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

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

[Collin Funk]

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 .
 .SH NOTES
-- 
2.52.0

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

[G. Branden Robinson]

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

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

[Alejandro Colomar]

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

Hi Collin, Branden,

On Tue, Nov 25, 2025 at 08:05:24PM -0600, G. Branden Robinson wrote:
> 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.

The underlining under 'PID' means that it's a variable part.  We use
that syntax in many pages.  This is documented in groff_man(3), as
Branden said.

However, you might have also noticed some dotted underline that extends
until the end of the line.  I think that's a bug somewhere --might be in
the terminal emulator, because I see it in xfce4-terminal(1) but not in
xterm(1)--.

> >  These angle brackets were replaced with spaces in
> > commit bc34639b160d8bd3d3daf748e8a54bc1df429901 for some reason.

[...]

We should have documented the formatting change in that commit message.
Or even better, apply it in a separate commit.

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

Correct.

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

We follow most of this paragraph, except for a few historical
differences:

Macro names and environment variables go in bold instead of italics.

(And possibly other similar things I'm forgetting.)

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

For now, I'll keep the current style, which is consistent in the
project.


Have a lovely day!
Alex

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



-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[Collin Funk]

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

Alejandro Colomar <alx@kernel.org> writes:

> On Tue, Nov 25, 2025 at 08:05:24PM -0600, G. Branden Robinson wrote:
>> 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.
>
> The underlining under 'PID' means that it's a variable part.  We use
> that syntax in many pages.  This is documented in groff_man(3), as
> Branden said.
>
> However, you might have also noticed some dotted underline that extends
> until the end of the line.  I think that's a bug somewhere --might be in
> the terminal emulator, because I see it in xfce4-terminal(1) but not in
> xterm(1)--.

I was using Gnome terminal and Emacs '(man "getopt.3")'.

>> > -.BI _ PID _GNU_nonoption_argv_flags_
>> > +.IR _ PID _GNU_nonoption_argv_flags_
>
> For now, I'll keep the current style, which is consistent in the
> project.

It still looks strange to me. But I guess I will survive. :)

Thank you both for the explanations.

Collin

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

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

[Alejandro Colomar]

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

Hi Collin,

On Wed, Nov 26, 2025 at 10:54:59PM -0800, Collin Funk wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> 
> > On Tue, Nov 25, 2025 at 08:05:24PM -0600, G. Branden Robinson wrote:
> >> 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.
> >
> > The underlining under 'PID' means that it's a variable part.  We use
> > that syntax in many pages.  This is documented in groff_man(3), as
> > Branden said.
> >
> > However, you might have also noticed some dotted underline that extends
> > until the end of the line.  I think that's a bug somewhere --might be in
> > the terminal emulator, because I see it in xfce4-terminal(1) but not in
> > xterm(1)--.
> 
> I was using Gnome terminal and Emacs '(man "getopt.3")'.

Hmmm, I can reproduce the dotted underline in gnome-terminal(1) too.
I don't know where's the bug.  It might be in both.  Branden, can you
have a look at it?  I guess you'll know better than me about these
issues.

> 
> >> > -.BI _ PID _GNU_nonoption_argv_flags_
> >> > +.IR _ PID _GNU_nonoption_argv_flags_
> >
> > For now, I'll keep the current style, which is consistent in the
> > project.
> 
> It still looks strange to me. But I guess I will survive. :)
> 
> Thank you both for the explanations.

You're welcome!  :)


Have a lovely day!
Alex

> 
> Collin



-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[G. Branden Robinson]

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

Hi Alex,

At 2025-11-27T13:12:26+0100, Alejandro Colomar wrote:
> On Wed, Nov 26, 2025 at 10:54:59PM -0800, Collin Funk wrote:
> > Alejandro Colomar <alx@kernel.org> writes:
> > > On Tue, Nov 25, 2025 at 08:05:24PM -0600, G. Branden Robinson wrote:
> > >> 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.
> > >
> > > The underlining under 'PID' means that it's a variable part.  We
> > > use that syntax in many pages.  This is documented in
> > > groff_man(3), as Branden said.
> > >
> > > However, you might have also noticed some dotted underline that
> > > extends until the end of the line.  I think that's a bug somewhere
> > > --might be in the terminal emulator, because I see it in
> > > xfce4-terminal(1) but not in xterm(1)--.
> > 
> > I was using Gnome terminal and Emacs '(man "getopt.3")'.
> 
> Hmmm, I can reproduce the dotted underline in gnome-terminal(1) too.
> I don't know where's the bug.  It might be in both.  Branden, can you
> have a look at it?  I guess you'll know better than me about these
> issues.

The dotted underline is how gnome-terminal(1) marks a hyperlink.  The
man page source explicitly formats this text as a hyperlink.

MP> .P
MP> Very old versions of glibc were affected by a
MP> .UR https://\:sourceware.org/\:git/\:?p=glibc.git;a=commitdiff;h=bf079e19f50d64aa5e05
MP> .BI _ PID _GNU_nonoption_argv_flags_
MP> environment variable
MP> .UE .

I observe a few cases of failure to protect literals from hyphenation in
this page, include the aforementioned literal.

       Very  old  versions  of  glibc  were  affected   by   a   _PID_GNU_nonop‐
       tion_argv_flags_ environment variable.

I'll prepare a patch.

Regards,
Branden

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

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

[Alejandro Colomar]

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

Hi Branden,

On Fri, Dec 19, 2025 at 10:25:03AM -0600, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2025-11-27T13:12:26+0100, Alejandro Colomar wrote:
> > On Wed, Nov 26, 2025 at 10:54:59PM -0800, Collin Funk wrote:
> > > Alejandro Colomar <alx@kernel.org> writes:
> > > > On Tue, Nov 25, 2025 at 08:05:24PM -0600, G. Branden Robinson wrote:
> > > >> 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.
> > > >
> > > > The underlining under 'PID' means that it's a variable part.  We
> > > > use that syntax in many pages.  This is documented in
> > > > groff_man(3), as Branden said.
> > > >
> > > > However, you might have also noticed some dotted underline that
> > > > extends until the end of the line.  I think that's a bug somewhere
> > > > --might be in the terminal emulator, because I see it in
> > > > xfce4-terminal(1) but not in xterm(1)--.
> > > 
> > > I was using Gnome terminal and Emacs '(man "getopt.3")'.
> > 
> > Hmmm, I can reproduce the dotted underline in gnome-terminal(1) too.
> > I don't know where's the bug.  It might be in both.  Branden, can you
> > have a look at it?  I guess you'll know better than me about these
> > issues.
> 
> The dotted underline is how gnome-terminal(1) marks a hyperlink.  The
> man page source explicitly formats this text as a hyperlink.
> 
> MP> .P
> MP> Very old versions of glibc were affected by a
> MP> .UR https://\:sourceware.org/\:git/\:?p=glibc.git;a=commitdiff;h=bf079e19f50d64aa5e05
> MP> .BI _ PID _GNU_nonoption_argv_flags_
> MP> environment variable
> MP> .UE .

I know this; however, for some reason I hadn't realized that we had a
hyperlink here.  My bad; a bug in my brain, it seems.  Thanks!  :)

> 
> I observe a few cases of failure to protect literals from hyphenation in
> this page, include the aforementioned literal.
> 
>        Very  old  versions  of  glibc  were  affected   by   a   _PID_GNU_nonop‐
>        tion_argv_flags_ environment variable.
> 
> I'll prepare a patch.

Thanks!


Have a lovely day!
Alex

> Regards,
> Branden



-- 
<https://www.alejandro-colomar.es>

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