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 <gardnerjo...@gmail.com> 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 <h...@stare.cz> wrote: > >> There is a reason I am keeping these ramblings off-list. >> >> On Nov 15 19:08:52, gardnerjo...@gmail.com 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 >> >> >
