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

[Kevin Walls]

On Thu, 8 Aug 2024 17:22:40 GMT, Chris Plummer <cjplummer 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.
>
> src/jdk.jcmd/share/man/jcmd.1 line 258:
> 
>> 256: \f[I]filename\f[R]: (Optional) The name of the map file.
>> 257: If %p is specified in the filename, it is expanded to the JVM\[aq]s PID.
>> 258: (FILE, \[dq]/tmp/perf-%p.map\[dq])
> 
> I'm not sure about this change to FILE from STRING. Are there previous uses of FILE? We still seem to use STRING for JFR.dump, JFR.start, and JFR.stop.

OK yes - my thinking is:

They are strings of course, but they are also names of an output FILE, and those are distinct because they do %p substitution.

They need to have a "type" of FILE internally in the tool, so they get %p substitution.

The FILE instead of STRING doesn't need to be in the man page, but it would make sense that the man page is the same as the live help output as much as possible.

After the intro, the body of the man page mostly duplicates the online help for the commands.
So much so that you'd think we can automate that, which would make a great future step.
Then we would get FILE for the type of these arguments, not STRING.  So I used FILE here as it avoids a future issue.

I think we should move other output file names e.g. in the JFR commands to FILE over time, after verifying they do the %p substitution.  There could be %t timestamp as well, I think an enhancement request for that exists.

Then the docs could summarise everything about the FILE parameters and not have to duplicate it every time.

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

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