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:
signature.asc
Description: PGP signature
