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

Alejandro Colomar
2025-11-26T11:57:51Z

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