[Quilt-dev] [patch 19/26] Sort options in alphabetical order to ease human scanning.

Index: quilt/doc/quilt.1.in === --- quilt.orig/doc/quilt.1.in +++ quilt/doc/quilt.1.in @@ -160,10 +160,6 @@ if one is specified, otherwise for .I quilt itself) and exit. .TP -.B \\-\\-trace -Runs the command in bash trace mode

[Quilt-dev] [patch 22/26] Wordsmith Exit Status section.

* Eliminate otherwise unused term "sub-command". Index: quilt/doc/quilt.1.in === --- quilt.orig/doc/quilt.1.in +++ quilt/doc/quilt.1.in @@ -201,15 +201,17 @@ internal operations. .B \\-\\-version prints the version number and

[Quilt-dev] [patch 26/26] Rewrite discussion of QUILT_COLORS configuration variable.

These are ANSI escape sequences as defined by ECMA-48; recast the entire discussion in light of that fact. Condense the many tagged paragraphs with a templated discussion of defaults into a table. Sort the QUILT_COLORS format names into alphabetical order. Add a hint to the formatter (man) to

[Quilt-dev] [patch 25/26] Make file tree diagram portable.

Use the groff extension .schar to provide an alternative output sequence for output devices missing the Unicode box-drawing characters. Index: quilt/doc/quilt.1.in === --- quilt.orig/doc/quilt.1.in +++ quilt/doc/quilt.1.in @@ -229,23

[Quilt-dev] [patch 14/26] Document -h flag in the Options section.

Also add a clarifying introductory sentence. Index: quilt/doc/quilt.1.in === --- quilt.orig/doc/quilt.1.in +++ quilt/doc/quilt.1.in @@ -149,6 +149,16 @@ there is no need to clean up manually. .SS Quilt commands reference

[Quilt-dev] [patch 02/26] Eliminate or replace blank lines.

Blank lines are bad roff style. Per CSTR #54, blank lines are the equivalent of ".sp 1", but in GNU roff this can be overridden with a blank line macro (".blm"), and all macro packages for text formatting (mm, ms, me, man, etc.) have macros for paragraph separation, and the inter-paragraph

[Quilt-dev] [patch 01/26] The man macro RE is given an argument when it does not need one.

This causes warnings from roff when the warning level is turned up really high, as some roff/man page hackers do. :891: warning: number register `an-saved-margin2' not defined :891: warning: number register `an-saved-prevailing-indent2' not defined Stop supplying the extraneous argument.

[Quilt-dev] [patch 07/26] Escape ASCII hyphen-minus characters used as such.

When a "literal" ASCII 45 hyphen-minus character is desired, it has to be escaped; this is a requirement going all the way back to Bell Labs Troff, but is frequently overlooked. Getting it right enables accurate cut-and-paste of code examples, filenames, URLs, and so forth from roff documents

[Quilt-dev] [patch 09/26] Use character escapes for directional quotes and spacing tilde.

Also add quotation marks where they make semantic sense. Index: quilt/doc/quilt.1.in === --- quilt.orig/doc/quilt.1.in +++ quilt/doc/quilt.1.in @@ -86,8 +86,8 @@ Different series files can be used to as ways, corresponding for

[Quilt-dev] [patch 04/26] Reorganize sections to use only section names endorsed by man-pages(7), and put them in the recommended order.

Use subsection macro (SS) where helpful. Index: quilt/doc/quilt.1.in === --- quilt.orig/doc/quilt.1.in +++ quilt/doc/quilt.1.in @@ -112,9 +112,9 @@ and refreshing patches .RB ( "quilt refresh" ). Files in the .pc directory are

[Quilt-dev] [patch 12/26] Update internal and external cross-references.

Embolden internal subsection reference, and refer to its parent section. Point explicitly to the GNU Diffutils manual regarding unified diff format, and add cross-reference in the See Also section. Add cross-reference to diffstat man page. Sort man page cross-reference list in alphabetical

[Quilt-dev] [patch 00/26] doc/quilt.1.in refactor revisited

Hi folks, Last month I sent a message[1] with a monolith of changes to the quilt man page. Here it is, improved (IMO), and in a form I hope is friendlier and easier to integrate. Thanks to Andreas Grünbacher and Jean Delvare for their encouragement. [1]

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

Also reflow input lines to 72 columns. Index: quilt/doc/quilt.1.in === --- quilt.orig/doc/quilt.1.in +++ quilt/doc/quilt.1.in @@ -8,19 +8,24 @@ quilt \\- tool to manage series of patch [-h] command [options] .SH DESCRIPTION Quilt

[Quilt-dev] [patch 11/26] Italicize work titles.

...including names of software projects (such as quilt itself). Index: quilt/doc/quilt.1.in === --- quilt.orig/doc/quilt.1.in +++ quilt/doc/quilt.1.in @@ -18,22 +18,31 @@ quilt \\- tool to manage series of patch .SY "quilt

[Quilt-dev] [patch 18/26] Change the form of the word "subdirectory".

Per style recommendation in man-pages(7). Index: quilt/doc/quilt.1.in === --- quilt.orig/doc/quilt.1.in +++ quilt/doc/quilt.1.in @@ -59,7 +59,7 @@ By default, most commands apply to the t .PP Patch files are located in the .I

[Quilt-dev] [patch 06/26] Use groff_man(7)s EX and EE macros for examples.

This eliminates the use of low-level requests in this man page (the groffism ".fam" to change the font family and the switching off and on of fill mode with ".nf" and ".fi".) Index: quilt/doc/quilt.1.in === ---

[Quilt-dev] [patch 08/26] Make synopsis comprehensive.

Document --quiltrc, --trace, and --version options explicitly. Separate the informational operation modes for reporting help and version information. Mark up synopsis canonically (literals in bold, variable content in italics, and roman for "synopsis language" (option brackets, etc.)). Use

[Quilt-dev] [patch 16/26] Render Andreas Gruenbachers name with a u-umlaut.

Revised 2018-06-07 to rename patch and use .schar instead of string definition. Index: quilt/doc/quilt.1.in === --- quilt.orig/doc/quilt.1.in +++ quilt/doc/quilt.1.in @@ -447,10 +447,11 @@ QUILT_COLORS='diff_hdr=35;44' .RE .EE .SH

[Quilt-dev] [patch 13/26] Set filespecs and environment variable names in italics.

Variable content in an italic context is set in roman for contrast, but still in italics in running roman prose. Index: quilt/doc/quilt.1.in === --- quilt.orig/doc/quilt.1.in +++ quilt/doc/quilt.1.in @@ -71,9 +71,7 @@ When not found

[Quilt-dev] [patch 21/26] Wordsmith Options section.

* Make tagged paragraphs readable as paragraphs (try it aloud). * Don't introduce a metavariable without explaining it or using it in context. Index: quilt/doc/quilt.1.in === --- quilt.orig/doc/quilt.1.in +++ quilt/doc/quilt.1.in

[Quilt-dev] [patch 05/26] Use font macros instead of font escapes.

Apart from being higher-level and easier to read, the macros get you proper italic corrections when abutting italic with non-italic text. Index: quilt/doc/quilt.1.in === --- quilt.orig/doc/quilt.1.in +++ quilt/doc/quilt.1.in @@

[Quilt-dev] [patch 10/26] Use "e.g." correctly.

The Latin "exempli gratia" is abbreviated "e.g.". Also, use a zero-width-space escape to defeat roff's end-of-sentence detection. See section 4.1 of CSTR #54, "Troff User's Manual", Ossanna & Kernighan . Index: quilt/doc/quilt.1.in

Re: [Quilt-dev] [patch 02/26] Eliminate or replace blank lines.

At 2018-06-17T22:26:00+0200, Jean Delvare wrote: > Hi Branden, Hi Jean! > Hmmm. I see the improvement in the formatted output, but the absence > of blank lines in the man page "source" make it pretty hard to read > now. I would appreciate some form of spacing at least before each > section to

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

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.robin...@gmail.com

Re: [Quilt-dev] [patch 04/26] Reorganize sections to use only section names endorsed by man-pages(7), and put them in the recommended order.

At 2018-06-17T23:04:08+0200, Jean Delvare wrote: > On Sat, 16 Jun 2018 12:22:36 -0400, g.branden.robin...@gmail.com wrote: > > Use subsection macro (SS) where helpful. > > That one is harder to review... I think most of your concerns are addressed by subsequent patches. In this one I was trying

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

Hi folks, In the course of trying to figure out why "quilt graph --all" wasn't working the way I expected, I was wondering why the quilt man page didn't look like others I work with and a look at its sources revealed that it did a few things unconventionally. As a groff and man-pages project

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

At 2018-06-01T13:11:40+0200, Andreas Grünbacher wrote: > Branden, Hi Andreas! > 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

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

[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 ha

Re: [Quilt-dev] [patch 01/26] The man macro RE is given an argument when it does not need one.

At 2018-06-17T22:15:09+0200, Jean Delvare wrote: > For next time: no final dot at end of subjects please ;-) Can do. Is it all right to use the DESC/EDESC approach for my next spin of these patches? -- Regards, Branden signature.asc Description: PGP signature

Re: [Quilt-dev] [patch 01/26] The man macro RE is given an argument when it does not need one.

At 2018-06-21T12:49:02+0200, Jean Delvare wrote: > On Thu, 2018-06-21 at 06:20 -0400, G. Branden Robinson wrote: > > At 2018-06-17T22:15:09+0200, Jean Delvare wrote: > > > For next time: no final dot at end of subjects please ;-) > > > > Can do. Is it all right

Re: [Quilt-dev] [patch 26/26] Rewrite discussion of QUILT_COLORS configuration variable.

Hi, Jean! Thanks for the in-depth review of my monstrous patch sequence! I'll reply inline for this one but mainly I wanted to ack your review and let you know that I'll be getting back to these soon but probably not immediately. At 2018-06-26T19:00:48+0200, Jean Delvare wrote: > > Add a hint

Re: [Quilt-dev] [patch 26/26] Rewrite discussion of QUILT_COLORS configuration variable.

At 2018-09-17T17:36:23+0200, Jean Delvare wrote: > Hi Branden, Hi Jean! > > On Fri, 2018-06-29 at 09:13 -0400, G. Branden Robinson wrote: > > Thanks for the in-depth review of my monstrous patch sequence! > > > > I'll reply inline for this one but mainly I wanted to

Re: [Quilt-dev] [patch 02/26] Eliminate or replace blank lines.

At 2018-06-17T22:26:00+0200, Jean Delvare wrote: > On Sat, 16 Jun 2018 12:22:34 -0400, g.branden.robin...@gmail.com wrote: > > Blank lines are bad roff style. Per CSTR #54, blank lines are the > > equivalent of ".sp 1", but in GNU roff this can be overridden with a > > blank line macro (".blm"),

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

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.robin...@gmail.com

Re: [Quilt-dev] [patch 04/26] Reorganize sections to use only section names endorsed by man-pages(7), and put them in the recommended order.

Hi Jean, At 2018-06-17T23:04:08+0200, Jean Delvare wrote: > On Sat, 16 Jun 2018 12:22:36 -0400, g.branden.robin...@gmail.com wrote: > > Use subsection macro (SS) where helpful. I have to admit I'm not clear on the state of this one's acceptance. Reviewing your last mail to me on item 4 in this

Re: [Quilt-dev] [patch 26/26] Rewrite discussion of QUILT_COLORS configuration variable.

Hi Jean, At 2022-07-04T14:18:11+0200, Jean Delvare wrote: > Hi Branden, > > On Tue, 2 Oct 2018 03:34:22 -0400, G. Branden Robinson wrote: > > Thanks for your review of these patches; I think we had a good meeting > > of the minds. Just needs that final push. > >

Re: [Quilt-dev] [patch 05/26] Use font macros instead of font escapes.

At 2018-06-20T10:24:30+0200, Jean Delvare wrote: > On Sat, 16 Jun 2018 12:22:37 -0400, g.branden.robin...@gmail.com wrote: > > Apart from being higher-level and easier to read, the macros get you > > proper italic corrections when abutting italic with non-italic text. > > (...) > > Looks good to

Re: [Quilt-dev] [patch 07/26] Escape ASCII hyphen-minus characters used as such.

Hi Jean, At 2018-06-20T11:33:25+0200, Jean Delvare wrote: > On Sat, 16 Jun 2018 12:22:39 -0400, g.branden.robin...@gmail.com wrote: > > When a "literal" ASCII 45 hyphen-minus character is desired, it has > > to be escaped; this is a requirement going all the way back to Bell > > Labs Troff, but

Re: [Quilt-dev] [patch 06/26] Use groff_man(7)s EX and EE macros for examples.

At 2018-06-20T11:24:34+0200, Jean Delvare wrote: > On Sat, 16 Jun 2018 12:22:38 -0400, g.branden.robin...@gmail.com wrote: > > This eliminates the use of low-level requests in this man page (the > > groffism ".fam" to change the font family and the switching off and > > on of fill mode with ".nf"

Re: [Quilt-dev] [patch 25/26] Make file tree diagram portable.

At 2022-07-25T16:14:46+0200, Jean Delvare wrote: > On Tue, 26 Jun 2018 13:41:55 +0200, Jean Delvare wrote: > > On Sat, 16 Jun 2018 12:22:57 -0400, g.branden.robin...@gmail.com wrote: > > > Use the groff extension .schar to provide an alternative output > > > sequence for output devices missing the

Re: [Quilt-dev] [patch v2 12/26] Man page: update internal and external cross-references

Hi Jean, At 2022-07-26T14:43:20+0200, Jean Delvare wrote: > Embolden internal subsection reference, and refer to its parent > section. In the groff man pages I do not use boldface for section or subsection cross references; instead I use simple quotation (that is, I surround the (sub)section

Re: [Quilt-dev] [patch v2 13/26] Man page: set filespecs and environment variable names in italics

Hi Jean, At 2022-07-26T14:43:21+0200, Jean Delvare wrote: > Variable content in an italic context is set in roman for contrast, but > still in italics in running roman prose. > > [JD: Revert some of the changes which did not belong there, and > restored the original indentation level as I think

Re: [Quilt-dev] [patch v2 04/26] Man page: reorganize sections

Hi Jean, Ah, this new series is _much_ easier to review--thank you! At 2022-07-26T14:43:12+0200, Jean Delvare wrote: > Use only section names endorsed by man-pages(7), and put them in the > recommended order. > Use subsection macro (SS) where helpful. > > [JD: Preserve the EXAMPLE section] The

Re: [Quilt-dev] [patch v2 26/26] Man page: rewrite discussion of QUILT_COLORS configuration variable

Hi Jean, No particular comments on this one except to say that I've read through all of them (except 01/26, which didn't appear in my inbox) and everything looks good to me. Did you have any other questions pending for me? groff maintenance and development has grown into quite an avocation for

Re: [Quilt-dev] [patch v2 16/26] Man page: render Andreas Gruenbachers name with a u-umlaut

Hi Jean, The first piece of this patch is erroneous. 4-5 years ago I didn't clearly understand the difference between "special" fonts and non-special fonts in *roff. Now I do. The u-with-umlaut character is "regular", or from a "text font", meaning it may have different styles available (bold,