Issue in man page namespaces.7

Issue in man page namespaces.7

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:   /proc/sys/user → I</proc/sys/user>

"The /proc/sys/user directory"

Issue in man page namespaces.7

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    /proc/sys/user → I</proc/sys/user>

"The /proc/sys/user directory"

Issue in man page namespaces.7

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    /proc/sys/user → I</proc/sys/user>

"The /proc/sys/user directory"

Re: Issue in man page namespaces.7

[Alejandro Colomar]

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

Hi Branden,

On 1/22/23 20:31, Helge Kreutzmann wrote:
> Without further ado, the following was found:
> 
> Issue:    /proc/sys/user → I</proc/sys/user>

Please review the following patch.

Cheers,

Alex
> 
> "The /proc/sys/user directory"

---

diff --git a/man7/namespaces.7 b/man7/namespaces.7
index 5b11f6186..8811f9af9 100644
--- a/man7/namespaces.7
+++ b/man7/namespaces.7
@@ -270,7 +270,7 @@ .SS The /proc/[pid]/ns/ directory
  .\"
  .\" ==================== The /proc/sys/user directory ====================
  .\"
-.SS The /proc/sys/user directory
+.SS The \fI/proc/sys/user\fR directory
  The files in the
  .I /proc/sys/user
  directory (which is present since Linux 4.9) expose limits


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

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

Re: Issue in man page namespaces.7

[G. Branden Robinson]

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

Hi Alex,

At 2023-01-22T21:17:40+0100, Alejandro Colomar wrote:
> On 1/22/23 20:31, Helge Kreutzmann wrote:
> > Without further ado, the following was found:
> > 
> > Issue:    /proc/sys/user → I</proc/sys/user>
> 
> Please review the following patch.
> --- a/man7/namespaces.7
> +++ b/man7/namespaces.7
> @@ -270,7 +270,7 @@ .SS The /proc/[pid]/ns/ directory
>  .\"
>  .\" ==================== The /proc/sys/user directory ====================
>  .\"
> -.SS The /proc/sys/user directory
> +.SS The \fI/proc/sys/user\fR directory
>  The files in the
>  .I /proc/sys/user
>  directory (which is present since Linux 4.9) expose limits

I would use \fP instead of \fR, this way you return to the "previous"
font, not the roman style in the current family.  This is important in
(sub)section headings because they are normally set in boldface, so
switching to roman explicitly would unintentionally put "directory" on a
diet (i.e., cause it to lose [stroke] weight).

With that correction, I'm +1.

But I would also quote multi-word arguments to _any_ man(7) macro.

Thus:

> +.SS "The \fI/proc/sys/user\fP directory"

Equivalently, if one doesn't care about portability to ancient
formatters...

> +.SS "The \f[I]/proc/sys/user\f[] directory"

...will suffice.

(One might reasonably wonder why "\fI" doesn't cause a loss of stroke
weight, too.  In groff 1.22.4 and earlier, it does.  In groff 1.23.0,
the man(7) package remaps the "I" to "BI".)

Regards,
Branden

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

Re: Issue in man page namespaces.7

[Alejandro Colomar]

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

Hi Branden,

On 1/22/23 22:02, G. Branden Robinson wrote:
> I would use \fP instead of \fR, this way you return to the "previous"

Ahh, yes, thanks for catching that!  Sleeping 3 hours is definitely not good for 
the brain :P

> font, not the roman style in the current family.  This is important in
> (sub)section headings because they are normally set in boldface, so
> switching to roman explicitly would unintentionally put "directory" on a
> diet (i.e., cause it to lose [stroke] weight).
> 
> With that correction, I'm +1.
> 
> But I would also quote multi-word arguments to _any_ man(7) macro.

Why is it?  I remember you mentioned that, but what's the win?

> 
> Thus:
> 
>> +.SS "The \fI/proc/sys/user\fP directory"
> 
> Equivalently, if one doesn't care about portability to ancient
> formatters...
> 
>> +.SS "The \f[I]/proc/sys/user\f[] directory"

Interesting.  I'll consider that for the long term.  However, for now I'll keep 
\fP style.

> 
> ...will suffice.
> 
> (One might reasonably wonder why "\fI" doesn't cause a loss of stroke
> weight, too.  In groff 1.22.4 and earlier, it does.  In groff 1.23.0,
> the man(7) package remaps the "I" to "BI".)
> 
> Regards,
> Branden

Cheers,

Alex

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

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

Re: Issue in man page namespaces.7

[G. Branden Robinson]

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

Hi Alex,

At 2023-01-22T22:11:06+0100, Alejandro Colomar wrote:
> On 1/22/23 22:02, G. Branden Robinson wrote:
> > I would use \fP instead of \fR, this way you return to the
> > "previous"
> 
> Ahh, yes, thanks for catching that!  Sleeping 3 hours is definitely
> not good for the brain :P

Certainly not.  Good self-care keeps the engineer's brain supple.  :)

> > But I would also quote multi-word arguments to _any_ man(7) macro.
> 
> Why is it?  I remember you mentioned that, but what's the win?

It's more portable.  AT&T troff and its descendants (except for Heirloom
Doctools troff) support only 9 macro arguments at most.  Worse, the AT&T
man(7) macros and most descendants support only _six_.

When doing maintenance, it's easy to forget that.

But even in a groff-only world, I would recommend the practice as good
style because it leaves room to expand the syntax of some macros.

Admittedly I don't see any promising places where we might do that in
man(7) to any macros that already accept formattable text as arguments.

I still think it's a good idea style-wise because the man(7) author
should keep the count of words following a macro call in mind,
especially if they want to effectively use the font style alternation
macros (.BI, .BR, .IB, .IR, .RB, .RI).

In mdoc(7) argument count makes a difference due to the package's
unique recursive argument interpretation feature.  Still, while this was
a measurable phenomenon 30 years ago, it may not be today.  (The whole
reason "cat pages" exist in man(1) is that the time spent by the
formatter on a document was significant then; it is negligible now.)

I will admit right now that I don't follow this rule rigidly myself in
groff's man pages when it comes to `I` calls.  I may fix that at some
point.  (If I did so, it would align doc/ms.ms better with groff_ms(7).)

So it's not a big deal, but there's so much ignorance about man(7) out
there that it's a goal of mine to make the language easier to acquire.

> > > +.SS "The \f[I]/proc/sys/user\f[] directory"
> 
> Interesting.  I'll consider that for the long term.  However, for now
> I'll keep \fP style.

No worries.

Regards,
Branden

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

Re: Issue in man page namespaces.7

[Alex Colomar]

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

Hi Branden,

On 1/23/23 09:45, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-01-22T22:11:06+0100, Alejandro Colomar wrote:
>> On 1/22/23 22:02, G. Branden Robinson wrote:
>>> I would use \fP instead of \fR, this way you return to the
>>> "previous"
>>
>> Ahh, yes, thanks for catching that!  Sleeping 3 hours is definitely
>> not good for the brain :P
> 
> Certainly not.  Good self-care keeps the engineer's brain supple.  :)

Yeah, but playing Munchkin till you realize it's 6 AM is soo fun :P

<https://munchkin.game/>

> 
>>> But I would also quote multi-word arguments to _any_ man(7) macro.
>>
>> Why is it?  I remember you mentioned that, but what's the win?
> 
> It's more portable.  AT&T troff and its descendants (except for Heirloom
> Doctools troff) support only 9 macro arguments at most.  Worse, the AT&T
> man(7) macros and most descendants support only _six_.

It's interesting to combine an advice for portability with a suggestion 
for when you don't care about the portability :P

.SS "The \f[I]/proc/sys/user\f[] directory"

> 
> When doing maintenance, it's easy to forget that.
> 
> But even in a groff-only world, I would recommend the practice as good
> style because it leaves room to expand the syntax of some macros.

Yeah, it's mostly groff/mandoc world here, since I plan to use .MR soon.

> 
> Admittedly I don't see any promising places where we might do that in
> man(7) to any macros that already accept formattable text as arguments.
> 
> I still think it's a good idea style-wise because the man(7) author
> should keep the count of words following a macro call in mind,
> especially if they want to effectively use the font style alternation
> macros (.BI, .BR, .IB, .IR, .RB, .RI).

I do avoid '"' when unnecessary for font macros, so I prefer not doing 
it here either (at least not for this reason).

> 
> In mdoc(7) argument count makes a difference due to the package's
> unique recursive argument interpretation feature.  Still, while this was
> a measurable phenomenon 30 years ago, it may not be today.  (The whole
> reason "cat pages" exist in man(1) is that the time spent by the
> formatter on a document was significant then; it is negligible now.)
> 
> I will admit right now that I don't follow this rule rigidly myself in
> groff's man pages when it comes to `I` calls.  I may fix that at some
> point.  (If I did so, it would align doc/ms.ms better with groff_ms(7).)
> 
> So it's not a big deal, but there's so much ignorance about man(7) out
> there that it's a goal of mine to make the language easier to acquire.
> 
>>>> +.SS "The \f[I]/proc/sys/user\f[] directory"
>>
>> Interesting.  I'll consider that for the long term.  However, for now
>> I'll keep \fP style.
> 
> No worries.
> 
> Regards,
> Branden

Cheers,

Alex

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


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