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

[Peter Hutterer]

On Mon, Nov 01, 2010 at 05:21:57PM -0700, Alan Coopersmith wrote:
> - 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.

nitpick: "These instructions" isn't quite correct here, better use "The
instructions herein" or something like this.

> +    </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>


base or evdev. using base with evdev gives a few funny bugs.

> +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

I would skip the -rules bit in the setxkbmap examples, because the rules are
usually selected already (e.g. evdev forces "evdev") and not tampering with
it is safer for the user.

Cheers,
  Peter