From 6ccaaa6f3dbb16d0a0b07ef46deef1185f7138f2 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Wed, 3 Aug 2022 21:25:29 +0200 Subject: Man page: rewrite discussion of QUILT_COLORS configuration variable These are ANSI escape sequences as defined by ECMA-48; recast the entire discussion in light of that fact. Condense the many tagged paragraphs with a templated discussion of defaults into a table. Sort the QUILT_COLORS format names into alphabetical order. Add a hint to the formatter (man) to call the tbl preprocessor to render the table. Expand the example to be more demonstrative. Add pointers to the ECMA-48 standard document and the console_codes section 4 man page (from Michael Kerrisk's man-pages project, widely available) to the See Also section. [JD: Some fixes, added patch_offs to the table, added a note that the patches command shares colors with the series command] --- doc/quilt.1.in | 168 ++++++++++++++++++++++++++++----------------------------- 1 file changed, 83 insertions(+), 85 deletions(-) diff --git a/doc/quilt.1.in b/doc/quilt.1.in index e25b2a8..691cf14 100644 --- a/doc/quilt.1.in +++ b/doc/quilt.1.in @@ -1,3 +1,4 @@ +'\\" t .\\" Created by Martin Quinson from the tex documentation .\\" .TH quilt 1 "Dec 17, 2013" "quilt" @@ -426,101 +427,87 @@ 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 .I QUILT_COLORS -By default, +A sequence of definitions that directs .I quilt -uses its predefined color set in order to be more -comprehensible when distiguishing various types of patches, e.g., -applied/unapplied, failed, etc. +which ANSI escape sequences to associate with an output context, +overriding the defaults. +The most common use is to set colors (thus the name of this variable), +but other attributes exist, such as bold or reverse. .IP -To override one or more color settings, set the +To override one or more settings, set .I QUILT_COLORS -variable in following syntax - colon (:) separated list of elements, -each being of the form =[;] +to a colon-separated list of elements, +each of the form +.RI \\[lq] format-name\\c +.BI = digit-sequence\\c +.RB [ ; ...]\\[rq]. .IP -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 -.TP -.B diff_hdr -Used in \\[lq]quilt diff\\[rq] to color the index line. -Defaults to 32 (green). -.TP -.B diff_add -Used in \\[lq]quilt diff\\[rq] to color added lines. -Defaults to 36 (azure). -.TP -.B diff_mod -Used in \\[lq]quilt diff\\[rq] to color modified lines. -Defaults to 35 (purple). -.TP -.B diff_rem -Used in \\[lq]quilt diff\\[rq] to color removed lines. -Defaults to 35 (purple). -.TP -.B diff_hunk -Used in \\[lq]quilt diff\\[rq] to color hunk header. -Defaults to 33 (brown/orange). -.TP -.B diff_ctx -Used in \\[lq]quilt diff\\[rq] to color the text after end of hunk -header (\\[lq]diff \\-\\-show\\-c\\-function\\[rq] generates this). -Defaults to 35 (purple). -.TP -.B diff_cctx -Used in \\[lq]quilt diff\\[rq] to color the 15-asterisk sequence before -or after a hunk. -Defaults to 33 (brown/orange). -.TP -.B patch_fuzz -Used in \\[lq]quilt push\\[rq] to color the patch fuzz information. -Defaults to 35 (purple). -.TP -.B patch_fail -Used in \\[lq]quilt push\\[rq] to color the fail message. -Defaults to 31 (red). -.TP -.B series_app -Used in \\[lq]quilt series\\[rq] and \\[lq]quilt patches\\[rq] to color -the applied patch names. -Defaults to 32 (green). -.TP -.B series_top -Used in \\[lq]quilt series\\[rq] and \\[lq]quilt patches\\[rq] to color -the top patch name. -Defaults to 33 (brown/orange). -.TP -.B series_una -Used in \\[lq]quilt series\\[rq] and \\[lq]quilt patches\\[rq] to color -unapplied patch names. -Defaults to 0 (no special color). -.RE -.RS 4 -In addition, the -.B clear -format name is used to turn off special coloring. -Its value is 0; it is not advised to modify it. -.PP -The content of -.I QUILT_COLORS -supersedes default values. -So the value \\[lq]diff_hdr=35;44\\[rq] will get you the -.I diff -headers in magenta over blue instead of the default green over unchanged -background. -For that, add the following content to +Each +.I digit-sequence +should be a SGR (Select Graphic Rendition) value supported by your +terminal. +The standardized SGR values were specified by ANSI and incorporated +into ISO-6429 and ECMA-48 (\\[sc]8.3.117). +The colors have standard names but their values were not defined within +a color space; +their precise appearance will vary and may be customizable in your +terminal (emulator). +.IP +Recognized +.IR format-name s, +along with the +.I quilt +commands that use them, +their use contexts, +and default values, follow. +.TS +box; +lI l l l. +format-name command context default +_ +.T& +lB l l l. +diff_add diff added lines 36 (cyan) +diff_cctx diff asterisk sequences 33 (yellow) +diff_ctx diff text after hunk 35 (magenta) +diff_hdr diff index line 32 (green) +diff_hunk diff hunk header 33 (yellow) +diff_mod diff modified lines 35 (magenta) +diff_rem diff removed lines 35 (magenta) +patch_fail push failure message 31 (red) +patch_fuzz push fuzz information 35 (magenta) +patch_offs push offset information 33 (yellow) +series_app series applied patch names 32 (green) +series_top series top patch name 33 (yellow) +series_una series unapplied patch names 0 (none) +.TE +.IP +All +.IR format-name s +used by the series command are also used by the patches command. +.IP +The special +.I format-name +\\[lq]clear\\[rq] is used to turn off special graphic renditions and +return to the terminal defaults. +Changing its definition should not be necessary for any terminal that +claims to support ANSI escape sequences. +If your terminal is corrupted despite your best efforts, try the command +\\[lq]tput sgr0\\[rq] to restore the default graphic rendition. +.IP +As an example, one can put the following in .I \\[ti]/.quiltrc (or .IR /etc/quilt.quiltrc ): -.PP +.RS 12 .EX -.RS QUILT_DIFF_ARGS="\\-\\-color" -QUILT_COLORS='diff_hdr=35;44' -.RE +# Render diff file headers in bold blue over yellow. +# Render diff hunk headers in "negative image" yellow. +# Render failed patches with a red background. +QUILT_COLORS="diff_hdr=1;34;43:diff_hunk=7;33:patch_fail=41" .EE +.RE . .SH AUTHORS .fchar \\[:u] ue @@ -560,6 +547,17 @@ and .I patch in detail. .PP +.UR https://\\:www.ecma\\-international.org/\\:publications/\\:standards/\\:Ecma\\-048.htm +.I Control Functions for Coded Character Sets +(ECMA-48) +.UE +specifies the ANSI escape sequences used by +.IR QUILT_COLORS ; +section 8.3.117 will be of the most interest. +See +.BR console_codes (4) +for a more convenient, if less canonical, resource. +.PP .BR diff (1), .BR diffstat (1), .BR guards (1), -- cgit