475 lines
25 KiB
Plaintext
475 lines
25 KiB
Plaintext
*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 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
|
|
|
|
==============================================================================
|
|
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:
|