libX11 git update 14 sep 2011

1 files changed, 818 insertions, 0 deletions

diff --git a/libX11/specs/XKB/ch02.xml b/libX11/specs/XKB/ch02.xml
new file mode 100644
index 000000000..55f15a322
--- /dev/null
+++ b/libX11/specs/XKB/ch02.xml
@@ -0,0 +1,818 @@
+<chapter id='initialization_and_general_programming_information'>
+<title>Initialization and General Programming Information</title>
+<sect1 id='extension_header_files'>
+<title>Extension Header Files</title>
+<para>
+The following include files are part of the Xkb standard:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+<emphasis>&lt;X11/XKBlib.h&gt;</emphasis>
+    </para>
+    <para><emphasis>XKBlib.h</emphasis>
+is the main header file for Xkb; it declares constants, types, and
+functions.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<emphasis>&lt;X11/extensions/XKBstr.h&gt;</emphasis>
+    </para>
+    <para>
+<emphasis>XKBstr.h</emphasis> declares types and
+constants for Xkb. It is included automatically from
+<emphasis>&lt;X11/XKBlib.h&gt;</emphasis>
+; you should never need to reference it directly in your application code.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<emphasis>&lt;X11/extensions/XKB.h&gt;</emphasis>
+    </para>
+    <para>
+<emphasis>XKB.h</emphasis>
+defines constants for Xkb. It is included automatically from <emphasis>
+&lt;X11/XKBstr.h&gt;</emphasis>
+; you should never need to reference it directly in your application code.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<emphasis>&lt;X11/extensions/XKBgeom.h&gt;</emphasis>
+   </para>
+   <para><emphasis>XKBgeom.h</emphasis>
+declares types, symbolic constants, and functions for manipulating
+keyboard geometry descriptions.
+    </para>
+  </listitem>
+</itemizedlist>
+</sect1>
+<sect1 id='extension_name'>
+<title>Extension Name</title>
+<para>
+The name of the Xkb extension is given in <emphasis>
+&lt;X11/extensions/Xkb.h&gt;:</emphasis>
+</para>
+
+<para>
+<emphasis>
+#define XkbName "XKEYBOARD"</emphasis>
+</para>
+
+<para>
+Most extensions to the X protocol are initialized by calling <emphasis>
+XInitExtension</emphasis>
+ and passing the extension name. However, as explained in section 2.4, Xkb
+requires a more complex initialization sequence, and a client program should
+not call <emphasis>
+XInitExtension</emphasis>
+ directly.
+</para>
+</sect1>
+<sect1 id='determining_library_compatibility'>
+<title>Determining Library Compatibility</title>
+<para>
+If an application is dynamically linked, both the X server and the client-side
+X library must contain the Xkb extension in order for the client to use the Xkb
+extension capabilities. Therefore a dynamically linked application must check
+both the library and the server for compatibility before using Xkb function
+calls. A properly written program must check for compatibility between the
+version of the Xkb library that is dynamically loaded and the one used when the
+application was built. It must then check the server version for compatibility
+with the version of Xkb in the library.
+</para>
+<para>
+If your application is statically linked, you must still check for server
+compatibility and may check library compatibility. (It is possible to compile
+against one set of header files and link against a different, incompatible,
+version of the library, although this should not normally occur.)
+</para>
+<para>
+To determine the compatibility of a library at runtime, call <emphasis>
+XkbLibraryVersion</emphasis>.
+</para>
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Bool <emphasis>
+XkbLibraryVersion</emphasis>
+(<emphasis>
+lib_major_in_out</emphasis>
+, <emphasis>
+lib_minor_in_out</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int *      <emphasis>
+lib_major_in_out;</emphasis>
+                  /* specifies and returns the major Xkb library version. */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int *      <emphasis>
+lib_minor_in_out;</emphasis>
+                  /* specifies and returns the minor Xkb library version. */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+Pass the symbolic value <emphasis>
+XkbMajorVersion</emphasis>
+ in <emphasis>
+lib_major_in_out</emphasis>
+ and <emphasis>
+XkbMinorVersion</emphasis>
+ in <emphasis>
+lib_minor_in_out</emphasis>
+. These arguments represent the version of the library used at compile time.
+The <emphasis>
+XkbLibraryVersion </emphasis>
+function backfills the major and minor version numbers of the library used at
+run time in <emphasis>
+lib_major_in_out</emphasis>
+ and <emphasis>
+lib_minor_in_out</emphasis>
+. If the versions of the compile time and run time libraries are compatible,
+<emphasis>
+XkbLibraryVersion </emphasis>
+returns <emphasis>
+True</emphasis>
+, otherwise, it returns <emphasis>
+False.</emphasis>
+</para>
+
+<para>
+In addition, in order to use the Xkb extension, you must ensure that the
+extension is present in the server and that the server supports the version of
+the extension expected by the client. Use <emphasis>
+XkbQueryExtension</emphasis>
+ to do this, as described in the next section.
+</para>
+
+</sect1>
+<sect1 id='initializing_the_keyboard_extension'>
+<title>Initializing the Keyboard Extension</title>
+<para>
+Call <emphasis>
+XkbQueryExtension</emphasis>
+ to check for the presence and compatibility of the extension in the server and
+to initialize the extension. Because of potential version mismatches, you
+cannot use the generic extension mechanism functions (<emphasis>
+XQueryExtension </emphasis>
+and<emphasis>
+ XInitExtension</emphasis>
+) for checking for the presence of, and initializing the Xkb extension.
+</para>
+
+<para>
+You must call <emphasis>
+XkbQueryExtension</emphasis>
+ or <emphasis>
+XkbOpenDisplay</emphasis>
+ before using any other Xkb library interfaces, unless such usage is explicitly
+allowed in the interface description in this document. The exceptions are:
+<emphasis>
+XkbIgnoreExtension</emphasis>
+, <emphasis>
+XkbLibraryVersion</emphasis>
+, and a handful of audible-bell functions. You should not use any other Xkb
+functions if the extension is not present or is uninitialized. In general,
+calls to Xkb library functions made prior to initializing the Xkb extension
+cause <emphasis>
+BadAccess</emphasis>
+ protocol errors.
+</para>
+
+<para>
+<emphasis>
+XkbQueryExtension</emphasis>
+ both determines whether a compatible Xkb extension is present in the X server
+and initializes the extension when it is present.
+</para>
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Bool <emphasis>
+XkbQueryExtension</emphasis>
+(<emphasis>
+dpy, opcode_rtrn, event_rtrn, error_rtrn, major_in_out, minor_in_out</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Display *      <emphasis>
+dpy;      </emphasis>
+      /* connection to the X server */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int *      <emphasis>
+opcode_rtrn</emphasis>
+;            /* backfilled with the major extension opcode */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int *      <emphasis>
+event_rtrn</emphasis>
+;            /* backfilled with the extension base event code */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int *      <emphasis>
+error_rtrn</emphasis>
+;            /* backfilled with the extension base error code */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int *      <emphasis>
+major_in_out</emphasis>
+;            /* compile time lib major version in, server major version out */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int *      <emphasis>
+minor_in_out;      </emphasis>
+      /* compile time lib min version in, server minor version out */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+The <emphasis>
+XkbQueryExtension</emphasis>
+ function determines whether a compatible version of the X Keyboard Extension
+is present in the server. If a compatible extension is present, <emphasis>
+XkbQueryExtension</emphasis>
+ returns <emphasis>
+True</emphasis>
+; otherwise, it returns <emphasis>
+False</emphasis>
+.
+</para>
+
+<para>
+If a compatible version of Xkb is present, <emphasis>
+XkbQueryExtension</emphasis>
+ initializes the extension. It backfills the major opcode for the keyboard
+extension in <emphasis>
+opcode_rtrn</emphasis>
+, the base event code in <emphasis>
+event_rtrn</emphasis>
+<emphasis>
+, the base error code</emphasis>
+ in <emphasis>
+error_rtrn</emphasis>
+, and the major and minor version numbers of the extension in <emphasis>
+major_in_out</emphasis>
+ and <emphasis>
+minor_in_out</emphasis>
+. The major opcode is reported in the <emphasis>
+req_major</emphasis>
+ fields of some Xkb events. For a discussion of the base event code, see
+section 4.1. <!-- xref -->
+</para>
+
+<para>
+As a convenience, you can use the function <emphasis>
+XkbOpenDisplay</emphasis>
+ to perform these three tasks at once: open a connection to an X server, check
+for a compatible version of the Xkb extension in both the library and the
+server, and initialize the extension for use.
+</para>
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Display *<emphasis>
+XkbOpenDisplay</emphasis>
+(<emphasis>
+display_name, event_rtrn, error_rtrn, major_in_out, minor_in_out,
+reason_rtrn)</emphasis>
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+char *      <emphasis>
+display_name</emphasis>
+;      /* hardware display name, which determines the display and
+communications domain to be used */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int *      <emphasis>
+event_rtrn</emphasis>
+;      /* backfilled with the extension base event code */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int *      <emphasis>
+error_rtrn</emphasis>
+;      /* backfilled with the extension base error code */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int *      <emphasis>
+major_in_out</emphasis>
+;      /* compile time lib major version in, server major version out */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int *      <emphasis>
+minor_in_out</emphasis>
+;      /* compile time lib minor version in, server minor version out */
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+int *      <emphasis>
+reason_rtrn</emphasis>
+;      /* backfilled with a status code */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+<emphasis>
+XkbOpenDisplay </emphasis>
+is a convenience function that opens an X display connection and initializes
+the X keyboard extension. In all cases, upon return <emphasis>
+reason_rtrn</emphasis>
+ contains a status value indicating success or the type of failure. If
+<emphasis>
+major_in_out</emphasis>
+ and <emphasis>
+minor_in_out</emphasis>
+ are not <emphasis>
+NULL</emphasis>
+, <emphasis>
+XkbOpenDisplay</emphasis>
+ first calls <emphasis>
+XkbLibraryVersion</emphasis>
+ to determine whether the client library is compatible, passing it the values
+pointed to by <emphasis>
+major_in_out</emphasis>
+ and <emphasis>
+minor_in_out</emphasis>
+. If the library is incompatible, <emphasis>
+XkbOpenDisplay</emphasis>
+ backfills <emphasis>
+major_in_out</emphasis>
+ and <emphasis>
+minor_in_out</emphasis>
+ with the major and minor extension versions of the library being used and
+returns <emphasis>
+NULL</emphasis>
+. If the library is compatible,<emphasis>
+ XkbOpenDisplay </emphasis>
+next calls <emphasis>
+XOpenDisplay</emphasis>
+ with the <emphasis>
+display_name</emphasis>
+. If this fails, the function returns <emphasis>
+NULL</emphasis>
+. If successful, <emphasis>
+XkbOpenDisplay </emphasis>
+calls <emphasis>
+XkbQueryExtension</emphasis>
+ and<emphasis>
+ </emphasis>
+backfills the major and minor Xkb server extension version numbers in <emphasis>
+major_in_out</emphasis>
+ and <emphasis>
+minor_in_out</emphasis>
+.<emphasis>
+ </emphasis>
+If the server extension version is not compatible with the library extension
+version or if the server extension is not present, <emphasis>
+XkbOpenDisplay </emphasis>
+closes the display and returns <emphasis>
+NULL</emphasis>
+. When successful, the function returns the display connection<emphasis>
+.</emphasis>
+</para>
+
+<para>
+The possible values for <emphasis>
+reason_rtrn</emphasis> are:
+</para>
+
+<itemizedlist>
+<listitem>
+  <para>
+<emphasis>
+XkbOD_BadLibraryVersion</emphasis>
+ indicates <emphasis>
+XkbLibraryVersion </emphasis>
+returned <emphasis>
+False</emphasis>.
+  </para>
+</listitem>
+<listitem>
+  <para>
+<emphasis>
+XkbOD_ConnectionRefused</emphasis>
+ indicates the display could not be opened.
+  </para>
+</listitem>
+<listitem>
+  <para>
+<emphasis>
+XkbOD_BadServerVersion</emphasis>
+ indicates the library and the server have incompatible extension versions.
+  </para>
+</listitem>
+<listitem>
+  <para>
+<emphasis>
+XkbOD_NonXkbServer</emphasis>
+ indicates the extension is not present in the X server.
+  </para>
+</listitem>
+<listitem>
+  <para>
+<emphasis>
+XkbOD_Success</emphasis>
+ indicates that the function succeeded.
+  </para>
+</listitem>
+</itemizedlist>
+</sect1>
+
+<sect1 id='disabling_the_keyboard_extension'>
+<title>Disabling the Keyboard Extension</title>
+<para>
+If a server supports the Xkb extension, the X library normally implements
+preXkb keyboard functions using the Xkb keyboard description and state. The
+server Xkb keyboard state may differ from the preXkb keyboard state. This
+difference does not affect most clients, but there are exceptions. To allow
+these clients to work properly, you may instruct the extension not to use Xkb
+functionality.
+</para>
+
+<para>
+Call <emphasis>
+XkbIgnoreExtension</emphasis>
+ to prevent core X library keyboard functions from using the X Keyboard
+Extension. You must call <emphasis>
+XkbIgnoreExtension</emphasis>
+ before you open a server connection; Xkb does not provide a way to enable or
+disable use of the extension once a connection is established.
+</para>
+
+<informaltable frame='none'>
+<tgroup cols='1'>
+<colspec colsep='0'/>
+<tbody>
+  <row rowsep='0'>
+    <entry role='functiondecl'>
+Bool<emphasis>
+ XkbIgnoreExtension</emphasis>
+(<emphasis>
+ignore</emphasis>
+)
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry role='functionargdecl'>
+Bool      <emphasis>
+ignore</emphasis>
+;      /* <emphasis>
+True</emphasis>
+ means ignore the extension */
+    </entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+<emphasis>
+XkbIgnoreExtension</emphasis>
+ tells the X library whether to use the X Keyboard Extension on any
+subsequently opened X display connections. If ignore is <emphasis>
+True</emphasis>
+, the library does not initialize the Xkb extension when it opens a new
+display. This forces the X server to use compatibility mode and communicate
+with the client using only core protocol requests and events. If ignore is
+<emphasis>
+False</emphasis>
+, the library treats subsequent calls to <emphasis>
+XOpenDisplay</emphasis>
+ normally and uses Xkb extension requests, events, and state. Do not explicitly
+use Xkb on a connection for which it is disabled.<emphasis>
+ XkbIgnoreExtension</emphasis>
+ returns <emphasis>
+False</emphasis>
+ if it was unable to apply the ignore request.
+</para>
+
+</sect1>
+<sect1 id='protocol_errors'>
+<title>Protocol Errors</title>
+<para>
+Many of the Xkb extension library functions described in this document can
+cause the X server to report an error, referred to in this document as a
+<emphasis>
+BadXxx</emphasis>
+ protocol error, where <emphasis>
+Xxx</emphasis>
+ is some name. These errors are fielded in the normal manner, by the default
+Xlib error handler or one replacing it. Note that X protocol errors are not
+necessarily reported immediately because of the buffering of X protocol
+requests in Xlib and the server.
+</para>
+
+<para>
+Table 2.1 lists the protocol errors that can be generated, and their causes. <!-- xref -->
+</para>
+
+<table frame='none'>
+<title>Xkb Protocol Errors</title>
+<tgroup cols='2'>
+<colspec colsep='0'/>
+<colspec colsep='0'/>
+<thead>
+  <row rowsep='1'>
+    <entry>Error</entry>
+    <entry>Cause</entry>
+  </row>
+</thead>
+<tbody>
+  <row rowsep='0'>
+    <entry>BadAccess</entry>
+    <entry>
+<para>
+The Xkb extension has not been properly initialized
+</para>
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry>BadKeyboard</entry>
+    <entry>
+<para>
+The device specified was not a valid core or input extension device
+</para>
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry>BadImplementation</entry>
+    <entry>
+<para>
+Invalid reply from server
+</para>
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry>BadAlloc</entry>
+    <entry>
+<para>
+Unable to allocate storage
+</para>
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry>BadMatch</entry>
+    <entry>
+<para>
+A compatible version of Xkb was not available in the server or an argument has
+correct type and range, but is otherwise invalid
+</para>
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry>BadValue</entry>
+    <entry>
+<para>
+An argument is out of range
+</para>
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry>BadAtom</entry>
+    <entry>
+<para>
+A name is neither a valid Atom or <emphasis>
+None</emphasis>
+</para>
+    </entry>
+  </row>
+  <row rowsep='0'>
+    <entry>BadDevice</entry>
+    <entry>
+<para>
+Device, Feedback Class, or Feedback ID invalid
+</para>
+    </entry>
+  </row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+The Xkb extension adds a single protocol error, <emphasis>
+BadKeyboard</emphasis>
+, to the core protocol error set. This error code will be reported as the
+<emphasis>
+error_rtrn</emphasis>
+ when <emphasis>
+XkbQueryExtension</emphasis>
+ is called. When a <emphasis>
+BadKeyboard</emphasis>
+ error is reported in an <emphasis>
+XErrorEvent</emphasis>
+, additional information is reported in the <emphasis>
+resource_id</emphasis>
+ field. The most significant byte of the <emphasis>
+resource_id</emphasis>
+ is a further refinement of the error cause, as defined in Table 2.2. The least
+significant byte will contain the device, class, or feedback ID as indicated in
+the table.
+</para>
+
+<table frame='none'>
+<title>BadKeyboard Protocol Error resource_id Values</title>
+<tgroup cols='4'>
+<colspec colsep='0'/>
+<colspec colsep='0'/>
+<colspec colsep='0'/>
+<colspec colsep='0'/>
+<thead>
+  <row rowsep='0'>
+    <entry>high-order byte</entry>
+    <entry>value</entry>
+    <entry>meaning</entry>
+    <entry>low-order byte</entry>
+  </row>
+</thead>
+<tbody>
+  <row rowsep='0'>
+    <entry>XkbErr_BadDevice</entry>
+    <entry>0xff</entry>
+    <entry>
+<para>
+device not found
+</para>
+    </entry>
+    <entry>device ID</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>XkbErr_BadClass</entry>
+    <entry>0xfe</entry>
+    <entry>
+<para>
+device found, but it is of the wrong class
+</para>
+    </entry>
+    <entry>class ID</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>XkbErr_BadId</entry>
+    <entry>0xfd</entry>
+    <entry>
+<para>
+device found, class ok, but device does not contain a feedback with the
+indicated ID
+</para>
+    </entry>
+    <entry>feedback ID</entry>
+  </row>
+</tbody>
+</tgroup>
+</table>
+</sect1>
+
+<sect1 id='display_and_device_specifications_in_function_calls'>
+<title>Display and Device Specifications in Function Calls</title>
+<para>
+Where a connection to the server is passed as an argument (Display*) and an
+<emphasis>
+XkbDescPtr</emphasis>
+ is also passed as an argument, the Display* argument must match the <emphasis>
+dpy</emphasis>
+ field of the <emphasis>
+XkbDescRec</emphasis>
+ pointed to by the <emphasis>
+XkbDescPtr</emphasis>
+ argument, or else the <emphasis>
+dpy</emphasis>
+ field of the <emphasis>
+XkbDescRec</emphasis>
+ must be <emphasis>
+NULL</emphasis>
+. If they don’t match or the <emphasis>
+dpy</emphasis>
+ field is not <emphasis>
+NULL</emphasis>
+, a <emphasis>
+BadMatch</emphasis>
+ error is returned (either in the return value or a backfilled <emphasis>
+Status</emphasis>
+ variable). Upon successful return, the <emphasis>
+dpy</emphasis>
+ field of the <emphasis>
+XkbDescRec</emphasis>
+ always contains the Display* value passed in.
+</para>
+
+<para>
+The Xkb extension can communicate with the X input extension if it is present.
+Consequently, there can potentially be more than one input device connected to
+the server. Most Xkb library calls that require communicating with the server
+involve both a server connection (Display * <emphasis>
+dpy</emphasis>
+) and a device identifier (unsigned int <emphasis>
+device_spec</emphasis>
+). In some cases, the device identifier is implicit and is taken as the
+<emphasis>
+device_spec</emphasis>
+ field of an <emphasis>
+XkbDescRec</emphasis>
+ structure passed as an argument.
+</para>
+
+<para>
+The device identifier can specify any X input extension device with a <emphasis>
+KeyClass</emphasis>
+ component, or it can specify the constant, <emphasis>
+XkbUseCoreKbd</emphasis>
+. The use of <emphasis>
+XkbUseCoreKbd</emphasis>
+ allows applications to indicate the core keyboard without having to determine
+its device identifier.
+</para>
+
+<para>
+Where an Xkb device identifier is passed as an argument and an <emphasis>
+XkbDescPtr</emphasis>
+ is also passed as an argument, if either the argument or the <emphasis>
+XkbDescRec</emphasis>
+ <emphasis>
+device_spec</emphasis>
+ field is <emphasis>
+XkbUseCoreKbd</emphasis>
+, and if the function returns successfully, the <emphasis>
+XkbDescPtr</emphasis>
+ <emphasis>
+device_spec</emphasis>
+ field will have been converted from <emphasis>
+XkbUseCoreKbd</emphasis>
+ to a real Xkb device ID. If the function does not complete successfully, the
+<emphasis>
+device_spec</emphasis>
+ field remains unchanged. Subsequently, the device id argument must match the
+<emphasis>
+device_spec</emphasis>
+ field of the <emphasis>
+XkbDescPtr</emphasis>
+ argument. If they don’t match, a <emphasis>
+BadMatch</emphasis>
+ error is returned (either in the return value or a backfilled <emphasis>
+Status</emphasis>
+ variable).
+</para>
+
+<para>
+When the Xkb extension in the server hands an application a device identifier
+to use for the keyboard, that ID is the input extension identifier for the
+device if the server supports the X Input Extension. If the server does not
+support the input extension, the meaning of the identifier is undefined — the
+only guarantee is that when you use <emphasis>
+XkbUseCoreKbd</emphasis>
+, <emphasis>
+XkbUseCoreKbd</emphasis>
+ will work and the identifier returned by the server will refer to the core
+keyboard device.
+</para>
+</sect1>
+</chapter>