Date:   Sun, 27 Sep 2020 15:46:59 +1000
From:   "G. Branden Robinson" <g.branden.robinson@...il.com>
To:     "Michael Kerrisk (man-pages)" <mtk.manpages@...il.com>
Cc:     "linux-man@...r.kernel.org" <linux-man@...r.kernel.org>,
        "linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>
Subject: 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 <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

Download attachment "signature.asc" of type "application/pgp-signature" (834 bytes)

Powered by blists - more mailing lists