On Tue, 15 Nov 2016 10:56:28 +1100 John Gardner <gardnerjo...@gmail.com> wrote:
> There're modules out there to generate manpages using Markdown or > other intermediate formats, but what we really need is something that > can use existing option-configs and churn out correctly-formatted > manpages without asking anything of the author. While I applaud the effort, I want to point out one pitfall. As you approach this problem, remember that "correctly formatted" doesn't imply "complete". A man page is more than a list of options. What's missing in the example you linked to between SYNOPSIS and OPTIONS is the meat of the matter: DESCRIPTION. If "without asking anything of the author" is part of the remit, then I suggest you'll want some structured way to augment the output. It could be a database of Descriptions by name, or a template that, if extant, has it's missing parts filled in rather than generated de novo. That would give people who'd like to improve the documentation a framework to work in, and continue generating from the source as it changes. (You might also want some way to determine when the generated output changes, version over version, to flag which augmented pages might need review.) I did something like this for the Subversion project. There, the "help" input is kept in a bespoke structure to facilitate reproducing shared text in different places. I used Perl to convert the output to man pages. The framework would have taken some work to generalize and keep up to date and, frankly, when I was done I was convinced that going the *opposite* way would have been better: maintain proper man pages, and generate "help" from them. Use .so to include shared parts. Much easier and much higher quality because the formatting macros are inserted directly, not algorithmically. But of course that means the team has to be willing to maintain man pages, which many regard as impossible without a VAX handy. I learned the same lesson a different way using Doxygen: generating the simple bits is pretty easy. Getting quality documentation out of it requires curation. --jkl
