SecBSD/xenocara
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

sync code with last improvements from OpenBSD

Browse source
This commit is contained in:
purplerain 2023-08-28 05:57:34 +00:00
commit 88965415ff
Signed by: purplerain
GPG key ID: F42C07F07E2E35B7
26235 changed files with 29195616 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

22
dist/xkeyboard-config/docs/HOWTO.testing vendored Normal file
View file

@ -0,0 +1,22 @@
A mini-HOWTO test the XKB config without modifying the system configuration.
(Only tested with XFree86 4.3+.)
First see what your configuration is. Note the model and layout.
$ setxkbmap -print
Then unpack the sources locally ...
$ gzip -dc xkeyboard-config*.tar.gz | tar -tf -
... and change to the delivered directory
$ cd xkeyboard-config-<version>
Then try to load the current keyboard using the local rules
$ setxkbmap -v 10 -I$PWD -rules base
Now try to set different keyboards using the -model and -layout.
$ setxkbmap -v 10 -I$PWD -rules base -model pc102 -layout intl
Look in the file rules/base for other example models and layouts
If there was a problem, you can reset the keyboard like so:
$ setxkbmap -rules xfree86 -model <noted model> -layout <noted layout>
If that doesn't work, you may have to log out and log back in.

19
dist/xkeyboard-config/docs/HOWTO.transition vendored Normal file
View file

@ -0,0 +1,19 @@
PURPOSE
This document describes the procedure for replacing the standard XKB configuration repository shipped with an X Window System implementation. The procedure should work for XFree86 4.3 and higher and X11R7 implementation from X.Org. Any other X server supporting so called "multiple layouts" can be powered with XKeyboardConfig in a similar way (at the moment NO known commercial X Window System implementations support "multiple layouts"). X servers which do not support "multiple layouts" can be used with XKeyboardConfig as well - but users should be aware that only one group will be accessible with each possible XKB configuration.
PROCEDURE
1. Find your current XKB configuration data directory. In most cases it is /usr/X11R6/lib/X11/xkb. This directory usually contain subdirectores: compat, compiled, geometry, keycodes, keymap, rules, semantics, symbols etc.
2. Backup your current XKB configuration data directory (for example, rename it to xkb.orig) - so you would be able to restore your original configuration in case of troubles.
3. Untar XKeyboardConfiguration tarball (tar -xzvf xkeyboard-config-0.2.tar.gz). Change to the root project directory. Run the configure script with appropriate options. There are several useful options:
--with-xkb-rules-symlink=NAME - this option creates symlinks for the rules and registry files. The default file names are base and base.xml correspondingly. Using this option allows to create symlinks for configuration files compatibility (for example, --with-xkb-rules-symlink=xfree86 creates symlinks xfree86 and xfree86.xml - so users would be able to use rules set "xfree86").
--enable-xkbcomp-symlink - creates symlink from original xkbcomp utility (usually found in /usr/X111R6/bin) to XKB configuration directory (usually it is required by XKB server). By default, this option is enabled - but user can disable it.
4. Run "make" and (as root) "make install". At that point, new /usr/X11R6/lib/X11/xkb should be created.
5. Adjust the configuration files (XF86Config, xorg.conf etc.). If you don't use the symlinks, you should use the rules set "base" (as the "XkbRules" value). If you added --with-xkb-rules-symlink option, you can use either "base" or the name of the rules symlink you created (for example, "xfree86").

1
dist/xkeyboard-config/docs/Makefile.am vendored Normal file
View file

@ -0,0 +1 @@
EXTRA_DIST= README.config README.enhancing README.symbols HOWTO.transition HOWTO.testing

458
dist/xkeyboard-config/docs/Makefile.in vendored Normal file
View file

@ -0,0 +1,458 @@
# Makefile.in generated by automake 1.15 from Makefile.am.
# @configure_input@
# Copyright (C) 1994-2014 Free Software Foundation, Inc.
# This Makefile.in is free software; the Free Software Foundation
# gives unlimited permission to copy and/or distribute it,
# with or without modifications, as long as this notice is preserved.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
# PARTICULAR PURPOSE.
@SET_MAKE@
VPATH = @srcdir@
am__is_gnu_make = { \
if test -z '$(MAKELEVEL)'; then \
false; \
elif test -n '$(MAKE_HOST)'; then \
true; \
elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \
true; \
else \
false; \
fi; \
}
am__make_running_with_option = \
case $${target_option-} in \
?) ;; \
*) echo "am__make_running_with_option: internal error: invalid" \
"target option '$${target_option-}' specified" >&2; \
exit 1;; \
esac; \
has_opt=no; \
sane_makeflags=$$MAKEFLAGS; \
if $(am__is_gnu_make); then \
sane_makeflags=$$MFLAGS; \
else \
case $$MAKEFLAGS in \
*\\[\ \ ]*) \
bs=\\; \
sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \
| sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \
esac; \
fi; \
skip_next=no; \
strip_trailopt () \
{ \
flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \
}; \
for flg in $$sane_makeflags; do \
test $$skip_next = yes && { skip_next=no; continue; }; \
case $$flg in \
*=*|--*) continue;; \
-*I) strip_trailopt 'I'; skip_next=yes;; \
-*I?*) strip_trailopt 'I';; \
-*O) strip_trailopt 'O'; skip_next=yes;; \
-*O?*) strip_trailopt 'O';; \
-*l) strip_trailopt 'l'; skip_next=yes;; \
-*l?*) strip_trailopt 'l';; \
-[dEDm]) skip_next=yes;; \
-[JT]) skip_next=yes;; \
esac; \
case $$flg in \
*$$target_option*) has_opt=yes; break;; \
esac; \
done; \
test $$has_opt = yes
am__make_dryrun = (target_option=n; $(am__make_running_with_option))
am__make_keepgoing = (target_option=k; $(am__make_running_with_option))
pkgdatadir = $(datadir)/@PACKAGE@
pkgincludedir = $(includedir)/@PACKAGE@
pkglibdir = $(libdir)/@PACKAGE@
pkglibexecdir = $(libexecdir)/@PACKAGE@
am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
install_sh_DATA = $(install_sh) -c -m 644
install_sh_PROGRAM = $(install_sh) -c
install_sh_SCRIPT = $(install_sh) -c
INSTALL_HEADER = $(INSTALL_DATA)
transform = $(program_transform_name)
NORMAL_INSTALL = :
PRE_INSTALL = :
POST_INSTALL = :
NORMAL_UNINSTALL = :
PRE_UNINSTALL = :
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
subdir = docs
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/m4/gettext.m4 \
$(top_srcdir)/m4/iconv.m4 $(top_srcdir)/m4/intlmacosx.m4 \
$(top_srcdir)/m4/lib-ld.m4 $(top_srcdir)/m4/lib-link.m4 \
$(top_srcdir)/m4/lib-prefix.m4 $(top_srcdir)/m4/nls.m4 \
$(top_srcdir)/m4/po.m4 $(top_srcdir)/m4/progtest.m4 \
$(top_srcdir)/configure.ac
am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
$(ACLOCAL_M4)
DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON)
mkinstalldirs = $(install_sh) -d
CONFIG_CLEAN_FILES =
CONFIG_CLEAN_VPATH_FILES =
AM_V_P = $(am__v_P_@AM_V@)
am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
am__v_P_0 = false
am__v_P_1 = :
AM_V_GEN = $(am__v_GEN_@AM_V@)
am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@)
am__v_GEN_0 = @echo " GEN " $@;
am__v_GEN_1 =
AM_V_at = $(am__v_at_@AM_V@)
am__v_at_ = $(am__v_at_@AM_DEFAULT_V@)
am__v_at_0 = @
am__v_at_1 =
SOURCES =
DIST_SOURCES =
am__can_run_installinfo = \
case $$AM_UPDATE_INFO_DIR in \
n|no|NO) false;; \
*) (install-info --version) >/dev/null 2>&1;; \
esac
am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
am__DIST_COMMON = $(srcdir)/Makefile.in
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
ACLOCAL = @ACLOCAL@
ADMIN_MAN_DIR = @ADMIN_MAN_DIR@
ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@
ALL_LINGUAS = @ALL_LINGUAS@
AMTAR = @AMTAR@
AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
APP_MAN_DIR = @APP_MAN_DIR@
APP_MAN_SUFFIX = @APP_MAN_SUFFIX@
AUTOCONF = @AUTOCONF@
AUTOHEADER = @AUTOHEADER@
AUTOMAKE = @AUTOMAKE@
AWK = @AWK@
CC = @CC@
CCDEPMODE = @CCDEPMODE@
CFLAGS = @CFLAGS@
CPPFLAGS = @CPPFLAGS@
CYGPATH_W = @CYGPATH_W@
DEFS = @DEFS@
DEPDIR = @DEPDIR@
DEPS_CFLAGS = @DEPS_CFLAGS@
DEPS_LIBS = @DEPS_LIBS@
DRIVER_MAN_DIR = @DRIVER_MAN_DIR@
DRIVER_MAN_SUFFIX = @DRIVER_MAN_SUFFIX@
ECHO_C = @ECHO_C@
ECHO_N = @ECHO_N@
ECHO_T = @ECHO_T@
EXEEXT = @EXEEXT@
FILE_MAN_DIR = @FILE_MAN_DIR@
FILE_MAN_SUFFIX = @FILE_MAN_SUFFIX@
GETTEXT_MACRO_VERSION = @GETTEXT_MACRO_VERSION@
GETTEXT_PACKAGE = @GETTEXT_PACKAGE@
GMSGFMT = @GMSGFMT@
GMSGFMT_015 = @GMSGFMT_015@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_SCRIPT = @INSTALL_SCRIPT@
INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
INTLLIBS = @INTLLIBS@
INTLTOOL_EXTRACT = @INTLTOOL_EXTRACT@
INTLTOOL_MERGE = @INTLTOOL_MERGE@
INTLTOOL_PERL = @INTLTOOL_PERL@
INTLTOOL_UPDATE = @INTLTOOL_UPDATE@
INTLTOOL_V_MERGE = @INTLTOOL_V_MERGE@
INTLTOOL_V_MERGE_OPTIONS = @INTLTOOL_V_MERGE_OPTIONS@
INTLTOOL__v_MERGE_ = @INTLTOOL__v_MERGE_@
INTLTOOL__v_MERGE_0 = @INTLTOOL__v_MERGE_0@
INTL_MACOSX_LIBS = @INTL_MACOSX_LIBS@
LDFLAGS = @LDFLAGS@
LIBICONV = @LIBICONV@
LIBINTL = @LIBINTL@
LIBOBJS = @LIBOBJS@
LIBS = @LIBS@
LIB_MAN_DIR = @LIB_MAN_DIR@
LIB_MAN_SUFFIX = @LIB_MAN_SUFFIX@
LTLIBICONV = @LTLIBICONV@
LTLIBINTL = @LTLIBINTL@
LTLIBOBJS = @LTLIBOBJS@
MAKEINFO = @MAKEINFO@
MAN_SUBSTS = @MAN_SUBSTS@
MISC_MAN_DIR = @MISC_MAN_DIR@
MISC_MAN_SUFFIX = @MISC_MAN_SUFFIX@
MKDIR_P = @MKDIR_P@
MSGFMT = @MSGFMT@
MSGFMT_015 = @MSGFMT_015@
MSGMERGE = @MSGMERGE@
OBJEXT = @OBJEXT@
PACKAGE = @PACKAGE@
PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
PACKAGE_NAME = @PACKAGE_NAME@
PACKAGE_STRING = @PACKAGE_STRING@
PACKAGE_TARNAME = @PACKAGE_TARNAME@
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
PKG_CONFIG = @PKG_CONFIG@
PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@
PKG_CONFIG_PATH = @PKG_CONFIG_PATH@
POSUB = @POSUB@
SED = @SED@
SET_MAKE = @SET_MAKE@
SHELL = @SHELL@
STRIP = @STRIP@
USE_NLS = @USE_NLS@
VERSION = @VERSION@
XGETTEXT = @XGETTEXT@
XGETTEXT_015 = @XGETTEXT_015@
XGETTEXT_EXTRA_OPTIONS = @XGETTEXT_EXTRA_OPTIONS@
XORG_MAN_PAGE = @XORG_MAN_PAGE@
XSLTPROC = @XSLTPROC@
abs_builddir = @abs_builddir@
abs_srcdir = @abs_srcdir@
abs_top_builddir = @abs_top_builddir@
abs_top_srcdir = @abs_top_srcdir@
ac_ct_CC = @ac_ct_CC@
am__include = @am__include@
am__leading_dot = @am__leading_dot@
am__quote = @am__quote@
am__tar = @am__tar@
am__untar = @am__untar@
bindir = @bindir@
build = @build@
build_alias = @build_alias@
build_cpu = @build_cpu@
build_os = @build_os@
build_vendor = @build_vendor@
builddir = @builddir@
datadir = @datadir@
datarootdir = @datarootdir@
docdir = @docdir@
dvidir = @dvidir@
exec_prefix = @exec_prefix@
host = @host@
host_alias = @host_alias@
host_cpu = @host_cpu@
host_os = @host_os@
host_vendor = @host_vendor@
htmldir = @htmldir@
includedir = @includedir@
infodir = @infodir@
install_sh = @install_sh@
intltool__v_merge_options_ = @intltool__v_merge_options_@
intltool__v_merge_options_0 = @intltool__v_merge_options_0@
libdir = @libdir@
libexecdir = @libexecdir@
localedir = @localedir@
localstatedir = @localstatedir@
mandir = @mandir@
mkdir_p = @mkdir_p@
oldincludedir = @oldincludedir@
pdfdir = @pdfdir@
prefix = @prefix@
program_transform_name = @program_transform_name@
psdir = @psdir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
sysconfdir = @sysconfdir@
target_alias = @target_alias@
top_build_prefix = @top_build_prefix@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
xkb_base = @xkb_base@
xkb_rules_symlink = @xkb_rules_symlink@
EXTRA_DIST = README.config README.enhancing README.symbols HOWTO.transition HOWTO.testing
all: all-am
.SUFFIXES:
$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps)
@for dep in $?; do \
case '$(am__configure_deps)' in \
*$$dep*) \
( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
&& { if test -f $@; then exit 0; else break; fi; }; \
exit 1;; \
esac; \
done; \
echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign docs/Makefile'; \
$(am__cd) $(top_srcdir) && \
$(AUTOMAKE) --foreign docs/Makefile
Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
@case '$?' in \
*config.status*) \
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
*) \
echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
esac;
$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(top_srcdir)/configure: $(am__configure_deps)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(ACLOCAL_M4): $(am__aclocal_m4_deps)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(am__aclocal_m4_deps):
tags TAGS:
ctags CTAGS:
cscope cscopelist:
distdir: $(DISTFILES)
@srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
list='$(DISTFILES)'; \
dist_files=`for file in $$list; do echo $$file; done | \
sed -e "s|^$$srcdirstrip/||;t" \
-e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
case $$dist_files in \
*/*) $(MKDIR_P) `echo "$$dist_files" | \
sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
sort -u` ;; \
esac; \
for file in $$dist_files; do \
if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
if test -d $$d/$$file; then \
dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
if test -d "$(distdir)/$$file"; then \
find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
fi; \
if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
fi; \
cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
else \
test -f "$(distdir)/$$file" \
|| cp -p $$d/$$file "$(distdir)/$$file" \
|| exit 1; \
fi; \
done
check-am: all-am
check: check-am
all-am: Makefile
installdirs:
install: install-am
install-exec: install-exec-am
install-data: install-data-am
uninstall: uninstall-am
install-am: all-am
@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
installcheck: installcheck-am
install-strip:
if test -z '$(STRIP)'; then \
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
install; \
else \
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
"INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
fi
mostlyclean-generic:
clean-generic:
distclean-generic:
-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
-test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
maintainer-clean-generic:
@echo "This command is intended for maintainers to use"
@echo "it deletes files that may require special tools to rebuild."
clean: clean-am
clean-am: clean-generic mostlyclean-am
distclean: distclean-am
-rm -f Makefile
distclean-am: clean-am distclean-generic
dvi: dvi-am
dvi-am:
html: html-am
html-am:
info: info-am
info-am:
install-data-am:
install-dvi: install-dvi-am
install-dvi-am:
install-exec-am:
install-html: install-html-am
install-html-am:
install-info: install-info-am
install-info-am:
install-man:
install-pdf: install-pdf-am
install-pdf-am:
install-ps: install-ps-am
install-ps-am:
installcheck-am:
maintainer-clean: maintainer-clean-am
-rm -f Makefile
maintainer-clean-am: distclean-am maintainer-clean-generic
mostlyclean: mostlyclean-am
mostlyclean-am: mostlyclean-generic
pdf: pdf-am
pdf-am:
ps: ps-am
ps-am:
uninstall-am:
.MAKE: install-am install-strip
.PHONY: all all-am check check-am clean clean-generic cscopelist-am \
ctags-am distclean distclean-generic distdir dvi dvi-am html \
html-am info info-am install install-am install-data \
install-data-am install-dvi install-dvi-am install-exec \
install-exec-am install-html install-html-am install-info \
install-info-am install-man install-pdf install-pdf-am \
install-ps install-ps-am install-strip installcheck \
installcheck-am installdirs maintainer-clean \
maintainer-clean-generic mostlyclean mostlyclean-generic pdf \
pdf-am ps ps-am tags-am uninstall uninstall-am
.PRECIOUS: Makefile
# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:

195
dist/xkeyboard-config/docs/README.config vendored Normal file
View file

@ -0,0 +1,195 @@
The XKB Configuration Guide
Kamil Toman, Ivan U. Pascal
25 November 2002
Abstract
This document describes how to configure XFree86 XKB from a user's
point a few. It converts basic configuration syntax and gives also
a few examples.
1. Overview
The XKB configuration is decomposed into a number of components. Selecting
proper parts and combining them back you can achieve most of configurations
you might need. Unless you have a completely atypical keyboard you really
don't need to touch any of xkb configuration files.
2. Selecting XKB Configuration
The easiest and the most natural way how to specify a keyboard mapping is to
use rules component. As its name suggests it describes a number of general
rules how 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 ful-
fill your needs.
The parameters are:
o XkbRules - files of rules to be used for keyboard mapping composition
o XkbModel - name of model of your keyboard type
o XkbLayout - layout(s) you intend to use
o XkbVariant - variant(s) of layout you intend to use
o XkbOptions - extra xkb configuration options
The proper rules file depends on your vendor. In reality, the commonest file
of rules is xfree86. For each rules file there is a description file named
<vendor-rules>.lst, for instance xfree86.lst which is located in xkb configu-
ration subdirectory rules (for example /etc/X11/xkb/rules).
2.1 Basic Configuration
Let's say you want to configure a PC style America keyboard with 104 keys as
described in xfree86.lst. It can be done by simply writing several lines from
below to you XFree86 configuration file (often found as /etc/X11/XF86Config-4
or /etc/X11/XF86Config):
Section "InputDevice"
Identifier "Keyboard1"
Driver "Keyboard"
Option "XkbModel" "pc104"
Option "XkbLayout" "us"
Option "XKbOptions" ""
EndSection
The values of parameters XkbModel and XkbLayout are really not surprising.
The parameters XkbOptions has been explicitly set to empty set of parameters.
The parameter XkbVariant has been left out. That means the default variant
named basic is loaded.
Of course, this can be also done at runtime using utility setxkbmap. Shell
command loading the same keyboard mapping would look like:
setxkbmap -rules xfree86 -model pc104 -layout us -option ""
The configuration and the shell command would be very analogical for most
other layouts (internationalized mappings).
2.2 Advanced Configuration
Since XFree86 4.3.x 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.
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 Alt-Shift combination for
switching among them.
Then the configuration snippet could look like this:
Section "InputDevice"
Identifier "Keyboard1"
Driver "Keyboard"
Option "XkbModel" "logicordless"
Option "XkbLayout" "us,cz,de"
Option "XKbOptions" "grp:alt_shift_toggle"
EndSection
Of course, this can be also done at runtime using utility setxkbmap. Shell
command loading the same keyboard mapping would look like:
setxkbmap -rules xfree86 -model logicordless -layout "us,cz,de" \
-option "grp:alt_shift_toggle"
2.3 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:
Section "InputDevice"
Identifier "Keyboard1"
Driver "Keyboard"
Option "XkbModel" "logicordless"
Option "XkbLayout" "us,cz,de"
Option "XkbVariant" ",bksl,"
Option "XKbOptions" "grp:alt_shift_toggle"
EndSection
That's 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 basic), the second is set to bksl (a special variant with an
enhanced definition of the backslash key).
Analogically, the loading runtime will change to:
setxkmap -rules xfree86 -model logicordless -layout "us,cz,de" \
-variant ",bksl," -option "grp:alt_shift_toggle"
2.4 Basic Global Options
See rules/*.lst files.
3. Direct XKB Configuration
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.
This method also exposes all xkb configuration details directly into XFree86
configuration file which is a not very fortunate fact. In rare occasions it
may be needed, though. So how does it work?
3.1 Basic Components
There are five basic components used to form a keyboard mapping:
o key codes - a translation of the scan codes produced by the keyboard
into a suitable symbolic form
o types - a specification of what various combinations of modifiers pro-
duce
o key symbols - a translation of symbolic key codes into actual symbols
o geometry - a description of physical keyboard geometry
o compatibility maps - a specification of what action should each key pro-
duce in order to preserve compatibility with XKB-unware clients
3.2 Example Configuration
Look at the following example:
Section "InputDevice"
Identifier "Keyboard0"
Driver "Keyboard"
Option "XkbKeycodes" "xfree86"
Option "XkbTypes" "default"
Option "XkbSymbols" "en_US(pc104)+de+swapcaps"
Option "XkbGeometry" "pc(pc104)"
Option "XkbCompat" "basic+pc+iso9995"
EndSection
This configuration sets the standard XFree86 default interpretation of key-
board keycodes, sets the default modificator types. The symbol table is com-
posed 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 Caps-lock and Control keys is swapped. The standard key-
board 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.
4. Keymap XKB Configuration
It is the formerly used way 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 flexi-
ble and allow simpler and more intuitive syntax. It is preserved merely for
compatibility reasons. Avoid using it if it is possible.
Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/XKB-Config.sgml,v 1.4 dawes Exp $

520
dist/xkeyboard-config/docs/README.enhancing vendored Normal file
View file

@ -0,0 +1,520 @@
How to further enhance XKB configuration
Kamil Toman, Ivan U. Pascal
25 November 2002
Abstract
This guide is aimed to relieve one's labour to create a new (inter-
nationalized) keyboard layout. Unlike other documents this guide
accents the keymap developer's point of view.
1. Overview
The developer of a new layout should read the xkb protocol specification (The
X Keyboard Extension: Protocol Specification
<URL:http://xfree86.org/current/XKBproto.pdf>) 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).
A useful source is also Ivan Pascal's text about xkb configuration
<URL:http://pascal.tsu.ru/en/xkb/> often referenced throughout this docu-
ment.
Note that this document covers only enhancements which are to be made to
XFree86 version 4.3.x and above.
2. The Basics
At the startup (or at later at user's command) X server starts its xkb key-
board module extension and reads data from a compiled configuration file.
This compiled configuration file is prepared by the program xkbcomp which
behaves altogether as an ordinary compiler (see 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 xkbcomp them-
selves, for them it is invisible. Usually, it is started upon X server
startup.
As you probably already know, the xkb configuration consists of five main
modules:
Keycodes
Tables that defines translation from keyboard scan codes into
reasonable symbolic names, maximum, minimum legal keycodes, sym-
bolic aliases and description of physically present LED-indica-
tors. The primary sence of this component is to allow definitions
of maps of symbols (see below) to be independent of physical key-
board scancodes. There are two main naming conventions for sym-
bolic names (always four bytes long):
o names which express some traditional meaning like <SPCE>
(stands for space bar) or
o names which express some relative positioning on a key-
board, for example <AE01> (an exclamation mark on US key-
boards), on the right there are keys <AE02>, <AE03> etc.
Types
Types describe how the produced key is changed by active modi-
fiers (like Shift, Control, Alt, ...). There are several prede-
fined types which cover most of used combinations.
Compat
Compatibility component defines internal behaviour of modifiers.
Using compat component you can assign various actions (elabo-
rately described in xkb specification) to key events. This is
also the place where LED-indicators behaviour is defined.
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.
Geometry
Geometry files aren't used by xkb itself but they may be used by
some external programs to depict a keyboard image.
All these components have the files located in xkb configuration tree in sub-
directories with the same names (usually in /usr/lib/X11/xkb).
3. 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).
What do you need to do? Generally, you have to define following things:
o the map of symbols itself
o the rules to allow users to select the new mapping
o the description of the new layout
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.
3.1 Levels And Groups
Since XFree86 4.3.0 you can use 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.
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 inter-
pretation is processed by Xlib, Xaw, Motif, Qt, Gtk and similar libraries.
The X server only supplies its mapping table (usually upon an application
startup).
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 modi-
fiers so it its row has only one column defined.
Note that in XKB there is no prior assumption that certain modifiers are
bound to certain columns. By editing proper files (see keytypes (section 4.2,
page 1)) this mapping can be changed as well.
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 ta-
ble. 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.
To sum it up:
o for each keycode XKB keyboard map contains up to four one-dimensional
tables - groups (logically different symbol sets)
o for each group of a keycode XKB keyboard map contains some columns -
shift levels (values reached by combinations of Shift, Ctrl, Alt, ...
modifiers)
o different keycodes can have different number of groups
o different groups of one keycode can have different number of shift lev-
els
o the current group number is tracked by X server
It is clear that if you sanely define levels, groups and sanely bind modi-
fiers and associated actions you can have simultaneously loaded up to four
different symbol sets where each of them would reside in its own group.
The multi-layout concept provides a facility to manipulate xkb groups and
symbol definitions in a way that allows almost arbitrary composition of pre-
defined symbol tables. To keep it fully functional you have to:
o define all symbols only in the first group
o (re)define any modifiers with extra care to avoid strange (anisometric)
behaviour
4. Defining New Layouts
See Some Words About XKB internals
<URL:http://pascal.tsu.ru/en/xkb/internals.html> for explanation of used xkb
terms and problems addressed by XKB extension.
See Common notes about XKB configuration files language
<URL:http://pascal.tsu.ru/en/xkb/gram-common.html> for more precise
explanation of syntax of xkb configuration files.
4.1 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.
Okay, let's assume you want extend an existing keymap and you want to over-
ride a few keys. Let's take a simple U.K. keyboard as an example (defined in
pc/gb):
partial default alphanumeric_keys
xkb_symbols "basic" {
include "pc/latin"
name[Group1]="Great Britain";
key <AE02> { [ 2, quotedbl, twosuperior, oneeighth ] };
key <AE03> { [ 3, sterling, threesuperior, sterling ] };
key <AC11> { [apostrophe, at, dead_circumflex, dead_caron] };
key <TLDE> { [ grave, notsign, bar, bar ] };
key <BKSL> { [numbersign, asciitilde, dead_grave, dead_breve ] };
key <RALT> { type[Group1]="TWO_LEVEL",
[ ISO_Level3_Shift, Multi_key ] };
modifier_map Mod5 { <RALT> };
};
It defines a new layout in 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>.
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.
Okay, you could now define more variants of your new layout besides basic
simply by including (augmenting/overriding/...) the basic definition and
altering what may be needed.
4.2 Key Types
The differences in the number of columns (shift levels) are caused by a dif-
ferent types of keys (see the types definition in section basics). Most key-
codes have implicitly set the keytype in the included "pc/latin" file to
"FOUR_LEVEL_ALPHABETIC". The only exception is <RALT> keycode which is
explicitly set "TWO_LEVEL" keytype.
All those names refer to pre-defined shift level schemes. Usually you can
choose a suitable shift level scheme from default types scheme list in proper
xkb component's subdirectory.
The most used schemes are:
ONE_LEVEL
The key does not depend on any modifiers. The symbol from first
level is always chosen.
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 modi-
fier (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 cap-
italization rules are applied (and usually have no effect).
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.
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 modi-
fier is active capitalization rules are applied on the resulting
symbol.
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.
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.
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.
FOUR_LEVEL_KEYPAD
Is similar to KEYPAD scheme but considers also LevelThree modi-
fier. 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+Num-
Lock+LevelThree modifiers apply the symbol from the third level
is taken. This also, shift-cancels-caps variant.
FOUR_LEVEL_MIXED_KEYPAD
A four-level keypad scheme where the first two levels are similar
to the KEYPAD scheme (NumLock+Shift)
LevelThree acts as an override providing access to two Shift-ed
levels. When LevelThree is active we totally ignore NumLock state
Intended for the digit area of the keypad
FOUR_LEVEL_X
A four-level scheme where the base level accepts no modifier,
LevelThree provides two more Shift-ed levels like in the previous
scheme, and Ctrl+Alt controls the fourth level
Intended for the operator part of a keypad, though since NumLock
plays no part, it is not keypad-specific
Besides that, there are several schemes for special purposes:
PC_CONTROL_LEVEL2
It is similar to TWO_LEVEL scheme but it considers the Control
modifier rather than Shift. That means, the symbol from the sec-
ond level is chosen by Control rather than by Shift.
PC_ALT_LEVEL2
It is similar to TWO_LEVEL scheme but it considers the Alt modi-
fier rather than Shift. That means, the symbol from the second
level is chosen by Alt rather than by Shift.
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 modi-
fiers apply the symbol from the second level is chosen.
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.
If needed, special caps schemes may be used. They redefine the standard
behaviour of all *ALPHABETIC types. The layouts (maps of symbols) with keys
defined in respective types then automatically change their behaviour accord-
ingly. Possible redefinitions are:
o internal
o internal_nocancel
o shift
o shift_nocancel
None of these schemes should be used directly. They are defined merely for
'caps:' xkb options (used to globally change the layouts behaviour).
Don't alter any of existing key types. If you need a different behaviour cre-
ate a new one.
4.2.1 More On Definitions Of Types
When the XKB software deals with a separate type description it gets a com-
plete list of modifiers that should be taken into account from the 'modi-
fiers=<list of modifiers>' list and expects that a set of '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).
Lets consider an example with two modifiers ModOne and ModTwo:
type "..." {
modifiers = ModOne+ModTwo;
map[None] = Level1;
map[ModOne] = Level2;
};
In this case the map statements for ModTwo only and ModOne+ModTwo are omit-
ted. It means that if the ModTwo is active the subroutine can't found
explicit mapping for such combination an will use the default level i.e.
Level1.
But in the case the type described as:
type "..." {
modifiers = ModOne;
map[None] = Level1;
map[ModOne] = Level2;
};
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.
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 combina-
tions 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 he first modifier - and this can be the symbol from the first
as well as from the second level.
Usually, all modifiers introduced in '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 'preserve[<combination of modi-
fiers>]=<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.
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:
virtual_modifiers <comma-separated list of modifiers> ;
as seen in for example basic, pc or mousekeys key type definitions.
4.3 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, sym-
bols and geometry components should be composed to give a sensible resulting
xkb configuration.
The main advantage of rules over formerly used keymaps is a possibility to
simply parameterize (once) fixed patterns of configurations and thus to ele-
gantly allow substitutions of various local configurations into predefined
templates.
A pattern in a rules file (often located in /usr/lib/X11/xkb/rules) can be
parameterized with four other arguments: Model, Layout, Variant and Options.
For most cases parameters model and layout should be sufficient for choosing
a functional keyboard mapping.
The rules file itself is composed of pattern lines and lines with rules. The
pattern line starts with an exclamation mark ('!') and describes how will the
xkb interpret the following lines (rules). A sample rules file looks like
this:
! model = keycodes
macintosh_old = macintosh
...
* = xfree86
! 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)
Each rule defines what certain combination of values on the left side of
equal sign ('=') results in. For example a (keyboard) model macintosh_old
instructs xkb to take definitions of keycodes from file keycodes/macintosh
while the rest of models (represented by a wild card '*') instructs it to
take them from file keycodes/xfree86. 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 gen-
eral ones, i.e. the more general rules supply reasonable default values.
As you can see some lines contain substitution parameters - the parameters
preceded by the percent sign ('%'). The first alphabetical character after
the percent sign expands to the value which has been found on the left side.
For example +%l%(v) expands into +cz(bksl) if the respective values on the
left side were cz layout in its bksl variant. More, if the layout resp. vari-
ant parameter is followed by a pair of brackets ('[', ']') it means that xkb
should place the layout resp. variant into specified xkb group. If the brack-
ets are omitted the first group is the default value.
So the second block of rules enhances symbol definitions for some particular
keyboard models with extra keys (for internet, multimedia, ...) . Other mod-
els are left intact. Similarly, the last block overrides some key type defi-
nitions, 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 us layout of macintosh keyboard and standard pc sym-
bols in appropriate variants as a default.
4.4 Descriptive Files of Rules
Now you just need to add a detailed description to <rules>.xml description
file so the other users (and external programs which often parse this file)
know what is your work about.
4.4.1 Old Descriptive Files
The formerly used descriptive files were named <rules>.lst Its structure is
very simple and quite self descriptive but such simplicity had also some cav-
ities, 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 con-
verted to old format '.lst'.
For each parameter of rules file should be described its meaning. For the
rules file described above the .lst file could look like:
! 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
And that should be it. Enjoy creating your own xkb mapping.

48
dist/xkeyboard-config/docs/README.symbols vendored Normal file
View file

@ -0,0 +1,48 @@
The files in the symbols directory describe possible keyboard layouts
for a given country or language or script.
The default layout in each file should describe the most common layout
for its kind, usually the one that matches the symbols printed on the
keys. Layout variants can describe common deviations that are not
necessarily printed on the keys (e.g. a phonetic version of Cyrillic).
The names of the files are referenced throughout the XKB rules, and may
be exposed in the X server configuration and in user configuration tools.
The filenames use the following convention:
Country layouts:
Keyboard layouts for a country must use the 2-letter code from the
ISO-3166 standard.
Language layouts:
Keyboard layouts for a language must use the 3-letter code from the
ISO-639 standard.
Script layouts:
Keyboard layouts for a script must use the 4-letter code from the
ISO-15924 standard.
Other:
Keyboard layouts that do not fit in the above categories must use a
filename between 5 and 8 characters.
The relevant ISO codes can be found at the following addresses:
Country layouts: http://www.iso.org/iso/home/standards/country_codes/iso-3166-1_decoding_table.htm
Language layouts: http://www.loc.gov/standards/iso639-2/php/code_list.php
Script layouts: http://www.unicode.org/iso15924/iso15924-codes.html
The descriptions of the layouts in the file base.xml.in should match the
group names in the symbols file.
If the layout is country-based, the group name has to be the full name of
the country. It is highly discouraged to use forms like "Republic of XXX"
or "XXX Republic" -- the form "XXX" should be used instead. The only
exception is "United Kingdom".
If the layout is language-based, the group name has to be the name of the
language.
Within a single symbols file, all the variants should have the same group name
(implemented using the "include" directive wherever possible).