From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: mtk.manpages@gmail.com,
"linux-man@vger.kernel.org" <linux-man@vger.kernel.org>,
"linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>
Subject: Re: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper
Date: Tue, 29 Sep 2020 14:06:07 +0200 [thread overview]
Message-ID: <baeb500b-f252-2632-585a-93adfab28141@gmail.com> (raw)
In-Reply-To: <20200927054657.ea2zaiesle6hwjit@localhost.localdomain>
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/
next prev parent reply other threads:[~2020-09-29 12:06 UTC|newest]
Thread overview: 100+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-10 21:13 [PATCH 00/24] Many patches Alejandro Colomar
2020-09-10 21:13 ` [PATCH 01/24] inet_net_pton.3: Use 'PRIx32' rather than "%x" when printing 'uint32_t' values Alejandro Colomar
2020-09-11 9:31 ` Michael Kerrisk (man-pages)
2020-09-11 9:39 ` Alejandro Colomar
2020-09-11 9:59 ` Michael Kerrisk (man-pages)
2020-09-12 21:07 ` David Laight
2020-09-10 21:13 ` [PATCH 02/24] endian.3: " Alejandro Colomar
2020-09-11 10:13 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 03/24] timerfd_create.2: Use 'PRIxN' macros when printing C99 fixed-width integer types Alejandro Colomar
2020-09-11 8:12 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 04/24] eventfd.2: " Alejandro Colomar
2020-09-11 8:13 ` Michael Kerrisk (man-pages)
2020-09-11 12:44 ` AW: " Walter Harms
2020-09-10 21:13 ` [PATCH 05/24] offsetof.3: Use "%zu" rather than "%zd" when printing 'size_t' values Alejandro Colomar
2020-09-11 8:06 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 06/24] timer_create.2: Cast to 'unsigned long' rathen than 'long' when printing with "%lx" Alejandro Colomar
2020-09-11 7:57 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 07/24] request_key.2: Cast to 'unsigned long' rather " Alejandro Colomar
2020-09-11 7:51 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 08/24] add_key.2: " Alejandro Colomar
2020-09-11 7:50 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 09/24] clock_getcpuclockid.3: Remove unneeded cast Alejandro Colomar
2020-09-11 7:48 ` Michael Kerrisk (man-pages)
2020-09-11 10:25 ` Alejandro Colomar
2020-09-11 11:05 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 10/24] ioctl_ns.2: " Alejandro Colomar
2020-09-11 7:24 ` Michael Kerrisk (man-pages)
2020-09-11 9:13 ` [PATCH v2 10/24] ioctl_ns.2: Cast to 'unsigned long' rather than 'long' when printing with "%lx" Alejandro Colomar
2020-09-11 9:18 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 11/24] stat.2: Remove unneeded cast Alejandro Colomar
2020-09-11 7:25 ` Michael Kerrisk (man-pages)
2020-09-11 9:16 ` [PATCH v2 11/24] stat.2: Cast to 'unsigned long' rather than 'long' when printing with "%lx" Alejandro Colomar
2020-09-11 9:19 ` Michael Kerrisk (man-pages)
2020-09-11 9:34 ` [PATCH v3 11/24] stat.2: wsfix Alejandro Colomar
2020-09-11 9:36 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 12/24] getgrent_r.3: Use sizeof() to get buffer size (instead of hardcoding macro name) Alejandro Colomar
2020-09-11 7:17 ` Michael Kerrisk (man-pages)
2020-09-11 12:50 ` AW: " Walter Harms
2020-09-11 19:17 ` Alejandro Colomar
2020-09-14 9:24 ` AW: " Walter Harms
2020-09-14 9:51 ` Alejandro Colomar
2020-09-11 14:35 ` Stefan Puiu
2020-09-11 15:28 ` Alejandro Colomar
2020-09-11 17:21 ` Alejandro Colomar
2020-09-15 10:03 ` Stefan Puiu
2020-09-23 20:35 ` Michael Kerrisk (man-pages)
2020-09-24 9:35 ` Alejandro Colomar
2020-09-24 10:04 ` Michael Kerrisk (man-pages)
2020-09-24 10:08 ` Alejandro Colomar
2020-09-24 11:38 ` Michael Kerrisk (man-pages)
2020-09-24 13:09 ` Alejandro Colomar
2020-09-29 13:38 ` Michael Kerrisk (man-pages)
2020-09-29 13:57 ` Alejandro Colomar
2020-09-10 21:13 ` [PATCH 13/24] getpwent_r.3: " Alejandro Colomar
2020-09-11 7:17 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 14/24] fread.3: Move ARRAY_SIZE logic into macro Alejandro Colomar
2020-09-11 8:04 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 15/24] unix.7: Use sizeof() to get buffer size (instead of hardcoding macro name) Alejandro Colomar
2020-09-11 8:05 ` Michael Kerrisk (man-pages)
2020-09-11 8:07 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 16/24] getpwent_r.3: Declare variables with different types in different lines Alejandro Colomar
2020-09-11 6:43 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 17/24] get_phys_pages.3: Write 'long' instead of 'long int' Alejandro Colomar
2020-09-11 6:43 ` Michael Kerrisk (man-pages)
2020-09-11 13:07 ` AW: " Walter Harms
2020-09-11 19:24 ` Alejandro Colomar
2020-09-10 21:13 ` [PATCH 18/24] core.5: Use adequate type Alejandro Colomar
2020-09-11 8:08 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 19/24] pthread_setname_np.3: ffix Alejandro Colomar
2020-09-11 7:58 ` Michael Kerrisk (man-pages)
2020-09-11 8:32 ` Alejandro Colomar
2020-09-11 11:12 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 20/24] loop.4: ffix Alejandro Colomar
2020-09-11 6:42 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 21/24] aio.7: Use perror() directly Alejandro Colomar
2020-09-11 6:42 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper Alejandro Colomar
2020-09-11 6:44 ` Michael Kerrisk (man-pages)
2020-09-11 9:33 ` Jakub Wilk
2020-09-11 9:35 ` Michael Kerrisk (man-pages)
2020-09-11 11:42 ` Alejandro Colomar
2020-09-11 12:58 ` AW: " Walter Harms
2020-09-21 14:36 ` G. Branden Robinson
2020-09-24 8:06 ` Michael Kerrisk (man-pages)
2020-09-27 5:46 ` G. Branden Robinson
2020-09-27 20:05 ` Alejandro Colomar
2020-09-28 12:52 ` G. Branden Robinson
2020-09-28 13:33 ` Alejandro Colomar
2020-09-28 13:48 ` G. Branden Robinson
2020-09-28 14:31 ` David Laight
2020-09-28 14:42 ` Alejandro Colomar
2020-09-29 12:07 ` Michael Kerrisk (man-pages)
2020-09-29 12:06 ` Michael Kerrisk (man-pages) [this message]
2020-09-10 21:13 ` [PATCH 23/24] select_tut.2: Use MAX(a, b) from <sys/param.h> Alejandro Colomar
2020-09-11 7:54 ` Michael Kerrisk (man-pages)
2020-09-11 8:46 ` Alejandro Colomar
2020-09-11 10:03 ` Michael Kerrisk (man-pages)
2020-09-10 21:13 ` [PATCH 24/24] bpf.2: Add missing headers Alejandro Colomar
2020-09-11 9:12 ` Michael Kerrisk (man-pages)
2020-09-11 9:32 ` [PATCH 00/24] Many patches Michael Kerrisk (man-pages)
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=baeb500b-f252-2632-585a-93adfab28141@gmail.com \
--to=mtk.manpages@gmail.com \
--cc=g.branden.robinson@gmail.com \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-man@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).