Hi folks, In the course of trying to figure out why "quilt graph --all" wasn't working the way I expected, I was wondering why the quilt man page didn't look like others I work with and a look at its sources revealed that it did a few things unconventionally.
As a groff and man-pages project contributor, I use and like quilt a lot, so I decided to spend a few hours making the page more attractive and more in line with recommended best practices. I've attached a patch and reproduced the patch header inline. I'd be pleased to offer further explanation/justification of any changes I'm proposing. I have ideas for further contributions I can make; they appear at the bottom below. And let me thank you all profusely for not using docbook-to-man, which generates man pages that make one long for the beauty of sendmail.cf. --- Refactor man page. This is a major refactor with respect to organization and markup, and a minor one with respect to the actual content. The general theme is to make the man page much more consistent with good *roff and man page style as documented in man-pages(7), groff_man(7), the GNU Troff manual, and elsewhere. I can't promise this is comprehensive, but: * Expand the synopsis to cover more invocation scenarios. * Mark up synopsis canonically (literals in bold, variable content in italics, and roman for "synopsis language" (option brackets, etc.)). * Escape hyphens that are supposed to be ASCII hyphens. This helps with cut-and-paste of text from multiple output formats, not just the terminal. * Use character escapes for directional quotes and spacing tilde. * Use man macros for font face changes; reduces the amount of syntax to learn (or imitate), and gets you proper italic corrections when abutting italic with non-italic text, * Reorganize sections to use only section names endorsed by man-pages(7), and put them in the recommended order. * Expand OPTIONS section to document -h. * Add ENVIRONMENT section and migrate relevant content to it. * Use subsection (SS) and start/end example macros (EX/EE) more liberally. * This patch presumes the availability of the groff extensions to the man macro package, which are 20+ years old and permissively licensed. The ones used can be copied into the header of this page if necessary. * One or two other groff extensions are used (like long names for character escapes); others, like the .fam request, are removed. * Eliminate empty lines; they are bad *roff style. * Break lines after sentences. In many cases, only a single space was used between sentences, which leads to incorrect inter-sentence spacing in all *roff output formats. Two spaces are better (because groff recognizes them as separating sentences, but line breaks are the best style. * Tidy and tighten the language in places. * Add BUGS section noting deficiencies in the QUILT_COLORS discussion. * Add reference to ECMA-48 (with URL) for canonical discussion of ANSI escape sequences. Still to be done: Use correct markup in the @REFERENCE@ material, generate good-looking ASCII output from it (with groff), and interpolate THAT into the generated README file. More ambitiously, doc/reference could be moved into the man page directly (with appropriate markup), appropriate markers added (only visible when groff is specially invoked) and good-looking ASCII output interpolated into README. Feedback? Thoughts? -- Regards, Branden
Refactor man page.
This is a major refactor with respect to organization and markup, and a
minor one with respect to the actual content.
The general theme is to make the man page much more consistent with good
*roff and man page style as documented in man-pages(7), groff_man(7),
the GNU Troff manual, and elsewhere.
I can't promise this is comprehensive, but:
* Expand the synopsis to cover more invocation scenarios.
* Mark up synopsis canonically (literals in bold, variable content in
italics, and roman for "synopsis language" (option brackets, etc.)).
* Escape hyphens that are supposed to be ASCII hyphens. This helps with
cut-and-paste of text from multiple output formats, not just the
terminal.
* Use character escapes for directional quotes and spacing tilde.
* Use man macros for font face changes; reduces the amount of syntax to
learn (or imitate), and gets you proper italic corrections when
abutting italic with non-italic text,
* Reorganize sections to use only section names endorsed by
man-pages(7), and put them in the recommended order.
* Expand OPTIONS section to document -h.
* Add ENVIRONMENT section and migrate relevant content to it.
* Use subsection (SS) and start/end example macros (EX/EE) more
liberally.
* This patch presumes the availability of the groff extensions to the
man macro package, which are 20+ years old and permissively licensed.
The ones used can be copied into the header of this page if necessary.
* One or two other groff extensions are used (like long names for
character escapes); others, like the .fam request, are removed.
* Eliminate empty lines; they are bad *roff style.
* Break lines after sentences. In many cases, only a single space was
used between sentences, which leads to incorrect inter-sentence
spacing in all *roff output formats. Two spaces are better (because
groff recognizes them as separating sentences, but line breaks are the
best style.
* Tidy and tighten the language in places.
* Add BUGS section noting deficiencies in the QUILT_COLORS discussion.
* Add reference to ECMA-48 (with URL) for canonical discussion of ANSI
escape sequences.
Still to be done:
Use correct markup in the @REFERENCE@ material, generate good-looking
ASCII output from it (with groff), and interpolate THAT into the
generated README file.
More ambitiously, doc/reference could be moved into the man page
directly (with appropriate markup), appropriate markers added (only
visible when groff is specially invoked) and good-looking ASCII output
interpolated into README.
Feedback? Thoughts?
Index: quilt/doc/quilt.1.in
===================================================================
--- quilt.orig/doc/quilt.1.in
+++ quilt/doc/quilt.1.in
@@ -1,29 +1,52 @@
.\\" Created by Martin Quinson from the tex documentation
.\\"
-.TH quilt 1 "Dec 17, 2013" "quilt"
-
+.TH quilt 1 "2018-05-30" "quilt 0.65+"
.SH NAME
-quilt \\- tool to manage series of patches
-
+quilt \\- manage a series of patches
.SH SYNOPSIS
-.B quilt
-[-h] command [options]
-
+.SY quilt
+.RB [ \\-\\-quiltrc
+.IR file ]
+.OP \\-\\-trace
+.I command
+.YS
+.SY "quilt \\-h"
+.RI [ command ]
+.SY "quilt \\-\\-version"
+.YS
.SH DESCRIPTION
-Quilt is a tool to manage large sets of patches by keeping track of the
-changes each patch makes. Patches can be applied, un-applied, refreshed,
-etc. The key philosophical concept is that your primary output is patches.
-
-With quilt, all work occurs within a single directory tree. Commands can be
-invoked from anywhere within the source tree. They are of the form
-.B quilt cmd
-similar to CVS, svn or git commands. They can be abbreviated as long as the specified
-part of the command is unique. All commands print some help text with
-.B quilt cmd -h.
-
-Quilt manages a stack of patches. Patches are applied incrementally on top
-of the base tree plus all preceding patches. They can be pushed on top of
-the stack
+.I Quilt
+is a tool to manage large sets of patches by keeping track of the
+changes each patch makes.
+Patches can be applied, reverted (\\[lq]unapplied\\[rq]), refreshed, and
+so forth.
+The key philosophical concept is that your primary working material is
+patches.
+.PP
+With
+.IR quilt ,
+all work occurs within a single directory tree.
+Commands can be invoked from anywhere within the source tree.
+They are of the form
+.RB \\[lq] quilt
+.IR command \\[rq],
+similarly to
+.IR CVS ,
+.IR Subversion ,
+or
+.IR Git .
+They can be abbreviated as long as the specified part of the command is
+unambiguous.
+All commands print a brief contextual help message with
+.RB \\[lq] quilt
+.I command
+.BR \\-h \\[rq].
+.PP
+.I Quilt
+manages a stack of patches.
+Patches are applied incrementally on top of the base tree plus all
+preceding patches.
+They can be pushed onto the stack
.RB ( "quilt push" ),
and popped off the stack
.RB ( "quilt pop" ).
@@ -34,111 +57,164 @@ see below), the contents of the stack
and the patches that are not applied at a particular moment
.RB ( "quilt next" , " quilt unapplied" ).
By default, most commands apply to the topmost patch on the stack.
-
+.PP
Patch files are located in the
.I patches
-sub-directory of the source tree (see EXAMPLE OF WORKING TREE below). The
+subdirectory of the source tree (see
+.BR "Example of working tree" ,
+under
+.BR FILES ,
+below).
+The
.I QUILT_PATCHES
-environment variable can be used to override this location. When not
-found in the current directory, that subdirectory is searched
+environment variable can be used to override this location.
+When not found in the current directory, that subdirectory is searched
recursively in the parent directories (this is similar to the way
-.I git
-searches for its configuration files). The
+.I Git
+searches for its configuration files).
+The
.I patches
-directory may contain sub-directories. It may also be a symbolic link
+directory may contain subdirectories.
+It may also be a symbolic link
instead of a directory.
-
-A file called
-.I series
-contains a list of patch file names that defines the order in which patches
-are applied. Unless there are means by which series files can be generated
-automatically, it is usually provided along with a set of patches. In this
-file, each patch file name is on a separate line. Patch files are identified
-by path names that are relative to the
+.PP
+.I Quilt
+creates a file called
+.IR series ,
+which contains a list of patch file names that defines the order in
+which patches are applied.
+In this file, each patch file name is on a separate line.
+Patch files are identified by path names that are relative to the
.I patches
-directory; patches may be in sub-directories below this directory. Lines
-in the series file that start with a hash character (#) are ignored.
+directory; patches may be in subdirectories below this directory.
+Lines in the series file that start with a hash character (#) are
+ignored.
You can also add a comment after each patch file name, introduced by a
-space followed by a hash character. When
-quilt adds, removes, or renames patches, it automatically updates the series
-file. Users of quilt can modify series files while some patches are
-applied, as long as the applied patches remain in their original order.
-
-Different series files can be used to assemble patches in different ways,
-corresponding for example to different development branches.
-
-Before a patch is applied (or ``pushed on the stack''), copies of all files
-the patch modifies are saved to the
-.RI .pc/ patch
-directory. The patch is added to the list of currently applied patches
-(.pc/applied-patches). Later when a patch is regenerated
+space followed by a hash character.
+When quilt adds, removes, or renames patches, it automatically updates
+the series file.
+Users of quilt can modify series files while some patches are applied,
+as long as the applied patches remain in their original order.
+Unless there are means by which a series file can be generated
+automatically, you should provide it along with any set of
+.IR Quilt -managed
+patches you distribute.
+.PP
+Different series files can be used to assemble patches in different
+ways, corresponding for example to different development branches.
+.PP
+Before a patch is applied,
+copies of all files the patch modifies are saved to the
+.IR .pc/ patch-name
+directory,
+where
+.I patch-name
+is the name of the patch (e.g.,
+.IR fix\\-buffer\\-overflow.patch ).
+The patch is added to the list of currently applied patches
+.RI ( .pc/applied\\-patches ).
+Later, when a patch is regenerated
.RB ( "quilt refresh" ),
the backup copies in
-.RI .pc/ patch
-are compared with the current versions of the files in the source tree using
-GNU diff.
-
+.IR .pc/ patch-name
+are compared with the current versions of the files in the source tree
+using GNU
+.BR diff (1).
+.PP
Documentation related to a patch can be put at the beginning of a patch
-file. Quilt is careful to preserve all text that precedes the actual patch
-when doing a refresh. (This is limited to patches in unified format; see
-.B diff
-documentation).
-
-The series file is looked up in the .pc directory, in the root of the source
-tree, and in the patches directory. The first series file that is found is
-used. This may also be a symbolic link, or a file with multiple hard links.
+file.
+.I Quilt
+is careful to preserve all text that precedes the actual patch when
+doing a refresh.
+(This is limited to patches in unified format; see
+.BR diff (1).)
+.PP
+The
+.I series
+file is looked up in the
+.I .pc
+directory, in the root of the source tree, and in the
+.I patches
+directory.
+The first series file that is found is used.
+This may also be a symbolic link, or a file with multiple hard links.
Usually, only one series file is used for a set of patches, so the
-patches sub-directory is a convenient location.
-
-The .pc directory and its sub-directories cannot be relocated, but it can be
-a symbolic link. While patches are applied to the source tree, this
-directory is essential for many operations, including taking patches off the
-stack
+.I patches
+subdirectory is a convenient location.
+.PP
+The
+.I .pc
+directory cannot be relocated, but it can be a symbolic link.
+Its subdirectories must not be renamed or restructured.
+While patches are applied to the source tree, this directory is
+essential for many operations, including taking patches off the stack
.RB ( "quilt pop" ),
and refreshing patches
.RB ( "quilt refresh" ).
-Files in the .pc directory are automatically removed when they are
-no longer needed, so there is no need to clean up manually.
-
-.SH QUILT COMMANDS REFERENCE
-
+Files in the
+.I .pc
+directory are automatically removed when they are no longer needed, so
+there is no need to clean up manually.
+.SS Quilt commands reference
@REFERENCE@
-
-.SH COMMON OPTIONS TO ALL COMMANDS
-
-.IP \"\\fB--trace\\fP\" 8
-
-Runs the command in bash trace mode (-x). For internal debugging.
-
-.IP \"\\fB--quiltrc\\fP file\" 8
-
-Use the specified configuration file instead of ~/.quiltrc (or
-/etc/quilt.quiltrc if ~/.quiltrc does not exist). See the pdf
-documentation for details about its possible contents. The
-special value \"-\" causes quilt not to read any configuration
-file.
-
-.IP \"\\fB--version\\fP\" 8
-
-Print the version number and exit immediately.
-
-.SH EXIT STATUS
-
-The exit status is 0 if the sub-command was successfully executed, and
+.SH OPTIONS
+These options are common to all
+.I quilt
+commands.
+.TP
+.B \\-h
+Print a usage message (for the given
+.IR command ,
+if one is specified, otherwise for
+.I quilt
+itself) and exit.
+.TP
+.BI "\\-\\-quiltrc " file
+Use the specified configuration file instead of the default (see
+.BR "Configuration file" ,
+under
+.BR FILES ,
+below).
+See the PDF documentation for details about its possible contents.
+The special value \\[lq]\\-\\[rq] causes quilt not to read any
+configuration file.
+.TP
+.B \\-\\-trace
+Run the command in the shell's trace mode (\\-x); for internal
+debugging.
+.TP
+.B \\-\\-version
+Print the version number and exit.
+.SH "EXIT STATUS"
+The exit status is 0 if the requested operation was successfully
+executed, and
1 in case of error.
-
-An exit status of 2 denotes that quilt did not do anything to complete
-the command. This happens in particular when asking to push when the
-whole stack is already pushed, or asking to pop when the whole stack
-is already popped. This behavior is intended to ease the scripting
-around quilt.
-
-.SH EXAMPLE OF WORKING TREE
-
-.fam C
-.RS
-.nf
-work/
+.PP
+An exit status of 2 denotes that
+.I quilt
+did not do anything to complete the command.
+This happens in particular when asking
+.I quilt
+to push when the whole stack is already pushed,
+or asking it to pop when the whole stack is already popped.
+This behavior is intended to ease scripting with
+.IR quilt .
+.SH ENVIRONMENT
+.I Quilt
+recognizes the following variables.
+.TP
+.I EDITOR
+specifies the program to run to edit files;
+e.g., with
+.RB \\[lq] "quilt header \\-e" \\[rq].
+.TP
+.I LESS
+specifies the arguments used to invoke the pager;
+if not set, \\[lq]\\-FRSX\\[rq] is used.
+.SH FILES
+.SS "Example of working tree"
+.EX
+project\\-1.2.3/
├── patches/
│ ├── series (list of patches to apply)
│ ├── patch1.diff (one particular patch)
@@ -153,194 +229,328 @@ work/
│ │ └── ...
│ └── ...
└── ...
-.fi
+.EE
+.PP
+The
+.I patches/
+directory is precious as it contains all your patches as well as the
+order in which they should be applied.
+.PP
+The
+.I .pc/
+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
+.I patches/
+directory (provided that all patches were regenerated before the
+removal).
+.SS "Configuration file"
+Upon startup,
+.I quilt
+evaluates the file specified with the \\-\\-quiltrc option;
+if that is not specified,
+the file
+.I .quiltrc
+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
+By defining a variable of the form
+.IR QUILT_ command _ARGS ,
+default options can be passed to any
+.IR command .
+For example,
+.EX
+.RS
+QUILT_DIFF_ARGS="\\-\\-color=auto"
.RE
-.fam T
-
-The patches/ directory is precious as it contains all your patches as
-well as the order in which it should be applied.
-
-The .pc/ directory contains some metadata about the current state of
-your patch serie. Changing its content is not advised. This directory
-can usually be regenerated from the initial files and the
-content of the patches/ directory (provided that all patches were
-regenerated before the removal).
-
-.SH EXAMPLE
-
-Please refer to the pdf documentation for a full example of use.
-
-.SH CONFIGURATION FILE
-
-Upon startup, quilt evaluates the file .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 COMMAND
-by defining a QUILT_${COMMAND}_ARGS variable. For example,
-QUILT_DIFF_ARGS="--color=auto" causes the output of quilt diff to be
-syntax colored when writing to a terminal.
-
-In addition to that, quilt recognizes the following variables:
-
-.IP EDITOR 4
-
-The program to run to edit files. If it isn't redefined in the
-configuration file, $EDITOR as defined in the environment will be used.
-
-.IP LESS 4
-
-The arguments used to invoke the pager. Inherits the existing value
-of $LESS if LESS is already set in the environment, otherwise defaults
-to "-FRSX".
-
-.IP QUILT_DIFF_OPTS 4
-
-Additional options that quilt shall pass to GNU diff when generating
-patches. A useful setting for C source code is "-p", which causes GNU diff
+.EE
+causes the output of
+.B quilt diff
+to be syntax-colored when writing to a terminal.
+.TP
+.I QUILT_DIFF_OPTS
+indicates additional options that
+.I quilt
+shall pass to GNU
+.I diff
+when generating patches.
+A useful setting for C source code is \\[lq]\\-p\\[rq], which causes GNU
+.I diff
to show in the resulting patch which function a change is in.
-
-.IP QUILT_PATCH_OPTS 4
-
-Additional options that quilt shall pass to GNU patch when applying
-patches. For example, recent versions of GNU patch support the
-"--reject-format=unified" option for generating reject files in unified
-diff style (older patch versions used "--unified-reject-files" for that).
-
-You may also want to add the "-E" option if you have issues with quilt
-not deleting empty files when you think it should. The documentation of
-GNU patch says that "normally this option is unnecessary", but when patch
-is in POSIX mode or if the patch format doesn't allow to distinguish
-empty files from deleted files, patch deletes empty files only if the
--E option is given. Beware that when passing -E to patch, quilt will
-no longer be able to deal with empty files, which is why using -E is
-no longer the default.
-
-.IP QUILT_DIFFSTAT_OPTS 4
-
-Additional options that quilt shall pass to diffstat when generating
-patch statistics. For example, "-f0" can be used for an alternative output
-format. Recent versions of diffstat also support alternative rounding
-methods ("-r1", "-r2").
-
-.IP QUILT_PATCHES 4
-
-The location of patch files, defaulting to "patches".
-
-.IP QUILT_SERIES 4
-
-The name of the series file, defaulting to "series". Unless an absolute path
+.TP
+.I QUILT_PATCH_OPTS
+indicates additional options that
+.I quilt
+shall pass to GNU
+.I patch
+when applying patches.
+For example,
+recent versions of GNU patch support the
+\\[lq]\\-\\-reject\\-format=unified\\[rq] option for generating reject
+files in unified diff style (older patch versions used
+\\[lq]\\-\\-unified\\-reject\\-files\\[rq] for that).
+.IP
+You may also want to add the \\[lq]\\-E\\[rq] option if you have issues
+with
+.I quilt
+not deleting empty files when you think it should.
+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 distinguish empty files
+from deleted files,
+.I patch
+deletes empty files only if the \\-E option is given.
+Beware that when passing \\-E to patch,
+.I quilt
+will no longer be able to deal with empty files,
+which is why using \\-E is no longer the default.
+.TP
+.I QUILT_DIFFSTAT_OPTS
+indicates additional options that
+.I quilt
+shall pass to
+.BR diffstat (1)
+when generating patch statistics.
+For example, \\[lq]\\-f0\\[rq] can be used for an alternative output
+format.
+Recent versions of
+.I diffstat
+also support alternative rounding methods (\\[lq]\\-r1\\[rq],
+\\[lq]\\-r2\\[rq]).
+.TP
+.I QUILT_PATCHES
+specifies the location of patch files, defaulting to
+.IR patches .
+.TP
+.I QUILT_SERIES
+specifies the name of the series file, defaulting to
+.IR series .
+Unless an absolute path
is used, the search algorithm described above applies.
-
-.IP QUILT_PATCHES_PREFIX 4
-
-If set to anything, quilt will prefix patch names it prints with their
-directory (QUILT_PATCHES).
-
-.IP QUILT_NO_DIFF_INDEX 4
-
-By default, quilt prepends an Index: 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.
-
-.IP QUILT_NO_DIFF_TIMESTAMPS 4
-
-By default, 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.
-
-.IP QUILT_PAGER 4
-
-The pager quilt shall use for commands which produce paginated output. If
-unset, the values of GIT_PAGER or PAGER is used. If none of these variables
-is set, "less -R" is used. An empty value indicates that no pager should be
-used.
-
-.IP QUILT_COLORS 4
-
-By default, quilt uses its predefined color set in order to be more
-comprehensible when distiguishing various types of patches, eg.
-applied/unapplied, failed, etc.
-
-To override one or more color settings, set the QUILT_COLORS variable in
-following syntax - colon (:) separated list of elements, each being of the
-form <format name>=<foreground color>[;<background color>]
-
-Format names with their respective default values are listed below,
-along with their usage(s).
-Color codes(values) are standard bash coloring escape codes.
-See more at http://tldp.org/LDP/abs/html/colorizing.html#AEN20229
-
-.RS 4
-.IP \\fBdiff_hdr\\fP 10
-Used in 'quilt diff' to color the index line. Defaults to 32 (green).
-
-.IP \\fBdiff_add\\fP 10
-Used in 'quilt diff' to color added lines. Defaults to 36 (azure).
-
-.IP \\fBdiff_mod\\fP 10
-Used in 'quilt diff' to color modified lines. Defaults to 35 (purple).
-
-.IP \\fBdiff_rem\\fP 10
-Used in 'quilt diff' to color removed lines. Defaults to 35 (purple).
-
-.IP \\fBdiff_hunk\\fP 10
-Used in 'quilt diff' to color hunk header. Defaults to 33 (brown/orange).
-
-.IP \\fBdiff_ctx\\fP 10
-Used in 'quilt diff' to color the text after end of hunk header (diff --show-c-function generates this). Defaults to 35 (purple).
-
-.IP \\fBdiff_cctx\\fP 10
-Used in 'quilt diff' to color the 15-asterisk sequence before or after a hunk. Defaults to 33 (brown/orange).
-
-.IP \\fBpatch_fuzz\\fP 10
-Used in 'quilt push' to color the patch fuzz information. Defaults to 35 (purple).
-
-.IP \\fBpatch_fail\\fP 10
-Used in 'quilt push' to color the fail message. Defaults to 31 (red).
-
-.IP \\fBseries_app\\fP 10
-Used in 'quilt series' and 'quilt patches' to color the applied patch names. Defaults to 32 (green).
-
-.IP \\fBseries_top\\fP 10
-Used in 'quilt series' and 'quilt patches' to color the top patch name. Defaults to 33 (brown/orange).
-
-.IP \\fBseries_una\\fP 10
-Used in 'quilt series' and 'quilt patches' to color unapplied patch names. Defaults to 0 (no special color).
-
+.TP
+.I QUILT_PATCHES_PREFIX
+is a Boolean flag; if set to anything,
+.I quilt
+will prefix patch names it prints with their directory
+.RI ( QUILT_PATCHES ).
+.TP
+.I QUILT_NO_DIFF_INDEX
+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
+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
+specifies the pager
+.I quilt
+shall use for commands which produce paginated output.
+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
+.I QUILT_COLORS
+By default,
+.I quilt
+uses a predefined color set in order to be more
+comprehensible when distiguishing various types of output,
+e.g.,
+a patch's status as applied, unapplied, or failed.
+.IP
+To override one or more color settings, this variable may be set to
+a colon-separated list of elements of the form
+.RI \\[lq] format-name\\c
+.BI = foreground-color\\c
+.RB [ ;\\c
+.IR background-color ]\\[rq].
+.IP
+Each
+.I format-name
+with its respective default
+.I foreground-color
+value is listed below,
+along with an explanation of where it is used.
+Numeric codes for foreground and background color values to be used in
+terminal escape sequences were specified by ANSI and incorporated into
+ISO-6429 and ECMA-48.
+The colors were given names but their values were not standardized
+within a color space;
+their precise appearance will vary and may be customizable in your
+terminal (emulator).
+.IP
+Each
+.I foreground-color
+may be one of
+30 (black),
+31 (red),
+32 (green),
+33 (yellow),
+34 (blue),
+35 (magenta),
+36 (cyan), or
+37 (white).
+Each
+.I background-color
+corresponds to the same color same names but adds ten, ranging from 40
+to 47.
+.RS
+.TP
+.B diff_hdr
+is used by
+.B quilt diff
+for the index line; the default is 32 (green).
+.TP
+.B diff_add
+is used by
+.B quilt diff
+for added lines; the default is 36 (cyan).
+.TP
+.B diff_mod
+is used by
+.B quilt diff
+for modified lines; the default is 35 (magenta).
+.TP
+.B diff_rem
+is used by
+.B quilt diff
+for removed lines; the default is 35 (magenta).
+.TP
+.B diff_hunk
+is used by
+.B quilt diff
+for the header of a patch hunk; the default is 33 (yellow).
+.TP
+.B diff_ctx
+is used by
+.B quilt diff
+for the context mark
+.RB ( "diff \\-\\-show\\-c\\-function"
+generates this);
+the default is 35 (magenta).
+.TP
+.B diff_cctx
+is used by
+.B quilt diff
+to color the 15-asterisk sequence before or after a hunk; the default is
+33 (yellow).
+.TP
+.B patch_fuzz
+is used by
+.B quilt push
+for the patch fuzz information; the default is 35 (magenta).
+.TP
+.B patch_fail
+is used by
+.B quilt push
+to color the fail message; the default is 31 (red).
+.TP
+.B series_app
+is used by
+.B quilt series
+and
+.B quilt patches
+for applied patch names; the default is 32 (green).
+.TP
+.B series_top
+is used by
+.B quilt series
+and
+.B quilt patches
+for the top patch name; the default is 33 (yellow).
+.TP
+.B series_una
+is used by
+.B quilt series
+and
+.B quilt patches
+for unapplied patch names; the default is 0 (normal foreground color).
+.RE
+.IP
+In addition, the
+.B clear
+format name is used to turn off special coloring.
+Its default value is 0; modifying it is not advised.
+.IP
+As an example, one can put the following in
+.I \\[ti]/.quiltrc
+(or
+.IR /etc/quilt.quiltrc ):
+.EX
+.RS 12
+QUILT_DIFF_ARGS="\\-\\-color"
+# Render diff headers in magenta over blue.
+# Render failed patches in the default foreground over red.
+QUILT_COLORS="diff_hdr=35;44:patch_fail=0;41"
.RE
-.RS 4
-In addition, the \\fBclear\\fP format name is used to turn off special
-coloring. Its value is 0; it is not advised to modify it.
-
-The content of QUILT_COLORS supersedes default values. So the value
-diff_hdr=35;44 will get you the diff headers in magenta over blue
-instead of the default green over unchanged background. For that, add
-the following content to ~/.quiltrc (or /etc/quilt.quiltrc):
-
-.nf
- QUILT_DIFF_ARGS="--color"
- QUILT_COLORS='diff_hdr=35;44'
-.fi
-.RE 4
-
+.EE
+.SH BUGS
+The
+.I QUILT_COLORS
+variable name and accompanying discussion is a bit misleading because
+.I quilt
+is simply emitting ANSI SGR (Select Graphic Rendition) sequences.
+Conseqently,
+the format is not limited to foreground and background colors and they
+do not have to be in the order specified.
+This is historically a poorly-understood aspect of terminal I/O.
.SH AUTHORS
-
-Quilt started as a series of scripts written by Andrew Morton
-(patch-scripts). Based on Andrew's ideas, Andreas Gruenbacher completely
-rewrote the scripts, with the help of several other contributors (see
-AUTHORS file in the distribution).
-
-This man page was written by Martin Quinson, based on information found in
-the pdf documentation, and in the help messages of each commands.
-
-.SH SEE ALSO
-
-The pdf documentation, which should be under @DOCSUBDIR@/quilt.pdf.
+.I Quilt
+started as a series of scripts written by Andrew Morton
+(patch\\-scripts).
+Based on Andrew's ideas,
+Andreas Gruenbacher completely rewrote the scripts,
+with the help of several other contributors (see the
+.I AUTHORS
+file 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 command.
+.SH "SEE ALSO"
+The PDF documentation, which should be under
+.IR @DOCSUBDIR@/quilt.pdf ,
+contains numerous examples of use.
Note that some distributors compress this file.
-.BR zxpdf ( 1 )
-can be used to display compressed pdf files.
-
-.BR diff ( 1 ),
-.BR patch ( 1 ),
-.BR guards ( 1 ).
+.BR zxpdf (1)
+can be used to display compressed PDF files.
+.PP
+.UR https://\\:www.ecma\\-international.org/\\:publications/\\
+\\:standards/\\:Ecma\\-048.htm
+.I Control Functions for Coded Character Sets
+(ECMA-48)
+.UE
+.PP
+.BR diff (1),
+.BR diffstat (1),
+.BR patch (1),
+.BR guards (1)
signature.asc
Description: PGP signature
_______________________________________________ Quilt-dev mailing list Quilt-dev@nongnu.org https://lists.nongnu.org/mailman/listinfo/quilt-dev
