diff --git a/kitty/options/definition.py b/kitty/options/definition.py
index 55c799857..9315c7319 100644
--- a/kitty/options/definition.py
+++ b/kitty/options/definition.py
@@ -3452,7 +3452,7 @@ For example::
 You can create mappings that apply when the focused window matches some condition,
 such as having a particular program running. For example::
 
-    map --when-focus-on title:keyboard.protocol kitty_mod+t
+    map --when-focus-on "title:keyboard.protocol" kitty_mod+t
 
 This will cause :kbd:`kitty_mod+t` (the default shortcut for opening a new tab)
 to be unmapped only when the focused window
@@ -3463,9 +3463,7 @@ has :code:`keyboard protocol` in its title. Run the show-key kitten as::
 and press :kbd:`ctrl+shift+t` and instead of a new tab opening, you will
 see the key press being reported by the kitten. :code:`--when-focus-on` can test
 the focused window using very powerful criteria, see :ref:`search_syntax` for
-details. Note that spaces are not allowed in the argument of --when-focus-on.
-Use the . character or :code:`\\\\s` to match spaces.
-A more practical example unmaps the key when the focused window is running vim::
+details. A more practical example unmaps the key when the focused window is running vim::
 
     map --when-focus-on var:in_editor
 
diff --git a/kitty/options/utils.py b/kitty/options/utils.py
index 0463cf34f..f6ffbf81c 100644
--- a/kitty/options/utils.py
+++ b/kitty/options/utils.py
@@ -26,7 +26,7 @@ from kitty.conf.utils import (
     unit_float,
 )
 from kitty.constants import is_macos
-from kitty.fast_data_types import CURSOR_BEAM, CURSOR_BLOCK, CURSOR_UNDERLINE, Color, SingleKey
+from kitty.fast_data_types import CURSOR_BEAM, CURSOR_BLOCK, CURSOR_UNDERLINE, Color, Shlex, SingleKey
 from kitty.fonts import FontFeature, FontModification, ModificationType, ModificationUnit, ModificationValue
 from kitty.key_names import character_key_name_aliases, functional_key_name_aliases, get_key_name_lookup
 from kitty.rgb import color_as_int
@@ -1212,11 +1212,12 @@ class KeyboardMode:
 KeyboardModeMap = Dict[str, KeyboardMode]
 
 
-def parse_options_for_map(val: str) -> Tuple[KeyMapOptions, List[str]]:
+def parse_options_for_map(val: str) -> Tuple[KeyMapOptions, str]:
     expecting_arg = ''
     ans = KeyMapOptions()
-    parts = val.split()
-    for i, x in enumerate(parts):
+    s = Shlex(val)
+    while (tok := s.next_word())[0] > -1:
+        x = tok[1]
         if expecting_arg:
             object.__setattr__(ans, expecting_arg, x)
             expecting_arg = ''
@@ -1231,8 +1232,8 @@ def parse_options_for_map(val: str) -> Tuple[KeyMapOptions, List[str]]:
                 object.__setattr__(ans, k, v)
                 expecting_arg = ''
         else:
-            return ans, parts[i:]
-    return ans, []
+            return ans, val[tok[0]:]
+    return ans, ''
 
 
 def parse_map(val: str) -> Iterable[KeyDefinition]:
@@ -1241,7 +1242,8 @@ def parse_map(val: str) -> Iterable[KeyDefinition]:
     if len(parts) == 2:
         sc, action = parts
         if sc.startswith('--'):
-            options, parts = parse_options_for_map(val)
+            options, leftover = parse_options_for_map(val)
+            parts = leftover.split(maxsplit=1)
             if len(parts) == 1:
                 sc, action = parts[0], ''
             else: