* [PATCH] pipe.7: tfix @ 2021-01-18 9:17 Jakub Wilk 2021-01-18 15:19 ` Alejandro Colomar (mailing lists; readonly) 2021-01-18 15:41 ` Michael Kerrisk (man-pages) 0 siblings, 2 replies; 4+ messages in thread From: Jakub Wilk @ 2021-01-18 9:17 UTC (permalink / raw) To: Michael Kerrisk; +Cc: linux-man 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 ^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH] pipe.7: tfix 2021-01-18 9:17 [PATCH] pipe.7: tfix Jakub Wilk @ 2021-01-18 15:19 ` Alejandro Colomar (mailing lists; readonly) 2021-01-18 15:40 ` Michael Kerrisk (man-pages) 2021-01-18 15:41 ` Michael Kerrisk (man-pages) 1 sibling, 1 reply; 4+ messages in thread From: Alejandro Colomar (mailing lists; readonly) @ 2021-01-18 15:19 UTC (permalink / raw) To: Jakub Wilk, Michael Kerrisk; +Cc: linux-man 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 > ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] pipe.7: tfix 2021-01-18 15:19 ` Alejandro Colomar (mailing lists; readonly) @ 2021-01-18 15:40 ` Michael Kerrisk (man-pages) 0 siblings, 0 replies; 4+ messages in thread From: Michael Kerrisk (man-pages) @ 2021-01-18 15:40 UTC (permalink / raw) To: alx.manpages, Jakub Wilk; +Cc: mtk.manpages, linux-man 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/ ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] pipe.7: tfix 2021-01-18 9:17 [PATCH] pipe.7: tfix Jakub Wilk 2021-01-18 15:19 ` Alejandro Colomar (mailing lists; readonly) @ 2021-01-18 15:41 ` Michael Kerrisk (man-pages) 1 sibling, 0 replies; 4+ messages in thread From: Michael Kerrisk (man-pages) @ 2021-01-18 15:41 UTC (permalink / raw) To: Jakub Wilk; +Cc: mtk.manpages, linux-man 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/ ^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2021-01-18 15:48 UTC | newest] Thread overview: 4+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2021-01-18 9:17 [PATCH] pipe.7: tfix Jakub Wilk 2021-01-18 15:19 ` Alejandro Colomar (mailing lists; readonly) 2021-01-18 15:40 ` Michael Kerrisk (man-pages) 2021-01-18 15:41 ` Michael Kerrisk (man-pages)
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox