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 <sys/types.h> > .br > .B #include <sys/stat.h> > .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/
