Improve bind documentation

[ci skip]

doc/help/configuring.asciidoc

@@ -66,6 +66,9 @@ link:commands.html#unbind[`:unbind`] commands:
 Key chains starting with a comma are ideal for custom bindings, as the comma key
 will never be used in a default keybinding.
 
+See the help pages linked above (or `:help :bind`, `:help :unbind`) for more
+information.
+
 Configuring qutebrowser via config.py
 -------------------------------------
 
@@ -159,28 +162,39 @@ To bind a key:
 .config.py:
 [source,python]
 ----
-config.bind(',v', 'spawn mpv {url}', mode='normal')
+config.bind('<Ctrl-v>', 'spawn mpv {url}')
 ----
 
-For bindings in normal mode, you can also leave out the `, mode='normal'` part.
+To bind a key in a mode other than `'normal'`, add a `mode` argument:
+
+[source,python]
+----
+config.bind('<Ctrl-y>', 'prompt-yes', mode='prompt')
+----
 
 If the key is already bound, `force=True` needs to be given to rebind it:
 
 [source,python]
 ----
-config.bind(',v', 'message-info foo', mode='normal', force=True)
+config.bind('<Ctrl-v>', 'message-info foo', force=True)
 ----
 
 To unbind a key (either a key which has been bound before, or a default binding):
 
 [source,python]
 ----
-config.unbind(',v', mode='normal')
+config.unbind('<Ctrl-v>', mode='normal')
 ----
 
-Key chains starting with a comma are ideal for custom bindings, as the comma key
+To bind keys without modifiers, specify a key chain to bind as a string. Key
+chains starting with a comma are ideal for custom bindings, as the comma key
 will never be used in a default keybinding.
 
+[source,python]
+----
+config.bind(',v', 'spawn mpv {url}')
+----
+
 To suppress loading of any default keybindings, you can set
 `c.bindings.default = {}`.
 

doc/help/settings.asciidoc

@@ -308,6 +308,7 @@ Default: +pass:[auto]+
 Keybindings mapping keys to commands in different modes.
 This setting is a dictionary containing mode names and dictionaries mapping keys to commands:
 `{mode: {key: command}}`
+While it's possible to bind keys by modifying this setting, it's recommended to use the `config.bind()` function or `:bind` command, which makes modifying it easier and checks for more possible mistakes.
 If you want to map a key to another key, check the `bindings.key_mappings` setting instead.
 For special keys (can't be part of a keychain), enclose them in `<`...`>`. For modifiers, you can use either `-` or `+` as delimiters, and these names:
 
@@ -364,7 +365,7 @@ Default: empty
 === bindings.default
 Default keybindings. If you want to add bindings, modify `bindings.commands` instead.
 The main purpose of this setting is that you can set it to an empty dictionary if you want to load no default keybindings at all.
-If you want to preserve default bindings (and get new bindings when there is an update), add new bindings to `bindings.commands` (or use `:bind`) and leave this setting alone.
+If you want to preserve default bindings (and get new bindings when there is an update), use `config.bind()` in `config.py` or the `:bind` command, and leave this setting alone.
 
 Type: <<types,Dict>>
 

qutebrowser/config/configdata.yml

@@ -2167,7 +2167,7 @@ bindings.default:
     want to load no default keybindings at all.
 
     If you want to preserve default bindings (and get new bindings when there is
-    an update), add new bindings to `bindings.commands` (or use `:bind`) and
+    an update), use `config.bind()` in `config.py` or the `:bind` command, and
     leave this setting alone.
 
 bindings.commands:
@@ -2193,64 +2193,4 @@ bindings.commands:
 
     `{mode: {key: command}}`
 
-    If you want to map a key to another key, check the `bindings.key_mappings`
+    While it's possible to bind keys by modifying this setting, it's recommended
-    setting instead.
-
-    For special keys (can't be part of a keychain), enclose them in `<`...`>`.
-    For modifiers, you can use either `-` or `+` as delimiters, and these names:
-
-      * Control: `Control`, `Ctrl`
-
-      * Meta:    `Meta`, `Windows`, `Mod4`
-
-      * Alt:     `Alt`, `Mod1`
-
-      * Shift:   `Shift`
-
-    For simple keys (no `<>`-signs), a capital letter means the key is pressed
-    with Shift. For special keys (with `<>`-signs), you need to explicitly add
-    `Shift-` to match a key pressed with shift.
-
-    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.
-      Note that single keys can't be bound in this mode.
-
-    * hint: Entered when `f` is pressed to select links with the keyboard. Note
-      that single keys can't be bound in this mode.
-
-    * passthrough: Similar to insert mode, but passes through all keypresses
-      except `<Escape>` to leave the mode. It might be useful to bind `<Escape>`
-      to some other key in this mode if you want to be able to send an Escape
-      key to the website as well. Note that single keys can't be bound in this
-      mode.
-
-    * command: Entered when pressing the `:` key in order to enter a command.
-      Note that single keys can't be bound in this mode.
-
-    * 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.
-
-    * caret: Entered when pressing the `v` mode, used to select text using the
-      keyboard.
-
-    * register: Entered when qutebrowser is waiting for a register name/key for
-      commands like `:set-mark`.