nick hilight more visible
[stack/conf/irssi-colors-solarized.git] / README.mkd
index eea7a3e..deff53b 100644 (file)
@@ -1,9 +1,11 @@
-Solarized Color Theme for irsii
+Solarized Color Theme for irssi
 ===============================
 
-Initially created by Huy Z <huy-git-pub circled-a huyzing.com>, this is a
-repository of themes for the [irssi] IRC chat client that support the
-[Solarized] color scheme.
+Initially created by [huyz](https://github.com/huyz), this is a
+repository of themes for the [irssi] IRC chat client that support Ethan
+Schoonover’s [Solarized] color scheme.
+
+![Solarized Dark main screenshot](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-irssi-main-in-iTerm-solarized-dark.png)
 
 [irssi]:                http://www.irssi.org/
 [Solarized]:            http://ethanschoonover.com/solarized
@@ -15,6 +17,172 @@ See the [Solarized] homepage for screenshots, details and color theme
 implementations for terminal emulators and other applications, such as Vim,
 Emacs, and Mutt.
 
+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 was designed with these 4 palettes in mind:
+
+-   Solarized Dark: the theme works best when the terminal emulator is
+    set to this scheme
+-   Solarized Light: the theme works, when the terminal emulator is set
+    to this scheme, almost as well as with 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 terminal ANSI Colors with a dark background
+-   Default terminal ANSI Colors with a light background
+
+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
+    simultaneously supporting 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):
+
+[![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)
+
+Solarized Light (this example uses iTerm2 on OS X):
+
+[![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)
+
+Default dark terminal colors (this example uses Apple's Terminal.app on OS X):
+
+[![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)
+
+Default light terminal colors (this example uses iTerm on OS X):
+
+[![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)
+
+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.
+
+In the future, the [irssi-only repository] may be kept in sync with the main
+[Solarized repository], but the [irssi-only repository] may be left separate
+for installation convenience and to include the latest improvements.
+
+At this time, issues, bug reports, changelogs are to be reported at the
+[irssi-only repository].
+
+[Solarized repository]:  https://github.com/altercation/solarized
+[irssi-only repository]: https://github.com/huyz/irssi-colors-solarized
+
+
+Installation
+------------
+
+1.  Configure your terminal emulator (See the section "Understanding Solarized Colors in
+    Terminals" for a detailed explanation behind these settings)
+
+    1.  Make sure that you have changed your terminal emulator's color settings to
+        the Solarized palette.
+
+    2.  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*.
+
+    3.  It's recommended to turn off the display of bold typeface for bold
+        text.  For example,
+        -   For iTerm2 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*.
+        -   For XTerm, this may mean setting the `font` and `boldFont` to be the
+            same in your .Xresources or .Xdefaults, e.g.:
+
+                xterm*font: fixed
+                xterm*boldFont: fixed
+
+    Example: for iTerm2, these are the correct settings:
+
+    ![iTerm bold settings](https://github.com/huyz/irssi-colors-solarized/raw/master/img/screen-iTerm2-bold-options.png)
+
+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";
+            };
+            ...
+        };
+
 Understanding Solarized Colors in Terminals
 -------------------------------------------
 
@@ -26,17 +194,17 @@ 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)].)
+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.
+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
+colors, e.g. Solarized red is close to ANSI red (or more precisely, 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.
@@ -46,7 +214,7 @@ 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
+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.
@@ -65,8 +233,8 @@ 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
+well as Xresources; 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.
 
@@ -113,148 +281,6 @@ 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)
-[<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)
-
-Solarized Light (this example uses iTerm2 on OS X)
-[<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)
-
-Default dark terminal colors (this example uses Apple's Terminal.app on OS X)
-[<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)
-
-Default light terminal colors (this example uses iTerm on OS X)
-[<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)
-
-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
 --------------------------
@@ -280,25 +306,3 @@ matched in sRGB space.
     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.