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

[Jan Stary]

On Nov 15 20:00:09, 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.

Exactly. Shudder to think.

I just don't think this is much relevant to groff itself.

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

"Not in an ideal form" is a mild way to put it.
It's a list of options. That's not documentation.
There's no DESCRIPTION of what it is and what it does
(and why and how), and what BUGS it has.

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

Exactly. And that informative description, known as DESCRIPTION,
does not exist. All that exists is a list of options, at least
in your example below.

You propose to rewrite that list of options
(formated so far in the way node.js software formats it)
into a roff-formated list of options in a manpage.
It's surely more convenient to have that manpage
instead of the --help output, as a _form_,
but it's still just a list of options.


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

And they agree to include it in their repository,
as a way to generate a manpage, because they care
that their node.js software has a manpage. Right?

>    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

This is the "informative description" you talked about above?
I have just read that .option() list and I have no idea
what "mocha" is and what it does. How is that documentation?

>    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

I just don't think it's gonna happen with much of node.js software.
They are not gonna include your thing into ther build process,
because all that it would do for them is generate a manpage, and

  "What would be in that 'manpage'? The list of options?
  But we already have --help to display the list of options!
  And how do you display that 'manpage' on windows anyway?"


> This wouldn't even ask anything of the maintainer's behalf.

Except integrating someone else's code and
changing their build process accordingly.
No big deal.

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

Muhahahaha. No.
They'd most probably not care.

Believe me, I have tried. There is software that I use and like
which has sub-optimal documentation, ranging from ill-formatted roff
to docbook to horrendous sed-awkery which greps for getopt, to nonexistent.
In quite a few cases, I have written clear cut mdoc(5) manpages from
scratch and offered them upstream. As far as I can remember,
libsndfile was the only one which simply took the nice manpages.
In most other cases, they just didn't care.
You cannot display a manpage on windows anyway.

(In one case, they adopted the mdoc(5) manpage but later found out
that some tool that comes with KDE and produces "html manpages" for them
slightly breaks on the mdoc(5) input, so they backed off.
Don't remember which one that was.)


And I don't think you will have much better luck
getting JavaScript developers, of all people,
to incorporate your manpage-producing tool.


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

I'm sure you are the master of regexp, but I'll repeat:
greping for ".option(" and rewriting it into roff
is not documentation.