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

[Magnus Ihse Bursie]

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:

http://cr.openjdk.java.net/~ihse/JDK-8178317-man-pages-according-to-JEP299/webrev.02

/Magnus

>
> /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