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.

1 files changed, 70 insertions, 73 deletions

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
-<vendor-rules>.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 <vendor>.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 $