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