Re: (off topic?) Docbook? Re: manlint?

[John Gardner]

Ironically, modern HTML isn't too dissimilar to nroff(1) output. For a
start, document structure and content hierarchy is critical for
readability, be it for humans (TTY output) or browsers (web-pages).

Secondly, most presentational details are lost because they're irrelevant
to the target medium. For nroff(1), that's because terminals are limited in
what they can render. For HTML, that's because CSS handles anything without
a semantic representation in HTML, SVG, or MathML. CSS is designed to
handle every fathomable medium for displaying a web page — be it a
smartphone, laptop, laser printer, text browser, text-to-speech software,
and all of them at varying levels of resolution. Conversely, Troff is only
designed to prepare output for a single display medium, rendered at a fixed
resolution and page-size (\X'papersize' notwithstanding).

So, instead of trying to preserve fonts, colours, margins and columns when
generating an HTML version of a Roff file, forget about such details in
favour of a separate (hand-written) stylesheet. It doesn't take much CSS to
establish the look-and-feel of the equivalent PDF output: Here's how I'd
render mandoc(1)'s manual page in HTML (without actually using mandoc…
sorry Ingo ;-))


   - Document content
   
<https://github.com/Alhadis/Stylesheets/blob/efd0e965f0d45839ba0505a7db6dcb7ce17b616e/complete/manpage/example.html>
   - Stylesheet
   
<https://github.com/Alhadis/Stylesheets/blob/efd0e965f0d45839ba0505a7db6dcb7ce17b616e/complete/manpage/manpage.css>

Here's how it all looks <https://cdpn.io/alhadis/debug/WNwWrOP/bYAdyXEXeXGk>.
Try opening it in lynx(1), which doesn't support CSS. Thanks to semantic
markup, the rendered document is more-or-less consistent with how a man(1)
page *really* looks.

</FMTEYEWTK>

On Mon, 28 Sep 2020 at 08:31, James K. Lowden <jklowden@schemamania.org>
wrote:

> On Sun, 27 Sep 2020 00:14:47 -0400
> Larry Kollar <larry.kollar@me.com> wrote:
>
> > Complain about Markdown all you will, and use weird-arse corner cases
> > to show it?s Bad, but GFM can handle a lot of everyday text.
>
> If you limit the feature set to what markdown does, -ms macros are
> readable too.  It's a little tricky to set up an auto-incrementing
> register -- I always have to look it up -- and it's a nuisance to
> separate paragraphs with PP, but SH, IP, I, B, and PP get a lot done.
>
> Obviously -ms lacks hyperlinks.  The things markdown lacks are too
> numerous to mention.
>
> > OK, let?s move to *roff for a moment. It can do most of the things
> > that DITA advocates tout: reusable topics, conditionals, variables,
> > insertions, and so forth (you can get a *lot* of mileage out of .so).
> > Most of the -ms macros that come before the first .LP or .NH are
> > considered book metadata in DITA, so metadata is covered. What
> > *roff doesn?t do is produce usable HTML output. Yet.
>
> There can be no question that troff boasts a very rich input language.
> Every time I point that out in the context of advocating its use,
> someone says, "but HTML".
>
> I think the idea behind grothml is that one input document "just works"
> with any backend.  A different -- and, I would argue, more
> realistic -- approach would be a macro-to-HTML converter that worked
> only for documents expressly written with HTML in mind, using only
> macros and eschewing troff requests.  Such a document is, I assert,
> easily converted to HTML and produces perfectly acceptable PDF.
>
> Almost any macro set you pick maps onto HTML pretty
> well because they work at about the same level: they define gross
> aspects of the document that are refined in terms of the target
> device.  If there was a simple way to add a "class" and "id" to macros
> (that would be ignored except for HTML) then a very
> simple HTML tagged with classes and IDs could leave most presentation
> choices to CSS.
>
> Any suggestions on how -ms macros could be compatibly extended to
> include classes and IDs?  I've always found that aspect of my
> "proposal" daunting.
>
> --jkl
>
>
>
>