RFR: 8344056: Use markdown format for man pages [v2]

[David Holmes]

On Thu, 14 Nov 2024 11:11:54 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

>> Currently, the man pages are stored as troff (a text format) in the open repo, and a content-wise identical copy is stored as markdown (another text format) in the closed repo.
>> 
>> Since markdown is preferred to troff in terms of editing, we make changes to the man pages in markdown and then convert it to troff.
>> 
>> This closed-markdown to open-troff processing needs to be done manually by an Oracle engineer. This is done regularly at the start and end of a new release cycle, adding to the burden of creating a new release. It is also done (if any of the reviewers knows about the process) whenever an Oracle engineer updates a man page. If a community contributor changes the behavior of a tool, an Oracle engineer needs to change the documentation for them, since they cannot do it themselves.
>
> Magnus Ihse Bursie has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Fix CheckManPageOptions test
>  - Remove classpath exception

> > Now `CheckManPageOptions` finds the `.md` file (good) and its checks fail (bad).
> 
> _sigh_
> 
> > A candidate for an ignore list as fixing it is out of scope of this PR?
> 
> Let me have a look at it first. It seems the test has the indention to handle markdown files, so maybe there is an easy fix.

I'm somewhat surprised that the full src tree is available to this test when it runs. I was expecting it to examine the .1 files in the JDK image.

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

PR Comment: https://git.openjdk.org/jdk/pull/22081#issuecomment-2477764902