Hi Pádraig, At 2026-05-09T11:11:00+0100, Pádraig Brady wrote: > On 08/05/2026 21:41, G. Branden Robinson wrote: > > At 2026-05-08T20:17:32+0100, Pádraig Brady wrote: > > > This is useful in many man pages like date , dd, od, tr, ... > > > where there are tables presented, where extraneous lines > > > between each entry are best avoided. > > > groff man(7) has discouraged use of the `PD` macro since groff 1.20 > > (2009). In groff 1.23, it started warning of the macro's > > deprecation when the `CHECKSTYLE` feature is used.[1] > > Fair enough. .PD 0 seems more functional rather than cosmetic, so I > would have avoided deprecating 0 as a special case.
Documentarily, the deprecation decision was taken several years before my time. I joined groff development in 2017, and didn't contribute much except documentation revisions and bug fixes until 2020. That said, I certainly could have chosen to undo the deprecation, as I have in fact since done with the `HP` macro,[1] a documented feature of man(7) since McIlroy's original in 1979. (To be fair, `PD` is too.[2]) > > I propose two new macros for groff man(7), `LS` and `LE`, to mark > > the beginning and ends of lists. These would: > > > > A. map more straightforwardly to HTML `dl`, `ol`, and `ul` > > elements; > > B. be nestable; > > C. accept an optional argument to request that the list be rendered > > "compactly", meaning without inter-paragraph distance _between > > items_. > > Yes this higher level construct makes sense, especially as it's used > so often, and maps to other formats more easily. I've started implementing, and have a simplifying revision to make. I expect to omit the "enumerated" (`ol`) type, at least initially and possibly indefinitely, awaiting demand. The reason is that man(7) documents are responsible for managing their own enumerators, and it will add complexity to drop the already explicitly specified list marks from page content so that the HTML renderer can supply them. Fortunately, in frankness I seldom see enumerated lists in man page sources. Bulleted lists are much more common (even if not everyone realizes they have portable access to a bullet character), and definition lists overwhelmingly frequent. This won't mean you suddenly can't have enumerated lists in man pages; it simply means that you'd mark them as "itemized" instead of "definition" lists in your `LS` calls. > Compat is the main consideration for me. I.e. we can use .PD 0 > everywhere now. We can adjust to LS/LE when available, I suppose > through a help2man option. I'm curious to see if you can have a belt-and-suspenders transition period. I wouldn't recommend that for a hand-maintained man page, but for a generator like help2man, it might make more sense. In principle, `.PD 0` and `.PD` control lines placed adjacently to `LS` and `LE` calls should be redundant at worst, and still do the right thing with formatters that know nothing of the new macros. I'm not certain of that yet--I need to check out a hard case like the Bash man page. My first piece of the implementation is in my working copy, and the groff(7) A/B compares identically when I rip out its page-local (and very simple) `LS` and `LE` calls, replacing them with calls of the new package extension macros. I'm attaching the diff that gets the ball rolling (still in rough form), plus a guinea pig man(7) document that tests list nesting and compaction, in source and rendered forms (using "nroff -man -T ascii"). The guinea pig works, and groff(7) works. Initial signs are good. > In general on compat if all man page consumers like mandoc etc. > support it, it seems like a good idea. Fingers crossed... Regards, Branden [1] https://github.com/GitMirroring/groff/commit/d483834af930eeec2cc9f77441af5d581fe18c50 [2] https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/man/man7/man.7
signature.asc
Description: PGP signature
