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

[Jean Delvare]

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

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