Do you know of alternatives ? When adding/changing command line options within the C sources, the man pages and texinfo file should automatically be updated.
This MR does it the following way:
build the tool
execute the tool with a special option
inject the output from the tool into a markdown template
use pandoc to generate manpage and texinfo from the resulting markdown file
The workflow allows the developer to just work on the C code (adding an array entry and doing the implementation). No manual editing of texinfo, no out-of-sync of implementation and documentation ever again.
No, I had searched in vain multiple times. I have found myriads of C option parsing libraries, but many are orphaned and none of the ones I looked offered the autogeneration of docs as autogen did. (A typical example is gengetopt: It can produce manpages, but they are very bare-bone, and it is also dead upstream.)
When adding/changing command line options within the C sources, the man pages and texinfo file should automatically be updated.
This MR does it the following way:
build the toolexecute the tool with a special optioninject the output from the tool into a markdown templateuse pandoc to generate manpage and texinfo from the resulting markdown file
The workflow allows the developer to just work on the C code (adding an array entry and doing the implementation). No manual editing of texinfo, no out-of-sync of implementation and documentation ever again.
That sounds very sensible and similar to the current solution. Thank you! (FWIW I think that moving away from autogen is something that will need to happen at some point, since it is a single-author project and upstream activity is declining.)
Regarding markdown to man and/or texinfo converters: The alternatives are rare. ronn needs ruby and only does manpage output. lunamark (lua) might have been a candidate, but it is not even packaged for Debian.
Note that the combination of the manpages with the texinfo documentation was done because we could, though it may not be completely natural to find the manpage information of gnutls tools in the pdf. Re-organizing the documentation to point that the tool information is available as manpages, and getting these manpages online in gnutls.org could be another way to address that.