From 4dfeb670df7930a76de64611fff2256df0319bf6 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Fri, 13 Sep 2019 15:37:34 +0200 Subject: [PATCH] man-pages.7: Relocate and enhance the text on semantic newlines Signed-off-by: Michael Kerrisk --- man7/man-pages.7 | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/man7/man-pages.7 b/man7/man-pages.7 index 58357cd82..819dccd97 100644 --- a/man7/man-pages.7 +++ b/man7/man-pages.7 @@ -102,10 +102,6 @@ Please limit source code line length to no more than about 75 characters wherever possible. This helps avoid line-wrapping in some mail clients when patches are submitted inline. -.PP -New sentences should be started on new lines. -This makes it easier to see the effect of patches, -which often operate at the level of individual sentences. .SS Title line The first command in a man page should be a .B TH @@ -527,7 +523,17 @@ The preferred way to write this in the source file is: (Using this format, rather than the use of "\efB...\efP()" 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 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. +.\" .SS Formatting conventions (general) +.PP Paragraphs should be separated by suitable markers (usually either .I .PP or