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

[John Gardner]

Good news, folks! The hate I've copped from Jan has inspired me to
prioritise this as my next project, which I hope to commence work on
shortly. =)

To spite Jan further, I've decided the project *will *be named on NPM as
*nroff*, with the human-readable title being "Node-Roff". Since any
*reasonable* person can see why that's an appropriate name for a *node-based
roff* generator.

Thanks for the motivation Jan... when something I love working on works
somebody up, it gives me incentive to work on it harder. =)

On 15 November 2016 at 20:00, John Gardner <address@hidden> wrote:

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