[Quilt-dev] [patch v2 24/26] Man page: wordsmith Files section

[Jean Delvare]

* 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.
* 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.
* Transform a popular Denglish construction into idiomatic English.
  
https://english.stackexchange.com/questions/85069/is-the-construction-it-allows-to-proper-english
* 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.

[JD: reverted 2 changes I did not like; fixes one more typo]
---
 doc/quilt.1.in |   99 ++++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 60 insertions(+), 39 deletions(-)

--- quilt.orig/doc/quilt.1.in   2022-07-25 15:28:14.087991615 +0200
+++ quilt/doc/quilt.1.in        2022-07-25 15:52:54.344433071 +0200
@@ -246,7 +246,7 @@ Defaults to \\[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)
@@ -266,11 +266,11 @@ 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
+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
@@ -282,22 +282,36 @@ 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,
+in the user's home directory is used, and if that does not exist,
 .I /etc/quilt.quiltrc
-if the former file does not exist, 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.
+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 4
 .I QUILT_DIFF_OPTS
 Additional options that
@@ -330,8 +344,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
@@ -341,10 +355,10 @@ will no longer be able to deal with empt
 \\[lq]\\-E\\[rq] is no longer the default.
 .TP 4
 .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.
@@ -361,40 +375,47 @@ perspective.
 Defaults to \\[lq].pc\\[rq].
 .TP 4
 .I QUILT_PATCHES
-The location of patch files, defaulting to \\[lq]patches\\[rq].
+The location of patch files, defaulting to
+.IR patches .
 .TP 4
 .I QUILT_SERIES
-The name of the series file, defaulting to \\[lq]series\\[rq].
+The name of the series file, defaulting to
+.IR series .
 Unless an absolute path is used, the search algorithm described above
 applies.
 .TP 4
 .I QUILT_PATCHES_PREFIX
-If set to anything,
+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 4
 .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.
+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 4
 .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.
+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 4
 .I QUILT_PAGER
 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 4
@@ -506,7 +527,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 message of each command.
 .
 .SH EXAMPLE
 Please refer to the PDF documentation for a full example of use (under