8336041: Doccheck: the jfr command doesn't show the correct command-line options

[nizarbenalla]

After JDK-8344056, we can now easily fix these typos that caused errors when rendering the HTML.

While I didn't find anything in the markdown spec mentioning escaping angle brackets, this stackoverflow answer says that we should use HTML entities for angle brackets. Otherwise the content inside <> is not shown. Doing so seems to fix the bug in the generated HTML.

The output of the man pages is also broken (you can verify on your local machines as this bug exists exists in older JDKs)

   jfr metadata subcommand
       Use jfr metadata to display information about events, such as event names, categories and field layout within a flight recording file.

       The syntax is:

       jfr metadata [--categories ] [--events ] []

Before:

After:

Here is the diff in the HTML after the change

--- build/macosx-aarch64/images/docs/specs/man/jfr.html 2024-11-19 17:08:08
+++ build/macosx-aarch64/images/test/docs/specs/man/jfr.html    2024-11-19 17:04:30
@@ -225,8 +225,7 @@
 <p>Use <code>jfr configure</code> to configure a .jfc settings file.</p>
 <p>The syntax is:</p>
 <p><code>jfr configure</code> [--interactive] [--verbose] [--input
-&lt;files&gt;] [--output &lt;file&gt;] [option=value]*
-[event-setting=value]*</p>
+<files>] [--output <file>] [option=value]* [event-setting=value]*</p>
 <dl>
 <dt><a id="configure-option-interactive"><code>--interactive</code></a></dt>
 <dd>
@@ -272,8 +271,8 @@
 such as event names, categories and field layout within a flight
 recording file.</p>
 <p>The syntax is:</p>
-<p><code>jfr metadata</code> [--categories &lt;filter&gt;] [--events
-&lt;filter&gt;] [&lt;file&gt;]</p>
+<p><code>jfr metadata</code> [--categories <filter>] [--events <filter>]
+[<file>]</p>
 <dl>
 <dt><a id="metadata-option-categories"><code>--categories</code>
 &lt;<em>filter</em>&gt;</a></dt>
@@ -292,8 +291,8 @@
 Location of the recording file (.jfr)
 </dd>
 </dl>
-<p>If the &lt;file&gt; parameter is omitted, metadata from the JDK where
-the 'jfr' tool is located will be used.</p>
+<p>If the <file> parameter is omitted, metadata from the JDK where the
+'jfr' tool is located will be used.</p>
 <h4 id="jfr-summary-subcommand"><code>jfr summary</code> subcommand</h4>
 <p>Use <code>jfr summary</code> to print statistics for a recording. For
 example, a summary can illustrate the number of recorded events and how

Here is the diff between the two troff files

213,214c213,214
< \f[V]jfr configure\f[R] [--interactive] [--verbose] [--input ] [--output
< ] [option=value]* [event-setting=value]*
---
> \f[V]jfr configure\f[R] [--interactive] [--verbose] [--input <files>]
> [--output <file>] [option=value]* [event-setting=value]*
255c255,256
< \f[V]jfr metadata\f[R] [--categories ] [--events ] []
---
> \f[V]jfr metadata\f[R] [--categories <filter>] [--events <filter>]
> [<file>]
270c271
< If the parameter is omitted, metadata from the JDK where the
---
> If the <file> parameter is omitted, metadata from the JDK where the

---

Progress

• Change must be properly reviewed (1 review required, with at least 1 Reviewer)
• Change must not contain extraneous whitespace
• Commit message must refer to an issue

Issue

• JDK-8336041: Doccheck: the jfr command doesn't show the correct command-line options (Bug - P3)

Reviewers

• David Holmes (@dholmes-ora - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/22247/head:pull/22247
$ git checkout pull/22247

Update a local copy of the PR:
$ git checkout pull/22247
$ git pull https://git.openjdk.org/jdk.git pull/22247/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 22247

View PR using the GUI difftool:
$ git pr show -t 22247

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/22247.diff

Using Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back nbenalla! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

@nizarbenalla This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8336041: Doccheck: the jfr command doesn't show the correct command-line options

Reviewed-by: dholmes

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 221 new commits pushed to the master branch:

• 959fa4a: 8344299: SM cleanup in javax.naming modules
• 43000a3: 8345075: java.lang.module.ModuleDescriptor constructor could be made private
• fd742af: 8344394: Remove SecurityManager and related calls from java.management.rmi
• 3b21a29: 8345175: Further cleanup in java.logging and jdk.internal.logger after JEP 486 integration
• 7dc00d3: 8345154: IGV: Show Parse and Assertion Predicate type as extra label
• 1e086b1: 8340103: Add internal set_flag function to VMATree
• db535c8: 8313367: SunMSCAPI cannot read Local Computer certs w/o Windows elevation
• edfe285: 8344306: RISC-V: Add zicond
• d33ad07: 8334493: Remove SecurityManager Permissions infrastructure from DiagnosticCommands
• 56f1e4e: 8344093: Implement JEP 501: Deprecate the 32-bit x86 Port for Removal
• ... and 211 more: https://git.openjdk.org/jdk/compare/fea5f2b1458cdd53f437e59caaffaa6e22fb59a7...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

[openjdk]

@nizarbenalla The following label will be automatically applied to this pull request:

• hotspot-jfr

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

[mlbridge]

Webrevs

• 00: Full (6221f2e7)

[dholmes-ora]

I would like to understand why it is necessary to do this. I cannot find any documentation to say that < must be escaped or replaced by HTML symbolic reference < in markdown sources.

[nizarbenalla]

It seems that the left angle bracket character is used to denote the start of HTML tags, if you want to use the literal < character, you need to escape it as an entity and use <

https://daringfireball.net/projects/markdown/syntax#autoescape

It seems that everything between < and > disappears because it looks like the beginning of an illegal HTML tag.

FWIW typing Hello <David>. in a github comment render as Hello ., so this happens in github as well.

[dholmes-ora]

Thanks for that info @nizarbenalla . It does make me wonder however whether perhaps we should be using code blocks for these syntax fragments so that they do get auto-escaped?

But that can be a future enhancement.

Thanks

[nizarbenalla]

Using code blocks or other tools such as a markdown viewer when updating these files could help avoid such bugs.
This specific bug was detected automatically by a test (experimental, not yet in the JDK) because the generated HTML was broken, so good tests can help prevent these problems.

I'll issue the integrate command in a few hours.

[nizarbenalla]

/integrate

[openjdk]

Going to push as commit 029ace0.
Since your change was applied there have been 234 commits pushed to the master branch:

• 2beb2b6: 8345234: Build system erroneously treats 32-bit x86 Zero as deprecated
• ed03f0d: 8345145: Display javap LineNumberTable and LocalVariableTable iff disassembled code output with -c or -v
• e9136b5: 8345223: Remove stray doPrivileged in java.base java.net and sun.net classes after JEP 486 integration
• a80ccf2: 8345039: IGV: save user-defined node colors to XML
• 28b0f3e: 8343705: IGV: Interactive Node Moving in Hierarchical Layout
• 4da7c35: 8314512: IGV: clean up hierarchical layout code
• 6bea1b6: 8344727: [JVMCI] Export the CompileBroker compilation activity mode for Truffle compiler control
• 8858de3: 8338571: [TestBug] DefaultCloseOperation.java test not working as expected wrt instruction after JDK-8325851 fix
• ece0401: 8345052: Harden StampedLock
• 095e769: 8345237: 32-bit Zero builds fail with assert(has_klass_gap()) failed: precondition
• ... and 224 more: https://git.openjdk.org/jdk/compare/fea5f2b1458cdd53f437e59caaffaa6e22fb59a7...master

Your commit was automatically rebased without conflicts.

[openjdk]

@nizarbenalla Pushed as commit 029ace0.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.