diff --git a/doc/CSApprox.txt b/doc/CSApprox.txt index aade8cb..e2aac5c 100644 --- a/doc/CSApprox.txt +++ b/doc/CSApprox.txt @@ -8,7 +8,7 @@ \___//___//_/ |_|/ .__// .__//_/ \___//_\_\ ~ /_/ /_/ ~ For Vim version 7.0 or newer - Last changed 14 Dec 2008 + Last changed 21 Jan 2009 By Matt Wozniski mjw@drexel.edu @@ -49,15 +49,47 @@ 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 +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. +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* @@ -66,34 +98,41 @@ 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: > +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" or "vim-gnome" on Debian/Ubuntu. +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 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 +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* @@ -108,16 +147,17 @@ 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 +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 provide a different default, -however - see |csapprox-configuration|. - +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 put something like -this into your |vimrc|: > - if &term == 'xterm' && hostname() == 'my-machine' +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 @@ -131,7 +171,8 @@ 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. + 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 @@ -140,15 +181,17 @@ g:CSApprox_verbose_level *g:CSApprox_verbose_level* 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. + higher verbosity levels. Has no effect on snapshotted schemes. 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. + 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, CSApprox will use the Konsole palette when 'term' is "xterm" or - "screen*". Otherwise, the xterm palette would be used. + 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 @@ -164,40 +207,14 @@ g:CSApprox_attr_map *g:CSApprox_attr_map* 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_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 @@ -205,12 +222,14 @@ 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: + 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' < @@ -273,6 +292,47 @@ g:CSApprox_hook_{scheme}_post *csapprox-hooks* 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* @@ -286,14 +346,20 @@ 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. +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. +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 @@ -301,9 +367,7 @@ GUI support is required. 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| + potential workarounds if your distribution doesn't provide a Vim with +gui. User intervention is sometimes required for information about the terminal. @@ -312,7 +376,7 @@ User intervention is sometimes required for information about the terminal. 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). + 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 @@ -321,7 +385,7 @@ User intervention is sometimes required for information about the terminal. generic without configuring the terminal properly is shown at |csapprox-terminal-example|. -Some colorschemes could fail if they try to be too smart. +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 @@ -330,17 +394,17 @@ Some colorschemes could fail if they try to be too smart. 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. + 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. -It's slow. +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. - - 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. + 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* @@ -418,7 +482,9 @@ GNU Screen (screen): *csapprox-terminals-bad* -------------------------------- Bad Terminals ------------------------------- -This is a list of terminals known *_not_* to have high color support: +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) @@ -441,6 +507,14 @@ 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. diff --git a/plugin/CSApprox.vim b/plugin/CSApprox.vim index a9be8ec..409a73e 100644 --- a/plugin/CSApprox.vim +++ b/plugin/CSApprox.vim @@ -1,7 +1,7 @@ -" CSApprox: Make gvim-only colorschemes work transparently in terminal vim +" CSApprox: Make gvim-only colorschemes work terminal vim " Maintainer: Matthew Wozniski (mjw@drexel.edu) -" Date: Sun, 14 Dec 2008 06:12:55 -0500 -" Version: 2.00 +" Date: Wed, 21 Jan 2009 19:21:31 -0500 +" Version: 3.00 " History: :help csapprox-changelog " Whenever you change colorschemes using the :colorscheme command, this script @@ -83,12 +83,12 @@ function! s:ApproximatePerComponent(r,g,b) let colors = s:urxvt_colors let type = 'urxvt' elseif ((&term ==# 'xterm' || &term =~# '^screen' || &term==# 'builtin_gui') - \ && exists('g:CSApprox_konsole')) + \ && exists('g:CSApprox_konsole') && g:CSApprox_konsole) \ || &term =~? '^konsole' let colors = s:konsole_colors let type = 'konsole' elseif ((&term ==# 'xterm' || &term =~# '^screen' || &term==# 'builtin_gui') - \ && exists('g:CSApprox_eterm')) + \ && exists('g:CSApprox_eterm') && g:CSApprox_eterm) \ || &term =~? '^eterm' let colors = s:eterm_colors let type = 'eterm'