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