summaryrefslogtreecommitdiff
path: root/specs/kbproto/ch13.xml
diff options
context:
space:
mode:
authorAlan Coopersmith <alan.coopersmith@oracle.com>2019-02-23 13:33:41 -0800
committerAlan Coopersmith <alan.coopersmith@oracle.com>2019-02-23 15:22:32 -0800
commit4feff33159efb139ddb89a90fb26ad646b288f2b (patch)
treeb36ecded595ec090c1df48636dec7ea51751b16b /specs/kbproto/ch13.xml
parenteb2c0108e495ff2a5febcc87234780c3a249f49f (diff)
Restore generation of specs from docbook in autotools builds
Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>
Diffstat (limited to 'specs/kbproto/ch13.xml')
-rw-r--r--specs/kbproto/ch13.xml442
1 files changed, 442 insertions, 0 deletions
diff --git a/specs/kbproto/ch13.xml b/specs/kbproto/ch13.xml
new file mode 100644
index 0000000..25fa96d
--- /dev/null
+++ b/specs/kbproto/ch13.xml
@@ -0,0 +1,442 @@
+<chapter id='The_Server_Database_of_Keyboard_Components'>
+<title>The Server Database of Keyboard Components</title>
+
+<para>
+The X server maintains a database of keyboard components and common keyboard
+mappings. This database contains five kinds of components; when combined, these
+five components provide a complete description of a keyboard and its behavior.
+</para>
+
+
+<para>
+The X Keyboard Extension provides requests to list the contents of this
+database, to assemble and complete keyboard descriptions by merging the current
+keyboard description with the contents of this database, or to replace the
+current keyboard description with a complete keyboard description assembled as
+described below.
+</para>
+
+<sect1 id='Component_Names'>
+<title>Component Names</title>
+
+<para>
+Component and keymap names have the form "<emphasis>
+class</emphasis>
+(<emphasis>
+member</emphasis>
+)" where <emphasis>
+class</emphasis>
+ describes a subset of the available components for a particular type and the
+optional <emphasis>
+member</emphasis>
+ identifies a specific component from that subset. For example, the name
+"atlantis(acme)" might specify the symbols used for the atlantis national
+keyboard layout by the vendor "acme." Each class has an optional <emphasis>
+default</emphasis>
+ member — references which specify a class but not a member refer to the
+default member of the class, if one exists.
+</para>
+
+
+<para>
+The <emphasis>
+class</emphasis>
+ and <emphasis>
+member</emphasis>
+ names are both specified using characters from the Latin-1 character set. XKB
+implementations must accept all alphanumeric characters, minus (‘-’) and
+underscore (‘_’) in class or member names, and must not accept parentheses,
+plus, vertical bar, percent sign, asterisk, question mark or white space. The
+use of other characters is implementation-dependent.
+</para>
+
+
+</sect1>
+<sect1 id='Partial_Components_and_Combining_Multiple_Components'>
+<title>Partial Components and Combining Multiple Components</title>
+
+<para>
+Some of the elements in the server database contain describe only a piece of
+the corresponding keyboard component. These <emphasis>
+partial</emphasis>
+ components should be combined with other components of the same type to be
+useful.
+</para>
+
+
+<para>
+For example, a partial symbols map might describe the differences between a
+common ASCII keyboard and some national layout. Such a partial map is not
+useful on its own because it does not include those symbols that are the same
+on both the ASCII and national layouts (such as function keys). On the other
+hand, this partial map can configure <emphasis>
+any</emphasis>
+ ASCII keyboard to use a national layout.
+</para>
+
+
+<para>
+Two components can be combined in two ways:
+</para>
+
+<itemizedlist>
+<listitem>
+ <para>If the second component <emphasis>
+overrides</emphasis>
+ the first, any definitions that are present in both components are taken from
+the second.
+ </para>
+</listitem>
+<listitem>
+ <para>If the second component <emphasis>
+augments</emphasis>
+ the first, any definitions that are present in both components are taken from
+the first.
+ </para>
+</listitem>
+</itemizedlist>
+
+<para>
+Applications can use a <emphasis>
+component expression</emphasis>
+ to combine multiple components of some time into a complete description of
+some aspect of the keyboard. A component expression is a string which lists the
+components to be combined separated by operators which specify the rules for
+combining them. A complete description is assembled from the listed components,
+left to right, as follows:
+</para>
+
+<itemizedlist>
+<listitem>
+ <para>If the new elements are being merged with an existing map, the special
+component name ‘%’ refers to the unmodified value of the map.
+ </para>
+</listitem>
+<listitem>
+ <para>The ‘+’ operator specifies that the next specified component should
+override the current assembled definition.
+ </para>
+</listitem>
+<listitem>
+ <para>The ‘|’ operator specifies that the next specified component should
+augment the currently assembled definition.
+ </para>
+</listitem>
+<listitem>
+ <para>If the new elements are being merged with an existing map and the
+component expression begins with an operator, a leading ‘%’ is implied.
+ </para>
+</listitem>
+<listitem>
+ <para>If any unknown or illegal characters appear anywhere in the string, the
+entire expression is invalid and is ignored.
+ </para>
+</listitem>
+</itemizedlist>
+
+<para>
+For example, the component expression "+de" specifies that the default element
+of the "de" map should be applied to the current keyboard mapping, overriding
+any existing definitions.
+</para>
+
+
+<para>
+A slightly more involved example: the expression
+"acme(ascii)+de(basic)|iso9995-3" constructs a German (de) mapping for the
+ASCII keyboard supplied by the "acme" vendor. The new definition begins with
+the symbols for the default ASCII keyboard for Acme, overrides them with any
+keys that are defined for the default German keyboard layout and then applies
+the definitions from the iso9995-3 to any undefined keys or groups of keys
+(part three of the iso9995 standard defines a common set of bindings for the
+secondary group, but allows national layouts to override those definitions
+where necessary).
+</para>
+
+
+</sect1>
+<sect1 id='Component_Hints'>
+<title>Component Hints</title>
+
+<para>
+Each component has a set of flags that provide some additional hints about that
+component. XKB provides these hints for clients that present the keyboard
+database to users and specifies their interpretation only loosely. Clients can
+use these hints to constrain the list of components or to control the way that
+components are presented to the user.
+</para>
+
+
+<para>
+Hints for a component are reported with its name. The least significant byte of
+the hints field has the same meaning for all five types of keyboard components,
+and can contain any combination of the following values:
+</para>
+
+<informaltable frame='topbot'>
+<?dbfo keep-together="always" ?>
+<tgroup cols='2' align='left' colsep='0' rowsep='0'>
+<colspec colname='c1' colwidth='1.0*'/>
+<colspec colname='c2' colwidth='3.0*'/>
+<thead>
+ <row rowsep='1'>
+ <entry>Flag</entry>
+ <entry>Meaning</entry>
+ </row>
+</thead>
+<tbody>
+ <row>
+ <entry><emphasis>
+LC_Hidden</emphasis>
+</entry>
+ <entry>Indicates a component that should not normally be presented to the
+user.</entry>
+ </row>
+ <row>
+ <entry><emphasis>
+LC_Default</emphasis>
+</entry>
+ <entry>Indicates a component that is the default member of its
+class.</entry>
+ </row>
+ <row>
+ <entry><emphasis>
+LC_Partial</emphasis>
+</entry>
+ <entry>Indicates a partial component.</entry>
+ </row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+The interpretation of the most significant byte of the hints field is dependent
+on the type of component. The hints defined for each kind of component are
+listed in the section below that describes that kind of component.
+</para>
+
+
+</sect1>
+<sect1 id='Keyboard_Components'>
+<title>Keyboard Components</title>
+
+<para>
+The five types of components stored in the server database of keyboard
+components correspond to the <emphasis>
+symbols</emphasis>
+, <emphasis>
+geometry</emphasis>
+, <emphasis>
+keycodes</emphasis>
+, <emphasis>
+compat</emphasis>
+ and <emphasis>
+types</emphasis>
+ symbolic names associated with a keyboard.
+</para>
+
+</sect1>
+<sect1 id='The_Keycodes_Component'>
+<title>The Keycodes Component</title>
+
+<para>
+The <emphasis>
+keycodes</emphasis>
+ component of a keyboard mapping specifies the range and interpretation of the
+raw keycodes reported by the device. It sets the <emphasis>
+keycodes</emphasis>
+ symbolic name, the minimum and maximum legal keycodes for the keyboard, and
+the symbolic name for each key. The keycodes component might also contain
+aliases for some keys, symbolic names for some indicators, and a description of
+which indicators are physically present.
+</para>
+
+
+<para>
+The special keycodes component named "computed" indicates that XKB should
+assign unused keycodes to any unknown keys referenced by name by any of the
+other components. The computed keycodes component is useful primarily when
+browsing keymaps because it makes it possible to use the symbols and geometry
+components without having to find a set of keycodes that includes keycode
+definitions for all of the keys listed in the two components.
+</para>
+
+
+<para>
+XKB defines no hints that are specific to the keycodes component.
+</para>
+
+
+<sect2 id='The_Types_Component'>
+<title>The Types Component</title>
+
+<para>
+The <emphasis>
+types</emphasis>
+ component of a keyboard mapping specifies the key types that can be associated
+with the various keyboard keys. It affects the <emphasis>
+types</emphasis>
+ symbolic name and the list of types associated with the keyboard (see
+<link linkend='Key_Types'>Key Types</link>). The types component
+of a keyboard mapping can also optionally contain real modifier bindings and
+symbolic names for one or more virtual modifiers.
+</para>
+
+
+<para>
+The special types component named "canonical" always contains the types and
+definitions listed in <link linkend="canonical_key_types">Canonical Key Types</link> of this document.
+</para>
+
+
+<para>
+XKB defines no hints that are specific to the types component.
+</para>
+
+
+</sect2>
+<sect2 id='The_Compatibility_Map_Component'>
+<title>The Compatibility Map Component</title>
+
+<para>
+The <emphasis>
+compatibility map</emphasis>
+ component of a keyboard mapping primarily specifies the rules used to assign
+actions to keysyms. It affects the <emphasis>
+compat</emphasis>
+ symbolic name, the symbol compatibility map and the group compatibility map.
+The compat component might also specify maps for some indicators and the real
+modifier bindings and symbolic names of some virtual modifiers.
+</para>
+
+
+<para>
+XKB defines no hints that are specific to the compatibility map component.
+</para>
+
+
+</sect2>
+<sect2 id='The_Symbols_Component'>
+<title>The Symbols Component</title>
+
+<para>
+The <emphasis>
+symbols</emphasis>
+ component of a keyboard mapping specifies primarily the symbols bound to each
+keyboard key. It affects the <emphasis>
+symbols</emphasis>
+ symbolic name, a key symbol mapping for each key, they keyboard modifier
+mapping, and the symbolic names for the keyboard symbol groups. Optionally, the
+<emphasis>
+symbols</emphasis>
+ component can contain explicit actions and behaviors for some keys, or the
+real modifier bindings and symbolic names for some virtual modifiers.
+</para>
+
+
+<para>
+XKB defines the following additional hints for the symbols component:
+</para>
+
+<informaltable frame='topbot'>
+<?dbfo keep-together="always" ?>
+<tgroup cols='2' align='left' colsep='0' rowsep='0'>
+<colspec colname='c1' colwidth='1.0*'/>
+<colspec colname='c2' colwidth='3.0*'/>
+<thead>
+ <row rowsep='1'>
+ <entry>Flag</entry>
+ <entry>Meaning</entry>
+ </row>
+</thead>
+<tbody>
+ <row>
+ <entry><emphasis>
+LC_AlphanumericKeys</emphasis>
+</entry>
+ <entry>Indicates a symbol component that contains bindings primarily for an
+alphanumeric section of the keyboard.</entry>
+ </row>
+ <row>
+ <entry><emphasis>
+LC_ModifierKeys</emphasis>
+</entry>
+ <entry>Indicates a symbol component that contains bindings primarily for
+modifier keys.</entry>
+ </row>
+ <row>
+ <entry><emphasis>
+LC_KeypadKeys</emphasis>
+</entry>
+ <entry>Indicates a symbol component that contains bindings primarily for
+numeric keypad keys.</entry>
+ </row>
+ <row>
+ <entry>LC_FunctionKeys</entry>
+ <entry>Indicates a symbol component that contains bindings primarily for
+function keys.</entry>
+ </row>
+ <row>
+ <entry>LC_AlternateGroup</entry>
+ <entry>Indicates a symbol component that contains bindings for an alternate
+keyboard group.</entry>
+ </row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+These hints only apply to partial symbols components; full symbols components
+are assumed to specify all of the pieces listed above.
+</para>
+
+<note><para>The alphanumeric, modifier, keypad or function keys hints should
+describe the primary intent of the component designer and should not simply an
+exhaustive list of the kinds of keys that are affected. For example, national
+keyboard layouts affect primarily alphanumeric keys, but many affect a few
+modifier keys too; such mappings should set only <emphasis>
+LC_AlphanumericKeys</emphasis>
+ hint. In general, symbol components should set only one of those four flags
+(though <emphasis>
+LC_AlternateGroup</emphasis>
+ may be combined with any of the other flags).</para></note>
+
+</sect2>
+<sect2 id='The_Geometry_Component'>
+<title>The Geometry Component</title>
+
+<para>
+The <emphasis>
+geometry</emphasis>
+ component of a keyboard mapping specifies primarily the geometry of the
+keyboard. It contains the geometry symbolic name and the keyboard geometry
+description. The geometry component might also contain aliases for some keys or
+symbolic names for some indicators and might affect the set of indicators that
+are physically present. Key aliases defined in the geometry component of a
+keyboard mapping override those defined in the keycodes component.
+</para>
+
+
+<para>
+XKB defines no hints that are specific to the geometry component.
+</para>
+
+
+</sect2>
+</sect1>
+<sect1 id='Complete_Keymaps'>
+<title>Complete Keymaps</title>
+
+<para>
+The X server also reports a set of fully specified keymaps. The keymaps
+specified in this list are usually assembled from the components stored in the
+rest of the database and typically represent the most commonly used keymaps for
+a particular system.
+</para>
+
+
+<para>
+XKB defines no hints that are specific to complete keymaps.
+</para>
+</sect1>
+</chapter>