groff
[Top][All Lists]
Advanced
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Ingo Schwarze
Subject: Re: (off topic?) Docbook? Re: manlint?
Date: Thu, 8 Oct 2020 02:38:04 +0200
User-agent: Mutt/1.12.2 (2019-09-21) 
Hi James,

James K. Lowden wrote on Wed, Oct 07, 2020 at 06:58:33PM -0400:

> I shouldn't criticize mandoc, especially its HTML output, without
> having used it.  
> 
> mdoc doesn't have levels of section headings the way -ms has.

Mostly true; mdoc has .Sh and .Ss, and i map these to <h1> and <h2>.
Since writing very long manual pages is considered poor style,
a third level is almost never needed.  In the rare cases where
some kind of a third level makes sense, people tend to use
tagged lists (.Bl -tag; i map that to <dl>) or *very* rarely just
a one-line paragraph with bold text (.Pp .Sy title .Pp).  But all
this is so rare in practice that mandoc(1) does not attempt to map
any such constructs to <h3>.

> For mdoc purposes, perhaps H1 is enough.  

Often, yes, plus <h2> in some longer pages.

Note that mandoc -T html supports a "-O fragment" mode which prints
just the contents of <body>, but without <body> tags around it, and
some sites use that mode to prepend not only their own <head>, but
also their own body content (like page headers, site navigation,
and the like).  A notable example of a site doing that is:

  https://manpages.debian.org/

The mandoc version used there is slightly outdated, but it still
demonstrates the general approach.

In principle, sites wrapping mandoc output in this way can use <h1>
in the surrounding code, without class="Sh", and then the class
will make a difference.  (Admittedly, manpages.debian.org isn't
doing that right now, and the Arch manual page site isn't either,
but they could if they wanted to.)

  https://jlk.fjfi.cvut.cz/arch/manpages/  # Arch manual pages

> I'm actually arguing in favor of applying mandoc's "just the macros"
> approach to HTML, but for all macro sets, not just mdoc and man.  
> 
> I might just try passing my texinfo sources through texinfo2mdoc,

Caveat:

 * pod2mdoc(1) is ready for routine use in production.
   It has been used to translate the complete LibreSSL documentation,
   thousands of pages.
 * docbook2mdoc(1) is experimental in so far as many features are
   missing, but has been used in production anyway to translate
   small numbers of X11 manuals.  It is not yet expected to handle
   all valid DocBook constructs.
 * texinfo2mdoc(1) is by far the most experimental of the three.
   It has never been used in production.  Feeded real-world documents,
   i would expect that it probably mishandles part of the input.
   The reason that it received the least amount of development and
   maintenance is that there has been less demand for converting
   texinfo docs.

> and see what pops out.  You never know.  
 
>> I can't speak for Ingo, but I don't think the "thin air"
>> was meant as an insult to your expertise.

The words "thin air" weren't even mine, James used them in explaining
how he interpreted what i wrote.

> Fair enough, thank you.  It seemed so to me, after leading with the
> assertion that I was struggling to solve a solved problem.  

I never intended to judge James' experience with respect to HTML
generators.  The "solved problem" referred to generating CSS-ready
HTML5 output from a roff(7) macro set - to be understood as "solved
in principle and implemented for one major application", of course;
so far, it is implemented for mdoc(7) and partially, with the
limitations caused by the language, for man(7).

Part of our talking past each other might result from a different
mindset: my expectation was to talk about the output-device-independent
design of semantic markup languages of the roff(7) family and how
to generate HTML5 output from them that is useful together with
CSS, so i didn't look kindly at syntax suggestions that felt like
being useful for no output mode except -T html.  Right now, i wonder
whether maybe your mindset in this context was to (mostly?) regard
roff as a HTML generator.  At least, that might explain suggestions
like:

  .SH Id foo Class bar

But even then, i don't particularly like the idea of designing
syntax with one specific output format in mind.

Yours,
  Ingo
reply via email to
[Prev in Thread] Current Thread [Next in Thread]