vim/csapprox
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Clean up comments, docs, and timestamps for 3.50

Browse Source
This commit is contained in:
Matt Wozniski 2009-04-02 03:46:43 -04:00
parent 6e73754fc7
commit ca9745614e
2 changed files with 146 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
doc/CSApprox.txt
View File

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

77
plugin/CSApprox.vim
View File

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