[Quilt-dev] [patch 24/26] Wordsmith Files section.

[g . branden . robinson]

* Give working tree example a name that looks more like an actual
  software project's directory name.
* Fix pronoun/antecedent agreement (multiple occurrences).
* Tighten language (e.g., unnecessary use of "some").
* Reorganize discussion of how quilt finds its rc file to proceed
  strictly in the order attempted (I think--I didn't actually check the
  source).
* Leave breadcrumbs about EDITOR and LESS, which used to be part of this
  discussion; add cross-reference to where the material is now.
* Make explicit the fact that quilt command names need to be manually
  up-cased for use in QUILT_COMMAND_ARGS.
* Set configuration variable names in italics.
* Make tagged paragraphs readable as paragraphs (try it aloud).
* Transform a popular Denglish construction into idiomatic English.
  
https://english.stackexchange.com/questions/85069/is-the-construction-it-allows-to-proper-english
* Change "path", when not used in the sense of $PATH, to "file
  specification"; this is a doomed, Quixotic effort of mine.
* Clarify that "if set to anything" variables function as Booleans.
* Recast "a shortcut to" as "shorthand for", which is more idiomatic
  English in context.
* Add cross-reference to diffstat man page on first occurrence.
* Fix typo: each commands -> each command.

Index: quilt/doc/quilt.1.in
===================================================================
--- quilt.orig/doc/quilt.1.in
+++ quilt/doc/quilt.1.in
@@ -230,7 +230,7 @@ the default is \\[lq]\\-FRSX\\[rq].
 .SH FILES
 .SS "Example of working tree"
 .EX
-work/
+project\\-1.2.3/
 ├── patches/
 │    ├── series         (list of patches to apply)
 │    ├── patch1.diff    (one particular patch)
@@ -250,12 +250,12 @@ work/
 The
 .I patches
 directory is precious as it contains all your patches as well as the
-order in which it should be applied.
+order in which they should be applied.
 .PP
 The
 .I .pc
-directory contains some metadata about the current state of your patch
-serie.
+directory contains metadata about the current state of your patch
+series.
 Changing its content is not advised.
 This directory can usually be regenerated from the initial files and the
 content of the
@@ -265,23 +265,39 @@ removal).
 .SS "Configuration file"
 Upon startup,
 .I quilt
-evaluates the file
+evaluates the file specified with the \\[lq]\\-\\-quiltrc\\[rq] option;
+if that option is not given, the file
 .I .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
-.I quilt COMMAND
-by defining a
-.IR QUILT_ COMMAND _ARGS
-variable.
-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.
+in the user's home directory is used, and if that does not exist,
+.I /etc/quilt.quiltrc
+is read.
+This file is a
+.BR bash (1)
+script.
+.I EDITOR
+and
+.I LESS
+can be overridden here if desired;
+see
+.BR ENVIRONMENT ,
+above.
 .PP
+Define a variable of the form
+.IR QUILT_ COMMAND _ARGS
+to specify default options to be passed to any
+.I quilt
+command (in uppercase).
+For example,
+.EX
+.RS
+QUILT_DIFF_ARGS="\\-\\-color=auto"
+.RE
+.EE
+causes the output of \\[lq]quilt diff\\[rq] to be syntax-colored when
+writing to a terminal.
 .TP
 .I QUILT_DIFF_OPTS
-Additional options that
+indicates additional options that
 .I quilt
 shall pass to GNU
 .I diff
@@ -291,7 +307,7 @@ A useful setting for C source code is \\
 to show in the resulting patch which function a change is in.
 .TP
 .I QUILT_PATCH_OPTS
-Additional options that
+indicates additional options that
 .I quilt
 shall pass to GNU
 .I patch
@@ -311,8 +327,8 @@ The documentation of GNU
 .I patch
 says that \\[lq]normally this option is unnecessary\\[rq], but when
 .I patch
-is in POSIX mode or if the patch format doesn't allow to distinguish
-empty files from deleted files,
+is in POSIX mode or if the patch format doesn't distinguish empty files
+from deleted files,
 .I patch
 deletes empty files only if the \\[lq]\\-E\\[rq] option is given.
 Beware that when passing \\[lq]\\-E\\[rq] to
@@ -322,10 +338,10 @@ will no longer be able to deal with empt
 \\[lq]\\-E\\[rq] is no longer the default.
 .TP
 .I QUILT_DIFFSTAT_OPTS
-Additional options that
+indicates additional options that
 .I quilt
 shall pass to
-.I diffstat
+.BR diffstat (1)
 when generating patch statistics.
 For example, \\[lq]\\-f0\\[rq] can be used for an alternative output
 format.
@@ -335,40 +351,47 @@ also support alternative rounding method
 \\[lq]\\-r2\\[rq]).
 .TP
 .I QUILT_PATCHES
-The location of patch files, defaulting to \\[lq]patches\\[rq].
+specifies the location of patch files, defaulting to
+.IR patches .
 .TP
 .I QUILT_SERIES
-The name of the series file, defaulting to \\[lq]series\\[rq].
-Unless an absolute path is used, the search algorithm described above
-applies.
+specifies the name of the series file, defaulting to
+.IR series .
+Unless an absolute file specification is used, the search algorithm
+described above applies.
 .TP
 .I QUILT_PATCHES_PREFIX
-If set to anything,
+is a Boolean flag; if set to anything,
 .I quilt
-will prefix patch names it prints with their
-directory (QUILT_PATCHES).
+will prefix any patch name it prints with its directory
+.RI ( QUILT_PATCHES ).
 .TP
 .I QUILT_NO_DIFF_INDEX
-By default,
-.I quilt
-prepends an \\[lq]Index:\\[rq] line to the patches it generates.
-If this variable is set to anything, no line is prepended.
-This is a shortcut to adding \\-\\-no\\-index to both QUILT_DIFF_ARGS
-and QUILT_REFRESH_ARGS.
+is a Boolean flag; if set to anything,
+no \\[lq]Index:\\[rq] line is prepended to patches generated by
+.IR quilt .
+This is shorthand for adding \\[lq]\\-\\-no\\-index\\[rq] to both
+.I QUILT_DIFF_ARGS
+and
+.IR QUILT_REFRESH_ARGS .
 .TP
 .I QUILT_NO_DIFF_TIMESTAMPS
-By default,
-.I quilt
-includes timestamps in headers when generating patches.
-If this variable is set to anything, no timestamp will be included.
-This is a shortcut to adding \\-\\-no\\-timestamps to both
-QUILT_DIFF_ARGS and QUILT_REFRESH_ARGS.
+is a Boolean flag; if set to anything,
+no timestamps are included in headers when generating patches.
+This is shorthand for adding \\[lq]\\-\\-no\\-timestamps\\[rq] to both
+.I QUILT_DIFF_ARGS
+and
+.IR QUILT_REFRESH_ARGS .
 .TP
 .I QUILT_PAGER
-The pager
+specifies the pager
 .I quilt
 shall use for commands which produce paginated output.
-If unset, the values of GIT_PAGER or PAGER is used.
+If unset, the value of
+.I GIT_PAGER
+or, failing that,
+.I PAGER
+is used.
 If none of these variables is set, \\[lq]less \\-R\\[rq] is used.
 An empty value indicates that no pager should be used.
 .TP
@@ -481,7 +504,7 @@ scripts, with the help of several other
 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.
+in the PDF documentation, and in the help messages of each command.
 .SH "SEE ALSO"
 .I How to Survive with Many Patches, or: Introduction to Quilt
 is installed at