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