Re: [PATCH] pipe.7: tfix

["Alejandro Colomar (mailing lists; readonly)" <alx.mailinglists@gmail.com>]

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
>