[RFC] man-pages.7: Add phrasal semantic newlines advise

[RFC] man-pages.7: Add phrasal semantic newlines advise

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---
 man7/man-pages.7 | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

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 @@ makes it easier to write tools that parse man page source files.)
 .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
-- 
2.33.1

[RFCv2] man-pages.7: Add phrasal semantic newlines advise

[Alejandro Colomar]

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>
---
 man7/man-pages.7 | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

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 @@ makes it easier to write tools that parse man page source files.)
 .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
-- 
2.33.1

Re: [RFCv2] man-pages.7: Add phrasal semantic newlines advise

[G. Branden Robinson]

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

Hi, Alex!

At 2021-11-13T01:06:15+0100, Alejandro Colomar wrote:
> 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.
> ]

Sound advice worth quoting if space permits, and linking to if it does
not.

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

I, do, however, find the free verse style more difficult to read in
email, as a rule.  A brain is a modal thing, and when I'm reading emails
I'm generally prepared for prose.  When I'm editing a man page, my mind
is in a different mode, and better prepared for the foregoing textual
style.

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

I would drop the qualifier "sentence" from "sentence clause(s)" here.
One wonders, "what's a NON-sentence clause"?  Just "clauses" is fine.

This noun is not otherwise used in the man-pages project except very
rarely to refer to items in legal notices, another standard usage with a
clearly distinct context.  In the context of the patch, the discussion
is obviously grammatical and sentential.

Apart from that, LGTM!

Regards,
Branden

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

Re: [RFCv2] man-pages.7: Add phrasal semantic newlines advise

[Alejandro Colomar (man-pages)]

Hi, Branden!

On 11/22/21 08:37, G. Branden Robinson wrote:
>> 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.
> 
> I, do, however, find the free verse style more difficult to read in
> email, as a rule.  A brain is a modal thing, and when I'm reading emails
> I'm generally prepared for prose.  When I'm editing a man page, my mind
> is in a different mode, and better prepared for the foregoing textual
> style.

Sorry :)

>>   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.
> 
> I would drop the qualifier "sentence" from "sentence clause(s)" here.
> One wonders, "what's a NON-sentence clause"?  Just "clauses" is fine. >
> This noun is not otherwise used in the man-pages project except very
> rarely to refer to items in legal notices, another standard usage with a
> clearly distinct context.  In the context of the patch, the discussion
> is obviously grammatical and sentential.

Makes sense; will do.

> 
> Apart from that, LGTM!
> 
> Regards,
> Branden
> 


Thanks!
Alex


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