Re: preferred /proc/<pid>/xxx style?

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 3949 bytes --]

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 /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.".


> 
> 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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]