Add documentation for themes.

1 files changed, 89 insertions, 0 deletions

diff --git a/doc/en/themes.txt b/doc/en/themes.txt
new file mode 100644
index 00000000..ebf654fe
--- /dev/null
+++ b/doc/en/themes.txt
@@ -0,0 +1,89 @@
+Themes
+======
+
+This page describes how themes work in poezio and how to create or
+modify one.
+
+A theme contains color attributes and character definitions. Poezio can display
+up to _256_ colors if your terminal supports it. Most of the time,
+if it doesn’t work, that’s because the _$TERM_ environnment variable is
+wrong. For example with tmux or screen, set it to _screen-256color_, in
+_xterm_, set it to _xterm-256color_, etc. If your terminal doesn’t have 256,
+only 8 color will be available, and poezio will replace the colors by one
+of the 8 values available. Thus, some theme file may not work properly
+if you only have 8 colors for example light gray on dark gray may
+be converted to black on black if only 8 colors are available, making
+the text impossible to read). The default theme should work properly in any
+case. If not, that’s a bug.
+
+A theme file is a python file (with the .py extension) containing a
+class, inheriting the *themimg.Theme* class defined into the *theming*
+poezio module.
+
+Create a theme
+--------------
+
+To create a theme named foo, create a file named foo.py into the theme
+directory (by default it’s _~/.local/share/poezio/themes/_) and insert
+into it:
+
+[source,python]
+----
+import theming
+
+class FooTheme(theming.Theme):
+      # Define here colors for that theme
+theme = FooTheme()
+----
+
+To define a _color pair_ and assign it to the COLOR_NAME option, just do
+[source,python]
+----
+class FooTheme(theming.Theme):
+      COLOR_NAME = (fg_color, bg_color, opt_attr)
+----
+
+You do not have to define all the <<available-options,available options>>,
+you can decide that your theme will only change some options, the other
+one will just have the default value (from the default theme).
+
+Colors and attributes
+~~~~~~~~~~~~~~~~~~~~~
+A color pair defines how the text will be displayed on the screen. It
+has a _foreground color_ (fg_color), a _background color_ (bg_color)
+and an *_optional_* _attribute_ (opt_attr).
+
+Colors
+^^^^^^
+A color is a number between -1 and 255. If it -1, this is the default
+color defined by your terminal (for example if your terminal displays
+text white on black by default, a fg_color of -1 is white, and a bg_color
+of -1 is black). If it’s between 0 and 256 it represents one of the colors
+on the image:
+
+image::../images/theme_256_colors.png["The list of all 256 colors", title="The list of all 256 colors"]
+
+Attributes
+^^^^^^^^^^
+An attribute is a python string (so, it has to be surrounded by
+*" "* or *' '*). It can be one of the following
+
+* *'b'*: bold text
+* *'u'*: underlined text
+
+Use a theme
+-----------
+To use a theme, just define the _theme_ option into the
+link:configure.html[configuration file] to the name of the theme you want
+to use. If that theme is not found, the default theme will be used instead.
+Note that the default theme is defined directly into poezio’s source code,
+and note in a theme file.
+
+[[available-options]]
+Available options
+-----------------
+
+CAUTION: This section is not complete.
+
+All available options can be found into the default theme, which is into the
+_theming.py_ file from the poezio’s source code.