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

[Michael Kerrisk (man-pages)]

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/