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

[James K. Lowden]

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.  
I'm also interested in mdoc.  

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, then
the class provides no additional information.  The CSS cannot
differentiate among, say, paragraphs if every paragraph has the same
class.   

        <p class=PP>

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

> mdoc(7) style is to insert the ".Tg" (tag) macro

1.  Really?  A macro you implemented outside groff 9 months ago is
"mdoc style" already?  

2.  IIUC, Tg creates an anchor.  (The link doesn't show the
corresponding HTML, so it's hard to tell.) IDs are used for more than
anchors, as you know, else they wouldn't appear in stylesheets.  

By "mdoc style", I only meant mdoc's unique way of stringing macros
onto a single line.  I find it works well, even if it's sometimes
confusing.  

> 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, impractically, over the
objections of more knowledgable users, unconcerned with their lack of
amusement.  What did I say that makes you think that?  

        https://gnucobol.cobolworx.com/

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.  

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.  It would be awful in -ms, where
ends are implied by new beginnings.  

+++

I would like to produce HTML5 from groff macros (all of them, ideally),
with all style choices made with CSS. 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.  

More than one person has converted groff macros to HTML but, other
than grothml, groff itself includes no standard, general solution.  I
don't think grohtml is the right approach, because 

1.  The structural information in the macros -- and needed for HTML
tags -- has to be squeezed through ditroff, where it's otherwise not
needed.

2.  The presentation details normally applied by the postprocessor are
discarded, or should be, because they're under the control of CSS and
the browser.  

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.  

The question I asked was, how could class and ID be added to various
macros in a way that doesn't trip up existing macro processors?  I
haven't seen a solution I like yet, least of all yours, which is none
at all.  But I'd like to.  

--jkl