From f70c5968a9a612fd3f8e866f8675e5e548197dd7 Mon Sep 17 00:00:00 2001
From: Florian Bruhin <git@the-compiler.org>
Date: Tue, 12 Sep 2017 15:10:27 +0200
Subject: [PATCH] Improve documentation for command modes

---
 doc/help/commands.asciidoc        | 6 ++++--
 doc/help/settings.asciidoc        | 4 +++-
 qutebrowser/config/config.py      | 4 +++-
 qutebrowser/config/configdata.yml | 4 +++-
 4 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/doc/help/commands.asciidoc b/doc/help/commands.asciidoc
index d54396e31..9d5fd6aeb 100644
--- a/doc/help/commands.asciidoc
+++ b/doc/help/commands.asciidoc
@@ -125,7 +125,8 @@ Bind a key to a command.
 
 
 ==== optional arguments
-* +*-m*+, +*--mode*+: A comma-separated list of modes to bind the key in (default: `normal`).
+* +*-m*+, +*--mode*+: A comma-separated list of modes to bind the key in (default: `normal`). See `:help bindings.commands` for the
+ available modes.
 
 * +*-f*+, +*--force*+: Rebind the key if it is already bound.
 
@@ -938,7 +939,8 @@ Unbind a keychain.
 
 ==== positional arguments
 * +'key'+: The keychain or special key (inside <...>) to unbind.
-* +'mode'+: A mode to unbind the key in (default: `normal`).
+* +'mode'+: A mode to unbind the key in (default: `normal`). See `:help bindings.commands` for the available modes.
+
 
 [[undo]]
 === undo
diff --git a/doc/help/settings.asciidoc b/doc/help/settings.asciidoc
index 831bc354f..26e1c1732 100644
--- a/doc/help/settings.asciidoc
+++ b/doc/help/settings.asciidoc
@@ -308,7 +308,9 @@ For simple keys (no `<>`-signs), a capital letter means the key is pressed with
 If you want a binding to do nothing, bind it to the `nop` command. If you want a default binding to be passed through to the website, bind it to null.
 Note that some commands which are only useful for bindings (but not used interactively) are hidden from the command completion. See `:help` for a full list of available commands.
 The following modes are available:
+
 * normal: The default mode, where most commands are invoked.
+
 * insert: Entered when an input field is focused on a website, or by
   pressing `i` in normal mode. Passes through almost all keypresses to the
   website, but has some bindings like `<Ctrl-e>` to open an external editor.
@@ -328,7 +330,7 @@ The following modes are available:
 
 * prompt: Entered when there's a prompt to display, like for download
   locations or when invoked from JavaScript.
-
+  +
   You can bind normal keys in this mode, but they will be only active when a
   yes/no-prompt is asked. For other prompt modes, you can only bind special
   keys.
diff --git a/qutebrowser/config/config.py b/qutebrowser/config/config.py
index 155f3e0de..5d211a7b4 100644
--- a/qutebrowser/config/config.py
+++ b/qutebrowser/config/config.py
@@ -320,7 +320,8 @@ class ConfigCommands:
             command: The command to execute, with optional args, or None to
                      print the current binding.
             mode: A comma-separated list of modes to bind the key in
-                  (default: `normal`).
+                  (default: `normal`). See `:help bindings.commands` for the
+                  available modes.
             force: Rebind the key if it is already bound.
         """
         if command is None:
@@ -352,6 +353,7 @@ class ConfigCommands:
         Args:
             key: The keychain or special key (inside <...>) to unbind.
             mode: A mode to unbind the key in (default: `normal`).
+                  See `:help bindings.commands` for the available modes.
         """
         try:
             self._keyconfig.unbind(key, mode=mode, save_yaml=True)
diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index acf1832ca..c94a92859 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -2177,8 +2177,10 @@ bindings.commands:
 
     The following modes are available:
 
+
     * normal: The default mode, where most commands are invoked.
 
+
     * insert: Entered when an input field is focused on a website, or by
       pressing `i` in normal mode. Passes through almost all keypresses to the
       website, but has some bindings like `<Ctrl-e>` to open an external editor.
@@ -2198,7 +2200,7 @@ bindings.commands:
 
     * prompt: Entered when there's a prompt to display, like for download
       locations or when invoked from JavaScript.
-
+      +
       You can bind normal keys in this mode, but they will be only active when a
       yes/no-prompt is asked. For other prompt modes, you can only bind special
       keys.