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 <sys/types.h> .br .B #include <sys/stat.h> .PP .B stat(name, buf) .br .B char *name; .br .B struct stat *buf; Regards, Branden
Attachment:
signature.asc
Description: PGP signature
