cleaned up manual a bit

5 files changed, 193 insertions, 198 deletions

diff --git a/docs/user/source/_templates/layout.html b/docs/user/source/_templates/layout.html
new file mode 100644
index 00000000..b4384e43
--- /dev/null
+++ b/docs/user/source/_templates/layout.html
@@ -0,0 +1,7 @@
+{% extends "!layout.html" %}
+{% set script_files = [] %}
+
+{% block linktags %}{% endblock %}
+{% block relbar1 %}{% endblock %}
+{% block footer %}{% endblock %}
+{% block relbaritems %}{% endblock %}
diff --git a/docs/user/source/config.rst b/docs/user/source/config.rst
deleted file mode 100644
index ea1cd6e1..00000000
--- a/docs/user/source/config.rst
+++ /dev/null
@@ -1,170 +0,0 @@
-Configuration
-=============
-
-
-All configs are optional, but if you want to send mails you need to
-specify at least one account section.
-
-Configfile Layout
-------------------
-Alot reads a config file in the "INI" syntax:
-It consists of some sections whose names are given in square brackets, followed by
-key-value pairs that use "=" or ":" as separator, ';' and '#' are comment-prefixes.
-
-The default location for the config file is `~/.config/alot/config`.
-You can find a complete example config with the default values and their decriptions in
-`alot/defaults/alot.rc`.
-
-Note that since ":" is a separator for key-value pairs you need to use "colon" to bind
-commands to ":".
-
-Here is a key for the interpreted sections:
-
-[general]
-    global settings: set your editor etc
-[account X]
-    defines properties of account X: (see below)
-[X-maps]
-    defines keymaps for mode X. possible modes are:
-    envelope, search, thread, taglist, bufferlist and global.
-    global-maps are valid in all modes.
-[tag-translate]
-    defines a map from tagnames to strings that is used when
-    displaying tags. utf-8 symbols welcome.
-[Xc-theme]
-    define colour palette for colour mode. X is in {1, 16, 256}.
-
-
-Account Sections
-----------------
-A sample gmail section looks like this (provided you have configured msmtp accordingly)::
-
-    [account gmail]
-    realname = Patrick Totzke
-    address = patricktotzke@gmail.com
-    aliases = patricktotzke@googlemail.com
-    sendmail_command = msmtp --account=gmail -t
-
-Here's a full list of the interpreted keywords in account sections::
-
-    # used to format the (proposed) From-header in outgoing mails
-    realname = your name
-    address = this accounts email address
-
-    # used to clear your addresses/ match account when formating replies
-    aliases = foobar@myuni.uk;f.bar@myuni.uk;f.b100@students.myuni.uk
-
-    # how to send mails
-    sendmail_command = command, defaults to 'sendmail'
-
-    # where to store outgoing mail
-    sent_box = maildir:///home/you/mail//Sent
-
-    # how to tag sent mails [default: sent]. seperate multiple tags with ','.
-    sent_tags = sent
-
-    # path to signature file
-    signature = ~/your_vcard_for_this_account.vcs
-
-    # attach signature file if set to True, append its content (mimetype text)
-    # to the body text if set to False. Defaults to False.
-    signature_as_attachment = False
-
-    # signature file's name as it appears in outgoing mails if
-    # signature_as_attachment is set to True
-    signature_filename = you.vcs
-
-    # command to lookup contacts
-    abook_command = abook --mutt-query
-    abook_regexp = regexp to match name & address in abook_commands output.
-
-.. warning::
-
-  Sending mails is only supported via sendmail for now. If you want
-  to use a sendmail command different from `sendmail`, specify it as `sendmail_command`.
-
-`send_box` specifies the mailbox where you want outgoing mails to be stored
-after successfully sending them. You can use mbox, maildir, mh, babyl and mmdf
-in the protocol part of the url.
-
-The file specified by `signature` is attached to all outgoing mails from this account, optionally
-renamed to `signature_filename`.
-
-If you specified `abook_command`, it will be used for tab completion in queries (to/from)
-and in message composition. The command will be called with your prefix as only argument
-and its output is searched for name-email pairs. The regular expression used here
-defaults to `(?P<email>.+?@.+?)\s+(?P<name>.+)`, which makes it work nicely with `abook --mutt-query`.
-You can tune this using the `abook_regexp` option (beware Commandparsers escaping semantic!).
-Have a look at the FAQ for other examples.
-
-
-Key Bindings
-------------
-If you want to bind a commandline to a key you can do so by adding the pair to the
-`[MODE-maps]` config section, where MODE is the buffer mode you want the binding to hold.
-Consider the following lines, which allow you to send mails in envelope buffers using the
-combination `control` + `s`::
-
-    [envelope-maps]
-    ctrl s = send
-
-Possible MODE strings are:
-
-* envelope
-* search
-* thread
-* taglist
-* bufferlist
-* global
-
-Bindings defined in section `[global-maps]` are valid in all modes.
-
-Have a look at `the urwid User Input documentation <http://excess.org/urwid/wiki/UserInput>`_ on how key strings are formated.
-
-
-
-Hooks
------
-Hooks are python callables that live in a module specified by
-`hooksfile` in the `[global]` section of your config. Per default this points
-to `~/.config/alot/hooks.py`.
-For every command X, the callable 'pre_X' will be called before X and 'post_X' afterwards.
-
-When a hook gets called, it receives instances of
-
-ui
-  `alot.ui.UI`, the main user interface object that can prompt etc.
-dbm
-  `alot.db.DBManager`, the applications database manager
-aman
-  `alot.account.AccountManager`, can be used to look up account info
-config
-  `alot.settings.config`, a configparser to access the users config
-
-An autogenerated API doc for these can be found at http://alot.rtfd.org ,
-the sphinx sources live in the `docs` folder.
-As an example, consider this pre-hook for the exit command,
-that logs a personalized goodby message::
-
-    import logging
-    def pre_exit(aman=None, **rest):
-        accounts = aman.get_accounts()
-        if accounts:
-            logging.info('goodbye, %s!' % accounts[0].realname)
-        else:
-            logging.info('goodbye!')
-
-Apart from command pre and posthooks, the following hooks will be interpreted:
-
-`reply_prefix(realname, address, timestamp, **kwargs)`
-    Is used to reformat the first indented line in a reply message.
-    Should return a string and defaults to 'Quoting %s (%s)\n' % (realname, timestamp)
-`forward_prefix(realname, address, timestamp, **kwargs)`
-    Is used to reformat the first indented line in a inline forwarded message.
-    Returns a string and defaults to 'Forwarded message from %s (%s)\n' % (realname, timestamp)
-`pre_edit_translate(bodytext, **kwargs)`
-    can be used to manipulate a messages bodytext before the editor is called.
-    Receives and returns a string.
-`post_edit_translate(bodytext, **kwargs)`
-    can be used to manipulate a messages bodytext after the editor is called
-    Receives and returns a string.
diff --git a/docs/user/source/theming.rst b/docs/user/source/configuration.rst
index 5bf10a7f..72750475 100644
--- a/docs/user/source/theming.rst
+++ b/docs/user/source/configuration.rst
@@ -1,8 +1,177 @@
-Theming
-=======
+*************
+Configuration
+*************
 
-Colours
--------
+
+All configs are optional, but if you want to send mails you need to
+specify at least one account section.
+
+Alot reads a config file in the "INI" syntax:
+It consists of some sections whose names are given in square brackets, followed by
+key-value pairs that use "=" or ":" as separator, ';' and '#' are comment-prefixes.
+
+The default location for the config file is `~/.config/alot/config`.
+You can find a complete example config with the default values and their decriptions in
+`alot/defaults/alot.rc`.
+
+Note that since ":" is a separator for key-value pairs you need to use "colon" to bind
+commands to ":".
+
+Here is a key for the interpreted sections:
+
+[general]
+    global settings: set your editor etc
+[account X]
+    defines properties of account X: (see below)
+[X-maps]
+    defines keymaps for mode X. possible modes are:
+    envelope, search, thread, taglist, bufferlist and global.
+    global-maps are valid in all modes.
+[tag-translate]
+    defines a map from tagnames to strings that is used when
+    displaying tags. utf-8 symbols welcome.
+[Xc-theme]
+    define colour palette for colour mode. X is in {1, 16, 256}.
+
+
+Accounts
+========
+A sample gmail section looks like this (provided you have configured msmtp accordingly)::
+
+    [account gmail]
+    realname = Patrick Totzke
+    address = patricktotzke@gmail.com
+    aliases = patricktotzke@googlemail.com
+    sendmail_command = msmtp --account=gmail -t
+
+Here's a full list of the interpreted keywords in account sections::
+
+    # used to format the (proposed) From-header in outgoing mails
+    realname = your name
+    address = this accounts email address
+
+    # used to clear your addresses/ match account when formating replies
+    aliases = foobar@myuni.uk;f.bar@myuni.uk;f.b100@students.myuni.uk
+
+    # how to send mails
+    sendmail_command = command, defaults to 'sendmail'
+
+    # where to store outgoing mail
+    sent_box = maildir:///home/you/mail//Sent
+
+    # how to tag sent mails [default: sent]. seperate multiple tags with ','.
+    sent_tags = sent
+
+    # path to signature file
+    signature = ~/your_vcard_for_this_account.vcs
+
+    # attach signature file if set to True, append its content (mimetype text)
+    # to the body text if set to False. Defaults to False.
+    signature_as_attachment = False
+
+    # signature file's name as it appears in outgoing mails if
+    # signature_as_attachment is set to True
+    signature_filename = you.vcs
+
+    # command to lookup contacts
+    abook_command = abook --mutt-query
+    abook_regexp = regexp to match name & address in abook_commands output.
+
+.. warning::
+
+  Sending mails is only supported via sendmail for now. If you want
+  to use a sendmail command different from `sendmail`, specify it as `sendmail_command`.
+
+`send_box` specifies the mailbox where you want outgoing mails to be stored
+after successfully sending them. You can use mbox, maildir, mh, babyl and mmdf
+in the protocol part of the url.
+
+The file specified by `signature` is attached to all outgoing mails from this account, optionally
+renamed to `signature_filename`.
+
+If you specified `abook_command`, it will be used for tab completion in queries (to/from)
+and in message composition. The command will be called with your prefix as only argument
+and its output is searched for name-email pairs. The regular expression used here
+defaults to `(?P<email>.+?@.+?)\s+(?P<name>.+)`, which makes it work nicely with `abook --mutt-query`.
+You can tune this using the `abook_regexp` option (beware Commandparsers escaping semantic!).
+Have a look at the FAQ for other examples.
+
+
+Key Bindings
+============
+If you want to bind a commandline to a key you can do so by adding the pair to the
+`[MODE-maps]` config section, where MODE is the buffer mode you want the binding to hold.
+Consider the following lines, which allow you to send mails in envelope buffers using the
+combination `control` + `s`::
+
+    [envelope-maps]
+    ctrl s = send
+
+Possible MODE strings are:
+
+* envelope
+* search
+* thread
+* taglist
+* bufferlist
+* global
+
+Bindings defined in section `[global-maps]` are valid in all modes.
+
+Have a look at `the urwid User Input documentation <http://excess.org/urwid/wiki/UserInput>`_ on how key strings are formated.
+
+
+
+Hooks
+=====
+Hooks are python callables that live in a module specified by
+`hooksfile` in the `[global]` section of your config. Per default this points
+to `~/.config/alot/hooks.py`.
+For every command X, the callable 'pre_X' will be called before X and 'post_X' afterwards.
+
+When a hook gets called, it receives instances of
+
+ui
+  `alot.ui.UI`, the main user interface object that can prompt etc.
+dbm
+  `alot.db.DBManager`, the applications database manager
+aman
+  `alot.account.AccountManager`, can be used to look up account info
+config
+  `alot.settings.config`, a configparser to access the users config
+
+An autogenerated API doc for these can be found at http://alot.rtfd.org ,
+the sphinx sources live in the `docs` folder.
+As an example, consider this pre-hook for the exit command,
+that logs a personalized goodby message::
+
+    import logging
+    def pre_exit(aman=None, **rest):
+        accounts = aman.get_accounts()
+        if accounts:
+            logging.info('goodbye, %s!' % accounts[0].realname)
+        else:
+            logging.info('goodbye!')
+
+Apart from command pre and posthooks, the following hooks will be interpreted:
+
+`reply_prefix(realname, address, timestamp, **kwargs)`
+    Is used to reformat the first indented line in a reply message.
+    Should return a string and defaults to 'Quoting %s (%s)\n' % (realname, timestamp)
+`forward_prefix(realname, address, timestamp, **kwargs)`
+    Is used to reformat the first indented line in a inline forwarded message.
+    Returns a string and defaults to 'Forwarded message from %s (%s)\n' % (realname, timestamp)
+`pre_edit_translate(bodytext, **kwargs)`
+    can be used to manipulate a messages bodytext before the editor is called.
+    Receives and returns a string.
+`post_edit_translate(bodytext, **kwargs)`
+    can be used to manipulate a messages bodytext after the editor is called
+    Receives and returns a string.
+
+    
+
+Widget Colours
+==============
 Alot can be run in 1, 16 or 256 colour mode.
 The requested mode is determined by the commandline parameter `-C` or read from
 option `colourmode` in section `[globals]` of your config file.
@@ -35,7 +204,7 @@ 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. ::
 
@@ -54,20 +223,14 @@ like this::
     unread = ✉
     replied = ⇄
 
-
-Highlighting
-============
-
-About
------
+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.
 
-Components
-----------
 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 
@@ -140,20 +303,15 @@ highlighted as `isunread` only.
 
 .. _later: `ambiguous theme identifiers`_
 
-Themes
-------
-Now that you have selected components for highlighting and defined some rules,
-you need to actually decide on some colours.
-
-Generic Components
-__________________
+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`_.
 
 To define a highlighting theme for a component, you need to add a key of the
-following format to your colour theme (please cf. `colours`_ for more information
+following format to your colour theme (please cf. `Widget Colours`_ for more information
 on theming): ::
 
    search_thread_COMPONENT_ID_[focus_][fg|bg]
@@ -184,13 +342,13 @@ 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: `Tags Component`_
+.. _next section: `Theme Tags Component`_
 
-`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
-custom themed tags to provide highlighting variants.
+individual themed tags to provide highlighting variants.
 
 To specify highlighting themes for default themed tags, just add a key with the wanted
 theme identifier: ::
diff --git a/docs/user/source/index.rst b/docs/user/source/index.rst
index b94829a6..889b1496 100644
--- a/docs/user/source/index.rst
+++ b/docs/user/source/index.rst
@@ -12,5 +12,4 @@ Contents:
    :maxdepth: 2
 
    usage
-   config
-   theming
+   configuration
diff --git a/docs/user/source/usage.rst b/docs/user/source/usage.rst
index 662ecdcd..cd55af36 100644
--- a/docs/user/source/usage.rst
+++ b/docs/user/source/usage.rst
@@ -1,5 +1,6 @@
+*****
 Usage
-=====
+*****
 
 In all views, arrows, page-up/down, `j`,`k` and `Space` can be used to move the focus.
 `Escape` cancels prompts and `Enter` selects. Hit `:` at any time and type in commands