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

[Kevin Walls]

On Wed, 31 Jul 2024 08:30:47 GMT, Kevin Walls <kevinw at openjdk.org> wrote:

> Man page update for jcmd.
> 
> Add updates for the filename options/arguments affected by:
> 8334492: DiagnosticCommands (jcmd) should accept %p in output filenames and substitute PID
> 
> Also:
> In the initial "command" summary, remove the text about "If the pid is 0.." as it is completely duplicated very shortly afterwards in the COMMANDS FOR JCMD section.
> 
> In Description:
> Each diagnostic command has its own set of options and arguments .
>  
> Added "options and" because arguments and options are different and this can still be confusing.  Mentioning them as being different may help.
> 
> Similarly, added a short section describing that jcmds "may take options and arguments" and further spelling out that options are name=value and arguments are not, as this can still be confusing.

Updating.
Since JDK-8338405, JFR.dump, JFR.start, JFR.stop also now use FILE.

JFR items already mention %t and %p, but we don't really want the man page and the live jcmd help giving diffrent information, so say "FILE" in the man page.

(We may come back here again for JDK-8204681 if we add a more general timetamp in output filename feature.)

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

PR Comment: https://git.openjdk.org/jdk/pull/20401#issuecomment-2416191111