From 829b483a890a28b9dec6d589d7b76d9734e46b93 Mon Sep 17 00:00:00 2001 From: Benno Schulenberg Date: Fri, 15 Apr 2022 12:55:44 +0200 Subject: docs: make one of the READMEs more grammatical, mostly by adding articles Also reword a few things for clarity, and rewrap some lines to avoid hyphenations. --- docs/README.config | 143 ++++++++++++++++++++++++++--------------------------- 1 file changed, 70 insertions(+), 73 deletions(-) (limited to 'docs') diff --git a/docs/README.config b/docs/README.config index 4a06886..7f2092c 100644 --- a/docs/README.config +++ b/docs/README.config @@ -7,48 +7,47 @@ Abstract This document describes how to configure XFree86 XKB from a user's - point a few. It converts basic configuration syntax and gives also + point of view. It covers the basic configuration syntax and gives 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. +The XKB configuration system consists of a number of components. Selecting +and combining the proper parts, 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 component files themselves. -2. Selecting XKB Configuration +2. Selecting an 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 +The easiest and most natural way to specify a keyboard mapping is to use +the rules component. As its name suggests, it describes a number of general +rules on how to combine the 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. +feed it with a few parameters that will adjust the keyboard behaviour to +fulfill your needs. The parameters are: - o XkbRules - files of rules to be used for keyboard mapping composition + o XkbRules - the file of rules to be used for keyboard mapping composition - o XkbModel - name of model of your keyboard type + o XkbModel - the name of the model of your keyboard - o XkbLayout - layout(s) you intend to use + o XkbLayout - the layout(s) you intend to use - o XkbVariant - variant(s) of layout you intend to use + o XkbVariant - the variant(s) of the layout(s) 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 -.lst, for instance xfree86.lst which is located in xkb configu- -ration subdirectory rules (for example /etc/X11/xkb/rules). +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 .lst, for instance xfree86.lst, which is located in the xkb +configuration 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): +Let's say you want to configure a PC-style American keyboard with 104 keys +as described in xfree86.lst. It can be done by simply writing several lines +to your XFree86 configuration file (often found as /etc/X11/XF86Config): Section "InputDevice" Identifier "Keyboard1" @@ -59,36 +58,36 @@ or /etc/X11/XF86Config): 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. +The values of the parameters XkbModel and XkbLayout are really not surprising. +The parameter XkbOptions has been explicitly set to empty, meaning no options. +The parameter XkbVariant has been left out, meaning that the default variant +(the first variant in the file, often named 'basic') will be loaded. -Of course, this can be also done at runtime using utility setxkbmap. Shell -command loading the same keyboard mapping would look like: +Of course, this can also be done at runtime using the utility setxkbmap. +The 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 +The configuration snippet and the shell command will be very similar 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. +Since XFree86 4.3.x, you can use multi-layouts xkb configuration. What does +it mean? Basically it allows you to load up to four different keyboard layouts +at a time. Each such layout will reside in its own group. The groups (unlike +a complete keyboard remapping) can be switched very fast from one to another +with some key combination. 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. +you intend to use three different layouts at the same time - US, Czech and +German (in this order), and that you are used to the Alt+Shift combination +for switching among them. Then the configuration snippet could look like this: Section "InputDevice" - Identifier "Keyboard1" + Identifier "Keyboard2" Driver "Keyboard" Option "XkbModel" "logicordless" @@ -96,20 +95,20 @@ Then the configuration snippet could look like this: 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: +Of course, this can also be done at runtime using the utility setxkbmap. +The shell command loading the same keyboard mapping would look like: setxkbmap -rules xfree86 -model logicordless -layout "us,cz,de" \ - -option "grp:alt_shift_toggle" + -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: +want to change it a bit. Let's imagine you want the Czech keyboard mapping to +use another variant than basic. The configuration snippet then changes into: Section "InputDevice" - Identifier "Keyboard1" + Identifier "Keyboard2" Driver "Keyboard" Option "XkbModel" "logicordless" @@ -118,12 +117,12 @@ use another variant but basic. The configuration snippet then changes into: 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). +That's seems tricky but it is not. The logic for setting variants is the same +as for layouts, which means that the first and the third variant settings are +left out (set to basic), and the second is set to bksl (a special variant with +an enhanced definition of the backslash key). -Analogically, the loading runtime will change to: +Analogically, the loading at runtime will change to: setxkmap -rules xfree86 -model logicordless -layout "us,cz,de" \ -variant ",bksl," -option "grp:alt_shift_toggle" @@ -134,14 +133,14 @@ 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 +Generally, you can directly prescribe what configuration of each of the 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. +the meaning of all of the 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? +This method also exposes all xkb configuration details directly into the +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 @@ -150,15 +149,14 @@ 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 types - a specification of what various combinations of modifiers produce o key symbols - a translation of symbolic key codes into actual symbols - o geometry - a description of physical keyboard geometry + o geometry - a description of all physical keyboard dimensions - o compatibility maps - a specification of what action should each key pro- - duce in order to preserve compatibility with XKB-unware clients + o compatibility maps - a specification of what action should each key + produce in order to preserve compatibility with XKB-unware clients 3.2 Example Configuration @@ -175,21 +173,20 @@ Look at the following example: 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 +This configuration sets the standard XFree86 interpretation of keyboard +keycodes, and sets the default modificator types. The symbol table is +composed of an extended US keyboard layout in its variant for PC keyboards +with 104 keys, and all keys for a German layout are redefined. Also the +logical meanings of the Caps-lock and Control keys are swapped. The standard +keyboard geometry (physical look) is set to a 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 +This 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. +been obsoleted by the previously described rules files which are far more +flexible and allow a simpler and more intuitive syntax. The obsolete method +is preserved merely for compatibility reasons. Avoid using it if possible. - Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/XKB-Config.sgml,v 1.4 dawes Exp $ -- cgit v1.2.1