restructured user manual sources

to be more modular, which makes it easier to generate both
html docs and manpages from the same sources

6 files changed, 49 insertions, 9 deletions

diff --git a/docs/user/source/description.rst b/docs/user/source/description.rst
new file mode 100644
index 00000000..9dea9693
--- /dev/null
+++ b/docs/user/source/description.rst
@@ -0,0 +1,4 @@
+Alot is a terminal-based mail user agent for the notmuch mail system.
+It features a modular and command prompt driven interface
+to provide a full MUA experience as an alternative to the Emacs mode shipped
+with notmuch.
diff --git a/docs/user/source/index.rst b/docs/user/source/index.rst
index 889b1496..755a4e33 100644
--- a/docs/user/source/index.rst
+++ b/docs/user/source/index.rst
@@ -5,11 +5,11 @@
 
 User Manual
 ===========
-
-Contents:
+.. include:: description.rst
 
 .. toctree::
    :maxdepth: 2
+   :numbered:
 
-   usage
+   usage/index
    configuration
diff --git a/docs/user/source/manpage.rst b/docs/user/source/manpage.rst
index 009cfbf3..b83409d0 100644
--- a/docs/user/source/manpage.rst
+++ b/docs/user/source/manpage.rst
@@ -16,4 +16,6 @@ Description
 
 .. include:: description.rst
 
-#.. include:: usage.rst
+Usage
+-----
+.. include:: usage/first_steps.rst
diff --git a/docs/user/source/usage.rst b/docs/user/source/usage/first_steps.rst
index cd55af36..3ffa09ac 100644
--- a/docs/user/source/usage.rst
+++ b/docs/user/source/usage/first_steps.rst
@@ -1,9 +1,6 @@
-*****
-Usage
-*****
-
-In all views, arrows, page-up/down, `j`,`k` and `Space` can be used to move the focus.
+The arrow keys, `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
 to the prompt.
+
 Usage information on any command can be listed by typing `help YOURCOMMAND` to the prompt;
 The key bindings for the current mode are listed upon pressing `?`.
diff --git a/docs/user/source/usage/index.rst b/docs/user/source/usage/index.rst
new file mode 100644
index 00000000..f8fc11d3
--- /dev/null
+++ b/docs/user/source/usage/index.rst
@@ -0,0 +1,12 @@
+*****
+Usage
+*****
+
+Commandline invocation
+======================
+.. include:: synopsis.rst
+
+First Steps
+===========
+
+.. include:: first_steps.rst
diff --git a/docs/user/source/usage/synopsis.rst b/docs/user/source/usage/synopsis.rst
new file mode 100644
index 00000000..f26ea6e1
--- /dev/null
+++ b/docs/user/source/usage/synopsis.rst
@@ -0,0 +1,25 @@
+.. code-block:: none
+
+    alot [-r] [-c CONFIGFILE] [-n NOTMUCHCONFIGFILE] [-C {1,16,256}] [-p DB_PATH]
+         [-d {debug,info,warning,error}] [-l LOGFILE] [--version] [--help]
+         [command]
+
+Options
+
+    -r, --read-only                open db in read only mode
+    -c, --config=FILENAME          config file (default: ~/.config/alot/config)
+    -n, --notmuch-config=FILENAME  notmuch config (default: ~/.notmuch-config)
+    -C, --colour-mode=COLOR        terminal colour mode (default: 256). Must be 1, 16 or 256
+    -p, --mailindex-path=PATH      path to notmuch index
+    -d, --debug-level=LEVEL        debug log (default: info). Must be one of debug,info,warning or error
+    -l, --logfile=FILENAME         logfile (default: /dev/null)
+    --version                      Display version string and exit
+    --help                         Display  help and exit
+
+Commands
+
+    search
+        start in a search buffer using the querystring provided as
+        parameter. See the SEARCH SYNTAX section of notmuch(1).
+    compose
+        compose a new message