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 Documentation
  60 -------------
  61 See man page source file: colorize.1.
  62
  63 Usage example
  64 -------------
  65 In ~/.bashrc:
  66
  67 | ls_color() {
  68 |     ls "$@" | colorize green -
  69 | }
  70 | alias ls=ls_color
  71
  72 This excerpt defines an alias which will set the color being
  73 printed for literal ls invocations to green.
  74
  75 Afterword
  76 ---------
  77 Let me know, if you have ideas, bug reports, patches, etc.
  78
  79 Author
  80 ------
  81 Steven Schubiger <stsc@refcnt.org>