diff options
Diffstat (limited to 'shellenv/dircolors-solarized/README.md')
| -rw-r--r-- | shellenv/dircolors-solarized/README.md | 384 |
1 files changed, 384 insertions, 0 deletions
diff --git a/shellenv/dircolors-solarized/README.md b/shellenv/dircolors-solarized/README.md new file mode 100644 index 0000000..388daa6 --- /dev/null +++ b/shellenv/dircolors-solarized/README.md @@ -0,0 +1,384 @@ +<h1>Solarized Color Theme for GNU ls (as setup by GNU dircolors)</h1> + +This is a repository of themes for GNU ls (configured via GNU +dircolors) that support Ethan Schoonover’s [Solarized color +scheme](http://ethanschoonover.com/solarized). + +See the [Solarized homepage](http://ethanschoonover.com/solarized) +for screenshots, details and color theme implementations for terminal +emulators and other applications, such as Vim, Emacs, and Mutt. + +Quick note for MacOS users: Your OS does not use GNU ls, so you can not use +this themes. However, [@logic](https://github.com/logic) provided something +your can use in [this issue](https://github.com/seebi/dircolors-solarized/issues/10). +Another option (as [proposed](https://github.com/seebi/dircolors-solarized/issues/10#issuecomment-2641754) +by [@metamorfos](https://github.com/metamorfos)) is to install GNU ls with +homebrew (coreutils). + +<h2>(Selected) Table of Contents</h2> + +* [Repositories](#repositories) +* [Themes](#themes) + * [Theme #1: "256dark"](#256dark) + * [Theme #2: "ansi-\*"](#ansi) +* [Installation](#installation) +* [Understanding Solarized Colors in Terminals](#understanding-solarized-colors-in-terminals) + +<h2 id="repositories">Repositories</h2> + + * The main Solarized repository: [/altercation/solarized](https://github.com/altercation/solarized) + * These themes as a separate repository: [/seebi/dircolors-solarized](https://github.com/seebi/dircolors-solarized) + +<h2 id="themes">Themes</h2> + +First, note that "256 colors" does not necessarily mean better than "ANSI". +Read on for more details. + +1. "256dark" - Degraded Solarized Dark theme for terminal emulators and + newer dircolors that both support 256 colors. This theme allows for the display + of the *approximate* Solarized palette, but it's very easy to set up and allows + for the use of many more colors beyond the 16 in Solarized. + (By [seebi](https://github.com/seebi)) + + Note: In the future, it may be possible to change the approximate + Solarized colors to the exact Solarized palette; and this theme would + automatically improve. Work on an appropriate .Xresources has not yet + started. (See [256-color remapping discussion](https://github.com/altercation/solarized/issues/8).) + +2. "ansi-universal" - Universal theme for 16-color or 256-color + terminal emulators and any version of dircolors. It is optimized for + Solarized Dark and Light and acceptable with default ANSI colors. This theme allows + for the display of the *exact* Solarized palette, but it requires the reconfiguration + of the terminal emulator's ANSI color settings and limits you to the 16 + Solarized colors. (By [huyz](https://github.com/huyz)) + + "ansi-dark" - Tweaked version of "ansi-universal", slightly more + optimized for the Solarized Dark palette to the slight detriment of the + Solarized Light palette. + + "ansi-light" - Tweaked version of "ansi-universal", slightly more + optimized for the Solarized Light palette to the slight detriment of the + Solarized Dark palette. + +<h3 id="256dark">Theme #1: "256dark" (by <a href="https://github.com/seebi">seebi</a>)</h3> + +<h4 id="256dark-features">Features / Properties</h4> + + * Solarized :-) + * Comment style for backup and log and cache files + * Highlighted style for files of special interest (.tex, Makefiles, .ini ...) + * Bold hierarchies: + * archive = violet, compressed archive = violet + bold + * audio = orange, video = orange + bold + * Tested use-cases: + * latex directories + * source code directories + * Special files (block devices, pipes, ...) are inverted using the + solarized light palette for the background + * Symbolic links bold and distinguishable from directories + +<h4 id="256dark-screenshots">Screenshots</h4> + +Here is a [screenshot](https://github.com/seebi/dircolors-solarized/raw/master/img/dircolors.256dark.png) of a prepared session which shows the content of the test-directory.tar.bz2. +It is captured from an [iterm2](http://iterm2.com/) using the [dz-version of the awesome Inconsolata font](http://nodnod.net/2009/feb/12/adding-straight-single-and-double-quotes-inconsola/) (but you can use any terminal emulator supporting 256colors). + + + +Some more screenshots are provided by [andrew from webupd8.org](http://www.webupd8.org/2011/04/solarized-must-have-color-paletter-for.html). + +<h3 id="ansi">Theme #2: "ansi-\*" (by <a href="https://github.com/huyz">huyz</a>)</h3> + +This theme and its variants require that the terminal emulator be properly +configured to display the Solarized palette instead of the 16 default ANSI +colors. + +<h4 id="ansi-features">Features / Properties</h4> + +This theme called "ansi-universal" and its variants "ansi-dark" and +"ansi-light", were designed to work best with both Solarized Dark and Light +palettes, but also to work under terminals' default ANSI colors. In other +words, these themes were 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, incrediby hard to read, or a boring +gray. + +Thus, the universal theme was designed with these 4 palettes in mind: + +- Solarized Dark: "ansi-universal" works best when the terminal emulator is + set to this scheme +- Solarized Light: "ansi-universal" works best when the terminal emulator is + set to this scheme +- Default terminal ANSI Colors with a dark background +- Default terminal ANSI Colors with a light background + +The "ansi-dark" and "ansi-light" are slightly optimized versions of "ansi-universal" +for Solarized Dark and Solarized Light, respectively, if you're willing +to sacrifice a bit of universality. + +Colors were selected based on the characteristics of the items to be displayed: + +- Visibility generally follows importance, with an attempt to let unimportant + items 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 items + +<h4 id="ansi-screenshots">Screenshots</h4> + +Solarized Dark (this example uses iTerm2 on OS X): + +] + +To see what this theme looks like when the terminal emulator is set with different color palettes: + +* [Solarized Light (with iTerm2 on OS X)](https://github.com/huyz/dircolors-solarized/raw/master/img/screen-dircolors-in-iTerm2-solarized_light.png) +* [Default dark background of iTerm on OS X](https://github.com/huyz/dircolors-solarized/raw/master/img/screen-dircolors-in-iTerm-dark.png) +* [Default light background of iTerm on OS X](https://github.com/huyz/dircolors-solarized/raw/master/img/screen-dircolors-in-iTerm-light.png) +* [Default dark colors of PuTTY on Windows](https://github.com/huyz/dircolors-solarized/raw/master/img/screen-dircolors-in-PuTTY-dark_default.png) +* [Default light colors of PuTTY on Windows](https://github.com/huyz/dircolors-solarized/raw/master/img/screen-dircolors-in-PuTTY-light_system.png) (Select "Use system colors") + + +<h2 id="installation">Installation</h2> + +### Downloads + +If you have come across these themes via the [dircolors-only repository] on +github, you may want to check the main [Solarized repository] to see if there +are official themes. + +In the future, the [dircolors-only repository] may be kept in sync with the main +[Solarized repository], but the [dircolors-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 +[dircolors-only repository]. + +If you want to access the latest improvements to a specific theme, then go to +that theme's unique github directory: + +* "256dark": https://github.com/seebi/dircolors-solarized +* "ansi-\*": https://github.com/huyz/dircolors-solarized + +[Solarized repository]: https://github.com/altercation/solarized +[dircolors-only repository]: https://github.com/seebi/dircolors-solarized + +### General Instructions + +The Solarized color themes are distributed as database files for GNU +dircolors, which is the application that sets up colors for GNU ls. +To use any of the database files, run this: + + eval `dircolors /path/to/dircolorsdb` + +To activate the theme for all future shell sessions, copy or link that file to +`~/.dir_colors`, and include the above command in your `~/.profile` (for bash) +or `~/.zshrc` (for zsh). + +For Ubuntu 14.04 it is sufficient to copy or link database file to `~/.dircolors`. +Statement in `~/.bashrc` will take care about triggering eval command. + +### Additional Instructions for 256-color Solarized Themes, e.g. "256dark" + +For the 256-color Solarized dircolors themes, such as "256dark", you need a 256-color +terminal (e.g. `gnome-terminal` or `urxvt`) and a correct `TERM` variable, +e.g.: + + export TERM=xterm-256color # for common 256 color terminals (e.g. gnome-terminal) + export TERM=screen-256color # for a tmux -2 session (also for screen) + export TERM=rxvt-unicode-256color # for a colorful rxvt unicode session + +### Additional Instructions for ANSI Solarized Themes, e.g. "ansi-universal" + +For the ANSI Solarized dircolors themes (which work with both 16-color and +256-color terminals) you must 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: + + + + +<h2 id="understanding">Understanding Solarized Colors in Terminals</h2> + +### How Solarized works with ANSI-redefinition themes + +8- or 256-color terminal programs such as dircolors use color codes that +correspond to the expected 8 normal ANSI colors. dircolors 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- or 256-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 dircolors 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 dircolors is entirely dependent on the terminal emulator for the +display of its colors, you cannot directly tell a dircolors theme to display +Solarized orange, e.g. by specifying an RGB value. Instead, the theme's colors +must be chosen using the available color codes (either ANSI or one of the 256 +XTerm colors) with the expectation that the terminal emulator will display +them as appropriate Solarized colors. For example, the dircolors color +format `01;31` which normally would be "bold red" is expected to be displayed +by the terminal emulator as Solarized orange. + +So in order for dircolors to display the *exact* 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 16-color themes *without* having +changed your emulator's palette, you will get a strange selection of colors +that may be hard to read or gray. + +Yes, this means that, to use the *exact* Solarized theme for dircolors, you +need to change color settings for not one but two different programs: your +terminal emulator and dircolors. 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 terminal applications such as older dircolors 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 +dirco color format `01;31`, 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. + +### How Solarized works with 256-color themes + +Newer versions of dircolors, as well as modern terminal emulators, support 256 +colors. Since 256 > 16, does this mean that 256-color dircolors themes are +better than ANSI dircolors themes for displaying the Solarized palette? Not +necessarily. Solarized is a 16-color palette with unique RGB values. +256-color terminal emulators have more colors than the ANSI palette but +completely different RGB values. (See [8-bit color +graphics](http://en.wikipedia.org/wiki/256_colors).) The "256dark" +theme was designed to use these standard fixed colors. + +#### How Solarized could work with 256 colors without touching ANSI + +There is ongoing +[discussion](https://github.com/altercation/solarized/issues/8) on how to +reconfigure the approximate Solarized colors (the default 256 XTerm colors) to +display the exact Solarized colors. The benefit of this approach is that the +ANSI colors would not be messed with, and all the existing terminal +applications (with non-Solarized-aware color themes) that expect ANSI colors +would get ANSI colors; i.e. you would not see text accidentally disappear or +turn gray on you as soon as you change your terminal emulator's ANSI color +settings to Solarized. + +The disadvantage of such a solution means that 8-color terminal applications +such as irssi or older dircolors would not be able to display Solarized +colors, no matter what theme they used. + +Work on an official solution has not yet started but the +[discussion](https://github.com/altercation/solarized/issues/8) has presented +some working solutions, at least for XTerm and possibly other Linux terminal +emulators. + + +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 + +NOTE: + +* For "256-color" themes, the XTERM/HEX column lists the approximate Solarized + colors that are used (note the RGB values in the XTERM/HEX column only + approximates the RGB values in the HEX column). +* For "ANSI" themes, the TERMCOL column lists the ANSI colors that are replaced + with the Solarized colors listed under the HEX column. |