Hi Branden, On 2026-05-08T15:41:18-0500, G. Branden Robinson wrote: > [adding Stephen, Alejandro, and Chet to CC] > > Hi Pádraig, > > 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. > > > > * man/help2man: Use .PD 0 (Paragraph Distance) > > to avoid extraneous blank lines within .TP delineated tables. > > Also use explicit widths with .TP in such tables, > > to preserve the alignment from the --help output. > > 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] > > I think the reasons for the deprecation are sound; the macro is: > > 1. too powerful--you can specify an inter-paragraph distance of 100 > inches with it, for instance; > 2. insufficiently powerful--some man(1) programs will pipe the output > through "cat -s" or equivalent, "squeezing" multiple blank lines > down to one; > 3. too far to the wrong end of the "presentation/semantics" continuum; > and > 4. inaccurately expressive of what _every_ person employing this macro, > so far as I have observed, has communicated that they want, which is > a more compact way to present lists--especially lengthy lists with > mostly short items and descriptions thereof. > > I would therefore like to propose and solicit support for an idea I had > a few years ago.[2] In fact I've already been quietly piloting a more > limited form of it in groff for some years.[3]
IIRC, I agreed to it back then. It still seems reasonable to me. > I propose two new macros for groff man(7), `LS` and `LE`, to mark the Yes, I seem to remember those names. :) > 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_. > > That last part is important. The bash(1) man page maintainer has to > tediously keep track of their `PD` macro calls, because sometimes the > "body" of a definition requires multiple paragraphs with the same > indentation even though the surrounding list context is "compact". That > means you have to remember to restore the inter-paragraph spacing with > an argumentless `.PD` and then shut it off again with `.PD 0` before > starting the next list item. This is tedious and error-prone. > > Why not let the man(7) package handle the tedium for you? > > Fleshing out my sketch of the design, here's a synopsis. > > .LS type [compactness [indentation]] > Start a list. type is one of "itemized", "enumerated", or > "definition". compactness is a Boolean value indicating > that inter-paragraph spacing between list items should be > suppressed. indentation specifies an indentation amount > for the body of each list item; it is then unnecessary to > specify this argument to the list item macros. Use IP with > a mark argument to represent an itemized or enumerated list > item, and TP for a definition list item. Use IP without > arguments to associate successive paragraphs with an > existing list item; to these, inter-paragraph spacing > applies even in compact lists. LS can be nested. > > .LE End the list corresponding to the most recent LS call. Pedantically, the description of LE is incorrect, I think. I'd say it's the most recent _not-yet-ended_ LS call. But I think everyone would understand the right thing from that text, and it's shorter, so maybe it's good. > Still to be determined: when to automatically end all active lists. > This would have to be done at (sub)sectioning macro calls (and the end > of the document) at the latest. Yes. > Possibly also at "regular" paragraphing > macro calls, I don't think so. This would unnecessarily preclude having multi-paragraph list elements. And in general, it would be a bad idea to leave too many unterminated LS, so why promote that? Let's force users to terminate their stuff. > but I'm leaning against that as it would frustrate an > alternative approach to setting the bodies of marked or tagged > paragraphs that is already supported and documented.[4] > > Another advantage, one that would need further work, is that the tags of > `TP` macro calls in definition lists could have bookmarks automatically > generated for them with supporting output devices. That means PDF and > HTML, and--perhaps less obviously--terminals, if groff can hammer out an > interface with man-db man(1) such that groff generates a ctags file that > man(1) can locate and pass it to a supporting pager; less(1) already > supports this: see its `-t` option and `t` and `T` commands. > > I get this impression this would make all of your lives easier. > > What do you think? If I build it, will you come? ;-) Yup! :) Have a lovely night! Alex > If there's consensus for this, I'll start a thread on the groff list as > well. Stephen, it is okay for me to quote your recent private mail to > me on this subject? > > Regards, > Branden > > [1] In groff 1.23, `CHECKSTYLE` wasn't documented. In 1.24, it is. > > groff_man(7): > > Options > ... > -rCHECKSTYLE=n > Report problems with usage of this macro package exhibited > by the input at verbosity level n, where n is an integer > in the range 0–3, inclusive; 0 disables the messages and > is the default. This feature is a development and > debugging aid for man page maintainers; the problems > diagnosed, and range and meanings of the supported levels, > are subject to change. > > [2] https://lists.gnu.org/archive/html/groff/2022-12/msg00075.html > > [3] > https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/man/groff.7.man?h=1.24.1#n245 > I'd have links to when I added these page-local macros back in 2022, > but cgit.git.savannah.gnu.org is alternately dog-slow or throwing > HTTP 502 errors at me. Sorry. Documentary support available later > on request. > > [4] > > groff_man_style(7): > > Notes > Some tips on composing and troubleshooting your man pages follow. > ... > Another approach to tagged paragraphs places an RS call > immediately after the tag; this also forces a break regardless of > the tag’s width, which some authors prefer. Follow‐up paragraphs > under the tag can then be set with P instead of IP. Remember to > use RE to end the indented region before starting the next tagged > paragraph (at the appropriate nesting level). -- <https://www.alejandro-colomar.es>
signature.asc
Description: PGP signature
