Re: [RFCv2] man-pages.7: Add phrasal semantic newlines advise
flat view
From: G. Branden Robinson <hidden>
Date: 2021-11-22 07:37:06
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.
quoted hunk ↗ jump to hunk
-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
Attachments
- signature.asc [application/pgp-signature] 833 bytes