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

[David Holmes]

Hi Harold,

On 12/06/2021 6:30 am, Harold Seigel wrote:
> 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! 

Thanks for the review.

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

I think that would just duplicate what is said later.

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

The wording is consistent with the help text which itself was set via a 
CSR request, so I'll jsut leave it as-is.

Thanks,
David

> -------------
> 
> Marked as reviewed by hseigel (Reviewer).
> 
> PR: https://git.openjdk.java.net/jdk17/pull/16
>