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

[John Gardner]

>
> *"There is a reason I am keeping these ramblings off-list."*


Well you haven't stated the reason, so I'll assume it's fear of opprobrium.

*Nota bene:* every reply you send will be publicly echoed back to the
mailing list. I've zero patience for arguments, especially one triggered by
a modest request for feedback for an idea.

*"You mean manpages, not webpages, right?"*


I'm flabbergasted my last e-mail had room left for ambiguity. Yes, I meant
manpages. Generated using *man* or *mdoc*, for terminal delivery.

*"What hope do you think one has of convincing people who do not care about
> documenting their software to document their software?"*


I've mentioned repeatedly that this documentation exists, just not in an
ideal form for those used to consulting manual pages for program reference.
If you want an *informative* description of what *git submodule* subcommands
do, for instance, you don't rely on *git submodule --help *to give you
meaningful documentation (beyond simple usage, I mean).


>
> *- "But it's _an_interesting_idea_, right? So let's see what comes out,
> eventually. Two obvious candidates:1. node.js developers producing
> manpages2. nothing"*

*- Here's another idea: ask the node.js dvelopers whether they would be
> willing to write documentation if you provided them with this tool. *


I've actually gotten this in writing. You can't make this up, folks.

*Just to be clear: I don't mean any disrespect. I just think it's
> pointless.* *If a guy writes a manpage for his software (node or
> otherwise), great. If not, how is that manpage going to come to existence?
> Someone has to write it.*


No. It's quite simple. I'll bullet-point it for you:

   1. I submit a pull-request to MochaJS's core repository
   <https://github.com/mochajs/mocha> introducing this new module
   2. Explain how it generates manpages by hooking into options they've
   already detailed
   <https://github.com/mochajs/mocha/blob/master/bin/_mocha#L62> for --help
   output
   3. Some questions are poised to ask that their preferred method of
   integration would be
   4. After some feedback and a few adjustments, it's merged into their
   codebase, become part of their build process, and is distributing copies of
   manual pages that're immediately available to every user the next time they
   run `npm update -g`.
   5. Suddenly, typing "man mocha" presents a manual page

This wouldn't even ask anything of the maintainer's behalf. They'd probably
be happy knowing their project's options are accessible in a medium that
would've taken them a fair bit of effort to tap into.


> *Or can a script turn the semi-structured --help into a proper manpage
> (roff or mdoc or otherwise)?*


Even if I weren't as fluent in regular expressions as I am, there's no
hackery involved here. It's taking input from existing code. No hackery or
guesswork is being performed.


On 15 November 2016 at 19:31, Jan Stary <address@hidden> wrote:

> There is a reason I am keeping these ramblings off-list.
>
> On Nov 15 19:08:52, address@hidden wrote:
> > When I refer to *documentation*, I'm referring to *documented usage of an
> > executable program*, like grep, git, groff, sed, et al. You sound like
> you
> > think I mean generating inline documentation for source code
>
> No I don't. Stop.
>
> > [Irrelevant list of random node.js software snipped]
> > Any web developer in a Unix-like environment who prefers the comfort of
> > command-line who uses these tools on a daily basis has probably felt the
> > sting of not having a decent man-page for programs with option lists of
> > non-trivial size.
> >
> > This is what I'm trying to achieve: giving developers a way of authoring
> > webpages without taking the hard turns of learning Roff.
>
> You mean manpages, not webpages, right?
>
> > I had enough
> > difficulties explaining cosmetic fixes to a manpage for a Node.js
> developer
> > <https://github.com/nodejs/node/pull/7819#issuecomment-234326130>... and
> > this is more regard for Unix manpages than you'll get from most of the
> Node
> > community. What hope do you think one has of convincing them to learn an
> > ancient typesetting language?
>
> What hope do you think one has of convincing people
> who do not care about documenting their software
> to document their software?
>
> But it's _an_interesting_idea_, right?
> So let's see what comes out, eventually.
> Two obvious candidates:
>
>         1. node.js developers producing manpages
>         2. nothing
>
>