On Tue, 12 Jul 2022 08:45:07 -0500, G. Branden Robinson wrote: > At 2018-06-17T22:32:17+0200, Jean Delvare wrote: > > The rationale for this change should be explained. I know we discussed > > it on the list, but developers browsing the git history won't easily > > get access to that discussion. > > > > On Sat, 16 Jun 2018 12:22:35 -0400, [email protected] wrote: > > > Also reflow input lines to 72 columns. > > > > The rationale for this could also be explained, even if it is possible > > to guess. > > > > I am perfectly fine with the changes themselves. > > I show the last discussion of this being a message from you. > > https://www.mail-archive.com/[email protected]/msg02455.html > > This is probably more rationale/justification than you need, but I do > happen to have some handy. ;-) > > Here's what groff's documentation says these days in its Git repository. > > Input conventions > Since troff fills text automatically, it is common practice in > roff languages to avoid visual composition of text in input > files: the esthetic appeal of the formatted output is what > matters. Therefore, roff input should be arranged such that it > is easy for authors and maintainers to compose and develop the > document, understand the syntax of roff requests, macro calls, > and preprocessor languages used, and predict the behavior of the > formatter. Several traditions have accrued in service of these > goals. > > • Follow sentence endings in the input with newlines to ease > their recognition. It is frequently convenient to end text > lines after colons and semicolons as well, as these typically > precede independent clauses. Consider doing so after commas; > they often occur in lists that become easy to scan when > itemized by line, or constitute supplements to the sentence > that are added, deleted, or updated to clarify it. > Parenthetical and quoted phrases are also good candidates for > placement on text lines by themselves.
I used line breaks between sentences only (as you did in your original submission if memory serves). I found that breaking after commas hindered readability more than it helped. I'm not really decided about colons and semicolons, but there aren't that many so I guess it doesn't really matter. > > • Set your text editor’s line length to 72 characters or fewer; > see the subsections below. This limit, combined with the > previous item of advice, makes it less common that an input > line will wrap in your text editor, and thus will help you > perceive excessively long constructions in your text. Recall > that natural languages originate in speech, not writing, and > that punctuation is correlated with pauses for breathing and > changes in prosody. > > • Use \& after “!”, “?”, and “.” if they are followed by space, > tab, or newline characters and don’t end a sentence. > > • In filled text lines, use \& before “.” and “'” if they are > preceded by space, so that reflowing the input doesn’t turn > them into control lines. > > • Do not use spaces to perform indentation or align columns of a > table. > > • Comment your document. It is never too soon to apply comments > to record information of use to future document maintainers > (including your future self). The \" escape sequence causes > troff to ignore the remainder of the input line. > > • Use the empty request—a control character followed immediately > by a newline—to visually manage separation of material in input > files. Many of the groff project’s own documents use an empty > request between sentences, after macro definitions, and where a > break is expected, and two empty requests between paragraphs or > other requests or macro calls that will introduce vertical > space into the document. You can combine the empty request > with the comment escape sequence to include whole‐line comments > in your document, and even “comment out” sections of it. > (from roff(7) and groff's Texinfo manual) OK, now that's a bit long for a patch header, plus there's little point in duplicating these explanations. I think it's better to just redirect the interested reviewer to the source of information. At the moment, my header looks like this: Subject: Man page: break input lines at all sentence endings Also reflow input lines to 72 columns. Both are recommended by *roff experts: https://www.gnu.org/software/groff/manual/html_node/Input-Conventions.html > Line length tastes naturally vary, with anything between about 40 and 80 > columns as defensible. In my experience, 72 works well because it > affords a few levels of quoting in email discussions without running > past 80 on traditional terminals. It's pretty solidly (albeit not > perfectly) standardized in the source of the groff project itself, and > over the years I've improved that consistency particularly in the *roff > documents that the project ships (mostly man pages, but other files, > too, using the "me" and "ms" macro packages). I've followed your 72 columns recommendation as I found the argumentation convincing. > As with indentation style and the tabs vs. spaces dispute, I feel that > the specific identity of the standard selected is less important than > choosing and adhering to one in the first place, with editor aid > comments supporting it, to reduce the amount of irrelevant churn in > diffs. > > Do you still need to me to re-submit these patches? In your recent mail > reviving this patch series, you mentioned that you'd rebased them > against current quilt HEAD--is there a branch I should check out? The rebased series currently lives as a quilt patch set on my local drive. I plan to submit it for review when I'm done with it. I reached patch 23/26 during my hack week project, then had to move to other topics (including a well deserved week of offline vacation). I'm resuming my work on it this week and hope to be done by Friday. I suggest you don't touch the "code" on your side for now to avoid collisions. Your comments are still very welcome of course :-) -- Jean Delvare SUSE L3 Support _______________________________________________ Quilt-dev mailing list [email protected] https://lists.nongnu.org/mailman/listinfo/quilt-dev
