Re: [PATCH] pipe.7: tfix

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hi Alex (and Jakub)

On 1/18/21 4:19 PM, Alejandro Colomar (mailing lists; readonly) wrote:
> On 1/18/21 10:17 AM, Jakub Wilk wrote:
>> Escape hyphens.
> 
> Hi Jakub,
> 
> Would you mind adding not only 'what',
> but also (and especially) 'why' is does it?
> I mean, 20 years from now we might wonder why we escaped hyphens.
>
> Adding for example the following to the commit message might help:
> 
> [
> $ man 7 man-pages 2>/dev/null \
>   |sed -n '/Generating optimal glyphs/,/\\-/p';
>    Generating optimal glyphs
>        Where a real minus character is required (e.g., for numbers
>        such as -1, for man page cross references such as utf-8(7),
>        or when writing options that have a leading dash,  such  as
>        in ls -l), use the following form in the man page source:
> 
>            \-
> ]
> 
> I'm also wondering... are there any other places where this patch would
> also be needed?

Well, it is documented in our man-pages(7). I think just an
"As per man-pages(7), ..." would suffice. But even without
it, I would not worry too much.

I think it's great when you add stuff like this little script in 
your commit messages, but I don't want to impose that burden on
others.

Thanks,

Michael



>> Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
>> ---
>>  man7/pipe.7 | 18 +++++++++---------
>>  1 file changed, 9 insertions(+), 9 deletions(-)
>>
>> diff --git a/man7/pipe.7 b/man7/pipe.7
>> index 21c8fa79b..c3210320c 100644
>> --- a/man7/pipe.7
>> +++ b/man7/pipe.7
>> @@ -163,7 +163,7 @@ but is provided on many implementations.
>>  .SS /proc files
>>  On Linux, the following files control how much memory can be used for pipes:
>>  .TP
>> -.IR /proc/sys/fs/pipe-max-pages " (only in Linux 2.6.34)"
>> +.IR /proc/sys/fs/pipe\-max\-pages " (only in Linux 2.6.34)"
>>  .\" commit b492e95be0ae672922f4734acf3f5d35c30be948
>>  An upper limit, in pages, on the capacity that an unprivileged user
>>  (one without the
>> @@ -175,9 +175,9 @@ The default value for this limit is 16 times the default pipe capacity
>>  (see above); the lower limit is two pages.
>>  .IP
>>  This interface was removed in Linux 2.6.35, in favor of
>> -.IR /proc/sys/fs/pipe-max-size .
>> +.IR /proc/sys/fs/pipe\-max\-size .
>>  .TP
>> -.IR /proc/sys/fs/pipe-max-size " (since Linux 2.6.35)"
>> +.IR /proc/sys/fs/pipe\-max\-size " (since Linux 2.6.35)"
>>  .\" commit ff9da691c0498ff81fdd014e7a0731dab2337dac
>>  The maximum size (in bytes) of individual pipes that can be set
>>  .\" This limit is not checked on pipe creation, where the capacity is
>> @@ -202,7 +202,7 @@ Since Linux 4.9,
>>  the value on this file also acts as a ceiling on the default capacity
>>  of a new pipe or newly opened FIFO.
>>  .TP
>> -.IR /proc/sys/fs/pipe-user-pages-hard " (since Linux 4.5)"
>> +.IR /proc/sys/fs/pipe\-user\-pages\-hard " (since Linux 4.5)"
>>  .\" commit 759c01142a5d0f364a462346168a56de28a80f52
>>  The hard limit on the total size (in pages) of all pipes created or set by
>>  a single unprivileged user (i.e., one with neither the
>> @@ -220,7 +220,7 @@ no hard limit is applied.
>>  .\" The default was chosen to avoid breaking existing applications that
>>  .\" make intensive use of pipes (e.g., for splicing).
>>  .TP
>> -.IR /proc/sys/fs/pipe-user-pages-soft " (since Linux 4.5)"
>> +.IR /proc/sys/fs/pipe\-user\-pages\-soft " (since Linux 4.5)"
>>  .\" commit 759c01142a5d0f364a462346168a56de28a80f52
>>  The soft limit on the total size (in pages) of all pipes created or set by
>>  a single unprivileged user (i.e., one with neither the
>> @@ -238,9 +238,9 @@ The default value for this file is 16384,
>>  which permits creating up to 1024 pipes with the default capacity.
>>  .PP
>>  Before Linux 4.9, some bugs affected the handling of the
>> -.IR pipe-user-pages-soft
>> +.IR pipe\-user\-pages\-soft
>>  and
>> -.IR pipe-user-pages-hard
>> +.IR pipe\-user\-pages\-hard
>>  limits; see BUGS.
>>  .\"
>>  .SS PIPE_BUF
>> @@ -342,9 +342,9 @@ Portable applications should avoid reliance on
>>  bidirectional pipe semantics.
>>  .SS BUGS
>>  Before Linux 4.9, some bugs affected the handling of the
>> -.IR pipe-user-pages-soft
>> +.IR pipe\-user\-pages\-soft
>>  and
>> -.IR pipe-user-pages-hard
>> +.IR pipe\-user\-pages\-hard
>>  limits when using the
>>  .BR fcntl (2)
>>  .BR F_SETPIPE_SZ
>>
> 


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