RFR: JDK-8178317 Create man pages using pandoc from markdown sources
Magnus Ihse Bursie
magnus.ihse.bursie at oracle.com
Tue Nov 27 10:25:10 UTC 2018
On 2018-11-26 20:33, Erik Joelsson wrote:
> Nice to see this finally happening!
> ProcessMarkdown.gmk: Looks like indentation got messed up on lines 79
> and 98. Looks good otherwise.
Ooops. Updated webrev:
> On 2018-11-26 10:57, Magnus Ihse Bursie wrote:
>> This patch will finally implement the last part of JEP 299, moving
>> man pages into the prescribed location in the source tree.
>> This patch also prepares for supplying man pages in markdown format,
>> which will be converted to troff (standard man page format) during
>> the build. Currently, such markdown versions only exists in the
>> closed sources, but hopefully they will migrate into open before too
>> long. When they do, the current static troff files and the logic
>> related to them will be obsolete.
>> The new code for man page handling leverages the already existing
>> functionality in jmod for bundling man pages in jmod files. This has
>> been supported for a long time, but not until now used by the OpenJDK
>> build. I tied the current functionality to the launcher make phase.
>> There is (or should be...) a 1-to-1 relationship between launchers
>> and man pages, so this seemed like a good fit. I did not want to
>> create a separate make phase for just man pages, and no other phase
>> was suitable.
>> I've slightly redefined the value of --disable-manpages. Now it is
>> described as "Set to disable copy of static man pages", meaning that
>> the old static troff files will be ignored, if --disable-manpages is
>> given. The intent of that flag was never to prohibit distribution of
>> man pages per se, but to avoid distributing the outdated static troff
>> files. I decided not to rename it to avoid invalidating existing
>> scripts, and also because it will hopefully not be needed for much
>> There's a fair bit of code for helping pandoc generate proper man
>> pages. While pandoc is good (except when it's buggy :-/) it takes
>> it's job very literaly. So for ideal man page output, you would need
>> to create your source markdown accordingly. But if you want to
>> generate dual output (both troff and html) like we do, pandoc needs
>> help to make the resulting man page look as expected. This is done by
>> the pandoc filter. Unfortunately, pandoc requires a stand-alone
>> executable with no arguments as filter, so we also need to manage a
>> wrapper script for the filter. There's also a post-processing sed
>> expression, but that's mostly a workaround to compensate for bugs in
>> I have also added a section for generating html versions of the man
>> pages to the docs-jdk-specs target in Docs.gmk.
>> Finally: I've moved the man pages from the location in
>> src/bsd/doc/man. In general, there was no difference between the
>> files in bsd, linux and solaris. However, for a couple of tools, the
>> bsd version was (for some reason) slightly more updated than the
>> linux and solaris versions. But please note that all these files has
>> not been updated for multiple JDK releases. Hopefully they will soon
>> be surpassed by the new, up-to-date markdown versions.
>> Bug: https://bugs.openjdk.java.net/browse/JDK-8178317
More information about the build-dev