markdown-to-pdf workflow relies on a deprecated pandoc feature

[ahouseholder]

Encountered this while exploring options for #184

When you run doc/compile-pdf.sh it throws a warning:
[WARNING] Deprecated: markdown_github. Use gfm instead.

This script is using a feature that was deprecated in pandoc 2.0, which released in 2017.

However, per the comments inside doc/compile-pdf.sh:

--from should use gfm, but gfm+citations is not supported
so this method should perhaps be considered slightly unstable.
This citation syntax won't render on github
but the @ citation syntax shouldn't interfere with @ mentions
GFM only allows @ mentions in issues and pull requests
https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown
documentation for citation processing:
https://pandoc.org/MANUAL.html#citations

Here is the main tracker for the issue in the gfm project:
jgm/pandoc#8452
which in turn depends on
jgm/commonmark-hs#15

As of this writing (4/12/2023) the latter issue has been open for four years with no updates in the past two. There is a comment in jgm/pandoc#8452 from the developer saying that "No definite time frame. It has been a surprisingly hard feature to implement and design."

Given that a fix seems unlikely in the near term, we need to explore alternatives for how to generate a PDF from the markdown while preserving citations.

[j---]

For what it's worth, I spent a couple days looking for a better option than the deprecated option that I used. The pandoc +citations is fairly well supported, but the supported markdown dialects didn't display properly when viewed on github website in a browser preview of the file (which I thought was important for usability to make commenting accessible to folks who just had access to a web browser).

[ahouseholder]

No resolution at this point, just keeping up with recent changes: as of #231 (which resolved #184), this is now a problem in

• .github/workflows/pandoc_html_pdf.yaml line 55 and also line 88
• doc/Makefile (note it occurs twice in the linked block too)

The links are to specific lines in a specific commit, but the problem will persist as long as markdown_github is invoked.

[ahouseholder]

Given the change to the web site as the primary documentation target instead of PDF-building, I think this issue is now moot and can be closed as wontfix. I'm leaving it open for a bit longer to allow for counterarguments, but let's set a timer that it can be closed after 2023-10-13 if no such reasons are forthcoming.