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

[Magnus Ihse Bursie]

On 2018-11-26 19: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 
> 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.
I've been asked to clarify that this patch does not affect the actual 
contents of the man pages. They were outdated before, and they are still 
outdated.

The end result of this patch, for an open-only source build, will be the 
same as before: the (outdated) man pages will be included in the image 
by default, and if you do not want this, you need to use the 
--disable-manpages option to configure. (This is what Oracle does for 
it's OpenJDK builds.)

If, however, closed markdown sources is present, those will be included. 
As I said, the intention is to open up the Oracle closed markdown, but 
it looks increasingly unlikely that this is going to happen in the JDK 
12 timeframe.

/Magnus

>
> Bug: https://bugs.openjdk.java.net/browse/JDK-8178317
> WebRev: 
> http://cr.openjdk.java.net/~ihse/JDK-8178317-man-pages-according-to-JEP299/webrev.01
>
> /Magnus