Re: preferred /proc//xxx style?

G. Branden Robinson
2022-12-09T21:03:55Z

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

Hi Alex & Mike,

Alex, you beat me to this one...

At 2022-12-09T20:43:21+0100, Alejandro Colomar wrote:
> > personally i find that jarring to read because it's using italics
> > for the whole path except for the pid which has no styling at all.

I submit that it is more jarring to have to have a file specification
with mixed literal and variable components, such as

/var/log/epidemic/pid/port

and have it all marked up in the same typeface without a visual clue as
to which part is nonliteral. (Observe the ambiguity.) Yes, "the
experienced user will usually know [which part to replace]".[1] To rely
on that principle in documentation is a deriliction of duty.

Granted, Team Boldface All Literals has a point here, in that under
their convention you would _also_ be able to tell. But typographers
argue against excessive use of bold for a reason; when a document is
saturated with emphasis, the worth of emphasis decreases.

> > in the terminal this yields colored & underlined text except for the
> > "pid" which is just plain text like the rest.

Yes. This is a convention of mathematical typography.

> You probably don't get the linter warnings because I think that
> requires groff-1.23.0 (still unreleased; hopefully available soon).

[grimace]

People can always help by building it from Git and reporting any
problems.

https://git.savannah.gnu.org/cgit/groff.git/tree/INSTALL.REPO

> We're talking about the following diff:
>
> -.IR /proc/[pid]/fdinfo
> +.IR /proc/ pid /fdinfo

People have developed a number of ad hoc syntaxes for specifying
variable content when the context already demands the use of the
typeface that they normally employ for it. People throw brackets,
braces, and <> signs around with great abandon. But these are all
syntactically significant in the languages that Unix people use. In
formal documentation, as opposed to email, it's better to just switch
typefaces.

> > the man-pages(7) guidance doesn't covert this afaict. it has:
> > > Formatting conventions (general)
> > > Filenames (whether pathnames, or references to header files) are
> > > always in italics ...
> > that implies it should be only in italics.
>
> It isn't covered in man-pages(7), AFAIK. However, it is covered by
> groff_man_style(7) (also unreleased; maybe your version of
> groff_man(7) covers it):

groff 1.22.4's groff_man(7) page has similar text to what you quoted
(meaning this was one my earlier efforts to organize man page chaos).
So this guidance has been out there for nearly four years.

Use italics for file and path names, for environment
variables, for enumeration or preprocessor constants in
C, for variable (user-determined) portions of syntax
synopses, for the first occurrence only of a technical
concept being introduced, for names of works of software
(including commands and functions, but excluding names
of operating systems or their kernels), and anywhere a
parameter requiring replacement by the user is encoun-
tered. An exception involves variable text in a context
that is already marked up in italics, such as file or
path names with variable components; in such cases, fol-
low the convention of mathematical typography: set the
file or path name in italics as usual (see .IR below),
but use roman for the variable part, and italics again
in running roman text when referring to the variable ma-
terial.

Regards,
Branden

[1] For those who haven't had the joy of using ed(1), let me share an
old Unix-Hater's Handbook quote.

Ken Thompson has an automobile which he helped design. Unlike most
automobiles, it has neither speedometer, nor gas gauge, nor any of
the other numerous idiot lights which plague the modern driver.
Rather, if the driver makes a mistake, a giant "?" lights up in the
center of the dashboard. "The experienced driver," says Thompson,
"will usually know what’s wrong."

[-- Attachment #2: signature.asc --]