lib/colors: update man page

Signed-off-by: Karel Zak <kzak@redhat.com>

1 files changed, 140 insertions, 11 deletions

diff --git a/lib/terminal-colors.d.5 b/lib/terminal-colors.d.5
index c5208cd74..f9e15828c 100644
--- a/lib/terminal-colors.d.5
+++ b/lib/terminal-colors.d.5
@@ -7,27 +7,156 @@
 .SH "NAME"
 terminal-colors.d \- Configure output colorization for various utilities
 .SH "SYNOPSIS"
-.PP
-/etc/terminal-colors.d/[name.]disable
-.sp
-/etc/terminal-colors.d/name.enable
+/etc/terminal-colors\&.d/[[name][@term]\&.][type]
 .SH "DESCRIPTION"
 Files in this directory determine the default behaviour for utilities
-when coloring output.  The
+when coloring output.
+
+The
 .B name
-is an utility name.  Supported files:
+is an utility name. The name is optional and when no specified than the
+file is used for all unspecified utilities.
 
+The
+.B term
+is a terminal identifier (the TERM environment variable).
+The terminal identifier is optional and when no specified than the file
+is used for all unspecified terminals.
+
+The
+.B type
+is a file type. Supported file types:
 .TP
 .B disable
 Turns off output colorization for all compatible utilities.
 .TP
-.B name.disable
-Turns off output colorization for specified utility.
-.TP
-.B name.enable
-Turns on output colorization on terminal for specified utility, all another
+.B enable
+Turns on output colorization, all another
 .B disable
 files are ignored.
+.TP
+.B scheme
+Specifies colors used for output. The file format may be specific to the utility,
+the default format is described below.
+.PP
+If there is more files that match for the utility then the file with more
+specific filename wins. For example filename "@xterm.scheme" has less
+priority than "dmesg@xterm.scheme". The lowest priority have files without
+utility name and terminal identifier (e.g. "disable").
+
+.SH EXAMPLES
+Disable colors for all compatible utilities:
+.RS
+.br
+.BI "touch /etc/terminal-colors.d/disable"
+.br
+.RE
+
+Disable colors for all compatible utils on vt100 terminal:
+.RS
+.br
+.BI "touch /etc/terminal-colors.d/@vt100.disable"
+.br
+.RE
+
+Disable colors for all compatible utils except dmesg(1):
+.RS
+.br
+.BI "touch /etc/terminal-colors.d/disable"
+.sp
+.BI "touch /etc/terminal-colors.d/dmesg.enable"
+.br
+.RE
+
+.SH DEFAULT SCHEME FILES FORMAT
+The following statement is recognized:
+
+.RS
+.br
+.BI "name color-sequence"
+.br
+.RE
+
+The
+.B 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.
+
+The
+.B color-sequence
+is a color name, ASCII color sequences or escape sequences.
+
+.SS Color names
+black, blue, brown, cyan, darkgray, gray, green, lightblue, lightcyan
+lightgray, lightgreen, lightmagenta, lightred, magenta, red and yellow
+.SS ANSI color sequences
+The color sequences are composed of sequences of numbers
+separated by semicolons. The most common codes are:
+.sp
+.RS
+.TS
+l l.
+ 0	to restore default color
+ 1	for brighter colors
+ 4	for underlined text
+ 5	for flashing text
+30	for black foreground
+31	for red foreground
+32	for green foreground
+33	for yellow (or brown) foreground
+34	for blue foreground
+35	for purple foreground
+36	for cyan foreground
+37	for white (or gray) foreground
+40	for black background
+41	for red background
+42	for green background
+43	for yellow (or brown) background
+44	for blue background
+45	for purple background
+46	for cyan background
+47	for white (or gray) background
+.TE
+.RE
+.SS Escape sequences
+To specify control or blank characters in the color sequences
+C-style \e-escaped notation can be used:
+.sp
+.RS
+.TS
+lb l.
+\ea	Bell (ASCII 7)
+\eb	Backspace (ASCII 8)
+\ee	Escape (ASCII 27)
+\ef	Form feed (ASCII 12)
+\en	Newline (ASCII 10)
+\er	Carriage Return (ASCII 13)
+\et	Tab (ASCII 9)
+\ev	Vertical Tab (ASCII 11)
+\e?	Delete (ASCII 127)
+\e_	Space
+\e\e	Backslash (\e)
+\e^	Caret (^)
+\e#	Hash mark (#)
+.TE
+.RE
+.sp
+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.
+
+For example to use red background for alert messages in
+.BR dmesg (1) 
+output use:
+
+.RS
+.br
+.BI "echo 'alert 37;41' >> /etc/terminal-colors.d/dmesg.scheme"
+.br
+.RE
+
+
 
 .SH COMPATIBILITY
 The terminal-colors.d functionality is currently supported by all util-linux