/Magnus
> 26 nov. 2018 kl. 23:14 skrev David Holmes <david.hol...@oracle.com>:
>
> Hi Magnus,
>
> I'm still rather confused by this JEP. IIUC this is mainly the infrastructure
> work needed to support manpages, but the actual manpages present in the
> sources are completely out of date and not in sync with the online
> documentation. Correct?
Yes, that is correct. The intention is to supersede the current static troff
pages with up-to-date man pages from markdown. This is still blocked
unfortunately, awaiting the transition to open. Hence the dual solution in the
interim.
/Magnus
>
> Thanks,
> David
>
>> On 27/11/2018 4:57 am, 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
