Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: 7f71abd0ab
Fetching contributors…

Cannot retrieve contributors at this time

file 464 lines (387 sloc) 25.107 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464
*CSApprox.txt* Bringing GVim colorschemes to the terminal!

                                                     *csapprox* *csapprox.vim*

                  _____ ____ ___ ~
                 / ___// __// _ | ___ ___ ____ ___ __ __ ~
                / /__ _\ \ / __ | / _ \ / _ \ / __// _ \ \ \ / ~
                \___//___//_/ |_|/ .__// .__//_/ \___//_\_\ ~
                                /_/ /_/ ~
                                                  For Vim version 7.0 or newer
                                                      Last changed 14 Dec 2008

                               By Matt Wozniski
                                mjw@drexel.edu

                              Reference Manual~

                                                                *csapprox-toc*

1. Description |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. Description *csapprox-intro*

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 by making GVim
colorschemes transparently backwards compatible with terminal Vim in a high
color terminal. Basically, whenever a colorscheme sets some colors for the
GUI, this script runs and tries to figure out the closest color available in
the terminal's color palette to the color the colorscheme author wanted.
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.

==============================================================================
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*

The "vim" binary must be built with GUI support (see |csapprox-limitations|
for an explanation). 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 by doing: >
    :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" 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 that does not work and no package with GUI support is available, you will
need to compile Vim yourself and ensure that GUI support is included. If this
is inconvenient for you, make sure that the Vim maintainer for your
distribution knows it.
                                                           *:CSApproxSnapshot*
NOTE: As of CSApprox version 1.5, there is another alternative. CSApprox now
      provides a command, :CSApproxSnapshot, that can be used from inside gvim
      or a terminal vim that is built with +gui. It allows you to write out a
      colorscheme file representing the current colors that will work in gvim,
      88 color vim, or 256 color vim. The syntax is: >
          :CSApproxSnapshot[!] /path/to/new/colorscheme
< For example: >
          :CSApproxSnapshot ~/.vim/colors/foobar.vim

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" 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 provide a different default,
however - see |csapprox-configuration|.

                                                   *csapprox-terminal-example*
To turn on high color support without fixing $TERM, you can put something like
this into your |vimrc|: >
    if &term == 'xterm' && $HOSTNAME == 'my-machine'
        " On my machine, I use Konsole with 256 color support
        set t_Co=256
        let g:CSApprox_konsole = 1
    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.

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.

g:CSApprox_eterm *g:CSApprox_eterm*
    If set, CSApprox will use the Eterm palette when 'term' is "xterm" or
    "screen*". Otherwise, the xterm palette would be used.

g:CSApprox_konsole *g:CSApprox_konsole*
    If set, CSApprox will use the Konsole palette when 'term' is "xterm" or
    "screen*". Otherwise, the xterm palette would be used.

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: 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_extra_rgb_txt_dirs *g:CSApprox_extra_rgb_txt_dirs*
    When the colorscheme author uses a color by name, CSApprox needs to figure
    out what #rrggbb value it stands for. It does this by parsing rgb.txt,
    but first needs to locate it. It has a default search path included, and
    will also search in any directory in the user's 'runtimepath', but first
    any directory included in this variable will be searched. Failing to find
    any valid rgb.txt is an unrecoverable error. Default search path: >
    [ /usr/local/share/X11, /usr/share/X11, /etc/X11, /usr/local/lib/X11,
      /usr/lib/X11, /usr/local/X11R6/lib/X11, /usr/X11R6/lib/X11 ]

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.

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!

                          *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. Each of
    these variables may be set to either a String containing a command to be
    :executed, 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',
                                \ 'hi NonText ctermbg=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',
                                       \ 'hi NonText ctermbg=NONE' ]
<
    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

==============================================================================
4. Rationale/Design *csapprox-design*

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). If any of my 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 upon my design you might want to suggest.

==============================================================================
5. Known Bugs and Limitations *csapprox-limitations*

GUI support is required.

  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 work arounds if your distribution doesn't provide a Vim with +gui.

  NOTE: As of CSApprox 1.5, a reasonable workaround is |:CSApproxSnapshot|

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 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.

It's 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.

  NOTE: As of CSApprox 1.5, |:CSApproxSnapshot| can be used to eliminate the
        overhead of CSApprox, since the approximations only need to be done
        when the colorscheme is created, rather than every time it's used.

==============================================================================
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:

                                                       *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*

 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:
Something went wrong with that request. Please try again.