]> git.refcnt.org Git - colorize.git/blob - colorize.1
Document config file usage
[colorize.git] / colorize.1
1 .TH COLORIZE 1 "2019-08-22" "colorize v0.64" "User Commands"
2 .SH NAME
3 colorize \- colorize text on terminal with ANSI escape sequences
4 .SH SYNOPSIS
5 \fBcolorize\fR [\fIoption\fR]... (\fIforeground\fR) [\fI-|file\fR]
6 .PP
7 \fBcolorize\fR [\fIoption\fR]... (\fIforeground\fR)/(\fIbackground\fR) [\fI-|file\fR]
8 .PP
9 \fBcolorize\fR \-\-clean[\-all] [\fI-|file\fR]
10 .PP
11 \fBcolorize\fR \-hV
12 .SH DESCRIPTION
13 Colorizes text read from standard input stream or file by using ANSI
14 escape sequences (and also vice versa, i.e. cleaning text from sequences)
15 and prints resulting output to the terminal.
16 .PP
17 When colorizing text, (foreground) and eventually (background) may be either
18 one of following color values: none, black, red, green, yellow, blue, magenta,
19 cyan, white, default or random. First character of color name in upper
20 case denotes increased intensity, whereas for lower case colors will be of
21 normal intensity. If "none" is chosen, no escape sequences will be emitted.
22 .PP
23 Color escape sequences are added per each line, hence colored lines can be
24 safely extracted.
25 .PP
26 When de-colorizing text, \-\-clean omits color escape sequences which
27 were emitted by colorize (see NOTES for list), whereas \-\-clean\-all
28 omits all valid ones. If in doubt, consider using \-\-clean\-all.
29 .SH OPTIONS
30 .TP
31 .BR \-\-attr=\fIATTR1,ATTR2,...\fR
32 set attributes by name
33 .RS
34 Attributes: bold, underscore, blink, reverse and concealed.
35 .RE
36 .TP
37 .BR \-\-clean
38 clean text from color escape sequences emitted by colorize
39 .TP
40 .BR \-\-clean\-all
41 clean text from all valid color escape sequences
42 .TP
43 .BR \-\-exclude\-random=\fICOLOR\fR
44 text color to be excluded when selecting a random foreground color
45 .TP
46 .BR \-\-omit\-color\-empty
47 omit printing color escape sequences for empty lines
48 .TP
49 .BR \-h ", " \-\-help
50 show help screen and exit
51 .TP
52 .BR \-V ", " \-\-version
53 display version data and exit
54 .SH FILES
55 .TP
56 .B ~/.colorize.conf
57 user configuration file
58 .PP
59 .RS
60 If the aforementioned file exists, it is read, parsed and processed
61 prior to handling the command-line options. Command-line options
62 override configuration values, but are currently not capable of
63 unsetting them. If unsetting is desired, comment them out or remove
64 them.
65 .RE
66 .PP
67 .RS
68 .B Sample configuration file
69 .RS
70 .nf
71 # ~/.colorize.conf
72 attr = bold,underscore
73 color = magenta # favorite one
74 exclude-random = black
75 omit-color-empty = yes
76 .fi
77 .RE
78 .RE
79 .PP
80 .RS
81 .B Configurable options and values
82 .RS
83 .nf
84 attr (values same as command-line option)
85 color (value same as command-line colors)
86 exclude-random (value same as command-line option)
87 omit-color-empty (yes/no)
88 .fi
89 .RE
90 .RE
91 .PP
92 .RS
93 .B Syntax
94 .RS
95 Each line ought to start with a name of an option, followed by = and
96 an optional value. Leaving the value blank, unsets the option.
97 .PP
98 Whitespace is allowed before the option name, after the option name,
99 before the option value and after the option value.
100 .PP
101 Comments may be placed before or after the option is set. Everything
102 following the '#' sign is treated as being commented out.
103 .RE
104 .RE
105 .SH NOTES
106 The list of color escape sequence codes being emitted and omitted is
107 as follows:
108 .IP * 4
109 30-37,39 (foreground colors)
110 .IP * 4
111 1-9;30-37,39 (foreground colors with attributes)
112 .IP * 4
113 40-47,49 (background colors)
114 .IP * 4
115 0 (reset)
116 .SH EXAMPLES
117 .TP
118 $ \fBcolorize green /etc/motd\fR
119 Print file /etc/motd with green as foreground color
120 .TP
121 $ \fBcolorize green/black /etc/motd\fR
122 Print file /etc/motd with green as foreground and black as background color
123 .TP
124 $ \fBcolorize green /etc/motd | colorize --clean\fR
125 Print input from stdin with color escape sequences omitted
126 .TP
127 $ \fBgit log -1 -p --color | colorize --clean-all\fR
128 Print input from stdin with all color escape sequences omitted
129 .TP
130 $ \fBcolorize --attr=bold green /etc/motd\fR
131 Print file /etc/motd with bold green as foreground color
132 .SH AUTHOR
133 Steven Schubiger <stsc@refcnt.org>