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

[John Gardner]

The Germans have a word for what I'm feeling right now, and it's
*fremdschämen...*


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


Well, it's now come down to sick amusement from seeing unsubstantiated
criticism from somebody who *very very blatantly* has no idea what he's
talking about.

I won't doubt you know about good documentation practices and authoring
roff/mdoc. But every time you've used the word "JavaScript" in a sentence,
it's been juxtaposed to an abhorrent train-wreck of logic that stretching
my ability to issue an adequately sarcastic response.

I'm just gonna start ripping band-aids off:


> *- I have just read that .option() list and I have no idea what "mocha" is
> and what it does. How is that documentation?*

*- but I'll repeat: greping for ".option(" and rewriting it into roff is
> not documentation.*


This sentence is like an Escher painting; but instead of staircases, it's
the mental image of a deluded programmer attempting to execute JavaScript
by matching patterns against its source code and cobbling it together into
some meaningful result.

*It's a list of options. That's not documentation.*


Today I learned it's possible to be elitist about how information is
communicated.

*because they care that their node.js software has a manpage. Right?*


Yes, the strategy here is to pump as many numeric file extensions as
possible into modern codebases. The fact it's making documentation easier
for to access for Linux/BSD/macOS-users is just a side-effect I'm relying
on.

*What you percieve as hate was meant simply as a criticism. You will be
> wasting your time building this. But go ahead.*


There's a word I'd like to use to describe the accuracy of your criticism,
but I don't think it exists in English. It means the exact opposite of
being something a human mind was meant to follow.


On 15 November 2016 at 21:05, Jan Stary <address@hidden> wrote:

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