[PATCH] pipe.7: tfix

[PATCH] pipe.7: tfix

[Jakub Wilk]

Escape hyphens.

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

Re: [PATCH] pipe.7: tfix

[Alejandro Colomar (mailing lists; readonly)]

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?

Thanks,

Alex

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

Re: [PATCH] pipe.7: tfix

[Michael Kerrisk (man-pages)]

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/

Re: [PATCH] pipe.7: tfix

[Michael Kerrisk (man-pages)]

On 1/18/21 10:17 AM, Jakub Wilk wrote:
> Escape hyphens.
> 
> Signed-off-by: Jakub Wilk <jwilk@jwilk.net>

I've applied this patch.

Thanks,

Michael

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