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

Hi Branden,

On 12/31/25 00:47, G. Branden Robinson wrote:
> 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.

My guess comes from groff_man_style(7), section "Horizontal and vertical spacing"
which repeatedly mentions:

   [...] .IP, .TP, and the deprecated .HP [...]

plus in the "Deprecated features" section:

   .HP [indentation]
       Set up a paragraph with a hanging left indentation.  The indentation argument,
       if present, is handled as with .TP.

I somehow read it like .HP is a related variant of '.TP'. :-)
>> 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.

The results with .TP for find.1 and locate.1 are fine, so I'll go with it
for now.

> 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.

I'll add a FIXME 2027 to switch back to '.HP' then.
See attached patch on top of your series (not yet pushed).

> Thoughts?

Thanks for the insight!

Have a nice day ... and New Year,
Berny

From cf1f4aed9859f56f34bcd23a568d8d964a62fca9 Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <[email protected]>
Date: Mon, 29 Dec 2025 00:51:24 +0100
Subject: [PATCH] doc: avoid man-lint errors due to deprecated .HP macro

The .HP macro introduced only recently triggers a 'make check' errors:

   env GROFF=groff ../build-aux/man-lint.sh . find.1
   check_manpages_format_without_error_messages  (         find.1): OK
   check_manpages_with_groff_checkstyle_2        (         find.1): FAILED
   an.tmac:./find.1:23: style: use of deprecated macro: .HP
   make[3]: *** [Makefile:3112: findutils-check-manpages] Error 1

and

   env GROFF=groff ../build-aux/man-lint.sh . locate.1 updatedb.1 locatedb.5
   check_manpages_format_without_error_messages  (       locate.1): OK
   check_manpages_format_without_error_messages  (     updatedb.1): OK
   check_manpages_format_without_error_messages  (     locatedb.5): OK
   check_manpages_with_groff_checkstyle_2        (       locate.1): FAILED
   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.

The HP hanging paragraph would work nicely, but is marked as deprecated
in groff-1.23; the deprecations warning will disappear in groff-1.24.
Until then, use .TP instead to avoid the check errors.

* find/find.1: Change '.HP' to the '.TP' tagged paragraph macro.
Add a FIXME for 2027 to switch to .HP when groff-1.24 is more commonly
available.
* locate/locate.1: Likewise.
---
 find/find.1     | 2 +-
 locate/locate.1 | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/find/find.1 b/find/find.1
index d79ecfbc..31689b7a 100644
--- a/find/find.1
+++ b/find/find.1
@@ -20,7 +20,7 @@
 .SH NAME
 find \- search for files in a directory hierarchy
 .SH SYNOPSIS
-.HP
+.TP \" FIXME-2027: switch to .HP when groff-1.24 is more commonly available.
 .nr sA \n(.j \" Save the adjustment mode.
 .na
 .B find
diff --git a/locate/locate.1 b/locate/locate.1
index dbe9bf51..8dd7d4a9 100644
--- a/locate/locate.1
+++ b/locate/locate.1
@@ -15,7 +15,7 @@
 locate \- list files in databases that match a pattern
 .
 .SH SYNOPSIS
-.HP
+.TP \" FIXME-2027: switch to .HP when groff-1.24 is more commonly available.
 .nr sA \n(.j \" Save the adjustment mode.
 .na
 .B locate
-- 
2.51.1