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 Debugging instructions
  39 ----------------------
  40 For the sake of completeness, colorize can be also built with
  41 debugging output by issuing `make FLAGS=-DDEBUG'.  The intention
  42 is to provide some memory allocation diagnostics (and might be
  43 extended in future).  Usually, a debugging build is not required.
  44
  45 Furthermore, tests can be run through valgrind by issuing, for
  46 example, `make check_valgrind 2>&1 | tee valgrind.out'.  The
  47 file provided here for the `tee' invocation will be populated
  48 with the captured output from both standard output and error
  49 stream.
  50
  51 Documentation
  52 -------------
  53 See man page source file: colorize.1.
  54
  55 Usage example
  56 -------------
  57 In ~/.bashrc:
  58
  59 | ls_color() {
  60 |     ls "$@" | colorize green -
  61 | }
  62 | alias ls=ls_color
  63
  64 This excerpt defines an alias which will set the color being
  65 printed for literal ls invocations to green.
  66
  67 Afterword
  68 ---------
  69 Let me know, if you have ideas, bug reports, patches, etc.
  70
  71 Author
  72 ------
  73 Steven Schubiger <stsc@refcnt.org>