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