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:

quoted

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

quoted

 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:

quoted

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