Merge pull request #81 from jan-warchol/devel

Rewrite documentation to be more catchy :-)

Author: jan-warchol

README.md

@@ -1,21 +1,25 @@
 Selenized color palette
 =======================
 
-Selenized is a color theme for terminals and text editors, carefully designed
-using professional-grade [CIE
-L*a*b*](http://en.wikipedia.org/wiki/Lab_color_space) color space for maximum
-readability and great eye comfort.
+<!--
+Solarized redesigned: fine-tuned color palette for programmers with focus on readability.
+-->
 
+![Selenized dark screenshot](http://i.imgur.com/yM0vadH.png)
 
-Design principles
------------------
+After researching perceptually uniform color spaces, _4 years of testing_,
+refining hues and fine-tuning lightness using professional grade [CIE
+Lab](http://en.wikipedia.org/wiki/Lab_color_space) color space, the task of
+redesigning venerable Solarized is almost finished!
+Results:
 
-- make the contrast just right: strong but not tiring to the eyes
-- adjust lightness of all colors for uniform readability
-- select colors in a way that boosts code comprehension
-- make it as beautiful and visually pleasing as possible
+* Easy on the eyes.
+* **Beautiful**, vibrant and easily **distinguishable** accent colors.
+* **Great readability** and better compatibility with Web Content
+  [Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/).
 
-Read more about the design [here](features-and-design.md).
+Read more [about the design](features-and-design.md)
+and see how it [improves on Solarized](whats-wrong-with-solarized.md).
 
 
 
@@ -71,66 +75,33 @@ See [this document](manual-installation.md) for guidelines.
 
 
 
-Palette variants
-----------------
-
-### Selenized dark
-
-![Selenized dark screenshot](http://i.imgur.com/yM0vadH.png)
-
-Like _Solarized dark_, but better.
-
-
-
-### Selenized black
-
-![Selenized black screenshot](http://i.imgur.com/rXIH87x.png)
-
-Oldschool black-and-white look with a little more contrast.
-
-
-
-### Selenized light
-
-![Selenized light screenshot](http://i.imgur.com/kQVgD5U.png)
-
-A warm sepia variant, corresponding to _Solarized light_.
-
-
 
-### Selenized white
 
-![Selenized white screenshot](http://i.imgur.com/sc0Uv9h.png)
+Compatibility notes
+-------------------
 
-Unlike many dark-on-white palettes, yellow color is readable here.
-
-
-
-What about _Solarized_?
------------------------
-
-There is a popular color palette named _Solarized_. I really liked the design
-principles behind Solarized, but it has a couple issues, which [Selenized
-solves](whats-wrong-with-solarized.md).
-
-By the way, the name is derived from the greek word "selene", which means
-the moon (as opposed to the sun in Solarized).
-
-
-
-Known issues
-------------
-
-Some command-line programs need reconfiguration to look good with Selenized,
+Some command-line programs may need reconfiguration to look good with Selenized,
 because they make assumptions about the colors configured in terminal (see
 [this issue](https://github.com/janek-warchol/selenized/issues/7) for details):
 
 - [`ls`](dircolors/)
 - [Midnight Commander](mc/)
 
+However, this is quite rare; vast majority of software works great
+out-of-the-box.
+
 
 
 Contributing and development
 ----------------------------
 
 See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+
+
+About the name
+--------------
+
+The name of the project is derived from the greek word "selene", which means
+_the moon_ - as opposed to _the sun_ in Solarized.
+

features-and-design.md

@@ -3,57 +3,71 @@ Features
 
 ### Comfortable contrast
 
-A couple years ago I noticed that my eyes quickly grew tired when I was working
-in a terminal.  It turned out that the problem was the palette I was using at
-that time - it was white text on dark violet background (default Ubuntu
-terminal colors - see [example](http://i.imgur.com/wICCS7x.png)).  High
-contrast like that tires the eye - that's why professional graphic software
-often use gray in their interfaces.
+It all started when I noticed that my eyes were quickly growing tired when
+coding.  I had been using default Ubuntu colors back then (white on dark
+magenta), and the contrast was simply _too high_.
 
 ![Selenized contrast sample](http://i.imgur.com/Y11xuwv.png)
 
-Selenized has moderate-to-low contrast - the difference in LAB lightness
-between foreground and background is 50, which is exactly half the distance
-between pure black and white.  The result is easy on eyes but still very
-readable, even on poor displays - see a [side-by-side comparison of Selenized
-and Ubuntu palettes](http://i.imgur.com/MtpKFFf.png).
+Selenized has moderately low contrast - a bit more than half the distance
+between pure black and white.  The result is easy on the eyes, but still **very
+readable:** long coding sessions are not a strain anymore!  ([compare with
+Ubuntu colors here](http://i.imgur.com/MtpKFFf.png))
 
 <!-- [selenized manpage example](http://i.imgur.com/twNvCfk.png) -->
 
 
 
-### Balanced accent colors
+### Balanced and beautiful accent colors
 
-It's not just foreground and background colors that matter. Lightness of all
-accent colors need to be carefully adjusted, too: we want them to be equally
-readable against the background, but at the same time they cannot have *exactly*
-the same lightness because that would make them harder to tell apart (for
-example, our eyes expect yellow to be brighter than orange and orange brighter
-than red).
+Lightness of accent colors needs to be carefully adjusted, so that they are
+both pleasant and present an even contrast against the background. This is
+tricky because of things like [Helmholtz–Kohlrausch
+effect](https://en.wikipedia.org/wiki/Helmholtz%E2%80%93Kohlrausch_effect) and
+eye cone sensitivity differences.
 
-<!-- ![Selenized accent colors diagram](http://i.imgur.com/kxylyHe.png) -->
+![Selenized accent colors diagram](http://i.imgur.com/QNKIw1U.png)
 
-I have fine-tuned the lightness to ensure that all colors present an even
-contrast, even red and blue (which are too dark in many palettes).  You can
-read more about accent color lightness and see a comparison between Selenized
-and other palettes [here](balancing-lightness-of-colors.md) (warning: extreme
-ugliness of some palette examples may scorch your eyes!).
+Selenized harmonizes the lightnesses while preserving each color's
+individuality (e.g. yellow should be brighter than red). This is possible
+thanks to the use of perceptually uniform CIE Lab color space.
 
+![Accent colors in xterm and ubuntu](http://i.imgur.com/wNCz40F.png)
 
+Many palettes - including default coloring in xterm, Ubuntu terminal and
+Sublime Text - [weren't designed this
+way](https://vis4.net/blog/posts/avoid-equidistant-hsv-colors/): they have a
+lot of variation in lightness. You can see above how this leads to bad
+readability.
 
-### Variants for different conditions
 
-Reducing contrast inside terminal window is one thing, but what about the
-contrast of the whole desktop?  If you have your terminal side-by-side with a
-window that has black text on white background (e.g. a document viewer or a
-browser), the resulting contrast between the two windows may make the terminal
-less readable.  That's why Selenized dark is has relatively light background:
-this ensures better readability and prevents eye fatigue when used next to a
-bright/high-contrast window.
 
-![Selenized next to black&white Wikipedia](http://i.imgur.com/OX2Ce2r.png)
+### Variants for different needs
 
-There is also a "black" variant meant for people who need higher contrast -
-either due to especially bad display/lightness conditions, or because they are
-not yet used to low contrast palettes.
+Selenized includes four variants so that everyone will find something that
+suits their taste. Thanks to the magic of CIE Lab color space, all variants
+share the same lightness relationships, resulting in exactly the same
+readability.
+
+
+#### Selenized dark & light
+
+![Selenized dark screenshot](http://i.imgur.com/yM0vadH.png)
+![Selenized light screenshot](http://i.imgur.com/kQVgD5U.png)
+
+Like _Solarized_, but better. Dark teal and warm sepia complement each other nicely.
+
+
+#### Selenized black & white
+
+Contrast inside terminal/editor is one thing, but what about the whole desktop?
+A window with black text on white background (e.g. a pdf document) next to your
+code will influence its perceived brightness. Also, what if you are working
+outdoors?
+
+![Selenized black screenshot](http://i.imgur.com/rXIH87x.png)
+![Selenized white screenshot](http://i.imgur.com/sc0Uv9h.png)
+
+That's why selenized has black and white variants: oldschool look with a little
+more contrast. Notice that yellow color on white background is readable here.
 

utils/palettes/3rd-party/adapted_solarized_dark.py

@@ -14,6 +14,8 @@
     "magenta":    "#d33682",
     "cyan":       "#2aa198",
     "dim_0":      "#586e75",
+    "orange":     "#cb4b16",
+    "violet":     "#6c71c4",
 
     "bg_2":       "#073642",
     "br_red":     "#dc322f",
@@ -23,4 +25,6 @@
     "br_magenta": "#d33682",
     "br_cyan":    "#2aa198",
     "fg_1":       "#93a1a1",
+    "br_orange":  "#cb4b16",
+    "br_violet":  "#6c71c4",
 }