Skip to content
Newer
Older
100644 691 lines (571 sloc) 36.6 KB
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
1 *CSApprox.txt* Bringing GVim colorschemes to the terminal!
2
3 *csapprox* *csapprox.vim*
4
5 _____ ____ ___ ~
6 / ___// __// _ | ___ ___ ____ ___ __ __ ~
7 / /__ _\ \ / __ | / _ \ / _ \ / __// _ \ \ \ / ~
8 \___//___//_/ |_|/ .__// .__//_/ \___//_\_\ ~
9 /_/ /_/ ~
10 For Vim version 7.0 or newer
a295809 Version 4.00
Matt Wozniski authored
11 Last changed 14 Sep 2012
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
12
13 By Matt Wozniski
a295809 Version 4.00
Matt Wozniski authored
14 godlygeek@gmail.com
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
15
16 Reference Manual~
17
18 *csapprox-toc*
19
ce2b1fd Version 3.50
Matt Wozniski authored
20 1. Introduction |csapprox-intro|
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
21 2. Requirements |csapprox-requirements|
22 3. Configuration |csapprox-configure|
23 4. Rationale/Design |csapprox-design|
24 5. Known Bugs and Limitations |csapprox-limitations|
25 6. Appendix - Terminals and Palettes |csapprox-terminal-list|
26 7. Changelog |csapprox-changelog|
27 8. Contact Info |csapprox-author|
28
29 The functionality mentioned here is a plugin, see |add-plugin|.
30 You can avoid loading this plugin by setting the "CSApprox_loaded" global
31 variable in your |vimrc| file: >
32 :let g:CSApprox_loaded = 1
33
34 ==============================================================================
ce2b1fd Version 3.50
Matt Wozniski authored
35 1. Introduction *csapprox-intro*
36
37 It's hard to find colorschemes for terminal Vim. Most colorschemes are
38 written to only support GVim, and don't work at all in terminal Vim.
39
40 This plugin makes GVim-only colorschemes Just Work in terminal Vim, as long
41 as the terminal supports 88 or 256 colors - and most do these days. This
42 usually requires no user interaction (but see below for what to do if things
43 don't Just Work). After getting this plugin happily installed, any time you
44 use :colorscheme it will do its magic and make the colorscheme Just Work.
45
46 Whenever you change colorschemes using the :colorscheme command this script
47 will be executed. It will take the colors that the scheme specified for use
48 in the GUI and use an approximation algorithm to try to gracefully degrade
49 them to the closest color available in your terminal. If you are running in
50 a GUI or if your terminal doesn't support 88 or 256 colors, no changes are
51 made. Also, no changes will be made if the colorscheme seems to have been
52 high color already.
53
54 If for some reason this transparent method isn't suitable to you (for instance
55 if your environment can't be configured to meet the |csapprox-requirements|,
56 or you need to work in Vim 6), another option is also available: using the
57 |:CSApproxSnapshot| command to create a new GUI/88-/256-color terminal
58 colorscheme. To use this command, a user would generally start GVim, choose a
59 colorscheme that sets up the desired colors, and then use |:CSApproxSnapshot|
60 to create a new colorscheme based on those colors that works in high color
61 terminals. This method is more flexible than the transparent mode and works
62 in more places, but also requires more user intervention, and makes it harder
63 to deal with colorschemes being updated and such.
bec6ab6 Version 3.00
Matt Wozniski authored
64 *:CSApproxSnapshot*
ce2b1fd Version 3.50
Matt Wozniski authored
65 The full syntax for the command is: >
bec6ab6 Version 3.00
Matt Wozniski authored
66 :CSApproxSnapshot[!] /path/to/new/colorscheme
67 < For example: >
68 :CSApproxSnapshot ~/.vim/colors/foobar.vim
69 <
70 NOTE: The generated colorscheme will only work in 88- and 256-color terminals,
71 and in GVim. It will not work at all in a terminal with 16 or fewer
72 colors. There's just no reliable way to approximate down from
73 16,777,216 colors to 16 colors, especially without there being any
74 standard for what those 16 colors look like other than 'orange-ish',
75 'red-ish', etc.
76
a295809 Version 4.00
Matt Wozniski authored
77 NOTE: Although |:CSApproxSnapshot| can be used in both GVim and terminal Vim,
bec6ab6 Version 3.00
Matt Wozniski authored
78 the resulting colors might be slightly off when run from terminal Vim.
79 I can find no way around this; Vim internally sets different colors when
80 running in a terminal than running in the GUI, and there's no way for
81 terminal Vim to figure out what color would have been used in GVim.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
82
a295809 Version 4.00
Matt Wozniski authored
83 *:CSApprox*
84 A command is also provided to run the approximation manually. This might be
85 useful if some colors were set outside of a colorscheme file, for instance.
86 By default, it will not change any colors unless no highlight group is set to
87 a color above 15, which is CSApprox's normal behavior. This probably isn't
88 useful in most use cases, though. On the other hand, if a ! is provided,
89 CSApprox will skip that test and update the cterm value for every highlight
90 group from the corresponding gui color. Syntax:
91 >
92 :CSApprox[!]
93 <
94
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
95 ==============================================================================
96 2. Requirements *csapprox-requirements*
97
98 For CSApprox to work, there are 2 major requirements that must be met.
99
a295809 Version 4.00
Matt Wozniski authored
100 a) GUI support (or vim >= 7.3) *csapprox-gui-support* *csapprox-+gui*
101
102 NOTE This section only applies to vim versions before 7.3.000 - a modern vim
103 does not need GUI support in order for CSApprox to function.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
104
bec6ab6 Version 3.00
Matt Wozniski authored
105 If CSApprox is being used to adjust a scheme's colors transparently, then the
106 terminal "vim" binary that is being run must be built with GUI support (see
107 |csapprox-limitations| for an explanation). If |:CSApproxSnapshot| is being
108 used to create a terminal colorscheme for high color terminals, then the
109 "vim" binary being used to create the scheme must be built with +gui, but the
110 scheme can be used in terminal "vim" binaries that weren't built with +gui.
a295809 Version 4.00
Matt Wozniski authored
111
bec6ab6 Version 3.00
Matt Wozniski authored
112 NOTE that creating snapshots with GVim will work better than making them with
113 Vim, and (obviously) all "gvim" binaries are built with +gui.
114
115 Unfortunately, several Linux distributions only include GUI support in their
116 "gvim" binary, and not in their "vim" binary. You can check if GUI support is
117 available with the following command:
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
118 :echo has('gui')
119
120 If that prints 0, the first thing to try would be searching for a larger vim
121 package provided by your distribution, like "vim-enhanced" on RedHat/CentOS
bec6ab6 Version 3.00
Matt Wozniski authored
122 or "vim-gtk" or "vim-gnome" on Debian/Ubuntu.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
123
124 If you are unable to obtain a "vim" binary that includes GUI support, but
125 have a "gvim" binary available, you can probably launch Vim with GUI support
126 anyway by calling gvim with the |-v| flag in the shell: >
127 gvim -v
128
bec6ab6 Version 3.00
Matt Wozniski authored
129 If the above works, you can remove the need to call "gvim -v" instead of "vim"
130 all the time by creating a symbolic link from your "gvim" binary to "vim"
131 somewhere in your $PATH, for example:
132 sudo ln -s $(which gvim) $(which vim)
133
134 If launching as "gvim -v" doesn"t work, and no package with GUI support is
135 available, you will need to compile Vim yourself and ensure that GUI support
136 is included to use CSApprox in its transparent mode, or create a snapshotted
137 scheme from GVim to use its snapshot mode. If this is inconvenient for you,
138 make sure that the Vim maintainer for your distribution knows it; they made a
139 conscious decision to build "vim" without +gui and "gvim" without terminal
140 support.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
141
142 b) Properly configured terminal *csapprox-terminal*
143
144 As said above, many modern terminals support 88 or 256 colors, but most of
145 these default to setting $TERM to something generic (usually "xterm"). Since
146 Vim uses the value of the "colors" attribute for the current $TERM in terminfo
147 to figure out the number of colors used internally as 't_Co', this plugin will
148 either need for 't_Co' to be set to 88 or 256 in |vimrc|, or for $TERM to be
149 set to something that implies high color support. Possible choices include
150 "xterm-256color" for 256 color support and "rxvt-unicode" for 88 color
151 support.
152 *csapprox-palettes*
a295809 Version 4.00
Matt Wozniski authored
153 Also, there are at least three different 256-color palettes in use. Nearly
154 all terminals use an xterm-compatible palette, so most users need not concern
155 themselves with this, with only two exceptions: Eterm uses a slightly
156 different palette, and older Konsole (pre KDE 2.2.0) used a third palette.
157 CSApprox has no reliable way to tell which palette your terminal uses, so it
158 makes some educated guesses:
159
160 i) If vim thinks that there are 88 colors available, CSApprox will use the
161 xterm/urxvt-compatible 88 color palette (I don't know of any other
162 88 color palette in use anywhere).
163
164 ii) If $TERM starts with "Eterm", CSApprox will approximate based on the
165 Eterm palette.
166
167 iii) If $TERM starts with "konsole", CSApprox will use the legacy Konsole
168 palette if either "kde4-config --kde-version" or "kde-config --version"
169 reports that the KDE version on the system is less than 4.2.0.
170 Otherwise, it will use the xterm palette.
171
172 iv) If $TERM starts with "xterm" or "screen", then CSApprox looks for the
173 vim variables "g:CSApprox_eterm" and "g:CSApprox_konsole".
174 If g:CSApprox_eterm is true, CSApprox uses the Eterm palette.
175 If g:CSApprox_konsole is true, CSApprox uses the old konsole palette.
176 Otherwise, CSApprox uses the xterm palette.
177
178 v) For all other $TERM values, CSApprox uses the xterm palette.
179
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
180 *csapprox-terminal-example*
a295809 Version 4.00
Matt Wozniski authored
181 To turn on high color support despite an incorrect $TERM, you can override
182 t_Co (the vim name for the terminfo setting defining how many colors are
183 available) in your .vimrc, and set either CSApprox_konsole or CSApprox_eterm
184 if appropriate. You could put something like this into your |vimrc|:
bec6ab6 Version 3.00
Matt Wozniski authored
185 >
ce2b1fd Version 3.50
Matt Wozniski authored
186 if (&term == 'xterm' || &term =~? '^screen') && hostname() == 'my-machine'
a295809 Version 4.00
Matt Wozniski authored
187 " On my machine, I use an old Konsole with 256 color support
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
188 set t_Co=256
189 let g:CSApprox_konsole = 1
190 endif
191
ce2b1fd Version 3.50
Matt Wozniski authored
192 Gnome Terminal, as of the time that I am writing this, doesn't support having
193 the terminal emulator set $TERM to something adequately descriptive. In cases
194 like this, something like the following would be appropriate:
195 >
196 if &term =~ '^\(xterm\|screen\)$' && $COLORTERM == 'gnome-terminal'
197 set t_Co=256
198 endif
199
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
200 ==============================================================================
201 3. Configuration *csapprox-configure*
202
203 There are several global variables that can be set to configure the behavior
204 of CSApprox. They are listed roughly based on the likelihood that the end
205 user might want to know about them.
206
207 g:CSApprox_loaded *g:CSApprox_loaded*
bec6ab6 Version 3.00
Matt Wozniski authored
208 If set in your |vimrc|, CSApprox is not loaded. Has no effect on
209 snapshotted schemes.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
210
211 g:CSApprox_verbose_level *g:CSApprox_verbose_level*
212 When CSApprox is run, the 'verbose' option will be temporarily raised to
213 the value held in this variable unless it is already greater. The default
214 value is 1, which allows CSApprox to default to warning whenever something
215 is wrong, even if it is recoverable, but allows the user to quiet us if he
216 wants by changing this variable to 0. The most important messages will be
217 shown at verbosity level 1; some less important ones will be shown at
bec6ab6 Version 3.00
Matt Wozniski authored
218 higher verbosity levels. Has no effect on snapshotted schemes.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
219
a295809 Version 4.00
Matt Wozniski authored
220 g:CSApprox_fake_reverse *g:CSApprox_fake_reverse*
221 In gvim, setting a highlight group like "Visual" (the color of your visual
222 mode selection) to do reverse video results in it reversing the colors of
223 each character cell under it. Some terminals don't support this and will
224 instead always use the default background color on the default foreground
225 color when asked for reverse video. If this variable is set to a non-zero
226 number, CSApprox will change any request for reverse video to the "Normal"
227 group's bg color on the "Normal" group's fg color, instead of asking the
228 terminal to do reverse video. This provides a middle ground for terminals
229 that don't properly support reverse video - it's worse than having the
230 terminal properly reverse the colors of each character cell, but it's
231 better than the broken behavior of some terminal emulators. This was the
232 default behavior before CSApprox 4.0.
233
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
234 g:CSApprox_eterm *g:CSApprox_eterm*
bec6ab6 Version 3.00
Matt Wozniski authored
235 If set to a non-zero number, CSApprox will use the Eterm palette when
236 'term' is set to "xterm" or begins with "screen". Otherwise, the xterm
237 palette would be used. This also affects snapshotted schemes.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
238
239 g:CSApprox_konsole *g:CSApprox_konsole*
a295809 Version 4.00
Matt Wozniski authored
240 If set to a non-zero number, CSApprox will use the old Konsole palette
241 when 'term' is set to "xterm" or begins with "screen". Otherwise, the
242 xterm palette would be used. This also affects snapshotted schemes.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
243
244 g:CSApprox_attr_map *g:CSApprox_attr_map*
245 Since some attributes (like 'guisp') can't be used in a terminal, and
246 others (like 'italic') are often very ugly in terminals, a generic way to
247 map between a requested attribute and another attribute is included. This
248 variable should be set to a Dictionary, where the keys are strings
249 representing the attributes the author wanted set, and the values are the
250 strings that the user wants set instead. If a value is '', it means the
251 attribute should just be ignored. The default is to replace 'italic' with
252 'underline', and to use 'fg' instead of 'sp': >
253 let g:CSApprox_attr_map = { 'italic' : 'underline', 'sp' : 'fg' }
254 <
255 Your author prefers disabling bold and italic entirely, so uses this: >
256 let g:CSApprox_attr_map = { 'bold' : '', 'italic' : '', 'sp' : 'fg' }
257 <
bec6ab6 Version 3.00
Matt Wozniski authored
258
259 Note: This transformation is considered at the time a snapshotted scheme
260 is created, rather than when it is used.
261
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
262 Note: You can only map an attribute representing a color to another
263 attribute representing a color; likewise with boolean attributes.
264 After all, sp -> bold and italic -> fg would be nonsensical.
265
8f0f2b7 Version 2.00
Matt Wozniski authored
266 *g:CSApprox_hook_pre* *g:CSApprox_hook_{scheme}_pre*
267 *g:CSApprox_hook_post* *g:CSApprox_hook_{scheme}_post*
268 g:CSApprox_hook_pre
269 g:CSApprox_hook_post
270 g:CSApprox_hook_{scheme}_pre
271 g:CSApprox_hook_{scheme}_post *csapprox-hooks*
272 These variables provide a method for adjusting tweaking the approximation
bec6ab6 Version 3.00
Matt Wozniski authored
273 algorithm, either for all schemes, or on a per scheme basis. For
274 snapshotted schemes, these will only take effect when the snapshotted
275 scheme is created, rather than when it is used. Each of these variables
276 may be set to either a String containing a command to be :execute'd, or a
277 List of such Strings. The _pre hooks are executed before any
278 approximations have been done. In order to affect the approximation at
279 this stage, you would need to change the gui colors for a group; the cterm
280 colors will then be approximated from those gui colors. Example:
8f0f2b7 Version 2.00
Matt Wozniski authored
281 >
282 let g:CSApprox_hook_pre = 'hi Comment guibg=#ffddff'
283 <
284 The advantage to tweaking the colors at this stage is that CSApprox will
285 handle approximating the given gui colors to the proper cterm colors,
286 regardless of the number of colors the terminal supports. The
287 disadvantage is that certain things aren't possible, including clearing
288 the background or foreground color for a group, selecting a precise cterm
289 color to be used, and overriding the mappings made by g:CSApprox_attr_map.
290 Another notable disadvantage is that overriding things at this level will
291 actually affect the gui colors, in case the :gui is used to start gvim
292 from the running vim instance.
293
294 To overcome these disadvantages, the _post hooks are provided. These
295 hooks will be executed only after all approximations have been completed.
296 At this stage, in order to have changes appear the cterm* colors must be
297 modified. For example:
298 *csapprox-transparency*
299 >
bec6ab6 Version 3.00
Matt Wozniski authored
300 let g:CSApprox_hook_post = ['hi Normal ctermbg=NONE ctermfg=NONE',
301 \ 'hi NonText ctermbg=NONE ctermfg=NONE' ]
8f0f2b7 Version 2.00
Matt Wozniski authored
302 <
303 Setting g:CSApprox_hook_post as shown above will clear the background of
304 the Normal and NonText groups, forcing the terminal's default background
305 color to be used instead, including any pseudotransparency done by that
306 terminal emulator. As noted, though, the _post functions do not allow
307 CSApprox to approximate the colors. This may be desired, but if this is
308 an inconvenience the function named by g:CSApprox_approximator_function
309 can still be called manually. For example:
310 >
311 let g:CSApprox_hook_post = 'exe "hi Comment ctermbg="'
312 \ . '. g:CSApprox_approximator_function(0xA0,0x50,0x35)'
313 <
314 The _{scheme}_ versions are exactly like their counterparts, except that
315 they will only be executed if the value of g:colors_name matches the
316 scheme name embedded in the variable name. They will be executed after
317 the corresponding hook without _{scheme}_, which provides a way to
318 override a less specific hook with a more specific one. For example, to
319 clear the Normal and NonText groups, but only for the colorscheme
320 "desert", one could do the following:
321 >
bec6ab6 Version 3.00
Matt Wozniski authored
322 let g:CSApprox_hook_desert_post = ['hi Normal ctermbg=NONE ctermfg=NONE',
323 \ 'hi NonText ctermbg=NONE ctermfg=NONE' ]
324 <
325 One final example: If you want CSApprox to be active for nearly all
326 colorschemes, but want one or two particular schemes to be ignored, you
327 can take advantage of the CSApprox logic that skips over any color scheme
328 that is already high color by setting a color to a number above 255. Note
329 that most colors greater than 15 will work, but some will not - 256 should
330 always work. For instance, you can prevent CSApprox from modifying the
331 colors of the zellner colorscheme like this:
332 >
333 let g:CSApprox_hook_zellner_pre = 'hi _FakeGroup ctermbg=256'
8f0f2b7 Version 2.00
Matt Wozniski authored
334 <
335 NOTE: Any characters that would stop the string stored in g:colors_name
336 from being a valid variable name will be removed before the
337 _{scheme}_ hook is searched. Basically, this means that first all
338 characters that are neither alphanumeric nor underscore will be
339 removed, then any leading digits will be removed. So, for a
340 colorscheme named "123 foo_bar-baz456.vim", the hook searched for
341 will be, eg, g:CSApprox_hook_foo_barbaz456_post
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
342
ce2b1fd Version 3.50
Matt Wozniski authored
343 g:CSApprox_use_showrgb *g:CSApprox_use_showrgb*
344 By default, CSApprox will use a built in mapping of color names to values.
345 This optimization greatly helps speed, but means that colors addressed by
346 name might not match up perfectly between gvim (which uses the system's
347 real rgb database) and CSApprox (which uses the builtin database). To
348 force CSApprox to try the systemwide database first, and only fall back on
349 the builtin database if it isn't available, set this variable non-zero.
bec6ab6 Version 3.00
Matt Wozniski authored
350
351 g:CSApprox_approximator_function *g:CSApprox_approximator_function*
352 If the default approximation function doesn't work well enough, the user
353 (or another author wishing to extend this plugin) can write another
354 approximation function. This function should take three numbers,
355 representing r, g, and b in decimal, and return the index on the color
356 cube that best matches those colors. Assigning a |Funcref| to this
357 variable will override the default approximator with the one the Funcref
358 references. This option will take effect at the time a snapshotted scheme
359 is created, rather than when it's used.
360
361 g:CSApprox_redirfallback *g:CSApprox_redirfallback*
362 Until Vim 7.2.052, there was a bug in the Vim function synIDattr() that
363 made it impossible to determine syntax information about the |guisp|
364 attribute. CSApprox includes a workaround for this problem, as well as a
365 test that ought to disable this workaround if synIDattr() works properly.
366 If this test should happen to give improper results somehow, the user can
367 force the behavior with this variable. When set to 1, the workaround will
368 always be used, and when set to 0, synIDattr() is blindly used. Needless
369 to say, if this automatic detection should ever fail, the author would
370 like to be notified! This option will take effect at the time a
371 snapshotted scheme is created, rather than when it's used.
372
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
373 ==============================================================================
374 4. Rationale/Design *csapprox-design*
375
ce2b1fd Version 3.50
Matt Wozniski authored
376 There is a wealth of colorschemes available for Vim. Unfortunately, since
377 traditional terminal emulators have only supported 2, 8 or 16 colors,
378 colorscheme authors have tended to avoid writing colorschemes for terminal
379 Vim, sticking instead to GVim. Even now that nearly every popular terminal
380 supports either 88 or 256 colors, few colorschemes are written to support
381 them. This may be because the terminal color codes are just numbers from 0 to
382 87 or 255 with no semantic meaning, or because the same number doesn't yield
383 the same color in all terminals, or simply because the colorscheme author
384 doesn't use the terminal and doesn't want to take the time to support
385 terminals.
386
387 Whatever the reason, this leaves users of many modern terminal emulators in
388 the awkward position of having a terminal emulator that supports many colors,
389 but having very few colorschemes that were written to utilize those colors.
390
391 This is where CSApprox comes in. It attempts to fill this void allowing GVim
392 colorschemes to be used in terminal Vim. CSApprox has two distinct modes of
393 operation. In the first mode, it attempts to make GVim colorschemes
394 transparently backwards compatible with terminal Vim in a high color terminal.
395 Basically, whenever a colorscheme is run it should set some colors for the
396 GUI, and this script will then run and attempt to figure out the closest color
397 available in the terminal's color palette to the color the scheme author asked
398 for. Unfortunately, this does not work well all the time, and it has some
399 limitations (see |csapprox-limitations|). Most of the time, however, this
400 gives a very close approximation to the GVim colors without requiring any
401 changes to the colorscheme, or any user interaction. It only requires that
402 the plugin be installed on the machine where Vim is being run, and that the
403 user's environment meets the needs specified at |csapprox-requirements|. In
a295809 Version 4.00
Matt Wozniski authored
404 the event that this doesn't work, a second option - using |:CSApproxSnapshot|
ce2b1fd Version 3.50
Matt Wozniski authored
405 to create a new, 88-/256-color capable colorscheme - is available.
406
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
407 Ideally, the aim is for CSApprox to be completely transparent to the user.
408 This is why the approach I take is entirely different from the GuiColorScheme
409 script, which will break on any but the simplest colorschemes. Unfortunately,
410 given the difficulty of determining exactly which terminal emulator the user
411 is running, and what features it supports, and which color palette it's using,
412 perfect transparency is difficult. So, to this end, I've attempted to default
413 to settings that make it unlikely that this script ever makes things worse
414 (this is why I chose not to override t_Co to 256 myself), and I've attempted
415 to make it easy to override my choice of defaults when necessary (through
416 g:CSApprox_approximator_function, g:CSApprox_konsole, g:CSApprox_eterm,
bec6ab6 Version 3.00
Matt Wozniski authored
417 g:CSApprox_attr_map, etc).
418
ce2b1fd Version 3.50
Matt Wozniski authored
419 In the event that the transparent solution is undesirable, or that the user's
420 environment can't be configured to allow it (no GVim and no Vim with +gui, for
421 instance), |:CSApproxSnapshot| should provide a workable alternative - less
422 cool, and less flexible, but it will work in more environments, and the
423 snapshotted colorscheme will even work in Vim 6.
bec6ab6 Version 3.00
Matt Wozniski authored
424
425 If any of my design choices seem to be causing extra work with no real
426 advantages, though, I'd like to hear about it. Feel free to email me with any
427 improvements or complaints.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
428
429 ==============================================================================
430 5. Known Bugs and Limitations *csapprox-limitations*
431
a295809 Version 4.00
Matt Wozniski authored
432 GUI support or vim >= 7.3 is required for transparently adapting schemes.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
433
434 There is nothing I can do about this given my chosen design. CSApprox works
435 by being notified every time a colorscheme sets some GUI colors, then
436 approximating those colors to similar terminal colors. Unfortunately, when
a295809 Version 4.00
Matt Wozniski authored
437 Vim < 7.3 is not built with GUI support, it doesn't bother to store the GUI
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
438 colors, so querying for them fails. This leaves me completely unable to
439 tell what the colorscheme was trying to do. See |csapprox-+gui| for some
a295809 Version 4.00
Matt Wozniski authored
440 potential workarounds if your distribution doesn't provide a Vim with +gui
441 and you can't upgrade to a modern vim.
e5ed96a Version 1.50
Matt Wozniski authored
442
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
443 User intervention is sometimes required for information about the terminal.
444
445 This is really an insurmountable problem. Unfortunately, most terminal
446 emulators default to setting $TERM to 'xterm', even when they're not really
447 compatible with an xterm. $TERM is really the only reliable way to
448 find anything at all out about the terminal you're running in, so there's no
449 way to know if the terminal supports 88 or 256 colors without either the
bec6ab6 Version 3.00
Matt Wozniski authored
450 terminal telling me (using $TERM) or the user telling me (using 't_Co').
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
451 Similarly, unless $TERM is set to something that implies a certain color
452 palette ought to be used, there's no way for me to know, so I'm forced to
453 default to the most common, xterm's palette, and allow the user to override
454 my choice with |g:CSApprox_konsole| or |g:CSApprox_eterm|. An example of
455 configuring Vim to work around a terminal where $TERM is set to something
456 generic without configuring the terminal properly is shown at
457 |csapprox-terminal-example|.
458
bec6ab6 Version 3.00
Matt Wozniski authored
459 Some colorschemes could fail to be converted if they try to be too smart.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
460
461 A colorscheme could decide to only set colors for the mode Vim is running
462 in. If a scheme only sets GUI colors when the GUI is running, instead of
463 using the usual approach of setting all colors and letting Vim choose which
464 to use, my approach falls apart. My method for figuring out what the scheme
465 author wants the scheme to look like absolutely depends upon him setting the
466 GUI colors in all modes. Fortunately, the few colorschemes that do this
467 seem to be, by and large, intended for 256 color terminals already, meaning
bec6ab6 Version 3.00
Matt Wozniski authored
468 that skipping them is the proper behavior. Note that this will only affect
469 transparently adapted schemes and snapshots made from terminal Vim;
470 snapshots made from GVim are immune to this problem.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
471
bec6ab6 Version 3.00
Matt Wozniski authored
472 Transparently adapting schemes is slow.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
473
474 For me, it takes Vim's startup time from 0.15 seconds to 0.35 seconds. This
475 is probably still acceptable, but it is definitely worth trying to cut down
bec6ab6 Version 3.00
Matt Wozniski authored
476 on this time in future versions. Snapshotted schemes are faster to use,
477 since all of the hard evaluations are made when they're made instead of when
478 they're used.
e5ed96a Version 1.50
Matt Wozniski authored
479
ce2b1fd Version 3.50
Matt Wozniski authored
480 NOTE: As of CSApprox 3.50, the overhead is down to about 0.10 seconds on my
481 test machine.
482
a295809 Version 4.00
Matt Wozniski authored
483 It isn't possible to approximate only a particular set of groups.
484
485 Unfortunately, the :CSApprox command will always update all groups, even if
486 only a small set of groups has changed. A future improvement would be to
487 provide a function called, say, CSApprox(), that takes an optional list of
488 highlight groups (default: all) and only does approximation for those
489 groups.
490
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
491 ==============================================================================
492 6. Appendix - Terminals and Palettes *csapprox-terminal-list*
493
494 What follows is a list of terminals known to have and known not to have high
495 color support. This list is certainly incomplete; feel free to contact me
496 with more to add to either list.
497
498 *csapprox-terminals-good*
499 ------------------------------- Good Terminals -------------------------------
500
501 The most recent versions of each of these terminals can be compiled with
502 either 88 or 256 color support.
503
504 *csapprox-xterm*
505 xterm:
506 256 color palette
507 Colors composed of: [ 0x00, 0x5F, 0x87, 0xAF, 0xD7, 0xFF ]
508 Greys composed of: [ 0x08, 0x12, 0x1C, 0x26, 0x30, 0x3A, 0x44, 0x4E,
509 0x58, 0x62, 0x6C, 0x76, 0x80, 0x8A, 0x94, 0x9E,
510 0xA8, 0xB2, 0xBC, 0xC6, 0xD0, 0xDA, 0xE4, 0xEE ]
511
512 *csapprox-urxvt*
513 rxvt-unicode (urxvt):
514 88 colors by default (but a patch is available to use xterm's palette)
515 Colors composed of: [ 0x00, 0x8B, 0xCD, 0xFF ]
516 Greys composed of: [ 0x2E, 0x5C, 0x73, 0x8B, 0xA2, 0xB9, 0xD0, 0xE7 ]
517
518 *csapprox-pterm* *csapprox-putty*
519 PuTTY (pterm; putty.exe):
520 256 colors; same palette as xterm
521
522 *csapprox-mrxvt*
523 Mrxvt (mrxvt):
524 256 colors; same palette as xterm
525
526 *csapprox-gnome-terminal*
527 GNOME Terminal (gnome-terminal):
528 256 colors; same palette as xterm
529
530 *csapprox-roxterm*
531 ROXTerm (roxterm):
532 256 colors; same palette as xterm
533
534 *csapprox-xfce4-terminal*
535 Terminal (xfce4-terminal):
536 256 colors; same palette as xterm
537
538 *csapprox-iterm.app*
539 iTerm (iTerm.app):
540 256 colors; same palette as xterm
541 *csapprox-konsole*
542 Konsole (konsole):
543 256 color palette
a295809 Version 4.00
Matt Wozniski authored
544 Colors used to be composed of: [ 0x00, 0x33, 0x66, 0x99, 0xCC, 0xFF ]
545 As of KDE 2.2.0, colors match the xterm palette
546 Always used the same greyscales as xterm
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
547
548 *csapprox-eterm*
549 eterm (Eterm):
550 256 color palette
551 Colors composed of: [ 0x00, 0x2A, 0x55, 0x7F, 0xAA, 0xD4 ]
552 Same greyscales as xterm
553 You should set the g:CSApprox_eterm variable unless $TERM begins with
554 'eterm', case insensitive
555
556 *csapprox-screen*
557 GNU Screen (screen):
558 256 color support. Internally, uses the xterm palette, but this is only
559 relevant when running screen inside a terminal with fewer than 256 colors,
560 in which case screen will attempt to map between its own 256 color cube
8f0f2b7 Version 2.00
Matt Wozniski authored
561 and the colors supported by the real terminal to the best of its ability,
562 in much the same way as CSApprox maps between GUI and terminal colors.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
563
564 *csapprox-terminals-bad*
565 -------------------------------- Bad Terminals -------------------------------
bec6ab6 Version 3.00
Matt Wozniski authored
566 This is a list of terminals known _not_ to have high color support. If any of
567 these terminals have high color support added at some point in the future,
568 please tell me and I'll update this information.
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
569
570 *csapprox-terminal.app*
571 Terminal.app (as of OS X 10.5.2)
572
573 *csapprox-aterm*
574 aterm (as of version 1.00.01)
575
576 *csapprox-xiterm*
577 xiterm (as of version 0.5)
578
579 *csapprox-wterm*
580 wterm (as of version 6.2.9)
581
582 *csapprox-mlterm*
583 mlterm (as of version 2.9.4)
584
585 *csapprox-kterm*
586 kterm (as of version 6.2.0)
587
588 ==============================================================================
589 7. Changelog *csapprox-changelog*
590
a295809 Version 4.00
Matt Wozniski authored
591 4.00 14 Sep 2012 Fix CSApprox to not fail in vim 7.3 if not +gui, now
592 that vim behaves properly even without +gui
593
594 Provide the |:CSApprox| command to re-run CSApprox's
595 approximation algorithm even if the colorscheme hasn't
596 changed - useful for when the user has tweaked some
597 colors manually.
598
599 Better handling for the |inverse| (aka reverse) attribute
600 for terminals that actually support it - and add the
601 g:CSApprox_fake_reverse config variable to allow
602 switching back to the old behavior for terminals that
603 don't support real reverse video.
604
605 Fix an issue where CSApprox would unconditionally leave
606 'background' set to "light" - now it will leave
607 'background' unchanged when it runs.
608
609 Change the handling for Konsole to use the xterm palette
610 by for KDE versions >= 2.2.0 - Konsole itself was
611 changed to drop its old, slightly incompatible palette
612 in KDE 2.2.0
613
614 Fix a minor issue where running vim in recovery mode
615 with |-r| would result in a complaint from CSApprox that
616 the terminal didn't have enough colors even when it did.
617
618 Fix an issue where, even if CSApprox had been disabled
619 by setting |g:CSApprox_loaded|, a CSApprox error message
620 could still be displayed.
621
ce2b1fd Version 3.50
Matt Wozniski authored
622 3.50 01 Apr 2009 Fix a major regression that prevented the Eterm and
623 Konsole colors from being correctly snapshotted
624
625 Fix a related bug causing incorrect terminal colors
a295809 Version 4.00
Matt Wozniski authored
626 after calling |:CSApproxSnapshot|
ce2b1fd Version 3.50
Matt Wozniski authored
627
628 Fix a bug causing black to be used instead of dark grey
629
630 Have snapshots calculate g:colors_name programmatically
631
632 Introduce many tweaks for better speed
633
634 Clarify some things at :help csapprox-terminal-example
635
636 Default to using our own list of rgb.txt colors rather
637 than searching, for performance. Add a new variable,
638 g:CSApprox_use_showrgb, which forces us to try finding
639 the colors using the "showrgb" program instead, and fall
640 back on our own list if it isn't available
641
642 Remove g:CSApprox_extra_rgb_txt_dirs - not needed in
643 light of the above change
644
a7e0d0c Version 3.05
Matt Wozniski authored
645 3.05 31 Jan 2009 Fix a harmless "Undefined variable" error in
a295809 Version 4.00
Matt Wozniski authored
646 |:CSApproxSnapshot|
a7e0d0c Version 3.05
Matt Wozniski authored
647
648 Fix a behavioral bug when dumping out colors defined
649 external to the scheme.
650
a295809 Version 4.00
Matt Wozniski authored
651 3.00 21 Jan 2009 Update the docs for better info on |:CSApproxSnapshot|
bec6ab6 Version 3.00
Matt Wozniski authored
652
653 Allow snapshotted schemes to work on Vim 6, and work
654 properly in Konsole and Eterm (thanks David Majnemer!)
655
656 Fix a bug causing a syntax error when using GVim while
657 CSApprox was loaded. (thanks again, David Majnemer!)
658
8f0f2b7 Version 2.00
Matt Wozniski authored
659 2.00 14 Dec 2008 Add a hooks system, allowing users to specify a command
660 to run, either before or after the approximation
661 algorithm is run, for all schemes or one specific one.
662
a295809 Version 4.00
Matt Wozniski authored
663 Also rewrite |:CSApproxSnapshot| to be more maintainable
8f0f2b7 Version 2.00
Matt Wozniski authored
664 and less of a hack, and fix several bugs that it
665 contained.
666
e5ed96a Version 1.50
Matt Wozniski authored
667 1.50 19 Nov 2008 Add CSApproxSnapshot command, as an alternative solution
668 when the user has gvim or a vim with gui support, but
669 sometimes needs to use a vim without gui support.
670
efe8bf5 Version 1.10
Matt Wozniski authored
671 1.10 28 Oct 2008 Enable running on systems with no rgb.txt (Penn Su)
672 Begin distributing a copy of rgb.txt with CSApprox
673
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
674 1.00 04 Oct 2008 First public release
675
676 0.90 14 Sep 2008 Initial beta release
677
678 ==============================================================================
679 8. Contact Info *csapprox-author*
680
681 Your author, a Vim nerd with some free time, was sick of seeing terminals
682 always get the short end of the stick. He'd like to be notified of any
683 problems you find - after all, he took the time to write all this lovely
684 documentation, and this plugin, which took more time than you could possibly
685 imagine to get working transparently for every colorscheme he could get his
a295809 Version 4.00
Matt Wozniski authored
686 hands on. You can contact him with any problems or praises at
687 godlygeek@gmail.com
9f658ab Version 1.00: Initial upload
Matt Wozniski authored
688
689 ==============================================================================
690 vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl:
Something went wrong with that request. Please try again.