colorize.1

   1 .TH COLORIZE 1 "2019-09-01" "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 \-c ", " \-\-config=\fIPATH\fR
  44 alternate configuration file location
  45 .TP
  46 .BR \-\-exclude\-random=\fICOLOR\fR
  47 text color to be excluded when selecting a random foreground color
  48 .TP
  49 .BR \-\-omit\-color\-empty
  50 omit printing color escape sequences for empty lines
  51 .TP
  52 .BR \-h ", " \-\-help
  53 show help screen and exit
  54 .TP
  55 .BR \-V ", " \-\-version
  56 display version data and exit
  57 .SH FILES
  58 .TP
  59 .B ~/.colorize.conf
  60 user configuration file
  61 .PP
  62 .RS
  63 If the aforementioned file exists, it is read, parsed and processed
  64 prior to handling the command-line options.  Command-line options
  65 override configuration values, but are currently not capable of
  66 unsetting them.  If unsetting is desired, comment them out or remove
  67 them.
  68 .RE
  69 .PP
  70 .RS
  71 .B Sample configuration file
  72 .RS
  73 .nf
  74 # ~/.colorize.conf
  75 attr = bold,underscore
  76 color = magenta # favorite one
  77 exclude-random = black
  78 omit-color-empty = yes
  79 .fi
  80 .RE
  81 .RE
  82 .PP
  83 .RS
  84 .B Configurable options and values
  85 .RS
  86 .nf
  87 attr             (values same as command-line option)
  88 color            (value  same as command-line colors)
  89 exclude-random   (value  same as command-line option)
  90 omit-color-empty (yes/no)
  91 .fi
  92 .RE
  93 .RE
  94 .PP
  95 .RS
  96 .B Syntax
  97 .RS
  98 Each line ought to start with a name of an option, followed by = and
  99 an optional value.  Leaving the value blank, unsets the option.
 100 .PP
 101 Whitespace is allowed before the option name, after the option name,
 102 before the option value and after the option value.
 103 .PP
 104 Comments may be placed before or after the option is set.  Everything
 105 following the '#' sign is treated as being commented out.
 106 .RE
 107 .RE
 108 .SH NOTES
 109 The list of color escape sequence codes being emitted and omitted is
 110 as follows:
 111 .IP * 4
 112 30-37,39 (foreground colors)
 113 .IP * 4
 114 1-9;30-37,39 (foreground colors with attributes)
 115 .IP * 4
 116 40-47,49 (background colors)
 117 .IP * 4
 118 0 (reset)
 119 .SH EXAMPLES
 120 .TP
 121 $ \fBcolorize green /etc/motd\fR
 122 Print file /etc/motd with green as foreground color
 123 .TP
 124 $ \fBcolorize green/black /etc/motd\fR
 125 Print file /etc/motd with green as foreground and black as background color
 126 .TP
 127 $ \fBcolorize green /etc/motd | colorize --clean\fR
 128 Print input from stdin with color escape sequences omitted
 129 .TP
 130 $ \fBgit log -1 -p --color | colorize --clean-all\fR
 131 Print input from stdin with all color escape sequences omitted
 132 .TP
 133 $ \fBcolorize --attr=bold green /etc/motd\fR
 134 Print file /etc/motd with bold green as foreground color
 135 .SH AUTHOR
 136 Steven Schubiger <stsc@refcnt.org>