Re: [Quilt-dev] [PATCH] clean up the quilt man page

[G. Branden Robinson]

[replying only to list]

At 2018-06-05T13:17:04+0200, Jean Delvare wrote:
> Hi Branden and Andreas,
> 
> On Fri, 1 Jun 2018 07:35:33 -0400, G. Branden Robinson wrote:
> > At 2018-06-01T13:11:40+0200, Andreas Grünbacher wrote:
> > > I'm not going to jump ahead of Jean who has been maintaining quilt the
> > > last couple of years, but thanks, your changes look like an
> > > improvement. The patch is somewhat difficult to review because it
> > > mixes formatting and content changes, so that may take a while.  
> 
> To be honest, I started looking into it last Friday, but the patch was
> so large and raised so many questions (because I don't know much about
> *roff really, just enough to survive) that I had to switch to something
> more urgent before going to the end, and then I forgot about it.
> Smaller patches are clearly easier to process.

Totally fair.  I went in without scope control and the outcome was
predictable.  :)

> About that... Personally I find it harder to read, because a line break
> between 2 sentences looks like a change of paragraph to me.

That's a misleading expectation in *roff.  A line break between two
sentences _never_ means a change of pargraph, at least not without some
deep and clever hackery that I've never seen done in practice.

> Is there actually any benefit of using a line break instead of two
> spaces, other than personal preference?

I keep meaning to write down the canonical list of all the reasons, and
I have vague memories of someone demonstrating an operational
difference, but I haven't been able to find the link.  Here are the
reasons I _can_ remember:

1. All the advice from *roff experts (traditional Unix DWB troff and GNU
groff as well) says to do it.  E.g.,
https://www.gnu.org/software/groff/manual/html_node/Input-Conventions.html

While I'm appealing to authority, I should note that adjacent bits of
advice are frequently not taken, even by *roff experts.  Breaking input
lines after phrase boundaries is seen only occasionally, and I've seen
very few *roff source documents that deliberately limit the line length
to 60 characters or fewer.  In English prose, if you break after every
sentence or phrase ending in a comma, it's hard to get that far anyway.

Point 3 about not attempting to format in a WYSIWYG way, however, is
widely respected.  Failure to heed that advice usually comes to grief,
especially when a document is prepared for an output format that the
writer did not expect (PDF vs. a UTF-8 terminal or vice-versa).

2. It makes life a little easier on translation tools, such that
sentence boundaries can be simply identified just by line numbers.

3. It can make diffs a little easier to read.  (An advantage thoroughly
wasted in my original monolith, I admit.)

> Sounds like a great plan. If you are able to split the changes into 3
> or 4 patches, that should make the last one small enough to be
> reviewable, even if it contains a mix of "all the rest".

Yes, actually I've been working on this and I'm to 25 separate patches
now.

> Specifically, sections reorganization must be a separate patch because
> it is intrusive.

Absolutely.

> The first two points above, however, can be 2 patches
> or 1 patch, I'm fine either way, because they are somewhat related and
> should not collide with each other - so whatever is easier for you.

That occurred to me as well but I still kept them separate, since the
blank line issue is much more demonstrably a problem (it visibly changes
the spacing between paragraph when compared to using paragraph macros),

> Believe me, I'm not going to make your life harder than strictly
> needed for my reviewing needs, I'm very happy to have a *roff
> specialist at my fingertips to clean up our man page, so I am going to
> trust you on everything.
> 
> Thank you very much,

Thank _you_!

I'm attaching my progress so far.  I have not yet redone the
QUILT_COLORS work.  The use of raw UTF-8 characters in the input for the
file tree diagram is one of those things that goes badly wrong when not
outputting to a UTF-8 terminal.  The patch correcting that is
in-progress; I am not au fait with pic and it's my intention to ask the
groff mailing list for advice from more experienced pic users.

Here's the output of "quilt series" corresponding to the attachment.

Every patch with an explanatory header is ready for review (and commit,
if acceptable).  That's all of them except
"make-file-tree-diagram-portable", discussed above.

patches/quilt.1.in-fix-roff-warning.patch
patches/quilt.1.in-replace-blank-lines-in-roff-input.patch
patches/quilt.1.in-break-input-lines-at-sentence-endings.patch
patches/quilt.1.in-reorganize-sections-and-use-subsections.patch
patches/quilt.1.in-use-font-macros-instead-of-font-escapes.patch
patches/quilt.1.in-use-EX-and-EE-macros-instead-of-roff-requests.patch
patches/quilt.1.in-escape-ASCII-hyphens.patch
patches/quilt.1.in-improve-synopsis.patch
patches/quilt.1.in-use-character-escapes-for-directional-quotes-and-tildes.patch
patches/quilt.1.in-fix-e.g.-usage.patch
patches/quilt.1.in-italicize-work-titles.patch
patches/quilt.1.in-update-cross-references.patch
patches/quilt.1.in-italicize-filespecs-and-environment-variables.patch
patches/quilt.1.in-document-h-flag-in-options-section.patch
patches/quilt.1.in-change-pdf-to-PDF.patch
patches/quilt.1.in-use-e-umlaut-character-escape.patch
patches/quilt.1.in-shorten-summary.patch
patches/quilt.1.in-change-sub-directory-to-subdirectory.patch
patches/quilt.1.in-alphabetize-options.patch
patches/quilt.1.in-wordsmith-description-section.patch
patches/quilt.1.in-wordsmith-options-section.patch
patches/quilt.1.in-wordsmith-exit-status-section.patch
patches/quilt.1.in-wordsmith-environment-section.patch
patches/quilt.1.in-wordsmith-example-of-working-tree-subsection-and-author-section.patch
patches/quilt.1.in-make-file-tree-diagram-portable.patch

Regards,
Branden

quilt.1-refactor-2018-06-05.tar.gz
Description: application/gzip

signature.asc
Description: PGP signature