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

[John Gardner]

>
> *- "...and show me the manpage which your module produced out of it."*

*- "Show me one manpage your module has produced."*


It sounds like you read my e-mail in reverse before giving up halfway
through to shoot vitriol, because the first paragraph states quite clearly
it's *an idea:*

*> While we're on the topic of projects and hypothetical interest, maybe I
> should bring this up... I plan to develop a Node.js module to generate
> manpages with the minimal amount of effort expected of the average Node
> developer.*


The rest of your e-mails paint you in a pretty embarrassing light, but to
make sure nobody else interprets my emails as incorrectly as you did, I'll
address you seriously:

*No. What we really need is people documenting their software. A list of
> options is not documentation*


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, not
distributed programs.

There are many Node modules distributed as executables
<https://docs.npmjs.com/files/package.json#bin> with widespread use in web
development: mocha <https://www.npmjs.com/package/mocha>, clean-css
<https://www.npmjs.com/package/clean-css>, uglifyjs
<https://www.npmjs.com/package/uglifyjs>, coffee-script
<https://www.npmjs.com/package/coffee-script>, the list goes on... 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. 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?

Which brings me to this amusing abortion of logic:

*- They do have everything they need to write proper manpages: a text
> editor. They just don't care. It's not like they don't document their
> software because they can't.*



* - Like they would normally do, usign a text editor. Jesus.*


I'm leaning towards pity at the moment, because it sounds like you expect
the average joe to know how to write Roff source. In the JavaScript
community, no less.

*I just gave up.*


This is a pretty long-winded way of calling it quits, but I'm patient...


> *nroff was created by people who cared deeply for quality documentation.**So
> this is not even funny.*


FYI, I spent several months developing this
<https://github.com/Alhadis/language-roff> to improve the clarity of
manpage source throughout GitHub. Which now affects countless repositories,
both new and historical. I put blood and effort into getting each macro
package and *roff precompiler supported, out of a love of history and
respect for Unix traditions.

But yeah, calling it *nroff* as a playful nod towards history is obviously
disrespectful.



On 15 November 2016 at 17:46, Jan Stary <address@hidden> wrote:

> On Nov 15 10:56:28, address@hidden wrote:
> > While we're on the topic of projects and hypothetical interest, maybe I
> > should bring this up... I plan to develop a Node.js module to generate
> > manpages with the minimal amount of effort expected of the average Node
> > developer.
> >
> > It'd seem nobody in the Node.js community gives a crap about poor ol'
> > manpages, and I feel that each time the *"No manual entry for-"* error
> > reminds me that an executable's --help flag needs to be used to check its
> > options reference.
> >
> > 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.
>
> No. What we really need is people documenting their software.
> A list of options is not documentation. A node.js module which
> turns a list of options into a grammaticaly correct roff or mdoc
> is not writing documentation.
>
> > Relevant example which sparked the idea
> > <https://github.com/atom/atom/issues/5430#issuecomment-207519291>.
>
> Take this https://github.com/distopik/node-flac and show me
> the manpage which your module produced out of it.
>
> It;s pretty horrid what passes for documentation nowadays.
>