haskellfoundation / haskellfoundation/haskell-2010-revised-report

Compile the Library report to PDF using haddock

Open
#18 1 comment 0 reactions 0 assignees View on GitHub
feature: standard libraries output: pdf question
Dominant language
Typst
Stars
20
Forks
5
Avg merge
4d 18h
Merged PRs (30d)
6

Description

`haddock` supports output of `latex` files, but it seems that this code path is not very well maintained. The repository https://github.com/haskell/haskell-report contains the generated latex files in the https://github.com/haskell/haskell-report/tree/master/report/libs subdirectory, but it doesn't contain the original Haskell files from which they were generated.

As an experiment, I tried to recreate them using the library contained in the `stdlib` directory. I used the following steps:

- `cabal haddock --haddock-option=--latex`
- This generates both `*.html` and `*.tex` files in the `dist-newstyle/...` directory.
- The `haddock.sty` file was not generated for some reason. I copied it manually from https://github.com/haskell/haskell-report/blob/master/report/haddock.sty into the directory.
- The generated tex files contained two instances of `\url{..}` which I temporarily had to comment out.
- I used `xelatex` instead of `pdflatex` to compile the base file: ` xelatex haskell2010-base-0.1.0.0-inplace.tex`. The sources contain some Unicode characters not recognized by `pdflatex`

This results in the following document, which is quite close to what the Haskell 2010 report contains.

[haskell2010-base-0.1.0.0-inplace.pdf](https://github.com/user-attachments/files/30707781/haskell2010-base-0.1.0.0-inplace.pdf)

The question is: Should we clean up this way of building the library report and publish the library report as a pdf file as well?

Contributor guide

Open the contributing guide

Research direction

Start with the stdlib directory and the generated files under dist-newstyle/...; reproduce the reported cabal haddock --haddock-option=--latex flow and inspect the report/libs output and haddock.sty handling. Check the generated .tex files and compile haskell2010-base-0.1.0.0-inplace.tex with xelatex. Done means the library report builds reproducibly as a PDF without manual file copying or commenting out URLs, with a clear publication path.

Written by the indexing model from the issue text.

Assessment

Tech stack
latex
Domain
build-system, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.