diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index b8426384..b0cc0a22 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -2491,9 +2491,11 @@
 	the recipient, as MAP_SHARED may fail.
 
 	From version 11 onwards, multiple wl_keyboard.keymap events may be sent
-	within the same frame, each one with a different keymap format. Clients
-	should select at most one of these events. Clients are advised to select
-	the format with most supported features.
+	within a single frame, each representing the same keymap in a distinct
+	keymap format. Clients must select and process at most one of these
+	keymaps, ideally the one offering the greatest feature coverage, while
+	immediately closing the file descriptors corresponding to unused
+	keymaps. Keymap events sent in a later frame replace the active keymap.
       </description>
       <arg name="format" type="uint" enum="keymap_format" summary="keymap format"/>
       <arg name="fd" type="fd" summary="keymap file descriptor"/>
@@ -2515,6 +2517,9 @@
 
 	Clients should not use the list of pressed keys to emulate key-press
 	events. The order of keys in the list is unspecified.
+
+	From version 11 onwards this event is part of a wl_keyboard.frame
+	logical	event group. See wl_keyboard.frame for details.
       </description>
       <arg name="serial" type="uint" summary="serial number of the enter event"/>
       <arg name="surface" type="object" interface="wl_surface" summary="surface gaining keyboard focus"/>
@@ -2533,6 +2538,9 @@
 	defaults. The compositor must not send this event if the active surface
 	of the wl_keyboard was not equal to the surface argument immediately
 	before this event.
+
+	From version 11 onwards this event is part of a wl_keyboard.frame
+	logical	event group. See wl_keyboard.frame for details.
       </description>
       <arg name="serial" type="uint" summary="serial number of the leave event"/>
       <arg name="surface" type="object" interface="wl_surface" summary="surface that lost keyboard focus"/>
@@ -2580,6 +2588,9 @@
 	key state when a wl_keyboard.repeat_info event with a rate argument of
 	0 has been received. This allows the compositor to take over the
 	responsibility of key repetition.
+
+	From version 11 onwards this event is part of a wl_keyboard.frame
+	logical	event group. See wl_keyboard.frame for details.
       </description>
       <arg name="serial" type="uint" summary="serial number of the key event"/>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
@@ -2602,6 +2613,9 @@
 
 	In the wl_keyboard logical state, this event updates the modifiers and
 	group.
+
+	From version 11 onwards this event is part of a wl_keyboard.frame
+	logical	event group. See wl_keyboard.frame for details.
       </description>
       <arg name="serial" type="uint" summary="serial number of the modifiers event"/>
       <arg name="mods_depressed" type="uint" summary="depressed modifiers"/>
@@ -2632,6 +2646,9 @@
 	This event can be sent later on as well with a new value if necessary,
 	so clients should continue listening for the event past the creation
 	of wl_keyboard.
+
+	From version 11 onwards this event is part of a wl_keyboard.frame
+	logical	event group. See wl_keyboard.frame for details.
       </description>
       <arg name="rate" type="int"
 	   summary="the rate of repeating keys in characters per second"/>
@@ -2650,8 +2667,8 @@
 	All wl_keyboard events before a wl_keyboard.frame event belong
 	logically together. For example, multiple wl_keyboard.keymap event may
 	be sent — each one with a different format — and finally a
-	wl_keyboard.frame event. The client may use this information to select
-	the keymap format that fits best.
+	wl_keyboard.frame event. See the wl_keyboard.keymap event for more
+	details.
 
 	A wl_keyboard.frame event is sent for every logical event group,
 	even if the group only contains a single wl_keyboard event.