Re: Escaping whitespace

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

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/