Manpage generation improvements #248
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The current regexp is quite lax, which results into a generic defined(3) manpage being installed. Limit the scope to MMDB_* symbols.
This is to allow needless deltas between builds with different Pandoc versions, to aid with reproducible builds efforts.
lowdown is a simple Markdown translator to multiple formats, including
man. lowdown is portable, and has no external dependencies, unlike
Pandoc which, due to its dependencies on the Haskell stack, can be a
headache for porters.
To make this more DRY, it converts the metadata preamble from Pandoc's
custom format ("% title(section") to Multimarkdown's, which is supported
by both Pandoc and lowdown.
Finally, this adds support for multiple translators in the
make-man-pages.pl script, to provide extensibility in case others (like
e.g. ronn-ng) are considered suitable in the future.
Fixes: maxmind#225
From Pandoc's documentation on the "smart" extension: Interpret straight quotes as curly quotes, --- as em-dashes, -- as en-dashes, and ... as ellipses. Nonbreaking spaces are inserted after certain abbreviations, such as “Mr.” This has the effect that all command-line options, like "--file", are translated as "\[en]file". That is, an en-dash, looking like a larger hyphen and potentially confusing users. Rather than escape these in the Markdown source, pass options to both pandoc and lowdown to disable smart(y) features. Note that this has the side-effect of disabling some curly quotes as well, but these are missing from the GitHub HTML output as well.
Currently, the generated manpages in tarballs are different than the
ones that CI generates, as Pandoc's default markdown flavors are
inconsistent across versions. Previous commit in this series attempted
to bridge the difference, but failed to work in older versions of
Pandoc.
In Pandoc < v2 (like e.g. Ubuntu 18.04's v1.19, used in CI):
* extension "smart" does not exist, there is a CLI option -S instead
* "markdown" does not enable any "smart" features by default
* "markdown_strict" and "markdown_mmd" do not include extension
backtick_code_blocks (which we use)
* GitHub-flavored Markdown is "markdown_github"
Pandoc v2+ (like e.g. v2.9 used by current upstream tarballs):
* Added the smart extension (-smart/+smart), deprecating -S
* The default Pandoc flavor ("markdown") enables "smart" by default
* "markdown_github" is deprecated, "gfm" is used instead
Therefore, to achieve the desired result of a) not including "smart" b)
enabling backtick code blocks, our only option is to specifically use a
Markdown flavor that does not include smart in either version
("markdown_strict" or "markdown_mmd"), plus specifically enable the
"backtick_code_blocks" extension. Since we want to enable
"mmd_title_block" anyway (for lowdown compatibility), use
"markdown_mmd+backtick_code_blocks".
This has been confirmed to generate the same output as before these
changes on both Ubuntu 18.04 (pandoc 1.19) and Debian sid (pandoc 2.9).
|
Nice improvements! Thanks! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Below you'll find a few improvements to
dev-bin/make-man-pages.plthat primarily help with generating better manpages, easier. I realize this is a script that is intended to be used mostly by you rather than downstreams, but in Debian we've decided to regenerate manpages as part of our efforts to distribute the preferred source of modifications and ensuring a FL/OSS stack can regenerate all "compiled" files.I expect some of these improvements -the defined(3) manpage and the smarty output- to affect you and produce better manpages in the official tarballs. The rest are mostly intended to be used by others (like Debian), but are generic enough that I'd prefer to not carry them as external patches.
Happy to answer any questions or make any desired improvements -- let me know!