From ca9745614e727e4bb4eda412a23f4eee04274bd6 Mon Sep 17 00:00:00 2001 From: Matt Wozniski Date: Thu, 2 Apr 2009 03:46:43 -0400 Subject: [PATCH] Clean up comments, docs, and timestamps for 3.50 --- doc/CSApprox.txt | 132 ++++++++++++++++++++++++++++++-------------- plugin/CSApprox.vim | 77 +++++++++++++++++++------- 2 files changed, 146 insertions(+), 63 deletions(-) diff --git a/doc/CSApprox.txt b/doc/CSApprox.txt index 65d79de..d91bb62 100644 --- a/doc/CSApprox.txt +++ b/doc/CSApprox.txt @@ -8,7 +8,7 @@ \___//___//_/ |_|/ .__// .__//_/ \___//_\_\ ~ /_/ /_/ ~ For Vim version 7.0 or newer - Last changed 31 Jan 2009 + Last changed 01 Apr 2009 By Matt Wozniski mjw@drexel.edu @@ -17,7 +17,7 @@ *csapprox-toc* -1. Description |csapprox-intro| +1. Introduction |csapprox-intro| 2. Requirements |csapprox-requirements| 3. Configuration |csapprox-configure| 4. Rationale/Design |csapprox-design| @@ -32,48 +32,37 @@ variable in your |vimrc| file: > :let g:CSApprox_loaded = 1 ============================================================================== -1. Description *csapprox-intro* +1. Introduction *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. +It's hard to find colorschemes for terminal Vim. Most colorschemes are +written to only support GVim, and don't work at all in terminal Vim. -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 plugin makes GVim-only colorschemes Just Work in terminal Vim, as long +as the terminal supports 88 or 256 colors - and most do these days. This +usually requires no user interaction (but see below for what to do if things +don't Just Work). After getting this plugin happily installed, any time you +use :colorscheme it will do its magic and make the colorscheme Just Work. -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|. +Whenever you change colorschemes using the :colorscheme command this script +will be executed. It will take the colors that the scheme specified for use +in the GUI and use an approximation algorithm to try to gracefully degrade +them to the closest color available in your terminal. If you are running in +a GUI or if your terminal doesn't support 88 or 256 colors, no changes are +made. Also, no changes will be made if the colorscheme seems to have been +high color already. +If for some reason this transparent method isn't suitable to you (for instance +if your environment can't be configured to meet the |csapprox-requirements|, +or you need to work in Vim 6), another option is also available: using the +|:CSApproxSnapshot| command to create a new GUI/88-/256-color terminal +colorscheme. To use this command, a user would generally start GVim, choose a +colorscheme that sets up the desired colors, and then use |:CSApproxSnapshot| +to create a new colorscheme based on those colors that works in high color +terminals. This method is more flexible than the transparent mode and works +in more places, but also requires more user intervention, and makes it harder +to deal with colorschemes being updated and such. *:CSApproxSnapshot* -The 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: > +The full syntax for the command is: > :CSApproxSnapshot[!] /path/to/new/colorscheme < For example: > :CSApproxSnapshot ~/.vim/colors/foobar.vim @@ -333,6 +322,37 @@ g:CSApprox_redirfallback *g:CSApprox_redirfallback* ============================================================================== 4. Rationale/Design *csapprox-design* +There is a wealth of colorschemes available for Vim. Unfortunately, since +traditional terminal emulators have only supported 2, 8 or 16 colors, +colorscheme authors have tended to avoid writing colorschemes for terminal +Vim, sticking instead to GVim. Even now that nearly every popular terminal +supports either 88 or 256 colors, few colorschemes are written to support +them. This may be because the terminal color codes are just numbers from 0 to +87 or 255 with no semantic meaning, or because the same number doesn't yield +the same color in all terminals, or simply because the colorscheme author +doesn't use the terminal and doesn't want to take the time to support +terminals. + +Whatever the reason, this leaves users of many modern terminal emulators in +the awkward position of having a terminal emulator that supports many colors, +but having very few colorschemes that were written to utilize those colors. + +This is where CSApprox comes in. It attempts to fill this void allowing GVim +colorschemes to be used in terminal Vim. CSApprox has two distinct modes of +operation. In the first mode, it attempts to make GVim colorschemes +transparently backwards compatible with terminal Vim in a high color terminal. +Basically, whenever a colorscheme is run it should set some colors for the +GUI, and this script will then run and attempt to figure out the closest color +available in the terminal's color palette to the color the scheme author asked +for. Unfortunately, this does not work well all the time, and it has some +limitations (see |csapprox-limitations|). Most of the time, however, this +gives a very close approximation to the GVim colors without requiring any +changes to the colorscheme, or any user interaction. It only requires that +the plugin be installed on the machine where Vim is being run, and that the +user's environment meets the needs specified at |csapprox-requirements|. In +the event that this doesn't work, a second option - using :CSApproxSnapshot +to create a new, 88-/256-color capable colorscheme - is available. + Ideally, the aim is for CSApprox to be completely transparent to the user. This is why the approach I take is entirely different from the GuiColorScheme script, which will break on any but the simplest colorschemes. Unfortunately, @@ -345,9 +365,11 @@ 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. +In the event that the transparent solution is undesirable, or that the user's +environment can't be configured to allow it (no GVim and no Vim with +gui, for +instance), |:CSApproxSnapshot| should provide a workable alternative - less +cool, and less flexible, but it will work in more environments, and the +snapshotted colorscheme will even work in Vim 6. If any of my design choices seem to be causing extra work with no real advantages, though, I'd like to hear about it. Feel free to email me with any @@ -403,6 +425,9 @@ Transparently adapting schemes is slow. since all of the hard evaluations are made when they're made instead of when they're used. + NOTE: As of CSApprox 3.50, the overhead is down to about 0.10 seconds on my + test machine. + ============================================================================== 6. Appendix - Terminals and Palettes *csapprox-terminal-list* @@ -504,6 +529,29 @@ kterm (as of version 6.2.0) ============================================================================== 7. Changelog *csapprox-changelog* + 3.50 01 Apr 2009 Fix a major regression that prevented the Eterm and + Konsole colors from being correctly snapshotted + + Fix a related bug causing incorrect terminal colors + after calling :CSApproxSnapshot + + Fix a bug causing black to be used instead of dark grey + + Have snapshots calculate g:colors_name programmatically + + Introduce many tweaks for better speed + + Clarify some things at :help csapprox-terminal-example + + Default to using our own list of rgb.txt colors rather + than searching, for performance. Add a new variable, + g:CSApprox_use_showrgb, which forces us to try finding + the colors using the "showrgb" program instead, and fall + back on our own list if it isn't available + + Remove g:CSApprox_extra_rgb_txt_dirs - not needed in + light of the above change + 3.05 31 Jan 2009 Fix a harmless "Undefined variable" error in :CSApproxSnapshot diff --git a/plugin/CSApprox.vim b/plugin/CSApprox.vim index fb5f231..0cb727f 100644 --- a/plugin/CSApprox.vim +++ b/plugin/CSApprox.vim @@ -1,17 +1,52 @@ -" CSApprox: Make gvim-only colorschemes work terminal vim +" CSApprox: Make gvim-only colorschemes Just Work terminal vim " Maintainer: Matthew Wozniski (mjw@drexel.edu) -" Date: Sat, 31 Jan 2009 04:14:27 -0500 -" Version: 3.05 +" Date: Wed, 01 Apr 2009 22:10:19 -0400 +" Version: 3.50 " History: :help csapprox-changelog - -" Whenever you change colorschemes using the :colorscheme command, this script -" will be executed. If you're running in 256 color terminal or an 88 color -" terminal, as reported by the command ":set t_Co?", it will take the colors -" that the scheme specified for use in the gui and use an approximation -" algorithm to try to gracefully degrade them to the closest color available. -" If you are running in a gui or if t_Co is reported as less than 88 colors, -" no changes are made. Also, no changes will be made if the colorscheme seems -" to have been high color already. +" +" Long Description: +" It's hard to find colorschemes for terminal Vim. Most colorschemes are +" written to only support GVim, and don't work at all in terminal Vim. +" +" This plugin makes GVim-only colorschemes Just Work in terminal Vim, as long +" as the terminal supports 88 or 256 colors - and most do these days. This +" usually requires no user interaction (but see below for what to do if things +" don't Just Work). After getting this plugin happily installed, any time you +" use :colorscheme it will do its magic and make the colorscheme Just Work. +" +" Whenever you change colorschemes using the :colorscheme command this script +" will be executed. It will take the colors that the scheme specified for use +" in the GUI and use an approximation algorithm to try to gracefully degrade +" them to the closest color available in your terminal. If you are running in +" a GUI or if your terminal doesn't support 88 or 256 colors, no changes are +" made. Also, no changes will be made if the colorscheme seems to have been +" high color already. +" +" License: +" Copyright (c) 2009, Matthew J. Wozniski +" All rights reserved. +" +" Redistribution and use in source and binary forms, with or without +" modification, are permitted provided that the following conditions are met: +" * Redistributions of source code must retain the above copyright notice, +" this list of conditions and the following disclaimer. +" * Redistributions in binary form must reproduce the above copyright +" notice, this list of conditions and the following disclaimer in the +" documentation and/or other materials provided with the distribution. +" * The names of the contributors may not be used to endorse or promote +" products derived from this software without specific prior written +" permission. +" +" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS'' AND ANY EXPRESS +" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN +" NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY DIRECT, INDIRECT, +" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, +" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. " {>1} Basic plugin setup @@ -66,8 +101,8 @@ endfunc " {>2} Approximator " Takes 3 decimal values for r, g, and b, and returns the closest cube number. " Uses &term to determine which cube should be used, though if &term is set to -" "xterm" the variables g:CSApprox_eterm and g:CSApprox_konsole can be used to -" change the default palette. +" "xterm" or begins with "screen", the variables g:CSApprox_eterm and +" g:CSApprox_konsole can be used to select a different palette. " " This approximator considers closeness based upon the individiual components. " For each of r, g, and b, it finds the closest cube component available on @@ -286,8 +321,8 @@ let s:rgb_defaults = { "lightred" : "#FFBBBB", \ "gray90" : "#E5E5E5", \ "grey90" : "#E5E5E5" } -" Colors that vim will use by name in one of the default schemes, either for -" bg=light or for bg=dark. This lets us avoid loading the entire rgb.txt +" {>2} Colors that vim will use by name in one of the default schemes, either +" for bg=light or for bg=dark. This lets us avoid loading the entire rgb.txt " database when the scheme itself doesn't ask for colors by name. let s:rgb_presets = { "black" : "#000000", \ "blue" : "#0000ff", @@ -312,11 +347,11 @@ let s:rgb_presets = { "black" : "#000000", \ "yellow" : "#ffff00" } " {>2} Find available color names -" Find the valid named colors. If it is available, use the "showrgb" program, -" otherwise use our own copy of rgb.txt (needed on OS X and systems without -" xorg). Store the color names and color values to the dictionary s:rgb - the -" keys are color names (in lowercase), the values are strings representing -" color values (as '#rrggbb'). +" Find the valid named colors. By default, use our own rgb list, but try to +" retrieve the system's list if g:CSApprox_use_showrgb is set to true. Store +" the color names and color values to the dictionary s:rgb - the keys are +" color names (in lowercase), the values are strings representing color values +" (as '#rrggbb'). function! s:UpdateRgbHash() try if !exists("g:CSApprox_use_showrgb") || !g:CSApprox_use_showrgb