nick hilight more visible
[stack/conf/irssi-colors-solarized.git] / README.mkd
index ab668ea..deff53b 100644 (file)
@@ -1,7 +1,7 @@
 Solarized Color Theme for irssi
 ===============================
 
-Initially created by Huy Z \<huy-git-pub circled-a huyzing.com\>, this is a
+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.
 
@@ -17,104 +17,6 @@ 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 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.
-
-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
 ---------------
 
@@ -125,15 +27,16 @@ 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:
+Thus, this theme was designed with these 4 palettes in mind:
 
--   Solarized Dark: "universal" works best with this scheme
--   Solarized Light: "universal" works with 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 dark-background terminal colors
--   Default light-background terminal colors
+-   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
@@ -181,10 +84,12 @@ 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 [irssi-only repository].
+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
@@ -193,17 +98,19 @@ are to be reported at the [irssi-only repository].
 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.  Configure your terminal emulator (See the section "Understanding Solarized Colors in
+    Terminals" for a detailed explanation behind these settings)
 
-    1.  Make sure that bold text is displayed using bright colors. For example,
+    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*.
 
-    2.  It's recommended to turn off the display of bold typeface for bold
+    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*.
@@ -276,6 +183,103 @@ Installation
             ...
         };
 
+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 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.
+
+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 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.
+
+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.
 
 
 The Solarized Color Values