Escaping whitespace

Escaping whitespace

[Alejandro Colomar (man-pages)]

Hi Michael,

While having a look at your latest commits,
I saw that there's a bit of inconsistency in escaping whitespace
(existing previous to the commit):

Sometimes it's [!\ (], and sometimes it's [! (].

Regards,

Alex

P.S.: I have queue.3 derivatives almost ready.

......

+++ b/man2/setpgid.2
@@ -88,8 +88,8 @@ Feature Test Macro Requirements for glibc (see
 .nf
     [These are available only before glibc 2.19]
     _BSD_SOURCE &&
-        !\ (_POSIX_SOURCE || _POSIX_C_SOURCE || _XOPEN_SOURCE ||
-            _GNU_SOURCE || _SVID_SOURCE)
+        !\ (_POSIX_SOURCE || _POSIX_C_SOURCE || _XOPEN_SOURCE
+            || _GNU_SOURCE || _SVID_SOURCE)
 .fi
 .SH DESCRIPTION
 All of these interfaces are available on Linux,
diff --git a/man2/wait4.2 b/man2/wait4.2
index faa63b30a..f45de09d1 100644
--- a/man2/wait4.2
+++ b/man2/wait4.2
@@ -53,9 +53,9 @@ Feature Test Macro Requirements for glibc (see
 .BR wait3 ():
 .nf
     Since glibc 2.26:
-        _DEFAULT_SOURCE ||
-        (_XOPEN_SOURCE\ >=\ 500 &&
-            ! (_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600))
+        _DEFAULT_SOURCE
+            || (_XOPEN_SOURCE\ >=\ 500 &&
+                ! (_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600))
     From glibc 2.19 to 2.25:
         _DEFAULT_SOURCE || _XOPEN_SOURCE\ >=\ 500
     Glibc 2.19 and earlier:



-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: Escaping whitespace

[Michael Kerrisk (man-pages)]

Hi Alex,

On 1/5/21 10:56 PM, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
> 
> While having a look at your latest commits,
> I saw that there's a bit of inconsistency in escaping whitespace
> (existing previous to the commit):
> 
> Sometimes it's [!\ (], and sometimes it's [! (].

Thanks for prodding me about this.

Yes, it's inconsistent. And given the use of .nf/.fi 
around the text blocks, escaping the spaces serves no
purpose. So I made a more radical fix; see commit
5c10d2c5e299011e34adb568737acfc8920fc27c

Thanks,

Michael
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: Escaping whitespace

[Alejandro Colomar (man-pages)]

Hi Michael,

On 1/6/21 1:51 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On 1/5/21 10:56 PM, Alejandro Colomar (man-pages) wrote:
>> Hi Michael,
>>
>> While having a look at your latest commits,
>> I saw that there's a bit of inconsistency in escaping whitespace
>> (existing previous to the commit):
>>
>> Sometimes it's [!\ (], and sometimes it's [! (].
> 
> Thanks for prodding me about this.
> 
> Yes, it's inconsistent. And given the use of .nf/.fi 
> around the text blocks, escaping the spaces serves no
> purpose. So I made a more radical fix; see commit
> 5c10d2c5e299011e34adb568737acfc8920fc27c

Nice!

After your following commit (422d5327a88fa89394100bafad69b21e50b26399),
I found that there are many such cases.  Just [[grep -rnI '\\ ' man?]]
and you'll see.  Some of them are valid, but a lot of them aren't.
What do you want to do about them?

Thanks,

Alex

> 
> Thanks,
> 
> Michael
>>
> 
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: Escaping whitespace

[Michael Kerrisk (man-pages)]

Hi Alex,

On Thu, 7 Jan 2021 at 18:11, Alejandro Colomar (man-pages)
<alx.manpages@gmail.com> wrote:
>
> Hi Michael,
>
> On 1/6/21 1:51 PM, Michael Kerrisk (man-pages) wrote:
> > Hi Alex,
> >
> > On 1/5/21 10:56 PM, Alejandro Colomar (man-pages) wrote:
> >> Hi Michael,
> >>
> >> While having a look at your latest commits,
> >> I saw that there's a bit of inconsistency in escaping whitespace
> >> (existing previous to the commit):
> >>
> >> Sometimes it's [!\ (], and sometimes it's [! (].
> >
> > Thanks for prodding me about this.
> >
> > Yes, it's inconsistent. And given the use of .nf/.fi
> > around the text blocks, escaping the spaces serves no
> > purpose. So I made a more radical fix; see commit
> > 5c10d2c5e299011e34adb568737acfc8920fc27c
>
> Nice!
>
> After your following commit (422d5327a88fa89394100bafad69b21e50b26399),
> I found that there are many such cases.  Just [[grep -rnI '\\ ' man?]]
> and you'll see.  Some of them are valid, but a lot of them aren't.

Can you point me at some examples?

Thanks,

Michael
-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: Escaping whitespace

[Alejandro Colomar (man-pages)]

On 1/8/21 12:29 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On Thu, 7 Jan 2021 at 18:11, Alejandro Colomar (man-pages)
> <alx.manpages@gmail.com> wrote:
>>
>> Hi Michael,
>>
>> On 1/6/21 1:51 PM, Michael Kerrisk (man-pages) wrote:
>>> Hi Alex,
>>>
>>> On 1/5/21 10:56 PM, Alejandro Colomar (man-pages) wrote:
>>>> Hi Michael,
>>>>
>>>> While having a look at your latest commits,
>>>> I saw that there's a bit of inconsistency in escaping whitespace
>>>> (existing previous to the commit):
>>>>
>>>> Sometimes it's [!\ (], and sometimes it's [! (].
>>>
>>> Thanks for prodding me about this.
>>>
>>> Yes, it's inconsistent. And given the use of .nf/.fi
>>> around the text blocks, escaping the spaces serves no
>>> purpose. So I made a more radical fix; see commit
>>> 5c10d2c5e299011e34adb568737acfc8920fc27c
>>
>> Nice!
>>
>> After your following commit (422d5327a88fa89394100bafad69b21e50b26399),
>> I found that there are many such cases.  Just [[grep -rnI '\\ ' man?]]
>> and you'll see.  Some of them are valid, but a lot of them aren't.
> 
> Can you point me at some examples?

A sample:

man3/envz_add.3:61:.RI ( *envz ,\  *envz_len )
<< this should be two lines
man3/xdr.3:184:.IR "long\ *" .
<< unnecessary
man3/scandir.3:277:.IR "const void\ *" .
<< unnecessary and self-inconsistent
man5/proc.5:1350:.RI ( "readelf\ \-l" ).
<< unnecessary
man7/symlink.7:424:.I "rm\ \-r slink directory"
<< unnecessary and self-inconsistent
man7/feature_test_macros.7:492:.IR "cc\ \-std=c99" ).
<< unnecessary
man8/ld.so.8:313:.IR "readelf\ \-n"
<< unnecessary

Maybe I'm missing something?

Thanks,

Alex

> 
> Thanks,
> 
> Michael
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: Escaping whitespace

[Alejandro Colomar (man-pages)]

On 1/8/21 12:49 PM, Alejandro Colomar (man-pages) wrote:
[...]
> man3/envz_add.3:61:.RI ( *envz ,\  *envz_len )
> << this should be two lines
Or [.RI ( *envz ", " *envz_len )]
Maybe it's better on one line like this
> man3/xdr.3:184:.IR "long\ *" .
> << unnecessary
> man3/scandir.3:277:.IR "const void\ *" .
> << unnecessary and self-inconsistent
> man5/proc.5:1350:.RI ( "readelf\ \-l" ).
> << unnecessary
> man7/symlink.7:424:.I "rm\ \-r slink directory"
> << unnecessary and self-inconsistent
> man7/feature_test_macros.7:492:.IR "cc\ \-std=c99" ).
> << unnecessary
> man8/ld.so.8:313:.IR "readelf\ \-n"
> << unnecessary
> 
> Maybe I'm missing something?
> 
> Thanks,
> 
> Alex
> 
>>
>> Thanks,
>>
>> Michael
>>
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: Escaping whitespace

[Michael Kerrisk (man-pages)]

On 1/8/21 12:49 PM, Alejandro Colomar (man-pages) wrote:
> 
> 
> On 1/8/21 12:29 PM, Michael Kerrisk (man-pages) wrote:
>> Hi Alex,
>>
>> On Thu, 7 Jan 2021 at 18:11, Alejandro Colomar (man-pages)
>> <alx.manpages@gmail.com> wrote:
>>>
>>> Hi Michael,
>>>
>>> On 1/6/21 1:51 PM, Michael Kerrisk (man-pages) wrote:
>>>> Hi Alex,
>>>>
>>>> On 1/5/21 10:56 PM, Alejandro Colomar (man-pages) wrote:
>>>>> Hi Michael,
>>>>>
>>>>> While having a look at your latest commits,
>>>>> I saw that there's a bit of inconsistency in escaping whitespace
>>>>> (existing previous to the commit):
>>>>>
>>>>> Sometimes it's [!\ (], and sometimes it's [! (].
>>>>
>>>> Thanks for prodding me about this.
>>>>
>>>> Yes, it's inconsistent. And given the use of .nf/.fi
>>>> around the text blocks, escaping the spaces serves no
>>>> purpose. So I made a more radical fix; see commit
>>>> 5c10d2c5e299011e34adb568737acfc8920fc27c
>>>
>>> Nice!
>>>
>>> After your following commit (422d5327a88fa89394100bafad69b21e50b26399),
>>> I found that there are many such cases.  Just [[grep -rnI '\\ ' man?]]
>>> and you'll see.  Some of them are valid, but a lot of them aren't.
>>
>> Can you point me at some examples?
> 
> A sample:
> 
> man3/envz_add.3:61:.RI ( *envz ,\  *envz_len )
> << this should be two lines
> man3/xdr.3:184:.IR "long\ *" .
> << unnecessary
> man3/scandir.3:277:.IR "const void\ *" .
> << unnecessary and self-inconsistent
> man5/proc.5:1350:.RI ( "readelf\ \-l" ).
> << unnecessary
> man7/symlink.7:424:.I "rm\ \-r slink directory"
> << unnecessary and self-inconsistent
> man7/feature_test_macros.7:492:.IR "cc\ \-std=c99" ).
> << unnecessary
> man8/ld.so.8:313:.IR "readelf\ \-n"
> << unnecessary
> 
> Maybe I'm missing something?

So, the point here is that suppose a line break falls badly and we end up with

...................... const void
* ...............................

or

......................... readelf
-n ..............................

or
.............................. cc
-std=c99 ........................

or

.............................. 16
MB ..............................

The general problem here is that a small piece of a unit (usually at
the end) is broken onto a new line, making  things a bit more
difficult to read. That sort of thing is ugly, I think. That's
why there is the "\\ ".

Maybe there are a few redundant cases. And maybe there are a few
borderline cases. For example, maybe in envz_add.3, "\\ " is
not strictly necessary (though I'm inclined to keep it).

There may still be a few misplaced "\\ " escapes (I just fixed a few),
but many of these really are needed, I think.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: Escaping whitespace

[Alejandro Colomar (man-pages)]

On 1/8/21 1:44 PM, Michael Kerrisk (man-pages) wrote:
> On 1/8/21 12:49 PM, Alejandro Colomar (man-pages) wrote:
>>
>>
>> On 1/8/21 12:29 PM, Michael Kerrisk (man-pages) wrote:
>>> Hi Alex,
>>>
>>> On Thu, 7 Jan 2021 at 18:11, Alejandro Colomar (man-pages)
>>> <alx.manpages@gmail.com> wrote:
>>>>
>>>> Hi Michael,
>>>>
>>>> On 1/6/21 1:51 PM, Michael Kerrisk (man-pages) wrote:
>>>>> Hi Alex,
>>>>>
>>>>> On 1/5/21 10:56 PM, Alejandro Colomar (man-pages) wrote:
>>>>>> Hi Michael,
>>>>>>
>>>>>> While having a look at your latest commits,
>>>>>> I saw that there's a bit of inconsistency in escaping whitespace
>>>>>> (existing previous to the commit):
>>>>>>
>>>>>> Sometimes it's [!\ (], and sometimes it's [! (].
>>>>>
>>>>> Thanks for prodding me about this.
>>>>>
>>>>> Yes, it's inconsistent. And given the use of .nf/.fi
>>>>> around the text blocks, escaping the spaces serves no
>>>>> purpose. So I made a more radical fix; see commit
>>>>> 5c10d2c5e299011e34adb568737acfc8920fc27c
>>>>
>>>> Nice!
>>>>
>>>> After your following commit (422d5327a88fa89394100bafad69b21e50b26399),
>>>> I found that there are many such cases.  Just [[grep -rnI '\\ ' man?]]
>>>> and you'll see.  Some of them are valid, but a lot of them aren't.
>>>
>>> Can you point me at some examples?
>>
>> A sample:
>>
>> man3/envz_add.3:61:.RI ( *envz ,\  *envz_len )
>> << this should be two lines
>> man3/xdr.3:184:.IR "long\ *" .
>> << unnecessary
>> man3/scandir.3:277:.IR "const void\ *" .
>> << unnecessary and self-inconsistent
>> man5/proc.5:1350:.RI ( "readelf\ \-l" ).
>> << unnecessary
>> man7/symlink.7:424:.I "rm\ \-r slink directory"
>> << unnecessary and self-inconsistent
>> man7/feature_test_macros.7:492:.IR "cc\ \-std=c99" ).
>> << unnecessary
>> man8/ld.so.8:313:.IR "readelf\ \-n"
>> << unnecessary
>>
>> Maybe I'm missing something?
> 
> So, the point here is that suppose a line break falls badly and we end up with
> 
> ...................... const void
> * ...............................
> 
> or
> 
> ......................... readelf
> -n ..............................
> 
> or
> .............................. cc
> -std=c99 ........................
> 
> or
> 
> .............................. 16
> MB ..............................
> 
> The general problem here is that a small piece of a unit (usually at
> the end) is broken onto a new line, making  things a bit more
> difficult to read. That sort of thing is ugly, I think. That's
> why there is the "\\ ".
> 

Ahhh, true.
Thanks!


> Maybe there are a few redundant cases. And maybe there are a few
> borderline cases. For example, maybe in envz_add.3, "\\ " is
> not strictly necessary (though I'm inclined to keep it).
> 
> There may still be a few misplaced "\\ " escapes (I just fixed a few),
> but many of these really are needed, I think.
> 
> Cheers,
> 
> Michael
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/