X-Git-Url: https://v.licheni.net/stack/conf/irssi-colors-solarized.git/blobdiff_plain/bd868582a9be456f8a1709b5bfe835fd0626b7ac..cf11022c98ab6035d9d76738cbd8484a542e6fdc:/README.mkd diff --git a/README.mkd b/README.mkd new file mode 100644 index 0000000..eea7a3e --- /dev/null +++ b/README.mkd @@ -0,0 +1,304 @@ +Solarized Color Theme for irsii +=============================== + +Initially created by Huy Z , this is a +repository of themes for the [irssi] IRC chat client that support the +[Solarized] color scheme. + +[irssi]: http://www.irssi.org/ +[Solarized]: http://ethanschoonover.com/solarized + +Visit the Solarized homepage +---------------------------- + +See the [Solarized] homepage for screenshots, details and color theme +implementations for terminal emulators and other applications, such as Vim, +Emacs, and Mutt. + +Understanding Solarized Colors in Terminals +------------------------------------------- + +### Solarized Colors vs. ANSI Colors ### + +8-color terminal programs such as irssi use color codes that correspond to the +expected 8 normal ANSI colors. irssi additionally supports bold, which +terminal emulators will usually display by using the *bright* versions of the 8 +ANSI colors and/or by using a bold typeface with a heavier weight. (Note that +different terminal emulators may have slightly different ideas of what color +values to use when displaying the 16 [ANSI color escape +codes](http://en.wikipedia.org/wiki/ANSI_escape_code#Colors)].) + +In order to be displayed by 8-color terminal programs, which cannot specify RGB +values, Solarized must replace the default ANSI colors. Since the Solarized +palette uses 16 colors, not only must this color scheme replace the 8 normal +colors but must also take over the 8 bright colors, for a total of 16 colors. +This means that a Solarized terminal application loses the ability to bold text +but gains 8 more Solarized colors. + +About half of the Solarized palette is reminiscent of the original ANSI +colors, e.g. Solarized red is close to ANSI red (or more precisley, the +general consensus of what ANSI red should look like). But the rest of the +Solarized colors do not correspond to any ANSI colors, e.g. there is no ANSI +color that corresponds to Solarized orange or purple. + +This means that, for example, if the irssi theme wants to display "green", a +Solarized terminal will display something close to green, but if the theme +wants to display "bold yellow" or "bright yellow", a Solarized terminal will +not be able to display it. However, a Solarized theme will be able to display +the new colors orange and purple and also several shades of gray. This is +again thanks to the replacement of the ANSI **bright** colors; e.g. ANSI "bold +red", which is usually displayed as "bright red", will now show as Solarized +orange, while ANSI "bold blue", which is usually displayed as "bright blue", +will now be a shade of gray. + +### Terminal Emulator ### + +Because irssi is an ANSI 8-color terminal program, it is entirely dependent on +the terminal emulator for the display of its colors. You cannot directly tell +an irssi theme to display Solarized orange, e.g. by specifying an RGB value. +Instead, the theme's colors must be chosen using the ANSI color codes with the +expectation that the terminal emulator will display them as appropriate +Solarized colors. For example, the irssi color format `%R` which normally +would be "bold red" is expected to be displayed by the terminal emulator as +Solarized orange. + +So in order for irssi to display the Solarized palette, you have to set your +Terminal emulator's color settings to the Solarized palette. The [Solarized +repository] includes theme settings for some popular terminal emulators as +well as Xdefaults; or you can download them from the official [Solarized +homepage]. If you use the irssi themes *without* having changed your +emulator's palette, you will get a strange selection of colors that may be +hard to read. + +Yes, this means that, to use the Solarized theme for irssi, you need to change +color settings for not one but two different programs: your terminal emulator +and irssi. The two sets of settings will work in concert to display Solarized +colors appropriately. + +### Bold Settings ### + +Historically, there has been a one-to-one correspondence between the bolded +versions of the 8 default ANSI colors and the bright versions of the 8 default +colors. Back in the day, when a color program demanded the display of bold +text, it was probably just easier for terminal emulators to display a brighter +version of whatever color the text was (and expect the user to interpret that +as bold) than to display a typeface with a bold weight + +Nowadays, it is easy for terminal emulators to display bold typefaces, so it +doesn't make sense for bolded text to change color, but the confusing +association remains. In fact, new terminal emulators allow users to break the +correspondence between bold and bright and can simply change the font. + +However, ANSI 8-color terminal applications such as irssi only have a +conception of bold and don't know about the possibility of using up to 16 +colors. So to use all 16 Solarized colors, we change the semantics of "bold" +in the theme to mean that we want to access the 8 new Solarized colors, +including the grays. Recall the example above, where we described that the +irssi color format `%R`, which would have normally displayed bold red, is +expected to show up as Solarized orange. + +This is why it is important to *not* break the association between bold and +bright colors. Many terminal emulators offer an option to disable the use of +bright colors for bold, and you must not do so. Often, new users of Solarized +will be confused when they change their terminal emulator's color palette to +Solarized but haven't yet installed Solarized-specific color themes for all +their terminal applications (e.g. mutt, ls's dircolors, irssi, and their +colorized shell prompts). They will see texts that are hard to read or +disappear entirely. The solution isn't to disable bright colors; the solution +is to install Solarized color themes for all terminal applications and then you +will have all 16 colors. + +Also, because the semantics of "bold" are lost in favor of more colors, it +also makes sense to disable the display of bold text as a bold typeface. It +won't hurt to see bold typefaces wherever the new 8 Solarized colors are +displayed but it doesn't make much sense anymore. + +Universal theme +--------------- + +The first irssi theme, called "universal", was designed to work best with both +Solarized Dark and Light palettes, but also to work under default terminal +colors. In other words, this theme was designed with a "fallback" scenario: if +you happen to find yourself on a terminal where the Solarized palette has not +been set up, you won't have elements become invisible or incrediby hard to +read. + +Thus, this theme has been designed with these 4 palettes in mind: +- Solarized Dark: "universal" works best with this scheme +- Solarized Light: "universal" works almost as well as Solarized Dark (you + probably won't notice the difference, but if you do, it could be optimized + slightly by switching the theme's use of some of the Solarized base colors) +- Default dark-background terminal colors +- Default light-background terminal colors + +This theme was designed to be clean and functional, starting from the default +theme distributed with irssi. Colors are strictly used for functionality and +the number of colors visible is minimized when possible. Colors were selected +based on the characteristics of the text characters to be displayed: +- Visibility generally follows importance, with an attempt to let unimportant + text fade into the background (which is not always possible when supporting + both dark and light backgrounds) +- Loud colors are chosen to call attention to noteworthy messages + +### Supported Scripts ### + +The following third-party scripts are supported: +- [adv\_windowlist.pl](http://anti.teamidiot.de/static/nei/*/Code/Irssi/) +- [usercount.pl](http://scripts.irssi.org/html/usercount.pl.html) +- [trackbar.pl](http://scripts.irssi.org/html/trackbar.pl.html) + +### Screenshots ### + +This is how the "universal" theme for irssi looks under different palettes. +Click images to see screenshots. + +Solarized Dark (this example uses iTerm2 on OS X) +[](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-irssi-in-iTerm2-solarized_dark.png) + +Solarized Light (this example uses iTerm2 on OS X) +[](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-irssi-in-iTerm2-solarized_light.png) + +Default dark terminal colors (this example uses Apple's Terminal.app on OS X) +[](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-irssi-in-Terminal.app-dark.png) + +Default light terminal colors (this example uses iTerm on OS X) +[](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-irssi-in-iTerm-light.png) + +Downloads +--------- + +If you have come across these themes via the [irssi-only repository] on github, +you may want to check the main [Solarized repository] to see if there is an +official theme. + +At some point, the [irssi-only repository] may be kept in sync with the main +[Solarized repository] and would then only be preserved separately for +installation convenience only. At this time, issues, bug reports, changelogs +are to be reported at the [irsii-only repository]. + +[Solarized repository]: https://github.com/altercation/solarized +[irsii-only repository]: https://github.com/huyz/irssi-colors-solarized + +Installation +------------ + +1. Make sure that you have changed your terminal emulator's color settings to + the Solarized palette. (See the section "Understanding Solarized Colors in + Terminals" for an explanation.) + + 1. Make sure that bold text is displayed using bright colors. For example, + - For iTerm2 on OS X, this means that Text Preferences must have the "Draw + bold text in bright colors" checkbox *selected*. + - For Apple's Terminal.app on OS X, this means that Text Settings must + have the "Use bright colors for bold text" checkbox *selected*. + + 2. It's recommended to turn off the display of bold typeface for bold text. For + example, + - For iTerm on OS X, this means that Text Preferences should have the + "Draw bold text in bold font" checkbox *unselected*. + - For Apple's Terminal.app on OS X, this means that Text Settings + should have the "Use bold fonts" checkbox *unselected*. + +2. Obtain solarized-universal.theme + + a) Option A: Download `solarized-universal.theme` from [irssi-only repository] + and place it in your ~/.irssi directory + + b) Option B: To always have the latest version, clone the git repository: + + $ git clone git://github.com/huyz/irssi-colors-solarized.git + $ ln -s $PWD/irssi-colors-solarized/solarized-universal.theme ~/.irssi/. + +3. Change your `~/.irssi/config` to include the following settings, while making + sure to replace `YOUR_NICKNAME` with your IRC nickname: + + settings = { + ... + "fe-common/core" = { + ... + # Solarized + theme = "solarized-universal"; + hilight_color = "= %R"; + }; + ... + }; + hilights = ( + { text = "YOUR_NICKNAME"; color = "%M"; nick = "yes"; word = "yes"; } + ); + statusbar = { + ... + items = { + ... + # Solarized + lag = "{sb Lag: %m$0-%n}"; + act = "{sb Act: $0-}"; + more = "%k%3-- more --%n"; + }; + ... + }; + +4. Optionally, if you have the `adv_windowlist.pl` or `trackbar.pl` scripts + installed, modify your `~/.irssi/config` so that: + + settings = { + ... + "perl/core/scripts" = { + ... + ### For Solarized adv_windowlist.pl script + awl_display_key_active = "%k%2[$Q=$N:$C]%n"; + awl_display_nokey_active = "%k%2[$N:$C]%n"; + awl_display_key = "[$Q:$H$C$S]"; + awl_display_nokey = "[$N:$H$C$S]"; + + ### For Solarized trackbar.pl script + trackbar_style = "%B"; + }; + ... + }; + +The Solarized Color Values +-------------------------- + +L\*a\*b values are canonical (White D65, Reference D50), other values are +matched in sRGB space. + + SOLARIZED HEX 16/8 TERMCOL XTERM/HEX L*A*B sRGB HSB + --------- ------- ---- ------- ----------- ---------- ----------- ----------- + base03 #002b36 8/4 brblack 234 #1c1c1c 15 -12 -12 0 43 54 193 100 21 + base02 #073642 0/4 black 235 #262626 20 -12 -12 7 54 66 192 90 26 + base01 #586e75 10/7 brgreen 240 #4e4e4e 45 -07 -07 88 110 117 194 25 46 + base00 #657b83 11/7 bryellow 241 #585858 50 -07 -07 101 123 131 195 23 51 + base0 #839496 12/6 brblue 244 #808080 60 -06 -03 131 148 150 186 13 59 + base1 #93a1a1 14/4 brcyan 245 #8a8a8a 65 -05 -02 147 161 161 180 9 63 + base2 #eee8d5 7/7 white 254 #d7d7af 92 -00 10 238 232 213 44 11 93 + base3 #fdf6e3 15/7 brwhite 230 #ffffd7 97 00 10 253 246 227 44 10 99 + yellow #b58900 3/3 yellow 136 #af8700 60 10 65 181 137 0 45 100 71 + orange #cb4b16 9/3 brred 166 #d75f00 50 50 55 203 75 22 18 89 80 + red #dc322f 1/1 red 160 #d70000 50 65 45 220 50 47 1 79 86 + magenta #d33682 5/5 magenta 125 #af005f 50 65 -05 211 54 130 331 74 83 + violet #6c71c4 13/5 brmagenta 61 #5f5faf 50 15 -45 108 113 196 237 45 77 + blue #268bd2 4/4 blue 33 #0087ff 55 -10 -45 38 139 210 205 82 82 + cyan #2aa198 6/6 cyan 37 #00afaf 60 -35 -05 42 161 152 175 74 63 + green #859900 2/2 green 64 #5f8700 60 -20 65 133 153 0 68 100 60 + +License +------- +Copyright (c) 2011 Huy Z + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE.