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

[G. Branden Robinson]

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 me over the past few
years and this patch series was quite the walk down memory lane.  I'm
happy to report that even though I've learned a tremendous amount since
then, I don't think I quite managed to embarrass myself.

Well, maybe the `schar` thing... X-)

Regards,
Branden


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[G. Branden Robinson]

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, oblique/italic, bold-italic), unlike, say, the square
root sign.

The correct groff request to define a fallback for a missing \[:u]
special character escape sequence is therefore.

.fchar \\[:u] ue

(For others reading, and posterity: normally, the backslash would not be
doubled, but quilt.1.in undergoes extra processing to produce quilt.1.)

I will add that, in my opinion, recent versions of the groff_char(7) man
page describe these matters much more clearly.[1]

Regards,
Branden

[1] https://www.dropbox.com/sh/17ftu3z31couf07/AAC_9kq0ZA-Ra2ZhmZFWlLuva?dl=0

At 2022-07-26T14:43:24+0200, Jean Delvare wrote:
> --- quilt.orig/doc/quilt.1.in 2022-07-06 09:47:39.094273219 +0200
> +++ quilt/doc/quilt.1.in  2022-07-06 10:27:42.523006977 +0200
> @@ -474,10 +474,11 @@ QUILT_COLORS='diff_hdr=35;44'
>  .EE
>  .
>  .SH AUTHORS
> +.schar \\[:u] ue
>  .I Quilt
>  started as a series of scripts written by Andrew Morton
>  .RI ( patch\\-scripts ).
> -Based on Andrew's ideas, Andreas Gruenbacher completely rewrote the
> +Based on Andrew's ideas, Andreas Gr\\[:u]nbacher completely rewrote the
>  scripts, with the help of several other contributors (see the file
>  .I AUTHORS
>  in the distribution).
> 


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[G. Branden Robinson]

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 Linux man-pages project uses "EXAMPLES", plural.  FYI.

https://man7.org/linux/man-pages/man7/man-pages.7.html

Regards,
Branden


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[G. Branden Robinson]

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 it looked better]

I have similarly softened on the "no explicit indentation" principle I
held to 4-5 years ago.  Once I got the groff man pages typesetting
nicely as a compiled document in PDF[1], the giant default indentation
grated on me more and more, especially for simple bulleted lists.

Regards,
Branden

[1] https://www.dropbox.com/sh/17ftu3z31couf07/AAC_9kq0ZA-Ra2ZhmZFWlLuva?dl=0


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[G. Branden Robinson]

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 title with \[lq] and \[rq] special character escape
sequences to get "typographer's quotes" where possible).  Just FYI; you
may not want to join this convention.  I have been strongly tempted to
add a "Q" macro to groff_man(7) to make this and other uses of quotation
easier.

> Sort man page cross-reference list in alphabetical order.

In the past 4-5 years I have come to no longer endorse this practice, at
least not when done robotically.

https://lore.kernel.org/linux-man/a2009ae6-7f51-f7c5-e108-f0c89a17a...@gmail.com/T/#md95904290a511f674762328f22813aa891e67978

However, if the man pages listed are co-equal in relevance and
importance, alphabetical order does no harm.

Regards,
Branden


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[G. Branden Robinson]

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 Unicode box-drawing
> > > characters.  
> > (...)
> > One more question below.
> > (...)
> > >  .EE
> > > +.fi  
> > 
> > That "fi" doesn't seem a make a difference, can you explain the
> > purpose?
> 
> I came to the conclusion that this was a leftover from patch
> re-spinning, and decided to removed it. We got rid of all .nf/.fi
> requests in patch 06/26, it would seem illogical to reintroduce one
> here.

Acknowledged and agreed.

Regards,
Branden


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[G. Branden Robinson]

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 is frequently overlooked.  Getting it right enables
> > accurate cut-and-paste of code examples, filenames, URLs, and so
> > forth from roff documents prepared for UTF-8 terminal and PDF
> > output, possibly among others.
> > 
> > See section 2.1 of CSTR #54, "Troff User's Manual", Ossanna &
> > Kernighan .
> 
> I'm curious why hyphens must be double-escaped (\\) while
> double-quotes are only escaped once (\)?

That appears to be an error on my part.  The extra layer of
backslash-escaping is necessary because the quilt.1 file is generated by
make using target rules that process quilt.1.in using the shell's 'read'
and 'echo' built-in commands.

A quick experiment reveals that extra escaping is needed in both cases.
At least with Bash.  I'd be nervous about assuming other shells will
behave exactly the same, even if they claim POSIX-conformance.

$ cat > infile
foo\\bar
foo\"bar
$ while read line; do echo "$line"; done < infile
foo\bar
foo"bar

The second line certainly does not remain a *roff comment.

> Also, I see a number of non-escaped hyphens left, if that on purpose
> or an overlook?
> 
> 12:Patches can be applied, un-applied, refreshed, etc.
> 42:sub-directory of the source tree (see EXAMPLE OF WORKING TREE below).
> 52:directory may contain sub-directories.
> 64:directory; patches may be in sub-directories below this directory.
> 104:patches sub-directory is a convenient location.
> 106:The .pc directory and its sub-directories cannot be relocated, but it
> 133:The exit status is 0 if the sub-command was successfully executed, and
> 282:Used in 'quilt diff' to color the 15-asterisk sequence before or after a

All of the above are idiomatic English prose hyphens, and so do not need
to be escaped.  On output devices that have a separate hyphen character
(like PostScript and PDF), they'll get one.

groff 1.23 will have documentation of why, exactly, *roff systems
distinguish '-' and '\-'.

https://git.savannah.gnu.org/cgit/groff.git/tree/man/groff_char.7.man#n1873

> 247:following syntax - colon (:) separated list of elements, each
> being of

The foregoing should probably be an em dash.  In *roff you can obtain it
with the special character escape sequence '\(em'.  My understanding of
good English style would also not put spaces around it.

> Other than that, looks good, no objection.

Regards,
Branden


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[G. Branden Robinson]

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" and ".fi".)
> > 
> > Index: quilt/doc/quilt.1.in
> > ===
> > --- quilt.orig/doc/quilt.1.in
> > +++ quilt/doc/quilt.1.in
> > @@ -149,9 +149,7 @@ Inherits the existing value of $LESS if
> >  environment, otherwise defaults to "-FRSX".
> >  .SH FILES
> >  .SS "Example of working tree"
> > -.fam C
> > -.RS
> > -.nf
> > +.EX
> >  work/
> >  ├── patches/
> >  │├── series (list of patches to apply)
> > @@ -167,9 +165,7 @@ work/
> >  ││└── ...
> >  │└── ...
> >  └── ...
> 
> I have trouble applying this patch. Because of the special characters
> used to represent the example working tree, the mail was sent as:
> 
> Content-Type: text/plain; charset="iso-8859-15"
> Content-Transfer-Encoding: quoted-printable
> 
> I don't think charset="iso-8859-15" can be right in the first place,
> as the special characters in question are not part of that character
> set.
> 
> In practice, the first hunk gets applied with fuzz 2, and the rest of
> the patch is ignored completely.
> 
> I had a vague memory that "formail" could be used to "decode" such
> transfer encodings but it doesn't seem to work this time. Any idea how
> to solve this problem?
> 
> I could redo the patch manually, but patches 13, 24 and 25 suffer from
> the same problem, so I would prefer to have a clean and fast way to get
> all such patches applied.
> 
> Oh wait, "qprint -d" seems to be doing the trick. It complains when
> processing the email headers (which contain a log of "=" signs but are
> not encoded) but seems to decode the patch itself just fine.
> 
> Nevertheless, a valid charset value (presumably "utf-8") would make the
> patch readable in the email client too, which would be convenient.

I admit I have no idea what caused my email to be sent using that
locale--whether my MUA made that terrible decision or GMail mangled it
somehow.  If you need a re-send on this, I'll double-check the point.

> Patch itself looks good to me, I'm just curious why you removed one
> indentation level for the first example and added one indentation
> level for the second example? I don't really care but this seems
> inconsistent so not really in line with your current effort.

I have no clear memory--but looking back at it, I have to guess that I
was trying to preserve the fact that the second example was indented,
albeit using a different mechanism (leading spaces).  Leading spaces
tend to get inexperienced *roff users into trouble.  I'll quote some new
groff 1.23 documentation.

--snip--
   A line that begins with one or more spaces causes a break.  The
spaces are output at the beginning of the next line without being
_adjusted_ (see below); however, this behavior can be modified (*note
Leading Space Traps::).  Again, macro packages may provide other methods
of producing indented paragraphs.  Trailing spaces on text lines are
discarded.(1)  (*note Breaking-Footnote-1::)
--snip--

When filling is disabled, it's hard for anything too shocking to happen
as a result of leading space usage, but for simplicity I would urge man
page authors to rely solely on man(7) macro calls for indentation
management.

And in fact, I have an undocumented[1] style checker in groff man(7)
that sets up a macro to complain if leading spaces are used.  (It
catches more serious problems, too, like calling a macro with the wrong
number of arguments.)

Back to the issue at hand--if you'd like the indentation of the examples
to be the same, that's easily done.

Regards,
Branden

[1] https://savannah.gnu.org/bugs/index.php?62042


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[G. Branden Robinson]

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 me overall. My only comment would be:
> > -In addition, the \\fBclear\\fP format name is used to turn off special
> > +In addition, the
> > +.B clear
> > +format name is used to turn off special
> >  coloring.
> >  Its value is 0; it is not advised to modify it.
> >  .PP
> 
> "coloring." could be moved at the end of the previous line to make the
> source easier to read.

Acknowledged.

Regards,
Branden


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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.

[G. Branden Robinson]

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 series, I don't feel I
was left with a clear request for explanation or revision, but I'm also
not certain that you were completely satisfied.

https://www.mail-archive.com/quilt-dev@nongnu.org/msg02463.html

However, maybe it's a little easier to return to your initial reply,
below.

> > 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 automatically removed when they are
> >  no longer needed, so there is no need to clean up manually.
> > -.SH QUILT COMMANDS REFERENCE
> > +.SS Quilt commands reference
> >  @REFERENCE@
> > -.SH COMMON OPTIONS TO ALL COMMANDS
> > +.SH OPTIONS
> 
> I understand the rationale for renaming the section, however the
> information "common to all commands" is lost in the process, while I
> believe it was valuable (in contrast with all options listed under
> "Quilt commands reference", which are command-specific.) I think it
> should be reintegrated as an introduction message before the first
> option.

Yes, I think that's a good idea.  Alternatively, `SS` could be deployed
yet again to clarify this issue.  Or both.  Like this.

.SH OPTIONS
.SS "Common options"
The following options are recognized by all
.I quilt
commands.

(By the way, I no longer spell section titles in full capitals because
that is an information-losing transformation that should be done
optionally at formatting time (if at all) rather than in the source.
groff 1.23's man(7) implementation will support performing that
transformation and Ingo Schwarze, the mandoc(1) developer, either
already supports this revised convention or is planning to (he also
contributes to groff).

https://git.savannah.gnu.org/cgit/groff.git/tree/NEWS#n222
)

> > -.SH EXAMPLE OF WORKING TREE
> > +.SH ENVIRONMENT
> > +In addition to that, quilt recognizes the following variables:
> 
> After the move, it is no longer clear what "to that" refers to. The 2
> environment variables are in fact a complement to all the variables
> which can be set in quiltrc files. They are listed separately because
> they are not quilt-specific.
> 
> Given that these are actually independent from the rest, my
> recommendation would be to simply drop the "In addition to that,".

I'm amenable to that, and moreover, what remains is implied by the fact
of having a section of that name in a man page of that name, so the
whole sentence could go away.

As a personal style point, I avoid using trailing colons before lists as
an escape hatch from the responsibility of writing a complete sentence.
(I acknowledge that is it is super-popular among man page writers.)  So
dropping the sentence would be an even bigger win from my view.  ;-)

> > +.SH FILES
> > +.SS "Example of working tree"
> 
> I don't believe that the example working tree belongs to the FILES
> section. EXAMPLE is listed as an allowed section name in man-pages(7),
> so why not just use that?

I concur.

> Also note that somewhere else in the man page is a pointer to this
> part, under the form "see EXAMPLE OF WORKING TREE below." Notice the
> use of capitals. As these capitals will be gone after your rework, the
> pointer should be adjusted accordingly.

Agreed.  By the way, another nice feature coming in groff 1.23 is that
when you render to PDF, man page title headings, and section and
subsection headings all get bookmarked, meaning that a PDF viewer with a
navigation pane exposes them as clickable links.

> > -.SH EXAMPLE
> > -Please refer to the pdf documentation for a full example of use.
> 
> You are dropping this line completely. I know that the pdf
> documentation is mentioned later in the "SEE ALSO" section, but there
> the "example" keyword is missing. We really want to point users
> looking for concrete examples to that pdf documentation. So either the
> statement above must stay, or the description under "SEE ALSO" must be
> extended to state that the pdf documentation includes a full example
> of use.

If the file tree diagram is relocated to "EXAMPLES" (the Linux man-pages
project prefers the plural[1]), then this section heading indeed needs
to come back.

I also don't think it would be altogether bad to reference the PDF
documentation with explicit mention of an example in "SEE ALSO"; that
section ain't just for man page cross references.

Regards,
Branden

[1] https://man7.org/linux/man-pages/man7/man-pages.7.html


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org

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.robin...@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
___
Quilt-dev mailing list

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

[G. Branden Robinson]

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.
> 
> It's been a while, I know.

Indeed it has!

> As part of SUSE's Hack Week 21, I decided to exhume this old patch
> series of yours which has been in the back of my mind for the last 4
> years. I could never get over the idea that all the work we both put
> into it would go to waste.

I agree.  I have not forgotten about this; I simply had a couple of
international moves, changed jobs, and got even more deeply engrossed in
groff development.  :)

> The project's page is here:
> https://hackweek.opensuse.org/21/projects/update-quilts-manual-page
> 
> What I've done so far:
> * Rebase the whole series on top of the current version of quilt's
>   manual page. There were lots of context changes due to additions and
>   fixes that were made to the manual page over the last 4 years.
> * Update individual patches to propagate the changes to the added
>   paragraphs, so that the changes are consistent and complete for the
>   current version of the manual page.

Sounds good!

> Now I'm reaching the next step of the process, which is to go through
> my own review and apply the suggested corrections where applicable.
> Unfortunately, I see that there were a lot of questions of mine which
> were left unanswered. As I do not have your deep knowledge of the roff
> language, macros and good practices, I don't feel good enforcing my
> views.

A bit of good news is that I've managed to learn a few more things over
the past four years.  So I may now have ideas about how to solve certain
problems that I didn't back then.

> On the other hand, there are a few changes you proposed which clearly
> did not make sense or were confusing, so it also does not feel right
> to apply your patches without cleaning them up first.

Perfectly fair.

> Therefore, if you are still around, still have some interest in the
> project, and have a few spare cycles you could allocate for this task,
> I would really appreciate if you could go through the questions I
> asked back then, and enlighten me.

It turns out I never even archived the messages, so I can easily go
through them from my (rather bloated) inbox and see if we can get some
photons flowing.

I'll start on that momentarily.

Regards,
Branden


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[G. Branden Robinson]

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"), and all macro packages for text
> > formatting (mm, ms, me, man, etc.) have macros for paragraph
> > separation, and the inter-paragraph spacing is usually different
> > from ".sp 1" for typesetter output (this can be seen in PostScript
> > and PDF output).  Explicit spacing is also unnecessary immediately
> > adjacent to section headings.
> > 
> > See section 5.3 of CSTR #54, "Troff User's Manual", Ossanna &
> > Kernighan .
> 
> 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 make it easier to navigate whenever a developer needs to
> edit the document. Does roff provide no way to achieve this?

I believe this item was resolved with a decision to use the empty
request.

https://www.mail-archive.com/quilt-dev@nongnu.org/msg02456.html

Regards,
Branden


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[G. Branden Robinson]

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 ack your review
> > and let you know that I'll be getting back to these soon but probably
> > not immediately.
> 
> I don't want to sound pushy but do you have any plans to submit an
> updated patch series? I would like to release a new version of quilt
> "soon" and would really appreciate if all the work you and me have put
> into this would make it into that new version.

Hi Jean!

I am wrapping up a job this week before I relocate (internationally) for
work next month.  There is a chance I'll be able to put some time into
this next week but after that the odds look slimmer because I'll be
moving house.  Assuming the work visa comes through...

Thanks for the reminder.  I will try to keep you posted, but if you
don't hear from me by October 12th, assume I've fallen off the edge of
the world until December or so.

Thanks for your review of these patches; I think we had a good meeting
of the minds.  Just needs that final push.

Regards,
Branden


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[G. Branden Robinson]

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 to the formatter (man) to call the tbl preprocessor render
> > the table.
> 
> Missing "to" in above sentence?

Yup--thanks!

> > +'\\" t
> 
> A comment might be in order? Within a week I'll have forgotten the
> meaning of this line.
> 
> How portable is this construct?

Well, if we precede it with a comment, it probably gets less portable.
No fooling.  :-|

Various man(1) implementations use this as a hint to decide which
preprocessors to run.

groff_man(7) says:

   If a preprocessor like tbl or eqn is needed, it has become common
   to make the first line of the man page look like this:

  '\" word

   Note the single space character after the double quote.  word
   consists of letters for the needed preprocessors: ‘e’ for eqn,
   ‘r’ for refer, and ‘t’ for tbl.  Modern implementations of the
   man program read this first line and automatically call the right
   preprocessor(s).

So if the implementation is dumb, it looks _only_ at the first line and
preceding it with a comment line defeats the purpose.

> >  .TP
> >  .I QUILT_COLORS
> > -By default,
> > +is a sequence of definitions that direct
> 
> As mentioned before, I don't like this "structure".

Acknowledged.  I'll undo it here and in the other patches.

> >  .I quilt
> > -uses its predefined color set in order to be more
> > -comprehensible when distiguishing various types of patches, e.g.\\&
> > -applied/unapplied, failed, etc.
> > +which ANSI escape sequences to associate with an output context,
> > +overriding the defaults.
> 
> This description does not mention the purpose of the escape sequences.
> Maybe "with ANSI color escape sequences" would make it clearer?

That omission was deliberate, though perhaps I could make it clearer
why.  You're passing through the escape sequences uninterpreted so
you're not limited to color changes.  You could stick a "1;" into one of
these variables to turn on boldface, for example.

> >  .IP
> > -To override one or more color settings, set the
> > +To override one or more settings, set
> 
> And here again your remove the word "color", while I think it was
> valuable.

Right.  And what I'm saying is that passing these escape sequences makes
more rendition changes than just color available.  QUILT_COLORS is
unfortunately named, unless you want to add code to filter out SGR
values that _aren't_ color changes.  And I would recommend against that.
I did some experimenting and things like bold ("1;") and "standout"
(reverse video, "7;") worked perfectly.  In fact I added them to the
in-page example, with explanatory comments.

Another advantage of thinking more expansively is that you achieve
broader portability and accessibility for people who are using
monochrome displays, have a defect in color vision, or simply prefer to
use alternative graphic renditions instead of or in addition to color
changes.

I doubt you're opposed to the goal; my challenge is to find wording that
communicates the traditional utility of this variable to your audience.
:)

> patch_offs is missing from the list, but that's not your fault, it was
> already missing from the manual page before.

Okay.  I'm noting that to fix it in the next cycle.  Thanks for the
catch!

> > +series_app series  applied patch names 32 (green)
> > +series_top series  top patch name  33 (yellow)
> > +series_una series  unapplied patch names   0 (none)
> 
> series_app, series_top and series_una are also used by "quilt patches".

I'll have to get creative; that table is already pushing the 80-column
limit.  :)

> > +.TE
> > +.IP
> > +The special
> > +.I format-name
> > +\\[lq]clear\\[rq] is used to turn off special graphics renditions and
> > +return to the terminal defaults.
> > +Changing its definition should
> > +.I not
> 
> Is it really worth an emphasis?

If people fiddle with that, they will find their display hideous, and
will probably kill the terminal window in disgust.  Honestly, I would
un-document this entirely.  I've never heard of a terminal or emulator
that supported ANSI SGR sequences that managed to screw up SGR 0.  I
could ask Thomas Dickey; as ncurses and xterm maintainer and a vigorous
monitor of portability issues, he would know better than I.  I pay
attention to this sort of thing but he's a true expert.

> > +.UR https://\\:www.ecma\\-international.org/\\:publications/\\
> > +\\:standards/\\:Ecma\\-048.htm
> 
> Would seem more simple to keep it on a single line. There is no hard
> limit to the line length.

Fair enough.  A lot of people don't know that *roff supports
syntactically transparent newline escapes, like C compilers always have.
(It shouldn't be a surprise, the same people at Bell Labs brought 

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

[G. Branden Robinson]

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 to use the DESC/EDESC approach for my next spin
> > of these patches?
> 
> I'm afraid I have no idea what you are talking about :-( Care to
> develop?

Sure!  It's from quilt's own documentation:

$ sed -n '41,42p' ./doc/README.MAIL
* if the patch has DESC a line followed by an EDESC line, use
  the text in between as the subject, or else

-- 
Regards,
Branden


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[G. Branden Robinson]

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

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.

[G. Branden Robinson]

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 not to alter any lines that I was moving, _except_
for section headings, which is the whole point of the patch.  Naturally
when deranging some slabs of running prose, some forward and backward
references are going to get scrambled.

Let me see if I can locate the fixes for the issues of concern, below.

> > -.SH QUILT COMMANDS REFERENCE
> > +.SS Quilt commands reference
> >  @REFERENCE@
> > -.SH COMMON OPTIONS TO ALL COMMANDS
> > +.SH OPTIONS
> 
> I understand the rationale for renaming the section, however the
> information "common to all commands" is lost in the process, while I
> believe it was valuable (in contrast with all options listed under
> "Quilt commands reference", which are command-specific.) I think it
> should be reintegrated as an introduction message before the first
> option.

This one is fixed in [14/26], "Document -h flag in the Options section."

> > +.SH ENVIRONMENT
> > +In addition to that, quilt recognizes the following variables:
> 
> After the move, it is no longer clear what "to that" refers to. The 2
> environment variables are in fact a complement to all the variables
> which can be set in quiltrc files. They are listed separately because
> they are not quilt-specific.
> 
> Given that these are actually independent from the rest, my
> recommendation would be to simply drop the "In addition to that,".

This one is fixed in [24/26], "Wordsmith Environment section."

> > +.SH FILES
> > +.SS "Example of working tree"
> 
> I don't believe that the example working tree belongs to the FILES
> section. EXAMPLE is listed as an allowed section name in man-pages(7),
> so why not just use that?

The man-pages project defines the FILES section as "A list of the files
the program or function uses, such as configuration files, startup
files, and files the program directly operates on." (man-pages(7)).

Quilt directly operates on many files, namely those in the .pc and
patches subdirectories.  man-pages(7) tells us, "Give the full pathname
of these files, and use the installation process to modify the directory
part to match user preferences"--however the very nature of quilt is
such that .pc and patches will all be relative to one or more arbitrary
locations, so we can't use absolute paths.

My perspective is that the Example of (a) Working Tree is neither
intended as nor useful primarily as an example of _use_ for the quilt
program ("One or more examples demonstrating how this function, file or
command is used," as man-pages(7) puts it).

Instead, the example working tree is offered to illuminate the reader
with respect to the locations of the files quilt opens and operates on.
Many man pages can just throw down an absolute path and be done with it,
but that won't do for quilt's working trees.

> Also note that somewhere else in the man page is a pointer to this
> part, under the form "see EXAMPLE OF WORKING TREE below." Notice the
> use of capitals. As these capitals will be gone after your rework, the
> pointer should be adjusted accordingly.

This one is fixed in [12/26], "Update internal and external
cross-references."

> > -.SH EXAMPLE
> > -Please refer to the pdf documentation for a full example of use.
> 
> You are dropping this line completely. I know that the pdf
> documentation is mentioned later in the "SEE ALSO" section, but there
> the "example" keyword is missing. We really want to point users looking
> for concrete examples to that pdf documentation. So either the
> statement above must stay, or the description under "SEE ALSO" must be
> extended to state that the pdf documentation includes a full example of
> use.

I'm happy to update patch [12/26] to include a mention of examples on
offer in that document, so I'll do that.

> It is getting late here, so I'll review the remainder of this patch
> series tomorrow.

Thanks!  I'm glad I anticipated some of your concerns; please let me
know about the ones which remain.

-- 
Regards,
Branden


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

Great!  It looks like some respinning is in the offing, so I'll just add
rationale to the patch header for my next iteration.

-- 
Regards,
Branden


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[G. Branden Robinson]

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 make it easier to navigate whenever a developer needs to
> edit the document. Does roff provide no way to achieve this?

It does!  There are a few possible approaches, which are not mutually
exclusive.

The empty request (just a dot on a line by itself) can be used for
vertically spacing the input.  Here are some conventions, all of which
I've seen in groff's own man page corpus.  For instance, I'll put a
segment of pfbtops(1) at the end of this message.

There are 3 features of note in it.

1. A single empty request is used between sentences;
2. Two empty requests are used between paragraphs; and
3. The empty request plus a comment of a line-spanning set of equals
   signs marks off a section.

In principle the break-suppressing escape character (') could also be
drafted into service for structuring the input, but in practice I have
not seen that done, and I fear it would confuse non-expert consumers of
the source.

What would you like to see in quilt's man pages?

.\" 
.SH DESCRIPTION
.\" 
.
.B pfbtops
translates a PostScript font in
.B .pfb
format to ASCII, splitting overlong lines in text packets into smaller
chunks.
.
If
.I pfb_file
is omitted the pfb file will be read from the standard input.
.
The ASCII format PostScript font will be written on the standard output.
.
PostScript fonts for MS-DOS are normally supplied in
.B .pfb
format.
.
.
.LP
The resulting ASCII format PostScript font can be used with groff.
.

-- 
Regards,
Branden


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

* 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 exits.
 .SH "EXIT STATUS"
-The exit status is 0 if the sub-command was successfully executed, and
-1 in case of error.
+The exit status is 0 if the requested operation completed successfully,
+or 1 in case of error.
 .PP
-An exit status of 2 denotes that
+An exit status of 2 indicates that
 .I quilt
 did not do anything to complete the command.
-This happens in particular when asking to push when the whole stack is
-already pushed, or asking to pop when the whole stack is already popped.
-This behavior is intended to ease the scripting around
+This happens in particular when asking
+.I quilt
+to push when the whole stack is already pushed, or to pop when the whole
+stack is already popped.
+This behavior is intended to ease scripting with
 .IR quilt .
 .SH ENVIRONMENT
 In addition to that,


___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

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 (\\-x).
-For internal debugging.
-.TP
 .BI "\\-\\-quiltrc " file
 Use the specified configuration file instead of
 .I \\[ti]/.quiltrc
@@ -177,6 +173,10 @@ The special value \\[lq]\\-\\[rq] causes
 .I quilt
 not to read any configuration file.
 .TP
+.B \\-\\-trace
+Runs the command in bash trace mode (\\-x).
+For internal debugging.
+.TP
 .B \\-\\-version
 Print the version number and exit immediately.
 .SH "EXIT STATUS"


___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

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 call the tbl preprocessor render
the table.

Expand the example to be more demonstrative.

Add pointers to the ECMA-48 standard document and the console_codes
section 4 man page (from Michael Kerrisk's man-pages project, widely
available) to the See Also section.

Index: quilt/doc/quilt.1.in
===
--- quilt.orig/doc/quilt.1.in
+++ quilt/doc/quilt.1.in
@@ -1,3 +1,4 @@
+'\\" t
 .\\" Created by Martin Quinson from the tex documentation
 .\\"
 .TH quilt 1 "Dec 17, 2013" "quilt"
@@ -403,103 +404,89 @@ If none of these variables is set, \\[lq
 An empty value indicates that no pager should be used.
 .TP
 .I QUILT_COLORS
-By default,
+is a sequence of definitions that direct
 .I quilt
-uses its predefined color set in order to be more
-comprehensible when distiguishing various types of patches, e.g.\\&
-applied/unapplied, failed, etc.
+which ANSI escape sequences to associate with an output context,
+overriding the defaults.
 .IP
-To override one or more color settings, set the
+To override one or more settings, set
 .I QUILT_COLORS
-variable in following syntax - colon (:) separated list of elements,
-each being of the form =[;]
+to a colon-separated list of elements,
+each of the form
+.RI \\[lq] format-name\\c
+.BI = digit-sequence\\c
+.RB [ ; ...]\\[rq].
 .IP
-Format names with their respective default values are listed below,
-along with their usage(s).
-Color codes(values) are standard bash coloring escape codes.
-See more at http://tldp.org/LDP/abs/html/colorizing.html#AEN20229
-.RS 4
-.TP
-.B diff_hdr
-Used in \\[lq]quilt diff\\[rq] to color the index line.
-Defaults to 32 (green).
-.TP
-.B diff_add
-Used in \\[lq]quilt diff\\[rq] to color added lines.
-Defaults to 36 (azure).
-.TP
-.B diff_mod
-Used in \\[lq]quilt diff\\[rq] to color modified lines.
-Defaults to 35 (purple).
-.TP
-.B diff_rem
-Used in \\[lq]quilt diff\\[rq] to color removed lines.
-Defaults to 35 (purple).
-.TP
-.B diff_hunk
-Used in \\[lq]quilt diff\\[rq] to color hunk header.
-Defaults to 33 (brown/orange).
-.TP
-.B diff_ctx
-Used in \\[lq]quilt diff\\[rq] to color the text after end of hunk
-header (\\[lq]diff \\-\\-show\\-c\\-function\\[rq] generates this).
-Defaults to 35 (purple).
-.TP
-.B diff_cctx
-Used in \\[lq]quilt diff\\[rq] to color the 15-asterisk sequence before
-or after a hunk.
-Defaults to 33 (brown/orange).
-.TP
-.B patch_fuzz
-Used in \\[lq]quilt push\\[rq] to color the patch fuzz information.
-Defaults to 35 (purple).
-.TP
-.B patch_fail
-Used in \\[lq]quilt push\\[rq] to color the fail message.
-Defaults to 31 (red).
-.TP
-.B series_app
-Used in \\[lq]quilt series\\[rq] and \\[lq]quilt patches\\[rq] to color
-the applied patch names.
-Defaults to 32 (green).
-.TP
-.B series_top
-Used in \\[lq]quilt series\\[rq] and \\[lq]quilt patches\\[rq] to color
-the top patch name.
-Defaults to 33 (brown/orange).
-.TP
-.B series_una
-Used in \\[lq]quilt series\\[rq] and \\[lq]quilt patches\\[rq] to color
-unapplied patch names.
-Defaults to 0 (no special color).
-.RE
-.RS 4
-.PP
-In addition, the
-.B clear
-format name is used to turn off special
-coloring.
-Its value is 0; it is not advised to modify it.
-.PP
-The content of
-.I QUILT_COLORS
-supersedes default values.
-So the value \\[lq]diff_hdr=35;44\\[rq] will get you the
-.I diff
-headers in magenta over blue instead of the default green over unchanged
-background.
-For that, add the following content to
+Each
+.I format-name
+with its respective default
+.I digit-sequence
+value is listed below,
+along with an explanation of where it is used.
+Each
+.I digit-sequence
+should be a SGR (Select Graphic Rendition) value supported by your
+terminal.
+The standardized SGR values were specified by ANSI and incorporated
+into ISO-6429 and ECMA-48 (\\[sc]8.3.117).
+The colors have standard names but their values were not defined within
+a color space;
+their precise appearance will vary and may be customizable in your
+terminal (emulator).
+.IP
+Recognized
+.IR format-name s,
+along with the
+.I quilt
+commands that use them,
+their use contexts,
+and default values, follow.
+.TS
+box;
+lI l l l.
+format-namecommand context default
+_
+.T&
+lB l l l.
+clear  -   -   0 (none)
+diff_add   diffadded lines 36 (cyan)
+diff_cctx  diffasterisk sequences  33 (yellow)
+diff_ctx   difftext after hunk 35 (magenta)
+diff_hdr   diffindex line  32 (green)
+diff_hunk  diffhunk header 33 (yellow)
+diff_mod   diffmodified lines  35 (magenta)
+diff_rem   diffremoved lines   35 (magenta)
+patch_fail pushfailure message 31 (red)
+patch_fuzz pushfuzz 

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

[g . branden . robinson]

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 +229,30 @@ pager;
 the default is \\[lq]\\-FRSX\\[rq].
 .SH FILES
 .SS "Example of working tree"
+.\\" Many roff output devices do not have font support for Unicode's
+.\\" box-drawing characters (U+2500 to U+257F).
+.schar \\[u2500] \\-
+.schar \\[u2502] |
+.schar \\[u2514] +
+.schar \\[u251C] +
 .EX
 project\\-1.2.3/
-├── patches/
-│├── series (list of patches to apply)
-│├── patch1.diff(one particular patch)
-│├── patch2.diff
-│└── ...
-├── .pc/
-│├── .quilt_patches (content of QUILT_PATCHES)
-│├── .quilt_series  (content of QUILT_SERIES)
-│├── patch1.diff/   (copy of patched files)
-││└── ...
-│├── patch2.diff/
-││└── ...
-│└── ...
-└── ...
+\\[u251C]\\[u2500]\\[u2500] patches/
+\\[u2502]\\[u251C]\\[u2500]\\[u2500] series (list of patches to 
apply)
+\\[u2502]\\[u251C]\\[u2500]\\[u2500] patch1.diff(one particular patch)
+\\[u2502]\\[u251C]\\[u2500]\\[u2500] patch2.diff
+\\[u2502]\\[u2514]\\[u2500]\\[u2500] ...
+\\[u251C]\\[u2500]\\[u2500] .pc/
+\\[u2502]\\[u251C]\\[u2500]\\[u2500] .quilt_patches (content of 
QUILT_PATCHES)
+\\[u2502]\\[u251C]\\[u2500]\\[u2500] .quilt_series  (content of 
QUILT_SERIES)
+\\[u2502]\\[u251C]\\[u2500]\\[u2500] patch1.diff/   (copy of patched files)
+\\[u2502]\\[u2502]\\[u2514]\\[u2500]\\[u2500] ...
+\\[u2502]\\[u251C]\\[u2500]\\[u2500] patch2.diff/
+\\[u2502]\\[u2502]\\[u2514]\\[u2500]\\[u2500] ...
+\\[u2502]\\[u2514]\\[u2500]\\[u2500] ...
+\\[u2514]\\[u2500]\\[u2500] ...
 .EE
+.fi
 .PP
 The
 .I patches


___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

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 in the current directory,
 recursively in the parent directories (this is similar to the way
 .I Git
 searches for its configuration files).
-The
-.I patches
-directory may contain sub-directories.
+The patches directory may contain sub-directories.
 It may also be a symbolic link instead of a directory.
 .PP
 A file called
@@ -84,8 +82,8 @@ Unless there are means by which series f
 automatically, it is usually provided along with a set of patches.
 In this file, each patch file name is on a separate line.
 Patch files are identified by path names that are relative to the
-.I patches
-directory; patches may be in sub-directories below this directory.
+patches directory; patches may be in sub-directories below this
+directory.
 Lines in the series file that start with a hash character (#) are
 ignored.
 You can also add a comment after each patch file name, introduced by a
@@ -105,14 +103,14 @@ corresponding for example to different d
 .PP
 Before a patch is applied (or \\[lq]pushed on the stack\\[rq]), copies
 of all files the patch modifies are saved to the
-.RI .pc/ patch
+.IR .pc/ patch
 directory.
 The patch is added to the list of currently applied patches
-(.pc/applied\\-patches).
+.RI ( .pc/applied\\-patches ).
 Later when a patch is regenerated
 .RB ( "quilt refresh" ),
 the backup copies in
-.RI .pc/ patch
+.IR .pc/ patch
 are compared with the current versions of the files in the source tree
 using GNU
 .IR diff .
@@ -127,22 +125,27 @@ the GNU
 .I Diffutils
 manual.)
 .PP
-The series file is looked up in the .pc directory, in the root of the
-source tree, and in the patches directory.
+The series file is looked up in the
+.I .pc
+directory, in the root of the source tree, and in the patches directory.
 The first series file that is found is used.
 This may also be a symbolic link, or a file with multiple hard links.
 Usually, only one series file is used for a set of patches, so the
 patches sub-directory is a convenient location.
 .PP
-The .pc directory and its sub-directories cannot be relocated, but it
-can be a symbolic link.
+The
+.I .pc
+directory and its sub-directories cannot be relocated, but it can be a
+symbolic link.
 While patches are applied to the source tree, this directory is
 essential for many operations, including taking patches off the stack
 .RB ( "quilt pop" ),
 and refreshing patches
 .RB ( "quilt refresh" ).
-Files in the .pc directory are automatically removed when they are
-no longer needed, so there is no need to clean up manually.
+Files in the
+.I .pc
+directory are automatically removed when they are no longer needed, so
+there is no need to clean up manually.
 .SS Quilt commands reference
 @REFERENCE@
 .SH OPTIONS
@@ -152,8 +155,13 @@ Runs the command in bash trace mode (\\-
 For internal debugging.
 .TP
 .BI "\\-\\-quiltrc " file
-Use the specified configuration file instead of \\[ti]/.quiltrc (or
-/etc/quilt.quiltrc if \\[ti]/.quiltrc does not exist).
+Use the specified configuration file instead of
+.I \\[ti]/.quiltrc
+(or
+.I /etc/quilt.quiltrc
+if
+.I \\[ti]/.quiltrc
+does not exist).
 See the pdf documentation for details about its possible contents.
 The special value \\[lq]\\-\\[rq] causes
 .I quilt
@@ -176,14 +184,15 @@ This behavior is intended to ease the sc
 In addition to that,
 .I quilt
 recognizes the following variables:
-.IP EDITOR 4
+.TP
+.I EDITOR
 The program to run to edit files.
-If it isn't redefined in the configuration file, $EDITOR as defined in
-the environment will be used.
-.IP LESS 4
-The arguments used to invoke the pager.
-Inherits the existing value of $LESS if LESS is already set in the
-environment, otherwise defaults to \\[lq]\\-FRSX\\[rq].
+.TP
+.I LESS
+The arguments used to invoke the
+.BR less (1)
+pager;
+defaults to \\[lq]\\-FRSX\\[rq].
 .SH FILES
 .SS "Example of working tree"
 .EX
@@ -204,28 +213,40 @@ work/
 └── ...
 .EE
 .PP
-The patches/ directory is precious as it contains all your patches as
-well as the order in which it should be applied.
+The
+.I patches
+directory is precious as it contains all your patches as well as the
+order in which it should be applied.
 .PP
-The .pc/ directory contains some metadata about the current state of
-your patch serie.
+The
+.I .pc
+directory contains some metadata about the current state of your patch
+serie.
 Changing its content is not advised.
 This directory can usually be regenerated from the initial files and the
-content of the patches/ directory (provided that all patches were
-regenerated before the removal).
+content of the
+.I patches
+directory (provided that all patches were regenerated before the
+removal).
 .SS "Configuration file"
 Upon startup,
 .I quilt

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

[g . branden . robinson]

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
===
--- quilt.orig/doc/quilt.1.in
+++ quilt/doc/quilt.1.in
@@ -255,7 +255,7 @@ If none of these variables is set, \\[lq
 An empty value indicates that no pager should be used.
 .IP QUILT_COLORS 4
 By default, quilt uses its predefined color set in order to be more
-comprehensible when distiguishing various types of patches, eg.
+comprehensible when distiguishing various types of patches, e.g.\\&
 applied/unapplied, failed, etc.
 .IP
 To override one or more color settings, set the QUILT_COLORS variable in


___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

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
@@ -115,15 +115,18 @@ no longer needed, so there is no need to
 .SS Quilt commands reference
 @REFERENCE@
 .SH OPTIONS
-.IP \"\\fB--trace\\fP\" 8
+.TP
+.B --trace
 Runs the command in bash trace mode (-x).
 For internal debugging.
-.IP \"\\fB--quiltrc\\fP file\" 8
+.TP
+.BI "--quiltrc " file
 Use the specified configuration file instead of ~/.quiltrc (or
 /etc/quilt.quiltrc if ~/.quiltrc does not exist).
 See the pdf documentation for details about its possible contents.
 The special value \"-\" causes quilt not to read any configuration file.
-.IP \"\\fB--version\\fP\" 8
+.TP
+.B --version
 Print the version number and exit immediately.
 .SH "EXIT STATUS"
 The exit status is 0 if the sub-command was successfully executed, and
@@ -252,50 +255,64 @@ along with their usage(s).
 Color codes(values) are standard bash coloring escape codes.
 See more at http://tldp.org/LDP/abs/html/colorizing.html#AEN20229
 .RS 4
-.IP \\fBdiff_hdr\\fP 10
+.TP
+.B diff_hdr
 Used in 'quilt diff' to color the index line.
 Defaults to 32 (green).
-.IP \\fBdiff_add\\fP 10
+.TP
+.B diff_add
 Used in 'quilt diff' to color added lines.
 Defaults to 36 (azure).
-.IP \\fBdiff_mod\\fP 10
+.TP
+.B diff_mod
 Used in 'quilt diff' to color modified lines.
 Defaults to 35 (purple).
-.IP \\fBdiff_rem\\fP 10
+.TP
+.B diff_rem
 Used in 'quilt diff' to color removed lines.
 Defaults to 35 (purple).
-.IP \\fBdiff_hunk\\fP 10
+.TP
+.B diff_hunk
 Used in 'quilt diff' to color hunk header.
 Defaults to 33 (brown/orange).
-.IP \\fBdiff_ctx\\fP 10
+.TP
+.B diff_ctx
 Used in 'quilt diff' to color the text after end of hunk header (diff
 --show-c-function generates this).
 Defaults to 35 (purple).
-.IP \\fBdiff_cctx\\fP 10
+.TP
+.B diff_cctx
 Used in 'quilt diff' to color the 15-asterisk sequence before or after a
 hunk.
 Defaults to 33 (brown/orange).
-.IP \\fBpatch_fuzz\\fP 10
+.TP
+.B patch_fuzz
 Used in 'quilt push' to color the patch fuzz information.
 Defaults to 35 (purple).
-.IP \\fBpatch_fail\\fP 10
+.TP
+.B patch_fail
 Used in 'quilt push' to color the fail message.
 Defaults to 31 (red).
-.IP \\fBseries_app\\fP 10
+.TP
+.B series_app
 Used in 'quilt series' and 'quilt patches' to color the applied patch
 names.
 Defaults to 32 (green).
-.IP \\fBseries_top\\fP 10
+.TP
+.B series_top
 Used in 'quilt series' and 'quilt patches' to color the top patch name.
 Defaults to 33 (brown/orange).
-.IP \\fBseries_una\\fP 10
+.TP
+.B series_una
 Used in 'quilt series' and 'quilt patches' to color unapplied patch
 names.
 Defaults to 0 (no special color).
 .RE
 .RS 4
 .PP
-In addition, the \\fBclear\\fP format name is used to turn off special
+In addition, the
+.B clear
+format name is used to turn off special
 coloring.
 Its value is 0; it is not advised to modify it.
 .PP


___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

* 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
@@ -174,31 +174,32 @@ These options are common to all
 commands.
 .TP
 .B \\-h
-Print a usage message (for the given
+prints a usage message (for the given
 .IR command ,
 if one is specified, otherwise for
 .I quilt
 itself) and exit.
 .TP
 .BI "\\-\\-quiltrc " file
-Use the specified configuration file instead of
+uses
+.I file
+as the specified configuration file instead of
 .I \\[ti]/.quiltrc
 (or
 .I /etc/quilt.quiltrc
 if
 .I \\[ti]/.quiltrc
 does not exist).
-See the PDF documentation for details about its possible contents.
 The special value \\[lq]\\-\\[rq] causes
 .I quilt
 not to read any configuration file.
 .TP
 .B \\-\\-trace
-Runs the command in bash trace mode (\\-x).
-For internal debugging.
+runs the command in the shell's trace mode (\\-x) for debugging of
+internal operations.
 .TP
 .B \\-\\-version
-Print the version number and exit immediately.
+prints the version number and exits.
 .SH "EXIT STATUS"
 The exit status is 0 if the sub-command was successfully executed, and
 1 in case of error.


___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

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 automatically removed when they are
 no longer needed, so there is no need to clean up manually.
-.SH QUILT COMMANDS REFERENCE
+.SS Quilt commands reference
 @REFERENCE@
-.SH COMMON OPTIONS TO ALL COMMANDS
+.SH OPTIONS
 .IP \"\\fB--trace\\fP\" 8
 Runs the command in bash trace mode (-x).
 For internal debugging.
@@ -125,7 +125,7 @@ See the pdf documentation for details ab
 The special value \"-\" causes quilt not to read any configuration file.
 .IP \"\\fB--version\\fP\" 8
 Print the version number and exit immediately.
-.SH EXIT STATUS
+.SH "EXIT STATUS"
 The exit status is 0 if the sub-command was successfully executed, and
 1 in case of error.
 .PP
@@ -134,7 +134,18 @@ the command.
 This happens in particular when asking to push when the whole stack is
 already pushed, or asking to pop when the whole stack is already popped.
 This behavior is intended to ease the scripting around quilt.
-.SH EXAMPLE OF WORKING TREE
+.SH ENVIRONMENT
+In addition to that, quilt recognizes the following variables:
+.IP EDITOR 4
+The program to run to edit files.
+If it isn't redefined in the configuration file, $EDITOR as defined in
+the environment will be used.
+.IP LESS 4
+The arguments used to invoke the pager.
+Inherits the existing value of $LESS if LESS is already set in the
+environment, otherwise defaults to "-FRSX".
+.SH FILES
+.SS "Example of working tree"
 .fam C
 .RS
 .nf
@@ -166,9 +177,7 @@ Changing its content is not advised.
 This directory can usually be regenerated from the initial files and the
 content of the patches/ directory (provided that all patches were
 regenerated before the removal).
-.SH EXAMPLE
-Please refer to the pdf documentation for a full example of use.
-.SH CONFIGURATION FILE
+.SS "Configuration file"
 Upon startup, quilt evaluates the file .quiltrc in the user's home
 directory, or the file specified with the --quiltrc option.
 This file is a regular bash script.
@@ -177,15 +186,6 @@ QUILT_${COMMAND}_ARGS variable.
 For example, QUILT_DIFF_ARGS="--color=auto" causes the output of quilt
 diff to be syntax colored when writing to a terminal.
 .PP
-In addition to that, quilt recognizes the following variables:
-.IP EDITOR 4
-The program to run to edit files.
-If it isn't redefined in the configuration file, $EDITOR as defined in
-the environment will be used.
-.IP LESS 4
-The arguments used to invoke the pager.
-Inherits the existing value of $LESS if LESS is already set in the
-environment, otherwise defaults to "-FRSX".
 .IP QUILT_DIFF_OPTS 4
 Additional options that quilt shall pass to GNU diff when generating
 patches.
@@ -319,7 +319,7 @@ in the distribution).
 .PP
 This man page was written by Martin Quinson, based on information found
 in the pdf documentation, and in the help messages of each commands.
-.SH SEE ALSO
+.SH "SEE ALSO"
 The pdf documentation, which should be under @DOCSUBDIR@/quilt.pdf.
 Note that some distributors compress this file.
 .BR zxpdf ( 1 )


___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

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

Index: quilt/doc/quilt.1.in
===
--- quilt.orig/doc/quilt.1.in
+++ quilt/doc/quilt.1.in
@@ -59,7 +59,11 @@ By default, most commands apply to the t
 .PP
 Patch files are located in the
 .I patches
-sub-directory of the source tree (see EXAMPLE OF WORKING TREE below).
+sub-directory of the source tree (see
+.BR "Example of working tree" ,
+under
+.BR FILES ,
+below).
 The
 .I QUILT_PATCHES
 environment variable can be used to override this location.
@@ -119,8 +123,9 @@ file.
 is careful to preserve all text that precedes the actual patch when
 doing a refresh.
 (This is limited to patches in unified format; see
-.B diff
-documentation).
+the GNU
+.I Diffutils
+manual.)
 .PP
 The series file is looked up in the .pc directory, in the root of the
 source tree, and in the patches directory.
@@ -406,11 +411,25 @@ in the distribution).
 This man page was written by Martin Quinson, based on information found
 in the pdf documentation, and in the help messages of each commands.
 .SH "SEE ALSO"
-The pdf documentation, which should be under @DOCSUBDIR@/quilt.pdf.
+.I How to Survive with Many Patches, or: Introduction to Quilt
+is installed at @DOCSUBDIR@/quilt.pdf.
 Note that some distributors compress this file.
-.BR zxpdf ( 1 )
+.BR zxpdf (1)
 can be used to display compressed pdf files.
 .PP
-.BR diff ( 1 ),
-.BR patch ( 1 ),
-.BR guards ( 1 ).
+The GNU
+.I Diffutils
+manual,
+.UR https://\\:www.gnu.org/\\:software/\\:diffutils/\\:manual/
+.I Comparing and Merging Files
+.UE ,
+documents
+.I diff
+and
+.I patch
+in detail.
+.PP
+.BR diff (1),
+.BR diffstat (1),
+.BR guards (1),
+.BR patch (1)


___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

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] https://lists.nongnu.org/archive/html/quilt-dev/2018-05/msg0.html

-- 
Regards,
Branden

___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

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 is a tool to manage large sets of patches by keeping track of the
-changes each patch makes. Patches can be applied, un-applied, refreshed,
-etc. The key philosophical concept is that your primary output is patches.
-.PP
-With quilt, all work occurs within a single directory tree. Commands can be
-invoked from anywhere within the source tree. They are of the form
+changes each patch makes.
+Patches can be applied, un-applied, refreshed, etc.
+The key philosophical concept is that your primary output is patches.
+.PP
+With quilt, all work occurs within a single directory tree.
+Commands can be invoked from anywhere within the source tree.
+They are of the form
 .B quilt cmd
-similar to CVS, svn or git commands. They can be abbreviated as long as the 
specified
-part of the command is unique. All commands print some help text with
+similar to CVS, svn or git commands.
+They can be abbreviated as long as the specified part of the command is
+unique.
+All commands print some help text with
 .B quilt cmd -h.
 .PP
-Quilt manages a stack of patches. Patches are applied incrementally on top
-of the base tree plus all preceding patches. They can be pushed on top of
-the stack
+Quilt manages a stack of patches.
+Patches are applied incrementally on top of the base tree plus all
+preceding patches.
+They can be pushed on top of the stack
 .RB ( "quilt push" ),
 and popped off the stack
 .RB ( "quilt pop" ).
@@ -34,63 +39,74 @@ By default, most commands apply to the t
 .PP
 Patch files are located in the
 .I patches
-sub-directory of the source tree (see EXAMPLE OF WORKING TREE below). The
+sub-directory of the source tree (see EXAMPLE OF WORKING TREE below).
+The
 .I QUILT_PATCHES
-environment variable can be used to override this location. When not
-found in the current directory, that subdirectory is searched
+environment variable can be used to override this location.
+When not found in the current directory, that subdirectory is searched
 recursively in the parent directories (this is similar to the way
 .I git
-searches for its configuration files). The
+searches for its configuration files).
+The
 .I patches
-directory may contain sub-directories. It may also be a symbolic link
-instead of a directory.
+directory may contain sub-directories.
+It may also be a symbolic link instead of a directory.
 .PP
 A file called
 .I series
-contains a list of patch file names that defines the order in which patches
-are applied. Unless there are means by which series files can be generated
-automatically, it is usually provided along with a set of patches. In this
-file, each patch file name is on a separate line. Patch files are identified
-by path names that are relative to the
+contains a list of patch file names that defines the order in which
+patches are applied.
+Unless there are means by which series files can be generated
+automatically, it is usually provided along with a set of patches.
+In this file, each patch file name is on a separate line.
+Patch files are identified by path names that are relative to the
 .I patches
-directory; patches may be in sub-directories below this directory. Lines
-in the series file that start with a hash character (#) are ignored.
+directory; patches may be in sub-directories below this directory.
+Lines in the series file that start with a hash character (#) are
+ignored.
 You can also add a comment after each patch file name, introduced by a
-space  followed by a hash character. When
-quilt adds, removes, or renames patches, it automatically updates the series
-file. Users of quilt can modify series files while some patches are
+space  followed by a hash character.
+When quilt adds, removes, or renames patches, it automatically updates
+the series file.
+Users of quilt can modify series files while some patches are
 applied, as long as the applied patches remain in their original order.
 .PP
-Different series files can be used to assemble patches in different ways,
+Different series files can be used to assemble patches in different
+ways,
 corresponding for example to different development branches.
 .PP
-Before a patch is applied (or ``pushed on the stack''), copies of all files
-the patch modifies are saved to the
+Before a patch is applied (or ``pushed on the stack''), copies of all
+files the patch modifies are saved to the
 .RI .pc/ patch
-directory. The patch is added to the list of currently applied patches
-(.pc/applied-patches). Later when a patch is regenerated
+directory.
+The patch is added to the list of currently applied patches
+(.pc/applied-patches).
+Later when a patch is regenerated
 .RB ( "quilt refresh" ),
 the backup copies in
 .RI .pc/ patch
-are compared with 

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

[g . branden . robinson]

...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 \\-\\-version"
 .YS
 .SH DESCRIPTION
-Quilt is a tool to manage large sets of patches by keeping track of the
+.I Quilt
+is a tool to manage large sets of patches by keeping track of the
 changes each patch makes.
 Patches can be applied, un-applied, refreshed, etc.
 The key philosophical concept is that your primary output is patches.
 .PP
-With quilt, all work occurs within a single directory tree.
+With
+.IR quilt ,
+all work occurs within a single directory tree.
 Commands can be invoked from anywhere within the source tree.
 They are of the form
 .B quilt cmd
-similar to CVS, svn or git commands.
+similar to
+.IR CVS ,
+.IR Subversion ,
+or
+.I Git
+commands.
 They can be abbreviated as long as the specified part of the command is
 unique.
 All commands print some help text with
 .B quilt cmd \\-h.
 .PP
-Quilt manages a stack of patches.
+.I Quilt
+manages a stack of patches.
 Patches are applied incrementally on top of the base tree plus all
 preceding patches.
 They can be pushed on top of the stack
@@ -56,7 +65,7 @@ The
 environment variable can be used to override this location.
 When not found in the current directory, that subdirectory is searched
 recursively in the parent directories (this is similar to the way
-.I git
+.I Git
 searches for its configuration files).
 The
 .I patches
@@ -77,10 +86,14 @@ Lines in the series file that start with
 ignored.
 You can also add a comment after each patch file name, introduced by a
 space  followed by a hash character.
-When quilt adds, removes, or renames patches, it automatically updates
-the series file.
-Users of quilt can modify series files while some patches are
-applied, as long as the applied patches remain in their original order.
+When
+.I quilt
+adds, removes, or renames patches, it automatically updates the series
+file.
+Users of
+.I quilt
+can modify series files while some patches are applied, as long as the
+applied patches remain in their original order.
 .PP
 Different series files can be used to assemble patches in different
 ways,
@@ -97,12 +110,14 @@ Later when a patch is regenerated
 the backup copies in
 .RI .pc/ patch
 are compared with the current versions of the files in the source tree
-using GNU diff.
+using GNU
+.IR diff .
 .PP
 Documentation related to a patch can be put at the beginning of a patch
 file.
-Quilt is careful to preserve all text that precedes the actual patch
-when doing a refresh.
+.I Quilt
+is careful to preserve all text that precedes the actual patch when
+doing a refresh.
 (This is limited to patches in unified format; see
 .B diff
 documentation).
@@ -135,8 +150,9 @@ For internal debugging.
 Use the specified configuration file instead of \\[ti]/.quiltrc (or
 /etc/quilt.quiltrc if \\[ti]/.quiltrc does not exist).
 See the pdf documentation for details about its possible contents.
-The special value \\[lq]\\-\\[rq] causes quilt not to read any
-configuration file.
+The special value \\[lq]\\-\\[rq] causes
+.I quilt
+not to read any configuration file.
 .TP
 .B \\-\\-version
 Print the version number and exit immediately.
@@ -144,13 +160,17 @@ Print the version number and exit immedi
 The exit status is 0 if the sub-command was successfully executed, and
 1 in case of error.
 .PP
-An exit status of 2 denotes that quilt did not do anything to complete
-the command.
+An exit status of 2 denotes that
+.I quilt
+did not do anything to complete the command.
 This happens in particular when asking to push when the whole stack is
 already pushed, or asking to pop when the whole stack is already popped.
-This behavior is intended to ease the scripting around quilt.
+This behavior is intended to ease the scripting around
+.IR quilt .
 .SH ENVIRONMENT
-In addition to that, quilt recognizes the following variables:
+In addition to that,
+.I quilt
+recognizes the following variables:
 .IP EDITOR 4
 The program to run to edit files.
 If it isn't redefined in the configuration file, $EDITOR as defined in
@@ -189,8 +209,10 @@ This directory can usually be regenerate
 content of the patches/ directory (provided that all patches were
 regenerated before the removal).
 .SS "Configuration file"
-Upon startup, quilt evaluates the file .quiltrc in the user's home
-directory, or the file specified with the \\-\\-quiltrc option.
+Upon startup,
+.I quilt
+evaluates the file .quiltrc in the user's home directory, or the file
+specified with the \\-\\-quiltrc option.
 This file is a regular bash script.
 Default options can be passed to any COMMAND by defining a
 QUILT_${COMMAND}_ARGS variable.
@@ -199,34 +221,56 @@ output of \\[lq]quilt diff\\[rq] to be s
 terminal.
 .PP
 .IP QUILT_DIFF_OPTS 4
-Additional options that quilt shall pass to GNU 

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

[g . branden . robinson]

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 patches
-sub-directory of the source tree (see
+subdirectory of the source tree (see
 .BR "Example of working tree" ,
 under
 .BR FILES ,
@@ -71,7 +71,7 @@ When not found in the current directory,
 recursively in the parent directories (this is similar to the way
 .I Git
 searches for its configuration files).
-The patches directory may contain sub-directories.
+The patches directory may contain subdirectories.
 It may also be a symbolic link instead of a directory.
 .PP
 A file called
@@ -82,7 +82,7 @@ Unless there are means by which series f
 automatically, it is usually provided along with a set of patches.
 In this file, each patch file name is on a separate line.
 Patch files are identified by path names that are relative to the
-patches directory; patches may be in sub-directories below this
+patches directory; patches may be in subdirectories below this
 directory.
 Lines in the series file that start with a hash character (#) are
 ignored.
@@ -131,11 +131,11 @@ directory, in the root of the source tre
 The first series file that is found is used.
 This may also be a symbolic link, or a file with multiple hard links.
 Usually, only one series file is used for a set of patches, so the
-patches sub-directory is a convenient location.
+patches subdirectory is a convenient location.
 .PP
 The
 .I .pc
-directory and its sub-directories cannot be relocated, but it can be a
+directory and its subdirectories cannot be relocated, but it can be a
 symbolic link.
 While patches are applied to the source tree, this directory is
 essential for many operations, including taking patches off the stack


___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

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.orig/doc/quilt.1.in
+++ quilt/doc/quilt.1.in
@@ -149,9 +149,7 @@ Inherits the existing value of $LESS if
 environment, otherwise defaults to "-FRSX".
 .SH FILES
 .SS "Example of working tree"
-.fam C
-.RS
-.nf
+.EX
 work/
 ├── patches/
 │├── series (list of patches to apply)
@@ -167,9 +165,7 @@ work/
 ││└── ...
 │└── ...
 └── ...
-.fi
-.RE
-.fam T
+.EE
 .PP
 The patches/ directory is precious as it contains all your patches as
 well as the order in which it should be applied.
@@ -322,11 +318,12 @@ over blue instead of the default green o
 For that, add the following content to ~/.quiltrc (or
 /etc/quilt.quiltrc):
 .PP
-.nf
-  QUILT_DIFF_ARGS="--color"
-  QUILT_COLORS='diff_hdr=35;44'
-.fi
+.EX
+.RS
+QUILT_DIFF_ARGS="--color"
+QUILT_COLORS='diff_hdr=35;44'
 .RE
+.EE
 .SH AUTHORS
 Quilt started as a series of scripts written by Andrew Morton
 (patch-scripts).


___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

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
 @REFERENCE@
 .SH OPTIONS
+These options are common to all
+.I quilt
+commands.
+.TP
+.B \\-h
+Print a usage message (for the given
+.IR command ,
+if one is specified, otherwise for
+.I quilt
+itself) and exit.
 .TP
 .B \\-\\-trace
 Runs the command in bash trace mode (\\-x).


___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

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 spacing is usually different from ".sp 1" for typesetter
output (this can be seen in PostScript and PDF output).  Explicit
spacing is also unnecessary immediately adjacent to section headings.

See section 5.3 of CSTR #54, "Troff User's Manual", Ossanna & Kernighan
.

Index: quilt/doc/quilt.1.in
===
--- quilt.orig/doc/quilt.1.in
+++ quilt/doc/quilt.1.in
@@ -1,26 +1,23 @@
 .\\" Created by Martin Quinson from the tex documentation
 .\\"
 .TH quilt 1 "Dec 17, 2013" "quilt"
-
 .SH NAME
 quilt \\- tool to manage series of patches
-
 .SH SYNOPSIS
 .B quilt
 [-h] command [options]
-
 .SH DESCRIPTION
 Quilt is a tool to manage large sets of patches by keeping track of the
 changes each patch makes. Patches can be applied, un-applied, refreshed,
 etc. The key philosophical concept is that your primary output is patches.
-
+.PP
 With quilt, all work occurs within a single directory tree. Commands can be
 invoked from anywhere within the source tree. They are of the form
 .B quilt cmd
 similar to CVS, svn or git commands. They can be abbreviated as long as the 
specified
 part of the command is unique. All commands print some help text with
 .B quilt cmd -h.
-
+.PP
 Quilt manages a stack of patches. Patches are applied incrementally on top
 of the base tree plus all preceding patches. They can be pushed on top of
 the stack
@@ -34,7 +31,7 @@ see below), the contents of the stack
 and the patches that are not applied at a particular moment
 .RB ( "quilt next" , " quilt unapplied" ).
 By default, most commands apply to the topmost patch on the stack.
-
+.PP
 Patch files are located in the
 .I patches
 sub-directory of the source tree (see EXAMPLE OF WORKING TREE below). The
@@ -47,7 +44,7 @@ searches for its configuration files). T
 .I patches
 directory may contain sub-directories. It may also be a symbolic link
 instead of a directory.
-
+.PP
 A file called
 .I series
 contains a list of patch file names that defines the order in which patches
@@ -63,10 +60,10 @@ space  followed by a hash character. Whe
 quilt adds, removes, or renames patches, it automatically updates the series
 file. Users of quilt can modify series files while some patches are
 applied, as long as the applied patches remain in their original order.
-
+.PP
 Different series files can be used to assemble patches in different ways,
 corresponding for example to different development branches.
-
+.PP
 Before a patch is applied (or ``pushed on the stack''), copies of all files
 the patch modifies are saved to the
 .RI .pc/ patch
@@ -77,19 +74,19 @@ the backup copies in
 .RI .pc/ patch
 are compared with the current versions of the files in the source tree using
 GNU diff.
-
+.PP
 Documentation related to a patch can be put at the beginning of a patch
 file.  Quilt is careful to preserve all text that precedes the actual patch
 when doing a refresh. (This is limited to patches in unified format; see
 .B diff
 documentation).
-
+.PP
 The series file is looked up in the .pc directory, in the root of the source
 tree, and in the patches directory.  The first series file that is found is
 used. This may also be a symbolic link, or a file with multiple hard links.
 Usually, only one series file is used for a set of patches, so the
 patches sub-directory is a convenient location.
-
+.PP
 The .pc directory and its sub-directories cannot be relocated, but it can be
 a symbolic link. While patches are applied to the source tree, this
 directory is essential for many operations, including taking patches off the
@@ -99,42 +96,29 @@ and refreshing patches
 .RB ( "quilt refresh" ).
 Files in the .pc directory are automatically removed when they are
 no longer needed, so there is no need to clean up manually.
-
 .SH QUILT COMMANDS REFERENCE
-
 @REFERENCE@
-
 .SH COMMON OPTIONS TO ALL COMMANDS
-
 .IP \"\\fB--trace\\fP\" 8
-
 Runs the command in bash trace mode (-x). For internal debugging.
-
 .IP \"\\fB--quiltrc\\fP file\" 8
-
 Use the specified configuration file instead of ~/.quiltrc (or
 /etc/quilt.quiltrc if ~/.quiltrc does not exist).  See the pdf
 documentation for details about its possible contents.  The
 special value \"-\" causes quilt not to read any configuration
 file.
-
 .IP \"\\fB--version\\fP\" 8
-
 Print the version number and exit immediately.
-
 .SH EXIT STATUS
-
 The exit status is 0 if the sub-command was successfully executed, and
 1 in case of error.
-
+.PP
 An exit status of 2 denotes that quilt did not do anything to complete
 the command.  This happens in particular when asking to push when the
 whole stack is already pushed, or asking to pop when the whole 

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

[g . branden . robinson]

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.

Index: quilt/doc/quilt.1.in
===
--- quilt.orig/doc/quilt.1.in
+++ quilt/doc/quilt.1.in
@@ -322,7 +322,7 @@ the following content to ~/.quiltrc (or
   QUILT_DIFF_ARGS="--color"
   QUILT_COLORS='diff_hdr=35;44'
 .fi
-.RE 4
+.RE
 
 .SH AUTHORS
 


___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

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 prepared for UTF-8 terminal and PDF output, possibly
among others.

See section 2.1 of CSTR #54, "Troff User's Manual", Ossanna & Kernighan
.

Index: quilt/doc/quilt.1.in
===
--- quilt.orig/doc/quilt.1.in
+++ quilt/doc/quilt.1.in
@@ -5,7 +5,7 @@
 quilt \\- tool to manage series of patches
 .SH SYNOPSIS
 .B quilt
-[-h] command [options]
+[\\-h] command [options]
 .SH DESCRIPTION
 Quilt is a tool to manage large sets of patches by keeping track of the
 changes each patch makes.
@@ -20,7 +20,7 @@ similar to CVS, svn or git commands.
 They can be abbreviated as long as the specified part of the command is
 unique.
 All commands print some help text with
-.B quilt cmd -h.
+.B quilt cmd \\-h.
 .PP
 Quilt manages a stack of patches.
 Patches are applied incrementally on top of the base tree plus all
@@ -80,7 +80,7 @@ files the patch modifies are saved to th
 .RI .pc/ patch
 directory.
 The patch is added to the list of currently applied patches
-(.pc/applied-patches).
+(.pc/applied\\-patches).
 Later when a patch is regenerated
 .RB ( "quilt refresh" ),
 the backup copies in
@@ -116,17 +116,18 @@ no longer needed, so there is no need to
 @REFERENCE@
 .SH OPTIONS
 .TP
-.B --trace
-Runs the command in bash trace mode (-x).
+.B \\-\\-trace
+Runs the command in bash trace mode (\\-x).
 For internal debugging.
 .TP
-.BI "--quiltrc " file
+.BI "\\-\\-quiltrc " file
 Use the specified configuration file instead of ~/.quiltrc (or
 /etc/quilt.quiltrc if ~/.quiltrc does not exist).
 See the pdf documentation for details about its possible contents.
-The special value \"-\" causes quilt not to read any configuration file.
+The special value \"\\-\" causes quilt not to read any configuration
+file.
 .TP
-.B --version
+.B \\-\\-version
 Print the version number and exit immediately.
 .SH "EXIT STATUS"
 The exit status is 0 if the sub-command was successfully executed, and
@@ -146,7 +147,7 @@ the environment will be used.
 .IP LESS 4
 The arguments used to invoke the pager.
 Inherits the existing value of $LESS if LESS is already set in the
-environment, otherwise defaults to "-FRSX".
+environment, otherwise defaults to "\\-FRSX".
 .SH FILES
 .SS "Example of working tree"
 .EX
@@ -178,40 +179,40 @@ content of the patches/ directory (provi
 regenerated before the removal).
 .SS "Configuration file"
 Upon startup, quilt evaluates the file .quiltrc in the user's home
-directory, or the file specified with the --quiltrc option.
+directory, or the file specified with the \\-\\-quiltrc option.
 This file is a regular bash script.
 Default options can be passed to any COMMAND by defining a
 QUILT_${COMMAND}_ARGS variable.
-For example, QUILT_DIFF_ARGS="--color=auto" causes the output of quilt
-diff to be syntax colored when writing to a terminal.
+For example, QUILT_DIFF_ARGS="\\-\\-color=auto" causes the output of
+quilt diff to be syntax colored when writing to a terminal.
 .PP
 .IP QUILT_DIFF_OPTS 4
 Additional options that quilt shall pass to GNU diff when generating
 patches.
-A useful setting for C source code is "-p", which causes GNU diff to
+A useful setting for C source code is "\\-p", which causes GNU diff to
 show in the resulting patch which function a change is in.
 .IP QUILT_PATCH_OPTS 4
 Additional options that quilt shall pass to GNU patch when applying
 patches.
 For example, recent versions of GNU patch support the
-"--reject-format=unified" option for generating reject files in unified
-diff style (older patch versions used "--unified-reject-files" for
-that).
+"\\-\\-reject\\-format=unified" option for generating reject files in
+unified diff style (older patch versions used
+"\\-\\-unified\\-reject\\-files" for that).
 .IP
-You may also want to add the "-E" option if you have issues with quilt
+You may also want to add the "\\-E" option if you have issues with quilt
 not deleting empty files when you think it should.
 The documentation of GNU patch says that "normally this option is
 unnecessary", but when patch is in POSIX mode or if the patch format
 doesn't allow to distinguish empty files from deleted files, patch
-deletes empty files only if the -E option is given.
-Beware that when passing -E to patch, quilt will no longer be able to
-deal with empty files, which is why using -E is no longer the default.
+deletes empty files only if the \\-E option is given.
+Beware that when passing \\-E to patch, quilt will no longer be able to
+deal with empty files, which is why using \\-E is no longer the default.
 .IP QUILT_DIFFSTAT_OPTS 4
 Additional options that quilt shall pass to diffstat when generating
 patch statistics.
-For 

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

[g . branden . robinson]

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 example to different development branches.
 .PP
-Before a patch is applied (or ``pushed on the stack''), copies of all
-files the patch modifies are saved to the
+Before a patch is applied (or \\[lq]pushed on the stack\\[rq]), copies
+of all files the patch modifies are saved to the
 .RI .pc/ patch
 directory.
 The patch is added to the list of currently applied patches
@@ -132,11 +132,11 @@ Runs the command in bash trace mode (\\-
 For internal debugging.
 .TP
 .BI "\\-\\-quiltrc " file
-Use the specified configuration file instead of ~/.quiltrc (or
-/etc/quilt.quiltrc if ~/.quiltrc does not exist).
+Use the specified configuration file instead of \\[ti]/.quiltrc (or
+/etc/quilt.quiltrc if \\[ti]/.quiltrc does not exist).
 See the pdf documentation for details about its possible contents.
-The special value \"\\-\" causes quilt not to read any configuration
-file.
+The special value \\[lq]\\-\\[rq] causes quilt not to read any
+configuration file.
 .TP
 .B \\-\\-version
 Print the version number and exit immediately.
@@ -158,7 +158,7 @@ the environment will be used.
 .IP LESS 4
 The arguments used to invoke the pager.
 Inherits the existing value of $LESS if LESS is already set in the
-environment, otherwise defaults to "\\-FRSX".
+environment, otherwise defaults to \\[lq]\\-FRSX\\[rq].
 .SH FILES
 .SS "Example of working tree"
 .EX
@@ -194,47 +194,51 @@ directory, or the file specified with th
 This file is a regular bash script.
 Default options can be passed to any COMMAND by defining a
 QUILT_${COMMAND}_ARGS variable.
-For example, QUILT_DIFF_ARGS="\\-\\-color=auto" causes the output of
-quilt diff to be syntax colored when writing to a terminal.
+For example, \\[lq]QUILT_DIFF_ARGS="\\-\\-color=auto"\\[rq] causes the
+output of \\[lq]quilt diff\\[rq] to be syntax colored when writing to a
+terminal.
 .PP
 .IP QUILT_DIFF_OPTS 4
 Additional options that quilt shall pass to GNU diff when generating
 patches.
-A useful setting for C source code is "\\-p", which causes GNU diff to
-show in the resulting patch which function a change is in.
+A useful setting for C source code is \\[lq]\\-p\\[rq], which causes GNU
+diff to show in the resulting patch which function a change is in.
 .IP QUILT_PATCH_OPTS 4
 Additional options that quilt shall pass to GNU patch when applying
 patches.
 For example, recent versions of GNU patch support the
-"\\-\\-reject\\-format=unified" option for generating reject files in
-unified diff style (older patch versions used
-"\\-\\-unified\\-reject\\-files" for that).
+\\[lq]\\-\\-reject\\-format=unified\\[rq] option for generating reject
+files in \\[lq]unified diff\\[rq] style (older patch versions used
+\\[lq]\\-\\-unified\\-reject\\-files\\[rq] for that).
 .IP
-You may also want to add the "\\-E" option if you have issues with quilt
-not deleting empty files when you think it should.
-The documentation of GNU patch says that "normally this option is
-unnecessary", but when patch is in POSIX mode or if the patch format
-doesn't allow to distinguish empty files from deleted files, patch
-deletes empty files only if the \\-E option is given.
-Beware that when passing \\-E to patch, quilt will no longer be able to
-deal with empty files, which is why using \\-E is no longer the default.
+You may also want to add the \\[lq]\\-E\\[rq] option if you have issues
+with quilt not deleting empty files when you think it should.
+The documentation of GNU patch says that \\[lq]normally this option is
+unnecessary\\[rq], but when patch is in POSIX mode or if the patch
+format doesn't allow to distinguish empty files from deleted files,
+patch deletes empty files only if the \\[lq]\\-E\\[rq] option is given.
+Beware that when passing \\[lq]\\-E\\[rq] to patch, quilt will no longer
+be able to deal with empty files, which is why using \\[lq]\\-E\\[rq] is
+no longer the default.
 .IP QUILT_DIFFSTAT_OPTS 4
 Additional options that quilt shall pass to diffstat when generating
 patch statistics.
-For example, "\\-f0" can be used for an alternative output format.
+For example, \\[lq]\\-f0\\[rq] can be used for an alternative output
+format.
 Recent versions of diffstat also support alternative rounding methods
-("\\-r1", "\\-r2").
+(\\[lq]\\-r1\\[rq], \\[lq]\\-r2\\[rq]).
 .IP QUILT_PATCHES 4
-The location of patch files, defaulting to "patches".
+The location of patch files, defaulting to \\[lq]patches\\[rq].
 .IP QUILT_SERIES 4
-The name of the series file, defaulting to "series".
+The name of the series file, defaulting to \\[lq]series\\[rq].
 Unless an absolute path is used, the search algorithm described above
 applies.
 .IP QUILT_PATCHES_PREFIX 4
 If set to anything, quilt will prefix patch names it 

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

[g . branden . robinson]

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 groff_man(7)'s SY and YS macros for more attractive presentation.

Index: quilt/doc/quilt.1.in
===
--- quilt.orig/doc/quilt.1.in
+++ quilt/doc/quilt.1.in
@@ -4,8 +4,19 @@
 .SH NAME
 quilt \\- tool to manage series of patches
 .SH SYNOPSIS
-.B quilt
-[\\-h] command [options]
+.SY quilt
+.RB [ \\-\\-quiltrc
+.IR file ]
+.OP \\-\\-trace
+.I command
+.YS
+.SY "quilt \\-h"
+.RI [ command ]
+.SY quilt
+.I command
+.B \\-h
+.SY "quilt \\-\\-version"
+.YS
 .SH DESCRIPTION
 Quilt is a tool to manage large sets of patches by keeping track of the
 changes each patch makes.


___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[g . branden . robinson]

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 AUTHORS
+.schar \\[:u] ue
 .I Quilt
 started as a series of scripts written by Andrew Morton
 .RI ( patch\\-scripts ).
-Based on Andrew's ideas, Andreas Gruenbacher completely rewrote the
+Based on Andrew's ideas, Andreas Gr\\[:u]nbacher completely rewrote the
 scripts, with the help of several other contributors (see the file
 .I AUTHORS
 in the distribution).


___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

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

[G. Branden Robinson]

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 formatting and content changes, so that may take a while.

I like focused changesets as much as anyone (it's one of the things
quilt facilitates marvelously), but this turned out to be a monolith
because I had no idea when I started how much I was going to be
changing.

I'm happy to break this into chunks if that would ease review, but I'd
like some feedback on how finely to chop it.

The changes I can think of that do the most to obscure others are:

> > * Eliminate empty lines; they are bad *roff style.

> > * Break lines after sentences.  In many cases, only a single space was
> >   used between sentences, which leads to incorrect inter-sentence
> >   spacing in all *roff output formats.  Two spaces are better (because
> >   groff recognizes them as separating sentences, but line breaks are the
> >   best style.

> > * Reorganize sections to use only section names endorsed by
> >   man-pages(7), and put them in the recommended order.

It would be straightforward for me to prepare 1-3 patches that perform
the above; I think all the other changes could be more easily reviewed
even as remaining "monolith".

Suggestions?

-- 
Regards,
Branden


signature.asc
Description: PGP signature
___
Quilt-dev mailing list
Quilt-dev@nongnu.org
https://lists.nongnu.org/mailman/listinfo/quilt-dev

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

[G. Branden Robinson]

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 contributor, I use and like quilt a
lot, so I decided to spend a few hours making the page more attractive
and more in line with recommended best practices.

I've attached a patch and reproduced the patch header inline.

I'd be pleased to offer further explanation/justification of any changes
I'm proposing.  I have ideas for further contributions I can make; they
appear at the bottom below.

And let me thank you all profusely for not using docbook-to-man, which
generates man pages that make one long for the beauty of sendmail.cf.

---
Refactor man page.

This is a major refactor with respect to organization and markup, and a
minor one with respect to the actual content.

The general theme is to make the man page much more consistent with good
*roff and man page style as documented in man-pages(7), groff_man(7),
the GNU Troff manual, and elsewhere.

I can't promise this is comprehensive, but:

* Expand the synopsis to cover more invocation scenarios.
* Mark up synopsis canonically (literals in bold, variable content in
  italics, and roman for "synopsis language" (option brackets, etc.)).
* Escape hyphens that are supposed to be ASCII hyphens.  This helps with
  cut-and-paste of text from multiple output formats, not just the
  terminal.
* Use character escapes for directional quotes and spacing tilde.
* Use man macros for font face changes; reduces the amount of syntax to
  learn (or imitate), and gets you proper italic corrections when
  abutting italic with non-italic text,
* Reorganize sections to use only section names endorsed by
  man-pages(7), and put them in the recommended order.
* Expand OPTIONS section to document -h.
* Add ENVIRONMENT section and migrate relevant content to it.
* Use subsection (SS) and start/end example macros (EX/EE) more
  liberally.
* This patch presumes the availability of the groff extensions to the
  man macro package, which are 20+ years old and permissively licensed.
  The ones used can be copied into the header of this page if necessary.
* One or two other groff extensions are used (like long names for
  character escapes); others, like the .fam request, are removed.
* Eliminate empty lines; they are bad *roff style.
* Break lines after sentences.  In many cases, only a single space was
  used between sentences, which leads to incorrect inter-sentence
  spacing in all *roff output formats.  Two spaces are better (because
  groff recognizes them as separating sentences, but line breaks are the
  best style.
* Tidy and tighten the language in places.
* Add BUGS section noting deficiencies in the QUILT_COLORS discussion.
* Add reference to ECMA-48 (with URL) for canonical discussion of ANSI
  escape sequences.

Still to be done:

Use correct markup in the @REFERENCE@ material, generate good-looking
ASCII output from it (with groff), and interpolate THAT into the
generated README file.

More ambitiously, doc/reference could be moved into the man page
directly (with appropriate markup), appropriate markers added (only
visible when groff is specially invoked) and good-looking ASCII output
interpolated into README.

Feedback?  Thoughts?

-- 
Regards,
Branden
Refactor man page.

This is a major refactor with respect to organization and markup, and a
minor one with respect to the actual content.

The general theme is to make the man page much more consistent with good
*roff and man page style as documented in man-pages(7), groff_man(7),
the GNU Troff manual, and elsewhere.

I can't promise this is comprehensive, but:

* Expand the synopsis to cover more invocation scenarios.
* Mark up synopsis canonically (literals in bold, variable content in
  italics, and roman for "synopsis language" (option brackets, etc.)).
* Escape hyphens that are supposed to be ASCII hyphens.  This helps with
  cut-and-paste of text from multiple output formats, not just the
  terminal.
* Use character escapes for directional quotes and spacing tilde.
* Use man macros for font face changes; reduces the amount of syntax to
  learn (or imitate), and gets you proper italic corrections when
  abutting italic with non-italic text,
* Reorganize sections to use only section names endorsed by
  man-pages(7), and put them in the recommended order.
* Expand OPTIONS section to document -h.
* Add ENVIRONMENT section and migrate relevant content to it.
* Use subsection (SS) and start/end example macros (EX/EE) more
  liberally.
* This patch presumes the availability of the groff extensions to the
  man macro package, which are 20+ years old and permissively licensed.
  The ones used can be copied into the header of this page if necessary.
* One or two other groff extensions are used (like long names for
  character