Re: [groff] groff as the basis for comprehensive documentation?

[John Gardner]

>
> None of those, and certainly not an em dash. It's `man page', short for
> `manual pages'.


Haha, don't worry! =) I was being facetious. Probably could've communicated
the joke better with `man\D'l 99n 0'pages` instead.

In all seriousness, I can be horribly inconsistent with hyphenation in
general, and I drive myself nuts. Somedays I'll write `e-mail`, and other
days it just looks like I'm subtracting the value of the `mail` variable
from whatever value is bound to `e`.... =(

*I suppose it depends on what one expects from the generated HTML.*


I should probably explain my other motive for developing these
post-processors. Schooling Ingo on HTML earlier has probably left me
looking way more critical and judgemental of people's markup than I really
am. It's arrogance and ignorance (and too much holding-my-tongue) that
caused me the long-winded bitchslap I gave before.

As I mentioned earlier, I recently refactored Node.js's manpage to use
mdoc(7) macros instead of man(7). My motive was to make formatting errors
harder for the majority of contributors, most of whom are unfamiliar with
roff or its macros. I was checking Node.js's repository to see if a patch
for OpenBSD had landed, and saw a recent commit
<https://github.com/nodejs/node/commit/e56189ed58903f63a3d9d877d98b3bbcbc432710#diff-176884dfbb649efd3b1316139eb4cd69>
titled *"doc: fix manpage warnings"*.  (Keep in mind this is the *only*
Roff file in a sea of markdown files. Heck, the project's *canonical source* of
documentation are markdown files split, parsed, and fed through a variety
of interlocked JavaScript modules to produce parsable output suitable for
their site's API pages <https://nodejs.org/api/all.html>.

An attempt <https://github.com/nodejs/node/pull/14164> was made to do the
same for generating manpages, but the contributor couldn't find the time to
finish the PR. I'd assumed it may have had something to do with lack of
Roff-knowledge, rather than the fact he was using Node.js's JSON-formatted
docs to generate the manpages. After all, anything in JSON format is
*surely* done with the intent of making content portable and
not-at-all-format specific, right? Right? I.... *OH GOD, IS THAT RAW HTML
IN JSON THAT WAS GENERATED FROM MARKDOWN?! <https://nodejs.org/api/fs.json>*

Yes. Yes it is. *And the entire web industry can't stop doing this shit.*

The web industry's obsession with markdown is going too far. Honestly, I
get the appeal of markdown being contributor-friendly, but when you've got
30-odd dependencies to generate JSON, static HTML, PDF and
god-knows-what-else, and you're *still* tasked with checking a manpage to
see if its options are "in sync with the rest of the documentation", you
can't help but wonder where the hell everybody went wrong.

Troff is a powerful, horribly under-appreciated system. If people actually
bothered to write manpages by hand, they'd be amazed by what the language
and its associated programs can really do. But today's generation of devs
have zero incentive to even give it a try. Those who are impelled to learn
any sort of programmatic document preparation will default to LaTeX,
period. Even if compiling LaTeX documents is as pleasant as pulling teeth,
and even if LaTeX formats are binary and completely opaque to the casual
observer.

*The only sane response to insanity is more insanity, *and I'm probably
crazy enough to believe more devs might give Roff a crack if they knew it
was easier to generate markdown and HTML from Roff, rather than the other
way around. Trouble is, grohtml's HTML output is, uh, somewhat archaic in
the age when HTML5 is now considered an umbrella family of specifications
<http://html5-overview.net/current>, rather than a language revision. Now,
I'm not holding this against anybody - when grohtml was devised, it was...
what, early 2001? 2002? CSS support was spotty and inconsistent, and the W3
kept claiming XML/XHTML was the way of the future. Zero progress was made
for about 7 years, and I honestly can't blame Groff for using very outdated
layout techniques. Basically, anything laid out using HTML tables clearly
wasn't written within the last decade...

We just need a post-processor that can generate reusable, *stylable* HTML
output for an endless and unpredictable range of both site layouts and
portable devices. Intelligently-structured markup is the first step – most
front-end developers these days are reusing existing stylesheets written in
a variety of CSS precompilers. The only way to accommodate this
all-pervasive cesspool of copy+pasta is *to focus on content and semantics,
not its presentation*.



On 21 April 2018 at 23:25, Ralph Corderoy <address@hidden> wrote:

> Hi John,
>
> > Manpages, man-pages, or man\(empages?
>
> None of those, and certainly not an em dash.
> It's `man page', short for `manual pages'.
>
>     $ dict -ms regexp 'man.*page'
>     jargon:  "man page"
>     foldoc:  "demand paged"  "man page"  "unix man page"
>       "unix manual page"
>     $
>
> It might get hyphenated as a compound adjective, `the man-page macros',
> or in a filename where as space isn't wanted, `man-pages.7'.
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>