Doc: add manual installation instructions

Author: jan-warchol

CONTRIBUTING.md

@@ -1,15 +1,3 @@
-Where are orange and violet?
-----------------------------
-
-Selenized [defines](the-values.md) 8 accent colors: red, orange, yellow, green,
-cyan, blue, violet and magenta. However, terminal emulators traditionally have
-escape codes for 6 colors (red, yellow, green, cyan, blue and magenta), with
-two additional codes for black and white. Therefore, terminal configs included
-in this repository don't include orange and violet. However, configs for GUI
-programs will include the full palette (as GUI programs can define as many
-colors as they want).
-
-
 Syntax highlighting design principles
 -------------------------------------
 

README.md

@@ -66,10 +66,8 @@ please comment on
 
 ### Manual installation
 
-If your application is not listed above, you can manually copy [hex
-values](the-values.md) into its preferences.  Please consider sending me a pull
-request with the resulting configuration so that I can add it to officially
-supported terminals :-)
+If your application is not listed above, it's easy to set the colors manually.
+See [this document](manual-installation.md) for guidelines.
 
 
 

manual-installation.md

@@ -0,0 +1,63 @@
+Using selenized palette
+-----------------------
+
+Guidelines for creating a selenized theme for your terminal emulator.
+
+Each Selenized variant defines 3 background shades (`bg_*`), 3 content shades
+(`dim_*`, `fg_*`) and 8 accent colors (each with a bright version). This
+document explains which color to use for what. You can find RGB values of the
+colors [here](the-values.md).
+
+
+### Color mapping
+
+| Element           | Color  |
+| ----------------- | ------ |
+| background        | bg_0   |
+| foreground        | fg_0   |
+| bold foreground   | fg_1   |
+| dim foreground    | dim_0  |
+| cursor color      | fg_1   |
+| selection         | bg_2   |
+| selection text    | (none) |
+
+Notes:
+
+* Most terminals don't allow setting selection colors, they simply reverse
+  foreground and background.
+* Some terminals allow setting the opacity/brightness of special "dim" colors.
+  This value should be set to 0.625.
+* In case your terminal has a setting like "bright background", set it to
+  `bg_1`.
+* ANSI colors don't include orange and violet, so they are not used in terminal
+  emulators - they are intended for GUI applications.
+
+
+
+ANSI palette:
+
+| #   | ANSI color     | Selenized color |
+| --- | -------------- | --------------- |
+| 0   | black          | bg_1            |
+| 1   | red            | red             |
+| 2   | green          | green           |
+| 3   | yellow         | yellow          |
+| 4   | blue           | blue            |
+| 5   | magenta        | magenta         |
+| 6   | cyan           | cyan            |
+| 7   | white          | dim_0           |
+|     |                |                 |
+| 8   | bright black   | bg_2            |
+| 9   | bright red     | br_red          |
+| 10  | bright green   | br_green        |
+| 11  | bright yellow  | br_yellow       |
+| 12  | bright blue    | br_blue         |
+| 13  | bright magenta | br_magenta      |
+| 14  | bright cyan    | br_cyan         |
+| 15  | bright white   | fg_1            |
+
+That's it!
+
+Please send me a [pull request](https://github.com/jan-warchol/selenized/pulls)
+with the resulting configuration so that I can make your terminal officially
+supported :-)

the-values.md

@@ -5,10 +5,6 @@ LAB values are canonical.  RGB values (both sRGB and Apple RGB) are calculated
 from LAB using `utils/convert-lab-palette-to-rgbs.py` script, which employs
 `python-colormath` library for color space transformations.
 
-Please note that orange and violet are not used in configs of terminal
-emulators - they are intended for use with GUI applications (see
-[FAQ](README.md#where-are-orange-and-violet)).
-
 
 
 Selenized dark