-.TH COLORIZE 1 "2013-04-29" "colorize v0.50" "User Commands"
+.TH COLORIZE 1 "2014-01-02" "colorize v0.54" "User Commands"
.SH NAME
colorize \- colorize text with escape sequences
.SH SYNOPSIS
-\fBcolorize\fR [option] (foreground) \fIfile\fR
+\fBcolorize\fR [\fIoption\fR] (\fIforeground\fR) [\fIfile\fR]
.PP
-\fBcolorize\fR [option] (foreground)/(background) \fIfile\fR
+\fBcolorize\fR [\fIoption\fR] (\fIforeground\fR)/(\fIbackground\fR) [\fIfile\fR]
.PP
-\fBcolorize\fR \-\-clean[\-all] \fIfile\fR
+\fBcolorize\fR \-\-clean[\-all] [\fIfile\fR]
.PP
\fBcolorize\fR \-hv
.SH DESCRIPTION
and prints resulting output to the terminal.
.PP
When colorizing text, (foreground) and eventually (background) may be either
-one of following color values: none, black, red, green, yellow, blue, cyan,
-magenta, white, default or random. First character of color name in upper
+one of following color values: none, black, red, green, yellow, blue, magenta,
+cyan, white, default or random. First character of color name in upper
case denotes increased intensity, whereas for lower case colors will be of
-normal intensity. If "none" is chosen, no escape sequences will be emitted.
+normal intensity. If "none" is chosen, no escape sequences will be emitted.
+.PP
+Color escape sequences are added per each line, hence colored lines can be
+safely extracted.
.PP
When de-colorizing text, \-\-clean omits color escape sequences which
-were emitted by colorize, whereas \-\-clean\-all omits all valid ones.
-If in doubt, consider using \-\-clean\-all.
+were emitted by colorize (see NOTES for list), whereas \-\-clean\-all
+omits all valid ones. If in doubt, consider using \-\-clean\-all.
.SH OPTIONS
.TP
.BR \-\-clean
text color to be excluded when selecting a random foreground color
.TP
.BR \-h ", " \-\-help
-show usage screen and exit
+show help screen and exit
.TP
.BR \-v ", " \-\-version
display version data and exit
+.SH NOTES
+The list of color escape sequence codes being emitted and omitted is
+as follows:
+.IP * 4
+30-37,39 (foreground colors)
+.IP * 4
+1;30-37,39 (bold foreground colors)
+.IP * 4
+40-47,49 (background colors)
+.IP * 4
+0 (reset)
.SH AUTHOR
Steven Schubiger <stsc@refcnt.org>