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

[John Gardner]

>
> *I, for one, do not expect an HTML rendered version of *anything* to be a
> faithful representation of a printed page.*


Barring physical factors like paper size, overprint, bleed and other
print-specific stuff, it's actually possible – thanks to CSS. It can
declaratively target 3 very different output mediums
<https://developer.mozilla.org/en-US/docs/Web/CSS/@media#Media_types>:
screen (browsers, tablets, phones, projectors, etc), print, and speech (the
last medium is particularly crippled by poorly structured markup...) There
were originally others, but they were axed from the spec largely due to the
shift in the technology landscape. Having tv, projection, and handheld as
distinct media types made less sense as smartphones took off and browsers
went mobile. Others like braille and embossed were narrow attempts at
accessibility - WHATWG realised that disabilities and assistive
technologies were too complex to be addressed by CSS alone, so it was
deferred to WAI-ARIA instead...

On 22 April 2018 at 00:54, John Gardner <address@hidden> wrote:

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