preferred /proc/<pid>/xxx style?
while browsing time_namespaces(7), i noticed it's inconsistent when it comes to styling of /proc/<pid>/paths. it uses the styles:
* .IR /proc/ pid /ns/time_for_children
* .I /proc/PID/timens_offsets
grepping the tree turns up more:
* .I /proc/<pid>/maps
* .I /proc/[pid]/status
it seems that the tree is moving towards the first style. 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. in the terminal this yields colored & underlined text except for the "pid" which is just plain text like the rest.
commit 1ae6b2c7b818e5d8804cf8d3abfdb6fba32119db made a large change recently to proc(5) to use .IR, but with no explanation in the commit message other than to satisfy a linter, and running that linter locally doesn't seem to show any warnings when using the previous /proc/[pid] style.
the man-pages(7) guidance doesn't covert this afaict. it has:
Quoted 2 lines
Formatting conventions (general)
Filenames (whether pathnames, or references to header files) are always in italics ...
that implies it should be only in italics.
if we look a bit further, using .IR seems inconsistent.
Quoted 10 lines
SYNOPSIS
For commands, this shows the syntax of the command and its arguments (including options); boldface is used for as-is text and italics are used to indicate replaceable argumentsFormatting conventions for manual pages describing commands
For manual pages that describe a command (...), the arguments are always specified using italicsFormatting conventions for manual pages describing functions
For manual pages that describe functions (...), the arguments are always specified using italics, even in the SYNOPSIS section, where the rest of the function is specified in bold:
-mike
Hi Mike!
Quoted 10 lines · Mike Frysinger
while browsing
time_namespaces(7), i noticed it's inconsistent when it comes to styling of /proc/<pid>/paths. it uses the styles:
* .IR/proc/pid /ns/time_for_children
* .I/proc/PID/timens_offsetsgrepping the tree turns up more:
* .I /proc/<pid>/maps
* .I /proc/[pid]/statusit seems that the tree is moving towards the first style.
That's correct.
Quoted 9 lines
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. in the terminal this yields colored & underlined text except for the "pid" which is just plain text like the rest.commit
1ae6b2c7b818e5d8804cf8d3abfdb6fba32119dbmade a large change recently to proc(5) to use .IR, but with no explanation in the commit message other than to satisfy a linter, and running that linter locally doesn't seem to show any warnings when using the previous /proc/[pid] style.
You probably don't get the linter warnings because I think that requires groff-1.23.0 (still unreleased; hopefully available soon).
We're talking about the following diff:
-.IR /proc/[pid]/fdinfo
+.IR /proc/ pid /fdinfo
Using '.IR' with a single argument results in a warning, since it would be better written as '.I'. However, I decided to apply the style fix instead of simplfy fixing the warning. I should have been more detailed in the commit message. I only covered it with "Plus some other found in the process.".
Quoted 5 lines
the man-pages(7) guidance doesn't covert this afaict. it has:
Quoted 2 lines
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_man_style(7):
.I [text]
...
Use italics for file and path names, for environment variables, for C data types, 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 in‐ troduced, 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 variable text in a context that is already marked up in italics, such as file or path names with variable 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 variable part (see .IR and .RI below), and italics again in running roman text when referring to the variable material.
I marked the start of the important part.
I will some day make it consistent across all pages.
Cheers,
Alex
Quoted 6 lines
if we look a bit further, using .IR seems inconsistent.
Quoted 4 lines
SYNOPSIS
For commands, this shows the syntax of the command and its arguments (including options); boldface is used for as-is text and italics are used to indicate replaceable arguments
Quoted 7 lines
Quoted 6 lines
Formatting conventions for manual pages describing commands
For manual pages that describe a command (...), the arguments are always specified using italicsFormatting conventions for manual pages describing functions
For manual pages that describe functions (...), the arguments are always specified using italics, even in the SYNOPSIS section, where the rest of the function is specified in bold:-mike
P.S.: Please CC me :)
Signature · 1 line
<http://www.alejandro-colomar.es/>
Hi Alex & Mike,
Alex, you beat me to this one...
Quoted 2 lines · Alejandro Colomar
Quoted 2 lines
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.
Quoted 2 lines
Quoted 2 lines
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.
Quoted 2 lines
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
Quoted 4 lines
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.
Quoted 9 lines
Quoted 5 lines
the man-pages(7) guidance doesn't covert this afaict. it has:
Quoted 3 lines
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 ofgroff_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."
words (and commands) that I learnt because of Branden (was: preferred /proc/<pid>/xxx style?)
Hi Branden!
Quoted 11 lines · G. Branden Robinson
Hi Alex & Mike,
Alex, you beat me to this one...
Quoted 2 lines · Alejandro Colomar
Quoted 2 lines
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
Quoted 6 lines
/var/log/epidemic/pid/portand 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.
Your emails are the reason I know and often use dict(1). Lol.
$ dict deriliction No definitions found for "deriliction", perhaps you mean: gcide: Dereliction wn: dereliction moby-thesaurus: dereliction
And yes, dereliction has a definition compatible with your use.
Cheers,
Alex
Signature · 1 line
<http://www.alejandro-colomar.es/>
Re: words (and commands) that I learnt because of Branden (was: preferred /proc/<pid>/xxx style?)
Quoted 11 lines · On Friday, 9 December 2022 21:09:57 GMT Alejandro Colomar wrote:
$ dict deriliction No definitions found for "deriliction", perhaps you mean: gcide: Dereliction wn: dereliction moby-thesaurus: derelictionAnd yes, dereliction has a definition compatible with your use.
Cheers,
Alex
If deriliction was a word I think it would be unsavoury. :-)
Cheers
Deri
A message that is not in the archive (sent off-list or not yet received): CAGcdajfWk+=xR3UfAnNri0F7OL0mFJ4xsp=sQoWLo_-_G5wcBA@mail.gmail.com
Re: words (and commands) that I learnt because of Branden (was: preferred /proc/<pid>/xxx style?)
This thread made my morning and I fully agree: Love to read the elaborate delicately humourful e-mails.
In Dutch there's a saying: Schrijvers zijn blijvers, which can be loosy translated as: Who writes, will be remembered. True in this case.
Regards,
Hans
Quoted 53 lines · John Gardner
Quoted 2 lines
Your emails are the reason I know and often use dict(1). Lol.
Branden's e-mails are the reason I consult the Oxford English dictionary far more often than I'm comfortable admitting. Either I'm learning obscure words I know I'll never remember when I need them,[1] <#snarky-footnote-1> or I'm asking myself *"wait, what does *X* mean, again…?"*, chiefly because I don't read enough (non-technical) literature. :-(
And even when he *isn't* filling my notes file I use to horde definitions of fancy-sounding words I probably won't ever use, I'm always admiring how he manages to balance cheeky humour with informative, expressive writing that brings the Camel Book's writing style to mind (seriously, when discussing dry topics like typesetting and Unix orthography, a sense of humour makes digestion *so* much easier).
Also, "*vituperator*" still reigns as my favourite Brandenism[2] <#if-you-can-read-this-gmail-forgot-to-sanitise-my-fragment-identifier> to date.
[1] Or awkwardly pigeonhole them into discussions when I do.
[2] An unintentional extension to a reader's vocabulary, often when you least expect it.
[3] There's no third footnote, I just wanted to point out how infectious Branden's writing style is.Quoted 23 lines · Deri
Quoted 11 lines · On Friday, 9 December 2022 21:09:57 GMT Alejandro Colomar wrote:
$ dict deriliction No definitions found for "deriliction", perhaps you mean: gcide: Dereliction wn: dereliction moby-thesaurus: derelictionAnd yes, dereliction has a definition compatible with your use.
Cheers,
Alex
If deriliction was a word I think it would be unsavoury. :-)
Cheers
Deri
Re: words (and commands) that I learnt because of Branden (was: preferred /proc/<pid>/xxx style?)
In reply to DeriQuoted 8 lines · Deri
Quoted 7 lines · On Friday, 9 December 2022 21:09:57 GMT Alejandro Colomar wrote:
$ dict deriliction No definitions found for "deriliction", perhaps you mean: gcide: Dereliction wn: dereliction moby-thesaurus: derelictionAnd yes, dereliction has a definition compatible with your use.
[...]
Quoted 1 line
If deriliction was a word I think it would be unsavoury. :-)
If nothing else can keep a person humble, one's own spelling errors will...
Regards,
Branden