]> Tony Duckles's Git Repositories (git.nynim.org) - dotfiles.git/blob - .vim/bundle/vim-colors-solarized/README.mkd
.vimrc: Enable swap files; scrolloff and sidescroll; comment clean-up
[dotfiles.git] / .vim / bundle / vim-colors-solarized / README.mkd
1 ---
2 Title: Solarized Colorscheme for Vim
3 Description: Precision colors for machines and people
4 Author: Ethan Schoonover
5 Colors: light yellow
6 Created: 2011 Mar 15
7 Modified: 2011 Apr 16
8
9 ---
10
11 Solarized Colorscheme for Vim
12 =============================
13
14 Developed by Ethan Schoonover <es@ethanschoonover.com>
15
16 Visit the [Solarized homepage]
17 ------------------------------
18
19 See the [Solarized homepage] for screenshots,
20 details and colorscheme versions for Vim, Mutt, popular terminal emulators and
21 other applications.
22
23 Screenshots
24 -----------
25
26 ![solarized dark](https://github.com/altercation/solarized/raw/master/img/solarized-vim.png)
27
28 Downloads
29 ---------
30
31 If you have come across this colorscheme via the [Vim-only repository] on
32 github, or the [vim.org script] page see the link above to the Solarized
33 homepage or visit the main [Solarized repository].
34
35 The [Vim-only repository] is kept in sync with the main [Solarized repository]
36 and is for installation convenience only (with [Pathogen] or [Vundle], for
37 instance). Issues, bug reports, changelogs are centralized at the main
38 [Solarized repository].
39
40 [Solarized homepage]: http://ethanschoonover.com/solarized
41 [Solarized repository]: https://github.com/altercation/solarized
42 [Vim-only repository]: https://github.com/altercation/vim-colors-solarized
43 [vimorg-script]: http://vim.org/script
44 [Pathogen]: https://github.com/tpope/vim-pathogen
45 [Vundle]: https://github.com/gmarik/vundle
46
47 Installation
48 ------------
49
50 ### Option 1: Manual installation
51
52 1. Move `solarized.vim` to your `.vim/colors` directory. After downloading the
53 vim script or package:
54
55 $ cd vim-colors-solarized/colors
56 $ mv solarized.vim ~/.vim/colors/
57
58 ### Option 2: Pathogen installation ***(recommended)***
59
60 1. Download and install Tim Pope's [Pathogen].
61
62 2. Next, move or clone the `vim-colors-solarized` directory so that it is
63 a subdirectory of the `.vim/bundle` directory.
64
65 a. **Clone:**
66
67 $ cd ~/.vim/bundle
68 $ git clone git://github.com/altercation/vim-colors-solarized.git
69
70 b. **Move:**
71
72 In the parent directory of vim-colors-solarized:
73
74 $ mv vim-colors-solarized ~/.vim/bundle/
75
76 ### Modify .vimrc
77
78 After either Option 1 or Option 2 above, put the following two lines in your
79 .vimrc:
80
81 syntax enable
82 set background=dark
83 colorscheme solarized
84
85 or, for the light background mode of Solarized:
86
87 syntax enable
88 set background=light
89 colorscheme solarized
90
91 I like to have a different background in GUI and terminal modes, so I can use
92 the following if-then. However, I find vim's background autodetection to be
93 pretty good and, at least with MacVim, I can leave this background value
94 assignment out entirely and get the same results.
95
96 if has('gui_running')
97 set background=light
98 else
99 set background=dark
100 endif
101
102 See the [Solarized homepage] for screenshots which will help you
103 select either the light or dark background.
104
105 ### IMPORTANT NOTE FOR TERMINAL USERS:
106
107 If you are going to use Solarized in Terminal mode (i.e. not in a GUI version
108 like gvim or macvim), **please please please** consider setting your terminal
109 emulator's colorscheme to used the Solarized palette. I've included palettes
110 for some popular terminal emulator as well as Xdefaults in the official
111 Solarized download available from [Solarized homepage]. If you use
112 Solarized *without* these colors, Solarized will need to be told to degrade its
113 colorscheme to a set compatible with the limited 256 terminal palette (whereas
114 by using the terminal's 16 ansi color values, you can set the correct, specific
115 values for the Solarized palette).
116
117 If you do use the custom terminal colors, solarized.vim should work out of the
118 box for you. If you are using a terminal emulator that supports 256 colors and
119 don't want to use the custom Solarized terminal colors, you will need to use
120 the degraded 256 colorscheme. To do so, simply add the following line *before*
121 the `colorschem solarized` line:
122
123 let g:solarized_termcolors=256
124
125 Again, I recommend just changing your terminal colors to Solarized values
126 either manually or via one of the many terminal schemes available for import.
127
128 Advanced Configuration
129 ----------------------
130
131 Solarized will work out of the box with just the two lines specified above but
132 does include several other options that can be set in your .vimrc file.
133
134 Set these in your vimrc file prior to calling the colorscheme.
135 "
136 option name default optional
137 ------------------------------------------------
138 g:solarized_termcolors= 16 | 256
139 g:solarized_termtrans = 0 | 1
140 g:solarized_degrade = 0 | 1
141 g:solarized_bold = 1 | 0
142 g:solarized_underline = 1 | 0
143 g:solarized_italic = 1 | 0
144 g:solarized_contrast = "normal"| "high" or "low"
145 g:solarized_visibility= "normal"| "high" or "low"
146 ------------------------------------------------
147
148 ### Option Details
149
150 * g:solarized_termcolors
151
152 This is set to *16* by default, meaning that Solarized will attempt to use
153 the standard 16 colors of your terminal emulator. You will need to set
154 those colors to the correct Solarized values either manually or by
155 importing one of the many colorscheme available for popular terminal
156 emulators and Xdefaults.
157
158 * g:solarized_termtrans
159
160 If you use a terminal emulator with a transparent background and Solarized
161 isn't displaying the background color transparently, set this to 1 and
162 Solarized will use the default (transparent) background of the terminal
163 emulator. *urxvt* required this in my testing; iTerm2 did not.
164
165 Note that on Mac OS X Terminal.app, solarized_termtrans is set to 1 by
166 default as this is almost always the best option. The only exception to
167 this is if the working terminfo file supports 256 colors (xterm-256color).
168
169 * g:solarized_degrade
170
171 For test purposes only; forces Solarized to use the 256 degraded color mode
172 to test the approximate color values for accuracy.
173
174 * g:solarized_bold | g:solarized_underline | g:solarized_italic
175
176 If you wish to stop Solarized from displaying bold, underlined or
177 italicized typefaces, simply assign a zero value to the appropriate
178 variable, for example: `let g:solarized_italic=0`
179
180 * g:solarized_contrast
181
182 Stick with normal! It's been carefully tested. Setting this option to high
183 or low does use the same Solarized palette but simply shifts some values up
184 or down in order to expand or compress the tonal range displayed.
185
186 * g:solarized_visibility
187
188 Special characters such as trailing whitespace, tabs, newlines, when
189 displayed using `:set list` can be set to one of three levels depending on
190 your needs. Default value is `normal` with `high` and `low` options.
191
192 Toggle Background Function
193 --------------------------
194
195 Solarized comes with a Toggle Background plugin that by default will map to
196 <F5> if that mapping is available. If it is not available you will need to
197 either map the function manually or change your current <F5> mapping to
198 something else.
199
200 To set your own mapping in your .vimrc file, simply add the following line to
201 support normal, insert and visual mode usage, changing the "<F5>" value to the
202 key or key combination you wish to use:
203
204 call togglebg#map("<F5>")
205
206 Note that you'll want to use a single function key or equivalent if you want
207 the plugin to work in all modes (normal, insert, visual).
208
209 Code Notes
210 ----------
211
212 Use folding to view the `solarized.vim` script with `foldmethod=marker` turned
213 on.
214
215 I have attempted to modularize the creation of Vim colorschemes in this script
216 and, while it could be refactored further, it should be a good foundation for
217 the creation of any color scheme. By simply changing the sixteen values in the
218 GUI section and testing in gvim (or mvim) you can rapidly prototype new
219 colorschemes without diving into the weeds of line-item editing each syntax
220 highlight declaration.
221
222 The Values
223 ----------
224
225 L\*a\*b values are canonical (White D65, Reference D50), other values are
226 matched in sRGB space.
227
228 SOLARIZED HEX 16/8 TERMCOL XTERM/HEX L*A*B sRGB HSB
229 --------- ------- ---- ------- ----------- ---------- ----------- -----------
230 base03 #002b36 8/4 brblack 234 #1c1c1c 15 -12 -12 0 43 54 193 100 21
231 base02 #073642 0/4 black 235 #262626 20 -12 -12 7 54 66 192 90 26
232 base01 #586e75 10/7 brgreen 240 #4e4e4e 45 -07 -07 88 110 117 194 25 46
233 base00 #657b83 11/7 bryellow 241 #585858 50 -07 -07 101 123 131 195 23 51
234 base0 #839496 12/6 brblue 244 #808080 60 -06 -03 131 148 150 186 13 59
235 base1 #93a1a1 14/4 brcyan 245 #8a8a8a 65 -05 -02 147 161 161 180 9 63
236 base2 #eee8d5 7/7 white 254 #d7d7af 92 -00 10 238 232 213 44 11 93
237 base3 #fdf6e3 15/7 brwhite 230 #ffffd7 97 00 10 253 246 227 44 10 99
238 yellow #b58900 3/3 yellow 136 #af8700 60 10 65 181 137 0 45 100 71
239 orange #cb4b16 9/3 brred 166 #d75f00 50 50 55 203 75 22 18 89 80
240 red #dc322f 1/1 red 160 #d70000 50 65 45 220 50 47 1 79 86
241 magenta #d33682 5/5 magenta 125 #af005f 50 65 -05 211 54 130 331 74 83
242 violet #6c71c4 13/5 brmagenta 61 #5f5faf 50 15 -45 108 113 196 237 45 77
243 blue #268bd2 4/4 blue 33 #0087ff 55 -10 -45 38 139 210 205 82 82
244 cyan #2aa198 6/6 cyan 37 #00afaf 60 -35 -05 42 161 152 175 74 63
245 green #859900 2/2 green 64 #5f8700 60 -20 65 133 153 0 68 100 60
246
247 License
248 -------
249 Copyright (c) 2011 Ethan Schoonover
250
251 Permission is hereby granted, free of charge, to any person obtaining a copy
252 of this software and associated documentation files (the "Software"), to deal
253 in the Software without restriction, including without limitation the rights
254 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
255 copies of the Software, and to permit persons to whom the Software is
256 furnished to do so, subject to the following conditions:
257
258 The above copyright notice and this permission notice shall be included in
259 all copies or substantial portions of the Software.
260
261 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
262 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
263 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
264 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
265 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
266 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
267 THE SOFTWARE.