Hi Mike! On 12/9/22 10:41, Mike Frysinger wrote:
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.
That's correct.
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.
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 /fdinfoUsing '.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.".
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_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
if we look a bit further, using .IR seems inconsistent.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 Formatting conventions for manual pages describing commands For manual pages that describe a command (...), the arguments are always specified using italics Formatting 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 :) -- <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
