preferred /proc/<pid>/xxx style?

preferred /proc/<pid>/xxx style?

[Mike Frysinger]

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

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

[Alejandro Colomar]

[-- 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 --]

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

[G. Branden Robinson]

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

Hi Alex & Mike,

Alex, you beat me to this one...

At 2022-12-09T20:43:21+0100, Alejandro Colomar wrote:
> > 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.

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

> 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

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

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

words (and commands) that I learnt because of Branden (was: preferred /proc/<pid>/xxx style?)

[Alejandro Colomar]

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

Hi Branden!

On 12/9/22 22:03, G. Branden Robinson wrote:
> Hi Alex & Mike,
> 
> Alex, you beat me to this one...
> 
> At 2022-12-09T20:43:21+0100, Alejandro Colomar wrote:
>>> 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.

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


-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: words (and commands) that I learnt because of Branden (was: preferred /proc/<pid>/xxx style?)

[Deri]

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:  dereliction
> 
> And 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?)

[hbezemer]

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
John Gardner <gardnerjohng@gmail.com> wrote:

> >
> >  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.
> 
> 
> On Sat, 10 Dec 2022 at 09:10, Deri <deri@chuzzlewit.myzen.co.uk> wrote:
> 
> > 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:  dereliction
> > >
> > > And 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?)

[G. Branden Robinson]

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

At 2022-12-09T22:10:34+0000, Deri wrote:
> 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:  dereliction
> > 
> > And yes, dereliction has a definition compatible with your use.
[...]
> 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]