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

[John Gardner]

Hi James,

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.


Believe me, I hear what you're saying. My intention is to give the
JavaScript community something that enables them to generate manpages of
any size or complexity. Not necessarily for terminal output, either...
though I don't anticipate too many PostScript manuals of Node docs. =)

When possible, auxiliary info like descriptions will be populated using the
package.json <https://docs.npmjs.com/files/package.json> manifest, standard
in every Node module.

The module's API will be split into "layers", loosely tiered by how serious
an author is about generating documentation.

   - At the top-most level are bootstrap functions that're expected to
   cater to the worst-case scenario: Linux-loathing Windows devs who'd only
   put a manpage in their codebase after users pressured them to. Practically
   one-click solutions.
   - Second-level would offer something flexible, but sticking to the
   fundamentals: methods to add an option section, a synopsis section, et al.
   - Third-level digs deeper and offers control over specific nodes,
   which're abstracted well enough to allow extensibility
   - Fourth-level is allowing a Roff-literate author access to inject raw
   source if they absolutely feel the incentive to

Each "layer" is essentially a shortcut/wrapper for the one below it, and
nothing imposes restrictions upon an author. If one wished, they could use
a  "one-click" solution to produce a manual page from declared option
descriptions and filtered readme text, then work off that.

I want to name the project `nroff` which is a clever contraction of "Node
Roff", but this feels morally wrong somehow.. =)


On 15 November 2016 at 14:15, James K. Lowden <address@hidden>
wrote:

> 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
>
>
>
>
>
>