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

[James K. Lowden]

On Mon, 5 Oct 2020 18:48:27 +0200
Jan Stary <hans@stare.cz> wrote:

> In the mdoc source, it's .Sh DESCRIPTION; that's it.
> if Sh sections get turned into h1's (which is a decision in itself),
> all this does is it gives these h1's a class="Sh" and an id.
> 
> That is the simplest and most obvious thing to do;
> it is up to the presentation author to prescribe a style
> to h1's of class Sh (or refer to a specific one by its id).

What tool does that, btw?  

We're starting from an mdoc document, right?  Therefore every h1 is
generated from Sh, so every h1 is <h1 class="Sh">.  What, then, is the
point of the class, if the CSS selectors

        h1
and
        h1.Sh

always refer to the same elements? 

Also: how does one generate h2-h6?  

> For example, in th eabove page, the list of options
> is <dl class="Bl-tag">.

You might be able to convince me that mdoc->HTML is mostly a solved
problem.  I would point out that, because there's no ID there,
individual lists can't be uniquely styled.  

> > I would like to produce HTML5 from groff macros (all of them,
> > ideally), with all style choices made with CSS.
> 
> That's "inventing new syntax" in my book; in an insane way, I might
> add.

I honestly don't understand your objection.  Is the idea too
complicated, too specialized, or doomed to fail because "you can't get
there from here"?  

Ingo accused me of inventing "out of thin air".  I've been working
in this space for 2 decades.  I've used LaTex, SGML, texinfo, groff, and
HTML extensively, surely for hundreds of hours each, maybe thousands.
If that's "thin air", what would form a solid foundation?  

> You are proposing to include an entire language
> in each and every macro of another language.

Already done, more than once.  The groff macros already live
hand-in-glove with raw groff requests, and support
device-specific escapes.  

My heresy is to suggest extending the macro sets to support
device-specific escapes for a hugely important target device.  

Far from "an entire language", all I'm suggesting is a way to supply
to macros user-defined information that would appear in the HTML.  

Let's step back just a little, Jan.  troff was invented when printers
still mattered.  The whole postprocessor strategy sprang from the need
to adapt ditroff to the input language of the target device.  Today,
that design is obsolete except for groascii and grops/gropdf.  

Is there *any* more important deficiency among groff's outputs than
HTML?  Is there *any* better candidate among document preparation
systems to produce excellent HTML *and* PDF?  I can't name one. 

ISTM that adapting the macros to HTML is perfectly reasonable.  There
is no way the authors of the standard macro sets could have foreseen
the emergence of HTML or what it would require.  And there is no more
important missing target.  

> > From the point of view of someone who wants to produce a document
> > in HTML and PDF, HTML output is a glaring deficiency of groff.  
> 
> Eh, the defficiency of groff's html output is not having too few html
> attributes ...

I'm not sure what you mean.  IMO the problem with groff's HTML output
is that the HTML exerts too much control over the appearance. 

A better approach would be to supply only classes for anything
non-structural, and let the CSS determine what to do. Without CSS, it
might appear very 1990 plain.  The "standard" CSS would render it more
like what the author intended, a bit like nroff does.  The user could
write his own CSS to do things like "float" certain elements, for
example.  With access to class & id information (on both ends) he could
adapt the document to HTML's varying needs and function. 

--jkl