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@xxxxxxxxx> Signed-off-by: Alejandro Colomar <alx.manpages@xxxxxxxxx> --- 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
