Quantcast

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

classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Magnus Ihse Bursie
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

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Erik Joelsson
Looks like this follows JEP 299 so OK by me. I do find it a bit strange
that we move the man pages out of the JDK/JRE images though.

/Erik


On 2017-05-11 05:56, Magnus Ihse Bursie 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
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Mandy Chung
In reply to this post by Magnus Ihse Bursie
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.

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].  

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??

Mandy
[1] https://bugs.openjdk.java.net/browse/JDK-8167558

> On May 11, 2017, at 5:56 AM, Magnus Ihse Bursie <[hidden email]> 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
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Erik Joelsson


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 <[hidden email]> 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
>>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Jonathan Gibbons


On 05/11/2017 05:44 PM, Erik Joelsson 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.

That was the original intent when we (optimistically) thought that we
would have time to do a pass over these docs to bring them up to date
for JDK 9.

-- jon
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Mandy Chung
In reply to this post by Erik Joelsson

> On May 11, 2017, at 5:44 PM, Erik Joelsson <[hidden email]> 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 <[hidden email]> 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
>>>
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 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 <[hidden email]> 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 <[hidden email]> 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
>>>>
>>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Magnus Ihse Bursie
In reply to this post by Mandy Chung
(Sorry if this is a bit TL, please don't DR though...)

Good we started clearing this up!

Let me start with a recap of the current situation:

The man pages exist in the source code in OpenJDK. During the build, they get copied to the JRE and JDK image, in the normal OpenJDK build. (Let me remind you that this is an OpenJDK list, so what we're discussing here is, by default, OpenJDK.)

In the Oracle JDK, some additional code has been added that actively filters out the man pages from the image.

The net effect is that the OpenJDK build includes these man pages, while the Oracle JDK does not.

At some point in time, during JDK 8 I think, Oracle started doing this filtering. As a consequence, we suggested deleting the man pages. This was, as I remember it, met by opposition from other parts of the community. It ended up with the man pages remaining, and a declaration from Oracle that the man pages will not be updated by Oracle, and that the rest of the community needed to step up to keep this up to date.

As far as I know, no contributions have been made to the man pages during this period.

This leaves us at today. That means that if we do nothing, we (meaning the OpenJDK project) will ship the same man pages as we did in JDK 8. (Note that the discussion what *Oracle* ships is different, and need to be conducted in a different forum.)

Since the rest of the community previously preferred to have any man pages, even if they were out of date, rather than to have none, I presume this still is the case. It would be good to have some input on this assumption, though, from e.g. Red Hat.

So, the first decision we need to make is:
1) should we keep the man pages as they are?
2) should we remove them completely?
3) should we keep the man pages and update them?

Unfortunately, option 3 which should have been the winner, is out of the question due to time constraints.

The default route (doing nothing) is selecting option 1, and so does this patch. Anyone opting for option 2, need to file a bug to remove the man pages.

My vote is definitely for option 1. It's the rare documentation that's completely up to date, and in most cases some documentation is better than none. I know I'd be pissed if I couldn't type "man javac" in my OpenJDK installation on Ubuntu. I acknowledge that there have been some substantial changes in JDK to some of the central tools, but most of the tools are unchanged, and even for java and javac, the vast majority  of the options and descriptions still apply.

The second part of the question is, given that option 1 above is followed, where should the man pages reside in the source tree, and where should it end up in the output? If option 2 is chosen, the rest of this discussion can be skipped.

JEP 299 clearly states a place in the source tree for man pages. While it  says that man pages should be in markdown format, it also includes a caveat saying that actual conversation of the man pages to markdown is a non-goal of the JEP. From a build perspective, it makes sense to look at all files in the $module/man directories, and if the file is in markdown, convert it (I have this code in a sandbox, and I had planned to post that as a follow-up), or if it's in troff format, just copy it.

So this patch is the first step of the build requirements on man pages as stated in JEP 299.

Given that we should keep these files, I see no reason not to move them to the location given by JEP 299. I really hope there is no opposition to this part, at least.

The final question is about where to store the man pages in the output. Previously, they have been part of the JDK and JRE images. Since JEP 299 states that man pages should be part of the docs image, I assume it meant that they should be removed from the JDK/JRE images, since it does not make sense to have it in two places.

The ability of jlink to include man pages was news to me. This is not mentioned in JEP 299, nor used in the current build. I assume this is a remnant from previous thinking, prior to JEP 299.

Frankly, I'm a bit surprised by the buzz this patch has generated. I think most of it stems from the confusion between OpenJDK and Oracle JDK, where it has not been apparent to all Oracle employees that what Oracle ships differs in this respect from what OpenJDK ships. And once again, this patch is not about what Oracle will ship, but OpenJDK.

/Magnus

> 12 maj 2017 kl. 04:57 skrev Mandy Chung <[hidden email]>:
>
>
>> On May 11, 2017, at 5:44 PM, Erik Joelsson <[hidden email]> 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 <[hidden email]> 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
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Erik Joelsson
Thanks Magnus, I agree completely with the below.

Option 1 seems most logical to me, especially since the work to conform
to JEP 299 has already been done.

/Erik


On 2017-05-11 23:51, Magnus Ihse Bursie wrote:

> (Sorry if this is a bit TL, please don't DR though...)
>
> Good we started clearing this up!
>
> Let me start with a recap of the current situation:
>
> The man pages exist in the source code in OpenJDK. During the build, they get copied to the JRE and JDK image, in the normal OpenJDK build. (Let me remind you that this is an OpenJDK list, so what we're discussing here is, by default, OpenJDK.)
>
> In the Oracle JDK, some additional code has been added that actively filters out the man pages from the image.
>
> The net effect is that the OpenJDK build includes these man pages, while the Oracle JDK does not.
>
> At some point in time, during JDK 8 I think, Oracle started doing this filtering. As a consequence, we suggested deleting the man pages. This was, as I remember it, met by opposition from other parts of the community. It ended up with the man pages remaining, and a declaration from Oracle that the man pages will not be updated by Oracle, and that the rest of the community needed to step up to keep this up to date.
>
> As far as I know, no contributions have been made to the man pages during this period.
>
> This leaves us at today. That means that if we do nothing, we (meaning the OpenJDK project) will ship the same man pages as we did in JDK 8. (Note that the discussion what *Oracle* ships is different, and need to be conducted in a different forum.)
>
> Since the rest of the community previously preferred to have any man pages, even if they were out of date, rather than to have none, I presume this still is the case. It would be good to have some input on this assumption, though, from e.g. Red Hat.
>
> So, the first decision we need to make is:
> 1) should we keep the man pages as they are?
> 2) should we remove them completely?
> 3) should we keep the man pages and update them?
>
> Unfortunately, option 3 which should have been the winner, is out of the question due to time constraints.
>
> The default route (doing nothing) is selecting option 1, and so does this patch. Anyone opting for option 2, need to file a bug to remove the man pages.
>
> My vote is definitely for option 1. It's the rare documentation that's completely up to date, and in most cases some documentation is better than none. I know I'd be pissed if I couldn't type "man javac" in my OpenJDK installation on Ubuntu. I acknowledge that there have been some substantial changes in JDK to some of the central tools, but most of the tools are unchanged, and even for java and javac, the vast majority  of the options and descriptions still apply.
>
> The second part of the question is, given that option 1 above is followed, where should the man pages reside in the source tree, and where should it end up in the output? If option 2 is chosen, the rest of this discussion can be skipped.
>
> JEP 299 clearly states a place in the source tree for man pages. While it  says that man pages should be in markdown format, it also includes a caveat saying that actual conversation of the man pages to markdown is a non-goal of the JEP. From a build perspective, it makes sense to look at all files in the $module/man directories, and if the file is in markdown, convert it (I have this code in a sandbox, and I had planned to post that as a follow-up), or if it's in troff format, just copy it.
>
> So this patch is the first step of the build requirements on man pages as stated in JEP 299.
>
> Given that we should keep these files, I see no reason not to move them to the location given by JEP 299. I really hope there is no opposition to this part, at least.
>
> The final question is about where to store the man pages in the output. Previously, they have been part of the JDK and JRE images. Since JEP 299 states that man pages should be part of the docs image, I assume it meant that they should be removed from the JDK/JRE images, since it does not make sense to have it in two places.
>
> The ability of jlink to include man pages was news to me. This is not mentioned in JEP 299, nor used in the current build. I assume this is a remnant from previous thinking, prior to JEP 299.
>
> Frankly, I'm a bit surprised by the buzz this patch has generated. I think most of it stems from the confusion between OpenJDK and Oracle JDK, where it has not been apparent to all Oracle employees that what Oracle ships differs in this respect from what OpenJDK ships. And once again, this patch is not about what Oracle will ship, but OpenJDK.
>
> /Magnus
>
>> 12 maj 2017 kl. 04:57 skrev Mandy Chung <[hidden email]>:
>>
>>
>>> On May 11, 2017, at 5:44 PM, Erik Joelsson <[hidden email]> 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 <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Mandy Chung
I suggest do nothing in JDK 9 (i.e. option 1) and do the man pages cleanup effort in JDK 10.  

This patch together with conversion to markdown can be pushed to jdk10 repo (probably best after the jdk9 build/docs changes are completed to avoid any merge conflict).  There will probably be some follow-up discussion on the man pages for other platforms like windows that may be in HTML format.

Mandy

> On May 12, 2017, at 9:01 AM, Erik Joelsson <[hidden email]> wrote:
>
> Thanks Magnus, I agree completely with the below.
>
> Option 1 seems most logical to me, especially since the work to conform to JEP 299 has already been done.
>
> /Erik
>
>
> On 2017-05-11 23:51, Magnus Ihse Bursie wrote:
>> (Sorry if this is a bit TL, please don't DR though...)
>>
>> Good we started clearing this up!
>>
>> Let me start with a recap of the current situation:
>>
>> The man pages exist in the source code in OpenJDK. During the build, they get copied to the JRE and JDK image, in the normal OpenJDK build. (Let me remind you that this is an OpenJDK list, so what we're discussing here is, by default, OpenJDK.)
>>
>> In the Oracle JDK, some additional code has been added that actively filters out the man pages from the image.
>>
>> The net effect is that the OpenJDK build includes these man pages, while the Oracle JDK does not.
>>
>> At some point in time, during JDK 8 I think, Oracle started doing this filtering. As a consequence, we suggested deleting the man pages. This was, as I remember it, met by opposition from other parts of the community. It ended up with the man pages remaining, and a declaration from Oracle that the man pages will not be updated by Oracle, and that the rest of the community needed to step up to keep this up to date.
>>
>> As far as I know, no contributions have been made to the man pages during this period.
>>
>> This leaves us at today. That means that if we do nothing, we (meaning the OpenJDK project) will ship the same man pages as we did in JDK 8. (Note that the discussion what *Oracle* ships is different, and need to be conducted in a different forum.)
>>
>> Since the rest of the community previously preferred to have any man pages, even if they were out of date, rather than to have none, I presume this still is the case. It would be good to have some input on this assumption, though, from e.g. Red Hat.
>>
>> So, the first decision we need to make is:
>> 1) should we keep the man pages as they are?
>> 2) should we remove them completely?
>> 3) should we keep the man pages and update them?
>>
>> Unfortunately, option 3 which should have been the winner, is out of the question due to time constraints.
>>
>> The default route (doing nothing) is selecting option 1, and so does this patch. Anyone opting for option 2, need to file a bug to remove the man pages.
>>
>> My vote is definitely for option 1. It's the rare documentation that's completely up to date, and in most cases some documentation is better than none. I know I'd be pissed if I couldn't type "man javac" in my OpenJDK installation on Ubuntu. I acknowledge that there have been some substantial changes in JDK to some of the central tools, but most of the tools are unchanged, and even for java and javac, the vast majority  of the options and descriptions still apply.
>>
>> The second part of the question is, given that option 1 above is followed, where should the man pages reside in the source tree, and where should it end up in the output? If option 2 is chosen, the rest of this discussion can be skipped.
>>
>> JEP 299 clearly states a place in the source tree for man pages. While it  says that man pages should be in markdown format, it also includes a caveat saying that actual conversation of the man pages to markdown is a non-goal of the JEP. From a build perspective, it makes sense to look at all files in the $module/man directories, and if the file is in markdown, convert it (I have this code in a sandbox, and I had planned to post that as a follow-up), or if it's in troff format, just copy it.
>>
>> So this patch is the first step of the build requirements on man pages as stated in JEP 299.
>>
>> Given that we should keep these files, I see no reason not to move them to the location given by JEP 299. I really hope there is no opposition to this part, at least.
>>
>> The final question is about where to store the man pages in the output. Previously, they have been part of the JDK and JRE images. Since JEP 299 states that man pages should be part of the docs image, I assume it meant that they should be removed from the JDK/JRE images, since it does not make sense to have it in two places.
>>
>> The ability of jlink to include man pages was news to me. This is not mentioned in JEP 299, nor used in the current build. I assume this is a remnant from previous thinking, prior to JEP 299.
>>
>> Frankly, I'm a bit surprised by the buzz this patch has generated. I think most of it stems from the confusion between OpenJDK and Oracle JDK, where it has not been apparent to all Oracle employees that what Oracle ships differs in this respect from what OpenJDK ships. And once again, this patch is not about what Oracle will ship, but OpenJDK.
>>
>> /Magnus
>>
>>> 12 maj 2017 kl. 04:57 skrev Mandy Chung <[hidden email]>:
>>>
>>>
>>>> On May 11, 2017, at 5:44 PM, Erik Joelsson <[hidden email]> 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 <[hidden email]> 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
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Magnus Ihse Bursie
In reply to this post by Erik Joelsson
I realize I was not very clear in my mail, despite my intentions. :-)

What I meant was, given option 1, there are some more choices to be made.

1a) do not do anything, ignore this patch, and ship things just as they are in JDK 8.

1b) apply this patch, move the files in the src tree and the output to the docs image.

1c) do a partial implementation of this patch, e.g. move the man pages in the src tree but do not change the output.

1d) do something differently, e.g start using the man functionality of jlink.

From these choices, I prefer 1b.

It was not clear to me which you (or Mandy) meant by your expressed support for "option 1".

/Magnus

> 12 maj 2017 kl. 18:01 skrev Erik Joelsson <[hidden email]>:
>
> Thanks Magnus, I agree completely with the below.
>
> Option 1 seems most logical to me, especially since the work to conform to JEP 299 has already been done.
>
> /Erik
>
>
>> On 2017-05-11 23:51, Magnus Ihse Bursie wrote:
>> (Sorry if this is a bit TL, please don't DR though...)
>>
>> Good we started clearing this up!
>>
>> Let me start with a recap of the current situation:
>>
>> The man pages exist in the source code in OpenJDK. During the build, they get copied to the JRE and JDK image, in the normal OpenJDK build. (Let me remind you that this is an OpenJDK list, so what we're discussing here is, by default, OpenJDK.)
>>
>> In the Oracle JDK, some additional code has been added that actively filters out the man pages from the image.
>>
>> The net effect is that the OpenJDK build includes these man pages, while the Oracle JDK does not.
>>
>> At some point in time, during JDK 8 I think, Oracle started doing this filtering. As a consequence, we suggested deleting the man pages. This was, as I remember it, met by opposition from other parts of the community. It ended up with the man pages remaining, and a declaration from Oracle that the man pages will not be updated by Oracle, and that the rest of the community needed to step up to keep this up to date.
>>
>> As far as I know, no contributions have been made to the man pages during this period.
>>
>> This leaves us at today. That means that if we do nothing, we (meaning the OpenJDK project) will ship the same man pages as we did in JDK 8. (Note that the discussion what *Oracle* ships is different, and need to be conducted in a different forum.)
>>
>> Since the rest of the community previously preferred to have any man pages, even if they were out of date, rather than to have none, I presume this still is the case. It would be good to have some input on this assumption, though, from e.g. Red Hat.
>>
>> So, the first decision we need to make is:
>> 1) should we keep the man pages as they are?
>> 2) should we remove them completely?
>> 3) should we keep the man pages and update them?
>>
>> Unfortunately, option 3 which should have been the winner, is out of the question due to time constraints.
>>
>> The default route (doing nothing) is selecting option 1, and so does this patch. Anyone opting for option 2, need to file a bug to remove the man pages.
>>
>> My vote is definitely for option 1. It's the rare documentation that's completely up to date, and in most cases some documentation is better than none. I know I'd be pissed if I couldn't type "man javac" in my OpenJDK installation on Ubuntu. I acknowledge that there have been some substantial changes in JDK to some of the central tools, but most of the tools are unchanged, and even for java and javac, the vast majority  of the options and descriptions still apply.
>>
>> The second part of the question is, given that option 1 above is followed, where should the man pages reside in the source tree, and where should it end up in the output? If option 2 is chosen, the rest of this discussion can be skipped.
>>
>> JEP 299 clearly states a place in the source tree for man pages. While it  says that man pages should be in markdown format, it also includes a caveat saying that actual conversation of the man pages to markdown is a non-goal of the JEP. From a build perspective, it makes sense to look at all files in the $module/man directories, and if the file is in markdown, convert it (I have this code in a sandbox, and I had planned to post that as a follow-up), or if it's in troff format, just copy it.
>>
>> So this patch is the first step of the build requirements on man pages as stated in JEP 299.
>>
>> Given that we should keep these files, I see no reason not to move them to the location given by JEP 299. I really hope there is no opposition to this part, at least.
>>
>> The final question is about where to store the man pages in the output. Previously, they have been part of the JDK and JRE images. Since JEP 299 states that man pages should be part of the docs image, I assume it meant that they should be removed from the JDK/JRE images, since it does not make sense to have it in two places.
>>
>> The ability of jlink to include man pages was news to me. This is not mentioned in JEP 299, nor used in the current build. I assume this is a remnant from previous thinking, prior to JEP 299.
>>
>> Frankly, I'm a bit surprised by the buzz this patch has generated. I think most of it stems from the confusion between OpenJDK and Oracle JDK, where it has not been apparent to all Oracle employees that what Oracle ships differs in this respect from what OpenJDK ships. And once again, this patch is not about what Oracle will ship, but OpenJDK.
>>
>> /Magnus
>>
>>> 12 maj 2017 kl. 04:57 skrev Mandy Chung <[hidden email]>:
>>>
>>>
>>>> On May 11, 2017, at 5:44 PM, Erik Joelsson <[hidden email]> 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 <[hidden email]> 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
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Mandy Chung
1a - do nothing in JDK 9 as I mentioned in my reply that answered your part 2 question for Option 1.

Do 1d in JDK 10 (along with modularizing the man pages)

Mandy

> On May 12, 2017, at 9:44 AM, Magnus Ihse Bursie <[hidden email]> wrote:
>
> I realize I was not very clear in my mail, despite my intentions. :-)
>
> What I meant was, given option 1, there are some more choices to be made.
>
> 1a) do not do anything, ignore this patch, and ship things just as they are in JDK 8.
>
> 1b) apply this patch, move the files in the src tree and the output to the docs image.
>
> 1c) do a partial implementation of this patch, e.g. move the man pages in the src tree but do not change the output.
>
> 1d) do something differently, e.g start using the man functionality of jlink.
>
> From these choices, I prefer 1b.
>
> It was not clear to me which you (or Mandy) meant by your expressed support for "option 1".
>
> /Magnus
>
>> 12 maj 2017 kl. 18:01 skrev Erik Joelsson <[hidden email]>:
>>
>> Thanks Magnus, I agree completely with the below.
>>
>> Option 1 seems most logical to me, especially since the work to conform to JEP 299 has already been done.
>>
>> /Erik
>>
>>
>>> On 2017-05-11 23:51, Magnus Ihse Bursie wrote:
>>> (Sorry if this is a bit TL, please don't DR though...)
>>>
>>> Good we started clearing this up!
>>>
>>> Let me start with a recap of the current situation:
>>>
>>> The man pages exist in the source code in OpenJDK. During the build, they get copied to the JRE and JDK image, in the normal OpenJDK build. (Let me remind you that this is an OpenJDK list, so what we're discussing here is, by default, OpenJDK.)
>>>
>>> In the Oracle JDK, some additional code has been added that actively filters out the man pages from the image.
>>>
>>> The net effect is that the OpenJDK build includes these man pages, while the Oracle JDK does not.
>>>
>>> At some point in time, during JDK 8 I think, Oracle started doing this filtering. As a consequence, we suggested deleting the man pages. This was, as I remember it, met by opposition from other parts of the community. It ended up with the man pages remaining, and a declaration from Oracle that the man pages will not be updated by Oracle, and that the rest of the community needed to step up to keep this up to date.
>>>
>>> As far as I know, no contributions have been made to the man pages during this period.
>>>
>>> This leaves us at today. That means that if we do nothing, we (meaning the OpenJDK project) will ship the same man pages as we did in JDK 8. (Note that the discussion what *Oracle* ships is different, and need to be conducted in a different forum.)
>>>
>>> Since the rest of the community previously preferred to have any man pages, even if they were out of date, rather than to have none, I presume this still is the case. It would be good to have some input on this assumption, though, from e.g. Red Hat.
>>>
>>> So, the first decision we need to make is:
>>> 1) should we keep the man pages as they are?
>>> 2) should we remove them completely?
>>> 3) should we keep the man pages and update them?
>>>
>>> Unfortunately, option 3 which should have been the winner, is out of the question due to time constraints.
>>>
>>> The default route (doing nothing) is selecting option 1, and so does this patch. Anyone opting for option 2, need to file a bug to remove the man pages.
>>>
>>> My vote is definitely for option 1. It's the rare documentation that's completely up to date, and in most cases some documentation is better than none. I know I'd be pissed if I couldn't type "man javac" in my OpenJDK installation on Ubuntu. I acknowledge that there have been some substantial changes in JDK to some of the central tools, but most of the tools are unchanged, and even for java and javac, the vast majority  of the options and descriptions still apply.
>>>
>>> The second part of the question is, given that option 1 above is followed, where should the man pages reside in the source tree, and where should it end up in the output? If option 2 is chosen, the rest of this discussion can be skipped.
>>>
>>> JEP 299 clearly states a place in the source tree for man pages. While it  says that man pages should be in markdown format, it also includes a caveat saying that actual conversation of the man pages to markdown is a non-goal of the JEP. From a build perspective, it makes sense to look at all files in the $module/man directories, and if the file is in markdown, convert it (I have this code in a sandbox, and I had planned to post that as a follow-up), or if it's in troff format, just copy it.
>>>
>>> So this patch is the first step of the build requirements on man pages as stated in JEP 299.
>>>
>>> Given that we should keep these files, I see no reason not to move them to the location given by JEP 299. I really hope there is no opposition to this part, at least.
>>>
>>> The final question is about where to store the man pages in the output. Previously, they have been part of the JDK and JRE images. Since JEP 299 states that man pages should be part of the docs image, I assume it meant that they should be removed from the JDK/JRE images, since it does not make sense to have it in two places.
>>>
>>> The ability of jlink to include man pages was news to me. This is not mentioned in JEP 299, nor used in the current build. I assume this is a remnant from previous thinking, prior to JEP 299.
>>>
>>> Frankly, I'm a bit surprised by the buzz this patch has generated. I think most of it stems from the confusion between OpenJDK and Oracle JDK, where it has not been apparent to all Oracle employees that what Oracle ships differs in this respect from what OpenJDK ships. And once again, this patch is not about what Oracle will ship, but OpenJDK.
>>>
>>> /Magnus
>>>
>>>> 12 maj 2017 kl. 04:57 skrev Mandy Chung <[hidden email]>:
>>>>
>>>>
>>>>> On May 11, 2017, at 5:44 PM, Erik Joelsson <[hidden email]> 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 <[hidden email]> 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
>>
>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

David Holmes
On 13/05/2017 3:23 AM, Mandy Chung wrote:
> 1a - do nothing in JDK 9 as I mentioned in my reply that answered your part 2 question for Option 1.

If we can't do (2) then (1a) would also be my preference from a set of
bad options. :(

But again this is a policy decision that someone higher up should be
making, having regard for both how this impacts the perception of
OpenJDK as a whole, and how any choice impacts resources need for 9 GA.

Thanks,
David

> Do 1d in JDK 10 (along with modularizing the man pages)
>
> Mandy
>
>> On May 12, 2017, at 9:44 AM, Magnus Ihse Bursie <[hidden email]> wrote:
>>
>> I realize I was not very clear in my mail, despite my intentions. :-)
>>
>> What I meant was, given option 1, there are some more choices to be made.
>>
>> 1a) do not do anything, ignore this patch, and ship things just as they are in JDK 8.
>>
>> 1b) apply this patch, move the files in the src tree and the output to the docs image.
>>
>> 1c) do a partial implementation of this patch, e.g. move the man pages in the src tree but do not change the output.
>>
>> 1d) do something differently, e.g start using the man functionality of jlink.
>>
>> From these choices, I prefer 1b.
>>
>> It was not clear to me which you (or Mandy) meant by your expressed support for "option 1".
>>
>> /Magnus
>>
>>> 12 maj 2017 kl. 18:01 skrev Erik Joelsson <[hidden email]>:
>>>
>>> Thanks Magnus, I agree completely with the below.
>>>
>>> Option 1 seems most logical to me, especially since the work to conform to JEP 299 has already been done.
>>>
>>> /Erik
>>>
>>>
>>>> On 2017-05-11 23:51, Magnus Ihse Bursie wrote:
>>>> (Sorry if this is a bit TL, please don't DR though...)
>>>>
>>>> Good we started clearing this up!
>>>>
>>>> Let me start with a recap of the current situation:
>>>>
>>>> The man pages exist in the source code in OpenJDK. During the build, they get copied to the JRE and JDK image, in the normal OpenJDK build. (Let me remind you that this is an OpenJDK list, so what we're discussing here is, by default, OpenJDK.)
>>>>
>>>> In the Oracle JDK, some additional code has been added that actively filters out the man pages from the image.
>>>>
>>>> The net effect is that the OpenJDK build includes these man pages, while the Oracle JDK does not.
>>>>
>>>> At some point in time, during JDK 8 I think, Oracle started doing this filtering. As a consequence, we suggested deleting the man pages. This was, as I remember it, met by opposition from other parts of the community. It ended up with the man pages remaining, and a declaration from Oracle that the man pages will not be updated by Oracle, and that the rest of the community needed to step up to keep this up to date.
>>>>
>>>> As far as I know, no contributions have been made to the man pages during this period.
>>>>
>>>> This leaves us at today. That means that if we do nothing, we (meaning the OpenJDK project) will ship the same man pages as we did in JDK 8. (Note that the discussion what *Oracle* ships is different, and need to be conducted in a different forum.)
>>>>
>>>> Since the rest of the community previously preferred to have any man pages, even if they were out of date, rather than to have none, I presume this still is the case. It would be good to have some input on this assumption, though, from e.g. Red Hat.
>>>>
>>>> So, the first decision we need to make is:
>>>> 1) should we keep the man pages as they are?
>>>> 2) should we remove them completely?
>>>> 3) should we keep the man pages and update them?
>>>>
>>>> Unfortunately, option 3 which should have been the winner, is out of the question due to time constraints.
>>>>
>>>> The default route (doing nothing) is selecting option 1, and so does this patch. Anyone opting for option 2, need to file a bug to remove the man pages.
>>>>
>>>> My vote is definitely for option 1. It's the rare documentation that's completely up to date, and in most cases some documentation is better than none. I know I'd be pissed if I couldn't type "man javac" in my OpenJDK installation on Ubuntu. I acknowledge that there have been some substantial changes in JDK to some of the central tools, but most of the tools are unchanged, and even for java and javac, the vast majority  of the options and descriptions still apply.
>>>>
>>>> The second part of the question is, given that option 1 above is followed, where should the man pages reside in the source tree, and where should it end up in the output? If option 2 is chosen, the rest of this discussion can be skipped.
>>>>
>>>> JEP 299 clearly states a place in the source tree for man pages. While it  says that man pages should be in markdown format, it also includes a caveat saying that actual conversation of the man pages to markdown is a non-goal of the JEP. From a build perspective, it makes sense to look at all files in the $module/man directories, and if the file is in markdown, convert it (I have this code in a sandbox, and I had planned to post that as a follow-up), or if it's in troff format, just copy it.
>>>>
>>>> So this patch is the first step of the build requirements on man pages as stated in JEP 299.
>>>>
>>>> Given that we should keep these files, I see no reason not to move them to the location given by JEP 299. I really hope there is no opposition to this part, at least.
>>>>
>>>> The final question is about where to store the man pages in the output. Previously, they have been part of the JDK and JRE images. Since JEP 299 states that man pages should be part of the docs image, I assume it meant that they should be removed from the JDK/JRE images, since it does not make sense to have it in two places.
>>>>
>>>> The ability of jlink to include man pages was news to me. This is not mentioned in JEP 299, nor used in the current build. I assume this is a remnant from previous thinking, prior to JEP 299.
>>>>
>>>> Frankly, I'm a bit surprised by the buzz this patch has generated. I think most of it stems from the confusion between OpenJDK and Oracle JDK, where it has not been apparent to all Oracle employees that what Oracle ships differs in this respect from what OpenJDK ships. And once again, this patch is not about what Oracle will ship, but OpenJDK.
>>>>
>>>> /Magnus
>>>>
>>>>> 12 maj 2017 kl. 04:57 skrev Mandy Chung <[hidden email]>:
>>>>>
>>>>>
>>>>>> On May 11, 2017, at 5:44 PM, Erik Joelsson <[hidden email]> 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 <[hidden email]> 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
>>>
>>
>
Loading...