Re: [PATCH 08/42] doc: improve formatting of command synopses (1/2)

"G. Branden Robinson" <[email protected]> Tue, 30 Dec 2025 17:47:41 -0600
Newsgroups	gmane.comp.gnu.findutils.bugs
Message-ID	<20251230234741.nbc3cvms42fwt3j3@illithid>
Hi Bernhard,

At 2025-12-28T23:42:27+0100, Bernhard Voelker wrote:
> > Should we replace .HP by a simple .P?
> > Or better just remove it?
> 
> According to groff_man_style(7), the better replacement seems to be
> .TP,

What language in that man page is leading you to that conclusion?
There's a good chance the wording is mine,[1] and I should revise it to
foreclose an avenue for confusion.

> which also caters better for the hanging indentation of the lines
> following ...

I think that's coincidental, and with a shorter or longer command name
you'd be less satisfied with the result.

Example:
$ printf '.TH foo 1 2025-12-30 "groff test suite"\n.TP\n.B ls\n.RB [ \\-1aAbBcCdDfFgGhHiklLmnNoqQrRsStuUvxXZ ]\n' \
    | ~/groff-1.23.0/bin/nroff -rLL=72n -man
foo(1)                   General Commands Manual                  foo(1)

       ls     [-1aAbBcCdDfFgGhHiklLmnNoqQrRsStuUvxXZ]

groff test suite               2025‐12‐30                         foo(1)

Conversely, if the tag name is lengthy, the line breaks after the tag,
which doesn't resemble a "hanging paragraph" at all.

$ printf '.TH foo 1 2025-12-30 "groff test suite"\n.TP\n.B really\\-long\\-command\\-name\n.RB [ \\-1aAbBcCdDfFgGhHiklLmnNoqQrRsStuUvxXZ ]\n' \
    | ~/groff-1.23.0/bin/nroff -rLL=72n -man
foo(1)                   General Commands Manual                  foo(1)

       really-long-command-name
              [-1aAbBcCdDfFgGhHiklLmnNoqQrRsStuUvxXZ]

groff test suite               2025‐12‐30                         foo(1)

(One _can_ specify the indentation that a `TP` paragraph uses, but this
can be tedious to maintain,[2] so neither I nor mandoc(1) maintainer
Ingo Schwarze recommend it.)

I also think that Eric Raymond proclaimed the deprecation of the `HP`
macro without sufficiently thinking through use cases, and/or announced
it premised on an overestimate of how swiftly the world would rush to
adopt groff's `SY` and `YS` extensions to man(7).  (I can't find any
evidence that this deprecation was discussed on the groff@gnu list.)

> >     an.tmac:./locate.1:18: style: use of deprecated macro: .HP
> >     make[3]: *** [Makefile:3287: findutils-check-manpages] Error 1
> >     make[3]: Target 'check-local' not remade because of errors.
> 
> ... which matters at least here in locate.1.

I understand not wanting to go to the trouble of working around this
deprecation warning, especially since it will go away on its own in
groff 1.24.0 anyway.

Maybe the best path is to use `TP` for now, then switch to `HP` (or
page-locally defined `SY` and `YS`) in the future when you feel groff
1.24 has sufficiently supplanted 1.23 in deployed systems of interest to
the findutils project.

Thoughts?

Regards,
Branden

[1] https://cgit.git.savannah.gnu.org/cgit/groff.git/log/tmac/groff_man.7.man.in?h=1.23.0

[2] I can't find it right now, I had an exchange with Alex Colomar,
    Linux man-pages project maintainer, on this topic some years ago.
    In so doing I managed to dream up a sequence of text layout
    problems, solutions, and further problems that may have resembled
    those that drove Mike Lesk's development of the tbl(1) preprocessor
    at the Bell Labs CSRC.
signature.asc (application/pgp-signature, 833 B)