[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]
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_.
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.
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. Possibly also at "regular" paragraphing
macro calls, 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? ;-)
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).
signature.asc
Description: PGP signature
