[FLOSS] Can Doxygen be used for building our man pages?

[markus2330]

It is unclear if we can build our man pages (currently checked in doc/man) from the source files in doc/help via Doxygen.

See #4528 manpages.md for why this might be a good idea.

[0x6178656c]

I had a brief look at the Doxygen documentation and it seems that it does have rather limited Markdown support.

However, I am not sure if your dismissal of Pandoc is justified. You have written

Pandoc 2.9 doesn't have the Markdown description-list feature like ronn-ng has

What exactly do you mean by a description-list? Could you provide examples for this in doc/help?

In the context of Markdown I have found only "definition list" which is supported by Pandoc (https://pandoc.org/MANUAL.html#definition-lists) but not Doxygen (https://www.doxygen.nl/manual/markdown.html#markdown_extra).

---

I believe that changing the tool used for generating the man pages will inevitably lead to slight changes in the output format and might also require changes in the way the Markdown files are written (although that last part could possibly also be automated as a preprocessing step). So it is hard to evaluate what tool might be a viable alternative to the status quo since simply diffing the generate man pages would probably not be too illuminating.

[markus2330]

However, I am not sure if your dismissal of Pandoc is justified.

It is not dismissed, Pandoc is great. It is only probably oversized just for the manpages.

What exactly do you mean by a description-list? Could you provide examples for this in doc/help?

I clarified it here: https://github.com/ElektraInitiative/libelektra/pull/4562/files#diff-6561dbfc58d01d3ebd5119e75ca982853e25357a360e3db8e728733e2bba11a3

As you seem interested, I added even more options to give you a more complete picture of what choices I am thinking about.

@hannes99 is rewriting the tools, so it might be a good chance now to completely get rid of the duplicated documentation (once in spec for --help and a second time for the man page).

[0x6178656c]

Thanks for clarifying.

I think that your use of the term "definition list" differs from the common terminology in Markdown

The example from doc/help/kdb.md

- `-H`, `--help`:
  Show the man page.
- `-V`, `--version`:
  Print version info.

is a plain Markdown list. The indentations simply tell Markdown that the respective lines are continuations of the line above.

The behavior found in ronn-ng therefore seems to be a violation of ordinary Markdown conventions. The PHP Markdown extension would format a "definition list" as:

`-H`, `--help`:
    Show the man page.

`-V`, `--version`:
    Print version info.

For what it's worth, Doxygen already builds the man pages when BUILD_DOCUMENTATION is set. The man pages have a prefix build/doc/man/libelektra3/doc_help, e.g. build/doc/man/man3elektra/doc_help_kdb_md.3elektra.

Both Doxygen and Pandoc implement a more standard Markdown parser and render the above (first) as

       o -H, --help: Show the man page.

       o -V, --version: Print version info.

The GitHub Markdown renderer also does this:
https://github.com/ElektraInitiative/libelektra/blob/master/doc/help/kdb.md#basic-options

---

(once in spec for --help and a second time for the man page)

What do you mean with the spec for --help? I grepped the repository but did not find any examples where the --help does anything but show the man page.

This raises another question: If the files in doc/man are generated from the files in doc/help, then why are they part of the repository?

In conclusion, I think that if moving away from ronn-ng is the goal and you want to keep the output format there is probably no way around creating some bespoke tool for the job. (Although it might be possible to abuse, say, Doxygen to do the task by introducing a preprocessing step).

---

PS:

You wrote regarding Pandoc

• would need YAML metadata for every file

I thought so too at first! But you can actually provide Pandoc with the required variables from the command line. Pandoc uses a template (when using the standalone mode --standalone) you can view with

pandoc --print-default-template=man

which shows for instance that there are title, author, etc., variables. (Furthermore, it is also possible to modify the template as required.)
One could then do, e.g.

pandoc --standalone --variable title="KDB(1)" --to=man "kdb.md"

[markus2330]

I think that your use of the term "definition list" differs from the common terminology in Markdown

Feel free to directly make suggestions to the decision. Last comments should be corrected in 6740787

is a plain Markdown list

Yes but ronn interprets it in a different way.

What do you mean with the spec for --help? I grepped the repository but did not find any examples where the --help does anything but show the man page.

Sorry, I mixed here features of the gopts framework and kdb as specific tool. gopts has support for --help but this isn't currently used in kdb (and we also don't want to use it, the behavior to show the man page is good). The duplication kdb has is on unknown arguments, e.g. kdb ls --doesn-t-exist

This raises another question: If the files in doc/man are generated from the files in doc/help, then why are they part of the repository?

Exactly, they shouldn't be in the repo. This is what #4528 is about. 6740787 adds a sentence to clarify why it was introduced that way.

[markus2330]

Will be continued in decision by @hannes99