libX11 git update 14 sep 2011

1 files changed, 404 insertions, 0 deletions

diff --git a/libX11/specs/XKB/ch01.xml b/libX11/specs/XKB/ch01.xml
new file mode 100644
index 000000000..5079a411a
--- /dev/null
+++ b/libX11/specs/XKB/ch01.xml
@@ -0,0 +1,404 @@
+<chapter id='overview'>
+<title>Overview</title>
+
+<para>
+The X Keyboard Extension provides capabilities that are lacking or are
+cumbersome in the core X protocol.
+</para>
+
+<sect1 id='core_x_protocol_support_for_keyboards'>
+<title>Core X Protocol Support for Keyboards</title>
+
+<para>
+The core X protocol specifies the ways that the
+<emphasis>Shift</emphasis>,
+<emphasis>Control</emphasis>, and
+<emphasis>Lock</emphasis>
+modifiers and the modifiers bound to the
+<emphasis>Mode_switch</emphasis> or
+<emphasis>Num_Lock</emphasis>
+keysyms interact to generate keysyms and characters. The core protocol also
+allows users to specify that a key affects one or more modifiers. This behavior
+is simple and fairly flexible, but it has a number of limitations that make it
+difficult or impossible to properly support many common varieties of keyboard
+behavior. The limitations of core protocol support for keyboards include:
+</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+Use of a single, uniform, four-symbol mapping for all keyboard keys makes it
+difficult to properly support keyboard overlays, PC-style break keys, or
+keyboards that comply with ISO9995, or a host of other national and
+international standards.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+A second keyboard group may be specified using a modifier, but this has side
+effects that wreak havoc with client grabs and X toolkit translations.
+Furthermore, this approach limits the number of keyboard groups to two.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Poorly specified locking key behavior requires X servers to look for a few
+"magic" keysyms to determine that keys should lock when pressed. This leads to
+incompatibilities between X servers with no way for clients to detect
+implementation differences.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Poorly specified capitalization and control behavior requires modifications to
+X library source code to support new character sets or locales and can lead to
+incompatibilities between system wide and X library capitalization behavior.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Limited interactions between modifiers specified by the core protocol make many
+common keyboard behaviors difficult or impossible to implement. For example,
+there is no reliable way to indicate whether or not the shift modifier should
+"cancel" the lock modifier.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The lack of any explicit descriptions for indicators, most modifiers, and other
+aspects of the keyboard appearance requires clients that wish to clearly
+describe the keyboard to a user to resort to a mish-mash of prior knowledge and
+heuristics.
+    </para>
+  </listitem>
+</itemizedlist>
+
+</sect1>
+<sect1 id='xkb_keyboard_extension_support_for_keyboards'>
+<title>Xkb Keyboard Extension Support for Keyboards</title>
+
+<para>
+The X Keyboard Extension makes it possible to clearly and explicitly specify
+most aspects of keyboard behavior on a per-key basis. It adds the notion of a
+keyboard group to the global keyboard state and provides mechanisms to more
+closely track the logical and physical state of the keyboard. For
+keyboard-control clients, Xkb provides descriptions and symbolic names for many
+aspects of keyboard appearance and behavior.
+</para>
+
+<para>
+In addition, the X Keyboard Extension includes additional keyboard controls
+designed to make keyboards more accessible to people with movement impairments.
+</para>
+
+</sect1>
+
+<sect1 id='xkb_extension_components'>
+<title>Xkb Extension Components</title>
+
+<para>
+The Xkb extension is composed of two parts: a server extension, and a
+client-side X library extension. These consist of a loadable module that may be
+activated when an X server is started and a modified version of Xlib. Both
+server and Xlib versions must be at least X11 R6.
+</para>
+
+
+<para>
+Figure 1.1 shows the overall structure of the Xkb extension:
+</para>
+
+<mediaobject>
+  <imageobject>
+    <imagedata format="SVG" fileref="XKBlib-1.svg"/>
+  </imageobject>
+  <caption>Overall Xkb Structure</caption>
+</mediaobject>
+
+
+<para>
+The server portion of the Xkb extension encompasses a database of named
+keyboard components, in unspecified format, that may be used to configure a
+keyboard. Internally, the server maintains a <emphasis>
+keyboard description</emphasis>
+ that includes the keyboard state and configuration (mapping). By "keyboard" we
+mean the logical keyboard device, which includes not only the physical keys,
+but also potentially a set of up to 32 indicators (usually LEDs) and bells.
+</para>
+
+
+<para>
+The keyboard description is a composite of several different data structures,
+each of which may be manipulated separately. When manipulating the server
+components, the design allows partial components to be transmitted between the
+server and a client. The individual components are shown in Figure 1.1.
+</para>
+
+<variablelist>
+  <varlistentry>
+    <term>Client Map</term>
+    <listitem>
+      <para>
+The key mapping information needed to convert arbitrary keycodes to symbols.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>Server Map</term>
+    <listitem>
+      <para>
+The key mapping information categorizing keys by functionality (which keys are
+modifiers, how keys behave, and so on).
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>Controls</term>
+    <listitem>
+      <para>
+Client configurable quantities effecting how the keyboard behaves, such as
+repeat behavior and modifications for people with movement impairments.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>Indicators</term>
+    <listitem>
+      <para>
+The mapping of behavior to indicators.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>Geometry</term>
+    <listitem>
+      <para>
+A complete description of the physical keyboard layout, sufficient to draw a
+representation of the keyboard.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>Names</term>
+    <listitem>
+      <para>
+A mapping of names to various aspects of the keyboard such as individual
+virtual modifiers, indicators, and bells.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>Compatibility Map</term>
+    <listitem>
+      <para>
+The definition of how to map core protocol keyboard state to Xkb keyboard state.
+      </para>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+A client application interrogates and manipulates the keyboard by reading and
+writing portions of the server description for the keyboard. In a typical
+sequence a client would fetch the current information it is interested in,
+modify it, and write it back. If a client wishes to track some portion of the
+keyboard state, it typically maintains a local copy of the portion of the
+server keyboard description dealing with the items of interest and updates this
+local copy from events describing state transitions that are sent by the server.
+</para>
+
+<para>
+A client may request the server to reconfigure the keyboard either by sending
+explicit reconfiguration instructions to it, or by telling it to load a new
+configuration from its database of named components. Partial reconfiguration
+and incremental reconfiguration are both supported.
+</para>
+
+<sect2 id='groups_and_shift_levels'>
+<title>Groups and Shift Levels</title>
+
+<para>
+The graphic characters or control functions that may be accessed by one key are
+logically arranged in groups and levels. See section 14.1for a complete
+description of groups and levels.
+</para>
+
+
+</sect2>
+<sect2 id='radio_groups'>
+<title>Radio Groups</title>
+
+<para>
+A radio group is a set of keys whose behavior simulates a set of radio buttons.
+Once a key in a radio group is pressed, it stays logically depressed until
+another key in the group is pressed, at which point the previously depressed
+key is logically released. Consequently, at most one key in a radio group can
+be logically depressed at one time. A radio group is defined by a radio group
+index, an optional name, and by assigning each key in the radio group <emphasis>
+XkbKB_RadioGroup</emphasis>
+ behavior and the radio group index.
+</para>
+
+</sect2>
+</sect1>
+
+<sect1 id='client_types'>
+<title>Client Types</title>
+
+<para>
+This specification differentiates between three different classes of client
+applications:
+</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+Xkb-aware applications
+    </para>
+    <para>
+These applications make specific use of Xkb functionality and APIs not present
+in the core protocol.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Xkb-capable applications
+    </para>
+    <para>
+These applications make no use of Xkb extended functionality and Application
+Programming Interfaces (APIs) directly. However, they are linked with a version
+of Xlib that includes Xkb and indirectly benefit from some of Xkb’s
+features.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Xkb-unaware applications
+    </para>
+    <para>
+These applications make no use of Xkb extended functionality or APIs and
+require Xkb’s functionality to be mapped to core Xlib functionality to
+operate properly.
+    </para>
+  </listitem>
+</itemizedlist>
+
+</sect1>
+
+<sect1 id='compatibility_with_the_core_protocol'>
+<title>Compatibility With the Core Protocol</title>
+
+<para>
+Because the Xkb extension allows a keyboard to be configured in ways not
+foreseen by the core protocol, and because Xkb-unaware clients are allowed to
+connect to a server using the Xkb extension, there must be a means of
+converting between the Xkb domain and the core protocol. The Xkb server
+extension maintains a compatibility map as part of its keyboard description;
+this map controls the conversion of Xkb generated events to core protocol
+events and the results of core protocol requests to appropriate Xkb state and
+configuration.
+</para>
+
+
+</sect1>
+<sect1 id='additional_protocol_errors'>
+<title>Additional Protocol Errors</title>
+
+<para>
+The Xkb extension adds a single protocol error, <emphasis>
+BadKeyboard</emphasis>
+, to the core protocol error set. See section 2.6 for a discussion of the  <!-- xref -->
+<emphasis>
+BadKeyboard</emphasis>
+ protocol error.
+</para>
+
+
+</sect1>
+<sect1 id='extension_library_functions'>
+<title>Extension Library Functions</title>
+
+<para>
+The X Keyboard Extension replaces the core protocol definition of a keyboard
+with a more comprehensive one. The X Keyboard Extension library interfaces are
+included in Xlib.<footnote><para>
+X11R6.1 is the first release by the X Consortium, Inc.,that includes the X
+Keyboard Extension in Xlib. X11R6 included work in progress on this extension
+as nonstandard additions to the library.
+</para>
+</footnote>
+</para>
+
+<para>
+Xlib detects the presence of the X Keyboard server extension and uses Xkb
+protocol to replace some standard X library functions related to the keyboard.
+If an application uses only standard X library functions to examine the
+keyboard or process key events, it should not need to be modified when linked
+with an X library containing the X keyboard extension. All of the
+keyboard-related X library functions have been modified to automatically use
+Xkb protocol when the server extension is present.
+</para>
+
+<para>
+The Xkb extension adds library interfaces to allow a client application to
+directly manipulate the new capabilities.
+</para>
+
+
+<sect2 id='error_indications'>
+<title>Error Indications</title>
+
+<para>
+Xkb functions that communicate with the X server check to be sure the Xkb
+extension has been properly initialized prior to doing any other operations. If
+the extension has not been properly initialized or the application, library,
+and server versions are incompatible, these functions return an error
+indication as shown in Table 1.1. Because of this test, <emphasis>
+BadAccess</emphasis>
+ and <emphasis>
+BadMatch</emphasis>
+ (due to incompatible versions) protocol errors should normally not be
+generated.
+</para>
+
+<table frame='none'>
+<!-- <caption>Function Error Returns Due to Extension Problems</caption> -->
+<title>Function Error Returns Due to Extension Problems</title>
+<tgroup cols='2'>
+<colspec align="left" colsep="0"/>
+<colspec align="left" colsep="0"/>
+<thead>
+  <row>
+    <entry>Functions return type</entry>
+    <entry>Return value</entry>
+  </row>
+</thead>
+<tbody>
+  <row rowsep='0'>
+    <entry>pointer to a structure</entry>
+    <entry>NULL</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>Bool</entry>
+    <entry>False</entry>
+  </row>
+  <row rowsep='0'>
+    <entry>Status</entry>
+    <entry>BadAccess</entry>
+  </row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+Many Xkb functions do not actually communicate with the X server; they only
+require processing in the client-side portion of the library. Furthermore, some
+applications may never actually need to communicate with the server; they
+simply use the Xkb library capabilities. The functions that do not communicate
+with the server return either a pointer to a structure, a Bool, or a Status.
+These functions check that the application has queried the Xkb library version
+and return the values shown in Table 1.1 if it has not.
+</para>
+</sect2>
+</sect1>
+</chapter>