Re: semantic newlines?

[Alejandro Colomar]

Hi!

On 5/21/23 21:48, Bruno Haible wrote:
> Hi,
> 
> Diffs of .texi files are often hard to review, because the committer has
> reformatted (refilled) the paragraph.
> 
> The Linux man-pages project has this guidance to avoid this problem (in
> groff -mandoc source, not in .texi files): [1]

Well, the recommendation is generic, and should apply even for book
authors I guess, even if we only write man(7) and maybe mdoc(7) pages.

> 
>     Use semantic newlines
>        In the source of a manual page, new sentences should be started
>        on new lines, and long sentences should be split into lines at
>        clause breaks (commas, semicolons, colons, and so on).  This
>        convention, sometimes known as "semantic newlines", makes it
>        easier to see the effect of patches, which often operate at the
>        level of individual sentences or sentence clauses.

That wording is the one from man7.org, which is outdated with
respect to the current manual page:

   Use semantic newlines
       In the source of a manual page, new sentences should be started
       on  new  lines,  long  sentences  should be split into lines at
       clause breaks (commas, semicolons, colons, and so on), and long
       clauses should be split at phrase boundaries.  This convention,
       sometimes known as "semantic newlines", makes it easier to  see
       the  effect of patches, which often operate at the level of in‐
       dividual sentences, clauses, or phrases.

This new wording is even more strict, and was added in this commit:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man7/man-pages.7?id=6ff6f43d68164f99a8c3fb66f4525d145571310c>

(and slightly reworded in this one:)

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man7/man-pages.7?id=c8d99e2c6dbf53f7c0edbae588ce6dde64cb7a20

Here's the commit that made the wording more strict, which contains
some more details about why we use them, and is itself a perfect
example of why they are good:


commit 6ff6f43d68164f99a8c3fb66f4525d145571310c
Author: Alejandro Colomar <alx@kernel.org>
Date:   Fri Nov 12 22:38:11 2021 +0100

    man-pages.7: Add phrasal semantic newlines advise
    
    Brian W. Kernighan, 1974 [UNIX For Beginners]:
    
    [
    Hints for Preparing Documents
    
    Most documents go through several versions
    (always more than you expected)
    before they are finally finished.
    Accordingly,
    you should do whatever possible
    to make the job of changing them easy.
    
    First,
    when you do the purely mechanical operations of typing,
    type so subsequent editing will be easy.
    Start each sentence on a new line.
    Make lines short,
    and break lines at natural places,
    such as after commas and semicolons,
    rather than randomly.
    Since most people change documents
    by rewriting phrases and
    adding, deleting and rearranging sentences,
    these precautions simplify any editing you have to do later.
    ]
    
    He mentioned phrases,
    and they are indeed commonly the operands of patches
    (see this patch's changes (the second part) as an example),
    so they make for a much better breaking point than random
    within a clause that is too long to fit a line.
    
    The downside is that they are more difficult to automatically spot
    than clause breaks (which tend to have associated punctuation).
    But we are humans writing patches,
    not machines,
    and therefore we should be able to decide and detect them better.
    
    Link: <https://rhodesmill.org/brandon/2012/one-sentence-per-line/>
    Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
    Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

diff --git a/man7/man-pages.7 b/man7/man-pages.7
index 23015b00a..b52a2260a 100644
--- a/man7/man-pages.7
+++ b/man7/man-pages.7
@@ -640,11 +640,13 @@ .SS Formatting conventions for manual pages describing 
functions
 .SS Use semantic newlines
 In the source of a manual page,
 new sentences should be started on new lines,
-and long sentences should be split into lines at clause breaks
-(commas, semicolons, colons, and so on).
+long sentences should be split into lines at clause breaks
+(commas, semicolons, colons, and so on),
+and long clauses should be split at phrase boundaries.
 This convention, sometimes known as "semantic newlines",
 makes it easier to see the effect of patches,
-which often operate at the level of individual sentences or sentence clauses.
+which often operate at the level of
+individual sentences, sentence clauses, or phrases.
 .\"
 .SS Formatting conventions (general)
 Paragraphs should be separated by suitable markers (usually either

> 
> Has anyone already used this convention for .texi files? Is it a
> good convention to follow?

+1

Cheers,
Alex

> 
> Bruno
> 
> [1] https://man7.org/linux/man-pages/man7/man-pages.7.html
> 
> 
> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

OpenPGP_signature
Description: OpenPGP digital signature