Re: [patch] Add docs on mount namespace rootfs access and pid namespace pid mapping

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

Hi, Branden!

On 3/20/22 15:53, G. Branden Robinson wrote:
> Hi, Alex!
> 
> At 2022-03-14T15:05:49+0100, Alejandro Colomar (man-pages) wrote:
>> Always start sentences after '.' in a new line.
>> That's already covered by "semantic newlines" (see above),
>> but it's especially important in this case because
>> groff(1) prints (at least) 2 spaces after '.' normally,
>> but if you write it this way it doesn't.
>>
>> BTW, Branden,
>> I CCd you because I didn't find this documented in groff(7),
>> or at least I couldn't find it.
>> I tried /\.[^ [a-z]] and also keywords like period, point or dot,
>> but no luck.
>> Is it documented anywhere?
> 
> It used to be one of those things everybody just "knew" about writing in
> *roff--back when people hung on Brian Kernighan's every word[1]--but
> over the years the knowledge has atrophied.

Okay.
> 
> The groff 1.22.4 Texinfo manual has the following.  I believe this
> material is adapted from Eric Allman's paper "Writing Papers with NROFF
> using -me".
> 
> [[
> 3 Tutorial for Macro Users
> **************************
> 
[...]
> 
>    * End each sentence with two spaces - or better, start each sentence
>      on a new line.  'gtroff' recognizes characters that usually end a
>      sentence, and inserts sentence space accordingly.

Ahh, that paragraph is what I was looking for.

[...]
> 
>        •      Set your text editor’s line length to 72 characters or
>               fewer; see the subsections below.  This limit, combined
>               with the previous advice regarding breaking around
>               punctuation, makes it less common that an input line will
>               wrap in your text editor, and thus will help you perceive
>               excessively long constructions in your text.  Recall that
>               natural languages originate in speech, not writing, and
>               that punctuation is correlated with pauses for breathing
>               and changes in prosody.

That last line should be reminded more often :)

[...]
> This point about beginning sentences only on new input lines _is_
> missing from groff_man_style(7).  As noted in the groff 1.22.4 NEWS
> file:
> 
> o ... groff_man(7) has been expanded and largely rewritten ... to be
>   more helpful and accessible to man page writers who may never read any
>   other groff documentation.
> 
> groff_man_style(7) is now fulfilling this role, since a quick reference
> for experienced man page writers remains desirable.  (I avoid letting
> the two drift out of sync by generating both from an m4 master
> document.)
> 
> I've been dithering over writing a new introductory section just for
> groff_man_style(7) to present an example of a partial man page and use
> it to explain typesetting terms that are inescapable even in the reduced
> domain of man pages: breaking, filling, adjustment, hyphenation, and the
> notorious matter of supplementary inter-sentence space.
> 
> As you will have observed, when I write in a hurry, I write a lot.  The
> foregoing notional material needs to be written well, and that means
> taking the time to cook the fat off.

I'll try to find some time to read the whole pages...

Thank you very much for your (very) detailed responses! :-)

Cheers,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/