split and update docs regarding cli-invocation

5 files changed, 50 insertions, 38 deletions

diff --git a/docs/source/usage/cli_commands.rst b/docs/source/usage/cli_commands.rst
new file mode 100644
index 00000000..b2fa28c6
--- /dev/null
+++ b/docs/source/usage/cli_commands.rst
@@ -0,0 +1,14 @@
+search
+    start in a search buffer using the querystring provided as
+    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.
+bufferlist
+    start with only a bufferlist buffer open
+taglist
+    start with only a taglist buffer open
+pyshell
+    start the interactive python shell inside alot
+    See the output of `alot pyshell --help` for more info on parameters.
diff --git a/docs/source/usage/cli_options.rst b/docs/source/usage/cli_options.rst
new file mode 100644
index 00000000..25f324ee
--- /dev/null
+++ b/docs/source/usage/cli_options.rst
@@ -0,0 +1,9 @@
+-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 or ~/.notmuch-config)
+-C, --colour-mode=COLOUR       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)
+-v, --version                  Display version string and exit
+-h, --help                     Display  help and exit
diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst
index ad207e4a..8fb96cd2 100644
--- a/docs/source/usage/index.rst
+++ b/docs/source/usage/index.rst
@@ -4,10 +4,27 @@ Usage
 
 Commandline invocation
 ======================
+.. rubric:: Synopsis
 .. include:: synopsis.rst
 
-First Steps
-===========
+.. rubric:: Options
+.. include:: cli_options.rst
+
+.. rubric:: Commands
+
+alot can be invoked with an optional subcommand from the command line.
+Those have their own parameters (see e.g. `alot search --help`).
+The following commands are available.
+
+.. include:: cli_commands.rst
+
+UNIX Signals
+============
+.. include:: signals.rst
+
+
+First Steps in the UI
+=====================
 
 .. _usage.first_steps:
 .. include:: first_steps.rst
diff --git a/docs/source/usage/signals.rst b/docs/source/usage/signals.rst
new file mode 100644
index 00000000..c1dcbc9e
--- /dev/null
+++ b/docs/source/usage/signals.rst
@@ -0,0 +1,7 @@
+.. glossary::
+
+  SIGUSR1
+    Refreshes the current buffer.
+
+  SIGINT
+    Shuts down the user interface.
diff --git a/docs/source/usage/synopsis.rst b/docs/source/usage/synopsis.rst
index b23b6df5..db246bd5 100644
--- a/docs/source/usage/synopsis.rst
+++ b/docs/source/usage/synopsis.rst
@@ -1,36 +1 @@
-.. code-block:: none
-
-    alot [-r] [-c CONFIGFILE] [-n NOTMUCHCONFIGFILE] [-C {1,16,256}] [-p DB_PATH]
-         [-d {debug,info,warning,error}] [-l LOGFILE] [-v] [-h] [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 or ~/.notmuch-config)
-    -C, --colour-mode=COLOUR       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)
-    -v, --version                  Display version string and exit
-    -h, --help                     Display  help and exit
-
-UNIX Signals
-    SIGUSR1
-        Refreshes the current buffer.
-    SIGINT
-        Shuts down the user interface.
-
-
-Subcommands
-
-    search
-        start in a search buffer using the querystring provided as
-        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.
-    pyshell
-        start the interactive python shell inside alot
-        See the output of `alot pyshell --help` for more info on parameters.
+alot [options ...] [subcommand]