preferred /proc//xxx style?

Mike Frysinger
2022-12-09T09:41:11Z

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

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:
> 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.
> 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

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