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

[Jan Stary]

On Oct 05 11:43:33, jklowden@schemamania.org wrote:
> On Sun, 4 Oct 2020 20:46:20 +0200
> Ingo Schwarze <schwarze@usta.de> wrote:
> 
> > You are discussing a problem that has been solved years ago, and
> > the solution has proven very successful in practical use: mdoc(7)
> > style is that you *never* specify the class manually but the macro
> > name *is* the class.  
> 
> Ingo, I'm never sure if the arrogance you exude is intentional or
> accidental.  
> 
> The problem we're discussing -- the one I'm discussing, anyway -- is
> unsolved. To wit: how to insinuate HTML information into the
> groff macro sets and map macros onto HTML, starting with -ms.

Sorry, I don't get it: what "HTML information"?
Some extra html attributes not present in the roff markup?

Do you mean to augment e.g. .PP with something like .PP class FOO
so that you can later turn it into <p class="foo"> in html output?

> I'm also interested in mdoc.  

Look at the html source of, say, http://man.openbsd.org/ls
- for example, <h1 class="Sh" id="DESCRIPTION"> .
That's exactly what Ingo describes above.

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 "HTML information" do you mean to "insinuate"
inside the Sh macro, for example?

Doing that imho implies supporting (a subset of) html attribute syntax
inside every macro, which is crazy (but I'm not sure it's what you mean).

> Not only is it unsolved, but the solution you propose is pointless.  
> If the macro is the class, and each macro maps onto 1 HTML tag,

There's two things here, if I am not mistaken.
To stay with the example above, one thing is that
Sh's get turned into h1's; the other thing is that _these_
h1's get a classs of "Sh" - you might want to have other macros
beside Sh also turned into h1's (of a different class then).

> then the class provides no additional information.

What "additional information"?

Having <h1 class="Sh" id="DESCRIPTION"> captures exactly the information
that was present in the source, namely, "this is an h1 that was created
from a Sh macro that named a DESCRIPTION section".

> The CSS cannot differentiate among, say, paragraphs
> if every paragraph has the same class.
>       <p class=PP>

Exactly - corresponding to the fact the a PP is a PP.
How do you differentiate among them in the mdoc/roff source?

> > Several years of practical experience show that specifying the ID
> > manually is very rarely needed.  
> 
> I have a few years of practical experience myself.  (Is there such a
> thing as "impractical experience"?)  And, yes, my style sheets usually
> don't use the ID but sometimes, as with the examples you cited, they do.
> 
> ID has survived in HTML, triumphing over NAME, through 5 major revisions
> over 3 decades. From that I infer they must be useful to someone.  It
> follows that, for them to be produced from groff macros, those macros
> need some syntactic support for them. 

To be sure: do you propose that every groff macro support
and ID argument so that it can have an id="..." in html output?

Or, more generally, that groff macros support some subset
of html attributes to be used in html output?

> > Remember that authors will not be amused because they
> > have to type in all that syntax you are inventing.  
> 
> That remark exemplifies the condescension I find most irritating.  It
> implies I'm inventing syntax out of thin air,

If the above is what you are proposing (again, I'm not sure),
it is new syntax, isn't it. Or does PP have an ID now?

> As it happens, the problem of generating good HTML from other markup is
> rather close at hand for me, having recently arranged for that manual
> to be produced as HTML from texinfo.  Texinfo is (as you know) semantic
> markup.  It lacks, however, anything like the detailed DocBook tags for
> user interaction on a screen, making it impossible to render, say,
> user input in boldface in an example terminal session or, for that
> matter, to render user-terminal sessions in COBOL-standard
> green-on-black. I would have liked to have been able to use a class for
> that.  

If texinfo had a macro for, say, user input, then doing what
Ingo describes would give you a html element of that class, right?
But texinfo has no such thing, which is a different problem.

> Dictionary lists are also problematic.  Depending on the sizes of the
> terms and their definitions, and the length of the list, it may be
> better to have the list rendered as 
> 
>       term def
>       term def
>       term def
> 
> or
> 
>       term
>               def
>       
>       term 
>               def
> 
>       term
>               def
> 
> If every <dl> has the same class, the CSS cannot distinguish between
> them by class.  The texinfo workaround is to insert explicit HTML <div>
> before and after the list. That's awkward in texinfo, a language that
> has explicit begin/end constructs.

I agree that texinfo is awkward; mdoc has lists of different styles
though (-bullet, -enum, -inset etc), and has a -width.

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

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

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

> 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 don't think it's a deep insight to notice the similarity of HTML tags
> and groff macros, and I'm sure I'm not alone in suspecting that one can
> be mapped unambiguously onto the other.  

I see. That makes them basically the same language,
right? Just calling the elements some other names.

In the sacred words of tedu@openbsd:
we still don't feed all the inputs to all the parsers!

        Jan