From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: "G. Branden Robinson" <g.branden.robinson@gmail.com>,
"linux-man@vger.kernel.org" <linux-man@vger.kernel.org>,
"linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>
Cc: mtk.manpages@gmail.com
Subject: Re: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper
Date: Thu, 24 Sep 2020 10:06:23 +0200 [thread overview]
Message-ID: <2862c745-a23a-95d2-157e-7f91f671f839@gmail.com> (raw)
In-Reply-To: <20200921143617.2iskdncu3diginqn@localhost.localdomain>
Hi Branden,
On 9/21/20 4:36 PM, G. Branden Robinson wrote:
> At 2020-09-11T12:58:08+0000, Walter Harms wrote:
>> the groff commands are ducument in man 7 groff
>> .nf No filling or adjusting of output-lines.
>> .fi Fill output lines
>>
>> (for me) a typical use is like this:
>> .nf
>>
>> struct timeval {
>> time_t tv_sec; /* seconds */
>> suseconds_t tv_usec; /* microseconds */
>> };
>> .fi
>>
>> In the top section you prevent indenting (if any).
>
> The above will not work as desired for typesetter output, a.k.a., "troff
> devices", such as PostScript or PDF. The initial code indent might work
> okay but the alignment of the field names will become
> ragged/mis-registered and the comments even more so.
Yes.
> This is because a proportional font is used by default for troff
> devices. The classical man macros, going back to Version 7 Unix (1979)
> had no good solution for this problem and Unix room tradition at Murray
> Hill going all the way back to (what we now call) the First Edition
> manual in 1971 was to read the man pages on a typewriter--a Teletype
> Model 33 or Model 37. Typewriters, of course, always[1] used monospaced
> fonts.
>
> Version 9 Unix (1986) introduced .EX and .EE for setting material in a
> monospaced font even if the device used proportional type by default.
> (Plan 9 troff inherited them.) GNU roff has supporteds .EX and .EE as
> well, for over 13 years, and its implementations are ultra-permissively
> licensed so other *roffs like Heirloom Doctools have picked them up.
> Therefore I recommend .EX and .EE for all code examples.
>
> They are very simple to use. In the above, simply replace ".nf" with
> ".EX" and ".fi" with ".EE".
>
> Regards,
> Branden
>
> [1] Not completely true; variable-pitch typewriters (such as 10/12 point
> selectable) were fairly common and some expensive models like the IBM
> Executive even featured true proportional type.
Thanks for the interesting history, Branden!
From time toi time I wonder if the function prototypes in
the SYNOPSIS should also be inside .EX/.EE. Your thoughts?
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-24 8: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) [this message]
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)
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=2862c745-a23a-95d2-157e-7f91f671f839@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).