Re: [PATCH] man/man3/getopt.3: Restore angle brackets.

G. Branden Robinson
2025-11-26T02:05:27Z

[-- Attachment #1: Type: text/plain, Size: 3620 bytes --]

Hi Collin,

At 2025-11-25T17:15:39-0800, Collin Funk wrote:
> While looking at 'man -S 3 getopt' the underlining under PID looked
> strange to me. These angle brackets were replaced with spaces in
> commit bc34639b160d8bd3d3daf748e8a54bc1df429901 for some reason.
>
> Signed-off-by: Collin Funk <collin.funk1@gmail.com>
> ---
> man/man3/getopt.3 | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/man/man3/getopt.3 b/man/man3/getopt.3
> index 8495719af..1e4f697c0 100644
> --- a/man/man3/getopt.3
> +++ b/man/man3/getopt.3
> @@ -415,7 +415,7 @@ .SH HISTORY
> .P
> Very old versions of glibc were affected by a
> .UR https://\:sourceware.org/\:git/\:?p=glibc.git;a=commitdiff;h=bf079e19f50d64aa5e05
> -.BI _ PID _GNU_nonoption_argv_flags_
> +.BI _<PID>_GNU_nonoption_argv_flags_
> environment variable
> .UE .

Syntactically, if that's what you want, there's no point calling `BI`
anymore because only one macro argument now remains. groff man's
"CHECKSTYLE" feature will complain about this.[1] Just use `B`.

Semantically, I expect "PID" was placed in italics (underlined on
traditional terminals, but consider MANROFFOPT=-P-i in your
environment) because it was a mutable parameter, not a literal part of
the environment variable's name.

Personally, I find both the old and the new renderings inconsistent with
Unix man page tradition.

groff_man_style(7):
Font style macros
...
Because font styles are presentational rather than semantic,
conflicting traditions have arisen regarding which font styles
should be used to mark file or path names, environment variables,
and inlined literals.
...
Use italics for file and path names, for environment
variables, for C data types, for enumeration or preprocessor
constants in C, for variant (user‐replaceable) portions of
syntax synopses, for the first occurrence (only) of a
technical concept being introduced, for names of journals
and of literary works longer than an article, and anywhere a
parameter requiring replacement by the user is encountered.
An exception involves variant text in a context already
typeset in italics, such as file or path names with
replaceable components; in such cases, follow the convention
of mathematical typography: set the file or path name in
italics as usual but use roman for the variant part (see IR
and RI below), and italics again in running roman text when
referring to the variant material.

So I'd say:

> -.BI _ PID _GNU_nonoption_argv_flags_
> +.IR _ PID _GNU_nonoption_argv_flags_

Regards,
Branden

[1] groff_man(7) in the forthcoming 1.24.0 release:

Options
The following groff options set registers (with -r) and strings
(with -d) recognized and used by the man macro package. To ensure
rendering consistent with output device capabilities and reader
preferences, man pages should never manipulate them.
...
-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.