custom tag representation docs

1 files changed, 27 insertions, 179 deletions

diff --git a/docs/source/configuration/index.rst b/docs/source/configuration/index.rst
index 295fa89c..285725f5 100644
--- a/docs/source/configuration/index.rst
+++ b/docs/source/configuration/index.rst
@@ -229,190 +229,38 @@ colours easy.
 
 Custom Tagstring Formatting
 ===========================
-In theme sections you can use keys with prefix `tag_` to format specific tagstrings. For instance,
-the following will make alot display the "todo" tag in white on red when in 256c-mode. ::
 
-    [256c-theme]
-    tag_todo_bg = #d66
-    tag_todo_fg = white
+To specify how a particular tgstring is displayes throughout the interface you can
+add a subsection named after the tag to the `[tags]` config section.
+The following attribute keys will interpreted and may contain urwid attribute strings
+as described in the :ref:`Themes` section above:
+        
+`fg` (foreground), `bg` (background), `focus_fg` (foreground if focussed) and `focus_bg` (background if focussed).
+An alternative string representation is read from the option `translated`.
 
-You can translate tag strings before displaying them using the `[tag-translate]` section. A
-key=value statement in this section is interpreted as:
-Always display the tag `key` as string `value`. Utf-8 symbols are welcome here, see e.g.
-http://panmental.de/symbols/info.htm for some fancy symbols. I personally display my maildir flags
-like this::
-
-    [tag-translate]
-    flagged = ⚑
-    unread = ✉
-    replied = ⇄
-
-Highlighting Search Results
-===========================
-Thread lines in the ``SearchBuffer`` can be highlighted by applying a theme different
-from their regular one if they match a `notmuch` query.
-
-The default config predefines highlighting for threads that carry the `unread`,
-the `flagged` or both of those tags.
-
-Thread lines consist of up to six components (not all of which are shown by
-default) that may be themed individually to provide highlighting. The components
-are 
-
- - `date`
- - `mailcount`
- - `tags`
- - `authors`
- - `subject`
- - `content`
- 
-Have a look at Alot's interface to see what they are.
-
-Customizing highlighting, you may define which components you want highlighted.
-Add a `highlighting` section to your config file and define a comma separated
-list of highlightable components: ::
-
-    [highlighting]
-    components = date, mailcount, tags, authors, subject
-
-Rules
------
-To specify which threads should be highlighted, you need to define highlighting
-rules. Rules map queries onto theme identifiers. Each thread that matches a given rule
-will use a theme identified by the ID the rule is mapped to.
-
-.. admonition:: Example
-
-    To highlight threads that are tagged as 'important', add the `rules`
-    key to your `highlighting` section and provide a dict in JSON syntax. Use an
-    appropriate `notmuch` query as a key and select a meaningful theme identifier as
-    its value:
-    
-::
-
-    rules = { "tag:important":"isimportant" }
-
-.. note::
-  Please make sure the identifier isn't the name of an actual tag, since this
-  may introduce ambiguity when highlighting tags. More on that `later`_.
-
-If you want highlighting for other threads as well, just add more rules to the
-dict: ::
-
-    rules = { "tag:important":"isimportant",
-              "subject:alot":"concernsalot",
-              "from:mom@example.com":"frommom"}
-
-.. note:: 
-    The sequence of the list defines the search order. The first query that
-    matches selects the highlighting. So if you have queries that are harder to
-    satisfy, you should put them earlier in the dict than ones that match more
-    easily:
-
-::
-
-    rules = { "tag:unread":"isunread",
-              "tag:unread AND tag:important":"isunreadimportant"}
-
-This setup will never highlight any threads as `isunreadimportant`, since alle
-threads that would match that identifier's query will *also* have matched the
-`isunread` query earlier in the rules dict. So, again, make sure that rules that
-are hard to satisfy show up early in the dict: ::
-
-    rules = { "tag:unread AND tag:important":"isunreadimportant",
-              "tag:unread":"isunread"}
-
-This way only threads that didn't match `isunreadimportant` before end up
-highlighted as `isunread` only.
-
-.. _later: `ambiguous theme identifiers`_
-
-Theme Generic Components
-------------------------
-.. note:: 
-  The following schema will allow you to define highlighting themes for all
-  components *except* `tags`, which follow a different system and will be
-  explained in the `next section`_.
+The following will make alot display the "todo" tag as "TODO" in white on red. ::
 
-To define a highlighting theme for a component, you need to add a key of the
-following format to your colour theme (please cf. `Widget Colours`_ for more information
-on theming): ::
+    [tags]
+      [[todo]]
+        bg = #d66
+        fg = white
+        translated TODO
 
-   search_thread_COMPONENT_ID_[focus_][fg|bg]
-
-where 
-
- - ``COMPONENT`` is the component this theme is meant to highlight,
- - ``ID`` is the theme identifier that defines which query this option belongs
-   to,
- - ``focus_`` is optional and if present defines that the theme should only be
-   used if the current thread is focussed and
- - ``fg`` or ``bg`` is a selection that specifies which themable part of the
-   component this option refers to.
-
-.. admonition:: Example
-
-    The following option will highlight the `subject` of each thread that
-    matches the query mapping to `isimportant` if the current thread is
-    `focus`\sed by theming its `foreground` according to the values stated
-    below:
-
-::
-    
-    search_thread_subject_isimportant_focus_fg = dark red, underline
-
-Following this pattern will allow you to set theming for the `background`, for
-the `subject` of threads tagged as `important` that are currently not focussed
-(by omitting the `focus_` part of the key string), for `subject`\s of threads
-matching a different query, and all other components except `tags`.
-
-.. _next section: `Theme Tags Component`_
-
-Theme `Tags` Component
-----------------------
-As described in `Custom Tagstring Formatting`_, tags may be themed individually.
-Highlighting expands this concept by allowing default themed tags as well as
-individual themed tags to provide highlighting variants.
-
-To specify highlighting themes for default themed tags, just add a key with the wanted
-theme identifier: ::
-
-    tag_ID_[focus_][fg|bg]
-
-where
-
- - ``ID`` is the theme identifier that defines which query this option belongs
-   to,
- - ``focus_`` is optional and if present defines that the theme should only be
-   used if the current thread is focussed and
- - ``fg`` or ``bg`` is a selection that specifies which themable part of the
-   component this option refers to.
-
-To highlight custom themed tags, proceed accordingly. Specify ::
-
-   tag_TAG_ID_[focus_][fg|bg]
-
-where
+Utf-8 symbols are welcome here, see e.g.
+http://panmental.de/symbols/info.htm for some fancy symbols. I personally display my maildir flags
+like this::
 
- - ``TAG`` is the name of the custom themed tag that is to be highlighted,
- - ``ID`` is the theme identifier that defines which query this option belongs
-   to,
- - ``focus_`` is optional and if present defines that the theme should only be
-   used if the current thread is focussed and
- - ``fg`` or ``bg`` is a selection that specifies which themable part of the
-   component this option refers to.
+    [tags]
+      [[flagged]]
+        translated = ⚑
+        fg = light red
 
-.. _ambiguous theme identifiers:
-.. caution::
-    As mentioned earlier, using tag names as theme identifiers may introduce
-    ambiguity and lead to unexpected theming results. 
+      [[unread]]
+        translated= ✉
+        fg = white
 
-Assuming one would replace the theme identifier `isimportant` with its intuitive
-alternative `important`, the tag theme ``tag_important_fg`` might either be a
-custom theme for the tag `important` of the form ``tag_TAG_fg`` or the highlight
-theme for default themed tags of threads that match the query that maps to the
-`important` identifier: ``tag_ID_fg``.
+      [[replied]]
+        translated= ⏎
 
-Using above proper identifier would distinguish those options as
-``tag_important_fg`` for the custom theme and ``tag_isimportant_fg`` for the
-highlighting theme.
+      [[encrypted]]
+        translated= ⚷