Hi Stephen, At 2026-05-08T20:00:41-0700, Stephen Gildea wrote: > > I don't want to get carried away with extensions. First, > > most people won't use them. Second, I find the semantically > > oriented mdoc(7) macro language too big. > > Yes, there needs to be a balance: the list of macros needs to > be small enough that people can remember which one to use, yet > big enough to produce pretty, accessible and searchable manuals.
My feeling exactly. When I first came to groff development I spent quite a bit of time thinking about why mdoc(7), despite its (loudly) touted superiority on the part of its advocates, and its possession of some features I found appealing vis à vis man(7), didn't win the war it had declared in Net/2 BSD, even after multiple multi-year stretches of near stagnation in man(7) development (even at the level of bug fixing), and a lengthy overlapping period where it was widely claimed that HTML, or DocBook-XML, or Doxygen, or Markdown, or some other new technology would swoop in and solve the documentation problem for us.[1] I twigged that one of the reasons man(7) has endured is its relatively small lexicon. > When I look over my man pages, I see only a few constructs: > > - definition lists > I currently use .TP for these, and it works well. Yup. 100% idiomatic. > I look > forward to .LS/.LE enabling them being represented in HTML > using DL instead of TABLE. That'll take some of the pressure off of me to reimplement the long- moribund troffcvt(1)'s tbl-to-HTML translator.[2] > - itemized lists > I have had to hack these to make them look good, and > .LS/.LE will give me the options I need. Excellent. > - example blocks > I use .EX/.EE for these, and it works well in PDF output > but fails to use a monospace font in HTML. This is an > implementation bug, not a macro-language deficiency. Yup. Tracking as <https://savannah.gnu.org/bugs/?68309>. > - inline examples > Switching to Courier font works fine in PDF output and not > at all in HTML. It would be nice to see this translate to > CODE, TT, or some such, but it probably doesn't need any > macro support. This is hard to support because while one can intercept _requests_ in GNU troff, there's no way to intercept an escape sequence. So when people use `\fC` or `\f(CW` or even `\f(CR` (the last being otherwise supported by groff) in nroff mode, it's hard for the macro package to help them by falling back to some sensible alternative--the document has already gone behind the package's back. As I've noted elsewhere, I'm hearing a bit of grousing from people running linters on their man pages who are upset that groff now throws warnings when a font selection fails. They are upset even when the warning occurs in nroff mode, and accuse me of having withdrawn support for monospaced typefaces in their man pages. That is, of course, false. Terminal devices _can't change the font family_ and every terminal emulator that even weakly implements ECMA-48 lays out the screen as a uniform grid of character cells. That means that the font in use is _already monospaced_. Further, nothing about the rendering has changed on these devices. `\fC` was _always_ doing nothing in nroff mode.[3] It's just that now, GNU troff is _telling_ you that your command to it is, and always has been, futile (in nroff mode). Evidently that is unwelcome information. > - Sections, subsections, and paragraphs > All well-supported: .SH, .SS, .PP I'll try not to break 'em, then. ;-) > To summarize, it seems to me that .LS/.LE fills maybe the only > deficiency I feel in the macro language. Nice! Great news. > > $ sed -i -e 's/^\.PD 0/.LS FIXME 1/' -e 's/^.PD$/.LE/' mypage.man > > > > ...then make one pass over the document, replacing the "FIXME" with > > "definition", "itemized", or "enumerated" as appropriate. > > I can do that. > > But what about the bullets (or numbers) in front of every list item? > Currently I write bullets in manually with \(bu on each line; I'm > hoping that ".LS itemized" will cause .IP to make the bullet for me. > What's your vision here? Sorry to disappoint, but my vision here is to change nothing in this respect. The reason is another of the objectives you identified: maintaining compatibility with formatters that don't copy my proposed innovation quickly, or at all. They can utterly ignore `LS` and `LE` calls, and the following will still format tolerably. .IP \(bu ...which works everywhere I know of today, and... .IP ...which does too, and already has semantics that _don't_ include "put a mark on this paragraph". So an "implicit mark" seems unachievable.[4] Maybe someone has a clever idea that will cut this knot? For the record, the interface of the mm(7) package list-begin macro is an anti-goal of mine. groff_mm(7): LB text‐indent mark‐indent pad type [mark‐or‐format [pre‐item‐ space [pre‐list‐space]]] Begin list. The macros AL, BL, BVL, DL, ML, RL, and VL call LB in various ways; they are simpler to use and may be preferred if they suit the desired purpose. That Spruce Goose will never soar among man(7) authors. Regards, Branden [1] For more of my half-informed speculations on the nature of *nix documentation intertia, see: https://lists.gnu.org/archive/html/groff/2026-04/msg00056.html [2] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1059802 https://lists.gnu.org/archive/html/groff/2025-01/msg00052.html https://savannah.gnu.org/bugs/?60052 [3] You _could_ exercise a GNU troff extension to remap the `C` font, say to `R` or `B`. But a man page should *never* do that. Only a system's "man.local" file or similar should be so meddlesome. And it's hard to know which choice aligns better with the intention of the man page author in any case. Moreover, it's not always warranted to assume that said intention is consistent within a document. Man pages tend to get fiddled by many different hands over the years. I think trying to get at inline Courier in man pages is a fool's errand. I'm not 100% opposed to introducing yet another new macro (pair--see below) to support it, because at least with a macro the package can evaluate the font-change instruction and try to do something sensible, and perhaps even string-configurable--but this solution faces multiple strong headwinds. First, many man(7) authors are besotted with `\f` escape sequences. If they don't change their input habits, a new macro won't help them. As noted above, if you use an escape sequence, a macro package is impotent. You've punched through the floor already. Second, the next most obvious thing to implement and to type is yet another font macro, say `C`. Apart from the combinatorial impact of an orthogonal design implying a need for font alternation macros with every other face, producing CB, CI, CR, BC, IC, and RC--a major bloat to the lexicon I really do want to keep lean, there is a big hazard here...what happens when the renderer doesn't support these macros? Recall what a formatter does with an unrecognized macro. The call is ignored. Text vanishes. Worst, some of the most important text in the document is precisely what goes missing. Third, we could solve most of the foregoing problems with a _pair_ of new macros. Call 'em `CS` and `CE`. Two drawbacks to that: (a) it clashes horribly with man(7)'s existing design, making the package harder to learn; and (b) without font alternation macros, a lot more people are going to have to learn how to use `\c`, and that might be enough to kill the plan right there, even if we solved the problem of po4a aborting as soon as it sees one of these. https://github.com/mquinson/po4a/issues/527 Fourth, if you apply inline Courier to multiple words, how does the reader know where the boundaries of the "literal text" are when the material is copied-and-pasted? Granted, this is a problem with bold and (less often) italic styling too, which is why I recommend that man page authors use quotation. But that faces a headwind as well, some of the original man(7)'s own making but fanned up to gale strength by GNU/Linux distributors' own decisions. https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/tmac/groff_man.7.man.in?h=1.24.1#n4697 So, no, not 100% opposed, but maybe 95%. Who has a solution to all of the foregoing problems? [4] By contrast, an implicit indentation _is_ achievable, because we already know from the structure of the macro call whether the user wants the "prevailing indent" or not. If they give `TP` an argument, or `IP` a second one, we know that they want to override that prevailing indent. Thus, `LS` can _set_ the prevailing indent.
signature.asc
Description: PGP signature
