[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Quilt-dev] [patch 24/26] Wordsmith Files section.
From: |
g . branden . robinson |
Subject: |
[Quilt-dev] [patch 24/26] Wordsmith Files section. |
Date: |
Sat, 16 Jun 2018 12:22:56 -0400 |
User-agent: |
quilt/0.65 |
* 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
- [Quilt-dev] [patch 20/26] Wordsmith Description section., (continued)
- [Quilt-dev] [patch 20/26] Wordsmith Description section., g . branden . robinson, 2018/06/16
- [Quilt-dev] [patch 25/26] Make file tree diagram portable., g . branden . robinson, 2018/06/16
- [Quilt-dev] [patch 26/26] Rewrite discussion of QUILT_COLORS configuration variable., g . branden . robinson, 2018/06/16
- [Quilt-dev] [patch 19/26] Sort options in alphabetical order to ease human scanning., g . branden . robinson, 2018/06/16
- [Quilt-dev] [patch 22/26] Wordsmith Exit Status section., g . branden . robinson, 2018/06/16
- [Quilt-dev] [patch 24/26] Wordsmith Files section.,
g . branden . robinson <=