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
