Re: [PATCH 22/24] membarrier.2: Note that glibc does not provide a wrapper

[G. Branden Robinson]

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: signature.asc
Description: PGP signature