README

   1 colorize
   2 ========
   3
   4 Description
   5 -----------
   6 Colorize aims at being a small, independent and handy command-line
   7 text colorizing tool.  It emits ANSI escape sequences in order to
   8 color lines of text; also, sequences emitted by colorize or foreign
   9 programs may be cleared.
  10
  11 The main code is written in C (c89 mostly), whereas the test script
  12 consists of Perl code.
  13
  14 Colorize is known to build and test successfully on Linux and
  15 Net/Open/MirBSD.  Other platforms are untested, so be prepared for
  16 it to eventually not work as expected there.
  17
  18 Requirements
  19 ------------
  20 gcc
  21 make
  22 perl
  23 valgrind (optional)
  24
  25 Build instructions
  26 ------------------
  27 Issue `make' to build colorize.
  28
  29 Once completed, run the tests with `make check'.
  30
  31 Then you should most likely have a working binary.
  32
  33 Next, install it with `make install' (may require elevated
  34 user permissions).
  35
  36 Finally, clean up the working directory through `make clean'.
  37
  38 Customizing instructions
  39 ------------------------
  40 The default character ('/') which separates the foreground
  41 from the background color may be redefined:
  42
  43 `make FLAGS=-DCOLOR_SEP_CHAR_COLON' -> defines as ':'
  44 `make FLAGS=-DCOLOR_SEP_CHAR_SLASH' -> defines as '/'
  45
  46 Debugging instructions
  47 ----------------------
  48 For the sake of completeness, colorize can be also built with
  49 debugging output by issuing `make FLAGS=-DDEBUG'.  The intention
  50 is to provide some memory allocation diagnostics (and might be
  51 extended in future).  Usually, a debugging build is not required.
  52
  53 Furthermore, tests can be run through valgrind by issuing, for
  54 example, `make check_valgrind 2>&1 | tee valgrind.out'.  The
  55 file provided here for the `tee' invocation will be populated
  56 with the captured output from both standard output and error
  57 stream.
  58
  59 Configuration File
  60 ------------------
  61 A user configuration file may be populated with options and
  62 according values.  See man page source file `colorize.1' for
  63 details.
  64
  65 Documentation
  66 -------------
  67 See man page source file: colorize.1.
  68
  69 Usage example
  70 -------------
  71 In ~/.bashrc:
  72
  73 | ls_color() {
  74 |     ls "$@" | colorize green -
  75 | }
  76 | alias ls=ls_color
  77
  78 This excerpt defines an alias which will set the color being
  79 printed for literal ls invocations to green.
  80
  81 Afterword
  82 ---------
  83 Let me know, if you have ideas, bug reports, patches, etc.
  84
  85 Author
  86 ------
  87 Steven Schubiger <stsc@refcnt.org>