vim/csapprox
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
4091aca090
csapprox/doc/CSApprox.txt
Matt Wozniski 5b57902f3c Finalize 3.0 release. 
Bump version numbers and timestamps.

Massive documentation update to make CSApproxSnapshot well-documented,
rather than just a side-note.

Add a slight tweak to the plugin to match the updated docs: it's no
longer enough for g:CSApprox_eterm or g:CSApprox_konsole to simply
exist, they must also evaluate as True.
2009-01-21 19:39:41 -05:00

549 lines
30 KiB
Plaintext
Raw Blame History

*CSApprox.txt* Bringing GVim colorschemes to the terminal!
*csapprox* *csapprox.vim*
_____ ____ ___ ~
/ ___// __// _ | ___ ___ ____ ___ __ __ ~
/ /__ _\ \ / __ | / _ \ / _ \ / __// _ \ \ \ / ~
\___//___//_/ |_|/ .__// .__//_/ \___//_\_\ ~
/_/ /_/ ~
For Vim version 7.0 or newer
Last changed 21 Jan 2009
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 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|.
*:CSApproxSnapshot*
The other mode of operation allows creating a colorscheme suitable for use in
high color terminals from the colorscheme currently in use. To use this mode,
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 has
several advantages over the transparent mode of operation - for example, it
doesn't cause any extra slowdown in Vim's starting and doesn't require a "vim"
built with +gui on the machine where the scheme is used - but it requires
action on the part of the user and can't be done transparently, making it much
less convenient. The 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
==============================================================================
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_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. When not running in GVim, Vim can't
tell it, so 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, but it should never happen since CSApprox includes an
rgb.txt in its distribution. The only reason for preferring other rgb.txt
files on the system to the one distributed with CSApprox is that they
might more accurately reflect the colors used in GVim; different rgb.txt
files might have different values for some colors. 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 ]
<
Snapshotted schemes will never contain colors by name, so this option is
unneeded and won't be used.
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*
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, |:CSApproxSnapshot|
should provide a workable alternative - less cool, and less flexible, but it
will work in more environments, and the snapshot 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.
==============================================================================
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.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:
Reference in New Issue View Git Blame Copy Permalink