git.r.bdr.sh - rbdr/dotfiles/blob - vim/doc/solarized.txt

   1 *solarized.vim* for Vim version 7.3 or newer. Modified: 2011 May 05
   2
   3
   4                 Solarized Vim Colorscheme by Ethan Schoonover ~
   5
   6 Solarized Colorscheme                                      *solarized*
   7                                                            *solarized-help*
   8                                                            *solarized-colors*
   9                                                            *solarized-colorscheme*
  10                                                            *vim-colors-solarized*
  11
  12 Solarized is a carefully designed selective contrast colorscheme with dual
  13 light and dark modes that runs in both GUI, 256 and 16 color modes.
  14
  15 See the homepage at http://ethanschoonover.com/solarized for screenshots and
  16 details.
  17
  18 0. Install                              |solarized-install|
  19 1. Solarized Menu                       |solarized-menu|
  20 2. Options                              |solarized-options|
  21 3. Toggle Background                    |solarized-togglebg|
  22 4. Terminal Issues                      |solarized-term|
  23
  24 ==============================================================================
  25 0. Install                                              *solarized-install*
  26
  27 Note: I recommend using Tim Pope's pathogen plugin to install this
  28 colorscheme. See https://github.com/tpope/vim-pathogen . If you've installed
  29 pathogen properly you can install Solarized with the following commands,
  30 followed by the .vimrc configuration below.
  31
  32         $ cd ~/.vim/bundle
  33         $ git clone https://github.com/altercation/vim-colors-solarized.git
  34
  35 If you aren't using pathogen, you can use the following three steps to install
  36 Solarized:
  37
  38 1.  Download the solarized distribution (available on the homepage above)
  39     and unarchive the file.
  40
  41 2.  Move `solarized.vim` to your `.vim/colors` directory.
  42
  43 3.  Move each of the files in each subdirectories to the corresponding .vim
  44     subdirectory (e.g. autoload/togglebg.vim goes into your .vim/autoload
  45     directory as .vim/autoload/togglebg.vim).
  46
  47
  48 After installation, place the following lines in your .vimrc:
  49
  50         syntax enable
  51         set background=dark
  52         colorscheme solarized
  53
  54 or, for the light background mode of Solarized:
  55
  56         syntax enable
  57         set background=light
  58         colorscheme solarized
  59
  60 ==============================================================================
  61 1. Solarized Menu                                       *solarized-menu*
  62
  63 Solarized makes available a menu when used in Vim GUI mode (gvim, macvim).
  64 This menu includes many of the options detailed below so that you can test out
  65 different values quickly without modifying your .vimrc file. If you wish to
  66 turn off this menu permanently, simply place the following line in your .vimrc
  67 above the "colorscheme solarized" line.
  68
  69         let g:solarized_menu=0
  70
  71 ==============================================================================
  72 2. Toggle Background                                    *solarized-togglebg*
  73                                                         *toggle-bg* *togglebg*
  74                                                         *toggle-background*
  75
  76 Solarized comes with Toggle Background, a simple plugin to switch between
  77 light and dark background modes and reset the colorscheme. This is most useful
  78 for colorschemes that support both light and dark modes and in terminals or
  79 gui vim windows where the background will be properly set.
  80
  81 Toggle Background can be accessed by:
  82
  83     * the Solarized menu (in Vim gui mode)
  84     * the Window menu (in Vim gui mode, even if the Solarized menu is off)
  85     * the "yin/yang" toolbar button (in Vim gui mode)
  86     * the default mapping of <F5>
  87     * custom key mapping you set in your .vimrc (see below)
  88     * command line via ":ToggleBG" (no quotes)
  89
  90 Toggle Background starts with a default mapping to function key <F5>. If you
  91 are already using this in a mapping, Toggle Background will not map itself to
  92 a default and you will have to map it manually in your .vimrc file, or
  93 remove/change your existing <F5> mapping to another value. To customize the
  94 keyboard mapping in your .vimrc file, use the following line, changing the
  95 "<F5>" value to the key or key combination you wish to use:
  96
  97         call togglebg#map("<F5>")
  98
  99 Note that you'll want to use a single function key or equivalent if you want
 100 the plugin to work in all modes (normal, insert, visual).
 101
 102 When using the plugin during normal, visual, or insert mode, there should be
 103 no interruption in workflow. However, if you activate the plugin during
 104 REPLACE mode, you will switch to standard insert mode (you will leave the
 105 overwrite replace mode).
 106
 107 ==============================================================================
 108 3. Solarized Terminal Issues                            *solarized-term*
 109
 110 If you are going to use Solarized in Terminal mode (i.e. not in a GUI version
 111 like gvim or macvim), **please please please** consider setting your terminal
 112 emulator's colorscheme to used the Solarized palette. I've included palettes
 113 for some popular terminal emulator as well as Xdefaults in the official
 114 Solarized download available from the Solarized homepage listed at the top of
 115 this help document. If you use Solarized *without* these colors, Solarized
 116 will need to be told to degrade its colorscheme to a set compatible with the
 117 limited 256 terminal palette (whereas by using the terminal's 16 ansi color
 118 values, you can set the correct, specific values for the Solarized palette).
 119
 120 If you do use the custom terminal colors, solarized.vim should work out of
 121 the box for you. If you are using a terminal emulator that supports 256
 122 colors and don't want to use the custom Solarized terminal colors, you will
 123 need to use the degraded 256 colorscheme. To do so, simply add the following
 124 line *before* the `colorschem solarized` line:
 125
 126     let g:solarized_termcolors=256
 127
 128 Again, I recommend just changing your terminal colors to Solarized values
 129 either manually or via one of the many terminal schemes available for import.
 130
 131 ==============================================================================
 132 4. Solarized Options                                    *solarized-options*
 133
 134
 135 AUTOGENERATE OPTIONS
 136
 137 You can easily modify and experiment with Solarized display options using the
 138 Solarized menu when using Vim in gui mode. Once you have things set to your
 139 liking, you can autogenerate the current option list in a format ready for
 140 insertion into your .vimrc file using the Solarized menu "Autogenerate
 141 Options" command or at the command line with:
 142
 143     :SolarizedOptions
 144
 145
 146 OPTION LIST
 147
 148 Set these in your vimrc file prior to calling the colorscheme.
 149
 150 option name               default     optional
 151 ------------------------------------------------
 152 g:solarized_termcolors=   16      |   256
 153 g:solarized_termtrans =   0       |   1
 154 g:solarized_degrade   =   0       |   1
 155 g:solarized_bold      =   1       |   0
 156 g:solarized_underline =   1       |   0
 157 g:solarized_italic    =   1       |   0
 158 g:solarized_contrast  =   "normal"|   "high" or "low"
 159 g:solarized_visibility=   "normal"|   "high" or "low"
 160 g:solarized_hitrail   =   0       |   1
 161 g:solarized_menu      =   1       |   0
 162 ------------------------------------------------
 163
 164
 165 OPTION DETAILS
 166
 167 ------------------------------------------------
 168 g:solarized_termcolors=   256     |   16                *'solarized_termcolors'*
 169 ------------------------------------------------
 170 The most important option if you are using vim in terminal (non gui) mode!
 171 This tells Solarized to use the 256 degraded color mode if running in a 256
 172 color capable terminal.  Otherwise, if set to `16` it will use the terminal
 173 emulators colorscheme (best option as long as you've set the emulators colors
 174 to the Solarized palette).
 175
 176 If you are going to use Solarized in Terminal mode (i.e. not in a GUI
 177 version like gvim or macvim), **please please please** consider setting your
 178 terminal emulator's colorscheme to used the Solarized palette. I've included
 179 palettes for some popular terminal emulator as well as Xdefaults in the
 180 official Solarized download available from:
 181 http://ethanschoonover.com/solarized . If you use Solarized without these
 182 colors, Solarized will by default use an approximate set of 256 colors.  It
 183 isn't bad looking and has been extensively tweaked, but it's still not quite
 184 the real thing.
 185
 186 ------------------------------------------------
 187 g:solarized_termtrans =   0       |   1                 *'solarized_termtrans'*
 188 ------------------------------------------------
 189 If you use a terminal emulator with a transparent background and Solarized
 190 isn't displaying the background color transparently, set this to 1 and
 191 Solarized will use the default (transparent) background of the terminal
 192 emulator. *urxvt* required this in my testing; iTerm2 did not.
 193
 194 Note that on Mac OS X Terminal.app, solarized_termtrans is set to 1 by
 195 default as this is almost always the best option. The only exception to this
 196 is if the working terminfo file supports 256 colors (xterm-256color).
 197
 198 ------------------------------------------------
 199 g:solarized_degrade   =   0       |   1                 *'solarized_degrade'*
 200 ------------------------------------------------
 201 For test purposes only; forces Solarized to use the 256 degraded color mode
 202 to test the approximate color values for accuracy.
 203
 204 ------------------------------------------------
 205 g:solarized_bold      =   1       |   0                 *'solarized_bold'*
 206 ------------------------------------------------
 207 ------------------------------------------------
 208 g:solarized_underline =   1       |   0                 *'solarized_underline'*
 209 ------------------------------------------------
 210 ------------------------------------------------
 211 g:solarized_italic    =   1       |   0                 *'solarized_italic'*
 212 ------------------------------------------------
 213 If you wish to stop Solarized from displaying bold, underlined or
 214 italicized typefaces, simply assign a zero value to the appropriate
 215 variable, for example: `let g:solarized_italic=0`
 216
 217 ------------------------------------------------
 218 g:solarized_contrast  =   "normal"|   "high" or "low"   *'solarized_contrast'*
 219 ------------------------------------------------
 220 Stick with normal! It's been carefully tested. Setting this option to high
 221 or low does use the same Solarized palette but simply shifts some values up
 222 or down in order to expand or compress the tonal range displayed.
 223
 224 ------------------------------------------------
 225 g:solarized_visibility =  "normal"|   "high" or "low" *'solarized_visibility'*
 226 ------------------------------------------------
 227 Special characters such as trailing whitespace, tabs, newlines, when
 228 displayed using ":set list" can be set to one of three levels depending on
 229 your needs.
 230
 231 ------------------------------------------------
 232 g:solarized_hitrail   =   0       |   1                 *'solarized_hitrail'*
 233 ------------------------------------------------
 234 Visibility can make listchar entities more visible, but if one has set
 235 cursorline on, these same listchar values standout somewhat less due to the
 236 background color of the cursorline. g:solarized_hitrail enables highlighting
 237 of trailing spaces (only one of the listchar types, but a particularly
 238 important one) while in the cursoline in a different manner in order to make
 239 them more visible. This may not work consistently as Solarized is using
 240 a pattern match than can be overridden by a more encompassing syntax-native
 241 match such as a comment line.
 242
 243
 244 ------------------------------------------------
 245 g:solarized_menu       =  1       |   0                 *'solarized_menu'*
 246 ------------------------------------------------
 247 Solarized includes a menu providing access to several of the above
 248 display related options, including contrast and visibility. This allows
 249 for an easy method of testing different values quickly before settling
 250 on a final assignment for your .vimrc. If you wish to turn off this menu,
 251 assign g:solarized_menu a value of 0.
 252
 253
 254  vim:tw=78:noet:ts=8:ft=help:norl: