Re: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper
On 9/27/20 10:05 PM, Alejandro Colomar wrote: > Hi Branden, > > * G. Branden Robinson via linux-man: > > 1) > > > .EX > > .B int fstat(int \c > > .IB fd , \~\c > > .B struct stat *\c > > .IB statbuf ); > > .EE > > 2) > > > .EX > > .BI "int fstat(int " fd ", struct stat *" statbuf ); > > .EE > > 3) > > > .EX > > .BI "int fstat(int\~" fd ", struct stat *" statbuf ); > > .EE > > I'd say number 2 is best. Rationale: grep :) > I agree it's visually somewhat harder, but grepping is way easier. I'd say number 2 also. But, visually, it's the least difficult for me. Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Re: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper
Hi Branden, On 9/27/20 7:46 AM, G. Branden Robinson wrote: > At 2020-09-24T10:06:23+0200, Michael Kerrisk (man-pages) wrote: >> Thanks for the interesting history, Branden! > > Hi, Michael. And you're welcome! I often wonder if I test people's > patience with my info dumps but I try to show my work when making > claims. > >> From time toi time I wonder if the function prototypes in >> the SYNOPSIS should also be inside .EX/.EE. Your thoughts? > > I think there are trade-offs. > > 1. If you want alignment, the monospaced font that .EX/.EE uses is the >most portable way to get it. > 2. For typeset output, you'll generally run out of line more quickly >with a monospaced font than with the troff/man default (Times). >_Any_ time filling is off, output should be checked to see if it >overruns the right margin, but this point strengthens in monospace. Yes, it's a good point. I think I'll leave this idea for now. > Here's something that isn't a trade-off that might come as a surprise to > some readers. > > * You can still get bold and italics inside an .EX/.EE region, so you > can still use these distinguish data types, variable names, and > what-have-you. > > The idiom for achieving this is apparently not well-known among those > who write man pages by hand, and tools that generate man(7) language > from some other source often produce output that is so ugly as to be > unintelligible to non-experts in *roff. > > The key insights are that (A) you can still make macro calls inside an > .EX/.EE region, and (B) you can use the \c escape to "interrupt" an > input line and continue it on the next without introducing any > whitespace. For instance, looking at fstat() from your stat(2) page, I > might write it using .EX and .EE as follows: > > .EX > .B int fstat(int \c > .IB fd , \~\c > .B struct stat *\c > .IB statbuf ); > .EE > > Normally in man pages, it is senseless to have any spaces before the \c > escape, and \c is best omitted in that event. However, when filling is > disabled (as is the case in .EX/.EE regions), output lines break where > the input lines do by default--\c overrides this, causing the lines to > be joined. (Regarding the \~, see below.) > > If there is no use for roman in the line, then you could do the whole > function signature with the .BI macro by quoting macro arguments that > contain whitespace. I was more or less aware of all of the above. (But the \c technique is something that I see rarely enough that I often take a moment to remember what it does.) > > .EX > .BI "int fstat(int " fd ", struct stat *" statbuf ); > .EE > > As a matter of personal style, I find quoted space characters interior > but adjacent to quotation marks visually confusing--it's slower for me > to tell which parts of the line are "inside" the quotes and which > outside--so I turn to groff's \~ non-breaking space escape (widely > supported elsewhere) for these boundary spaces. > > .EX > .BI "int fstat(int\~" fd ", struct stat *" statbuf ); > .EE > > Which of the above three models do you think would work best for the > man-pages project? I understand what you say about quoted interior spaces being a little hard to parse. But I find the \~ makes the source less readable. Likewise, IMO, the \c technique renders the source harder to read. > Also, do you have any use for roman in function signatures? I see it > used for comments and feature test macro material, but not within > function signatures proper. I think you're correct. Roman only occurs in comments. > > As an aside, I will admit to some unease with the heavy use of bold in > synopses in section 2 and 3 man pages, It's been that way "forever" in the Linux man-pages. > but I can marshal no historical > argument against it. In fact, a quick check of some Unix v7 section 2 > pages from 1979 that I have lying around (thanks to TUHS) reveals that > Bell Labs used undifferentiated bold for the whole synopsis! > > $ head -n 13 usr/man/man2/stat.2 > .TH STAT 2 > .SH NAME > stat, fstat \- get file status > .SH SYNOPSIS > .B #include > .br > .B #include > .PP > .B stat(name, buf) > .br > .B char *name; > .br > .B struct stat *buf; As ever, thanks for the history! Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Re: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper
On 2020-09-28 15:48, G. Branden Robinson wrote: >> There are a few cases: if I want to find declarations of type int, >> I'd start with: >> >> $ grep -rn "int\s" >> >> or something like that. "int\~" would break the ability to do that. > > That would, among more obscure cases, miss the style of function > declaration used by people who get along without ctags: > > static int > my_little_function(int foo, char bar) > > So I would tend to use grep 'int\>' to match a word boundary instead of > a whitespace character. > > Regards, > Branden > On 2020-09-28 16:31, David Laight wrote: From: Alejandro Colomar Sent: 28 September 2020 14:33 ... There are a few cases: if I want to find declarations of type int, I'd start with: $ grep -rn "int\s" or something like that. "int\~" would break the ability to do that. The 'word markers' \< and \> are your friends; look for "\". David - Registered Address Lakeside, Bramley Road, Mount Farm, Milton Keynes, MK1 1PT, UK Registration No: 1397386 (Wales) Thank you both, I didn't know about those. Regards, Alex
RE: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper
From: Alejandro Colomar > Sent: 28 September 2020 14:33 ... > There are a few cases: if I want to find declarations of type int, > I'd start with: > > $ grep -rn "int\s" > > or something like that. "int\~" would break the ability to do that. The 'word markers' \< and \> are your friends; look for "\". David - Registered Address Lakeside, Bramley Road, Mount Farm, Milton Keynes, MK1 1PT, UK Registration No: 1397386 (Wales)
Re: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper
At 2020-09-28T15:33:21+0200, Alejandro Colomar wrote: > On 2020-09-28 14:52, G. Branden Robinson wrote: > > At 2020-09-27T22:05:14+0200, Alejandro Colomar wrote: > >> 2) > >> > >>> .EX > >>> .BI "int fstat(int " fd ", struct stat *" statbuf ); > >>> .EE > >> > >> 3) > >> > >>> .EX > >>> .BI "int fstat(int\~" fd ", struct stat *" statbuf ); > >>> .EE > >> > >> I'd say number 2 is best. Rationale: grep :) > >> I agree it's visually somewhat harder, but grepping is way easier. > > > > I don't see how (2) is any tougher to grep than (3)...? [...] > > $ grep 'fstat.*fd.*statbuf' man2/* > > There are a few cases: if I want to find declarations of type int, > I'd start with: > > $ grep -rn "int\s" > > or something like that. "int\~" would break the ability to do that. That would, among more obscure cases, miss the style of function declaration used by people who get along without ctags: static int my_little_function(int foo, char bar) So I would tend to use grep 'int\>' to match a word boundary instead of a whitespace character. Regards, Branden signature.asc Description: PGP signature
Re: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper
On 2020-09-28 14:52, G. Branden Robinson wrote: > At 2020-09-27T22:05:14+0200, Alejandro Colomar wrote: >> Hi Branden, >> >> * G. Branden Robinson via linux-man: >> >> 1) >> >>> .EX >>> .B int fstat(int \c >>> .IB fd , \~\c >>> .B struct stat *\c >>> .IB statbuf ); >>> .EE >> >> 2) >> >>> .EX >>> .BI "int fstat(int " fd ", struct stat *" statbuf ); >>> .EE >> >> 3) >> >>> .EX >>> .BI "int fstat(int\~" fd ", struct stat *" statbuf ); >>> .EE >> >> I'd say number 2 is best. Rationale: grep :) >> I agree it's visually somewhat harder, but grepping is way easier. > > I don't see how (2) is any tougher to grep than (3)...? > > If I'm grepping, I'm usually concerned with things like > variable/function names and not with punctuation, so if I were grepping > for the above function signature I'd probably write: > > $ grep 'fstat.*fd.*statbuf' man2/* > > ...which would catch either of the above just fine. > > Am I missing something? > > Regards, > Branden > There are a few cases: if I want to find declarations of type int, I'd start with: $ grep -rn "int\s" or something like that. "int\~" would break the ability to do that. Regards, Alex
Re: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper
At 2020-09-27T22:05:14+0200, Alejandro Colomar wrote: > Hi Branden, > > * G. Branden Robinson via linux-man: > > 1) > > > .EX > > .B int fstat(int \c > > .IB fd , \~\c > > .B struct stat *\c > > .IB statbuf ); > > .EE > > 2) > > > .EX > > .BI "int fstat(int " fd ", struct stat *" statbuf ); > > .EE > > 3) > > > .EX > > .BI "int fstat(int\~" fd ", struct stat *" statbuf ); > > .EE > > I'd say number 2 is best. Rationale: grep :) > I agree it's visually somewhat harder, but grepping is way easier. I don't see how (2) is any tougher to grep than (3)...? If I'm grepping, I'm usually concerned with things like variable/function names and not with punctuation, so if I were grepping for the above function signature I'd probably write: $ grep 'fstat.*fd.*statbuf' man2/* ...which would catch either of the above just fine. Am I missing something? Regards, Branden signature.asc Description: PGP signature
Re: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper
Hi Branden, * G. Branden Robinson via linux-man: 1) > .EX > .B int fstat(int \c > .IB fd , \~\c > .B struct stat *\c > .IB statbuf ); > .EE 2) > .EX > .BI "int fstat(int " fd ", struct stat *" statbuf ); > .EE 3) > .EX > .BI "int fstat(int\~" fd ", struct stat *" statbuf ); > .EE I'd say number 2 is best. Rationale: grep :) I agree it's visually somewhat harder, but grepping is way easier. Regards, Alex
Re: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper
At 2020-09-24T10:06:23+0200, Michael Kerrisk (man-pages) wrote: > Thanks for the interesting history, Branden! Hi, Michael. And you're welcome! I often wonder if I test people's patience with my info dumps but I try to show my work when making claims. > From time toi time I wonder if the function prototypes in > the SYNOPSIS should also be inside .EX/.EE. Your thoughts? I think there are trade-offs. 1. If you want alignment, the monospaced font that .EX/.EE uses is the most portable way to get it. 2. For typeset output, you'll generally run out of line more quickly with a monospaced font than with the troff/man default (Times). _Any_ time filling is off, output should be checked to see if it overruns the right margin, but this point strengthens in monospace. Here's something that isn't a trade-off that might come as a surprise to some readers. * You can still get bold and italics inside an .EX/.EE region, so you can still use these distinguish data types, variable names, and what-have-you. The idiom for achieving this is apparently not well-known among those who write man pages by hand, and tools that generate man(7) language from some other source often produce output that is so ugly as to be unintelligible to non-experts in *roff. The key insights are that (A) you can still make macro calls inside an .EX/.EE region, and (B) you can use the \c escape to "interrupt" an input line and continue it on the next without introducing any whitespace. For instance, looking at fstat() from your stat(2) page, I might write it using .EX and .EE as follows: .EX .B int fstat(int \c .IB fd , \~\c .B struct stat *\c .IB statbuf ); .EE Normally in man pages, it is senseless to have any spaces before the \c escape, and \c is best omitted in that event. However, when filling is disabled (as is the case in .EX/.EE regions), output lines break where the input lines do by default--\c overrides this, causing the lines to be joined. (Regarding the \~, see below.) If there is no use for roman in the line, then you could do the whole function signature with the .BI macro by quoting macro arguments that contain whitespace. .EX .BI "int fstat(int " fd ", struct stat *" statbuf ); .EE As a matter of personal style, I find quoted space characters interior but adjacent to quotation marks visually confusing--it's slower for me to tell which parts of the line are "inside" the quotes and which outside--so I turn to groff's \~ non-breaking space escape (widely supported elsewhere) for these boundary spaces. .EX .BI "int fstat(int\~" fd ", struct stat *" statbuf ); .EE Which of the above three models do you think would work best for the man-pages project? Also, do you have any use for roman in function signatures? I see it used for comments and feature test macro material, but not within function signatures proper. As an aside, I will admit to some unease with the heavy use of bold in synopses in section 2 and 3 man pages, but I can marshal no historical argument against it. In fact, a quick check of some Unix v7 section 2 pages from 1979 that I have lying around (thanks to TUHS) reveals that Bell Labs used undifferentiated bold for the whole synopsis! $ head -n 13 usr/man/man2/stat.2 .TH STAT 2 .SH NAME stat, fstat \- get file status .SH SYNOPSIS .B #include .br .B #include .PP .B stat(name, buf) .br .B char *name; .br .B struct stat *buf; Regards, Branden signature.asc Description: PGP signature
Re: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper
Hi Branden,
On 9/21/20 4:36 PM, G. Branden Robinson wrote:
> At 2020-09-11T12:58:08+, Walter Harms wrote:
>> the groff commands are ducument in man 7 groff
>> .nf No filling or adjusting of output-lines.
>> .fi Fill output lines
>>
>> (for me) a typical use is like this:
>> .nf
>>
>> struct timeval {
>> time_t tv_sec; /* seconds */
>> suseconds_t tv_usec;/* microseconds */
>> };
>> .fi
>>
>> In the top section you prevent indenting (if any).
>
> The above will not work as desired for typesetter output, a.k.a., "troff
> devices", such as PostScript or PDF. The initial code indent might work
> okay but the alignment of the field names will become
> ragged/mis-registered and the comments even more so.
Yes.
> This is because a proportional font is used by default for troff
> devices. The classical man macros, going back to Version 7 Unix (1979)
> had no good solution for this problem and Unix room tradition at Murray
> Hill going all the way back to (what we now call) the First Edition
> manual in 1971 was to read the man pages on a typewriter--a Teletype
> Model 33 or Model 37. Typewriters, of course, always[1] used monospaced
> fonts.
>
> Version 9 Unix (1986) introduced .EX and .EE for setting material in a
> monospaced font even if the device used proportional type by default.
> (Plan 9 troff inherited them.) GNU roff has supporteds .EX and .EE as
> well, for over 13 years, and its implementations are ultra-permissively
> licensed so other *roffs like Heirloom Doctools have picked them up.
> Therefore I recommend .EX and .EE for all code examples.
>
> They are very simple to use. In the above, simply replace ".nf" with
> ".EX" and ".fi" with ".EE".
>
> Regards,
> Branden
>
> [1] Not completely true; variable-pitch typewriters (such as 10/12 point
> selectable) were fairly common and some expensive models like the IBM
> Executive even featured true proportional type.
Thanks for the interesting history, Branden!
>From time toi time I wonder if the function prototypes in
the SYNOPSIS should also be inside .EX/.EE. Your thoughts?
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
Re: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper
At 2020-09-11T12:58:08+, Walter Harms wrote:
> the groff commands are ducument in man 7 groff
> .nf No filling or adjusting of output-lines.
> .fi Fill output lines
>
> (for me) a typical use is like this:
> .nf
>
> struct timeval {
> time_t tv_sec; /* seconds */
> suseconds_t tv_usec;/* microseconds */
> };
> .fi
>
> In the top section you prevent indenting (if any).
The above will not work as desired for typesetter output, a.k.a., "troff
devices", such as PostScript or PDF. The initial code indent might work
okay but the alignment of the field names will become
ragged/mis-registered and the comments even more so.
This is because a proportional font is used by default for troff
devices. The classical man macros, going back to Version 7 Unix (1979)
had no good solution for this problem and Unix room tradition at Murray
Hill going all the way back to (what we now call) the First Edition
manual in 1971 was to read the man pages on a typewriter--a Teletype
Model 33 or Model 37. Typewriters, of course, always[1] used monospaced
fonts.
Version 9 Unix (1986) introduced .EX and .EE for setting material in a
monospaced font even if the device used proportional type by default.
(Plan 9 troff inherited them.) GNU roff has supporteds .EX and .EE as
well, for over 13 years, and its implementations are ultra-permissively
licensed so other *roffs like Heirloom Doctools have picked them up.
Therefore I recommend .EX and .EE for all code examples.
They are very simple to use. In the above, simply replace ".nf" with
".EX" and ".fi" with ".EE".
Regards,
Branden
[1] Not completely true; variable-pitch typewriters (such as 10/12 point
selectable) were fairly common and some expensive models like the IBM
Executive even featured true proportional type.
signature.asc
Description: PGP signature
Re: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper
On 9/10/20 11:13 PM, Alejandro Colomar wrote: > Notes: I copied .nf and .fi from futex.2, but they made no visual difference. > What do they actually do? > > Signed-off-by: Alejandro Colomar Thanks, Alex. Patch applied. Cheers, Michael > --- > man2/membarrier.2 | 9 + > 1 file changed, 9 insertions(+) > > diff --git a/man2/membarrier.2 b/man2/membarrier.2 > index 8825de71e..f65c6be5c 100644 > --- a/man2/membarrier.2 > +++ b/man2/membarrier.2 > @@ -26,9 +26,15 @@ > .SH NAME > membarrier \- issue memory barriers on a set of threads > .SH SYNOPSIS > +.nf > +.PP > .B #include > .PP > .BI "int membarrier(int " cmd ", int " flags ");" > +.fi > +.PP > +.IR Note : > +There is no glibc wrapper for this system call; see NOTES. > .SH DESCRIPTION > The > .BR membarrier () > @@ -270,6 +276,9 @@ Examples where > .BR membarrier () > can be useful include implementations > of Read-Copy-Update libraries and garbage collectors. > +.PP > +Glibc does not provide a wrapper for this system call; call it using > +.BR syscall (2). > .SH EXAMPLES > Assuming a multithreaded application where "fast_path()" is executed > very frequently, and where "slow_path()" is executed infrequently, the > -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
