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
