doc: document threadline highlighting

1 files changed, 91 insertions, 12 deletions

diff --git a/docs/source/configuration/index.rst b/docs/source/configuration/index.rst
index aa3ba4d8..6314754e 100644
--- a/docs/source/configuration/index.rst
+++ b/docs/source/configuration/index.rst
@@ -273,17 +273,28 @@ Alot can be run in 1, 16 or 256 colour mode. The requested mode is determined by
 from option `colourmode` config value. The default is 256, which scales down depending on how many colours your
 terminal supports.
 
-To specify the theme to use, set the `theme` config option to the name of a theme-file.
+To specify the theme to use, set the :ref:`theme <theme>` config option to the name of a theme-file.
 A file by that name will be looked up in the path given by the :ref:`themes_dir <themes-dir>` config setting
 which defaults to :file:`~/.config/alot/themes/`.
 
-Theme files contain a section for each :ref:`MODE <modes>` plus "help" for the bindings-help overlay
+.. _config.theming.themefiles:
+
+Theme Files
+-----------
+contain a section for each :ref:`MODE <modes>` plus "help" for the bindings-help overlay
 and "global" for globally used themables like footer, prompt etc.
 Each such section contains attribute values for the parts that can be themed.
-The names of the themables should be self-explanatory. Attributes are sextuples of urwid Attribute
-strings that specify fore/background for mono, 16 and 256-colour modes respectively.
+The names of the themables should be self-explanatory.
+Have a look at the default theme file at :file:`alot/defaults/default.theme`
+and the config spec :file:`alot/defaults/default.theme` for the exact format.
 
-For mono-mode only the flags "blink,standup,underline,bold" are available,
+.. _config.theming.attributes:
+
+Colour Attributes
+-----------------
+Attributes are *sextuples* of `urwid Attribute strings <http://excess.org/urwid/wiki/DisplayAttributes>`__
+that specify foreground and background for mono, 16 and 256-colour modes respectively.
+For mono-mode only the flags `blink`, `standup`, `underline` and `bold` are available,
 16c mode supports these in combination with the colour names::
 
     brown    dark red     dark magenta    dark blue    dark cyan    dark green
@@ -292,13 +303,10 @@ For mono-mode only the flags "blink,standup,underline,bold" are available,
 
 In high-colour mode, you may use the above plus grayscales `g0` to `g100` and
 colour codes given as `#` followed by three hex values.
-See `here <http://excess.org/urwid/wiki/DisplayAttributes>`_
-and `here <http://excess.org/urwid/reference.html#AttrSpec>`_
-for more details on the interpreted values.
-A colour picker that makes choosing colours easy can be found in :file:`alot/extra/colour_picker.py`.
-
-Have a look at the default theme file at :file:`alot/defaults/default.theme`
-and the config spec :file:`alot/defaults/default.theme` for the exact format.
+See `here <http://excess.org/urwid/wiki/DisplayAttributes>`__
+and `here <http://excess.org/urwid/reference.html#AttrSpec>`__
+for more details on the interpreted values.  A colour picker that makes choosing colours easy can be
+found in :file:`alot/extra/colour_picker.py`.
 
 As an example, check the setting below that makes the footer line appear as
 underlined bold red text on a bright green background::
@@ -309,6 +317,77 @@ underlined bold red text on a bright green background::
     #        v                 v   v                             v              v                             v
     footer = 'bold,underline', '', 'light red, bold, underline', 'light green', 'light red, bold, underline', '#8f6'
 
+Highlighting Thread lines in Search Mode
+----------------------------------------
+The subsection '[[threadline]]' of the '[search]' section in :ref:`Theme Files <config.theming.themefiles>`
+determines how to present a thread: here, :ref:`attributes <config.theming.attributes>` 'normal' and
+'focus' provide fallback/spacer themes and 'parts' is a (string) list of displayed subwidgets.
+Possible part strings are:
+
+* date
+* mailcount
+* tags
+* authors
+* subject
+
+For every listed part there must be a subsection with the same name, defining
+
+:normal: :ref:`attribute <config.theming.attributes>` used for this part if unfocussed
+:focus: :ref:`attribute <config.theming.attributes>` used for this part if focussed
+:width: tuple indicating the width of the part. This is either `('fit', min, max)` to force the widget
+        to be at least `min` and at most `max` characters wide,
+        or `('weight', n)` which makes it share remaining space
+        with other 'weight' parts.
+:alignment: how to place the content string if the widget space is larger.
+            This must be one of 'right', 'left' or 'center'.
+
+To "highlight" some thread lines (use different attributes than the defaults found in the
+'[[threadline]]' section), one can define sections with prefix 'threadline'.
+Each one of those can redefine any part of the structure outlined above, the rest defaults to
+values defined in '[[threadline]]'.
+
+The section used to theme a particular thread is the first one (in file-order) that matches
+the criteria defined by its 'query' and 'taggeswith' values:
+
+* If 'query' is defined, the thread must match that querystring.
+* If 'tagged_with' is defined, is value (string list)  must be a subset of the accumulated tags of all messages in the thread.
+
+.. note:: that 'tagged_with = A,B' is different from 'query = "is:A AND is:B"':
+   the latter will match only if the thread contains a single message that is both tagged with
+   A and B.
+
+   Moreover, note that if both query and tagged_with is undefined, this section will always match
+   and thus overwrite the defaults.
+
+The example below shows how to highlight unread threads:
+The date-part will be bold red if the thread has unread messages and flagged messages
+and just bold if the thread has unread but no flagged messages::
+
+    [search]
+        # default threadline
+        [[threadline]]
+            normal = 'default','default','default','default','#6d6','default'
+            focus = 'standout','default','light gray','dark gray','white','#68a'
+            parts = date,mailcount,tags,authors,subject
+            [[[date]]]
+                normal = 'default','default','light gray','default','g58','default'
+                focus = 'standout','default','light gray','dark gray','g89','#68a'
+                width = 'fit',10,10
+            ...
+
+        # highlight threads containing unread and flagged messages
+        [[threadline-flagged-unread]]
+            tagged_with = 'unread','flagged'
+            [[[date]]]
+                normal = 'default','default','light red,bold','default','light red,bold','default'
+
+        # highlight threads containing unread messages
+        [[threadline-unread]]
+            query = 'is:unread'
+            [[[date]]]
+                normal = 'default','default','light gray,bold','default','g58,bold','default'
+
+
 
 Custom Tagstring Formatting
 ===========================