docs: usage cleanup

7 files changed, 24 insertions, 14 deletions

diff --git a/docs/source/configuration/hooks.rst b/docs/source/configuration/hooks.rst
index 7475a237..40b46271 100644
--- a/docs/source/configuration/hooks.rst
+++ b/docs/source/configuration/hooks.rst
@@ -4,9 +4,10 @@ Hooks
 =====
 Hooks are python callables that live in a module specified by `hooksfile` in the
 config. Per default this points to :file:`~/.config/alot/hooks.py`.
-When a hook gets called it receives a reference to the :class:`main user interface <alot.ui.UI>` and the
-:class:`database manager <alot.db.DBManager>`.
-For every :ref:`COMMAND <commands>` in mode :ref:`MODE <modes>`, the callables :func:`pre_MODE_COMMAND` and :func:`post_MODE_COMMAND`
+
+.. rubric:: Pre/Post Command Hooks
+
+For every :ref:`COMMAND <usage.commands>` in mode :ref:`MODE <modes>`, the callables :func:`pre_MODE_COMMAND` and :func:`post_MODE_COMMAND`
 -- if defined -- will be called before and after the command is applied respectively. The signature for the
 pre-`send` hook in envelope mode for example looks like this:
 
@@ -15,7 +16,7 @@ pre-`send` hook in envelope mode for example looks like this:
     :param ui: the main user interface
     :type ui: :class:`alot.ui.UI`
     :param dbm: a database manager
-    :type dbm: :class:`alot.db.DBManager`
+    :type dbm: :class:`alot.db.manager.DBManager`
 
 Consider this pre-hook for the exit command, that logs a personalized goodbye message::
 
@@ -28,6 +29,8 @@ Consider this pre-hook for the exit command, that logs a personalized goodbye me
         else:
             logging.info('goodbye!')
 
+.. rubric:: Other Hooks
+
 Apart from command pre- and posthooks, the following hooks will be interpreted:
 
 .. py:function:: reply_prefix(realname, address, timestamp[, ui= None, dbm=None])
diff --git a/docs/source/description b/docs/source/description.rst
index 9dea9693..9dea9693 100644
--- a/docs/source/description
+++ b/docs/source/description.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 9500aaa8..323bec4c 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -5,7 +5,7 @@
 
 User Manual
 ===========
-.. include:: description
+.. include:: description.rst
 
 .. toctree::
    :maxdepth: 2
@@ -22,3 +22,4 @@ User Manual
    :hidden:
 
    manpage
+   description
diff --git a/docs/source/manpage.rst b/docs/source/manpage.rst
index bfdf43da..0e53d82b 100644
--- a/docs/source/manpage.rst
+++ b/docs/source/manpage.rst
@@ -4,16 +4,16 @@ Manpage
 Synopsis
 --------
 
-.. include:: usage/synopsis
+.. include:: usage/synopsis.rst
 
 Description
 -----------
 
-.. include:: description
+.. include:: description.rst
 
 Usage
 -----
-.. include:: usage/first_steps
+.. include:: usage/first_steps.rst
 
 
 See Also
diff --git a/docs/source/usage/first_steps b/docs/source/usage/first_steps.rst
index e99c44ce..707b2766 100644
--- a/docs/source/usage/first_steps
+++ b/docs/source/usage/first_steps.rst
@@ -2,7 +2,7 @@ The arrow keys, `page-up/down`, `j`, `k` and `Space` can be used to move the foc
 `Escape` cancels prompts and `Enter` selects. Hit `:` at any time and type in commands
 to the prompt.
 
-The interface shows one buffer at a time, you can use `tab` and `Shift-Tab` to switch
+The interface shows one buffer at a time, you can use `Tab` and `Shift-Tab` to switch
 between them, close the current buffer with `d` and list them all with `;`.
 
 The buffer type or *mode* (displayed at the bottom left) determines which prompt commands
diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst
index afc10fc4..224f831a 100644
--- a/docs/source/usage/index.rst
+++ b/docs/source/usage/index.rst
@@ -4,17 +4,21 @@ Usage
 
 Commandline invocation
 ======================
-.. include:: synopsis
+.. include:: synopsis.rst
 
 First Steps
 ===========
 
-.. include:: first_steps
+.. _usage.first_steps:
+.. include:: first_steps.rst
 
-.. _commands:
+.. _usage.commands:
 .. include:: commands.rst
 
 .. toctree::
    :hidden:
 
    commands
+   first_steps
+   synopsis
+
diff --git a/docs/source/usage/synopsis b/docs/source/usage/synopsis.rst
index 5bfb8e88..a6e776d4 100644
--- a/docs/source/usage/synopsis
+++ b/docs/source/usage/synopsis.rst
@@ -17,10 +17,12 @@ Options
     --help                         Display  help and exit
 
 
-Commands
+Subommands
 
     search
         start in a search buffer using the querystring provided as
-        parameter. See the SEARCH SYNTAX section of notmuch(1).
+        parameter. See also the SEARCH SYNTAX section of notmuch(1)
+        and the output of `alot search --help`.
     compose
         compose a new message
+        See the output of `alot compose --help` for more info on parameters.