ab668eae2855121acd59343e44cb5d512242cbb9
[stack/conf/irssi-colors-solarized.git] / README.mkd
1 Solarized Color Theme for irssi
2 ===============================
3
4 Initially created by Huy Z \<huy-git-pub circled-a huyzing.com\>, this is a
5 repository of themes for the [irssi] IRC chat client that support Ethan
6 Schoonover’s [Solarized] color scheme.
7
8 ![Solarized Dark main screenshot](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-irssi-main-in-iTerm-solarized-dark.png)
9
10 [irssi]:                http://www.irssi.org/
11 [Solarized]:            http://ethanschoonover.com/solarized
12
13 Visit the Solarized homepage
14 ----------------------------
15
16 See the [Solarized] homepage for screenshots, details and color theme
17 implementations for terminal emulators and other applications, such as Vim,
18 Emacs, and Mutt.
19
20 Understanding Solarized Colors in Terminals
21 -------------------------------------------
22
23 ### Solarized Colors vs. ANSI Colors ###
24
25 8-color terminal programs such as irssi use color codes that correspond to the
26 expected 8 normal ANSI colors.  irssi additionally supports bold, which
27 terminal emulators will usually display by using the *bright* versions of the 8
28 ANSI colors and/or by using a bold typeface with a heavier weight. (Note that
29 different terminal emulators may have slightly different ideas of what color
30 values to use when displaying the 16 [ANSI color escape
31 codes](http://en.wikipedia.org/wiki/ANSI_escape_code#Colors).)
32
33 In order to be displayed by 8-color terminal programs, which cannot specify RGB
34 values, Solarized must replace the default ANSI colors.  Since the Solarized
35 palette uses 16 colors, not only must this color scheme replace the 8 normal
36 colors but must also take over the 8 *bright* colors, for a total of 16 colors.
37 This means that a Solarized terminal application loses the ability to bold text
38 but gains 8 more Solarized colors.
39
40 About half of the Solarized palette is reminiscent of the original ANSI
41 colors, e.g. Solarized red is close to ANSI red (or more precisely, the
42 general consensus of what ANSI red should look like).  But the rest of the
43 Solarized colors do not correspond to any ANSI colors, e.g. there is no ANSI
44 color that corresponds to Solarized orange or purple.
45
46 This means that, for example, if the irssi theme wants to display "green", a
47 Solarized terminal will display something close to green, but if the theme
48 wants to display "bold yellow" or "bright yellow", a Solarized terminal will
49 not be able to display it.  However, a Solarized theme will be able to display
50 the new colors orange and purple and also several shades of gray.  This is
51 again thanks to the replacement of the ANSI *bright* colors; e.g. ANSI "bold
52 red", which is usually displayed as "bright red", will now show as Solarized
53 orange, while ANSI "bold blue", which is usually displayed as "bright blue",
54 will now be a shade of gray.
55
56 ### Terminal Emulator ###
57
58 Because irssi is an ANSI 8-color terminal program, it is entirely dependent on
59 the terminal emulator for the display of its colors.  You cannot directly tell
60 an irssi theme to display Solarized orange, e.g. by specifying an RGB value.
61 Instead, the theme's colors must be chosen using the ANSI color codes with the
62 expectation that the terminal emulator will display them as appropriate
63 Solarized colors.  For example, the irssi color format `%R` which normally
64 would be "bold red" is expected to be displayed by the terminal emulator as
65 Solarized orange.
66
67 So in order for irssi to display the Solarized palette, you have to set your
68 Terminal emulator's color settings to the Solarized palette. The [Solarized
69 repository] includes theme settings for some popular terminal emulators as
70 well as Xdefaults; or you can download them from the official [Solarized]
71 homepage. If you use the irssi themes *without* having changed your
72 emulator's palette, you will get a strange selection of colors that may be
73 hard to read.
74
75 Yes, this means that, to use the Solarized theme for irssi, you need to change
76 color settings for not one but two different programs: your terminal emulator
77 and irssi.  The two sets of settings will work in concert to display Solarized
78 colors appropriately.
79
80 ### Bold Settings ###
81
82 Historically, there has been a one-to-one correspondence between the bolded
83 versions of the 8 default ANSI colors and the bright versions of the 8 default
84 colors.  Back in the day, when a color program demanded the display of bold
85 text, it was probably just easier for terminal emulators to display a brighter
86 version of whatever color the text was (and expect the user to interpret that
87 as bold) than to display a typeface with a bold weight
88
89 Nowadays, it is easy for terminal emulators to display bold typefaces, so it
90 doesn't make sense for bolded text to change color, but the confusing
91 association remains. In fact, new terminal emulators allow users to break the
92 correspondence between bold and bright and can simply change the font.
93
94 However, ANSI 8-color terminal applications such as irssi only have a
95 conception of bold and don't know about the possibility of using up to 16
96 colors.  So to use all 16 Solarized colors, we change the semantics of "bold"
97 in the theme to mean that we want to access the 8 new Solarized colors,
98 including the grays. Recall the example above, where we described that the
99 irssi color format `%R`, which would have normally displayed bold red, is
100 expected to show up as Solarized orange.
101
102 This is why it is important to *not* break the association between bold and
103 bright colors. Many terminal emulators offer an option to disable the use of
104 bright colors for bold, and you must not do so.  Often, new users of Solarized
105 will be confused when they change their terminal emulator's color palette to
106 Solarized but haven't yet installed Solarized-specific color themes for all
107 their terminal applications (e.g. mutt, ls's dircolors, irssi, and their
108 colorized shell prompts).  They will see texts that are hard to read or
109 disappear entirely.  The solution isn't to disable bright colors; the solution
110 is to install Solarized color themes for all terminal applications and then you
111 will have all 16 colors.
112
113 Also, because the semantics of "bold" are lost in favor of more colors, it
114 also makes sense to disable the display of bold text as a bold typeface.  It
115 won't hurt to see bold typefaces wherever the new 8 Solarized colors are
116 displayed but it doesn't make much sense anymore.
117
118 Universal theme
119 ---------------
120
121 The first irssi theme, called "universal", was designed to work best with both
122 Solarized Dark and Light palettes, but also to work under default terminal
123 colors. In other words, this theme was designed with a "fallback" scenario: if
124 you happen to find yourself on a terminal where the Solarized palette has not
125 been set up, you won't have elements become invisible or incrediby hard to
126 read.
127
128 Thus, this theme has been designed with these 4 palettes in mind:
129
130 -   Solarized Dark: "universal" works best with this scheme
131 -   Solarized Light: "universal" works with this scheme almost as well as with
132     Solarized Dark (you probably won't notice the difference, but if you do, it
133     could be optimized slightly by switching the theme's use of some of the
134     Solarized base colors)
135 -   Default dark-background terminal colors
136 -   Default light-background terminal colors
137
138 This theme was designed to be clean and functional, starting from the default
139 theme distributed with irssi.  Colors are strictly used for functionality and
140 the number of colors visible is minimized when possible. Colors were selected
141 based on the characteristics of the text characters to be displayed:
142
143 -   Visibility generally follows importance, with an attempt to let unimportant
144     text fade into the background (which is not always possible when
145     simultaneously supporting dark and light backgrounds)
146 -   Loud colors are chosen to call attention to noteworthy messages
147
148 ### Supported Scripts ###
149
150 The following third-party scripts are supported:
151
152 -   [adv\_windowlist.pl](http://anti.teamidiot.de/static/nei/*/Code/Irssi/)
153 -   [usercount.pl](http://scripts.irssi.org/html/usercount.pl.html)
154 -   [trackbar.pl](http://scripts.irssi.org/html/trackbar.pl.html)
155
156 ### Screenshots ###
157
158 This is how the "universal" theme for irssi looks under different palettes.
159 Click images to see screenshots.
160
161 Solarized Dark (this example uses iTerm2 on OS X):
162
163 [![Solarized Dark](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-irssi-in-iTerm2-solarized_dark-th.png)](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-irssi-in-iTerm2-solarized\_dark.png)
164
165 Solarized Light (this example uses iTerm2 on OS X):
166
167 [![Solarized Light](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-irssi-in-iTerm2-solarized_light-th.png)](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-irssi-in-iTerm2-solarized\_light.png)
168
169 Default dark terminal colors (this example uses Apple's Terminal.app on OS X):
170
171 [![default dark](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-irssi-in-Terminal.app-dark-th.png)](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-irssi-in-Terminal.app-dark.png)
172
173 Default light terminal colors (this example uses iTerm on OS X):
174
175 [![default light](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-irssi-in-iTerm-light-th.png)](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-irssi-in-iTerm-light.png)
176
177 Downloads
178 ---------
179
180 If you have come across these themes via the [irssi-only repository] on github,
181 you may want to check the main [Solarized repository] to see if there is an
182 official theme.
183
184 At some point, the [irssi-only repository] may be kept in sync with the main
185 [Solarized repository] and would then only be preserved separately for
186 installation convenience only. At this time, issues, bug reports, changelogs
187 are to be reported at the [irssi-only repository].
188
189 [Solarized repository]:  https://github.com/altercation/solarized
190 [irssi-only repository]: https://github.com/huyz/irssi-colors-solarized
191
192
193 Installation
194 ------------
195
196 1.  Make sure that you have changed your terminal emulator's color settings to
197     the Solarized palette.  (See the section "Understanding Solarized Colors in
198     Terminals" for an explanation.)
199
200     1.  Make sure that bold text is displayed using bright colors. For example,
201         -   For iTerm2 on OS X, this means that Text Preferences must have the `Draw
202             bold text in bright colors` checkbox *selected*.
203         -   For Apple's Terminal.app on OS X, this means that Text Settings must
204             have the `Use bright colors for bold text` checkbox *selected*.
205
206     2.  It's recommended to turn off the display of bold typeface for bold
207         text.  For example,
208         -   For iTerm2 on OS X, this means that Text Preferences should have the
209             `Draw bold text in bold font` checkbox *unselected*.
210         -   For Apple's Terminal.app on OS X, this means that Text Settings
211             should have the `Use bold fonts` checkbox *unselected*.
212         -   For XTerm, this may mean setting the `font` and `boldFont` to be the
213             same in your .Xresources or .Xdefaults, e.g.:
214
215                 xterm*font: fixed
216                 xterm*boldFont: fixed
217
218     Example: for iTerm2, these are the correct settings:
219
220     ![iTerm bold settings](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-iTerm2-bold-options.png)
221
222 2.  Obtain `solarized-universal.theme`
223
224     a) Option A: Download `solarized-universal.theme` from [irssi-only repository]
225        and place it in your `~/.irssi` directory
226
227     b) Option B: To always have the latest version, clone the git repository:
228
229         $ git clone git://github.com/huyz/irssi-colors-solarized.git
230         $ ln -s $PWD/irssi-colors-solarized/solarized-universal.theme ~/.irssi/.
231
232 3.  Change your `~/.irssi/config` to include the following settings, while making
233     sure to replace `YOUR_NICKNAME` with your IRC nickname:
234
235         settings = {
236             ...
237             "fe-common/core" = {
238                 ...
239                 # Solarized
240                 theme = "solarized-universal";
241                 hilight_color = "= %R";
242             };
243             ...
244         };
245         hilights = (
246                 { text = "YOUR_NICKNAME"; color = "%M"; nick = "yes"; word = "yes"; }
247         );
248         statusbar = {
249             ...
250             items = {
251                 ...
252                 # Solarized
253                 lag = "{sb Lag: %m$0-%n}";
254                 act = "{sb Act: $0-}";
255                 more = "%k%3-- more --%n";
256             };
257             ...
258         };
259
260 4.  Optionally, if you have the `adv_windowlist.pl` or `trackbar.pl` scripts
261     installed, modify your `~/.irssi/config` so that:
262
263         settings = {
264             ...
265             "perl/core/scripts" = {
266                 ...
267                 ### For Solarized adv_windowlist.pl script
268                 awl_display_key_active = "%k%2[$Q=$N:$C]%n";
269                 awl_display_nokey_active = "%k%2[$N:$C]%n";
270                 awl_display_key = "[$Q:$H$C$S]";
271                 awl_display_nokey = "[$N:$H$C$S]";
272         
273                 ### For Solarized trackbar.pl script
274                 trackbar_style = "%B";
275             };
276             ...
277         };
278
279
280
281 The Solarized Color Values
282 --------------------------
283
284 L\*a\*b values are canonical (White D65, Reference D50), other values are
285 matched in sRGB space.
286
287     SOLARIZED HEX     16/8 TERMCOL  XTERM/HEX   L*A*B      sRGB        HSB
288     --------- ------- ---- -------  ----------- ---------- ----------- -----------
289     base03    #002b36  8/4 brblack  234 #1c1c1c 15 -12 -12   0  43  54 193 100  21
290     base02    #073642  0/4 black    235 #262626 20 -12 -12   7  54  66 192  90  26
291     base01    #586e75 10/7 brgreen  240 #4e4e4e 45 -07 -07  88 110 117 194  25  46
292     base00    #657b83 11/7 bryellow 241 #585858 50 -07 -07 101 123 131 195  23  51
293     base0     #839496 12/6 brblue   244 #808080 60 -06 -03 131 148 150 186  13  59
294     base1     #93a1a1 14/4 brcyan   245 #8a8a8a 65 -05 -02 147 161 161 180   9  63
295     base2     #eee8d5  7/7 white    254 #d7d7af 92 -00  10 238 232 213  44  11  93
296     base3     #fdf6e3 15/7 brwhite  230 #ffffd7 97  00  10 253 246 227  44  10  99
297     yellow    #b58900  3/3 yellow   136 #af8700 60  10  65 181 137   0  45 100  71
298     orange    #cb4b16  9/3 brred    166 #d75f00 50  50  55 203  75  22  18  89  80
299     red       #dc322f  1/1 red      160 #d70000 50  65  45 220  50  47   1  79  86
300     magenta   #d33682  5/5 magenta  125 #af005f 50  65 -05 211  54 130 331  74  83
301     violet    #6c71c4 13/5 brmagenta 61 #5f5faf 50  15 -45 108 113 196 237  45  77
302     blue      #268bd2  4/4 blue      33 #0087ff 55 -10 -45  38 139 210 205  82  82
303     cyan      #2aa198  6/6 cyan      37 #00afaf 60 -35 -05  42 161 152 175  74  63
304     green     #859900  2/2 green     64 #5f8700 60 -20  65 133 153   0  68 100  60