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

On 11/19/25 04:45, G. Branden Robinson wrote:
> * find/find.1:
> * locate/locate.1: Use `HP` hanging paragraph macro to indent
>    non-initial lines of synopsis.  Temporarily disable adjustment.
> 
> An alternative approach would be to use groff man(7)'s `SY` and `YS`
> extension macros; each man page would then need to define local versions
> for portability to DWB 3.3, Plan 9, and Solaris 10 troffs.
> ---
>   find/find.1     | 5 +++++
>   locate/locate.1 | 5 +++++
>   2 files changed, 10 insertions(+)
> 
> diff --git a/find/find.1 b/find/find.1
> index 21036c89..191a6638 100644
> --- a/find/find.1
> +++ b/find/find.1
> @@ -3,6 +3,9 @@
>   .SH NAME
>   find \- search for files in a directory hierarchy
>   .SH SYNOPSIS
> +.HP

This triggers a 'make check' error:

   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

Should we replace .HP by a simple .P?
Or better just remove it?

> +.nr sA \n(.j \" Save the adjustment mode.
> +.na
>   .B find
>   .RB [ \-H ]
>   .RB [ \-L ]
> @@ -13,6 +16,8 @@ .SH SYNOPSIS
>   .IR level ]
>   .RI [ starting-point .\|.\|.]\&
>   .RI [ expression ]
> +.ad \n(sA \" Restore the adjustment mode.
> +.rr sA
>   .
>   .SH DESCRIPTION
>   This manual page
> diff --git a/locate/locate.1 b/locate/locate.1
> index c366daa2..25571fed 100644
> --- a/locate/locate.1
> +++ b/locate/locate.1
> @@ -11,6 +11,9 @@ .SH NAME
>   locate \- list files in databases that match a pattern
>   .
>   .SH SYNOPSIS
> +.HP

Likewise here:

   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.

> +.nr sA \n(.j \" Save the adjustment mode.
> +.na
>   .B locate
>   .RB [ \-d
>   .I path
> @@ -69,6 +72,8 @@ .SH SYNOPSIS
>   .BR \*%\-\-print ]
>   .RB \*%[ \-\-help ]
>   .IR pattern .\|.\|.
> +.ad \n(sA \" Restore the adjustment mode.
> +.rr sA
>   .
>   .SH DESCRIPTION
>   This manual page