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