X-Git-Url: http://git.refcnt.org/?p=colorize.git;a=blobdiff_plain;f=colorize.1;h=02ffe2ead8fbf50de5327835d77d0e42177b3a87;hp=c6f0bdb4551485dde4bbe486628ee5560ae741f5;hb=b5ff1ba35b959261c855262b6e820732e72b0bfe;hpb=20c83df5d03e4b89d3a93803db0f9f9307517faf

diff --git a/colorize.1 b/colorize.1
index c6f0bdb..02ffe2e 100644
--- a/colorize.1
+++ b/colorize.1
@@ -1,14 +1,14 @@
-.TH COLORIZE 1 "2014-01-02" "colorize v0.55" "User Commands"
+.TH COLORIZE 1 "2019-09-01" "colorize v0.64" "User Commands"
 .SH NAME
-colorize \- colorize text with escape sequences
+colorize \- colorize text on terminal with ANSI escape sequences
 .SH SYNOPSIS
-\fBcolorize\fR [\fIoption\fR] (\fIforeground\fR) [\fIfile\fR]
+\fBcolorize\fR [\fIoption\fR]... (\fIforeground\fR) [\fI-|file\fR]
 .PP
-\fBcolorize\fR [\fIoption\fR] (\fIforeground\fR)/(\fIbackground\fR) [\fIfile\fR]
+\fBcolorize\fR [\fIoption\fR]... (\fIforeground\fR)/(\fIbackground\fR) [\fI-|file\fR]
 .PP
-\fBcolorize\fR \-\-clean[\-all] [\fIfile\fR]
+\fBcolorize\fR \-\-clean[\-all] [\fI-|file\fR]
 .PP
-\fBcolorize\fR \-hv
+\fBcolorize\fR \-hV
 .SH DESCRIPTION
 Colorizes text read from standard input stream or file by using ANSI
 escape sequences (and also vice versa, i.e. cleaning text from sequences)
@@ -28,30 +28,109 @@ 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 \-\-attr=\fIATTR1,ATTR2,...\fR
+set attributes by name
+.RS
+Attributes: bold, underscore, blink, reverse and concealed.
+.RE
+.TP
 .BR \-\-clean
 clean text from color escape sequences emitted by colorize
 .TP
 .BR \-\-clean\-all
 clean text from all valid color escape sequences
 .TP
+.BR \-c ", " \-\-config=\fIPATH\fR
+alternate configuration file location
+.TP
 .BR \-\-exclude\-random=\fICOLOR\fR
 text color to be excluded when selecting a random foreground color
 .TP
+.BR \-\-omit\-color\-empty
+omit printing color escape sequences for empty lines
+.TP
 .BR \-h ", " \-\-help
 show help screen and exit
 .TP
-.BR \-v ", " \-\-version
+.BR \-V ", " \-\-version
 display version data and exit
+.SH FILES
+.TP
+.B ~/.colorize.conf
+user configuration file
+.PP
+.RS
+If the aforementioned file exists, it is read, parsed and processed
+prior to handling the command-line options.  Command-line options
+override configuration values, but are currently not capable of
+unsetting them.  If unsetting is desired, comment them out or remove
+them.
+.RE
+.PP
+.RS
+.B Sample configuration file
+.RS
+.nf
+# ~/.colorize.conf
+attr = bold,underscore
+color = magenta # favorite one
+exclude-random = black
+omit-color-empty = yes
+.fi
+.RE
+.RE
+.PP
+.RS
+.B Configurable options and values
+.RS
+.nf
+attr             (values same as command-line option)
+color            (value  same as command-line colors)
+exclude-random   (value  same as command-line option)
+omit-color-empty (yes/no)
+.fi
+.RE
+.RE
+.PP
+.RS
+.B Syntax
+.RS
+Each line ought to start with a name of an option, followed by = and
+an optional value.  Leaving the value blank, unsets the option.
+.PP
+Whitespace is allowed before the option name, after the option name,
+before the option value and after the option value.
+.PP
+Comments may be placed before or after the option is set.  Everything
+following the '#' sign is treated as being commented out.
+.RE
+.RE
 .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)
+1-9;30-37,39 (foreground colors with attributes)
 .IP * 4
 40-47,49 (background colors)
 .IP * 4
 0 (reset)
+.SH EXAMPLES
+.TP
+$ \fBcolorize green /etc/motd\fR
+Print file /etc/motd with green as foreground color
+.TP
+$ \fBcolorize green/black /etc/motd\fR
+Print file /etc/motd with green as foreground and black as background color
+.TP
+$ \fBcolorize green /etc/motd | colorize --clean\fR
+Print input from stdin with color escape sequences omitted
+.TP
+$ \fBgit log -1 -p --color | colorize --clean-all\fR
+Print input from stdin with all color escape sequences omitted
+.TP
+$ \fBcolorize --attr=bold green /etc/motd\fR
+Print file /etc/motd with bold green as foreground color
 .SH AUTHOR
 Steven Schubiger <stsc@refcnt.org>