RFR: 8344056: Use markdown format for man pages

[David Holmes]

On Wed, 13 Nov 2024 17:05:25 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.

Great to finally see this happen!

Just one glitch with the GPL headers.

Thanks

src/java.base/share/man/java.md line 9:

> 7: # published by the Free Software Foundation.  Oracle designates this
> 8: # particular file as subject to the "Classpath" exception as provided
> 9: # by Oracle in the LICENSE file that accompanied this code.

Documentation files should not have the Classpath exception.

make/data/license-templates/gpl-header

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

Changes requested by dholmes (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/22081#pullrequestreview-2434474132
PR Review Comment: https://git.openjdk.org/jdk/pull/22081#discussion_r1841189067