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

[Erik Joelsson]

Nice to see this finally happening!

ProcessMarkdown.gmk: Looks like indentation got messed up on lines 79 
and 98. Looks good otherwise.

/Erik

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 
> 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
> WebRev: 
> http://cr.openjdk.java.net/~ihse/JDK-8178317-man-pages-according-to-JEP299/webrev.01
>
> /Magnus