* 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 _______________________________________________ Quilt-dev mailing list [email protected] https://lists.nongnu.org/mailman/listinfo/quilt-dev
