[PATCH v3 2/4] proc_pid_fdinfo.5: Make pid clearer in the name and 1st paragraph

[Ian Rogers]

On Sat, Nov 2, 2024 at 3:17 AM G. Branden Robinson
<g.branden.robinson at gmail.com> wrote:
>
> Hi Ian,
>
> At 2024-11-01T12:11:54-0700, Ian Rogers wrote:
> > diff --git a/man/man5/proc_pid_fdinfo.5 b/man/man5/proc_pid_fdinfo.5
> > index 87e6dbe56..935b54b4c 100644
> > --- a/man/man5/proc_pid_fdinfo.5
> > +++ b/man/man5/proc_pid_fdinfo.5
> [...]
> > -this is a subdirectory containing one entry for each file which the
> > -process has open, named by its file descriptor.
> > +this subdirectory contains one entry for each file that process
> > +.IR pid
> > +has open, named by its file descriptor.
>
> `IR` is better used with two or more arguments.
>
> As of groff 1.23 (July 2023), the man(7) package will warn you about
> problem like this if you ask it to.
>
> $ nroff -man -rCHECKSTYLE=1 /tmp/proc_pid_fdinfo_mini.5
> an.tmac:/tmp/proc_pid_fdinfo_mini.5:7: style: .IR expects at least 2 arguments, got 1
> proc_pid_fdinfo_mini(5)       File Formats Manual      proc_pid_fdinfo_mini(5)
>
> Name
>        /proc/pid/fdinfo - information about file descriptors
>
> Description
>        Text text text text.  One pid to rule them all and in the darkness bind
>        them.
>
> example                           2024‐11‐02           proc_pid_fdinfo_mini(5)
>
> I think Alex has a make(1) target that assists with running groff this
> way.
>
> groff_man(7):
>    Font style macros
>      ... It is often necessary to set
>      text in different styles without intervening space.  The macros
>      .BI, .BR, .IB, .IR, .RB, and .RI, where “B”, “I”, and “R”
>      indicate bold, italic, and roman, respectively, set their odd‐
>      and even‐numbered arguments in alternating styles, with no space
>      separating them.
>
> One reason to pay close attention to this point is that
>
> .IR foo bar
>
> formats as "foobar" (with "foo" in italics), whereas
>
> .I foo bar
>
> formats as "foo bar", with both words in italics.
>
> The different handling of the space is a common manifestation of error.

Thanks Branden, I think I'm taking away use ".I pid" rather than ".IR
pid" as the pattern of using ".I <name>" is used already in the file
and groff/nroff weird stuff, who knows. I'll change this for v5.

Ian