Re: [Groff] groff developments - query about any interest?

[James K. Lowden]

On Tue, 15 Nov 2016 10:56:28 +1100
John Gardner <address@hidden> 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