[jdk17] RFR: 8266614: update manpage for -Xlog:async

[Harold Seigel]

On Fri, 11 Jun 2021 04:40:09 GMT, David Holmes <dholmes at openjdk.org> wrote:

> Please review this update to the java manpage to describe the new -Xlog:async flag
> 
> There are two places where the text is changed:
> 
> 1. At the start where the -Xlog synopsis is given it now shows that `-Xlog:directive` is an allowed form where directive can be one of: help, disable, async
> 2.  A new subsection "-Xlog Output Mode" that explains async mode
> 
> The commited file is the java.1 nroff version which is not very readable, so I've included a commit that also contains a html version with the changed text flagged by "START NEW TEXT" and "END NEW TEXT". You can view that in rendered html via this link:
> 
> https://htmlpreview.github.io/?https://github.com/openjdk/jdk17/blob/8dcf544dfd2e19a3a49cce98d2d9abd9d2756538/java.html
> 
> Note that because the nroff file has not been updated for a while it also contains changes unrelated to this PR, the source changes for which have already been reviewed and approved. So just ignore those bits and look at the html file.
> 
> Thanks,
> David

Thanks for doing this!
Harold

The changes look good!  Here's some optional suggestions.

Under the "Description" heading where it says "The following provides quick reference to the -Xlog command and syntax for options:", perhaps add something about -Xlog:async?

Possible rewording suggestions:

1. Change "The default value should be big enough to cater for most cases." to
          "The default value should be big enough to handle most cases."

2. Change "... trade memory overhead for log accuracy if they need to."
   to   "... trade memory overhead for log accuracy if needed."

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

Marked as reviewed by hseigel (Reviewer).

PR: https://git.openjdk.java.net/jdk17/pull/16