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

[Nizar Benalla]

On Tue, 19 Nov 2024 16:26:45 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

> After [JDK-8344056](https://bugs.openjdk.org/browse/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](https://meta.stackoverflow.com/questions/288707/how-do-you-show-words-surrounded-by-angle-brackets) 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:
> 
> <img width="750" alt="Screenshot 2024-11-19 at 17 13 58" src="https://github.com/user-attachments/assets/a94053a1-49f1-43c6-8116-fbc711c51920">
> 
> <img width="722" alt="Screenshot 2024-11-19 at 17 13 46" src="https://github.com/user-attachments/assets/2d6105d1-b55d-473f-8ba7-48c37d147659">
> 
> <img width="319" alt="Screenshot 2024-11-19 at 17 14 18" src="https://github.com/user-attachments/assets/c4ccc5e7-1f2f-4ce1-a1fc-e04368449209">
> 
> After:
> 
> <img width="850" alt="Screenshot 2024-11-19 at 17 25 22" src="https://github.com/user-attachments/assets/a4b3f6ac-ffc4-4b73-9ffa-562195081042">
> <img width="781" alt="Screenshot 2024-11-19 at 17 25 48" src="https://github.com/user-attachments/assets/76edc5cb-1be2-4c5b-bdc7-32c3ac6c8412">
> <img width="496" alt="Screenshot 2024-11-19 at 18 33 29" src="https://github.com/user-attachments/assets/647a68cc-5804-4e61-b4e2-de788e790a0b">
> 
> 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
> -<files>] [--output <file>] [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
> ...

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

FWIW typing `Hello <David>.` in a github comment render as `Hello.`

<img width="291" alt="Screenshot 2024-11-26 at 16 57 21" src="https://github.com/user-attachments/assets/e89da416-8e8c-4260-a346-02e64a3b5e23">
<img width="366" alt="Screenshot 2024-11-26 at 16 57 42" src="https://github.com/user-attachments/assets/b844000d-5481-41dd-92d5-d60e439e9b3d">

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

PR Comment: https://git.openjdk.org/jdk/pull/22247#issuecomment-2501242677