jgm
Extract Templates section of manual to its own document
This is by way of a proof-of-concept or initial attempt at the work discussed in https://github.com/jgm/pandoc/discussions/10351. This PR proposes initial handling of the cross-reference links to the erstwhile Templates section in MANUAL.txt by just making them links to templates.md that are cleaned up by lua filters for the manual page generation (here) and the website (in a related change over there, https://github.com/jgm/pandoc-website/pull/65).
None of this is quite perfect but it does function, with minimal churn in MANUAL.txt. The system could be stress-tested further by adding man page generation for more of the existing extra docs but I haven't done so so far. The main thing bothering me about what I have here is that documents will have to be paired with the right manual section in multiple places.
I'm still not sure about this one. Note that there are references in the manual to, e.g. [Variables] and [Variables for HTML slides] which would be broken by this change. (Their destinations would now be in a separate md file, templates.md.)
Also, the entire "Variables" subsection seems more relevant to the average user of pandoc than the details of template syntax. After all, this is the part that tells you how to specify the font, font size, margins, and so on for your target format. With the proposed change, this would go in templates.md and readers of the pandoc manual might not even know to look there.
Thanks for the notes and calling out the reference links I missed. I didn’t really do any developmental editing on the proposed templates.md, just extracted the whole section and then focused on the associated machinery. I’ll mess around a bit further.
Thinking about this a bit more: I don't think it makes sense to break out the whole Templates section. As noted above, the "Variables" part belongs with the main pandoc page, both because this gives crucial information about how to do things like set margins and font sizes, and because it describes variables that are set by or interpreted by the pandoc executable, not the syntax of templates.
The introductory part about what templates are and how you use them also belongs with the main manual.
The subsection Template syntax could go in a separate manual page. (In fact, it is just copied from the README of jgm/doctemplates.) But at this point we may have diminishing returns. That's only 380 lines, out of the 1200 or so lines in the whole Templates section.