Generate a single PDF of language specification

[k4rtik]

It will be nice if there was a way to output a single PDF or single-page HTML of the language specification for easy grepping. The navigation structure is nice, but harder to navigate with.

[k4rtik]

Using pandoc, I was able to get to the attached PDF using the following options (after some manual wrangling of markdown header levels):

PlatiniumM1Pro in language/Specifications/Language on  main [?]
❯ for f in *.md */*.md; do cat $f; echo; done | cat > spec.md
❯ pandoc spec.md --pdf-engine=xelatex -V mainfont="TeX Gyre Pagella" -V monofont="Fira Code" -V linkcolor:blue --toc --highlight-style tango -V geometry:margin=2.5cm -f gfm -o spec.pdf

PDF: spec.pdf MD: spec.md

I found the following helpful:

1. https://learnbyexample.github.io/customizing-pandoc/
2. https://pandoc.org/MANUAL.html

[k4rtik]

To-dos:

• [ ] Syntax highlighting for Q# code
• [ ] Add a title page or title on the front page
• [ ] Include grammar explicitly, instead of just links
• [ ] Automation of PDF generation, so it doesn't fall out of sync with this repo
• [ ] Highlight [!NOTE]s in a visually distinct manner, currently they are just shown as block quotes.
• [x] Ensure that long tables wrap properly: one (pg. 21) and two (pg. 36--37)
• [ ] switch to local links instead of linking to GitHub pages.

[k4rtik]

• Ensure that long tables wrap properly: one (pg. 21) and two (pg. 36--37)

This is solved if instead of -f gfm, we use the deprecated -f markdown_github (see https://github.com/jgm/pandoc/commit/eb8aee477db045a7449bc752975528263964b8ce), ie:

❯ pandoc spec.md --pdf-engine=xelatex -V mainfont="TeX Gyre Pagella" -V monofont="Fira Code" -V linkcolor:blue --toc --highlight-style tango -V geometry:margin=2.5cm -f markdown_github -o spec.pdf
[WARNING] Deprecated: markdown_github. Use gfm instead.

Updated spec.md and spec.pdf (44 pages).