[PATCH] Xkb-Config.xml: update for current releases

[Alan Coopersmith]

- Document xorg.conf.d keyboard matches instead of kbd driver entries
  in xorg.conf
- Update to current xkb-config file names & paths, and link to the
  xkb-config project site

Signed-off-by: Alan Coopersmith <alan.coopersmith at oracle.com>
---
 general/input/XKB-Config.xml |   69 +++++++++++++++++++++++++-----------------
 1 files changed, 41 insertions(+), 28 deletions(-)

HTML & Text output of the document with these changes applied can be found at:
     http://people.freedesktop.org/~alanc/input/XKB-Config.html
     http://people.freedesktop.org/~alanc/input/XKB-Config.txt

diff --git a/general/input/XKB-Config.xml b/general/input/XKB-Config.xml
index 118f189..dd60854 100644
--- a/general/input/XKB-Config.xml
+++ b/general/input/XKB-Config.xml
@@ -17,13 +17,17 @@
 	<surname>Pascal</surname>
       </author>
     </authorgroup>
-    <pubdate>25 November 2002</pubdate>
+    <pubdate>November 2010</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.
+This version covers Xorg server versions 1.8 and later, used with the
+data files from the <ulink
+url="http://www.freedesktop.org/wiki/Software/XKeyboardConfig"
+>xkeyboard-config</ulink> project.
       </para>
 
     </abstract>
@@ -40,6 +44,14 @@ you might need. Unless you have a completely atypical keyboard you really don't
 need to touch any of the xkb configuration files.
     </para>
 
+    <para>
+Some desktop environments now provide integrated graphical configuration tools
+for setting XKB configuration as part of your desktop session.   These
+instructions are provided for those without such support, those who need to
+configure XKB before the session startup (such as at the login screen), or
+those who need to perform more advanced configuration than those tools provide.
+    </para>
+
   </sect1>
 
   <sect1>
@@ -98,13 +110,14 @@ files of rules to be used for keyboard mapping composition
     </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
+The rules file commonly used with Xorg is the <filename>base</filename>
+rules provided by xkeyboard-config.  Some additional rules files exist
+for historical reasons, but are no longer widely used.
+For each rules file there is a description file named
 <filename>&lt;<replaceable>vendor-rules</replaceable>&gt;.lst</filename>,
-for instance <filename>xorg.lst</filename> which is located in
+for instance <filename>base.lst</filename> which is located in
 the xkb configuration subdirectory <filename>rules</filename>
-(for example <filename>/etc/X11/xkb/rules</filename>).
+(for example <filename>/usr/share/X11/xkb/rules</filename>).
     </para>
 
     <sect2>
@@ -112,16 +125,16 @@ the xkb configuration subdirectory <filename>rules</filename>
 
       <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>):
+keys as described in <filename>base.lst</filename>.  This can be done
+by simply writing several lines from below to a new configuration file
+in <filename>/etc/X11/xorg.conf.d</filename>, such
+as <filename>/etc/X11/xorg.conf.d/90-custom-kbd.conf</filename>.
 
- 	<screen>
-Section "InputDevice"
-    Identifier "Keyboard1"
-    Driver "kbd"
+
+	<screen>
+Section "InputClass"
+    Identifier "keyboard defaults"
+    MatchIsKeyboard "on"
 
     Option "XkbModel" "pc104"
     Option "XkbLayout" "us"
@@ -143,7 +156,7 @@ Of course, this can be also done at runtime using the utility
 The shell command loading the same keyboard mapping would look like:
 
 	<screen>
-setxkbmap -rules xorg -model pc104 -layout us -option ""
+setxkbmap -rules base -model pc104 -layout us -option ""
 	</screen>
 
 The configuration and the shell command would be very analogous
@@ -175,9 +188,9 @@ combination for switching among them.
 Then the configuration snippet could look like this:
 
 	<screen>
-Section "InputDevice"
-    Identifier "Keyboard1"
-    Driver "kbd"
+Section "InputClass"
+    Identifier        "logicordless"
+    MatchIsKeyboard   "on"
 
     Option "XkbModel" "logicordless"
     Option "XkbLayout" "us,cz,de"
@@ -190,7 +203,7 @@ Of course, this can be also done at runtime using the utility
 The shell command loading the same keyboard mapping would look like:
 
 	<screen>
-setxkbmap -rules xorg -model logicordless -layout "us,cz,de" \
+setxkbmap -rules base -model logicordless -layout "us,cz,de" \
          -option "grp:alt_shift_toggle"
 	</screen>
 
@@ -208,9 +221,9 @@ the czech keyboard mapping to use another variant but basic.
 The configuration snippet then changes into:
 
 	<screen>
-Section "InputDevice"
-    Identifier "Keyboard1"
-    Driver "kbd"
+Section "InputClass"
+    Identifier        "logicordless"
+    MatchIsKeyboard   "on"
 
     Option "XkbModel" "logicordless"
     Option "XkbLayout" "us,cz,de"
@@ -230,7 +243,7 @@ variant with an enhanced definition of the backslash key).
 Analogously, the loading runtime will change to:
 
 	<screen>
-setxkbmap -rules xorg -model logicordless -layout "us,cz,de" \
+setxkbmap -rules base -model logicordless -layout "us,cz,de" \
          -variant ",bksl," -option "grp:alt_shift_toggle"
 	</screen>
 
@@ -328,11 +341,11 @@ each key produce in order to preserve compatibility with XKB-unware clients
 Look at the following example:
 
 	<screen>
-Section "InputDevice"
-    Identifier "Keyboard0"
-    Driver "kbd"
+Section "InputClass"
+    Identifier        "keyboard defaults"
+    MatchIsKeyboard   "on"
 
-    Option "XkbKeycodes" "xorg"
+    Option "XkbKeycodes" "base"
     Option "XkbTypes"    "default"
     Option "XkbSymbols"  "en_US(pc104)+de+swapcaps"
     Option "XkbGeometry" "pc(pc104)"
-- 
1.7.3.2