Re: [Quilt-dev] [patch 03/26] Break input lines at all sentence endings.

[G. Branden Robinson]

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, g.branden.robinson@gmail.com 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/quilt-dev@nongnu.org/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.

       • 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)

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).

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?

Regards,
Branden

signature.asc
Description: PGP signature