RFR: 8337276: jcmd man page update for PID in output filenames [v2]

[Kevin Walls]

On Wed, 16 Oct 2024 22:15:05 GMT, Chris Plummer <cjplummer at openjdk.org> wrote:

>> Kevin Walls has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains three additional commits since the last revision:
>> 
>>  - Update JFR commands for FILE
>>  - Merge remote-tracking branch 'upstream/master' into 8337276_jcmd_pid_manpage
>>  - 8337276: jcmd man page update for PID in output filenames
>
> src/jdk.jcmd/share/man/jcmd.1 line 974:
> 
>> 972: \f[I]filename\f[R]: (Optional) Name of the shared archive to be dumped.
>> 973: If %p is specified in the filename, it is expanded to the JVM\[aq]s PID.
>> 974: (FILE, \[dq]java_pid%p_<subcmd>.jsa\[dq])
> 
> The paragraph below this goes into details on how the default path is generated even though it is implied by the above help. We don't do this extra explanation for other places where the filename has a default, so probably not needed here, but I suppose it doesn't hurt either.
> 
> Also, two paragraphs below is a discussions about absolute paths that also applies to all other uses of filename. If it is necessary here, then that implies it is necessary in the other locations too.

Yes - both of those paragraphs are _not_very_ useful.

"If `filename` is not specified, a default file name is chosen using the pid..." - this explains how the default filename works.

" If `filename` is not specified as an absolute path, the archive file is created in a directory relative to.." -- Well yes, we are saying that is if it's not absolute, it's relative... Hmm... This does not add much value either.

The good thing is these are not in the live help output, so deleting them does not make the help any more inconsistent.  I think these can both be removed.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/20401#discussion_r1805040920