docs: updated commands section

3 files changed, 44 insertions, 30 deletions

diff --git a/docs/source/usage/commands b/docs/source/usage/commands
deleted file mode 100644
index daf36a1d..00000000
--- a/docs/source/usage/commands
+++ /dev/null
@@ -1,29 +0,0 @@
-.. _commands:
-
-Commands
-========
-
-:doc:`global <modes/global>`
-    globally available commands
-:doc:`search <modes/search>`
-    shows a result list of threads for a query
-:doc:`thread <modes/thread>`
-    displays a thread as a tree of messages
-:doc:`envelope <modes/envelope>`
-    message composition mode
-:doc:`bufferlist <modes/bufferlist>`
-    lists all active buffers
-:doc:`taglist <modes/taglist>`
-    lists all tagstrings present in the notmuch database
-
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-
-   modes/global
-   modes/search
-   modes/thread
-   modes/envelope
-   modes/bufferlist
-   modes/taglist
-
diff --git a/docs/source/usage/commands.rst b/docs/source/usage/commands.rst
new file mode 100644
index 00000000..6fa99b58
--- /dev/null
+++ b/docs/source/usage/commands.rst
@@ -0,0 +1,37 @@
+Commands
+========
+
+Alot interprets user input as command line strings given via its prompt
+or :ref:`bound to keys <config.key_bindings>` in the config.
+Command lines are semi-colon separated command strings, each of which
+starts with a command name and possibly followed by arguments.
+
+
+See the sections below for which commands are available in which (UI) mode.
+`global` commands are available independently of the mode.
+
+
+:doc:`modes/global`
+    globally available commands
+:doc:`modes/search`
+    commands available when showing thread search results
+:doc:`modes/thread`
+    commands available while displaying a thread
+:doc:`modes/envelope`
+    commands during message composition
+:doc:`modes/bufferlist`
+    commands while listing active buffers
+:doc:`modes/taglist`
+    commands while listing all tagstrings present in the notmuch database
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   modes/global
+   modes/search
+   modes/thread
+   modes/envelope
+   modes/bufferlist
+   modes/taglist
+
diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst
index 4992ba1c..afc10fc4 100644
--- a/docs/source/usage/index.rst
+++ b/docs/source/usage/index.rst
@@ -11,4 +11,10 @@ First Steps
 
 .. include:: first_steps
 
-.. include:: commands
+.. _commands:
+.. include:: commands.rst
+
+.. toctree::
+   :hidden:
+
+   commands