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