doc/keymap-format-text-v1: update info on preserve

Signed-off-by: Ran Benita <ran234@gmail.com>

1 files changed, 17 insertions, 22 deletions

diff --git a/doc/keymap-format-text-v1.txt b/doc/keymap-format-text-v1.txt
index 95849fc..c32f44e 100644
--- a/doc/keymap-format-text-v1.txt
+++ b/doc/keymap-format-text-v1.txt
@@ -129,29 +129,24 @@ forms:
         map[Shift+Lock+LevelThree] = Level5;
         preserve[Shift+Lock+LevelThree] = Lock;
 
-  When a map entry matches the active modifiers and the level it
-  specified is chosen, then these modifiers are said to be "consumed";
-  for example, in a simple US keymap where the "g" key is assigned an
-  ordinary ALPHABETIC key type, if the Lock (Caps Lock) modifier is
-  active and the key is pressed, then a "G" keysym is produced (as
-  opposed to lower-case "g"). This is because the type definition has
-  a map entry like the following:
-
-        map[Lock] = Level2;
-
-  And as such the Lock modifier is consumed. This information is
-  relevant for applications which further process the modifiers,
-  since by then the consumed modifiers have already "done their part"
-  and should be masked out.
-
-  However, sometimes even if a modifier is actually used to choose
-  the shift level (as Lock above), it should *not* be reported as
+  When a key type is used for keysym translation, its modifiers are
+  said to be "consumed". For example, in a simple US keymap, the "g"
+  "g" key is assigned an ordinary ALPHABETIC key type, whose modifiers
+  are Shift and Lock; then for the "g" key, these two modifiers are
+  consumed by the translation. This information is relevant for
+  applications which further process the modifiers, since by then the
+  consumed modifiers have already "done their part" and should be
+  masked out.
+
+  However, sometimes even if a modifier had already affected the key
+  translation through the type, it should *not* be reported as
   consumed, for various reasons. In this case, a preserve[] statement
-  can be used to augment the map entry. The modifiers inside the square
-  brackets should match one of the map[] statements in the type. The
-  right hand side should consists of modifiers from the left hand
-  side; these modifiers are then "preserved" and not reported as
-  consumed.
+  can be used to augment the map entry. The modifiers inside the
+  square brackets should match one of the map[] statements in the type
+  (if there is no matching map entry, one mapping to Level1 is
+  implicitly added). The right hand side should consists of modifiers
+  from the type's modifiers; these modifiers are then "preserved" and
+  not reported as consumed.
 
 
 The xkb_compat section