libX11 git update 14 sep 2011

1 files changed, 1789 insertions, 0 deletions

diff --git a/libX11/specs/XKB/ch17.xml b/libX11/specs/XKB/ch17.xml
new file mode 100644
index 000000000..3c44da5c1
--- /dev/null
+++ b/libX11/specs/XKB/ch17.xml
@@ -0,0 +1,1789 @@
+<chapter id='the_xkb_compatibility_map'>
+<title>The Xkb Compatibility Map</title>
+
+<para>
+As shown in Figure 17.1, the X server is normally dealing with more than one
+client, each of which may be receiving events from the keyboard, and each of
+which may issue requests to modify the keyboard in some manner. Each client may
+be either Xkb-unaware, Xkb-capable, or Xkb-aware. The server itself may be
+either Xkb-aware or Xkb-unaware. If the server is Xkb-unaware, Xkb state and
+keyboard mappings are not involved in any manner, and Xkb-aware clients may not
+issue Xkb requests to the server. If the server is Xkb-aware, the server must
+be able to deliver events and accept requests in which the keyboard state and
+mapping are compatible with the mode in which the client is operating.
+Consequently, for some situations, conversions must be made between Xkb state /
+keyboard mappings and core protocol state / keyboard mappings, and vice versa.
+</para>
+
+<mediaobject>
+ <imageobject> <imagedata format="SVG" fileref="XKBlib-18.svg"/>
+ </imageobject>
+ <caption>Server Interaction with Types of Clients</caption>
+</mediaobject>
+
+
+
+<para>
+In addition to these situations involving a single server, there are cases
+where a client that deals with multiple servers may need to configure keyboards
+on different servers to be similar and the different servers may not all be
+Xkb-aware. Finally, a client may be dealing with descriptions of keyboards
+(files, and so on) that are based on core protocol and therefore may need to be
+able to map these descriptions to Xkb descriptions.
+</para>
+
+
+<para>
+An Xkb-aware server maintains keyboard state and mapping as an Xkb keyboard
+state and an Xkb keyboard mapping plus a compatibility map used to convert from
+Xkb components to core components and vice versa. In addition, the server also
+maintains a core keyboard mapping that approximates the Xkb keyboard mapping.
+The core keyboard mapping may be updated piecemeal, on a per-key basis. When
+the server receives a core protocol <emphasis>
+ChangeKeyboardMapping</emphasis>
+ or <emphasis>
+SetModifierMapping</emphasis>
+ request, it updates its core keyboard mapping, then uses the compatibility map
+to update its Xkb keyboard mapping. When the server receives an <emphasis>
+XkbSetMap</emphasis>
+ request, it updates those portions of its Xkb keyboard mapping specified by
+the request, then uses its compatibility map to update the corresponding parts
+of its core keyboard map. Consequently, the server’s Xkb keyboard map and
+also its core keyboard map may contain components that were set directly and
+others that were computed. Figure 17.2 illustrates these relationships.
+</para>
+
+<note><para>The core keyboard map is contained only in the server, not in any
+client-side data structures.</para></note>
+
+<mediaobject>
+ <imageobject> <imagedata format="SVG" fileref="XKBlib-19.svg"/>
+ </imageobject>
+ <caption>Server Derivation of State and Keyboard Mapping Components</caption>
+</mediaobject>
+
+
+
+<para>
+There are three kinds of compatibility transformations made by the server:
+</para>
+
+<orderedlist>
+  <listitem>
+    <para><emphasis role='bold'>Xkb State to Core State</emphasis></para>
+    <para>
+Keyboard state information reported to a client in the state field of various
+core events may be translated from the Xkb keyboard state maintained by the
+server, which includes a group number, to core protocol state, which does
+not.
+    </para>
+    <para>
+In addition, whenever the Xkb state is retrieved, the <emphasis>
+compat_state</emphasis>
+, <emphasis>
+compat_grab_mods</emphasis>
+, and <emphasis>
+compat_lookup_mods</emphasis>
+ fields of the <emphasis>
+XkbStateRec</emphasis>
+ returned indicate the result of applying the compatibility map to the current
+Xkb state in the server.
+    </para>
+  </listitem>
+  <listitem>
+    <para><emphasis role='bold'>Core Keyboard Mapping to Xkb Keyboard Mapping</emphasis></para>
+    <para>
+After core protocol requests received by the server to change the keyboard
+mapping (<emphasis>
+ChangeKeyboardMapping</emphasis>
+ and <emphasis>
+SetModifierMapping</emphasis>
+) have been applied to the server’s core keyboard map, the results must be
+transformed to achieve an equivalent change of the Xkb keyboard mapping
+maintained by the server.
+    </para>
+  </listitem>
+  <listitem>
+    <para><emphasis role='bold'>Xkb Keyboard Mapping to Core Keyboard Mapping</emphasis></para>
+    <para>
+After Xkb protocol requests received by the server to change the keyboard
+mapping (<emphasis>
+XkbSetMap</emphasis>
+) have been applied to the server’s Xkb keyboard map, the results are
+transformed to achieve an approximately equivalent change to the core keyboard
+mapping maintained by the server.
+    </para>
+  </listitem>
+</orderedlist>
+
+<para>
+This chapter discusses how a client may modify the compatibility map so that
+subsequent transformations have a particular result.
+</para>
+
+
+<sect1 id='the_xkbcompatmap_structure'>
+<title>The XkbCompatMap Structure</title>
+
+<para>
+All configurable aspects of mapping Xkb state and configuration to and from
+core protocol state and configuration are defined by a compatibility map,
+contained in an <emphasis>
+XkbCompatMap</emphasis>
+ structure; plus a set of explicit override controls used to prevent particular
+components of type 2 (core-to-Xkb keyboard mapping) transformations from
+automatically occurring. These explicit override controls are maintained in a
+separate data structure discussed in section 16.3. <!-- xref -->
+</para>
+
+
+<para>
+The <emphasis>
+compat</emphasis>
+ member of an Xkb keyboard description (<emphasis>
+XkbDescRec</emphasis>
+) points to the<emphasis>
+ XkbCompatMap</emphasis>
+ structure:
+</para>
+
+<para><programlisting>
+typedef struct _XkbCompatMapRec {
+      XkbSymInterpretPtr   sym_interpret;            /* symbol based key semantics*/
+      XkbModsRec           groups[XkbNumKbdGroups];  /* group =&gt; modifier map */
+      unsigned short       num_si;                   /* # structures used in
+                                                        <emphasis>sym_interpret</emphasis> */
+      unsigned short       size_si;                  /* # structures allocated in
+                                                        <emphasis>sym_interpret</emphasis> */
+} <emphasis>XkbCompatMapRec</emphasis>, *XkbCompatMapPtr;
+</programlisting></para>
+
+<mediaobject>
+ <imageobject> <imagedata format="SVG" fileref="XKBlib-20.svg"/>
+ </imageobject>
+ <caption>Xkb Compatibility Data Structures</caption>
+</mediaobject>
+
+
+<para>
+The subsections that follow discuss how the compatibility map and explicit
+override controls are used in each of the three cases where compatibility
+transformations are made.
+</para>
+
+<sect2 id='xkb_state_to_core_protocol_state_transformation'>
+<title>Xkb State to Core Protocol State Transformation</title>
+
+<para>
+As shown in Figure 17.3, there are four <emphasis>
+group compatibility maps</emphasis>
+ (contained in <emphasis>
+groups</emphasis>
+ [0..3]) in the <emphasis>
+XkbCompatMapRec</emphasis>
+ structure, one per possible Xkb group. Each group compatibility map is a
+modifier definition (see section 7.2 for a description of modifier
+definitions). The <emphasis>
+mask</emphasis>
+ component of the definition specifies which real modifiers should be set in
+the core protocol state field when the corresponding group is active. Because
+only one group is active at any one time, only one of the four possible
+transformations is ever applied at any one point in time. If the device
+described by the <emphasis>
+XkbDescRec</emphasis>
+ does not support four groups, the extra groups fields are present, but
+undefined.
+</para>
+
+<para>
+Normally, the Xkb-aware server reports keyboard state in the <emphasis>
+state</emphasis>
+ member of events such as a <emphasis>
+KeyPress</emphasis>
+ event and <emphasis>
+ButtonPress</emphasis>
+ event, encoded as follows:
+</para>
+
+<informaltable frame='none'>
+<tgroup cols='2'>
+<colspec colsep='0'/>
+<colspec colsep='0'/>
+<thead>
+  <row rowsep='0'>
+    <entry>bits</entry>
+    <entry>meaning</entry>
+  </row>
+</thead>
+<tbody>
+  <row rowsep='0'>
+    <entry>15</entry>
+    <entry>0</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>13-14</entry>
+    <entry>Group index</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>8-12</entry>
+    <entry>Pointer Buttons</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>0-7</entry>
+    <entry>Modifiers</entry>
+  </row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+For Xkb-unaware clients, only core protocol keyboard information may be
+reported. Because core protocol does not define the group index, the group
+index is mapped to modifier bits as specified by the <emphasis>
+groups</emphasis>
+[group index] field of the compatibility map (the bits set in the compatibility
+map are ORed into bits 0-7 of the state), and bits 13-14 are reported in the
+event as zero.
+</para>
+
+</sect2>
+<sect2 id='core_keyboard_mapping_to_xkb_keyboard_mapping_transformation'>
+<title>Core Keyboard Mapping to Xkb Keyboard Mapping Transformation</title>
+
+<para>
+When a core protocol keyboard mapping request is received by the server, the
+server’s core keyboard map is updated, and then the Xkb map maintained by the
+server is updated. Because a client may have explicitly configured some of the
+Xkb keyboard mapping in the server, this automatic regeneration of the Xkb
+keyboard mapping from the core protocol keyboard mapping should not modify any
+components of the Xkb keyboard mapping that were explicitly set by a client.
+The client must set explicit override controls to prevent this from happening
+(see section 16.3). The core-to-Xkb mapping is done as follows:
+</para>
+
+<orderedlist>
+  <listitem>
+    <para>
+Map the symbols from the keys in the core keyboard map to groups and symbols on
+keys in the Xkb keyboard map. The core keyboard mapping is of fixed width, so
+each key in the core mapping has the same number of symbols associated with it.
+The Xkb mapping allows a different number of symbols to be associated with each
+key; those symbols may be divided into a different number of groups (1-4) for
+each key. For each key, this process therefore involves partitioning the fixed
+number of symbols from the core mapping into a set of variable-length groups
+with a variable number of symbols in each group. For example, if the core
+protocol map is of width five, the partition for one key might result in one
+group with two symbols and another with three symbols. A different key might
+result in two groups with two symbols plus a third group with one symbol. The
+core protocol map requires at least two symbols in each of the first two
+groups.
+    </para>
+    <orderedlist>
+      <listitem>
+        <para>
+For each changed key, determine the number of groups represented in the new
+core keyboard map. This results in a tentative group count for each key in the
+Xkb map.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+For each changed key, determine the number of symbols in each of the groups
+found in step 1a. There is one explicit override control associated with each
+of the four possible groups for each Xkb key, <emphasis>
+ExplicitKeyType1</emphasis>
+ through <emphasis>
+ExplicitKeyType4</emphasis>
+. If no explicit override control is set for a group, the number of symbols
+used for that group from the core map is two.  If the explicit override control
+is set for a group on the key, the number of symbols used for that Xkb group
+from the core map is the width of the Xkb group with one exception: because of
+the core protocol requirement for at least two symbols in each of groups one
+and two, the number of symbols used for groups one and two is the maximum of 2
+or the width of the Xkb group.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+For each changed key, assign the symbols in the core map to the appropriate
+group on the key. If the total number of symbols required by the Xkb map for a
+particular key needs more symbols than the core protocol map contains, the
+additional symbols are taken to be <emphasis>
+NoSymbol</emphasis>
+ keysyms appended to the end of the core set. If the core map contains more
+symbols than are needed by the Xkb map, trailing symbols in the core map are
+discarded. In the absence of an explicit override for group one or two, symbols
+are assigned in order by group; the first symbols in the core map are assigned
+to group one, in order, followed by group two, and so on. For example, if the
+core map contained eight symbols per key, and a particular Xkb map contained 2
+symbols for G1 and G2 and three for G3, the symbols would be assigned as (G is
+group, L is shift level):
+        </para>
+<literallayout>
+          G1L1 G1L2 G2L1 G2L2 G3L1 G3L2 G3L3
+</literallayout>
+        <para>
+If an explicit override control is set for group one or two, the symbols are
+taken from the core set in a somewhat different order. The first four symbols
+from the core set are assigned to G1L1, G1L2, G2L1, G2L2, respectively. If
+group one requires more symbols, they are taken next, and then any additional
+symbols needed by group two. Group three and four symbols are taken in complete
+sequence after group two. For example, a key with four groups and three symbols
+in each group would take symbols from the core set in the following order:
+        </para>
+<literallayout>
+G1L1 G1L2 G2L1 G2L2 G1L3 G2L3 G3L1 G3L2 G3L3 G4L1 G4L2 G4L3
+</literallayout>
+        <para>
+As previously noted, the core protocol map requires at lease two symbols in
+groups one and two. Because of this, if an explicit override control for an Xkb
+key is set and group one and / or group two is of width one, it is not possible
+to generate the symbols taken from the core protocol set and assigned to
+position G1L2 and / or G2L2.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+For each group on each changed key, assign a key type appropriate for the
+symbols in the group.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+For each changed key, remove any empty or redundant groups.
+        </para>
+      </listitem>
+    </orderedlist>
+  </listitem>
+  <listitem>
+    <para>
+At this point, the groups and their associated symbols have been assigned to
+the corresponding key definitions in the Xkb map.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Apply symbol interpretations to modify key operation. This phase is completely
+skipped if the  <emphasis>
+ExplicitInterpret</emphasis>
+ override control bit is set in the explicit controls mask for the Xkb key (see
+section 16.3).
+    </para>
+    <orderedlist>
+      <listitem>
+        <para>
+For each symbol on each changed key, attempt to match the symbol and modifiers
+from the Xkb map to a symbol interpretation describing how to generate the
+symbol.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+When a match is found in step 2a, apply the symbol interpretation to change the
+semantics associated with the symbol in the Xkb key map. If no match is found,
+apply a default interpretation.
+        </para>
+      </listitem>
+    </orderedlist>
+  </listitem>
+</orderedlist>
+
+<para>
+The symbol interpretations used in step 2 are configurable and may be specified
+using <emphasis>
+XkbSymInterpretRec</emphasis>
+ structures referenced by the <emphasis>
+sym_interpret</emphasis>
+ field of an <emphasis>
+XkbCompatMapRec</emphasis>
+ (see Figure 17.3).
+</para>
+
+<sect3 id='symbol_interpretations_the_xkbsyminterpretrec_structure'>
+<title>Symbol Interpretations — the XkbSymInterpretRec Structure</title>
+
+<para>
+Symbol interpretations are used to guide the X server when it modifies the Xkb
+keymap in step 2. An initial set of symbol interpretations is loaded by the
+server when it starts. A client may add new ones using <emphasis>
+XkbSetCompatMap</emphasis>
+ (see section 17.4).
+</para>
+
+
+<para>
+Symbol interpretations result in key semantics being set. When a symbol
+interpretation is applied, the following components of server key event
+processing may be modified for the particular key involved:
+</para>
+
+<literallayout>
+      Virtual modifier map
+      Auto repeat
+      Key behavior (may be set to <emphasis>XkbKB_Lock</emphasis>)
+      Key action (see section 16.1)
+</literallayout>
+
+<para>
+The <emphasis>XkbSymInterpretRec</emphasis>
+structure specifies a symbol interpretation:
+</para>
+
+<para><programlisting>
+typedef struct {
+      KeySym          sym;          /* keysym of interest or <emphasis>NULL</emphasis> */
+      unsigned char   flags;        /* <emphasis>XkbSI_AutoRepeat, XkbSI_LockingKey</emphasis> */
+      unsigned char   match;        /* specifies how mods is interpreted */
+      unsigned char   mods;         /* modifier bits, correspond to eight real modifiers */
+      unsigned char   virtual_mod;  /* 1 modifier to add to key virtual mod map */
+      XkbAnyAction    act;          /* action to bind to symbol position on key */
+} <emphasis>XkbSymInterpretRec</emphasis>,*XkbSymInterpretPtr;
+</programlisting></para>
+
+<para>
+If <emphasis>
+sym</emphasis>
+ is not <emphasis>
+NULL</emphasis>
+, it limits the symbol interpretation to keys on which that particular keysym
+is selected by the modifiers matching the criteria specified by <emphasis>
+mods</emphasis>
+ and <emphasis>
+match</emphasis>
+. If <emphasis>
+sym</emphasis>
+ is <emphasis>
+NULL</emphasis>
+, the interpretation may be applied to any symbol selected on a key when the
+modifiers match the criteria specified by <emphasis>
+mods</emphasis>
+ and <emphasis>
+match</emphasis>
+.
+</para>
+
+
+<para>
+<emphasis>match</emphasis>
+must be one of the values shown in Table 17.1 and specifies how the real
+modifiers specified in <emphasis>mods</emphasis>
+are to be interpreted.
+</para>
+
+<table frame='none'>
+<title>Symbol Interpretation Match Criteria</title>
+<tgroup cols='3'>
+<colspec colsep='0'/>
+<thead>
+<row rowsep='1'>
+  <entry>Match Criteria</entry>
+  <entry>Value</entry>
+  <entry>Effect</entry>
+  </row>
+</thead>
+<tbody>
+  <row rowsep='1'>
+    <entry><emphasis>XkbSI_NoneOf</emphasis></entry>
+    <entry>(0)</entry>
+    <entry>
+None of the bits that are on in <emphasis>mods</emphasis>
+ can be set, but other bits can be.
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry><emphasis>XkbSI_AnyOfOrNone</emphasis></entry>
+    <entry>(1)</entry>
+    <entry>
+Zero or more of the bits that are on in <emphasis>
+mods</emphasis>
+ can be set, as well as others.
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry><emphasis>XkbSI_AnyOf</emphasis></entry>
+    <entry>(2)</entry>
+    <entry>
+One or more of the bits that are on in <emphasis>
+mods</emphasis>
+ can be set, as well as any others.
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry><emphasis>XkbSI_AllOf</emphasis></entry>
+    <entry>(3)</entry>
+    <entry>
+All of the bits that are on in <emphasis>
+mods</emphasis>
+ must be set, but others may be set as well.
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry><emphasis>XkbSI_Exactly</emphasis></entry>
+    <entry>(4)</entry>
+    <entry>
+All of the bits that are on in <emphasis>
+mods</emphasis>
+ must be set, and no other bits may be set.
+    </entry>
+  </row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+In addition to the above bits, <emphasis>
+match</emphasis>
+ may contain the <emphasis>
+XkbSI_LevelOneOnly</emphasis>
+ bit, in which case the modifier match criteria specified by <emphasis>
+mods</emphasis>
+ and <emphasis>
+match</emphasis>
+ applies only if <emphasis>
+sym</emphasis>
+ is in level one of its group; otherwise, <emphasis>
+mods</emphasis>
+ and <emphasis>
+match</emphasis>
+ are ignored and the symbol matches a condition where no modifiers are set.
+</para>
+
+<para><programlisting>
+#define XkbSI_LevelOneOnly  (0x80)
+/* use mods + match only if sym is level 1 */
+</programlisting></para>
+
+<para>
+If no matching symbol interpretation is found, the server uses a default
+interpretation where:
+</para>
+
+<informaltable frame='none'>
+<tgroup cols='2'>
+<colspec colsep='0'/>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry><emphasis>sym</emphasis> =</entry>
+    <entry>0</entry>
+  </row>
+  <row rowsep='0'>
+    <entry><emphasis>flags</emphasis> =</entry>
+    <entry><emphasis>XkbSI_AutoRepeat</emphasis></entry>
+  </row>
+  <row rowsep='0'>
+    <entry><emphasis>match</emphasis> =</entry>
+    <entry><emphasis>XkbSI_AnyOfOrNone</emphasis></entry>
+  </row>
+  <row rowsep='0'>
+    <entry><emphasis>mods</emphasis> =</entry>
+    <entry>0</entry>
+  </row>
+  <row rowsep='0'>
+    <entry><emphasis>virtual_mod</emphasis> =</entry>
+    <entry><emphasis>XkbNoModifier</emphasis></entry>
+  </row>
+  <row rowsep='0'>
+
+   <entry><emphasis>act</emphasis> =</entry>
+    <entry><emphasis>SA_NoAction</emphasis></entry>
+  </row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+When a matching symbol interpretation is found in step 2a, the interpretation
+is applied to modify the Xkb map as follows.
+</para>
+
+<para>
+The <emphasis>
+act</emphasis>
+ field specifies a single action to be bound to the symbol position; any key
+event that selects the symbol causes the action to be taken. Valid actions are
+defined in section 16.1.
+</para>
+
+
+<para>
+If the Xkb keyboard map for the key does not have its <emphasis>
+ExplicitVModMap</emphasis>
+ control set, the <emphasis>
+XkbSI_LevelOneOnly</emphasis>
+ bit and symbol position are examined. If the <emphasis>
+XkbSI_LevelOneOnly</emphasis>
+ bit is not set in <emphasis>
+match</emphasis>
+ or the symbol is in position G1L1, the <emphasis>
+virtual_mod</emphasis>
+ field is examined. If <emphasis>
+virtual_mod</emphasis>
+ is not <emphasis>
+XkbNoModifier</emphasis>
+, <emphasis>
+virtual_mod</emphasis>
+ specifies a single virtual modifier to be added to the virtual modifier map
+for the key.<emphasis>
+ virtual_mod</emphasis>
+ is specified as an index in the range [0..15].
+</para>
+
+
+<para>
+If the matching symbol is in position G1L1 of the key, two bits in the flags
+field potentially specify additional behavior modifications:
+</para>
+
+<para><programlisting>
+#define      XkbSI_AutoRepeat    (1&lt;&lt;0)
+                                 /* key repeats if sym is in position G1L1 */
+#define      XkbSI_LockingKey    (1&lt;&lt;1)
+                                 /* set <emphasis> KB_Lock</emphasis>
+                                    behavior if sym is in psn G1L1 */
+</programlisting></para>
+
+<para>
+If the Xkb keyboard map for the key does not have its <emphasis>
+ExplicitAutoRepeat</emphasis>
+ control set, its auto repeat behavior is set based on the value of the
+<emphasis>
+XkbSI_AutoRepeat</emphasis>
+ bit. If the <emphasis>
+XkbSI_AutoRepeat</emphasis>
+ bit is set, the auto-repeat behavior of the key is turned on; otherwise, it is
+turned off.
+</para>
+
+
+<para>
+If the Xkb keyboard map for the key does not have its <emphasis>
+ExplicitBehavior</emphasis>
+ control set, its locking behavior is set based on the value of the <emphasis>
+XkbSI_LockingKey</emphasis>
+ bit. If <emphasis>
+XkbSI_LockingKey</emphasis>
+ is set, the key behavior is set to <emphasis>
+KB_Lock</emphasis>
+; otherwise, it is turned off (see section 16.3).
+</para>
+
+
+</sect3>
+</sect2>
+<sect2 id='xkb_keyboard_mapping_to_core_keyboard_mapping_transformations'>
+<title>Xkb Keyboard Mapping to Core Keyboard Mapping Transformations</title>
+
+<para>
+Whenever the server processes Xkb requests to change the keyboard mapping, it
+discards the affected portion of its core keyboard mapping and regenerates it
+based on the new Xkb mapping.
+</para>
+
+
+<para>
+When the Xkb mapping for a key is transformed to a core protocol mapping, the
+symbols for the core map are taken in the following order from the Xkb map:
+</para>
+
+
+<para>
+G1L1 G1L2 G2L1 G2L2 G1L3-n G2L3-n G3L1-n G4L1-n
+</para>
+
+
+<para>
+If group one is of width one in the Xkb map, G1L2 is taken to be NoSymbol;
+similarly, if group two is of width one in the Xkb map, G2L2 is taken to be
+NoSymbol.
+</para>
+
+
+<para>
+If the Xkb key map for a particular key has fewer groups than the core
+keyboard, the symbols for group one are repeated to fill in the missing core
+components. For example, an Xkb key with a single width-three group would be
+mapped to a core mapping counting three groups as:
+</para>
+
+
+<para>
+G1L1 G1L2 G1L1 G1L2 G1L3 G1L3 G1L1 G1L2 G1L3
+</para>
+
+
+<para>
+When a core keyboard map entry is generated from an Xkb keyboard map entry, a
+modifier mapping is generated as well. The modifier mapping contains all of the
+modifiers affected by any of the actions associated with the key combined with
+all of the real modifiers associated with any of the virtual modifiers bound to
+the key. In addition, if any of the actions associated with the key affect any
+component of the keyboard group, all of the modifiers in the <emphasis>
+mask</emphasis>
+ field of all of the group compatibility maps are added to the modifier mapping
+as well. While an <emphasis>
+XkbSA_ISOLock</emphasis>
+ action can theoretically affect any modifier, if the Xkb mapping for a key
+specifies an <emphasis>
+XkbSA_ISOLock</emphasis>
+ action, only the modifiers or group that are set by default are added to the
+modifier mapping.
+</para>
+
+
+</sect2>
+</sect1>
+<sect1 id='getting_compatibility_map_components_from_the_server'>
+<title>Getting Compatibility Map Components From the Server</title>
+
+<para>
+Use <emphasis>
+XkbGetCompatMap</emphasis>
+ to fetch any combination of the current compatibility map components from the
+server. When another client modifies the compatibility map, you are notified if
+you have selected for <emphasis>
+XkbCompatMapNotify</emphasis>
+ events (see section 17.5). <emphasis>
+XkbGetCompatMap</emphasis>
+ is particularly useful when you receive an event of this type, as it allows
+you to update your program’s version of the compatibility map to match the
+modified version now in the server. If your program is dealing with multiple
+servers and needs to configure them all in a similar manner, the updated
+compatibility map may be used to reconfigure other servers.
+</para>
+
+<note><para>To make a complete matching configuration you must also update the
+explicit override components of the server state.</para></note>
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Status <emphasis>
+XkbGetCompatMap</emphasis>
+(<emphasis>
+display, which, xkb</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Display * <emphasis>
+            display</emphasis>
+;            /* connection to server */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int<emphasis>
+            which</emphasis>
+;            /* mask of compatibility map components to fetch */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+XkbDescRec * <emphasis>
+            xkb</emphasis>
+;            /* keyboard description where results placed */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+<emphasis>
+XkbGetCompatMap</emphasis>
+ fetches the components of the compatibility map specified in <emphasis>
+which</emphasis>
+ from the server specified by <emphasis>
+display</emphasis>
+ and places them in the <emphasis>
+compat</emphasis>
+ structure of the keyboard description <emphasis>
+xkb</emphasis>
+. Valid values for <emphasis>
+which</emphasis>
+ are an inclusive OR of the values shown in Table 17.2.
+</para>
+
+<table frame='none'>
+<title>Compatibility Map Component Masks</title>
+<tgroup cols='3'>
+<colspec colsep='0'/>
+<thead>
+<row rowsep='0'>
+  <entry>Mask</entry>
+  <entry>Value</entry>
+  <entry>Affecting</entry>
+  </row>
+</thead>
+<tbody>
+  <row rowsep='0'>
+    <entry><emphasis>XkbSymInterpMask</emphasis></entry>
+    <entry>(1&lt;&lt;0)</entry>
+    <entry>Symbol interpretations</entry>
+  </row>
+  <row rowsep='0'>
+    <entry><emphasis>XkbGroupCompatMask</emphasis></entry>
+    <entry>(1&lt;&lt;1)</entry>
+    <entry>Group maps</entry>
+  </row>
+  <row rowsep='0'>
+    <entry><emphasis>XkbAllCompatMask</emphasis></entry>
+    <entry>(0x3)</entry>
+    <entry>All compatibility map components</entry>
+  </row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+If no compatibility map structure is allocated in <emphasis>
+xkb</emphasis>
+ upon entry, <emphasis>
+XkbGetCompatMap</emphasis>
+ allocates one. If one already exists, its contents are overwritten with the
+returned results.
+</para>
+
+
+<para>
+<emphasis>
+XkbGetCompatMap</emphasis>
+ fetches compatibility map information for the device specified by the
+<emphasis>
+device_spec</emphasis>
+ field of <emphasis>
+xkb</emphasis>
+. Unless you have specifically modified this field, it is the default keyboard
+device. <emphasis>
+XkbGetCompatMap</emphasis>
+ returns <emphasis>
+Success</emphasis>
+ if successful, <emphasis>
+BadAlloc</emphasis>
+ if it is unable to obtain necessary storage for either the return values or
+work space, <emphasis>
+BadMatch</emphasis>
+ if the <emphasis>
+dpy</emphasis>
+ field of the <emphasis>
+xkb</emphasis>
+ argument is non-<emphasis>
+NULL</emphasis>
+ and does not match the <emphasis>
+display</emphasis>
+ argument, and <emphasis>
+BadLength</emphasis>
+ under certain conditions caused by server or Xkb implementation errors.
+</para>
+
+
+</sect1>
+<sect1 id='using_the_compatibility_map'>
+<title>Using the Compatibility Map</title>
+
+<para>
+Xkb provides several functions that make it easier to apply the compatibility
+map to configure a client-side Xkb keyboard mapping, given a core protocol
+representation of part or all of a keyboard mapping. Obtain a core protocol
+representation of a keyboard mapping from an actual server (by using <emphasis>
+XGetKeyboardMapping</emphasis>
+, for example), a data file, or some other source.
+</para>
+
+<para>
+To update a local Xkb keyboard map to reflect the mapping expressed by a core
+format mapping by calling the function <emphasis>
+XkbUpdateMapFromCore</emphasis>
+.
+</para>
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Bool <emphasis>
+XkbUpdateMapFromCore</emphasis>
+(<emphasis>
+xkb</emphasis>
+,<emphasis>
+ first_key</emphasis>
+,<emphasis>
+ num_keys</emphasis>
+,<emphasis>
+ map_width</emphasis>
+,<emphasis>
+ core_keysyms</emphasis>
+,<emphasis>
+ changes</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+XkbDescPtr <emphasis>
+            xkb</emphasis>
+;            /* keyboard description to update */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+KeyCode <emphasis>
+            first_key</emphasis>
+;            /* keycode of first key description to update */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int <emphasis>
+            num_keys</emphasis>
+;            /* number of key descriptions to update */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int <emphasis>
+            map_width</emphasis>
+;            /* width of core protocol keymap */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+KeySym *<emphasis>
+            core_keysyms</emphasis>
+;            /* symbols in core protocol keymap */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+XkbChangesPtr       <emphasis>
+      changes</emphasis>
+;            /* backfilled with changes made to Xkb */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+<emphasis>
+XkbUpdateMapFromCore</emphasis>
+ interprets input argument information representing a keyboard map in core
+format to update the Xkb keyboard description passed in <emphasis>
+xkb</emphasis>
+. Only a portion of the Xkb map is updated — the portion corresponding to
+keys with keycodes in the range <emphasis>
+first_key</emphasis>
+ through <emphasis>
+first_key</emphasis>
+ + <emphasis>
+num_keys</emphasis>
+ - 1. If <emphasis>
+XkbUpdateMapFromCore</emphasis>
+ is being called in response to a<emphasis>
+ </emphasis>
+<emphasis>
+MappingNotify</emphasis>
+<emphasis>
+ </emphasis>
+event<emphasis>
+, first_key</emphasis>
+ and <emphasis>
+num_keys</emphasis>
+ are reported in the <emphasis>
+MappingNotify</emphasis>
+ event. <emphasis>
+core_keysyms</emphasis>
+ contains the keysyms corresponding to the keycode range being updated, in core
+keyboard description order. <emphasis>
+map_width</emphasis>
+ is the number of keysyms per key in <emphasis>
+core_keysyms</emphasis>
+. Thus, the first <emphasis>
+map_width</emphasis>
+ entries in <emphasis>
+core_keysyms</emphasis>
+ are for the key with keycode <emphasis>
+first_key</emphasis>
+, the next <emphasis>
+map_width</emphasis>
+ entries are for key <emphasis>
+first_key</emphasis>
+ + 1, and so on.
+</para>
+
+
+<para>
+In addition to modifying the Xkb keyboard mapping in <emphasis>
+xkb</emphasis>
+, <emphasis>
+XkbUpdateMapFromCore</emphasis>
+ backfills the changes structure whose address is passed in <emphasis>
+changes</emphasis>
+ to indicate the modifications that were made. You may then use <emphasis>
+changes</emphasis>
+ in subsequent calls such as <emphasis>
+XkbSetMap</emphasis>
+, to propagate the local modifications to a server.
+</para>
+
+
+<para>
+When dealing with core keyboard mappings or descriptions, it is sometimes
+necessary to determine the Xkb key types appropriate for the symbols bound to a
+key in a core keyboard mapping. Use <emphasis>
+XkbKeyTypesForCoreSymbols</emphasis>
+ for this purpose:
+</para>
+
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+int <emphasis>
+XkbKeyTypesForCoreSymbols</emphasis>
+(<emphasis>
+map_width</emphasis>
+,<emphasis>
+ core_syms</emphasis>
+,<emphasis>
+ protected, types_inout, xkb_syms_rtrn</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+XkbDescPtr<emphasis>
+      xkb</emphasis>
+;            /* keyboard description in which to place symbols*/
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int<emphasis>
+      map_width</emphasis>
+;            /* width of core protocol keymap in <emphasis>
+xkb_syms_rtrn</emphasis>
+ */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+KeySym *<emphasis>
+      core_syms</emphasis>
+;            /* core protocol format array of KeySyms */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int       <emphasis>
+protected</emphasis>
+;            /* explicit key types */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int *<emphasis>
+      types_inout;</emphasis>
+            /* backfilled with the canonical types bound to groups one and two
+for the key */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+KeySym *      <emphasis>
+xkb_syms_rtrn</emphasis>
+      ;      /* backfilled with symbols bound to the key in the Xkb mapping */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+<emphasis>
+XkbKeyTypesForCoreSymbols</emphasis>
+ expands the symbols in <emphasis>
+core_syms</emphasis>
+ and types in <emphasis>
+types_inout</emphasis>
+ according to the rules specified in section 12 of the core protocol, then
+chooses canonical key types (canonical key types are defined in section 15.2.1)
+for groups 1 and 2 using the rules specified by the Xkb protocol and places
+them in <emphasis>
+xkb_syms_rtrn</emphasis>
+, which will be non-<emphasis>
+NULL</emphasis>
+.
+</para>
+
+
+<para>
+A core keymap is a two-dimensional array of keysyms. It has <emphasis>
+map_width</emphasis>
+ columns and <emphasis>
+max_key_code</emphasis>
+ rows. <emphasis>
+XkbKeyTypesForCoreSymbols</emphasis>
+ takes a single row from a core keymap, determines the number of groups
+associated with it, the type of each group, and the symbols bound to each
+group. The return value is the number of groups, <emphasis>
+types_inout</emphasis>
+ has the types for each group, and <emphasis>
+xkb_syms_rtrn</emphasis>
+ has the symbols in Xkb order (that is, groups are contiguous, regardless of
+size).
+</para>
+
+
+<para>
+<emphasis>
+protected</emphasis>
+ contains the explicitly protected key types. There is one  explicit override
+control associated with each of the four possible groups for each Xkb key,
+<emphasis>
+ExplicitKeyType1</emphasis>
+ through <emphasis>
+ExplicitKeyType4</emphasis>
+<emphasis>
+; protected </emphasis>
+is an inclusive OR of these controls. <emphasis>
+map_width</emphasis>
+ is the width of the core keymap and is not dependent on any Xkb definitions.
+<emphasis>
+types_inout</emphasis>
+ is an array of four type indices. On input, <emphasis>
+types_inout</emphasis>
+ contains the indices of any types already assigned to the key, in case they
+are explicitly protected from change.
+</para>
+
+
+<para>
+Upon return, <emphasis>
+types_inout</emphasis>
+ contains any automatically selected (that is, canonical) types plus any
+protected types. Canonical types are assigned to all four groups if there are
+enough symbols to do so. The four entries in <emphasis>
+types_inout</emphasis>
+ correspond to the four groups for the key in question.
+</para>
+
+
+<para>
+If the groups mapping does not change, but the symbols assigned to an Xkb
+keyboard compatibility map do change, the semantics of the key may be modified.
+To apply the new compatibility mapping to an individual key to get its
+semantics updated, use <emphasis>
+XkbApplyCompatMapToKey</emphasis>
+.
+</para>
+
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Bool <emphasis>
+XkbApplyCompatMapToKey</emphasis>
+(<emphasis>
+xkb</emphasis>
+,<emphasis>
+ key</emphasis>
+,<emphasis>
+ changes</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+  XkbDescPtr<emphasis>
+            xkb;            </emphasis>
+/* keyboard description to be updated */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+  KeyCode<emphasis>
+            key</emphasis>
+;            /* key to be updated */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+  XkbChangesPtr<emphasis>
+            changes</emphasis>
+;            /* notes changes to the Xkb keyboard description */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+<emphasis>
+XkbApplyCompatMapToKey</emphasis>
+ essentially performs the operation described in section 17.1.2 to a specific
+key. This updates the behavior, actions, repeat status, and virtual modifier
+bindings of the key.
+</para>
+
+
+</sect1>
+<sect1 id='changing_the_servers_compatibility_map'>
+<title>Changing the Server’s Compatibility Map</title>
+
+<para>
+To modify the server’s compatibility map, first modify a local copy of the
+Xkb compatibility map, then call <emphasis>
+XkbSetCompatMap</emphasis>
+. You may allocate a new compatibility map for this purpose using <emphasis>
+XkbAllocCompatMap</emphasis>
+ (see section 17.6). You may also use a compatibility map from another server,
+although you need to adjust the <emphasis>
+device_spec</emphasis>
+ field in the <emphasis>
+XkbDescRec</emphasis>
+ accordingly. Note that symbol interpretations in a compatibility map
+(<emphasis>
+sym_interpret</emphasis>
+, the vector of <emphasis>
+XkbSymInterpretRec</emphasis>
+ structures) are also allocated using this same function.
+</para>
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Bool <emphasis>
+XkbSetCompatMap</emphasis>
+(<emphasis>
+display, which, xkb, update_actions</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Display * <emphasis>
+            display</emphasis>
+;            /* connection to server */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int<emphasis>
+            which</emphasis>
+;            /* mask of compat map components to set */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+XkbDescPtr <emphasis>
+            xkb</emphasis>
+;            /* source for compat map components */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Bool <emphasis>
+            update_actions</emphasis>
+;            /* <emphasis>
+True</emphasis>
+ =&gt; apply to server’s keyboard map */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+<emphasis>
+XkbSetCompatMap</emphasis>
+ copies compatibility map information from the keyboard description in
+<emphasis>
+xkb</emphasis>
+ to the server specified in <emphasis>
+display</emphasis>
+’s compatibility map for the device specified by the <emphasis>
+device_spec</emphasis>
+ field of <emphasis>
+xkb</emphasis>
+. Unless you have specifically modified this field, it is the default keyboard
+device.<emphasis>
+ which</emphasis>
+ specifies the compatibility map components to be set, and is an inclusive OR
+of the bits shown in Table 17.2.
+</para>
+
+
+<para>
+After updating its compatibility map for the specified device, if <emphasis>
+update_actions</emphasis>
+ is <emphasis>
+True,</emphasis>
+ the server applies the new compatibility map to its entire keyboard for the
+device to generate a new set of key semantics, compatibility state, and a new
+core keyboard map. If <emphasis>
+update_actions</emphasis>
+ is <emphasis>
+False</emphasis>
+, the new compatibility map is not used to generate any modifications to the
+current device semantics, state, or core keyboard map. One reason for not
+applying the compatibility map immediately would be if one server was being
+configured to match another on a piecemeal basis; the map should not be applied
+until everything is updated. To force an update at a later time, use <emphasis>
+XkbSetCompatMap</emphasis>
+ specifying <emphasis>
+which</emphasis>
+ as zero and <emphasis>
+update_actions</emphasis>
+ as <emphasis>
+True</emphasis>
+.
+</para>
+
+
+<para>
+<emphasis>
+XkbSetCompatMap</emphasis>
+ returns <emphasis>
+True</emphasis>
+ if successful and <emphasis>
+False</emphasis>
+ if unsuccessful. The server may report problems it encounters when processing
+the request subsequently via protocol errors.
+</para>
+
+
+<para>
+To add a symbol interpretation to the list of symbol interpretations in an
+<emphasis>
+XkbCompatRec</emphasis>
+, use <emphasis>
+XkbAddSymInterpret</emphasis>
+.
+</para>
+
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+XkbSymInterpretPtr <emphasis>
+XkbAddSymInterpret</emphasis>
+(<emphasis>
+xkb, si, updateMap, changes</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+XkbDescPtr<emphasis>
+            xkb</emphasis>
+;            /* keyboard description to be updated */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+XkbSymInterpretPtr<emphasis>
+            si</emphasis>
+;            /* symbol interpretation to be added */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Bool<emphasis>
+            updateMap</emphasis>
+;            /* <emphasis>
+True</emphasis>
+=&gt;apply compatibility map to keys */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+XkbChangesPtr<emphasis>
+            changes</emphasis>
+;            /* changes are put here */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+<emphasis>
+XkbAddSymInterpret</emphasis>
+ adds <emphasis>
+si</emphasis>
+ to the list of symbol interpretations in <emphasis>
+xkb</emphasis>
+. If <emphasis>
+updateMap</emphasis>
+ is <emphasis>
+True</emphasis>
+, it (re)applies the compatibility map to all of the keys on the keyboard. If
+<emphasis>
+changes</emphasis>
+ is non-<emphasis>
+NULL</emphasis>
+, it reports the parts of the keyboard that were affected (unless <emphasis>
+updateMap</emphasis>
+ is <emphasis>
+True</emphasis>
+, not much changes). <emphasis>
+XkbAddSymInterpret</emphasis>
+ returns a pointer to the actual new symbol interpretation in the list or
+<emphasis>
+NULL</emphasis>
+ if it failed.
+</para>
+
+
+</sect1>
+<sect1 id='tracking_changes_to_the_compatibility_map'>
+<title>Tracking Changes to the Compatibility Map</title>
+
+<para>
+The server automatically generates <emphasis>
+MappingNotify</emphasis>
+ events when the keyboard mapping changes. If you wish to be notified of
+changes to the compatibility map, you should select for <emphasis>
+XkbCompatMapNotify</emphasis>
+ events. If you select for <emphasis>
+XkbMapNotify</emphasis>
+ events, you no longer receive the automatically generated <emphasis>
+MappingNotify</emphasis>
+ events. If you subsequently deselect <emphasis>
+XkbMapNotifyEvent</emphasis>
+ delivery, you again receive <emphasis>
+MappingNotify</emphasis>
+ events.
+</para>
+
+
+<para>
+To receive <emphasis>
+XkbCompatMapNotify</emphasis>
+ events under all possible conditions, use <emphasis>
+XkbSelectEvents</emphasis>
+ (see section 4.3) and pass <emphasis>
+XkbCompatMapNotifyMask</emphasis>
+ in both <emphasis>
+bits_to_change</emphasis>
+ and <emphasis>
+values_for_bits</emphasis>
+.
+</para>
+
+
+<para>
+To receive <emphasis>
+XkbCompatMapNotify</emphasis>
+ events only under certain conditions, use <emphasis>
+XkbSelectEventDetails</emphasis>
+ using <emphasis>
+XkbCompatMapNotify</emphasis>
+ as the <emphasis>
+event_type</emphasis>
+ and specifying the desired map changes in <emphasis>
+bits_to_change</emphasis>
+ and <emphasis>
+values_for_bits</emphasis>
+ using mask bits from Table 17.2.
+</para>
+
+
+<para>
+Note that you are notified of changes you make yourself, as well as changes
+made by other clients.
+</para>
+
+
+<para>
+The structure for the <emphasis>
+XkbCompatMapNotifyEvent</emphasis>
+ is:
+</para>
+
+<para><programlisting>
+typedef struct {
+      int            type;          /* Xkb extension base event code */
+      unsigned long  serial;        /* X server serial number for event */
+      Bool           send_event;    /* <emphasis>True</emphasis> =&gt;
+                                       synthetically generated */
+      Display *      display;       /* server connection where event generated */
+      Time           time;          /* server time when event generated */
+      int            xkb_type;      /* <emphasis>XkbCompatMapNotify</emphasis> */
+      int            device;        /* Xkb device ID, will not be
+                                       <emphasis>XkbUseCoreKbd</emphasis> */
+      unsigned int   changed_groups;/* number of group maps changed */
+      int            first_si;      /* index to 1st changed symbol
+                                       interpretation */
+      int            num_si;        /* number of changed symbol
+                                       interpretations */
+      int            num_total_si;  /* total number of valid symbol
+                                       interpretations */
+} <emphasis>XkbCompatMapNotifyEvent</emphasis>;
+</programlisting></para>
+
+<para>
+<emphasis>
+changed_groups</emphasis>
+ is the number of group compatibility maps that have changed. If you are
+maintaining a corresponding copy of the compatibility map, or get a fresh copy
+from the server using <emphasis>
+XkbGetCompatMap</emphasis>
+, <emphasis>
+changed_groups</emphasis>
+ references <emphasis>
+groups</emphasis>
+[0..<emphasis>
+changed_groups</emphasis>
+-1] in the <emphasis>
+XkbCompatMapRec</emphasis>
+ structure.
+</para>
+
+
+<para>
+<emphasis>
+first_si</emphasis>
+ is the index of the first changed symbol interpretation, <emphasis>
+num_si</emphasis>
+ is the number of changed symbol interpretations, and <emphasis>
+num_total_si</emphasis>
+ is the total number of valid symbol interpretations. If you are maintaining a
+corresponding copy of the compatibility map, or get a fresh copy from the
+server using <emphasis>
+XkbGetCompatMap</emphasis>
+, <emphasis>
+first_si</emphasis>
+, <emphasis>
+num_si</emphasis>
+, and <emphasis>
+num_total_si</emphasis>
+ are appropriate for use with the <emphasis>
+compat.sym_interpret</emphasis>
+ vector in this structure.
+</para>
+
+
+</sect1>
+<sect1 id='allocating_and_freeing_the_compatibility_map'>
+<title>Allocating and Freeing the Compatibility Map</title>
+
+<para>
+If you are modifying the compatibility map, you need to allocate a new
+compatibility map if you do not already have one available. To do so, use
+<emphasis>
+XkbAllocCompatMap</emphasis>
+.
+</para>
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Status <emphasis>
+XkbAllocCompatMap</emphasis>
+(<emphasis>
+xkb, which, num_si</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+XkbDescPtr <emphasis>
+      xkb</emphasis>
+;            /* keyboard description in which to allocate compat map */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int<emphasis>
+      which</emphasis>
+;            /* mask of compatibility map components to allocate */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int<emphasis>
+      num_si</emphasis>
+;            /* number of symbol interpretations to allocate */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+<emphasis>
+xkb</emphasis>
+ specifies the keyboard description for which compatibility maps are to be
+allocated. The compatibility map is the <emphasis>
+compat</emphasis>
+ field in this structure.
+</para>
+
+
+<para>
+<emphasis>
+which</emphasis>
+ specifies the compatibility map components to be allocated (see <emphasis>
+XkbGetCompatMap</emphasis>
+, in section 17.2). <emphasis>
+which</emphasis>
+ is an inclusive OR of the bits shown in Table 17.2.
+</para>
+
+
+<para>
+<emphasis>
+num_si</emphasis>
+ specifies the total number of entries to allocate in the symbol interpretation
+vector (<emphasis>
+xkb.compat.sym_interpret</emphasis>
+).
+</para>
+
+
+<para>
+Note that symbol interpretations in a compatibility map (the <emphasis>
+sym_interpret</emphasis>
+ vector of <emphasis>
+XkbSymInterpretRec</emphasis>
+ structures) are also allocated using this same function. To ensure that there
+is sufficient space in the symbol interpretation vector for entries to be
+added, use <emphasis>
+XkbAllocCompatMap</emphasis>
+ specifying <emphasis>
+which</emphasis>
+ as <emphasis>
+XkbSymInterpretMask</emphasis>
+ and the number of free symbol interpretations needed in <emphasis>
+num_si</emphasis>
+.
+</para>
+
+
+<para>
+<emphasis>
+XkbAllocCompatMap</emphasis>
+ returns <emphasis>
+Success</emphasis>
+ if successful, <emphasis>
+BadMatch</emphasis>
+ if <emphasis>
+xkb</emphasis>
+ is <emphasis>
+NULL</emphasis>
+, or <emphasis>
+BadAlloc</emphasis>
+ if errors are encountered when attempting to allocate storage.
+</para>
+
+
+<para>
+To free an entire compatibility map or selected portions of one, use <emphasis>
+XkbFreeCompatMap</emphasis>
+.
+</para>
+
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+void <emphasis>
+XkbFreeCompatMap</emphasis>
+(<emphasis>
+xkb, which, free_map</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+XkbDescPtr <emphasis>
+      xkb</emphasis>
+;            /* Xkb description in which to free compatibility map */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+unsigned int<emphasis>
+      which</emphasis>
+;            /* mask of compatibility map components to free */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Bool <emphasis>
+      free_map</emphasis>
+;            /* <emphasis>
+True</emphasis>
+ =&gt; free <emphasis>
+XkbCompatMap</emphasis>
+ structure itself */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+<emphasis>
+which</emphasis>
+ specifies the compatibility map components to be freed (see <emphasis>
+XkbGetCompatMap</emphasis>
+, in section 17.2). <emphasis>
+which</emphasis>
+ is an inclusive OR of the bits shown in Table 17.2
+</para>
+
+
+<para>
+<emphasis>
+free_map</emphasis>
+ indicates whether the <emphasis>
+XkbCompatMap</emphasis>
+ structure itself should be freed. If <emphasis>
+free_map</emphasis>
+ is <emphasis>
+True</emphasis>
+, <emphasis>
+which</emphasis>
+ is ignored, all non-<emphasis>
+NULL</emphasis>
+ compatibility map components are freed, and the <emphasis>
+compat</emphasis>
+ field in the <emphasis>
+XkbDescRec</emphasis>
+ referenced by <emphasis>
+xkb</emphasis>
+ is set to <emphasis>
+NULL</emphasis>
+.
+</para>
+
+</sect1>
+</chapter>