$Id$

   o  Colour does not work with all backends and all terminals. I tested
      many terminal emulators and tried to summarise which combinations
      worked properly and which ones did not.

      From termcap(5):

       set_a_background              setab        AB        Set background
                                                            color to #1, using
                                                            ANSI escape
       set_a_foreground              setaf        AF        Set foreground
                                                            color to #1, using
                                                            ANSI escape
      From the xterm terminfo:

        setab=\E[4%p1%dm, setaf=\E[3%p1%dm

      From the xterm-16color terminfo:
      (http://www.sct.gu.edu.au/~anthony/info/X/Xterm_xf86.terminfo)

        setab=\E[%?%p1%{8}%<%t%p1%{40}%+%e%p1%{92}%+%;%dm,
        setaf=\E[%?%p1%{8}%<%t%p1%{30}%+%e%p1%{82}%+%;%dm,

      These values can be simply retrieved with a tigetstr() call.

   o  I tested the following terminals:

         name             $TERM        $COLORTERM
        ------------------------------------------
         Linux console    linux
         pterm            xterm
         aterm            xterm        rxvt-xpm
         wterm            xterm        wterm-xpm
         Eterm            xterm        Eterm
         xterm            xterm
         gnome-terminal   xterm
         konsole          xterm
         mlterm           mlterm
         uxterm           xterm

   o  In most terminals, \e[3xm and \[4xm respectively set the foreground
      and background colours. x is a colour between 0 and 7 or the value
      9 for default colour (may be transparent).

      \e[0m sets everything to normal, \e[1m sets bold, \e[5m sets blink
      and \e[7m sets inverse video.

      In ncurses, only 64 colour pairs are created, and A_BOLD (\e[1m) and
      A_BLINK (\e[5m) are used for foreground/background colour highlighting,
      hence creating 256 possible colour pairs.

      Different tests of blue on yellow:

      for invert in '' '\e[7m'; do
        for blink in '' '\e[5m'; do
          for bold in '' '\e[1m'; do
            echo -ne "$bold$blink$invert"'\e[33m\e[44m'hop'\e[0m '
            echo "($bold$blink$invert)"
          done
        done
      done

      Successfully works on:
       + Linux console
       + pterm
       + Eterm
       + aterm, wterm, rxvt

      Almost works on:
       + xterm (bright bg only works when fg is bright and then inverted,
         but then fg is not bright)

      Fails on:
       + mlterm (no bright colours, neither fg nor bg)
       + gnome-terminal (no bright bg)
       + konsole (no bright bg, $blink really blinks)

   o In an XTerm-compatible terminal, \e[9xm sets bright foreground
     and \e[10xm bright background colours. Documentation on this can be
     found at http://ftp.xfree86.org/pub/XFree86/4.2.1/doc/ctlseqs.TXT .
     Unfortunately all terminals don't support these escape sequences. Here
     is a testcase:

      for fgpre in 3 9; do for fg in 0 4 2 6 1 5 3 7; do
        for bgpre in 4 10; do
          echo -ne '\e['$fgpre$fg'm'
          for bg in 0 4 2 6 1 5 3 7; do echo -ne '\e['$bgpre$bg'm# '; done
          echo -ne '\e[0m '
        done
        echo ''
      done; echo ''; done

      Successfully tested on:
       + gnome-terminal
       + konsole
       + xterm
       + pterm

      Failed (\e[9x and \e[10x don't do anything) on:
       + Eterm
       + aterm, wterm, rxvt
       + mlterm
       + Linux console

   o  How to draw bright colours on any terminal?

      '\e[93;104m' -> bright yellow on bright blue
       doesn't work on mlterm, gnome-terminal, konsole

      '\e[5;1;33;44m' -> bright yellow on bright blue
       doesn't work on mlterm, aterm/wterm/rxvt, Eterm, console

      '\e[5;1;33;44;93;104m' -> bright yellow on bright blue
       works on gnome-terminal, xterm, pterm, aterm/wterm/rxvt, console
       doesn't work on konsole

   o  S-Lang:

      256 character pairs are definable, but only 128 can be used. This is
      because slsmg.c's This_Color variable uses its 8th bit to indicate an
      alternate character set. Replacing a few 0x7F with 0xFF in sldisply.c
      works around the problem but gets rid of the alternate charset.

      We can work around this problem. See this usage grid:

                      bg                         1 1 1 1 1 1
        fg                  0 1 2 3 4 5 6 7  8 9 0 1 2 3 4 5

        0 (black)             C C C C C C F  B c c c c c c F
        1 (blue)            A   h D h D i f  C C h E h E k g
        2 (green)           A h   D h i D f  C h C E h k E g
        3 (cyan)            A D D   i h h f  C E E C k h h g
        4 (red)             A h h i   D D f  C h h k C E E g
        5 (magenta)         A D i h D   h f  C E k h E C h g
        6 (brown)           A i D h D h   f  C k E h E h C g
        7 (light gray)      A F a a a a a    B C C C C C C B

        8 (dark gray)       A C C C C C C B    d d d d d d F
        9 (light blue)      A C h E h E j C  e   h D h D l C
        10 (light green)    A h C E h j E C  e h   D h l D C
        11 (light cyan)     A E E C j h h C  e D D   l h h C
        12 (light red)      A h h j C E E C  e h h l   D D C
        13 (light magenta)  A E j h E C h C  e D l h D   h C
        14 (yellow)         A j E h E h C C  e l D h D h   C
        15 (white)          A F b b b b b B  F C C C C C C  

      ' ': useless colour pairs that can be emulated by printing a space in
           any other colour pair that has the same background
      'A': black background colour pairs that are needed for the old renderer
      'B': gray combinations used for grayscale dithering
      'C': white/light, light/dark, lightgray/light, darkgray/dark, dark/black
           combinations often used for saturation/value dithering (the two
           other possible combinations, lightgray/dark and darkgray/light, are
           not considered here)
      'D': next colour combinations for hue dithering (magenta/blue, blue/green
           and so on)
      'E': next colour combinations for hue/value dithering (blue/lightgreen,
           green/lightblue and so on)
      'F': black on light gray, black on white, white on dark gray, dark gray
           on white, white on blue, light gray on blue (chosen arbitrarily)

      'A': 15 colour pairs
      'A'+'B': 20 colour pairs
      'A'+'B'+'C': 74 colour pairs
      'A'+'B'+'C'+'D': 98 colour pairs
      'A'+'B'+'C'+'D'+'E': 122 colour pairs
      'A'+'B'+'C'+'D'+'E'+'F': 128 colour pairs

      The remaining slightly important colour pairs are:

      'a': light gray on dark colour: emulate with light colour on dark colour
      'b': white on dark colour: emulate with light gray on light colour
      'c': black on light colour: emulate with dark gray on dark colour
      'd': dark gray on light colour: emulate with dark colour on light colour
      'e': light colour on dark gray: emulate with dark colour on dark gray
      'f': dark colour on light gray: emulate with light colour on light gray
      'g': dark colour on white: emulate with light colour on white

      And now the seldom used pairs:

      'h': 120 degree hue pairs can be emulated as well; for instance blue on
           red can be emulated using magenta on red, and blue on green using
           cyan on green

      And the almost never used pairs:

      'i': dark opposite on dark: emulate with dark opposite on black
      'j': light opposite on dark: emulate with light opposite on black
      'k': dark opposite on light: emulate with black on dark
      'l': light opposite on light: emulate with white on light

   o  MS-DOS: all bright colours, bright backgrounds, and bright combinations
      work using <conio.h>. No need to kludge anything.

   o  Win32: we use GetConsoleScreenBufferInfo etc. There is an interesting
      tutorial here: http://www.adrianxw.dk/SoftwareSite/index.html

   o  Set terminal window title:
      http://mail.gnome.org/archives/mc-devel/2003-January/msg00101.html