Add CSAprox plugin.

1 files changed, 599 insertions, 0 deletions

diff --git a/files/.vim/doc/CSApprox.txt b/files/.vim/doc/CSApprox.txt
new file mode 100644
index 0000000..d91bb62
--- /dev/null
+++ b/files/.vim/doc/CSApprox.txt
@@ -0,0 +1,599 @@
+*CSApprox.txt*  Bringing GVim colorschemes to the terminal!
+
+                                                     *csapprox* *csapprox.vim*
+
+                  _____ ____ ___                               ~
+                 / ___// __// _ |  ___   ___   ____ ___  __ __ ~
+                / /__ _\ \ / __ | / _ \ / _ \ / __// _ \ \ \ / ~
+                \___//___//_/ |_|/ .__// .__//_/   \___//_\_\  ~
+                                /_/   /_/                      ~
+                                                  For Vim version 7.0 or newer
+                                                      Last changed 01 Apr 2009
+
+                               By Matt Wozniski
+                                mjw@drexel.edu
+
+                              Reference Manual~
+
+                                                                *csapprox-toc*
+
+1. Introduction                                       |csapprox-intro|
+2. Requirements                                       |csapprox-requirements|
+3. Configuration                                      |csapprox-configure|
+4. Rationale/Design                                   |csapprox-design|
+5. Known Bugs and Limitations                         |csapprox-limitations|
+6. Appendix - Terminals and Palettes                  |csapprox-terminal-list|
+7. Changelog                                          |csapprox-changelog|
+8. Contact Info                                       |csapprox-author|
+
+The functionality mentioned here is a plugin, see |add-plugin|.
+You can avoid loading this plugin by setting the "CSApprox_loaded" global
+variable in your |vimrc| file: >
+    :let g:CSApprox_loaded = 1
+
+==============================================================================
+1. Introduction                                               *csapprox-intro*
+
+It's hard to find colorschemes for terminal Vim.  Most colorschemes are
+written to only support GVim, and don't work at all in terminal Vim.
+
+This plugin makes GVim-only colorschemes Just Work in terminal Vim, as long
+as the terminal supports 88 or 256 colors - and most do these days.  This
+usually requires no user interaction (but see below for what to do if things
+don't Just Work).  After getting this plugin happily installed, any time you
+use :colorscheme it will do its magic and make the colorscheme Just Work.
+
+Whenever you change colorschemes using the :colorscheme command this script
+will be executed.  It will take the colors that the scheme specified for use
+in the GUI and use an approximation algorithm to try to gracefully degrade
+them to the closest color available in your terminal.  If you are running in
+a GUI or if your terminal doesn't support 88 or 256 colors, no changes are
+made.  Also, no changes will be made if the colorscheme seems to have been
+high color already.
+
+If for some reason this transparent method isn't suitable to you (for instance
+if your environment can't be configured to meet the |csapprox-requirements|,
+or you need to work in Vim 6), another option is also available: using the
+|:CSApproxSnapshot| command to create a new GUI/88-/256-color terminal
+colorscheme.  To use this command, a user would generally start GVim, choose a
+colorscheme that sets up the desired colors, and then use |:CSApproxSnapshot|
+to create a new colorscheme based on those colors that works in high color
+terminals.  This method is more flexible than the transparent mode and works
+in more places, but also requires more user intervention, and makes it harder
+to deal with colorschemes being updated and such.
+                                                           *:CSApproxSnapshot*
+The full syntax for the command is: >
+    :CSApproxSnapshot[!] /path/to/new/colorscheme
+<       For example: >
+    :CSApproxSnapshot ~/.vim/colors/foobar.vim
+<
+NOTE: The generated colorscheme will only work in 88- and 256-color terminals,
+      and in GVim.  It will not work at all in a terminal with 16 or fewer
+      colors.  There's just no reliable way to approximate down from
+      16,777,216 colors to 16 colors, especially without there being any
+      standard for what those 16 colors look like other than 'orange-ish',
+      'red-ish', etc.
+
+NOTE: Although :CSApproxSnapshot can be used in both GVim and terminal Vim,
+      the resulting colors might be slightly off when run from terminal Vim.
+      I can find no way around this; Vim internally sets different colors when
+      running in a terminal than running in the GUI, and there's no way for
+      terminal Vim to figure out what color would have been used in GVim.
+
+==============================================================================
+2. Requirements                                        *csapprox-requirements*
+
+For CSApprox to work, there are 2 major requirements that must be met.
+
+a) GUI support                          *csapprox-gui-support* *csapprox-+gui*
+
+If CSApprox is being used to adjust a scheme's colors transparently, then the
+terminal "vim" binary that is being run must be built with GUI support (see
+|csapprox-limitations| for an explanation).  If |:CSApproxSnapshot| is being
+used to create a terminal colorscheme for high color terminals, then the
+"vim" binary being used to create the scheme must be built with +gui, but the
+scheme can be used in terminal "vim" binaries that weren't built with +gui.
+NOTE that creating snapshots with GVim will work better than making them with
+Vim, and (obviously) all "gvim" binaries are built with +gui.
+
+Unfortunately, several Linux distributions only include GUI support in their
+"gvim" binary, and not in their "vim" binary.  You can check if GUI support is
+available with the following command:
+    :echo has('gui')
+
+If that prints 0, the first thing to try would be searching for a larger vim
+package provided by your distribution, like "vim-enhanced" on RedHat/CentOS
+or "vim-gtk" or "vim-gnome" on Debian/Ubuntu.
+
+If you are unable to obtain a "vim" binary that includes GUI support, but
+have a "gvim" binary available, you can probably launch Vim with GUI support
+anyway by calling gvim with the |-v| flag in the shell: >
+    gvim -v
+
+If the above works, you can remove the need to call "gvim -v" instead of "vim"
+all the time by creating a symbolic link from your "gvim" binary to "vim"
+somewhere in your $PATH, for example:
+    sudo ln -s $(which gvim) $(which vim)
+
+If launching as "gvim -v" doesn"t work, and no package with GUI support is
+available, you will need to compile Vim yourself and ensure that GUI support
+is included to use CSApprox in its transparent mode, or create a snapshotted
+scheme from GVim to use its snapshot mode.  If this is inconvenient for you,
+make sure that the Vim maintainer for your distribution knows it; they made a
+conscious decision to build "vim" without +gui and "gvim" without terminal
+support.
+
+b) Properly configured terminal                            *csapprox-terminal*
+
+As said above, many modern terminals support 88 or 256 colors, but most of
+these default to setting $TERM to something generic (usually "xterm").  Since
+Vim uses the value of the "colors" attribute for the current $TERM in terminfo
+to figure out the number of colors used internally as 't_Co', this plugin will
+either need for 't_Co' to be set to 88 or 256 in |vimrc|, or for $TERM to be
+set to something that implies high color support.  Possible choices include
+"xterm-256color" for 256 color support and "rxvt-unicode" for 88 color
+support.
+                                                              *csapprox-palettes*
+Also, there are three different 256 color cube palettes available and CSApprox
+has no way to tell which you're using unless $TERM is set to something that is
+specific to the terminal, like "konsole-256color" or "Eterm".  Because of this, the
+most sane behavior is assuming the user is using the most popular palette,
+which is used by all but Konsole and Eterm, whenever $TERM is set to something
+generic like "xterm" or "screen".  You can override this default, however -
+see |csapprox-configure|.
+                                                   *csapprox-terminal-example*
+To turn on high color support without fixing $TERM, you can change t_Co in
+your .vimrc, and set either CSApprox_konsole or CSApprox_eterm if appropriate.
+One way would be to put something like this into your |vimrc|:
+>
+    if (&term == 'xterm' || &term =~? '^screen') && hostname() == 'my-machine'
+        " On my machine, I use Konsole with 256 color support
+        set t_Co=256
+        let g:CSApprox_konsole = 1
+    endif
+
+Gnome Terminal, as of the time that I am writing this, doesn't support having
+the terminal emulator set $TERM to something adequately descriptive.  In cases
+like this, something like the following would be appropriate:
+>
+    if &term =~ '^\(xterm\|screen\)$' && $COLORTERM == 'gnome-terminal'
+      set t_Co=256
+    endif
+
+==============================================================================
+3. Configuration                                          *csapprox-configure*
+
+There are several global variables that can be set to configure the behavior
+of CSApprox.  They are listed roughly based on the likelihood that the end
+user might want to know about them.
+
+g:CSApprox_loaded                                          *g:CSApprox_loaded*
+    If set in your |vimrc|, CSApprox is not loaded.  Has no effect on
+    snapshotted schemes.
+
+g:CSApprox_verbose_level                            *g:CSApprox_verbose_level*
+    When CSApprox is run, the 'verbose' option will be temporarily raised to
+    the value held in this variable unless it is already greater.  The default
+    value is 1, which allows CSApprox to default to warning whenever something
+    is wrong, even if it is recoverable, but allows the user to quiet us if he
+    wants by changing this variable to 0.  The most important messages will be
+    shown at verbosity level 1; some less important ones will be shown at
+    higher verbosity levels.  Has no effect on snapshotted schemes.
+
+g:CSApprox_eterm                                            *g:CSApprox_eterm*
+    If set to a non-zero number, CSApprox will use the Eterm palette when
+    'term' is set to "xterm" or begins with "screen".  Otherwise, the xterm
+    palette would be used.  This also affects snapshotted schemes.
+
+g:CSApprox_konsole                                        *g:CSApprox_konsole*
+    If set to a non-zero number, CSApprox will use the Konsole palette when
+    'term' is set to "xterm" or begins with "screen".  Otherwise, the xterm
+    palette would be used.  This also affects snapshotted schemes.
+
+g:CSApprox_attr_map                                      *g:CSApprox_attr_map*
+    Since some attributes (like 'guisp') can't be used in a terminal, and
+    others (like 'italic') are often very ugly in terminals, a generic way to
+    map between a requested attribute and another attribute is included.  This
+    variable should be set to a Dictionary, where the keys are strings
+    representing the attributes the author wanted set, and the values are the
+    strings that the user wants set instead.  If a value is '', it means the
+    attribute should just be ignored.  The default is to replace 'italic' with
+    'underline', and to use 'fg' instead of 'sp': >
+        let g:CSApprox_attr_map = { 'italic' : 'underline', 'sp' : 'fg' }
+<
+    Your author prefers disabling bold and italic entirely, so uses this: >
+        let g:CSApprox_attr_map = { 'bold' : '', 'italic' : '', 'sp' : 'fg' }
+<
+
+    Note: This transformation is considered at the time a snapshotted scheme
+          is created, rather than when it is used.
+
+    Note: You can only map an attribute representing a color to another
+          attribute representing a color; likewise with boolean attributes.
+          After all, sp -> bold and italic -> fg would be nonsensical.
+
+                          *g:CSApprox_hook_pre* *g:CSApprox_hook_{scheme}_pre*
+                        *g:CSApprox_hook_post* *g:CSApprox_hook_{scheme}_post*
+g:CSApprox_hook_pre
+g:CSApprox_hook_post
+g:CSApprox_hook_{scheme}_pre
+g:CSApprox_hook_{scheme}_post                                 *csapprox-hooks*
+    These variables provide a method for adjusting tweaking the approximation
+    algorithm, either for all schemes, or on a per scheme basis.  For
+    snapshotted schemes, these will only take effect when the snapshotted
+    scheme is created, rather than when it is used.  Each of these variables
+    may be set to either a String containing a command to be :execute'd, or a
+    List of such Strings.  The _pre hooks are executed before any
+    approximations have been done.  In order to affect the approximation at
+    this stage, you would need to change the gui colors for a group; the cterm
+    colors will then be approximated from those gui colors.  Example:
+>
+      let g:CSApprox_hook_pre = 'hi Comment guibg=#ffddff'
+<
+    The advantage to tweaking the colors at this stage is that CSApprox will
+    handle approximating the given gui colors to the proper cterm colors,
+    regardless of the number of colors the terminal supports.  The
+    disadvantage is that certain things aren't possible, including clearing
+    the background or foreground color for a group, selecting a precise cterm
+    color to be used, and overriding the mappings made by g:CSApprox_attr_map.
+    Another notable disadvantage is that overriding things at this level will
+    actually affect the gui colors, in case the :gui is used to start gvim
+    from the running vim instance.
+
+    To overcome these disadvantages, the _post hooks are provided.  These
+    hooks will be executed only after all approximations have been completed.
+    At this stage, in order to have changes appear the cterm* colors must be
+    modified.  For example:
+                                                       *csapprox-transparency*
+>
+      let g:CSApprox_hook_post = ['hi Normal  ctermbg=NONE ctermfg=NONE',
+                                \ 'hi NonText ctermbg=NONE ctermfg=NONE' ]
+<
+    Setting g:CSApprox_hook_post as shown above will clear the background of
+    the Normal and NonText groups, forcing the terminal's default background
+    color to be used instead, including any pseudotransparency done by that
+    terminal emulator.  As noted, though, the _post functions do not allow
+    CSApprox to approximate the colors.  This may be desired, but if this is
+    an inconvenience the function named by g:CSApprox_approximator_function
+    can still be called manually.  For example:
+>
+      let g:CSApprox_hook_post = 'exe "hi Comment ctermbg="'
+                      \ . '. g:CSApprox_approximator_function(0xA0,0x50,0x35)'
+<
+    The _{scheme}_ versions are exactly like their counterparts, except that
+    they will only be executed if the value of g:colors_name matches the
+    scheme name embedded in the variable name.  They will be executed after
+    the corresponding hook without _{scheme}_, which provides a way to
+    override a less specific hook with a more specific one.  For example, to
+    clear the Normal and NonText groups, but only for the colorscheme
+    "desert", one could do the following:
+>
+    let g:CSApprox_hook_desert_post = ['hi Normal ctermbg=NONE ctermfg=NONE',
+                                    \ 'hi NonText ctermbg=NONE ctermfg=NONE' ]
+<
+    One final example: If you want CSApprox to be active for nearly all
+    colorschemes, but want one or two particular schemes to be ignored, you
+    can take advantage of the CSApprox logic that skips over any color scheme
+    that is already high color by setting a color to a number above 255.  Note
+    that most colors greater than 15 will work, but some will not - 256 should
+    always work.  For instance, you can prevent CSApprox from modifying the
+    colors of the zellner colorscheme like this:
+>
+    let g:CSApprox_hook_zellner_pre = 'hi _FakeGroup ctermbg=256'
+<
+    NOTE: Any characters that would stop the string stored in g:colors_name
+          from being a valid variable name will be removed before the
+          _{scheme}_ hook is searched.  Basically, this means that first all
+          characters that are neither alphanumeric nor underscore will be
+          removed, then any leading digits will be removed.  So, for a
+          colorscheme named "123 foo_bar-baz456.vim", the hook searched for
+          will be, eg, g:CSApprox_hook_foo_barbaz456_post
+
+g:CSApprox_use_showrgb                                *g:CSApprox_use_showrgb*
+    By default, CSApprox will use a built in mapping of color names to values.
+    This optimization greatly helps speed, but means that colors addressed by
+    name might not match up perfectly between gvim (which uses the system's
+    real rgb database) and CSApprox (which uses the builtin database).  To
+    force CSApprox to try the systemwide database first, and only fall back on
+    the builtin database if it isn't available, set this variable non-zero.
+
+g:CSApprox_approximator_function            *g:CSApprox_approximator_function*
+    If the default approximation function doesn't work well enough, the user
+    (or another author wishing to extend this plugin) can write another
+    approximation function.  This function should take three numbers,
+    representing r, g, and b in decimal, and return the index on the color
+    cube that best matches those colors.  Assigning a |Funcref| to this
+    variable will override the default approximator with the one the Funcref
+    references.  This option will take effect at the time a snapshotted scheme
+    is created, rather than when it's used.
+
+g:CSApprox_redirfallback                            *g:CSApprox_redirfallback*
+    Until Vim 7.2.052, there was a bug in the Vim function synIDattr() that
+    made it impossible to determine syntax information about the |guisp|
+    attribute.  CSApprox includes a workaround for this problem, as well as a
+    test that ought to disable this workaround if synIDattr() works properly.
+    If this test should happen to give improper results somehow, the user can
+    force the behavior with this variable.  When set to 1, the workaround will
+    always be used, and when set to 0, synIDattr() is blindly used.  Needless
+    to say, if this automatic detection should ever fail, the author would
+    like to be notified!  This option will take effect at the time a
+    snapshotted scheme is created, rather than when it's used.
+
+==============================================================================
+4. Rationale/Design                                          *csapprox-design*
+
+There is a wealth of colorschemes available for Vim.  Unfortunately, since
+traditional terminal emulators have only supported 2, 8 or 16 colors,
+colorscheme authors have tended to avoid writing colorschemes for terminal
+Vim, sticking instead to GVim.  Even now that nearly every popular terminal
+supports either 88 or 256 colors, few colorschemes are written to support
+them.  This may be because the terminal color codes are just numbers from 0 to
+87 or 255 with no semantic meaning, or because the same number doesn't yield
+the same color in all terminals, or simply because the colorscheme author
+doesn't use the terminal and doesn't want to take the time to support
+terminals.
+
+Whatever the reason, this leaves users of many modern terminal emulators in
+the awkward position of having a terminal emulator that supports many colors,
+but having very few colorschemes that were written to utilize those colors.
+
+This is where CSApprox comes in.  It attempts to fill this void allowing GVim
+colorschemes to be used in terminal Vim.  CSApprox has two distinct modes of
+operation.  In the first mode, it attempts to make GVim colorschemes
+transparently backwards compatible with terminal Vim in a high color terminal.
+Basically, whenever a colorscheme is run it should set some colors for the
+GUI, and this script will then run and attempt to figure out the closest color
+available in the terminal's color palette to the color the scheme author asked
+for.  Unfortunately, this does not work well all the time, and it has some
+limitations (see |csapprox-limitations|).  Most of the time, however, this
+gives a very close approximation to the GVim colors without requiring any
+changes to the colorscheme, or any user interaction.  It only requires that
+the plugin be installed on the machine where Vim is being run, and that the
+user's environment meets the needs specified at |csapprox-requirements|.  In
+the event that this doesn't work, a second option - using :CSApproxSnapshot
+to create a new, 88-/256-color capable colorscheme - is available.
+
+Ideally, the aim is for CSApprox to be completely transparent to the user.
+This is why the approach I take is entirely different from the GuiColorScheme
+script, which will break on any but the simplest colorschemes.  Unfortunately,
+given the difficulty of determining exactly which terminal emulator the user
+is running, and what features it supports, and which color palette it's using,
+perfect transparency is difficult.  So, to this end, I've attempted to default
+to settings that make it unlikely that this script ever makes things worse
+(this is why I chose not to override t_Co to 256 myself), and I've attempted
+to make it easy to override my choice of defaults when necessary (through
+g:CSApprox_approximator_function, g:CSApprox_konsole, g:CSApprox_eterm,
+g:CSApprox_attr_map, etc).
+
+In the event that the transparent solution is undesirable, or that the user's
+environment can't be configured to allow it (no GVim and no Vim with +gui, for
+instance), |:CSApproxSnapshot| should provide a workable alternative - less
+cool, and less flexible, but it will work in more environments, and the
+snapshotted colorscheme will even work in Vim 6.
+
+If any of my design choices seem to be causing extra work with no real
+advantages, though, I'd like to hear about it.  Feel free to email me with any
+improvements or complaints.
+
+==============================================================================
+5. Known Bugs and Limitations                           *csapprox-limitations*
+
+GUI support is required for transparently adapting schemes.
+
+  There is nothing I can do about this given my chosen design.  CSApprox works
+  by being notified every time a colorscheme sets some GUI colors, then
+  approximating those colors to similar terminal colors.  Unfortunately, when
+  Vim is not built with GUI support, it doesn't bother to store the GUI
+  colors, so querying for them fails.  This leaves me completely unable to
+  tell what the colorscheme was trying to do.  See |csapprox-+gui| for some
+  potential workarounds if your distribution doesn't provide a Vim with +gui.
+
+User intervention is sometimes required for information about the terminal.
+
+  This is really an insurmountable problem.  Unfortunately, most terminal
+  emulators default to setting $TERM to 'xterm', even when they're not really
+  compatible with an xterm.  $TERM is really the only reliable way to
+  find anything at all out about the terminal you're running in, so there's no
+  way to know if the terminal supports 88 or 256 colors without either the
+  terminal telling me (using $TERM) or the user telling me (using 't_Co').
+  Similarly, unless $TERM is set to something that implies a certain color
+  palette ought to be used, there's no way for me to know, so I'm forced to
+  default to the most common, xterm's palette, and allow the user to override
+  my choice with |g:CSApprox_konsole| or |g:CSApprox_eterm|.  An example of
+  configuring Vim to work around a terminal where $TERM is set to something
+  generic without configuring the terminal properly is shown at
+  |csapprox-terminal-example|.
+
+Some colorschemes could fail to be converted if they try to be too smart.
+
+  A colorscheme could decide to only set colors for the mode Vim is running
+  in.  If a scheme only sets GUI colors when the GUI is running, instead of
+  using the usual approach of setting all colors and letting Vim choose which
+  to use, my approach falls apart.  My method for figuring out what the scheme
+  author wants the scheme to look like absolutely depends upon him setting the
+  GUI colors in all modes.  Fortunately, the few colorschemes that do this
+  seem to be, by and large, intended for 256 color terminals already, meaning
+  that skipping them is the proper behavior.  Note that this will only affect
+  transparently adapted schemes and snapshots made from terminal Vim;
+  snapshots made from GVim are immune to this problem.
+
+Transparently adapting schemes is slow.
+
+  For me, it takes Vim's startup time from 0.15 seconds to 0.35 seconds.  This
+  is probably still acceptable, but it is definitely worth trying to cut down
+  on this time in future versions.  Snapshotted schemes are faster to use,
+  since all of the hard evaluations are made when they're made instead of when
+  they're used.
+
+  NOTE: As of CSApprox 3.50, the overhead is down to about 0.10 seconds on my
+        test machine.
+
+==============================================================================
+6. Appendix - Terminals and Palettes                  *csapprox-terminal-list*
+
+What follows is a list of terminals known to have and known not to have high
+color support.  This list is certainly incomplete; feel free to contact me
+with more to add to either list.
+
+                                                     *csapprox-terminals-good*
+------------------------------- Good Terminals -------------------------------
+
+The most recent versions of each of these terminals can be compiled with
+either 88 or 256 color support.
+
+                                                              *csapprox-xterm*
+xterm:
+    256 color palette
+    Colors composed of: [ 0x00, 0x5F, 0x87, 0xAF, 0xD7, 0xFF ]
+    Greys composed of:  [ 0x08, 0x12, 0x1C, 0x26, 0x30, 0x3A, 0x44, 0x4E,
+                          0x58, 0x62, 0x6C, 0x76, 0x80, 0x8A, 0x94, 0x9E,
+                          0xA8, 0xB2, 0xBC, 0xC6, 0xD0, 0xDA, 0xE4, 0xEE ]
+
+                                                              *csapprox-urxvt*
+rxvt-unicode (urxvt):
+    88 colors by default (but a patch is available to use xterm's palette)
+    Colors composed of: [ 0x00, 0x8B, 0xCD, 0xFF ]
+    Greys composed of:  [ 0x2E, 0x5C, 0x73, 0x8B, 0xA2, 0xB9, 0xD0, 0xE7 ]
+
+                                               *csapprox-pterm* *csapprox-putty*
+PuTTY (pterm; putty.exe):
+    256 colors; same palette as xterm
+
+                                                              *csapprox-mrxvt*
+Mrxvt (mrxvt):
+    256 colors; same palette as xterm
+
+                                                     *csapprox-gnome-terminal*
+GNOME Terminal (gnome-terminal):
+    256 colors; same palette as xterm
+
+                                                            *csapprox-roxterm*
+ROXTerm (roxterm):
+    256 colors; same palette as xterm
+
+                                                     *csapprox-xfce4-terminal*
+Terminal (xfce4-terminal):
+    256 colors; same palette as xterm
+
+                                                          *csapprox-iterm.app*
+iTerm (iTerm.app):
+    256 colors; same palette as xterm
+                                                            *csapprox-konsole*
+Konsole (konsole):
+    256 color palette
+    Colors composed of: [ 0x00, 0x33, 0x66, 0x99, 0xCC, 0xFF ]
+    Same greyscales as xterm
+    You should set the g:CSApprox_konsole variable unless $TERM begins with
+    'konsole', case insensitive
+
+                                                              *csapprox-eterm*
+eterm (Eterm):
+    256 color palette
+    Colors composed of: [ 0x00, 0x2A, 0x55, 0x7F, 0xAA, 0xD4 ]
+    Same greyscales as xterm
+    You should set the g:CSApprox_eterm variable unless $TERM begins with
+    'eterm', case insensitive
+
+                                                             *csapprox-screen*
+GNU Screen (screen):
+    256 color support.  Internally, uses the xterm palette, but this is only
+    relevant when running screen inside a terminal with fewer than 256 colors,
+    in which case screen will attempt to map between its own 256 color cube
+    and the colors supported by the real terminal to the best of its ability,
+    in much the same way as CSApprox maps between GUI and terminal colors.
+
+                                                      *csapprox-terminals-bad*
+-------------------------------- Bad Terminals -------------------------------
+This is a list of terminals known _not_ to have high color support.  If any of
+these terminals have high color support added at some point in the future,
+please tell me and I'll update this information.
+
+                                                       *csapprox-terminal.app*
+Terminal.app (as of OS X 10.5.2)
+
+                                                              *csapprox-aterm*
+aterm (as of version 1.00.01)
+
+                                                             *csapprox-xiterm*
+xiterm (as of version 0.5)
+
+                                                              *csapprox-wterm*
+wterm (as of version 6.2.9)
+
+                                                             *csapprox-mlterm*
+mlterm (as of version 2.9.4)
+
+                                                              *csapprox-kterm*
+kterm (as of version 6.2.0)
+
+==============================================================================
+7. Changelog                                              *csapprox-changelog*
+
+ 3.50   01 Apr 2009   Fix a major regression that prevented the Eterm and
+                      Konsole colors from being correctly snapshotted
+
+                      Fix a related bug causing incorrect terminal colors
+                      after calling :CSApproxSnapshot
+
+                      Fix a bug causing black to be used instead of dark grey
+
+                      Have snapshots calculate g:colors_name programmatically
+
+                      Introduce many tweaks for better speed
+
+                      Clarify some things at :help csapprox-terminal-example
+
+                      Default to using our own list of rgb.txt colors rather
+                      than searching, for performance.  Add a new variable,
+                      g:CSApprox_use_showrgb, which forces us to try finding
+                      the colors using the "showrgb" program instead, and fall
+                      back on our own list if it isn't available
+
+                      Remove g:CSApprox_extra_rgb_txt_dirs - not needed in
+                      light of the above change
+
+ 3.05   31 Jan 2009   Fix a harmless "Undefined variable" error in
+                      :CSApproxSnapshot
+
+                      Fix a behavioral bug when dumping out colors defined
+                      external to the scheme.
+
+ 3.00   21 Jan 2009   Update the docs for better info on :CSApproxSnapshot
+
+                      Allow snapshotted schemes to work on Vim 6, and work
+                      properly in Konsole and Eterm (thanks David Majnemer!)
+
+                      Fix a bug causing a syntax error when using GVim while
+                      CSApprox was loaded.  (thanks again, David Majnemer!)
+
+ 2.00   14 Dec 2008   Add a hooks system, allowing users to specify a command
+                      to run, either before or after the approximation
+                      algorithm is run, for all schemes or one specific one.
+
+                      Also rewrite :CSApproxSnapshot to be more maintainable
+                      and less of a hack, and fix several bugs that it
+                      contained.
+
+ 1.50   19 Nov 2008   Add CSApproxSnapshot command, as an alternative solution
+                      when the user has gvim or a vim with gui support, but
+                      sometimes needs to use a vim without gui support.
+
+ 1.10   28 Oct 2008   Enable running on systems with no rgb.txt (Penn Su)
+                      Begin distributing a copy of rgb.txt with CSApprox
+
+ 1.00   04 Oct 2008   First public release
+
+ 0.90   14 Sep 2008   Initial beta release
+
+==============================================================================
+8. Contact Info                                              *csapprox-author*
+
+Your author, a Vim nerd with some free time, was sick of seeing terminals
+always get the short end of the stick.  He'd like to be notified of any
+problems you find - after all, he took the time to write all this lovely
+documentation, and this plugin, which took more time than you could possibly
+imagine to get working transparently for every colorscheme he could get his
+hands on.  You can contact him with any problems or praises at mjw@drexel.edu
+
+==============================================================================
+vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: