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:
signature.asc
Description: PGP signature
