On 2017-05-11 15:38, Mandy Chung wrote:
Magnus,
I’m surprised to see the man pages are moved to src/$MODULE/share/man
directory. These man pages are not maintained and not updated. It’s agreed
that the man pages are specification for the tools that we should write and
include in the source under src/$MODULE/share/man directory. However, it’s not
intended to move these unmaintained man page to the source.
My quick skimming through JEP 299 led me to think this was indeed the
intention, at least as placeholders until better documentation can be
provided.
Related to copying the man pages to the image, man pages should be packaged in
a module (JDK-8167558 [1]). JMOD file has a man page section specific for man
pages. jlink provides an option --no-man-pages to exclude man pages when
creating an image. make/CreateJmods.gmk was modified to include the man pages
in creating JMOD files [1].
The jmods will add man pages if there are any in support/modules_man but
I know of now part of the build process that ever puts man pages in
there. The man pages in the jdk/jre images are still copied into the
image using manual makefile copy in Images.gmk.
If my memory served well, I tested on OpenJDK build that jdk image has the man
pages. For Oracle build, it does not ship with man pages. Did I remember
correctly? Under what build configuration do we include the man pages in the
image? Maybe it’s not doing what it’s supposed to be??
We currently only copy man pages into the jdk/jre images when building
OpenJDK and not when building OracleJDK.
/Erik
Mandy
[1] https://bugs.openjdk.java.net/browse/JDK-8167558
On May 11, 2017, at 5:56 AM, Magnus Ihse Bursie <[email protected]>
wrote:
In preparation for JDK-8178317, the existing man page troff sources will be
moved to their corresponding modules, according to the layout determined by JEP
299. During the docs build, they will be copied to the man directory in the
docs image, as specified by JEP 299. No markdown conversion will be done for
now, though.
Note that this will only apply to OpenJDK, not the Oracle JDK, which do not ship the man pages from
the OpenJDK repository. (This has not been the case since at least JDK 8.) Also note that the man
pages themselves have not been updated. I did update "JDK 8" to "JDK 9", but I
have made no other changes. Nevertheless, I believe having man pages (even if outdated) is better
for the community than not having man pages.
The jhat and jsadebug tools have been removed in JDK 9, so I removed these man
pages as well.
Prior to this reorganisation, the man pages were duplicated in three
directories, one for each of solaris, linux and bsd. I have verified that for
the remaining man pages, there were no substantial difference between these
versions.
Bug: https://bugs.openjdk.java.net/browse/JDK-8180178
WebRev:
http://cr.openjdk.java.net/~ihse/JDK-8180178-restructure-man-pages/webrev.01
/Magnus
