8278274: Update nroff pages in JDK 19 before RC

[dholmes-ora]

Please review these changes to the nroff manpage files so that they match their markdown sources that Oracle maintains.

All pages at a minimum have 19-ea replaced with 19, and copyright set to 2022 if needed. Additionally:

The Java manpage was missing updates from:

• JDK-8282018: Add captions to tables on java man page.

The Java manpage has slight formatting differences from:

• JDK-8262004: Classpath separator: Man page says semicolon; should be colon on Linux
• JDK-8236569: -Xss not multiple of 4K does not work for the main thread on macOS

The Java manpage has a typo fixed in mainline by JDK-8279047 (for JDK 20)

The keytool manpage was missing updates from:

• JDK-8282014: Add captions to tables on keytool man page.
• JDK-8267319: Use larger default key sizes and algorithms based on CNSA

The jar manpage was missing updates from:

• JDK-8278764: jar and jmod man pages need the new --date documenting from CSR JDK-8277755

The jarsigner manpage was missing updates from:

• JDK-8282015: Add captions to tables on jarsigner man page.
• JDK-8267319: Use larger default key sizes and algorithms based on CNSA

The javadoc manpage was missing updates from:

• JDK-8279034: Update man page for javadoc --date option

The jmod manpage was missing updates from:

• JDK-8278764: jar and jmod man pages need the new --date documenting from CSR JDK-8277755

The jpackage manpage was missing updates from:

• JDK-8285146: Document jpackage resource dir feature
• JDK-8284695: Update jpackage man pages for JDK 19
• JDK-8284209: Replace remaining usages of 'a the' in source code

The jshell manpage was missing updates from:

• JDK-8282016: Add captions to tables on jshell man page.

---

Progress

• Change must be properly reviewed (1 review required, with at least 1 Reviewer)
• Change must not contain extraneous whitespace
• Commit message must refer to an issue

Issue

• JDK-8278274: Update nroff pages in JDK 19 before RC ⚠️ Issue is not open.

Reviewers

• Jonathan Gibbons (@jonathan-gibbons - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk19 pull/145/head:pull/145
$ git checkout pull/145

Update a local copy of the PR:
$ git checkout pull/145
$ git pull https://git.openjdk.org/jdk19 pull/145/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 145

View PR using the GUI difftool:
$ git pr show -t 145

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk19/pull/145.diff

[bridgekeeper]

👋 Welcome back dholmes! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

@dholmes-ora The following labels will be automatically applied to this pull request:

• compiler
• core-libs
• hotspot-jfr
• javadoc
• kulla
• net
• security
• serviceability

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.

[dholmes-ora]

/label remove kulla

[openjdk]

@dholmes-ora
The kulla label was successfully removed.

[dholmes-ora]

/label remove hotspot-jfr
/label add hotspot

[openjdk]

@dholmes-ora
The hotspot-jfr label was successfully removed.

[openjdk]

@dholmes-ora
The hotspot label was successfully added.

[mlbridge]

Webrevs

• 00: Full (9b77adc7)

[jonathan-gibbons]

Not a problem with this PR as such, but we still have a ? character in the output.

[dholmes-ora]

Yeah I spotted that too, but it would need to be fixed in source and nroff. Must be some kind of "smart quote" from an editor. Do you think this needs to be fixed or just handle it in mainline?

[dholmes-ora]

Filed JDK-8290626. It can easily be fixed before RDP2.

[Pfiver]

Hello @jonathan-gibbons

Excuse my hijacking / piggy-backing on this conversation!

When you say

Not a problem with this PR as such, but we still have a ? character in the output.

This strongly suggests that there must be an input to those man pages somewhere. :-) Would you mind to point me to it? Are they even included in the git repo?

Also, I was wondering why these man pages (i.e. the outputs) are obviously not included any more in the OpenJDK builds, e.g. https://jdk.java.net/19/ ? I am not sure when they were removed or if they were ever included in _open_jdk builds at all, but I see them in the Oracle JDK 1.8 Build.

I find them really nice to read! Are there other output formats, e.g. HTML, that might be are deployed somewhere on the web?

[Pfiver]

It did not take much effort to answer the last of the above question myself.

Are there other output formats, e.g. HTML, that might be are deployed somewhere on the web?

Obviously "yes". HTML renderings can be found by following the, e.g. "Java Development Kit Version 18 Tool Specifications" Link on the "Specifications Overview" page at, e.g. "https://docs.oracle.com/en/java/javase/18/docs/specs/".

Still hunting for the sources.

[jonathan-gibbons]

The version changes in each file look good (19-ea to 19).
The changes for javadoc look good.

I looked over the other changes for other files, and while they look good, I cannot speak for their technical accuracy. That being said, this is an automated process deriving info from upstream, so is likely OK.

[openjdk]

@dholmes-ora This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8278274: Update nroff pages in JDK 19 before RC

Reviewed-by: jjg

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 2 new commits pushed to the master branch:

• 2677dd6: 8289954: C2: Assert failed in PhaseCFG::verify() after JDK-8183390
• 4f3f74c: 8289127: Apache Lucene triggers: DEBUG MESSAGE: duplicated predicate failed which is impossible

Please see this link for an up-to-date comparison between the source branch of this pull request and the master branch.
As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

[dholmes-ora]

Thanks for the review @jonathan-gibbons ! I'll wait a day in case there are any further comments.

[dholmes-ora]

/integrate

[openjdk]

Going to push as commit 618f3a8.
Since your change was applied there have been 15 commits pushed to the master branch:

• f1001a0: 8287916: Address the inconsistency between the constant array and pool size
• 5d1c448: 8285407: Improve Xalan supports
• d0a2f13: 8282676: Improve subject handling
• 8333950: 8284370: Improve zlib usage
• 879ea78: 8283190: Improve MIDI processing
• 78c514d: 8281866: Enhance MethodHandle invocations
• ac93ab0: 8281859: Improve class compilation
• 67dd3f7: 8272249: Better properties of loaded Properties
• 243c76f: 8277608: Address IP Addressing
• ddb106b: 8272243: Improve DER parsing
• ... and 5 more: https://git.openjdk.org/jdk19/compare/15d3329edd552dcda29d6de2a6f20a5db075b60b...master

Your commit was automatically rebased without conflicts.

[openjdk]

@dholmes-ora Pushed as commit 618f3a8.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

[mlbridge]

Mailing list message from David Holmes on javadoc-dev:

Hi Patrick,

On 6/08/2022 7:05 pm, Patrick Pfeifer wrote:

On Mon, 18 Jul 2022 15:22:01 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

Please review these changes to the nroff manpage files so that they match their markdown sources that Oracle maintains.

Not a problem with this PR as such, but we still have a `?` character in the output.

Hello @jonathan-gibbons

Excuse my hijacking / piggy-backing on this conversation!

When you say

Not a problem with this PR as such, but we still have a `?` character in the output.

This strongly suggests that there must be an input to those man pages somewhere. :-) Would you mind to point me to it? Are they even included in the git repo?

The sources to the manpages are not currently open sourced and so are
held in Oracle's internal repository. Making them open-sourced has been
a goal for some time now but has to overcome legal obstacles, but we are
hopeful it will be "soon".

Also, I was wondering why these man pages (i.e. the outputs) are obviously not included any more in the OpenJDK builds, e.g. https://jdk.java.net/19/ ? I am not sure when they were removed or if they were ever included in _open_jdk builds at all, but I see them in the Oracle JDK 1.8 Build.

I find them really nice to read! Are there other output formats, e.g. HTML, that might be are deployed somewhere on the web?

As you found, Oracle does provide these in html format.

Cheers,
David