Improve bindings.key_mappings description

(cherry picked from commit 3dc5584cac2a588828dbd50ba441c04ad27e6d17)

2 files changed, 14 insertions, 6 deletions

diff --git a/doc/help/settings.asciidoc b/doc/help/settings.asciidoc
index 7a5cfd47b..ca97fa973 100644
--- a/doc/help/settings.asciidoc
+++ b/doc/help/settings.asciidoc
@@ -16,7 +16,7 @@
 |<<backend,backend>>|Backend to use to display websites.
 |<<bindings.commands,bindings.commands>>|Keybindings mapping keys to commands in different modes.
 |<<bindings.default,bindings.default>>|Default keybindings. If you want to add bindings, modify `bindings.commands` instead.
-|<<bindings.key_mappings,bindings.key_mappings>>|This setting can be used to map keys to other keys.
+|<<bindings.key_mappings,bindings.key_mappings>>|Map keys to other keys, so that they are equivalent in all modes.
 |<<changelog_after_upgrade,changelog_after_upgrade>>|When to show a changelog after qutebrowser was upgraded.
 |<<colors.completion.category.bg,colors.completion.category.bg>>|Background color of the completion widget category headers.
 |<<colors.completion.category.border.bottom,colors.completion.category.border.bottom>>|Bottom border color of the completion widget category headers.
@@ -774,9 +774,10 @@ Default:
 
 [[bindings.key_mappings]]
 === bindings.key_mappings
-This setting can be used to map keys to other keys.
+Map keys to other keys, so that they are equivalent in all modes.
 When the key used as dictionary-key is pressed, the binding for the key used as dictionary-value is invoked instead.
-This is useful for global remappings of keys, for example to map Ctrl-[ to Escape.
+This is useful for global remappings of keys, for example to map <Ctrl-[> to <Escape>.
+NOTE: This should only be used if two keys should always be equivalent, i.e. for things like <Enter> (keypad) and <Return> (non-keypad). For normal command bindings, qutebrowser works differently to vim: You always bind keys to commands, usually via `:bind` or `config.bind()`. Instead of using this setting, consider finding the command a key is bound to (e.g. via `:bind gg`) and then binding the same command to the desired key.
 Note that when a key is bound (via `bindings.default` or `bindings.commands`), the mapping is ignored.
 
 Type: <<types,Dict>>
diff --git a/qutebrowser/config/configdata.yml b/qutebrowser/config/configdata.yml
index 22a4b2151..2e0f409ee 100644
--- a/qutebrowser/config/configdata.yml
+++ b/qutebrowser/config/configdata.yml
@@ -3232,13 +3232,20 @@ bindings.key_mappings:
     keytype: Key
     valtype: Key
   desc: >-
-    This setting can be used to map keys to other keys.
+    Map keys to other keys, so that they are equivalent in all modes.
 
     When the key used as dictionary-key is pressed, the binding for the key
     used as dictionary-value is invoked instead.
 
-    This is useful for global remappings of keys, for example to map Ctrl-[ to
-    Escape.
+    This is useful for global remappings of keys, for example to map <Ctrl-[> to
+    <Escape>.
+
+    NOTE: This should only be used if two keys should always be equivalent, i.e. for
+    things like <Enter> (keypad) and <Return> (non-keypad). For normal command bindings,
+    qutebrowser works differently to vim: You always bind keys to commands, usually via
+    `:bind` or `config.bind()`. Instead of using this setting, consider finding the
+    command a key is bound to (e.g. via `:bind gg`) and then binding the same command to
+    the desired key.
 
     Note that when a key is bound (via `bindings.default` or
     `bindings.commands`), the mapping is ignored.