[jdk19] RFR: 8278274: Update nroff pages in JDK 19 before RC

[Patrick Pfeifer]

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.
>> 
>> 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](https://bugs.openjdk.org/browse/JDK-8282018): Add captions to tables on java man page.
>> 
>> The Java manpage has slight formatting differences from:
>> - [JDK-8262004](https://bugs.openjdk.org/browse/JDK-8262004): Classpath separator: Man page says semicolon; should be colon on Linux
>> - [JDK-8236569](https://bugs.openjdk.org/browse/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](https://bugs.openjdk.org/browse/JDK-8279047) (for JDK 20)
>> 
>> 
>> The keytool manpage was missing updates from:
>> - [JDK-8282014](https://bugs.openjdk.org/browse/JDK-8282014): Add captions to tables on keytool man page.
>> - [JDK-8267319](https://bugs.openjdk.org/browse/JDK-8267319): Use larger default key sizes and algorithms based on CNSA
>> 
>> The jar manpage was missing updates from:
>> - [JDK-8278764](https://bugs.openjdk.org/browse/JDK-8278764): jar and jmod man pages need the new --date documenting from CSR [JDK-8277755](https://bugs.openjdk.org/browse/JDK-8277755)
>> 
>> The jarsigner manpage was missing updates from:
>> - [JDK-8282015](https://bugs.openjdk.org/browse/JDK-8282015): Add captions to tables on jarsigner man page.
>> - [JDK-8267319](https://bugs.openjdk.org/browse/JDK-8267319): Use larger default key sizes and algorithms based on CNSA
>> 
>> The javadoc manpage was missing updates from:
>> - [JDK-8279034](https://bugs.openjdk.org/browse/JDK-8279034): Update man page for javadoc `--date` option
>> 
>> The jmod manpage was missing updates from:
>> - [JDK-8278764](https://bugs.openjdk.org/browse/JDK-8278764): jar and jmod man pages need the new --date documenting from CSR [JDK-8277755](https://bugs.openjdk.org/browse/JDK-8277755)
>> 
>> The jpackage manpage was missing updates from:
>> - [JDK-8285146](https://bugs.openjdk.org/browse/JDK-8285146): Document jpackage resource dir feature
>> - [JDK-8284695](https://bugs.openjdk.org/browse/JDK-8284695): Update jpackage man pages for JDK 19
>> - [JDK-8284209](https://bugs.openjdk.org/browse/JDK-8284209): Replace remaining usages of 'a the' in source code
>> 
>> The jshell manpage was missing updates from:
>> - [JDK-8282016](https://bugs.openjdk.org/browse/JDK-8282016): Add captions to tables on jshell man page.
>
> src/java.base/share/man/keytool.1 line 456:
> 
>> 454: \f[CB]PrivateKeyEntry\f[R] for the signer that already exists in the
>> 455: keystore.
>> 456: This option is used to sign the certificate with the signer?s private
> 
> 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?

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?

-------------

PR: https://git.openjdk.org/jdk19/pull/145