add documentation on color schemes

COLORSCHEMES.md

@@ -0,0 +1,111 @@
+# Color Schemes in Terminology
+
+Terminology uses color schemes to define the usual colors used by terminal
+applications, and a bit more: color schemes can also have an impact on the
+theme used.
+
+
+# Configuration file
+
+The colorschemes are stored in EET format for speed up and ease of
+development.
+This format being a bit cumbersome to edit, color schemes can be edit in an
+easy INI format described below.
+
+One can have a look at `data/color_schemes/Default.ini` for an example.
+
+## Organisation of the file
+
+The INI format is made of sections, where the name appears in square brackets
+(`[` and `]`), that contain keys. Every key has a name and a value, delimited
+by an equals sign (`=`).
+
+Those value have 3 types:
+ * integers, mostly used to describe versions,
+ * strings, surrounded by double quotes (`"`) or not,
+ * colors, described as hex color codes, with or without alpha channels, like
+   `#00ffcc` or `#00ff00aa`.
+
+Semicolons (`;`) at the beginning of the line indicate a comment.
+
+The color scheme file contains the following sections that are mandatory:
+`Main`, `Metadata`, `Colors`, `Normal`, `Bright`, `Faint` and `BrightFaint`.
+
+## `Main`
+
+This section has only one field `version` with a default of `1`.
+In case the format has to change, this value will change.
+
+## `Metadata`
+
+This describes everything that is related to the color scheme but is not
+actually a color!
+The fields are the following:
+
+* `version`: an integer, this is the version of the color scheme itself
+* `name` is the name of the color scheme. It is expected to be the same as the
+  file name without the `.ini` extension
+* `author`: who made this color scheme
+* `website`
+* `license`: the short code of an opensource-approved license as listed on
+  https://spdx.org/licenses/
+
+## `Colors`
+
+This section describes colors used in the UI.  The fields are:
+
+* `bg`: the background color of the terminal
+* `main`: this color is used as the main color for cursor and various effects
+  on the terminal, like change of border on focus …
+* `hl`: a color used for an object or text when being highlighted. Usually
+  surrounded by the `main` color.
+* `end_sel`: on selections, the color of the handles used to expand or shrink
+  the area of the selection
+* `tab_missed_1`, `tab_missed_2`, `tab_missed_3`: the main color, the outline
+  color and the shadow color of the number of tabs where a bell has rung, tabs
+  that need attention.
+* `tab_missed_over_1`, `tab_missed_over_2`, `tab_missed_over_3`: same as
+  before but when the mouse is over that number
+* `tab_title_2`: the outline color of the active tab title. The foreground
+  used is `Normal.def` and the shadow is `bg`.
+
+
+## `Normal`, `Bright`, `Faint`, `BrightFaint`
+
+All those sections offer the same set of colors.
+`Normal` are the base colors. `Bright` are a brighter version of the `Normal`
+colors, while `Faint` are a dimer version of the `Normal` colors. Finally,
+`BrightFaint` are a dimer version of the `Bright` colors.
+
+They all have those fields:
+
+* `def`: the default foreground color
+* `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan` and `white` are
+  self-explanatory
+* `inverse_fg` and `inverse_fg` are the colors used when espace codes are used
+  to reverse background and foreground. Sometimes used to display selections
+  by the terminal applications
+
+
+# How to add a new color scheme
+
+First, one has to write a color scheme file as described above.  Let's say we
+are creating the color scheme `FooBar` stored in file `FooBar.ini`.
+
+The `Faint` and `BrightFaint` version can be generated by using the
+`gen_faint.py` script stored in `data/color_schemes/` as seen below:
+`gen_faint.py FooBar.ini > FooBar_with_faint.ini`
+
+What this script does is to pick the colors from `Normal` and `Bright` and
+merge them with the background color (`Colors.bg`) in a 70/30 proportion. This
+proportion is configurable, like this for a 80/20 proportion:
+`gen_faint.py FooBar.ini 80 > FooBar_with_faint.ini`
+
+Now that we are happy with the content of `FooBar_with_faint.ini`, we can call
+the script `add_color_scheme.sh` stored in `data/color_schemes/` as seen
+below:
+`add_color_scheme.sh eet ~/.config/terminology/colorschemes.eet FooBar_with_faint.ini`
+
+Now you should be able to select your color scheme in Terminology!
+
+

README.md

@@ -46,6 +46,25 @@ Note: to make terminology work with input methods in general you need:
 ```
 
 
+Themes
+------
+
+Apart from the ones shipped with Terminology, themes can be stored in
+`~/.config/terminology/themes/` .
+
+Documentation on themes is written in [THEMES.md](THEMES.md).
+
+
+Color Schemes
+-------------
+
+Terminology ships with some common color schemes.
+
+To know how to modify or add some new color schemes, please read
+[COLORSCHEMES.md](COLORSCHEMES.md).
+
+
+
 Mouse controls
 --------------
 
@@ -111,12 +130,6 @@ Default key controls
 
 
 
-Themes
-------
-
-Apart from the ones shipped with Terminology, themes can be stored in
-`~/.config/terminology/themes/` .
-
 
 Companion tools
 ---------------

THEMES.md

@@ -1,13 +1,54 @@
+# Themes in Terminology
+
 This document describes how Terminology interacts with themes and what needs
 to be handled by themes.
 
 See `ChangeLog.theme` on changes related to themes.
 
+# Color classes
 
-Windows contain group `terminology/base`.
+Based on the chosen color scheme, Terminology sets the following color classes
+on all the following edje groups:
 
+* `BG`: the background color of the terminal
+* `FG`: the default foreground color
+* `CURSOR`: the color of the cursor
+* `GLOW`: the color in the UI to ouline elements
+* `HIGHLIGHT`: the color used as main color when an elemeent is highlighted
+* `GLOW_TXT`: text colors with some glow
+* `GLOW_TXT_HIGHLIGHT`: text with glow that is highlighted
+* `END_SELECTION`: on selections, the color of the handles used to expand or shrink
+  the area of the selection
+* `TAB_MISSED`: the number of tabs where a bell has rung, tabs that need
+  attention
+* `TAB_MISSED_OVER`: same but when the mouse is over that number
+* `TAB_TITLE`: the colors of the active tab title
+* `BG_SENDFILE` is the background color when there is a sendfile action. See
+  `man tysend`. It is set to `#404040`.
+
+The following table explains how color classes are set from color scheme
+values:
+
+| Color Class          | Object color     | Outline color    | Shadow color  |
+| -------------------- | ---------------- | ---------------- | ------------- |
+| `BG`                 | `Colors.bg`      | `Colors.bg`      | `Colors.bg`   |
+| `FG`                 | `Normal.def`     | `Normal.def`     | `Normal.def`  |
+| `CURSOR`             | `Colors.main`    | `Colors.main`    | `Colors.main` |
+| `GLOW`               | `Colors.main`    | `Colors.main`    | `Colors.main` |
+| `GLOW_TXT_HIGHLIGHT` | `Colors.hl`      | `Colors.main`    | `Colors.main` |
+| `END_SELECTION`      | `Colors.end_sel` | `Colors.end_sel` | `Colors.end_sel` |
+| `TAB_MISSED`         | `Colors.tab_missed_1` | `Colors.tab_missed_2` | `Colors.tab_missed_3` |
+| `TAB_MISSED_OVER`    | `Colors.tab_missed_1` | `Colors.tab_missed_2` | `Colors.tab_missed_3` |
+| `TAB_TITLE`          | `Normal.def` | `Colors.tab_title_2` | `Colors.bg`   |
+| `BG_SENDFILE`        | `#404040`    | `#404040`            | `#404040`     |
+
+
+
+Let's dive into the edje groups that Terminology uses.
 
 # `terminology/base`
+Windows contain group `terminology/base`.
+
 Contains what is global to a window.
 
 ## Swallowed parts