Date:   Tue, 29 Sep 2020 14:06:07 +0200
From:   "Michael Kerrisk (man-pages)" <mtk.manpages@...il.com>
To:     "G. Branden Robinson" <g.branden.robinson@...il.com>
Cc:     mtk.manpages@...il.com,
        "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

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/

Powered by blists - more mailing lists