Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extract Templates section of manual to its own document #10431

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

silby
Copy link
Contributor

@silby silby commented Dec 1, 2024

This is by way of a proof-of-concept or initial attempt at the work discussed in #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, jgm/pandoc-website#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.

and use it on templates.md

manfilter.lua learns how to turn a link to another document in docs/
into a manual page cross-reference. This is paralleled by a
pandoc-website filter change for handling such links.

a lightly customized template for turning arbitrary docs into manual
pages is provided, which exploits the standard `subtitle` metadata for
the NAME section of the manual

This first stab at this work does the brutal minimum amount of work
while still being somewhat extensible. The new Makefile rule that
applies the new man template hardcodes section 5. The mapping of
document titles to manpage names and sections used by the lua filter is
hardcoded at the top. Cleverer ideas could reduce repetition, at the
cost of having to read yaml frontmatter out of all the docs to support
cross-references, or relying on exotic GNU Make tricks, or similar.
Some unrelated changes picked up in pandoc.1 since that's usually a
release task.
@jgm
Copy link
Owner

jgm commented Dec 2, 2024

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.

@silby
Copy link
Contributor Author

silby commented Dec 2, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants