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