lib/terminal-colors.d.5.adoc

   1 //po4a: entry man manual
   2 ////
   3 terminal-colors.d.5 --
   4 Copyright 2014 Ondrej Oprala <ooprala@redhat.com>
   5 Copyright (C) 2014 Karel Zak <kzak@redhat.com>
   6 Copyright 2014 Red Hat, Inc.
   7 May be distributed under the GNU General Public License
   8 ////
   9
  10 = terminal-colors.d(5)
  11 :doctype: manpage
  12 :man manual: File formats
  13 :man source: util-linux {release-version}
  14 :page-layout: base
  15 :configfile: terminal-colors.d
  16
  17 == NAME
  18
  19 terminal-colors.d - configure output colorization for various utilities
  20
  21 == SYNOPSIS
  22
  23 /etc/terminal-colors.d/_[[name][@term].][type]_
  24
  25 == DESCRIPTION
  26
  27 Files in this directory determine the default behavior for utilities when coloring output.
  28
  29 The _name_ is a utility name. The name is optional and when none is specified then the file is used for all unspecified utilities.
  30
  31 The _term_ is a terminal identifier (the *TERM* environment variable). The terminal identifier is optional and when none is specified then the file is used for all unspecified terminals.
  32
  33 The _type_ is a file type. Supported file types are:
  34
  35 *disable*::
  36 Turns off output colorization for all compatible utilities.
  37
  38 *enable*::
  39 Turns on output colorization; any matching *disable* files are ignored.
  40
  41 *scheme*::
  42 Specifies colors used for output. The file format may be specific to the utility, the default format is described below.
  43
  44 If there are more files that match for a utility, then the file with the more specific filename wins. For example, the filename "@xterm.scheme" has less priority than "dmesg@xterm.scheme". The lowest priority are those files without a utility name and terminal identifier (e.g., "disable").
  45
  46 The user-specific _$XDG_CONFIG_HOME/terminal-colors.d_ or _$HOME/.config/terminal-colors.d_ overrides the global setting.
  47
  48 == DEFAULT SCHEME FILES FORMAT
  49
  50 The following statement is recognized:
  51
  52 ____
  53 *name color-sequence*
  54 ____
  55
  56 The *name* is a logical name of color sequence (for example "error"). The names are specific to the utilities. For more details always see the *COLORS* section in the man page for the utility.
  57
  58 The *color-sequence* is a color name, ASCII color sequences or escape sequences.
  59
  60 === Color names
  61
  62 black, blink, blue, bold, brown, cyan, darkgray, gray, green, halfbright, lightblue, lightcyan, lightgray, lightgreen, lightmagenta, lightred, magenta, red, reset, reverse, and yellow.
  63
  64 === ANSI color sequences
  65
  66 The color sequences are composed of sequences of numbers separated by semicolons. The most common codes are:
  67
  68 ____
  69 [cols=",",]
  70 |===
  71 |0 |to restore default color
  72 |1 |for brighter colors
  73 |4 |for underlined text
  74 |5 |for flashing text
  75 |30 |for black foreground
  76 |31 |for red foreground
  77 |32 |for green foreground
  78 |33 |for yellow (or brown) foreground
  79 |34 |for blue foreground
  80 |35 |for purple foreground
  81 |36 |for cyan foreground
  82 |37 |for white (or gray) foreground
  83 |40 |for black background
  84 |41 |for red background
  85 |42 |for green background
  86 |43 |for yellow (or brown) background
  87 |44 |for blue background
  88 |45 |for purple background
  89 |46 |for cyan background
  90 |47 |for white (or gray) background
  91 |===
  92 ____
  93
  94 === Escape sequences
  95
  96 To specify control or blank characters in the color sequences, C-style \-escaped notation can be used:
  97
  98 ____
  99 [cols=",",]
 100 |===
 101 |*\a* |Bell (ASCII 7)
 102 |*\b* |Backspace (ASCII 8)
 103 |*\e* |Escape (ASCII 27)
 104 |*\f* |Form feed (ASCII 12)
 105 |*\n* |Newline (ASCII 10)
 106 |*\r* |Carriage Return (ASCII 13)
 107 |*\t* |Tab (ASCII 9)
 108 |*\v* |Vertical Tab (ASCII 11)
 109 |*\?* |Delete (ASCII 127)
 110 |*\_* |Space
 111 |*\\* |Backslash (\)
 112 |*\^* |Caret (^)
 113 |*\#* |Hash mark (#)
 114 |===
 115 ____
 116
 117 Please note that escapes are necessary to enter a space, backslash, caret, or any control character anywhere in the string, as well as a hash mark as the first character.
 118
 119 For example, to use a red background for alert messages in the output of *dmesg*(1), use:
 120
 121 ____
 122 *echo 'alert 37;41' >> /etc/terminal-colors.d/dmesg.scheme*
 123 ____
 124
 125 === Comments
 126
 127 Lines where the first non-blank character is a # (hash) are ignored. Any other use of the hash character is not interpreted as introducing a comment.
 128
 129 == ENVIRONMENT
 130
 131 *TERMINAL_COLORS_DEBUG*=all::
 132 enables debug output.
 133
 134 == FILES
 135
 136 _$XDG_CONFIG_HOME/terminal-colors.d_
 137
 138 _$HOME/.config/terminal-colors.d_
 139
 140 _/etc/terminal-colors.d_
 141
 142 == EXAMPLE
 143
 144 Disable colors for all compatible utilities:
 145
 146 ____
 147 *touch /etc/terminal-colors.d/disable*
 148 ____
 149
 150 Disable colors for all compatible utils on a vt100 terminal:
 151
 152 ____
 153 *touch /etc/terminal-colors.d/@vt100.disable*
 154 ____
 155
 156 Disable colors for all compatible utils except *dmesg*(1):
 157
 158 ____
 159 *touch /etc/terminal-colors.d/disable*
 160
 161 *touch /etc/terminal-colors.d/dmesg.enable*
 162 ____
 163
 164 == COMPATIBILITY
 165
 166 The *terminal-colors.d* functionality is currently supported by all util-linux utilities which provides colorized output. For more details always see the *COLORS* section in the man page for the utility.
 167
 168 include::man-common/bugreports.adoc[]
 169
 170 include::man-common/footer-config.adoc[]
 171
 172 ifdef::translation[]
 173 include::man-common/translation.adoc[]
 174 endif::[]