diff --git a/docs/conf.py b/docs/conf.py
index bf5bf4d87..decc3d72c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -525,9 +525,12 @@ def process_shortcut_link(env, refnode, has_explicit_title, title, target):
         conf_name, slug = 'kitty', conf_name
     full_name = conf_name + '.' + slug
     try:
-        target, title = shortcut_slugs[full_name]
+        target, stitle = shortcut_slugs[full_name]
     except KeyError:
         logger.warning('Unknown shortcut: {}'.format(target), location=refnode)
+    else:
+        if not has_explicit_title:
+            title = stitle
     return title, target
 
 
diff --git a/docs/faq.rst b/docs/faq.rst
index 50899a58f..dba97c702 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -162,3 +162,31 @@ Bringing up applications on a single key press is the job of the window
 manager/desktop environment. For ways to do it with kitty (or indeed any
 terminal) in different environments,
 see `here <https://github.com/kovidgoyal/kitty/issues/45>`_.
+
+
+How do I map key presses in kitty to different keys in the terminal program?
+--------------------------------------------------------------------------------------
+
+This is accomplished by using ``map`` with :sc:`send_text <send_text>` in :file:`kitty.conf`.
+For example::
+
+    map alt+s send_text all \x13
+
+This maps :kbd:`alt+s`` to :kbd:`ctrl+s`. To figure out what bytes to use for
+the :sc:`send_text <send_text>` you can use the ``showkey`` utility. Run::
+
+    showkey -a
+
+Then press the key you want to emulate. On macOS, this utility is currently not
+available. The manual way to figure it out is:
+
+    1. Look up your key's decimal value in the table at the bottom of `this
+       page <http://ascii-table.com/ansi-escape-sequences.php>`_ or any
+       ANSI escape sequence table. There are different modifiers for :kbd:`ctrl`,
+       :kbd:`alt`, etc. For e.g., for :kbd:`ctrl+s`, find the ``S`` row and look at
+       the third column value, ``19``.
+
+    2. Convert the decimal value to hex with ``kitty +runpy "print(hex(19))"``.
+       This shows the hex value, ``13`` in this case.
+
+    3. Use ``\x(hexval)`` in your ``send_text`` command in kitty. So in this example, ``\x13``
diff --git a/kitty/config_data.py b/kitty/config_data.py
index 4dd961bd1..6610fce56 100644
--- a/kitty/config_data.py
+++ b/kitty/config_data.py
@@ -1209,7 +1209,7 @@ You can create shortcuts to clear/reset the terminal. For example::
     # Scroll the contents of the screen into the scrollback
     map kitty_mod+f12 clear_terminal scroll active
 
-If you want to operate on all windows instead of just the current one, use :italic:`all` instead of :italic`active`.
+If you want to operate on all windows instead of just the current one, use :italic:`all` instead of :italic:`active`.
 
 It is also possible to remap Ctrl+L to both scroll the current screen contents into the scrollback buffer
 and clear the screen, instead of just clearing the screen::