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

[Eirik Bjørsnøs]

On Fri, 15 Nov 2024 14:50:21 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 one additional commit since the last revision:
> 
>   It's somewhat nicer to use \\s instead of space character in regex

Is the warning log when pandoc is not installed a bit loud?


% make images
Building target 'images' in configuration 'macosx-x86_64-server-release'
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Finished building target 'images' in configuration 'macosx-x86_64-server-release'

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

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