@@ -28,7 +28,7 @@
     hotkeys: it describes a trigger and the compositor accepts it or rejects it
     with a reason. A hotkey fires regardless of which surface holds keyboard
     focus. The compositor remains the arbiter and may deny a commit or revoke a
-    binding at any time.
+    binding at any time, but the client chooses the trigger.
 
     The key words "must", "must not", "required", "shall", "shall not",
     "should", "should not", "recommended", "may", and "optional" in this
@@ -45,11 +45,6 @@
     may grant the same trigger to several bindings, in which case each bound
     hotkey receives the events. Clients must cope with either.
 
-    Warning! The protocol described in this file is currently in the
-    experimental phase. Backwards incompatible major versions of the protocol
-    are to be expected. Exposing this protocol without an opt-in mechanism is
-    discouraged.
-
     Security considerations:
 
     A global hotkey lets an unfocused client observe that a specific trigger
@@ -80,6 +75,11 @@
     The protocol's one hard guarantee is containment: a compositor must not
     deliver events for a trigger the client did not successfully bind, and never
     forwards the raw input stream.
+
+    Warning! The protocol described in this file is currently in the
+    experimental phase. Backwards incompatible major versions of the protocol
+    are to be expected. Exposing this protocol without an opt-in mechanism is
+    discouraged.
   </description>
 
   <interface name="xx_hotkey_manager_v1" version="1">
@@ -98,6 +98,9 @@
     <enum name="modifiers" bitfield="true">
       <description summary="modifier keys required by a trigger">
         A bitmask of the modifiers that must be held for the trigger to fire.
+        The match is exact: a trigger does not fire while a modifier outside
+        its mask is held, so Super+Space does not fire on Super+Shift+Space.
+        Bits outside this enum raise the "invalid_trigger" error.
 
         These are fixed, keymap-independent semantic bits. A compositor matches
         each bit against the corresponding modifier in its keyboard state as the
@@ -171,7 +174,7 @@
         compositor is reported through "denied" and is not an error.
       </description>
       <entry name="invalid_trigger" value="0"
-             summary="a null keysym"/>
+             summary="a null keysym, or unknown modifier bits"/>
       <entry name="no_trigger" value="1"
              summary="commit was sent before any trigger was described"/>
     </enum>
@@ -183,8 +186,7 @@
         may describe a different trigger and commit again.
 
         A compositor is not obliged to distinguish "already_bound" from
-        "not_permitted" and may report the latter for both. A client that
-        receives an unrecognised value must treat it as "not_permitted".
+        "not_permitted" and may report the latter for both.
       </description>
       <entry name="already_bound" value="0"
              summary="held by another hotkey the compositor treats as exclusive"/>
@@ -212,6 +214,7 @@
       <description summary="restrict the hotkey to one seat">
         Restrict the hotkey to the given seat, or pass null for all of the
         client's seats, virtual ones included. Optional; the default is null.
+        If the given seat is removed, the compositor sends "revoked".
       </description>
       <arg name="seat" type="object" interface="wl_seat" allow-null="true"
            summary="target seat, or null for all of the client's seats"/>
@@ -225,13 +228,17 @@
 
         The keysym uses the numbering shared with the keymap delivered over
         wl_keyboard (for the xkb_v1 keymap format, an XKB_KEY_* value), in its
-        unshifted form (XKB_KEY_b, not XKB_KEY_B). A compositor should match it
-        against any of the user's layout groups, so that a binding keeps firing
-        after a layout group switch.
+        unshifted form (XKB_KEY_b, not XKB_KEY_B). The compositor matches it
+        against the keysym each key produces at its first shift level in any of
+        the user's layout groups, ignoring the effect Shift has on the key, so
+        that Shift is handled through the modifier mask like every other
+        modifier and a binding keeps firing after a layout group switch. A
+        binding whose keysym no group of the current keymap produces stays
+        bound and simply does not fire until the keymap changes again.
 
         The trigger fires on key press; the compositor does not wait to see
-        whether another key follows. The press is consumed and must not be
-        delivered to the focused surface.
+        whether another key follows. The press and the matching release are
+        consumed and must not be delivered to the focused surface.
 
         The keysym may be one that contributes to modifier state, such as
         XKB_KEY_Super_L; whether it does is decided by the seat's keymap. Such a
@@ -262,8 +269,8 @@
 
         The button is a button code in the same space as wl_pointer.button.
 
-        The press is consumed and must not be delivered to the surface under the
-        pointer.
+        The press and the matching release are consumed and must not be
+        delivered to the surface under the pointer.
       </description>
       <arg name="button" type="uint" summary="button code, as in wl_pointer.button"/>
       <arg name="modifiers" type="uint" enum="xx_hotkey_manager_v1.modifiers"
@@ -279,9 +286,12 @@
         "no_trigger" error.
 
         Commit may be sent again to apply a changed trigger, description or
-        seat, keeping the binding's identity. An established binding survives a
-        rejected commit: the previous state stays active, so a denied
-        reconfiguration never leaves the user with no hotkey.
+        seat, keeping the binding's identity. Values set with set_* requests are
+        retained across commits, accepted or denied, and each commit applies
+        all of them; committing with nothing changed is accepted with "bound".
+        An established binding survives a rejected commit: the previous state
+        stays active, so a denied reconfiguration never leaves the user with no
+        hotkey.
       </description>
     </request>
 
@@ -337,9 +347,10 @@
 
     <event name="released">
       <description summary="the hotkey was released">
-        The trigger of a previously triggered hotkey was released. This enables
-        press-and-hold uses such as push-to-talk; clients that only act on
-        the initial firing may ignore it.
+        The key or button of a previously triggered hotkey was released,
+        regardless of modifier state. This enables press-and-hold uses such as
+        push-to-talk; clients that only act on the initial firing may ignore
+        it.
 
         serial and time have the same meaning as in the "triggered" event.
       </description>