Install more manual pages:

* XKB-Config(7), XKB-Enhancing(7): user-level documentation
for XKB configuration; not perfect, but the best available.
* xtrans(3): a library actively maintained upstream.
* libXmu and libXext: Many libraries are effectively frozen upstream.
According to matthieu@, the documentation of libXmu and libXext
is among the most valuable of those.
Feedback and OK matthieu@.

4 files changed, 916 insertions, 2 deletions

diff --git a/doc/xorg-docs/Makefile.bsd-wrapper b/doc/xorg-docs/Makefile.bsd-wrapper
index 075b2b6c0..f1a5b1091 100644
--- a/doc/xorg-docs/Makefile.bsd-wrapper
+++ b/doc/xorg-docs/Makefile.bsd-wrapper
@@ -1,8 +1,10 @@
-# $OpenBSD: Makefile.bsd-wrapper,v 1.5 2019/05/05 23:27:58 schwarze Exp $
+# $OpenBSD: Makefile.bsd-wrapper,v 1.6 2019/05/10 11:44:39 schwarze Exp $
 
 CONFIGURE_ARGS += --without-fop --without-xmlto
 
-MDOCS =	general/fonts/fonts
+MDOCS =	general/fonts/fonts \
+	general/input/XKB-Config \
+	general/input/XKB-Enhancing
 
 beforeinstall:
 .for n in ${MDOCS}
diff --git a/doc/xorg-docs/general/input/XKB-Config.7 b/doc/xorg-docs/general/input/XKB-Config.7
new file mode 100644
index 000000000..44979185d
--- /dev/null
+++ b/doc/xorg-docs/general/input/XKB-Config.7
@@ -0,0 +1,239 @@
+.\" automatically generated with docbook2mdoc XKB-Config.xml
+.Dd November 2010
+.Dt XKB-CONFIG 7
+.Os
+.Sh NAME
+.Nm XKB-Config
+.Nd The XKB Configuration Guide
+.Sh ABSTRACT
+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.
+.Pp
+This version covers Xorg server versions 1.8 and later, used with the
+data files from the
+.Lk http://www.freedesktop.org/wiki/Software/XKeyboardConfig xkeyboard-config
+project.
+.Sh OVERVIEW
+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.
+.Pp
+Some desktop environments now provide integrated graphical configuration
+tools for setting XKB configuration as part of your desktop session.
+The
+instructions in this document 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.
+.Sh SELECTING XKB CONFIGURATION
+The easiest and the most natural way to specify a keyboard mapping is to use
+the
+.Ql rules
+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.
+.Pp
+The parameters are:
+.Bl -tag -width Ds
+.It Fl XkbRules
+files of rules to be used for keyboard mapping composition
+.It Fl XkbModel
+name of the model of your keyboard type
+.It Fl XkbLayout
+layout(s) you intend to use
+.It Fl XkbVariant
+variant(s) of the layout you intend to use
+.It Fl XkbOptions
+extra xkb configuration options
+.El
+.Pp
+The rules file used depends on your system.
+The rules files commonly
+used with Xorg are provided by the
+.Lk http://www.freedesktop.org/wiki/Software/XKeyboardConfig xkeyboard-config
+project.
+On Linux systems, the
+.Pa evdev
+rules are most
+commonly used, on other systems the
+.Pa base
+rules
+are used.
+Some additional rules files exist for historical reasons,
+but are no longer widely used.
+In general, it's best to simply not
+specify the rules file, in order to use the default rules selected
+automatically by the X server.
+.Pp
+For each rules file there is a description file named
+.Pa < Ns Ar vendor-rules Ns > . Ns lst ,
+for instance
+.Pa base.lst
+which is located in
+the xkb configuration subdirectory
+.Pa rules
+(for example
+.Pa /usr/share/X11/xkb/rules ) .
+.Ss Basic Configuration
+Let's say you want to configure a PC-style American keyboard with 104
+keys as described in
+.Pa base.lst .
+This can be done
+by simply writing several lines from below to a new configuration file
+in
+.Pa /etc/X11/xorg.conf.d ,
+such
+as
+.Pa /etc/X11/xorg.conf.d/90-custom-kbd.conf .
+.Bd -literal
+Section "InputClass"
+    Identifier "keyboard defaults"
+    MatchIsKeyboard "on"
+    Option "XkbModel" "pc104"
+    Option "XkbLayout" "us"
+    Option "XKbOptions" ""
+EndSection
+.Ed
+.Pp
+The values of
+.Fl XkbModel
+and
+.Fl XkbLayout
+are
+really not surprising.
+The
+.Fl XkbOptions
+has been explicitly set to the empty set of parameters.
+The
+.Fl XkbVariant
+option has been left out.
+That means the default variant named
+.Ql basic
+is loaded.
+.Pp
+Of course, this can be also done at runtime using the utility
+.Nm setxkbmap .
+The shell command loading the same keyboard mapping would look like:
+.Bd -literal
+setxkbmap -model pc104 -layout us -option ""
+.Ed
+.Pp
+The configuration and the shell command would be very analogous
+for most other layouts (internationalized mappings).
+.Pp
+If you wanted to enable the
+.Sy Ctrl
+.Sy Alt Ns Sy Backspace
+sequence to kill
+the X server by default, you could create a configuration snippet
+.Pa /etc/X11/xorg.conf.d/90-zap.conf
+containing:
+.Bd -literal
+Section "InputClass"
+    Identifier "keyboard defaults"
+    MatchIsKeyboard "on"
+    Option "XKbOptions" "terminate:ctrl_alt_bksp"
+EndSection
+.Ed
+.Pp
+This would be equivalent to running the shell command:
+.Bd -literal
+setxkbmap -option "terminate:ctrl_alt_bksp"
+.Ed
+.Ss Advanced Configuration
+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.
+.Pp
+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
+.Sy Alt Ns Sy Shift
+combination for switching among them.
+.Pp
+Then the configuration snippet could look like this:
+.Bd -literal
+Section "InputClass"
+    Identifier "Logitech Cordless"
+    MatchIsKeyboard   "on"
+    Option "XkbModel" "logicordless"
+    Option "XkbLayout" "us,cz,de"
+    Option "XKbOptions" "grp:alt_shift_toggle"
+EndSection
+.Ed
+.Pp
+Of course, this can be also done at runtime using the utility
+.Nm setxkbmap .
+The shell command loading the same keyboard mapping would look like:
+.Bd -literal
+setxkbmap -model logicordless -layout "us,cz,de" \e
+         -option "grp:alt_shift_toggle"
+.Ed
+.Ss Even More Advanced Configuration
+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:
+.Bd -literal
+Section "InputClass"
+    Identifier "Logitech Cordless"
+    MatchIsKeyboard   "on"
+    Option "XkbModel" "logicordless"
+    Option "XkbLayout" "us,cz,de"
+    Option "XkbVariant" ",bksl,"
+    Option "XKbOptions" "grp:alt_shift_toggle" EndSection
+.Ed
+.Pp
+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
+.Ql basic ) ,
+the second is set to
+.Ql bksl
+(a special
+variant with an enhanced definition of the backslash key).
+.Pp
+Analogously, the loading runtime will change to:
+.Bd -literal
+setxkbmap -model logicordless -layout "us,cz,de" \e
+         -variant ",bksl," -option "grp:alt_shift_toggle"
+.Ed
+.Ss Basic Global Options
+For a list of available options, with a short description of what they do,
+see the section starting with
+.Dq Li ! option
+in the
+.Pa rules/*.lst
+files.
+.Sh KEYMAP XKB CONFIGURATION
+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.
+.Sh AUTHORS
+.An -nosplit
+X Version 11, Release 6
+.An -split
+.An Kamil Toman
+.An Ivan U. Pascal
diff --git a/doc/xorg-docs/general/input/XKB-Enhancing.7 b/doc/xorg-docs/general/input/XKB-Enhancing.7
new file mode 100644
index 000000000..8b6b076ef
--- /dev/null
+++ b/doc/xorg-docs/general/input/XKB-Enhancing.7
@@ -0,0 +1,672 @@
+.\" automatically generated with docbook2mdoc XKB-Enhancing.xml
+.Dd 25 November 2002
+.Dt XKB-ENHANCING 7
+.Os
+.Sh NAME
+.Nm XKB-Enhancing
+.Nd How to further enhance XKB configuration
+.Sh ABSTRACT
+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.
+.Sh OVERVIEW
+The developer of a new layout should read the xkb
+protocol specification
+.Pf ( Lk http://www.x.org/docs/XKB/XKBproto.pdf "The X Keyboard Extension: Protocol Specification" )
+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).
+.Pp
+A useful source is also
+.Lk http://www.tsu.ru/~pascal/en/xkb "Ivan Pascal's text about xkb configuration"
+often referenced throughout this
+document.
+.Pp
+Note that this document covers only enhancements which
+are to be made to XFree86 version 4.3 and X11R6.7.0 and above.
+.Sh THE BASICS
+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.
+.Pp
+This compiled configuration file is prepared by the
+program
+.Nm xkbcomp
+which behaves altogether as an
+ordinary compiler (see
+.Ql man xkbcomp ) .
+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
+.Nm xkbcomp
+themselves, for them it is invisible.
+Usually,
+it is started upon X server startup.
+.Pp
+As you probably already know, the xkb configuration consists of five
+main modules:
+.Bl -tag -width Ds
+.It Keycodes
+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 sense of
+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):
+.Bl -bullet
+.It
+names which express some traditional meaning like
+<SPCE> (stands for space bar) or
+.It
+names which express some relative positioning on a keyboard, for
+example <AE01> (an exclamation mark on US keyboards), on
+the right there are keys <AE02>, <AE03>
+etc.
+.El
+.It Types
+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.
+.It Compat
+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.
+.It Symbols
+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.
+.It Geometry
+Geometry files aren't used by xkb itself but they may be used by some
+external programs to depict a keyboard image.
+.El
+.Pp
+All these components have the files located in xkb configuration tree
+in subdirectories with the same names (usually in
+.Pa /usr/lib/X11/xkb ) .
+.Sh ENHANCING XKB CONFIGURATION
+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).
+.Pp
+What do you need to do?
+Generally, you have to define following things:
+.Bl -bullet
+.It
+the map of symbols itself
+.It
+the rules to allow users to select the new mapping
+.It
+the description of the new layout
+.El
+.Pp
+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.
+.Ss Levels And Groups
+Since XFree86 4.3.0 and X11R6.7.0 you can use
+.Em multi-layout
+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.
+.Pp
+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).
+.Pp
+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.
+<ENTER> key, for instance, usually doesn't depend on any
+modifiers so it its row has only one column defined.
+.Pp
+Note that in XKB there is no prior assumption that certain modifiers are bound
+to certain columns.
+By editing proper files (see
+.Sx Key_Types )
+this mapping can be changed as well.
+.Pp
+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
+dimension of this vector may differ for different keycodes). What is it good
+for?
+The group is not very useful unless you intend to use more than one
+logically different set of symbols (like more than one alphabet) defined in a
+single mapping table.
+But then, the group has a natural meaning - each symbol
+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.
+.Pp
+To sum it up:
+.Bl -bullet
+.It
+for each keycode XKB keyboard map contains up to four one-dimensional
+tables - groups (logically different symbol sets)
+.It
+for each group of a keycode XKB keyboard map contains some columns
+- shift levels (values reached by combinations of Shift, Ctrl, Alt, ...
+modifiers)
+.It
+different keycodes can have different number of groups
+.It
+different groups of one keycode can have different number of shift levels
+.It
+the current group number is tracked by X server
+.El
+.Pp
+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.
+.Pp
+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:
+.Bl -bullet
+.It
+define all symbols only in the first group
+.It
+(re)define any modifiers with extra care to avoid strange (anisometric)
+behaviour
+.El
+.Sh DEFINING NEW LAYOUTS
+See
+.Lk http://www.tsu.ru/~pascal/en/xkb/internals.html "Some Words About XKB internals"
+for explanation of used xkb terms and problems
+addressed by XKB extension.
+.Pp
+See
+.Lk http://www.tsu.ru/~pascal/en/xkb/gram-common.html "Common notes about XKB configuration files language"
+for more precise explanation of
+syntax of xkb configuration files.
+.Ss Predefined XKB Symbol Sets
+If you are about to define some European symbol map extension, you might
+want to use on of four predefined latin alphabet layouts.
+.Pp
+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
+.Pa pc/gb ) :
+.Bd -literal
+partial default alphanumeric_keys
+xkb_symbols "basic" {
+  include "pc/latin"
+  name[Group1]="Great Britain";
+  key \[u003C]AE02\[u003E]   { [         2,   quotedbl,  twosuperior,    oneeighth ] };
+  key \[u003C]AE03\[u003E]   { [         3,   sterling, threesuperior,    sterling ] };
+  key \[u003C]AC11\[u003E]   { [apostrophe,         at, dead_circumflex, dead_caron] };
+  key \[u003C]TLDE\[u003E]   { [     grave,    notsign,          bar,          bar ] };
+  key \[u003C]BKSL\[u003E]   { [numbersign, asciitilde,   dead_grave,   dead_breve ] };
+  key \[u003C]RALT\[u003E]   { type[Group1]="TWO_LEVEL",
+                [ ISO_Level3_Shift, Multi_key ]   };
+  modifier_map Mod5   { \[u003C]RALT\[u003E]  };
+};
+.Ed
+.Pp
+It defines a new layout in
+.Ql basic
+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
+<AE02>, <AE03>,
+<AC11>, <TLDE> and
+<BKSL> keys but it differs from number of shift
+levels of <RALT>.
+.Pp
+Note that the <RALT> 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.
+.Pp
+Okay, you could now define more variants of your new layout besides
+.Ql basic
+simply by including (augmenting/overriding/...)
+the basic
+definition and altering what may be needed.
+.Ss Key Types
+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
+.Pa pc/latin
+file to
+.Dq Li FOUR_LEVEL_ALPHABETIC .
+The only exception is
+<RALT> keycode which is explicitly set
+.Dq Li TWO_LEVEL
+keytype.
+.Pp
+All those names refer to pre-defined shift level schemes.
+Usually you can
+choose a suitable shift level scheme from
+.Ql default
+types scheme list
+in proper xkb component's subdirectory.
+.Pp
+The most used schemes are:
+.Bl -tag -width Ds
+.It ONE_LEVEL
+The key does not depend on any modifiers.
+The symbol from first level
+is always chosen.
+.It TWO_LEVEL
+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).
+.It ALPHABETIC
+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
+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.
+.It THREE_LEVEL
+Is the same as TWO_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
+level is also taken.
+As in TWO_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.
+.It FOUR_LEVEL
+Is the same as THREE_LEVEL but unlike LEVEL_THREE if both Shift+LevelThree
+modifiers apply the symbol is taken from the fourth level.
+.It FOUR_LEVEL_ALPHABETIC
+Is similar to FOUR_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.
+.It KEYPAD
+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.
+.It FOUR_LEVEL_KEYPAD
+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.
+.El
+.Pp
+Besides that, there are several schemes for special purposes:
+.Bl -tag -width Ds
+.It PC_BREAK
+It is similar to TWO_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.
+.It PC_SYSRQ
+It is similar to TWO_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.
+.It CTRL+ALT
+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.
+.It SHIFT+ALT
+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.
+.El
+.Pp
+If needed, special
+.Ql caps
+schemes may be used.
+They redefine the standard behaviour of all
+.Ql *ALPHABETIC
+types.
+The layouts (maps of
+symbols) with keys defined in respective types then automatically change
+their behaviour accordingly.
+Possible redefinitions are:
+.Bl -bullet
+.It
+internal
+.It
+internal_nocancel
+.It
+shift
+.It
+shift_nocancel
+.El
+.Pp
+None of these schemes should be used directly.
+They are defined merely
+for
+.Ql 'caps:'
+xkb options (used to globally
+change the layouts behaviour).
+.Pp
+Don't alter any of existing key types.
+If you need a different behaviour
+create a new one.
+.Pp
+.Sy More \&On Definitions \&Of Types
+.Pp
+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
+.Ql 'modifiers=<list of modifiers>'
+list and expects that a set
+of
+.Ql 'map[<combination of modifiers>]=<list of modifiers>'
+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).
+.Pp
+Lets consider an example with two modifiers
+.Sy ModOne
+and
+.Sy ModTwo :
+.Bd -literal
+type "..." {
+    modifiers = ModOne+ModTwo;
+    map[None] = Level1;
+    map[ModOne] = Level2;
+};
+.Ed
+.Pp
+In this case the map statements for
+.Sy ModTwo
+only and
+.Sy ModOne+ModTwo
+are omitted.
+It means that if
+the
+.Sy ModTwo
+is active the subroutine can't found
+explicit mapping for such combination an will use
+the
+.Em default level
+i.e. Level1.
+.Pp
+But in the case the type described as:
+.Bd -literal
+type "..." {
+    modifiers = ModOne;
+    map[None] = Level1;
+    map[ModOne] = Level2;
+};
+.Ed
+.Pp
+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.
+.Pp
+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)
+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 the first modifier - and this can be the symbol from the
+first as well as from the second level.
+.Pp
+Usually, all modifiers introduced in
+.Ql 'modifiers=<list of modifiers>'
+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
+.Pf ' Ql preserve[<combination of modifiers>]=<list of modifiers>' .
+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.
+.Pp
+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:
+.Bd -literal
+virtual_modifiers <comma-separated list of modifiers>   ;
+.Ed
+.Pp
+as seen in for example
+.Ql basic ,
+.Ql pc
+or
+.Ql mousekeys
+key
+type definitions.
+.Ss Rules
+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.
+.Pp
+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.
+.Pp
+A pattern in a rules file (often located in
+.Pa /usr/lib/X11/xkb/rules )
+can be parameterized with four other arguments:
+.Ql Model ,
+.Ql Layout ,
+.Ql Variant
+and
+.Ql Options .
+For most cases parameters
+.Ql model
+and
+.Ql layout
+should
+be sufficient for choosing a functional keyboard mapping.
+.Pp
+The rules file itself is composed of pattern lines and lines with rules.
+The
+pattern line starts with an exclamation mark
+.Pf (' Ql ! Ns ')
+and describes how will the xkb interpret the following lines (rules). A sample
+rules file looks like this:
+.Bd -literal
+! model 	                =	keycodes
+  macintosh_old	                =	macintosh
+  ...
+  *		                =	xorg
+! model		                =	symbols
+  hp		                =	+inet(%m)
+  microsoftpro	                =	+inet(%m)
+  geniuscomfy	                =	+inet(%m)
+! model	    layout[1]	        =	symbols
+  macintosh	us	        =	macintosh/us%(v[1])
+  *             *               =       pc/pc(%m)+pc/%l[1]%(v[1])
+! model     layout[2]	        =	symbols
+  macintosh     us              =	+macintosh/us[2]%(v[2]):2
+  *		*               =	+pc/%l[2]%(v[2]):2
+! option			=	types
+  caps:internal			=	+caps(internal)
+  caps:internal_nocancel	=	+caps(internal_nocancel)
+.Ed
+.Pp
+Each rule defines what certain combination of values on the left side
+of equal sign
+.Pf (' Ql = Ns ')
+results in.
+For
+example a (keyboard) model
+.Ql macintosh_old
+instructs xkb to take definitions of keycodes from
+file
+.Pa keycodes/macintosh
+while the rest
+of models (represented by a wild card
+.Pf ' Ql * Ns ')
+instructs it to take them from file
+.Pa keycodes/xorg .
+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.
+.Pp
+As you can see some lines contain substitution parameters - the parameters
+preceded by the percent sign
+.Pf (' Ql % Ns ').
+The first alphabetical character after the percent sign expands to the
+value which has been found on the left side.
+For
+example
+.Ql +%l%(v)
+expands
+into
+.Ql +cz(bksl)
+if the respective values
+on the left side were
+.Ql cz
+layout in
+its
+.Ql bksl
+variant.
+More, if the layout
+resp.
+variant parameter is followed by a pair of brackets
+.Pf (' Ql [ Ns ',
+.Pf ' Ql ] Ns ')
+it means that xkb should
+.Em place the layout resp. variant into specified xkb group .
+If the brackets are omitted the first
+group is the default value.
+.Pp
+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
+.Ql us
+layout of
+.Ql macintosh
+keyboard and standard pc
+symbols in appropriate variants as a default.
+.Ss Descriptive Files of Rules
+Now you just need to add a detailed description to
+.Pa <rules>.xml
+description file so the other users (and external programs which often parse
+this file) know what is your work about.
+.Pp
+.Sy Old Descriptive Files
+.Pp
+The formerly used descriptive files were named
+.Pa <rules>.lst
+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'.
+.Pp
+For each parameter of rules file should be described its meaning.
+For the rules
+file described above the
+.Pa .lst
+file could look like:
+.Bd -literal
+! model
+  pc104		Generic 104-key PC
+  microsoft	Microsoft Natural
+  pc98		PC-98xx Series
+  macintosh     Original Macintosh
+  ...
+! layout
+  us		U.S. English
+  cz		Czech
+  de		German
+  ...
+! option
+  caps:internal		 uses internal capitalization. Shift cancels Caps
+  caps:internal_nocancel uses internal capitalization. Shift doesn't cancel Caps
+.Ed
+.Pp
+And that should be it.
+Enjoy creating your own xkb mapping.
+.Sh AUTHORS
+.An -nosplit
+X Version 11, Release 6
+.An -split
+.An Kamil Toman
+.An Ivan U. Pascal
diff --git a/doc/xorg-docs/general/input/defs.ent b/doc/xorg-docs/general/input/defs.ent
new file mode 100644
index 000000000..30b1911cd
--- /dev/null
+++ b/doc/xorg-docs/general/input/defs.ent
@@ -0,0 +1 @@
+<!ENTITY fullrelvers "6">