RFR: JDK-8178317 Create man pages using pandoc from markdown sources

Magnus Ihse Bursie magnus.ihse.bursie at oracle.com
Mon Nov 26 18:57:15 UTC 2018

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 longer.

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 pandoc.

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 mailing list