linux-man.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
To: "mtk.manpages@gmail.com" <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, 22 Sep 2020 00:36:19 +1000	[thread overview]
Message-ID: <20200921143617.2iskdncu3diginqn@localhost.localdomain> (raw)
In-Reply-To: <4ace434523f5491b9efcc7af175ad781@bfs.de>

[-- Attachment #1: Type: text/plain, Size: 1857 bytes --]

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.

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.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

  reply	other threads:[~2020-09-21 14:36 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 [this message]
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)
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=20200921143617.2iskdncu3diginqn@localhost.localdomain \
    --to=g.branden.robinson@gmail.com \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-man@vger.kernel.org \
    --cc=mtk.manpages@gmail.com \
    /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).