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
