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 <a...@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.robin...@gmail.com> Signed-off-by: Alejandro Colomar <alx.manpa...@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