Convert XKB docs from DocBook SGML to DocBook XML

Uses newer tools for formatting, better matching other new docs
Moved from sgml/input to new directory general/input

Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>

9 files changed, 843 insertions, 846 deletions

diff --git a/Makefile.am b/Makefile.am
index 29eaf0c..a938766 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -20,7 +20,7 @@
 #
 #  Process this file with autoconf to create configure.
 
-SUBDIRS = man sgml specs
+SUBDIRS = general man sgml specs
 
 dist_doc_DATA = MAINTAINERS
 
diff --git a/configure.ac b/configure.ac
index dfbd83e..ee816a8 100644
--- a/configure.ac
+++ b/configure.ac
@@ -45,11 +45,12 @@ XORG_CHECK_SGML_DOCTOOLS(1.5)
 XORG_CHECK_DOCBOOK
 
 AC_CONFIG_FILES([Makefile
+		 general/Makefile
+		 general/input/Makefile
 		 man/Makefile
 		 sgml/Makefile
 		 sgml/fonts/Makefile
 		 sgml/graphics/Makefile
-		 sgml/input/Makefile
 		 sgml/platforms/Makefile
 		 specs/Makefile
 		 specs/CTEXT/Makefile
diff --git a/general/Makefile.am b/general/Makefile.am
new file mode 100644
index 0000000..af1d60a
--- /dev/null
+++ b/general/Makefile.am
@@ -0,0 +1,3 @@
+#  Process this file with automake to create Makefile.in
+
+SUBDIRS = input
diff --git a/general/input/Makefile.am b/general/input/Makefile.am
new file mode 100644
index 0000000..ede099f
--- /dev/null
+++ b/general/input/Makefile.am
@@ -0,0 +1,8 @@
+#  Process this file with automake to create Makefile.in
+
+doc_sources = XKB-Config.xml XKB-Enhancing.xml
+
+xmldir = $(docdir)/input
+dist_xml_DATA = $(doc_sources)
+
+include $(top_srcdir)/xmlrules.in
diff --git a/general/input/XKB-Config.xml b/general/input/XKB-Config.xml
new file mode 100644
index 0000000..82e479f
--- /dev/null
+++ b/general/input/XKB-Config.xml
@@ -0,0 +1,378 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+          "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+
+<article>
+
+  <articleinfo>
+
+    <title>The XKB Configuration Guide</title>
+    <authorgroup>
+      <author>
+	<firstname>Kamil</firstname><surname>Toman</surname>
+      </author>
+      <author>
+	<firstname>Ivan</firstname><othername>U.</othername>
+	<surname>Pascal</surname>
+      </author>
+    </authorgroup>
+    <pubdate>25 November 2002</pubdate>
+
+    <abstract>
+
+      <para>
+This document describes how to configure Xorg XKB from a user's point
+of view. It covers basic configuration syntax and gives also a few examples.
+      </para>
+
+    </abstract>
+
+  </articleinfo>
+
+  <sect1>
+    <title>Overview</title>
+
+    <para>
+The XKB configuration is decomposed into a number of components. Selecting
+proper parts and combining them back you can achieve most of the configurations
+you might need. Unless you have a completely atypical keyboard you really don't
+need to touch any of the xkb configuration files.
+    </para>
+
+  </sect1>
+
+  <sect1>
+    <title>Selecting XKB Configuration</title>
+
+    <para>
+The easiest and the most natural way to specify a keyboard mapping is to use
+the <literal remap="tt">rules</literal> component. As its name suggests it describes a number of
+general rules to combine all bits and pieces into a valid and useful keyboard
+mapping. All you need to do is to select a suitable rules file and then to
+feed it with a few parameters that will adjust the keyboard behaviour to
+fulfill your needs.
+    </para>
+
+    <para>
+      The parameters are:
+
+      <itemizedlist>
+	<listitem>
+
+	  <para>
+<literal remap="tt">XkbRules </literal>- files of rules to be used for keyboard mapping
+composition
+	  </para>
+	</listitem>
+
+	<listitem>
+	  <para>
+<literal remap="tt">XkbModel </literal>- name of the model of your keyboard type
+	  </para>
+	</listitem>
+
+	<listitem>
+	  <para>
+<literal remap="tt">XkbLayout </literal>- layout(s) you intend to use
+	  </para>
+	</listitem>
+
+	<listitem>
+	  <para>
+<literal remap="tt">XkbVariant </literal>- variant(s) of the layout you intend to use
+	  </para>
+	</listitem>
+
+	<listitem>
+	  <para>
+<literal remap="tt">XkbOptions </literal>- extra xkb configuration options
+	  </para>
+	</listitem>
+
+      </itemizedlist>
+
+    </para>
+
+    <para>
+The proper rules file depends on your vendor. In reality, the commonest
+file of rules is <filename>xorg</filename>. For each rules file there is a
+description file named
+<filename>&lt;<replaceable>vendor-rules</replaceable>&gt;.lst</filename>,
+for instance <literal remap="tt">xorg.lst</literal> which is located in
+the xkb configuration subdirectory <filename>rules</filename>
+(for example <filename>/etc/X11/xkb/rules</filename>).
+    </para>
+
+    <sect2>
+      <title>Basic Configuration</title>
+
+      <para>
+Let's say you want to configure a PC-style American keyboard with 104
+keys as described in <filename>xorg.lst</filename>.  This can be done by simply
+writing several lines from below to your <filename>xorg.conf</filename>
+configuration file (previously known
+as <filename>/etc/X11/XF86Config-4</filename>
+or <filename>/etc/X11/XF86Config</filename>):
+
+ 	<screen>
+Section "InputDevice"
+    Identifier "Keyboard1"
+    Driver "kbd"
+
+    Option "XkbModel" "pc104"
+    Option "XkbLayout" "us"
+    Option "XKbOptions" ""
+EndSection
+	</screen>
+
+The values of <literal remap="tt">XkbModel</literal>
+and <literal remap="tt">XkbLayout</literal> are really
+not surprising. The <literal remap="tt">XkbOptions</literal>
+has been explicitly set to the empty set of parameters.
+The <literal remap="tt">XkbVariant</literal> option has been left out.
+That means the default variant named <literal remap="tt">basic</literal>
+is loaded.
+      </para>
+
+      <para>
+Of course, this can be also done at runtime using the utility
+<command>setxkbmap</command>.
+The shell command loading the same keyboard mapping would look like:
+
+	<screen>
+setxkbmap -rules xorg -model pc104 -layout us -option ""
+	</screen>
+
+The configuration and the shell command would be very analogous
+for most other layouts (internationalized mappings).
+      </para>
+
+    </sect2>
+
+    <sect2>
+      <title>Advanced Configuration</title>
+
+      <para>
+You can use multi-layouts xkb configuration.
+What does it mean? Basically it allows to load up to four different
+keyboard layouts at a time. Each such layout would reside in its
+own group. The groups (unlike complete keyboard remapping) can be
+switched very fast from one to another by a combination of keys.
+      </para>
+
+      <para>
+Let's say you want to configure your new Logitech cordless desktop
+keyboard, you intend to use three different layouts at the same
+time - us, czech and german (in this order), and that you are used
+to <literal remap="tt">Alt-Shift</literal> combination for switching among them.
+      </para>
+
+      <para>
+Then the configuration snippet could look like this:
+
+	<screen>
+Section "InputDevice"
+    Identifier "Keyboard1"
+    Driver "kbd"
+
+    Option "XkbModel" "logicordless"
+    Option "XkbLayout" "us,cz,de"
+    Option "XKbOptions" "grp:alt_shift_toggle"
+EndSection
+	</screen>
+
+Of course, this can be also done at runtime using the utility
+<command>setxkbmap</command>.
+The shell command loading the same keyboard mapping would look like:
+
+	<screen>
+setxkbmap -rules xorg -model logicordless -layout "us,cz,de" \
+         -option "grp:alt_shift_toggle"
+	</screen>
+
+      </para>
+
+    </sect2>
+
+    <sect2>
+      <title>Even More Advanced Configuration</title>
+
+      <para>
+Okay, let's say you are more demanding. You do like the example
+above but you want it to change a bit. Let's imagine you want
+the czech keyboard mapping to use another variant but basic.
+The configuration snippet then changes into:
+
+	<screen>
+Section "InputDevice"
+    Identifier "Keyboard1"
+    Driver "kbd"
+
+    Option "XkbModel" "logicordless"
+    Option "XkbLayout" "us,cz,de"
+    Option "XkbVariant" ",bksl,"
+    Option "XKbOptions" "grp:alt_shift_toggle"
+EndSection
+	</screen>
+
+That seems tricky but it is not. The logic for settings of variants
+is the same as for layouts, that means the first and the third variant
+settings are left out (set to <literal remap="tt">basic</literal>),
+the second is set to <literal remap="tt">bksl</literal> (a special
+variant with an enhanced definition of the backslash key).
+      </para>
+
+      <para>
+Analogously, the loading runtime will change to:
+
+	<screen>
+setxkbmap -rules xorg -model logicordless -layout "us,cz,de" \
+         -variant ",bksl," -option "grp:alt_shift_toggle"
+	</screen>
+
+      </para>
+
+    </sect2>
+
+    <sect2>
+      <title>Basic Global Options</title>
+
+      <para>
+For a list of available options, with a short decription of what they do,
+see the section starting with "! option" in the
+<filename>rules/*.lst</filename> files.
+      </para>
+
+<!--
+  TODO: More detailed descriptions of options. Users often get confused.
+-->
+
+    </sect2>
+
+  </sect1>
+
+  <sect1>
+    <title>Direct XKB Configuration</title>
+
+    <para>
+Generally, you can directly prescribe what configuration of each of basic
+xkb components should be used to form the resulting keyboard mapping.
+This method is rather "brute force". You precisely need to know the structure
+and the meaning of all of used configuration components.
+    </para>
+
+    <para>
+This method also exposes all xkb configuration details directly into xorg.conf
+configuration file which is a not very fortunate fact.
+In rare occasions it may be needed, though. So how does it work?
+    </para>
+
+    <sect2>
+      <title>Basic Components</title>
+
+      <para>
+There are five basic components used to form a keyboard mapping:
+
+	<variablelist>
+	  <varlistentry>
+	    <term>key codes</term>
+	    <listitem><para>
+a translation of the scan codes produced by the keyboard into a
+suitable symbolic form
+	    </para></listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>types</term>
+	    <listitem><para>
+a specification of what various combinations of modifiers produce
+	    </para></listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>key symbols</term>
+	    <listitem><para>
+a translation of symbolic key codes into actual symbols
+	    </para></listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>geometry</term>
+	    <listitem><para>
+a description of physical keyboard geometry
+	    </para></listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>compatibility maps</term>
+	    <listitem><para>
+a specification of what action should
+each key produce in order to preserve compatibility with XKB-unware clients
+	    </para></listitem>
+	  </varlistentry>
+
+	</variablelist>
+
+      </para>
+
+    </sect2>
+
+    <sect2>
+      <title>Example Configuration</title>
+
+      <para>
+Look at the following example:
+
+	<screen>
+Section "InputDevice"
+    Identifier "Keyboard0"
+    Driver "kbd"
+
+    Option "XkbKeycodes" "xorg"
+    Option "XkbTypes"    "default"
+    Option "XkbSymbols"  "en_US(pc104)+de+swapcaps"
+    Option "XkbGeometry" "pc(pc104)"
+    Option "XkbCompat"   "basic+pc+iso9995"
+EndSection
+	</screen>
+
+      </para>
+
+      <para>
+This configuration sets the standard X server default interpretation of keyboard
+keycodes, and sets the default modifier types. The
+symbol table is composed of extended US keyboard layout in its
+variant for pc keyboards with 104 keys plus all keys
+for german layout are redefined respectively. Also the logical meaning
+of <keycap>Caps-lock</keycap> and <keycap>Control</keycap> keys is swapped.
+The standard keyboard geometry (physical look) is set to pc style
+keyboard with 104 keys. The compatibility map is set to allow
+basic shifting, to allow Alt keys to be interpreted and also
+to allow iso9995 group shifting.
+      </para>
+
+<!--
+    TODO: add information about layout shifting:
+    TODO: us+ru(winkeys):2+de:3
+-->
+
+    </sect2>
+
+  </sect1>
+
+  <sect1>
+    <title>Keymap XKB Configuration</title>
+
+    <para>
+Keymap configuration is the way formerly used to configure xkb. The
+user included a special keymap file which specified the direct xkb
+configuration. This method has been obsoleted by previously described
+rules files which are far more flexible and allow simpler and more
+intuitive syntax. It is preserved merely for compatibility reasons and
+should be avoided if possible.
+    </para>
+
+  </sect1>
+
+</article>
diff --git a/sgml/input/XKB-Enhancing.sgml b/general/input/XKB-Enhancing.xml
index 4aec2e6..3749541 100644
--- a/sgml/input/XKB-Enhancing.sgml
+++ b/general/input/XKB-Enhancing.xml
@@ -1,86 +1,92 @@
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
-
-<Article>
-
-<articleinfo>
-
-<Title>How to further enhance XKB configuration</Title>
-<AUTHOR
->
-<FirstName>Kamil Toman, Ivan U. Pascal</FirstName>
-</AUTHOR
->
-<PubDate>25 November 2002
-</PubDate>
-
-<Abstract>
-
-<Para>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[]>
+
+<article>
+
+  <articleinfo>
+
+    <title>How to further enhance XKB configuration</title>
+    <authorgroup>
+      <author>
+	<firstname>Kamil</firstname><surname>Toman</surname>
+      </author>
+      <author>
+	<firstname>Ivan</firstname><othername>U.</othername>
+	<surname>Pascal</surname>
+      </author>
+    </authorgroup>
+    <pubdate>25 November 2002</pubdate>
+    <abstract>
+
+      <para>
 This guide is aimed to relieve one's labour to create a new (internationalized)
 keyboard layout. Unlike other documents this guide accents the keymap developer's point of view.
-</Para>
+      </para>
 
-</Abstract>
+    </abstract>
 
-</articleinfo>
+  </articleinfo>
 
-<Sect1>
-<Title>Overview</Title>
+  <sect1>
+    <title>Overview</title>
 
-<Para>
+    <para>
 The developer of a new layout should read the xkb
-protocol specification (<ULink
-URL="http://www.x-docs.org/XKB/XKBproto.pdf"
->The X Keyboard Extension: Protocol Specification</ULink
+protocol specification (<ulink
+url="http://www.x-docs.org/XKB/XKBproto.pdf"
+>The X Keyboard Extension: Protocol Specification</ulink
 >) at least
 to clarify for himself some xkb-specific terms used in this document
 and elsewhere in xkb configuration. Also it shows wise to understand
 how the X server and a client digest their keyboard inputs
 (with and without xkb).
-</Para>
+    </para>
 
-<Para>
-A useful source is also <ULink
-URL="http://www.tsu.ru/~pascal/en/xkb"
->Ivan  Pascal's text about xkb configuration</ULink
+    <para>
+A useful source is also <ulink
+url="http://www.tsu.ru/~pascal/en/xkb"
+>Ivan  Pascal's text about xkb configuration</ulink
 > often referenced throughout this
 document.
-</Para>
+    </para>
 
-<Para>
+    <para>
 Note that this document covers only enhancements which
 are to be made to XFree86 version 4.3 and X11R6.7.0 and above.
-</Para>
+    </para>
 
-</Sect1>
+  </sect1>
 
-<Sect1>
-<Title>The Basics</Title>
+  <sect1>
+    <title>The Basics</title>
 
-<Para>
+    <para>
 At the startup (or at later at user's command) X server starts its xkb
 keyboard module extension and reads data from a compiled configuration
 file.
-</Para>
+    </para>
 
-<Para>
-This compiled configuration file is prepared by the program <Literal remap="tt">xkbcomp</Literal>
-which behaves altogether as an ordinary compiler (see <Literal remap="tt">man xkbcomp</Literal>).
+    <para>
+This compiled configuration file is prepared by the
+program <command>xkbcomp</command> which behaves altogether as an
+ordinary compiler (see <userinput>man xkbcomp</userinput>).
 Its input are human readable xkb configuration files which are verified and
 then composed into a useful xkb configuration. Users don't need to mess with
-<Literal remap="tt">xkbcomp</Literal> themselves, for them it is invisible. Usually, it is started
-upon X server startup.
-</Para>
+<command>xkbcomp</command> themselves, for them it is invisible. Usually,
+it is started upon X server startup.
+    </para>
 
-<Para>
+    <para>
 As you probably already know, the xkb configuration consists of five
 main modules:
-<VariableList>
+      <variablelist>
 
-<VarListEntry>
-<Term>Keycodes</Term>
-<ListItem>
-<Para>
+	<varlistentry>
+	  <term>Keycodes</term>
+	  <listitem>
+	    <para>
 Tables that defines translation from keyboard scan codes into reasonable
 symbolic names, maximum, minimum legal keycodes, symbolic aliases and
 description of physically present LED-indicators. The primary sence of
@@ -88,158 +94,154 @@ this component is to allow definitions of maps of symbols (see below)
 to be independent of physical keyboard scancodes. There are two main
 naming conventions for symbolic names (always four bytes long):
 
-<ItemizedList>
-<ListItem>
-
-<Para>
+	      <itemizedlist>
+		<listitem>
+		  <para>
  names which express some traditional meaning like
-<Literal remap="tt">&lt;SPCE&gt;</Literal> (stands for space bar) or
-</Para>
-</ListItem>
-<ListItem>
+<keycode>&lt;SPCE&gt;</keycode> (stands for space bar) or
+		  </para>
+		</listitem>
 
-<Para>
+		<listitem>
+		  <para>
  names which express some relative positioning on a keyboard, for
-example <Literal remap="tt">&lt;AE01&gt;</Literal> (an exclamation mark on US keyboards), on
-the right there are keys <Literal remap="tt">&lt;AE02&gt;</Literal>, <Literal remap="tt">&lt;AE03&gt;</Literal>
+example <keycode>&lt;AE01&gt;</keycode> (an exclamation mark on US keyboards), on
+the right there are keys <keycode>&lt;AE02&gt;</keycode>, <keycode>&lt;AE03&gt;</keycode>
 etc.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>Types</Term>
-<ListItem>
-<Para>
+		  </para>
+		</listitem>
+	      </itemizedlist>
+
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>Types</term>
+	  <listitem>
+	    <para>
 Types describe how the produced key is changed by active modifiers (like
 Shift, Control, Alt, ...). There are several predefined types which
 cover most of used combinations.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>Compat</Term>
-<ListItem>
-<Para>
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>Compat</term>
+	  <listitem>
+	    <para>
 Compatibility component defines internal behaviour of modifiers. Using
 compat component you can assign various actions (elaborately described
 in xkb specification) to key events. This is also the place where
 LED-indicators behaviour is defined.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>Symbols</Term>
-<ListItem>
-<Para>
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>Symbols</term>
+	  <listitem>
+	    <para>
 For i18n purposes, this is the most important table. It defines what
 values (=symbols) are assigned to what keycodes (represented by their
 symbolic name, see above). There may be defined more than one value
 for each key and then it depends on a key type and on modifiers state
 (respective compat component) which value will be the resulting one.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>Geometry</Term>
-<ListItem>
-<Para>
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>Geometry</term>
+	  <listitem>
+	    <para>
 Geometry files aren't used by xkb itself but they may be used by some
 external programs to depict a keyboard image.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
+	    </para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
 All these components have the files located in xkb configuration tree
-in subdirectories with the same names (usually in <Literal remap="tt">/usr/lib/X11/xkb</Literal>).
-</Para>
+in subdirectories with the same names (usually in
+<filename class="directory">/usr/lib/X11/xkb</filename>).
+    </para>
 
-</Sect1>
+  </sect1>
 
-<Sect1>
-<Title>Enhancing XKB Configuration</Title>
+  <sect1>
+    <title>Enhancing XKB Configuration</title>
 
-<Para>
+    <para>
 Most of xkb enhancements concerns a need to define new output symbols
 for the some input key events. In other words, a need to define a new
 symbol map (for a new language, standard or just to feel more comfortable
 when typing text).
-</Para>
+    </para>
 
-<Para>
+    <para>
 What do you need to do? Generally, you have to define following things:
 
-<ItemizedList>
-<ListItem>
-
-<Para>
+      <itemizedlist>
+	<listitem>
+	  <para>
  the map of symbols itself
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
  the rules to allow users to select the new mapping
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
  the description of the new layout
-</Para>
-</ListItem>
+	  </para>
+	</listitem>
+      </itemizedlist>
 
-</ItemizedList>
+    </para>
 
-</Para>
-
-<Para>
+    <para>
 First of all, it is good to go through existing layouts and to examine
 them if there is something you could easily adjust to fit your needs.
 Even if there is nothing similar you may get some ideas about basic
 concepts and used tricks.
-</Para>
+    </para>
 
-<Sect2>
-<Title>Levels And Groups</Title>
+    <sect2>
+      <title>Levels And Groups</title>
 
-<Para>
-Since XFree86 4.3.0 and X11R6.7.0 you can use <Emphasis remap="bf">multi-layout</Emphasis> concept of xkb
+      <para>
+Since XFree86 4.3.0 and X11R6.7.0 you can use
+<firstterm>multi-layout</firstterm> concept of xkb
 configuration.
 Though it is still in boundaries of xkb protocol and general ideas, the
 keymap designer must obey new rules when creating new maps. In exchange
 we get a more powerful and cleaner configuration system.
-</Para>
+      </para>
 
-<Para>
+      <para>
 Remember that it is the application which must decide which symbol
 matches which keycode according to effective modifier state. The X server
 itself sends only an input event message to. Of course, usually
 the general interpretation is processed by Xlib, Xaw, Motif, Qt, Gtk
 and similar libraries. The X server only supplies its mapping table
 (usually upon an application startup).
-</Para>
+      </para>
 
-<Para>
+      <para>
 You can think of the X server's symbol table as of a irregular table where each
 keycode has its row and where each combination of modifiers determines exactly
 one column. The resulting cell then gives the proper symbolic value. Not all
 keycodes need to bind different values for different combination of modifiers.
-<Literal remap="tt">&lt;ENTER&gt;</Literal> key, for instance, usually doesn't depend on any
+<keycode>&lt;ENTER&gt;</keycode> key, for instance, usually doesn't depend on any
 modifiers so it its row has only one column defined.
-</Para>
+      </para>
 
-<Para>
+      <para>
 Note that in XKB there is no prior assumption that certain modifiers are bound
-to certain columns. By editing proper files (see <XRef LinkEnd="keytypes">) this
-mapping can be changed as well.
-</Para>
+to certain columns. By editing proper files (see <xref linkend="keytypes" />)
+this mapping can be changed as well.
+      </para>
 
-<Para>
+      <para>
 Unlike the original X protocol the XKB approach is far more
 flexible. It is comfortable to add one additional XKB term - group. You can
 think of a group as of a vector of columns per each keycode (naturally the
@@ -251,117 +253,102 @@ set has its own group and changing it means selecting a different one.
 XKB approach allows up to four different groups. The columns inside each group
 are called (shift) levels. The X server knows the current group and reports it
 together with modifier set and with a keycode in key events.
-</Para>
+      </para>
 
-<Para>
+      <para>
 To sum it up:
-</Para>
-
-<Para>
 
-<ItemizedList>
-<ListItem>
-
-<Para>
+	<itemizedlist>
+	  <listitem>
+	    <para>
  for each keycode XKB keyboard map contains up to four one-dimensional
 tables - groups (logically different symbol sets)
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
  for each group of a keycode XKB keyboard map contains some columns
 - shift levels (values reached by combinations of Shift, Ctrl, Alt, ...
 modifiers)
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
  different keycodes can have different number of groups
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
  different groups of one keycode can have different number of shift levels
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
  the current group number is tracked by X server
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
+	    </para>
+	  </listitem>
+	</itemizedlist>
+      </para>
 
-<Para>
+      <para>
 It is clear that if you sanely define levels, groups and sanely bind
 modifiers and associated actions you can have simultaneously loaded up to
 four different symbol sets where each of them would reside in its own group.
-</Para>
+      </para>
 
-<Para>
+      <para>
 The multi-layout concept provides a facility to manipulate xkb groups
 and symbol definitions in a way that allows almost arbitrary composition of
 predefined symbol tables. To keep it fully functional you have to:
 
-<ItemizedList>
-<ListItem>
-
-<Para>
+	<itemizedlist>
+	  <listitem>
+	    <para>
  define all symbols only in the first group
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para>
  (re)define any modifiers with extra care to avoid strange (anisometric)
 behaviour
-</Para>
-</ListItem>
-
-</ItemizedList>
+	    </para>
+	  </listitem>
+	</itemizedlist>
 
-</Para>
+      </para>
 
-</Sect2>
+    </sect2>
 
-</Sect1>
+  </sect1>
 
-<Sect1>
-<Title>Defining New Layouts</Title>
+  <sect1>
+    <title>Defining New Layouts</title>
 
 <!--
   TODO: It may be better to merge IP01 docs and this guide.
 -->
 
-<Para>
-See <ULink
-URL="http://www.tsu.ru/~pascal/en/xkb/internals.html"
->Some Words  About XKB internals</ULink
+    <para>
+See <ulink url="http://www.tsu.ru/~pascal/en/xkb/internals.html"
+>Some Words  About XKB internals</ulink
 > for explanation of used xkb terms and problems
 addressed by XKB extension.
-</Para>
+    </para>
 
-<Para>
-See <ULink
-URL="http://www.tsu.ru/~pascal/en/xkb/gram-common.html"
->Common  notes about XKB configuration files language</ULink
+    <para>
+See <ulink url="http://www.tsu.ru/~pascal/en/xkb/gram-common.html"
+>Common  notes about XKB configuration files language</ulink
 > for more precise explanation of
 syntax of xkb configuration files.
-</Para>
+    </para>
 
-<Sect2>
-<Title>Predefined XKB Symbol Sets</Title>
+    <sect2>
+      <title>Predefined XKB Symbol Sets</title>
 
-<Para>
+      <para>
 If you are about to define some European symbol map extension, you might
 want to use on of four predefined latin alphabet layouts.
-</Para>
+      </para>
 
 <!--
     TODO: more details
@@ -369,15 +356,12 @@ want to use on of four predefined latin alphabet layouts.
     TODO: what are pc/pc layouts good for???
 -->
 
-<Para>
+      <para>
 Okay, let's assume you want extend an existing keymap and you want to override
 a few keys. Let's take a simple U.K. keyboard as an example (defined in
-<Literal remap="tt">pc/gb</Literal>):
-</Para>
+<filename>pc/gb</filename>):
 
-<Para>
-
-<Screen>
+	<screen>
 partial default alphanumeric_keys
 xkb_symbols "basic" {
   include "pc/latin"
@@ -394,9 +378,9 @@ xkb_symbols "basic" {
 
   modifier_map Mod5   { &#60;RALT&#62; };
 };
-</Screen>
+	</screen>
 
-</Para>
+      </para>
 
 <!--
     TODO: ref IP01 file syntax TODO: some words about symbolic names like
@@ -405,81 +389,81 @@ xkb_symbols "basic" {
      TODO: ref to compatibility symbolic names vs. unicode
 -->
 
-<Para>
-It defines a new layout in <Literal remap="tt">basic</Literal> variant as an extension of common
+      <para>
+It defines a new layout in <literal remap="tt">basic</literal> variant as an extension of common
 latin alphabet layout. The layout (symbol set) name is set to "Great Britain".
 Then there are redefinitions of a few keycodes and a modifiers binding. As you
-can see the number of shift levels is the same for <Literal remap="tt">&lt;AE02&gt;</Literal>,
-<Literal remap="tt">&lt;AE03&gt;</Literal>, <Literal remap="tt">&lt;AC11&gt;</Literal>, <Literal remap="tt">&lt;TLDE&gt;</Literal> and
-<Literal remap="tt">&lt;BKSL&gt;</Literal> keys but it differs from number of shift levels of
-<Literal remap="tt">&lt;RALT&gt;</Literal>.
-</Para>
-
-<Para>
-Note that the <Literal remap="tt">&lt;RALT&gt;</Literal> key itself is a binding key for Mod5 and
+can see the number of shift levels is the same for
+<keycode>&lt;AE02&gt;</keycode>, <keycode>&lt;AE03&gt;</keycode>,
+<keycode>&lt;AC11&gt;</keycode>, <keycode>&lt;TLDE&gt;</keycode> and
+<keycode>&lt;BKSL&gt;</keycode> keys but it differs from number of shift
+levels of <keycode>&lt;RALT&gt;</keycode>.
+      </para>
+
+      <para>
+Note that the <keycode>&lt;RALT&gt;</keycode> key itself is a binding key for Mod5 and
 that it
 serves like a shift modifier for LevelThree, together with Shift
 as a multi-key. It is a good habit to respect this rule in a new similar
 layout.
-</Para>
+      </para>
 
-<Para>
+      <para>
 Okay, you could now define more variants of your new layout besides
-<Literal remap="tt">basic</Literal> simply by including (augmenting/overriding/...) the basic
+<literal remap="tt">basic</literal> simply by including (augmenting/overriding/...) the basic
 definition and altering what may be needed.
-</Para>
+      </para>
 
-</Sect2>
+    </sect2>
 
-<Sect2 id="keytypes" xreflabel="keytypes">
-<Title>Key Types</Title>
+    <sect2 id="keytypes" xreflabel="keytypes">
+      <title>Key Types</title>
 
-<Para>
+      <para>
 The differences in the number of columns (shift levels) are caused by
 a different types of keys (see the types definition in section basics).  Most
 keycodes have implicitly set the keytype in the included
-<quote><Literal remap="tt">pc/latin</Literal></quote> file to
-<quote><Literal remap="tt">FOUR&lowbar;LEVEL&lowbar;ALPHABETIC</Literal></quote>. The only exception is
-<Literal remap="tt">&lt;RALT&gt;</Literal> keycode which is explicitly set
-<quote><Literal remap="tt">TWO&lowbar;LEVEL</Literal></quote> keytype.
-</Para>
+<quote><filename>pc/latin</filename></quote> file to
+<quote><literal remap="tt">FOUR&lowbar;LEVEL&lowbar;ALPHABETIC</literal></quote>. The only exception is
+<keycode>&lt;RALT&gt;</keycode> keycode which is explicitly set
+<quote><literal remap="tt">TWO&lowbar;LEVEL</literal></quote> keytype.
+      </para>
 
-<Para>
+      <para>
 All those names refer to pre-defined shift level schemes. Usually you can
-choose a suitable shift level scheme from <Literal remap="tt">default</Literal> types scheme list
+choose a suitable shift level scheme from <literal remap="tt">default</literal> types scheme list
 in proper xkb component's subdirectory.
-</Para>
+      </para>
 
-<Para>
+      <para>
 The most used schemes are:
-<VariableList>
-
-<VarListEntry>
-<Term>ONE&lowbar;LEVEL</Term>
-<ListItem>
-<Para>
+	<variablelist>
+	  <varlistentry>
+	    <term>ONE&lowbar;LEVEL</term>
+	    <listitem>
+	      <para>
 The key does not depend on any modifiers. The symbol from first level
 is always chosen.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>TWO&lowbar;LEVEL</Term>
-<ListItem>
-<Para>
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>TWO&lowbar;LEVEL</term>
+	    <listitem>
+	      <para>
 The key uses a modifier Shift and may have two possible values.
 The second level may be chosen by Shift modifier. If Lock modifier
 (usually Caps-lock) applies the symbol is further processed using
 system-specific capitalization rules. If both Shift+Lock modifier apply the
 symbol from the second level is taken and capitalization rules are applied
 (and usually have no effect).
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>ALPHABETIC</Term>
-<ListItem>
-<Para>
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>ALPHABETIC</term>
+	    <listitem>
+	      <para>
 The key uses modifiers Shift and Lock. It may have two possible
 values. The second level may be chosen by Shift modifier. When Lock
 modifier applies, the symbol from the first level is taken and further
@@ -487,13 +471,13 @@ processed using system-specific capitalization rules. If both Shift+Lock
 modifier apply the symbol from the first level is taken and no
 capitalization rules applied. This is often called shift-cancels-caps
 behaviour.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>THREE&lowbar;LEVEL</Term>
-<ListItem>
-<Para>
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>THREE&lowbar;LEVEL</term>
+	    <listitem>
+	      <para>
 Is the same as TWO&lowbar;LEVEL but it considers an extra modifier -
 LevelThree which can be used to gain the symbol value from the third
 level. If both Shift+LevelThree modifiers apply the value from the third
@@ -501,201 +485,183 @@ level is also taken. As in TWO&lowbar;LEVEL, the Lock modifier doesn't influence
 the resulting level. Only Shift and LevelThree are taken into that
 consideration. If the Lock modifier is active capitalization rules
 are applied on the resulting symbol.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>FOUR&lowbar;LEVEL</Term>
-<ListItem>
-<Para>
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>FOUR&lowbar;LEVEL</term>
+	    <listitem>
+	      <para>
 Is the same as THREE&lowbar;LEVEL but unlike LEVEL&lowbar;THREE if both Shift+LevelThree
 modifiers apply the symbol is taken from the fourth level.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>FOUR&lowbar;LEVEL&lowbar;ALPHABETIC</Term>
-<ListItem>
-<Para>
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>FOUR&lowbar;LEVEL&lowbar;ALPHABETIC</term>
+	    <listitem>
+	      <para>
 Is similar to FOUR&lowbar;LEVEL but also defines shift-cancels-caps behaviour
 as in ALPHABETIC. If Lock+LevelThree apply the symbol from the
 third level is taken and the capitalization rules are applied.
 If Lock+Shift+LevelThree apply the symbol from the third level is taken
 and no capitalization rules are applied.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>KEYPAD</Term>
-<ListItem>
-<Para>
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>KEYPAD</term>
+	    <listitem>
+	      <para>
 As the name suggest this scheme is primarily used for numeric keypads.
 The scheme considers two modifiers - Shift and NumLock. If none
 of modifiers applies the symbol from the first level is taken. If either
 Shift or NumLock modifiers apply the symbol from the second level is taken.
 If both Shift+NumLock modifiers apply the symbol from the first level
 is taken. Again, shift-cancels-caps variant.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>FOUR&lowbar;LEVEL&lowbar;KEYPAD</Term>
-<ListItem>
-<Para>
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>FOUR&lowbar;LEVEL&lowbar;KEYPAD</term>
+	    <listitem>
+	      <para>
 Is similar to KEYPAD scheme but considers also LevelThree modifier.
 If LevelThree modifier applies the symbol from the third level is taken.
 If Shift+LevelThree or NumLock+LevelThree apply the symbol from the fourth
 level is taken. If all Shift+NumLock+LevelThree modifiers apply the symbol
 from the third level is taken. This also, shift-cancels-caps variant.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </para>
 
-<Para>
+      <para>
 Besides that, there are several schemes for special purposes:
-<VariableList>
+	<variablelist>
 
-<VarListEntry>
-<Term>PC&lowbar;BREAK</Term>
-<ListItem>
-<Para>
+	  <varlistentry>
+	    <term>PC&lowbar;BREAK</term>
+	    <listitem>
+	      <para>
 It is similar to TWO&lowbar;LEVEL scheme but it considers the Control
 modifier rather than Shift. That means, the symbol from the second level
 is chosen by Control rather than by Shift.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>PC&lowbar;SYSRQ</Term>
-<ListItem>
-<Para>
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>PC&lowbar;SYSRQ</term>
+	    <listitem>
+	      <para>
 It is similar to TWO&lowbar;LEVEL scheme but it considers the Alt modifier rather
 than Shift. That means, the symbol from the second level
 is chosen by Alt rather than by Shift.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>CTRL+ALT</Term>
-<ListItem>
-<Para>
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>CTRL+ALT</term>
+	    <listitem>
+	      <para>
 The key uses modifiers Alt and Control. It may have two possible
 values. If only one modifier (Alt or Control) applies the symbol
 from the first level is chosen. Only if both Alt+Control modifiers apply
 the symbol from the second level is chosen.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>SHIFT+ALT</Term>
-<ListItem>
-<Para>
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>SHIFT+ALT</term>
+	    <listitem>
+	      <para>
 The key uses modifiers Shift and Alt. It may have two possible values.
 If only one modifier (Alt or Shift) applies the symbol
 from the first level is chosen. Only if both Alt+Shift modifiers apply
 the symbol from the second level is chosen.
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-If needed, special <Literal remap="tt">caps</Literal> schemes may be used. They redefine the
-standard behaviour of all <Literal remap="tt">*ALPHABETIC</Literal> types. The layouts (maps of
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </para>
+
+      <para>
+If needed, special <literal remap="tt">caps</literal> schemes may be used.
+They redefine the standard behaviour of all
+<literal remap="tt">*ALPHABETIC</literal> types. The layouts (maps of
 symbols) with keys defined in respective types then automatically change
 their behaviour accordingly. Possible redefinitions are:
 
-<ItemizedList>
-<ListItem>
-
-<Para>
-internal
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-internal&lowbar;nocancel
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-shift
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-shift&lowbar;nocancel
-</Para>
-</ListItem>
-
-</ItemizedList>
+	<itemizedlist>
+	  <listitem><para>internal</para></listitem>
+	  <listitem><para>internal&lowbar;nocancel</para></listitem>
+	  <listitem><para>shift</para></listitem>
+	  <listitem><para>shift&lowbar;nocancel</para></listitem>
+	</itemizedlist>
 
 None of these schemes should be used directly. They are defined merely
-for <Literal remap="tt">'caps:'</Literal> xkb options (used to globally change the layouts
-behaviour).
-</Para>
+for <literal remap="tt">'caps:'</literal> xkb options (used to globally
+change the layouts behaviour).
+      </para>
 
-<Para>
+      <para>
 Don't alter any of existing key types. If you need a different behaviour
 create a new one.
-</Para>
+      </para>
 
-<Sect3>
-<Title>More On Definitions Of Types</Title>
+      <sect3>
+	<title>More On Definitions Of Types</title>
 
-<Para>
+	<para>
 When the XKB software deals with a separate type description it gets
 a complete list of modifiers that should be taken into account from the
-<Literal remap="tt">'modifiers=&lt;list of modifiers&gt;'</Literal> list and expects that a set
-of <Literal remap="tt">'map[&lt;combination of modifiers&gt;]=&lt;list of modifiers&gt;'</Literal>
+<literal remap="tt">'modifiers=&lt;list of modifiers&gt;'</literal> list and expects that a set
+of <literal remap="tt">'map[&lt;combination of modifiers&gt;]=&lt;list of modifiers&gt;'</literal>
 instructions that contain the mapping for each combination of modifiers
 mentioned in that list. Modifiers that are not explicitly listed are NOT taken
 into account
 when the resulting shift level is computed.
 If some combination is omitted the program (subroutine) should choose the first
 level for this combination (a quite reasonable behavior).
-</Para>
+	</para>
 
-<Para>
-Lets consider an example with two modifiers <Literal remap="tt">ModOne</Literal> and <Literal remap="tt">ModTwo</Literal>:
+	<para>
+Lets consider an example with two modifiers <keysym>ModOne</keysym> and
+<keysym>ModTwo</keysym>:
 
-<Screen>
+	  <screen>
 type "..." {
     modifiers = ModOne+ModTwo;
     map[None] = Level1;
     map[ModOne] = Level2;
 };
-</Screen>
+	  </screen>
 
-In this case the map statements for <Literal remap="tt">ModTwo</Literal> only and
-<Literal remap="tt">ModOne+ModTwo</Literal> are omitted.  It means that if the <Literal remap="tt">ModTwo</Literal> is
-active the subroutine can't found explicit mapping for such combination an will
-use the <Emphasis>default level</Emphasis> i.e. Level1.
-</Para>
+In this case the map statements for <keysym>ModTwo</keysym> only and
+<keysym>ModOne+ModTwo</keysym> are omitted.  It means that if
+the <keysym>ModTwo</keysym> is active the subroutine can't found
+explicit mapping for such combination an will use
+the <emphasis>default level</emphasis> i.e. Level1.
+	</para>
 
-<Para>
+	<para>
 But in the case the type described as:
 
-<Screen>
+	  <screen>
 type "..." {
     modifiers = ModOne;
     map[None] = Level1;
     map[ModOne] = Level2;
 };
-</Screen>
+	  </screen>
 
 the ModTwo will not be taken into account and the resulting level depends on
 the ModOne state only. That means, ModTwo alone produces the Level1 but the
 combination ModOne+ModTwo produces the Level2 as well as ModOne alone.
-</Para>
+	</para>
 
-<Para>
+	<para>
 What does it mean if the second modifier is the Lock? It means that in
 the first case (the Lock itself is included in the list of modifiers but
 combinations with this modifier aren't mentioned in the map statements)
@@ -703,67 +669,71 @@ the internal capitalization rules will be applied to the symbol from the first
 level. But in the second case the capitalization will be applied to the symbol
 chosen accordingly to he first modifier - and this can be the symbol from the
 first as well as from the second level.
-</Para>
+	</para>
 
-<Para>
-Usually, all modifiers introduced in <Literal remap="tt">'modifiers=&lt;list of modifiers&gt;'</Literal> list are used for shift level calculation and then
+	<para>
+Usually, all modifiers introduced in <literal remap="tt">'modifiers=&lt;list of modifiers&gt;'</literal> list are used for shift level calculation and then
 discarded. Sometimes this is not desirable. If you want to use a modifier
 for shift level calculation but you don't want to discard it, you may
-list in '<Literal remap="tt">preserve[&lt;combination of modifiers&gt;]=&lt;list of modifiers&gt;'</Literal>. That means, for a given combination all listed modifiers
+list in '<literal remap="tt">preserve[&lt;combination of modifiers&gt;]=&lt;list of modifiers&gt;'</literal>. That means, for a given combination all listed modifiers
 will be preserved. If the Lock modifier is preserved then the resulting
 symbol is passed to internal capitalization routine regardless whether
 it has been used for a shift level calculation or not.
-</Para>
+	</para>
 
-<Para>
+	<para>
 Any key type description can use both real and virtual modifiers. Since real
 modifiers always have standard names it is not necessary to explicitly declare
 them. Virtual modifiers can have arbitrary names and can be declared (prior
 using them) directly in key type definition:
 
-<Screen>
+	  <screen>
 virtual_modifiers &lt;comma-separated list of modifiers&gt;  ;
-</Screen>
+	  </screen>
 
-as seen in for example <Literal remap="tt">basic</Literal>, <Literal remap="tt">pc</Literal> or <Literal remap="tt">mousekeys</Literal> key
+as seen in for example <literal remap="tt">basic</literal>, <literal remap="tt">pc</literal> or <literal remap="tt">mousekeys</literal> key
 type definitions.
-</Para>
+	</para>
 
-</Sect3>
+      </sect3>
 
-</Sect2>
+    </sect2>
 
-<Sect2>
-<Title>Rules</Title>
+    <sect2>
+      <title>Rules</title>
 
-<Para>
+      <para>
 Once you are finished with your symbol map you need to add it
 to rules file. The rules file describes how all the
 five basic keycodes, types, compat, symbols and geometry components
 should be composed to give a sensible resulting xkb configuration.
-</Para>
+      </para>
 
-<Para>
+      <para>
 The main advantage of rules over formerly used keymaps is a possibility
 to simply parameterize (once) fixed patterns of configurations and thus
 to elegantly allow substitutions of various local configurations
 into predefined templates.
-</Para>
+      </para>
 
-<Para>
+      <para>
 A pattern in a rules file (often located in
-<Literal remap="tt">/usr/lib/X11/xkb/rules</Literal>) can be parameterized with four other arguments:
-<Literal remap="tt">Model</Literal>, <Literal remap="tt">Layout</Literal>, <Literal remap="tt">Variant</Literal> and <Literal remap="tt">Options</Literal>.
-For most cases parameters <Literal remap="tt">model</Literal> and <Literal remap="tt">layout</Literal> should
+<filename>/usr/lib/X11/xkb/rules</filename>)
+ can be parameterized with four other arguments:
+<literal remap="tt">Model</literal>, <literal remap="tt">Layout</literal>,
+<literal remap="tt">Variant</literal> and <literal remap="tt">Options</literal>.
+For most cases parameters <literal remap="tt">model</literal> and
+<literal remap="tt">layout</literal> should
 be sufficient for choosing a functional keyboard mapping.
-</Para>
+      </para>
 
-<Para>
-The rules file itself is composed of pattern lines and lines with rules. The pattern line starts with an exclamation mark ('<Literal remap="tt">!</Literal>')
+      <para>
+The rules file itself is composed of pattern lines and lines with rules. The
+pattern line starts with an exclamation mark ('<literal remap="tt">!</literal>')
 and describes how will the xkb interpret the following lines (rules). A sample
 rules file looks like this:
 
-<Screen>
+	<screen>
 ! model 	                =	keycodes
   macintosh_old	                =	macintosh
   ...
@@ -785,45 +755,52 @@ rules file looks like this:
 ! option			=	types
   caps:internal			=	+caps(internal)
   caps:internal_nocancel	=	+caps(internal_nocancel)
-</Screen>
+	</screen>
 
-</Para>
+      </para>
 
-<Para>
+      <para>
 Each rule defines what certain combination of values on the left side
-of equal sign ('<Literal remap="tt">=</Literal>') results in. For example a (keyboard) model
-<Literal remap="tt">macintosh&lowbar;old</Literal> instructs xkb to take definitions of keycodes
-from file <Literal remap="tt">keycodes/macintosh</Literal> while the rest of models
-(represented by a wild card '<Literal remap="tt">*</Literal>') instructs it to take them from
-file <Literal remap="tt">keycodes/xorg</Literal>. The wild card represents all possible
-values on the left side which were not found in any of the previous rules.
-The more specialized (more complete) rules have higher precedence than general
-ones, i.e. the more general rules supply reasonable default values.
-</Para>
-
-<Para>
+of equal sign ('<literal remap="tt">=</literal>') results in. For
+example a (keyboard) model <literal remap="tt">macintosh&lowbar;old</literal>
+instructs xkb to take definitions of keycodes from
+file <filename>keycodes/macintosh</filename> while the rest
+of models (represented by a wild card '<literal remap="tt">*</literal>')
+instructs it to take them from file <filename>keycodes/xorg</filename>.
+The wild card represents all possible values on the left side which
+were not found in any of the previous rules.  The more specialized
+(more complete) rules have higher precedence than general ones,
+i.e. the more general rules supply reasonable default values.
+      </para>
+
+      <para>
 As you can see some lines contain substitution parameters - the parameters
-preceded by the percent sign ('<Literal remap="tt">&percnt;</Literal>'). The first alphabetical character
-after the percent sign expands to the value which has been found on the left
-side. For example <Literal remap="tt">+&percnt;l&percnt;(v)</Literal> expands into <Literal remap="tt">+cz(bksl)</Literal> if the
-respective values on the left side were <Literal remap="tt">cz</Literal> layout in its <Literal remap="tt">bksl</Literal>
-variant. More, if the layout resp. variant  parameter is followed by a pair of
-brackets ('<Literal remap="tt">[</Literal>', '<Literal remap="tt">]</Literal>') it means that xkb should <Emphasis>place the
-layout resp. variant into specified xkb group</Emphasis>. If the brackets are omitted
-the first group is the default value.
-</Para>
-
-<Para>
+preceded by the percent sign ('<literal remap="tt">&percnt;</literal>').
+The first alphabetical character after the percent sign expands to the
+value which has been found on the left side. For
+example <literal remap="tt">+&percnt;l&percnt;(v)</literal> expands
+into <literal remap="tt">+cz(bksl)</literal> if the respective values
+on the left side were <literal remap="tt">cz</literal> layout in
+its <literal remap="tt">bksl</literal> variant. More, if the layout
+resp. variant parameter is followed by a pair of brackets
+('<literal remap="tt">[</literal>', '<literal remap="tt">]</literal>')
+it means that xkb should <emphasis>place the layout resp. variant into
+specified xkb group</emphasis>. If the brackets are omitted the first
+group is the default value.
+      </para>
+
+      <para>
 So the second block of rules enhances symbol definitions for some particular
 keyboard models with extra keys (for internet, multimedia, ...) . Other models
 are left intact. Similarly, the last block overrides some key type definitions,
 so the common global behaviour ''shift cancels caps'' or ''shift doesn't cancel
 caps'' can be selected. The rest of rules produces special symbols for each
-variant <Literal remap="tt">us</Literal> layout of <Literal remap="tt">macintosh</Literal> keyboard and standard pc
+variant <literal remap="tt">us</literal> layout of
+<literal remap="tt">macintosh</literal> keyboard and standard pc
 symbols in appropriate variants as a default.
-</Para>
+      </para>
 
-</Sect2>
+    </sect2>
 
 <!--
   TODO: more words about group switching (XkbOptions grp:...)?
@@ -834,36 +811,37 @@ symbols in appropriate variants as a default.
   TODO: better and more complex explanation of rules
 -->
 
-<Sect2>
-<Title>Descriptive Files of Rules</Title>
+    <sect2>
+      <title>Descriptive Files of Rules</title>
 
-<Para>
-Now you just need to add a detailed description to <Literal remap="tt">&lt;rules&gt;.xml</Literal>
+      <para>
+Now you just need to add a detailed description to
+<filename>&lt;rules&gt;.xml</filename>
 description file so the other users (and external programs which often parse
 this file) know what is your work about.
-</Para>
+      </para>
 
 <!--
     TODO: format and semantics
 -->
 
-<Sect3>
-<Title>Old Descriptive Files</Title>
+      <sect3>
+	<title>Old Descriptive Files</title>
 
-<Para>
-The formerly used descriptive files were named <Literal remap="tt">&lt;rules&gt;.lst</Literal>
+	<para>
+The formerly used descriptive files were named <filename>&lt;rules&gt;.lst</filename>
 Its structure is very simple and quite self descriptive but such simplicity
 had also some cavities, for example there was no way how to describe local
 variants of layouts and there were problems with the localization of
 descriptions. To preserve compatibility with some older programs,
 new XML descriptive files can be converted to old format '.lst'.
-</Para>
+	</para>
 
-<Para>
+	<para>
 For each parameter of rules file should be described its meaning. For the rules
-file described above the <Literal remap="tt">.lst</Literal> file could look like:
+file described above the <filename>.lst</filename> file could look like:
 
-<Screen>
+	  <screen>
 ! model
   pc104		Generic 104-key PC
   microsoft	Microsoft Natural
@@ -881,18 +859,18 @@ file described above the <Literal remap="tt">.lst</Literal> file could look like
   caps:internal		 uses internal capitalization. Shift cancels Caps
   caps:internal_nocancel uses internal capitalization. Shift doesn't cancel Caps
 
-</Screen>
+	  </screen>
 
-</Para>
+	</para>
 
-<Para>
+	<para>
 And that should be it. Enjoy creating your own xkb mapping.
-</Para>
+	</para>
 
-</Sect3>
+      </sect3>
 
-</Sect2>
+    </sect2>
 
-</Sect1>
+  </sect1>
 
-</Article>
+</article>
diff --git a/sgml/Makefile.am b/sgml/Makefile.am
index 9e1a732..b72c23e 100644
--- a/sgml/Makefile.am
+++ b/sgml/Makefile.am
@@ -20,7 +20,7 @@
 #
 #  Process this file with autoconf to create configure.
 
-SUBDIRS = fonts graphics input platforms
+SUBDIRS = fonts graphics platforms
 
 x11docdir = $(docdir)
 SGML_FILES = \
diff --git a/sgml/input/Makefile.am b/sgml/input/Makefile.am
deleted file mode 100644
index 226c217..0000000
--- a/sgml/input/Makefile.am
+++ /dev/null
@@ -1,5 +0,0 @@
-#  Process this file with automake to create Makefile.in
-
-x11docdir = $(docdir)/input
-SGML_FILES = XKB-Config.sgml XKB-Enhancing.sgml
-include $(top_srcdir)/sgmlrules.in
diff --git a/sgml/input/XKB-Config.sgml b/sgml/input/XKB-Config.sgml
deleted file mode 100644
index f9df0bf..0000000
--- a/sgml/input/XKB-Config.sgml
+++ /dev/null
@@ -1,366 +0,0 @@
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
-<!ENTITY % defs SYSTEM "X11/defs.ent"> %defs;
-]>
-
-<Article>
-
-<articleinfo>
-
-<Title>The XKB Configuration Guide</Title>
-<AUTHOR
->
-<FirstName>Kamil Toman, Ivan U. Pascal</FirstName>
-</AUTHOR
->
-<PubDate>25 November 2002
-</PubDate>
-
-<Abstract>
-
-<Para>
-This document describes how to configure X11R&relvers; XKB from a user's point
-of view. It covers basic configuration syntax and gives also a few examples.
-</Para>
-
-</Abstract>
-
-</articleinfo>
-
-<Sect1>
-<Title>Overview</Title>
-
-<Para>
-The XKB configuration is decomposed into a number of components. Selecting
-proper parts and combining them back you can achieve most of the configurations
-you might need. Unless you have a completely atypical keyboard you really don't
-need to touch any of the xkb configuration files.
-</Para>
-
-</Sect1>
-
-<Sect1>
-<Title>Selecting XKB Configuration</Title>
-
-<Para>
-The easiest and the most natural way to specify a keyboard mapping is to use
-the <Literal remap="tt">rules</Literal> component. As its name suggests it describes a number of
-general rules to combine all bits and pieces into a valid and useful keyboard
-mapping. All you need to do is to select a suitable rules file and then to
-feed it with a few parameters that will adjust the keyboard behaviour to
-fulfill your needs.
-</Para>
-
-<Para>
-The parameters are:
-
-<ItemizedList>
-<ListItem>
-
-<Para>
-<Literal remap="tt">XkbRules </Literal>- files of rules to be used for keyboard mapping
-composition
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-<Literal remap="tt">XkbModel </Literal>- name of the model of your keyboard type
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-<Literal remap="tt">XkbLayout </Literal>- layout(s) you intend to use
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-<Literal remap="tt">XkbVariant </Literal>- variant(s) of the layout you intend to use
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-<Literal remap="tt">XkbOptions </Literal>- extra xkb configuration options
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-
-<Para>
-The proper rules file depends on your vendor. In reality, the commonest
-file of rules is <Literal remap="tt">xorg</Literal>. For each rules file there is a description
-file named <Literal remap="tt">&lt;vendor-rules&gt;.lst</Literal>, for instance <Literal remap="tt">xorg.lst</Literal>
-which is located in the xkb configuration subdirectory <Literal remap="tt">rules</Literal>
-(for example <Literal remap="tt">/etc/X11/xkb/rules</Literal>).
-</Para>
-
-<Sect2>
-<Title>Basic Configuration</Title>
-
-<Para>
-Let's say you want to configure a PC-style American keyboard with 104
-keys as described in <Literal remap="tt">xorg.lst</Literal>.  This can be done by simply writing
-several lines from below to your xorg.conf configuration file (previously known
-as <Literal remap="tt">/etc/X11/XF86Config-4</Literal> or <Literal remap="tt">/etc/X11/XF86Config</Literal>):
-
-<Screen>
-Section "InputDevice"
-    Identifier "Keyboard1"
-    Driver "kbd"
-
-    Option "XkbModel" "pc104"
-    Option "XkbLayout" "us"
-    Option "XKbOptions" ""
-EndSection
-</Screen>
-
-The values of <Literal remap="tt">XkbModel</Literal> and <Literal remap="tt">XkbLayout</Literal> are really
-not surprising. The <Literal remap="tt">XkbOptions</Literal> has been explicitly set to
-the empty set of parameters. The <Literal remap="tt">XkbVariant</Literal> option has been left out.
-That means the default variant named <Literal remap="tt">basic</Literal> is loaded.
-</Para>
-
-<Para>
-Of course, this can be also done at runtime using the utility setxkbmap.
-The shell command loading the same keyboard mapping would look like:
-
-<Screen>
-setxkbmap -rules xorg -model pc104 -layout us -option ""
-</Screen>
-
-The configuration and the shell command would be very analogous
-for most other layouts (internationalized mappings).
-</Para>
-
-</Sect2>
-
-<Sect2>
-<Title>Advanced Configuration</Title>
-
-<Para>
-You can use multi-layouts xkb configuration.
-What does it mean? Basically it allows to load up to four different
-keyboard layouts at a time. Each such layout would reside in its
-own group. The groups (unlike complete keyboard remapping) can be
-switched very fast from one to another by a combination of keys.
-</Para>
-
-<Para>
-Let's say you want to configure your new Logitech cordless desktop
-keyboard, you intend to use three different layouts at the same
-time - us, czech and german (in this order), and that you are used
-to <Literal remap="tt">Alt-Shift</Literal> combination for switching among them.
-</Para>
-
-<Para>
-Then the configuration snippet could look like this:
-
-<Screen>
-Section "InputDevice"
-    Identifier "Keyboard1"
-    Driver "kbd"
-
-    Option "XkbModel" "logicordless"
-    Option "XkbLayout" "us,cz,de"
-    Option "XKbOptions" "grp:alt_shift_toggle"
-EndSection
-</Screen>
-
-Of course, this can be also done at runtime using the utility setxkbmap.
-The shell command loading the same keyboard mapping would look like:
-
-<Screen>
-setxkbmap -rules xorg -model logicordless -layout "us,cz,de" \
-         -option "grp:alt_shift_toggle"
-</Screen>
-
-</Para>
-
-</Sect2>
-
-<Sect2>
-<Title>Even More Advanced Configuration</Title>
-
-<Para>
-Okay, let's say you are more demanding. You do like the example
-above but you want it to change a bit. Let's imagine you want
-the czech keyboard mapping to use another variant but basic.
-The configuration snippet then changes into:
-
-<Screen>
-Section "InputDevice"
-    Identifier "Keyboard1"
-    Driver "kbd"
-
-    Option "XkbModel" "logicordless"
-    Option "XkbLayout" "us,cz,de"
-    Option "XkbVariant" ",bksl,"
-    Option "XKbOptions" "grp:alt_shift_toggle"
-EndSection
-</Screen>
-
-That seems tricky but it is not. The logic for settings of variants
-is the same as for layouts, that means the first and the third variant
-settings are left out (set to <Literal remap="tt">basic</Literal>), the second is set to
-<Literal remap="tt">bksl</Literal> (a special variant with an enhanced definition of the backslash
-key).
-</Para>
-
-<Para>
-Analogously, the loading runtime will change to:
-
-<Screen>
-setxkbmap -rules xorg -model logicordless -layout "us,cz,de" \
-         -variant ",bksl," -option "grp:alt_shift_toggle"
-</Screen>
-
-</Para>
-
-</Sect2>
-
-<Sect2>
-<Title>Basic Global Options</Title>
-
-<Para>
-For a list of available options, with a short decription of what they do,
-see the section starting with "! option" in the rules/*.lst files.
-</Para>
-
-<!--
-  TODO: More detailed descriptions of options. Users often get confused.
--->
-
-</Sect2>
-
-</Sect1>
-
-<Sect1>
-<Title>Direct XKB Configuration</Title>
-
-<Para>
-Generally, you can directly prescribe what configuration of each of basic
-xkb components should be used to form the resulting keyboard mapping.
-This method is rather "brute force". You precisely need to know the structure
-and the meaning of all of used configuration components.
-</Para>
-
-<Para>
-This method also exposes all xkb configuration details directly into xorg.conf
-configuration file which is a not very fortunate fact.
-In rare occasions it may be needed, though. So how does it work?
-</Para>
-
-<Sect2>
-<Title>Basic Components</Title>
-
-<Para>
-There are five basic components used to form a keyboard mapping:
-
-<ItemizedList>
-<ListItem>
-
-<Para>
-<Emphasis>key codes</Emphasis> - a translation of the scan codes produced by the
-keyboard into a suitable symbolic form
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-<Emphasis>types</Emphasis> - a specification of what various combinations of
-modifiers produce
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-<Emphasis>key symbols</Emphasis> - a translation of symbolic key codes into actual
-symbols
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-<Emphasis>geometry</Emphasis> - a description of physical keyboard geometry
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-<Emphasis>compatibility maps</Emphasis> - a specification of what action should
-each key produce in order to preserve compatibility with XKB-unware clients
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-
-</Sect2>
-
-<Sect2>
-<Title>Example Configuration</Title>
-
-<Para>
-Look at the following example:
-
-<Screen>
-Section "InputDevice"
-    Identifier "Keyboard0"
-    Driver "kbd"
-
-    Option "XkbKeycodes" "xorg"
-    Option "XkbTypes"    "default"
-    Option "XkbSymbols"  "en_US(pc104)+de+swapcaps"
-    Option "XkbGeometry" "pc(pc104)"
-    Option "XkbCompat"   "basic+pc+iso9995"
-EndSection
-</Screen>
-
-</Para>
-
-<Para>
-This configuration sets the standard X server default interpretation of keyboard
-keycodes, and sets the default modifier types. The
-symbol table is composed of extended US keyboard layout in its
-variant for pc keyboards with 104 keys plus all keys
-for german layout are redefined respectively. Also the logical
-meaning of <Literal remap="tt">Caps-lock</Literal> and <Literal remap="tt">Control</Literal> keys is swapped.
-The standard keyboard geometry (physical look) is set to pc style
-keyboard with 104 keys. The compatibility map is set to allow
-basic shifting, to allow Alt keys to be interpreted and also
-to allow iso9995 group shifting.
-</Para>
-
-<!--
-    TODO: add information about layout shifting:
-    TODO: us+ru(winkeys):2+de:3
--->
-
-</Sect2>
-
-</Sect1>
-
-<Sect1>
-<Title>Keymap XKB Configuration</Title>
-
-<Para>
-Keymap configuration is the way formerly used to configure xkb. The
-user included a special keymap file which specified the direct xkb
-configuration. This method has been obsoleted by previously described
-rules files which are far more flexible and allow simpler and more
-intuitive syntax. It is preserved merely for compatibility reasons and
-should be avoided if possible.
-</Para>
-
-</Sect1>
-
-</Article>