RFR: JDK-8180178 Restructure existing man pages according to JEP 299

[David Holmes]

Sorry but:

 > Nevertheless, I believe having man pages (even if outdated) is
 > better for the community than not having man pages.

is not something I can agree with at all. This seems quite a ridiculous 
situation. We have not updated and maintained these manpages, they have 
been slated for removal - indeed I thought they already had been 
removed, yet we're now proposing to include them in OpenJDK builds - 
why?? The only thing worse than no documentation is out-of-date, 
incorrect documentation - which is what these man pages are!

David
-----

On 12/05/2017 12:57 PM, Mandy Chung wrote:
>
>> On May 11, 2017, at 5:44 PM, Erik Joelsson <erik.joelsson at oracle.com> wrote:
>>
>>
>>
>> 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.
>
> Jon already clarified.  That’s the original intent but had to defer it to JDK 10 due to the time we have.
>
>>> 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.
>
> Hmm…  At that time we might have thought to wait for JEP 299 to do the man pages work.  I added the jmod and jlink mechanism and waited for the man pages be converted to the source form.
>
>>> 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.
>>
>
> We have to decide what to do with the man pages for OpenJDK build:
> 1) copy to jdk/jre image as is.
>   These man pages are out dated.  Copying by default seems not good.
> 2) a configure option to enable copying man pages.  Default no man page.
>
> other options?
>
> Mandy
>
>> /Erik
>>> Mandy
>>> [1] https://bugs.openjdk.java.net/browse/JDK-8167558
>>>
>>>> On May 11, 2017, at 5:56 AM, Magnus Ihse Bursie <magnus.ihse.bursie at oracle.com> 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
>>>>
>>
>