xsconfig(X)

xsconfig -- X keyboard configuration compiler

Syntax

/usr/bin/X11/xsconfig [-o configfile] sourcefile [...]

Description

xsconfig compiles a keyboard configuration file for the Xsco server. If you do not specify an output configuration file with the -o option, xsconfig creates .Xsco.cfg in the current working directory.

On startup, the server reads the file /usr/lib/X11/.Xsco.cfg to set the initial configuration. If the file $HOME/.Xsco.cfg exists, the server reads it instead of /usr/lib/X11/.Xsco.cfg. The server also reads the configuration file if it is reset by a display manager such as scologin(XC). Key mappings may be changed after starting the server with the xmodmap utility.

Although xsconfig accepts multiple filenames as command line arguments, you usually need only change one or two files to achieve any desired keyboard modifications. Because xsconfig's command line can become unwieldy, and because it provides minimal syntax error detection, use the /usr/lib/X11/xsconfig/xsconfig.sh script instead of running xsconfig. xsconfig.sh uses X11 and system keyboard configuration files to create the server configuration file .Xsco.cfg.

The xsconfig.sh script uses the following command line syntax:

xsconfig.sh [-m] [[/usr/lib/X11/csxmaps/csxmap_file] /usr/lib/keyboard/keyboard_name]

xsconfig.sh must be run as root from the /usr/lib/X11/xsconfig directory. When the script exits, you must move the new configuration file, .Xsco.cfg, into /usr/lib/X11 or into a user's $HOME directory. The new configuration file will take effect the next time the server starts.

If you need to create a configuration file for non-US keyboards, you must supply the keyboard_name argument, and optionally the cxsmap_file argument.

If you do not want the <Alt_R> key to be the ``group modifier'' Mode_switch key, then use the -m option to xsconfig.sh. Setting the <Alt_R> key to the Mode_switch key will prevent screenswitching using the <Ctrl><Alt_R><Fn> sequence (where <Fn> is a function key). However, using the left Alt key <Alt_L> will still allow screenswitching.

If you do not want the Mode_switch key defined, then use the -m option to xsconfig.sh.

For examples of valid parameter entries, see the relevant sections of the following files:

/usr/lib/X11/xsconfig/definitions/DEFAULT
/usr/lib/X11/xsconfig/keyctrl/DEFAULT
/usr/lib/X11/xsconfig/keysyms/DEFAULT
/usr/lib/X11/xsconfig/modifiers/DEFAULT
/usr/lib/X11/xsconfig/translations/DEFAULT

In the absence of command line arguments, xsconfig.sh will generate .Xsco.cfg from the information in the DEFAULT files in each of the subdirectories definitions, keyctrl, keysyms, modifiers, and translations.

If the optional parameter keyboard_name is given, then xsconfig.sh will generate .Xsco.cfg from the information in the file named keyboard_name in each of the subdirectories definitions, keyctrl, keysyms, modifiers, and translations. Whenever the filename keyboard_name does not exist in any of these subdirectories, then xsconfig.sh will use the DEFAULT file.

If the optional parameters csxmap_file and keyboard_name are given and the file keysyms/keyboard_name does not exist, then this script will call mapkey -c with those parameters. The output of mapkey -c will provide the default keysyms settings to be used instead of the settings specified in the file keysyms/DEFAULT. In addition Mode_switch will be defined to be Mod3 unless the -m option is specified.

Configuration source files

xsconfig processes multiple source files in sequence. A configuration source file is a text file that contains the following types of data:

comments, preceded by a semicolon
#include commands that provide a full path to another source configuration file (full path is required because a search strategy is not implemented). This command must have the same syntax as the C preprocessor #include command.
section headers enclosed in square brackets. Configuration data is separated into the following sections:
- definitions
- translations
- keyctrl
- modifiers
- keysyms
These sections are described in the following paragraphs.
configuration settings or definitions in each section

Definitions

Configuration source files list definitions under the heading ``[definitions]''. Each line of this section has the following syntax: #define name value

name is a sequence of letters, numbers, and underscores. Valid names are a superset of name values in C preprocessor #define commands. name must contain at least one non-digit.

value must be either a number sequence or a string enclosed in quotation marks ("). There is currently no use for string definitions. There is no expression evaluator, so numeric values must be a single number using C conventions for specifying octal, decimal, and hexadecimal numbers.

The primary purpose of this section is to include the file /usr/lib/X11/xsconfig/keysymdef.h which defines the key symbol values. Any line in this section not beginning with #define or #include is interpreted as commentary.

For examples, see the ``definitions'' section in /usr/lib/X11/xsconfig/keysymdef.h.

Translations

Configuration source files list translations under the heading ``[translations]''. Each line of this section has the following syntax:

scancode=translation

scancode is the original scancode generated by pressing the key. translation is a translated keycode.

On 101-key personal computer keyboards, the dedicated cursor keys produce two-byte scancodes. The first byte is always ``0xE0''. The second byte is the scancode of the corresponding numeric keypad key. The ``translations'' section is used to translate these two-byte scancodes to a unique single-byte keycode.

For examples, see the ``translations'' section in /usr/lib/X11/xsconfig/translations/DEFAULT.

Keyctrl

The ``[keyctrl]'' section of configuration source files attaches any of several control flags to particular keys. The keys are specified by their scancodes as in the ``translations'' section. The ``translations'' section has no effect on the scancodes specified in the ``keyctrl'' section. Each line in the ``keyctrl'' section has the following syntax:

scancode: flag [flag . . .]

scancode is the original scancode generated by pressing the key. flag specifies one of the following locking keys:

<CapsLock>
<NumLock>
<ScrollLock>
<PseudoLock>

In each case, the LED reflects the state of the key. In the case of <PseudoLock>, locking is simulated, and no keyboard LED is associated with the key. Any number of keys may have this attribute. Only one key should be associated with each of the keyboard LEDs.

For examples, see the ``keyctrl'' section in /usr/lib/X11/xsconfig/keyctrl/DEFAULT.

Modifiers

Configuration source files list modifiers under the heading ``[modifiers]''. This section defines the modifier keys, such as <Shift>, <Caps Lock>, <Ctrl>, <Alt>, and <Mode_Switch>. Each line of this section has the following syntax:

keycode: modifiername

keycode is the keycode, possibly translated, for the key. keycode ranges from 0 to whatever range of values the keyboard can generate.

modifiername is one of ``Shift'', ``Lock'', ``Control'', or``Mod1'' through ``Mod5''. The SCO OpenServer convention is to use ``Mod1'' for the right <Alt> key.

For examples, see the ``modifiers'' section in /usr/lib/X11/xsconfig/modifiers/DEFAULT.

Keysyms

Configuration source files list keysyms under the heading ``[keysyms]''. This section provides the mapping between keycodes and the glyphs associated with each key. Each line of this section has the following syntax:

keycode: keysymlist

keycode is the keycode, possibly translated, for the key. keycode ranges from 0 to whatever range of values the keyboard can generate.

keysymlist is a list of keysyms, separated by white space. Each keysym corresponds to a legend (glyph) on the key. The /usr/lib/X11/xsconfig/keysymdef.h file is useful for choosing keysym names. Each keysym definition is prefaced with the string XK_, which should be omitted when specifying keysyms in the ``modifiers'' section.

The translation currently used by most clients associates the first keysym in keysymlist with the unshifted state and the second keysym, if present, with the shifted state. For the alphabetic keys, only the uppercase keysym is specified and the value is converted to lowercase when unshifted.

Many non-U.S. keyboards have more than two symbols on some keys. A modifier key, referred to as the ``Mode Switch'' key, is used to switch to a second group of symbols. Conventionally, the default Mode Switch key is labeled <AltGr>, though the right <Alt> key is often used. You can make any key the Mode Switch key by attaching a modifier bit (``Mod1'' though ``Mod5'') to the key in the ``modifiers'' section. By default, the Mode Switch key is undefined unless the International Supplement is installed, in which case the convention is to use ``Mod3''. When the Mode Switch key is pressed, the third keysym in keysymlist is associated with the unshifted key, and the fourth keysym is associated with the shifted key.

It is the responsibility of the clients to interpret the association of the modifier bit with the new keysyms.

For examples, see the ``keysyms'' section in /usr/lib/X11/xsconfig/keysyms/DEFAULT.

Files

/usr/lib/X11/.Xsco.cfg
/usr/lib/X11/xsconfig/.Xsco.cfg
/usr/lib/X11/xsconfig/deadkeysymdef.h
/usr/lib/X11/xsconfig/keysymdef.h
/usr/lib/X11/xsconfig/xsconfig.sh