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

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]