[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
_______________________________________________ Quilt-dev mailing list Quilt-dev@nongnu.org https://lists.nongnu.org/mailman/listinfo/quilt-dev