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

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

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

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.

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
**************************

Most users tend to use a macro package to format their papers.  This
means that the whole breadth of 'groff' is not necessary for most
people.  This chapter covers the material needed to efficiently use a
macro package.
[...]
   * In keeping with this, it is helpful to begin a new line after every
     comma or phrase, since common corrections are to add or delete
     sentences or phrases.

   * 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.
]]

This advice, in the context of macro package usage, is scoped too
narrowly.  The manual has a later section which makes the point again.

[[
5.1.6 Input Conventions
-----------------------

Since 'gtroff' does filling automatically, it is traditional in 'groff'
not to try and type things in as nicely formatted paragraphs.  These are
some conventions commonly used when typing 'gtroff' text:

   * Break lines after punctuation, particularly at the end of a
     sentence and in other logical places.  Keep separate phrases on
     lines by themselves, as entire phrases are often added or deleted
     when editing.

   * Try to keep lines less than 40-60 characters, to allow space for
     inserting more text.

   * Do not try to do any formatting in a WYSIWYG manner (i.e., don't
     try using spaces to get proper indentation).
]]

I have written new material for groff's Texinfo manual in the
forthcoming 1.23.0 release.  The above section is significantly expanded
and, happily for skeptics of GNU Texinfo, ported to a man page as well.
The roff(7) page bears the fruit of much labor, including the following.

[[
Input conventions
       Since troff fills text automatically, it is common practice in
       roff languages to not attempt careful visual composition of text
       in input files: it is the esthetic appeal of the formatted output
       that matters.  Therefore, roff input should be arranged such that
       it is easy for authors and maintainers to compose and develop the
       document, understand the syntax of roff requests, macro calls,
       and preprocessor languages used, and predict the behavior of the
       formatter.  Several traditions have accrued in service of these
       goals.

       •      Break input lines after sentence‐ending punctuation to
              ease their recognition.  It is frequently convenient to
              break after colons and semicolons as well, as these
              typically precede independent clauses.  Consider breaking
              after commas; they often occur in lists that become easy
              to scan when itemized by line, or constitute supplements
              to the sentence that are added, deleted, or updated to
              clarify it.  Parenthetical and quoted phrases are also
              good candidates for placement on input lines by
              themselves.  In filled text, spaces and newlines are
              interchangeable; place breaks where it aids your purpose.

       •      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.

       •      Use \& after “!”, “?”, and “.” if they are followed by
              space, tab, or newline characters and don’t end a
              sentence.

       •      In filled text lines, use \& before “.” and “'” if they
              are preceded by space, so that reflowing the input doesn't
              turn them into control lines.

       •      Do not attempt to format the input in a WYSIWYG manner
              (i.e., don’t try using spaces to get proper indentation or
              align columns of a table).

       •      Comment your document.  It is never too soon to apply
              comments to record information of use to future document
              maintainers (including your future self).  The \" escape
              sequence causes troff to ignore the remainder of the input
              line.

       •      Use the empty request—a control character followed
              immediately by a newline—to visually manage separation of
              material in input files.  Many of the groff project’s own
              documents use an empty request between sentences, after
              macro definitions, and where a break is expected, and two
              empty requests between paragraphs or other requests or
              macro calls that will introduce vertical space into the
              document.  You can combine the empty request with the
              comment escape sequence to include whole‐line comments in
              your document, and even “comment out” sections of it.
]]

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.

Regards,
Branden

[1] https://rhodesmill.org/brandon/2012/one-sentence-per-line/

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