lotsa changes and inclusion of elpy
[emacs.git] / .emacs.d / elisp / emacs-color-theme-solarized / README.md
1 Solarized Colorscheme for Emacs
2 ===============================
3
4 Stolen from Ethan Schoonover <es@ethanschoonover.com> by Greg Pfeil <greg@technomadic.org>
5
6 Visit the [Solarized homepage]
7 ------------------------------
8
9 See the [Solarized homepage] for screenshots,
10 details and colorscheme versions for Vim, Mutt, popular terminal emulators and
11 other applications.
12
13 Screenshots
14 -----------
15
16 ![solarized dark](https://github.com/altercation/solarized/raw/master/img/solarized-vim.png)
17
18 Downloads
19 ---------
20
21 If you have come across this colorscheme via the [Emacs-only repository] on
22 github, see the link above to the Solarized homepage or visit the main [Solarized repository].
23
24 The [Emacs-only repository] is kept in sync with the main [Solarized repository]. Issues, bug reports, changelogs that are not specific to the Emacs implementation should be submitted to the main [Solarized repository].
25
26 [Solarized homepage]: http://ethanschoonover.com/solarized
27 [Solarized repository]: https://github.com/altercation/solarized
28 [Emacs-only repository]: https://github.com/sellout/emacs-color-theme-solarized
29 [color-theme]: http://www.nongnu.org/color-theme
30
31 Installation & Usage
32 --------------------
33
34 ### Emacs 24
35
36 1. Add the `emacs-color-theme-solarized` directory to your Emacs `custom-theme-load-path`, or install from marmalade using `package-install color-theme-solarized`
37 2. Add `(load-theme 'solarized-[light|dark] t)` to your Emacs init file.
38 3. Reload the init file, or restart Emacs.
39
40 ### [color-theme] \(pre-Emacs 24\)
41
42 1. Download and install [color-theme].
43 2. Add the `emacs-color-theme-solarized` directory to your Emacs `load-path`.
44 3. Add `(require 'color-theme-solarized)` to your Emacs init file (usually `~/.emacs`).
45 3. Reload the init file, or restart Emacs.
46 4. Use the usual [color-theme] mechanism to select one of the Solarized themes, or `M-x color-theme-solarized-[light|dark]`.
47
48 ### IMPORTANT NOTE FOR TERMINAL USERS:
49
50 If you are going to use Solarized in Terminal mode (i.e. not in a GUI version
51 like Cocoa or X11 Emacs), **please please please** consider setting your
52 terminal emulator's colorscheme to use the Solarized palette. The [Solarized
53 repository] includes palettes for some popular terminal emulator as well as
54 Xdefaults; or you can download them from the official [Solarized homepage].
55 If you use this emacs color theme *without* having changed your emulator's
56 palette, you will need to configure Solarized to degrade its colorscheme to
57 a set compatible with the terminal's default limited 256 color palette
58 (whereas by using the terminal's 16 ANSI color values, you would
59 see the correct, specific values for the Solarized palette).
60
61 If you do use the custom terminal colors, i.e. the 16 overridden ANSI color
62 values, the emacs colorscheme should work out of the box for you. If you are
63 using a terminal emulator that supports 256 colors and don't want to use
64 the custom Solarized terminal colors, you will need to use the degraded 256
65 colorscheme. To do so, simply customize the `solarized-termcolor` variable to
66 `256`.
67
68 Again, I recommend just changing your terminal colors to Solarized values
69 either manually or via one of the many terminal schemes available for import.
70
71 Advanced Configuration
72 ----------------------
73
74 Solarized will work out of the box with just the instructions specified above
75 but does include several variables that can be customized.
76
77 variable name default optional
78 --------------------------------------------
79 solarized-termcolors = 16 | 256
80 solarized-degrade = nil | t
81 solarized-bold = t | nil
82 solarized-underline = t | nil
83 solarized-italic = t | nil
84 solarized-contrast = normal| high, low
85 solarized-visibility = normal| high, low
86 solarized-broken-srgb= nil | t (see details for Mac behavior)
87 --------------------------------------------
88
89 ### Option Details
90
91 * solarized-termcolors
92
93 This is set to *16* by default, meaning that Solarized will attempt to use
94 the standard 16 colors of your terminal emulator, assuming that you've set
95 these colors to the correct Solarized values either manually or by
96 importing one of the many colorscheme available for popular terminal
97 emulators and Xdefaults.
98 If you don't want to use the Solarized colors via the terminal
99 emulator's palette, you can set this to *256*, which will use a degraded
100 version of the Solarized palette by displaying the closest colors in
101 the terminal's default 256 colors as shown in [Xterm's color
102 chart](http://en.wikipedia.org/wiki/File:Xterm_color_chart.png).
103
104 * solarized-degrade
105
106 For test purposes only; in GUI mode, this forces Solarized to use the 256
107 degraded color mode to test the approximate color values for accuracy.
108
109 * solarized-bold | solarized-underline | solarized-italic
110
111 If you wish to stop Solarized from displaying bold, underlined or
112 italicized typefaces, simply set the appropriate variable to `nil`.
113
114 * solarized-contrast
115
116 Stick with normal! It's been carefully tested. Setting this option to high
117 or low does use the same Solarized palette but simply shifts some values
118 up or down in order to expand or compress the tonal range displayed.
119
120 * solarized-visibility
121
122 Special characters such as trailing whitespace, tabs, newlines, when
123 displayed using `:set list` can be set to one of three levels depending on
124 your needs. Default value is `normal` with `high` and `low` options.
125
126 * solarized-broken-srgb
127
128 Emacs [bug #8402](http://debbugs.gnu.org/cgi/bugreport.cgi?bug=8402)
129 results in incorrect color handling on Macs. If this is `t` (the default
130 on Macs), Solarized works around it with alternative colors. However,
131 these colors are not totally portable, so you may be able to edit the
132 "Gen RGB" column in `solarized-definitions.el` to improve them further.
133
134 Code Notes
135 ----------
136
137 I have attempted to modularize the creation of Emacs colorschemes in this script and, while it could be refactored further, it should be a good foundation for the creation of any color scheme. By simply changing the values in the `solarized-colors` table in `solarized-definitions.el` and testing in a GUI Emacs, you can rapidly prototype new colorschemes without diving into the weeds of line-item editing each syntax highlight declaration.
138
139 The Values
140 ----------
141
142 L\*a\*b values are canonical (White D65, Reference D50), other values are
143 matched in sRGB space.
144
145 SOLARIZED HEX 16/8 TERMCOL XTERM/HEX L*A*B RGB HSB
146 --------- ------- ---- ------- ----------- ---------- ----------- -----------
147 base03 #002b36 8/4 brblack 234 #1c1c1c 15 -12 -12 0 43 54 193 100 21
148 base02 #073642 0/4 black 235 #262626 20 -12 -12 7 54 66 192 90 26
149 base01 #586e75 10/7 brgreen 240 #585858 45 -07 -07 88 110 117 194 25 46
150 base00 #657b83 11/7 bryellow 241 #626262 50 -07 -07 101 123 131 195 23 51
151 base0 #839496 12/6 brblue 244 #808080 60 -06 -03 131 148 150 186 13 59
152 base1 #93a1a1 14/4 brcyan 245 #8a8a8a 65 -05 -02 147 161 161 180 9 63
153 base2 #eee8d5 7/7 white 254 #e4e4e4 92 -00 10 238 232 213 44 11 93
154 base3 #fdf6e3 15/7 brwhite 230 #ffffd7 97 00 10 253 246 227 44 10 99
155 yellow #b58900 3/3 yellow 136 #af8700 60 10 65 181 137 0 45 100 71
156 orange #cb4b16 9/3 brred 166 #d75f00 50 50 55 203 75 22 18 89 80
157 red #dc322f 1/1 red 160 #d70000 50 65 45 220 50 47 1 79 86
158 magenta #d33682 5/5 magenta 125 #af005f 50 65 -05 211 54 130 331 74 83
159 violet #6c71c4 13/5 brmagenta 61 #5f5faf 50 15 -45 108 113 196 237 45 77
160 blue #268bd2 4/4 blue 33 #0087ff 55 -10 -45 38 139 210 205 82 82
161 cyan #2aa198 6/6 cyan 37 #00afaf 60 -35 -05 42 161 152 175 74 63
162 green #859900 2/2 green 64 #5f8700 60 -20 65 133 153 0 68 100 60
163
164 ### Bug Reporting
165
166 Here are some things to keep in mind when submitting a bug report:
167
168 * include the output of `M-x version` in your report,
169 * mention whether you’re using color-theme or the Emacs 24 theme,
170 * include the names of Emacs faces that you have a problem with (`M-x describe-face` will tell you the name of the face at point),
171 * screenshots are very helpful (before and after if you made a change),
172 * it’s very helpful (but not expected) if you can compare it to a similar situation in VIM (especially if you know the VIM highlight name or have a screenshot), and
173 * `M-x customize-apropos-faces` can help you find all the relevant faces if you are submitting faces for a mode.