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

[Erik Joelsson]

Looks good.

/Erik

On 2018-11-27 02:25, Magnus Ihse Bursie wrote:
> 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
>