Bring back accidentally deleted hunk

doc/help/settings.asciidoc

@@ -306,9 +306,9 @@ Default: +pass:[auto]+
 [[bindings.commands]]
 === bindings.commands
 Keybindings mapping keys to commands in different modes.
+While it's possible to add bindings with this setting, it's recommended to use `config.bind()` in `config.py` or the `:bind` command, and leave this setting alone.
 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:
 

qutebrowser/config/configdata.yml

@@ -2187,9 +2187,73 @@ bindings.commands:
   desc: >-
     Keybindings mapping keys to commands in different modes.
 
+    While it's possible to add bindings with this setting, it's recommended to
+    use `config.bind()` in `config.py` or the `:bind` command, and leave this
+    setting alone.
+
     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
+    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:
+
+      * 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`.