docs: make another README more grammatical, mostly by adding articles

2 files changed, 187 insertions, 178 deletions

diff --git a/docs/README.config b/docs/README.config
index 7f2092c7..6f8518a5 100644
--- a/docs/README.config
+++ b/docs/README.config
@@ -1,3 +1,4 @@
+
                          The XKB Configuration Guide
 
                          Kamil Toman, Ivan U. Pascal
@@ -10,6 +11,7 @@
      point of view. It covers the basic configuration syntax and gives
      a few examples.
 
+
 1.  Overview
 
 The XKB configuration system consists of a number of components. Selecting
@@ -17,6 +19,7 @@ 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 an XKB configuration
 
 The easiest and most natural way to specify a keyboard mapping is to use
@@ -117,7 +120,7 @@ use another variant than 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 setting variants is the same
+That 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).
@@ -129,11 +132,12 @@ Analogically, the loading at runtime will change to:
 
 2.4  Basic Global Options
 
-See rules/*.lst files.
+See the rules/*.lst files.
+
 
 3.  Direct XKB Configuration
 
-Generally, you can directly prescribe what configuration of each of the basic
+Generally, you can directly prescribe what configuration for 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 the used configuration components.
@@ -155,7 +159,7 @@ There are five basic components used to form a keyboard mapping:
 
    o geometry - a description of all physical keyboard dimensions
 
-   o compatibility maps - a specification of what action should each key
+   o compatibility maps - a specification of what action each key should
      produce in order to preserve compatibility with XKB-unware clients
 
 3.2  Example Configuration
@@ -182,6 +186,7 @@ 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
 
 This is the formerly used way to configure xkb. The user included a special
@@ -189,4 +194,3 @@ keymap file which specified the direct xkb configuration. This method has
 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.
-
diff --git a/docs/README.enhancing b/docs/README.enhancing
index f8790dd3..4a6b083a 100644
--- a/docs/README.enhancing
+++ b/docs/README.enhancing
@@ -1,4 +1,5 @@
-                  How to further enhance XKB configuration
+
+                      How to enhance XKB configuration
 
                          Kamil Toman, Ivan U. Pascal
 
@@ -6,90 +7,93 @@
 
                                   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.
+     This guide is aimed at alleviating one's labour when creating a
+     new (internationalized) keyboard layout. Unlike other documents,
+     this guide emphasizes 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).
+The developer of a new layout should read the XKB protocol specification
+(The X Keyboard Extension: Protocol Specification [1]) at least to clarify
+for themselves some XKB-specific terms used in this document and elsewhere
+in XKB configuration. It is also wise to understand how the X server and
+a client digest their keyboard inputs (with and without XKB).
+
+Another useful source is Ivan Pascal's text about XKB configuration [2].
 
-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.
+   [1] https://www.x.org/docs/XKB/XKBproto.pdf
+   [2] http://pascal.tsu.ru/en/xkb/
 
 Note that this document covers only enhancements which are to be made to
-XFree86 version 4.3.x and above.
+XFree86 versions 4.3.x and newer.
+
 
 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.
+At boottime (or later at the user's command) the X server starts its xkb
+keyboard extension module 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
+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.
+selves, for them it is invisible. Usually, it is run upon X server startup.
 
-As you probably already know, the xkb configuration consists of five main
+As you probably already know, 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
+            Tables that define the translation from keyboard scan codes into
+            reasonably symbolic names, maximum and minimum valid keycodes,
+            symbolic aliases, and a description of physically present LED-indica-
+            tors. The primary sense 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):
+            board scancodes. There are two main conventions for symbolic
+            names (always four bytes long):
 
-               o  names which express some traditional meaning like <SPCE>
-                 (stands for space bar) or
+               o  names which express some traditional meaning, like <SPCE>
+                  (which stands for space bar)
 
-               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.
+               o  names which express a relative position on the keyboard,
+                  for example <AE01> (the exclamation mark on US keyboards),
+                  with on its right the 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.
+            Types describe how the pressed key is affected by active modifiers
+            (like Shift, Control, Alt, ...). There are several predefined
+            types which cover most of the usual 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.
+            The compatibility component defines the internal behaviour of
+            modifiers. Using the compat component you can assign various
+            actions (elaborately described in the 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.
+            by their symbolic name, see above). More than one value may be
+            defined for each key and then it depends on the key type and on
+            the modifiers state (respective compat component) which value
+            will be the resulting one when the key is pressed.
 
       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).
+All these components have their files located in the xkb configuration tree,
+in subdirectories with the same name (usually in /usr/share/X11/xkb).
+
 
-3.  Enhancing XKB Configuration
+3.  Enhancing the XKB Configuration
 
-Most of xkb enhancements concerns a need to define new output symbols for the
+Most of XKB enhancements are about a need to define new output symbols for
 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).
+a new language, or standard, or just to feel more comfortable when typing text).
 
-What do you need to do? Generally, you have to define following things:
+What do you need to do? Generally, you have to define the following things:
 
    o  the map of symbols itself
 
@@ -98,97 +102,98 @@ What do you need to do? Generally, you have to define following things:
    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.
+to see if there is something you could easily adjust to fit your needs. Even
+if there is nothing similar, you may get some ideas about the basic concepts
+and used tricks.
 
-3.1  Levels And Groups
+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.
+Since XFree86 4.3.0, you can use multiple layouts in the xkb configuration.
+Though still within the boundaries of the xkb protocol and its 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).
+which keycode according to the effective modifier state. The X server itself
+sends only an input event message. Of course, usually the interpretation is
+done by Xlib, Xaw, Motif, Qt, Gtk, or similar libraries. The X server only
+supplies its mapping table (usually upon application startup).
 
-You can think of the X server's symbol table as of a irregular table where
+You can think of the X server's symbol table as of an 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.
+Not all keycodes need to bind different values for different combinations of
+modifiers. The <ENTER> key, for instance, usually doesn't depend on any modi-
+fiers so it has in its row 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.
+bound to certain columns. By editing the proper files (see Key Types, below)
+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
+Unlike the original X protocol, the XKB approach is far more flexible.
+XKB introduces one additional term: the group. You can think of a group
+as of a vector of columns per 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
+ble. But then the group has a natural meaning: each symbol set has its own
+group and changing it means selecting a different one. The 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.
+levels. The X server knows what the current group is and reports it together
+with the modifier state and the 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 keycode the 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  for each group of a keycode the 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  different groups of one keycode can have different number of shift levels
 
-   o  the current group number is tracked by X server
+   o  the current group number is tracked by the 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
+It is clear that if you sanely define levels and groups, and sanely bind modi-
+fiers and associated actions, you can have loaded simultaneously 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:
+symbol definitions in a way that allows almost arbitrary composition of
+predefined 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
+      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 "Some Words About XKB internals" [3] for an explanation of used XKB
+terms and problems addressed by the XKB extension.
+
+See "Common notes about XKB configuration files language" [4] for a more
+precise explanation of the syntax of XKB configuration files.
 
-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.
+   [3] http://pascal.tsu.ru/en/xkb/internals.html
+   [4] http://pascal.tsu.ru/en/xkb/gram-common.html
 
 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.
+to use one of four predefined Latin alphabet layouts.
 
-Okay, let's assume you want extend an existing keymap and you want to over-
+Okay, let's assume you want to 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):
 
      default partial alphanumeric_keys
      xkb_symbols "basic" {
+
        include "pc/latin"
 
        name[Group1]="Great Britain";
@@ -198,22 +203,23 @@ pc/gb):
        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 ]   };
+                     [ ISO_Level3_Shift, Multi_key ] };
 
        modifier_map Mod5   { <RALT> };
      };
 
-It defines a new layout in basic variant as an extension of common latin
+It defines a new layout in the basic variant as an extension of a 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>.
+Then there are redefinitions of a few keycodes and a modifier binding. As
+you can see, the number of shift levels is the same for the <AE02>, <AE03>,
+<AC11>, <TLDE> and <BKSL> keys but it differs from the 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.
+like a shift modifier for LevelThree, and together with Shift as a Compose 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
@@ -221,15 +227,15 @@ 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
+The differences in the number of columns (shift levels) are caused by the
+different types of the keys (see the Types definition in section The Basics).
+Most keycodes have implicitly set the keytype in the included "pc/latin" file
+to "FOUR_LEVEL_ALPHABETIC". The only exception is the <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.
+choose a suitable shift level scheme from the default types scheme list in
+the proper xkb component's subdirectory.
 
 The most used schemes are:
 
@@ -238,7 +244,7 @@ The most used schemes are:
             level is always chosen.
 
       TWO_LEVEL
-            The key uses a modifier Shift and may have two possible values.
+            The key uses the 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
@@ -295,29 +301,29 @@ The most used schemes are:
 
       FOUR_LEVEL_MIXED_KEYPAD
 	    A four-level keypad scheme where the first two levels are similar
-            to the KEYPAD scheme (NumLock+Shift)
+            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
+            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
+            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
+            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.
+            modifier rather than Shift. That means, the symbol from the
+            second 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.
+            It is similar to the 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.
 
       CTRL+ALT
             The key uses modifiers Alt and Control. It may have two possible
@@ -345,23 +351,23 @@ ingly. Possible redefinitions are:
    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).
+the 'caps:' xkb option (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.
+Don't alter any of the existing key types. If you need a different behaviour,
+create a new type.
 
-4.2.1  More On Definitions Of Types
+4.2.1  More on Definitions of Types
 
-When the XKB software deals with a separate type description it gets a com-
+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
+fiers=<list of modifiers>' list and expects a set of 'map[<combination of
+modifiers>]=<level indication>' 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
+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:
+Let's consider an example with two modifiers, ModOne and ModTwo:
 
      type "..." {
          modifiers = ModOne+ModTwo;
@@ -369,12 +375,12 @@ Lets consider an example with two modifiers ModOne and ModTwo:
          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.
+In this case the map has a statement for ModOne only and ModOne+ModTwo is
+omitted. This means that if ModTwo is active, the subroutine can't find an
+explicit mapping for this combination and will use the default level, i.e.
 Level1.
 
-But in the case the type described as:
+But in the case that the type is described as:
 
      type "..." {
          modifiers = ModOne;
@@ -384,55 +390,54 @@ But in the case the type described as:
 
 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.
+combination ModOne+ModTwo (as well as ModOne alone) produces the Level2.
 
-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-
+What does it mean if the second modifier is not ModTwo but Lock? It means that
+in the first case (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
+accordingly to the 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-
+don't want to discard it, you may list it 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
+resulting symbol is passed to the 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:
+declare them. Virtual modifiers can have arbitrary names and must be declared
+(prior to using them) directly in the key type definition:
 
-     virtual_modifiers <comma-separated list of modifiers>  ;
+     virtual_modifiers <comma-separated list of modifiers> ;
 
-as seen in for example basic, pc or mousekeys key type definitions.
+as seen in for example the 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
+Once you are finished with your symbol map you need to add it to the rules file.
+The rules file describes how all the five basic components (keycodes, types,
+compat, symbols, and geometry) should be composed to give a sensible resulting
 xkb configuration.
 
-The main advantage of rules over formerly used keymaps is a possibility to
+The main advantage of rules over formerly used keymaps is the 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 pattern in a rules file (often located in /usr/share/X11/xkb/rules) can be
+parameterized with four other arguments: Model, Layout, Variant, and Options.
+For most cases the 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:
+The rules file itself is composed of pattern lines and lines with rules. Each
+pattern line starts with an exclamation mark ('!') and describes how XKB will
+interpret the subsequent lines (rules). A sample rules file looks like this:
 
      ! model                   =   keycodes
        macintosh_old           =   macintosh
@@ -456,11 +461,11 @@ this:
        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
+Each rule defines what a certain combination of values on the left side of the
+equals 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
+while the rest of the models (represented by a wildcard '*') instructs it to
+take them from file keycodes/xfree86. The wildcard 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.
@@ -471,34 +476,34 @@ 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.
+should place the layout resp. variant into the specified xkb group. If the
+brackets 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.
+doesn't cancel caps'' can be selected. The rest of the rules produce special
+symbols for each US variant of the macintosh keyboard, and standard pc symbols
+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.
+Now you just need to add a detailed description to the <rules>.xml description
+file so that other users (and external programs which often parse this file)
+know what your work is about.
 
 4.4.1  Old Descriptive Files
 
-The formerly used descriptive files were named <rules>.lst Its structure is
+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'.
+verted to the old '.lst' format.
 
-For each parameter of rules file should be described its meaning. For the
-rules file described above the .lst file could look like:
+The meaning of each possible parameter of the rules file should be described.
+For the sample rules file given above, the .lst file could look like this:
 
      ! model
        pc104        Generic 104-key PC
@@ -514,7 +519,7 @@ rules file described above the .lst file could look like:
        ...
 
      ! option
-       caps:internal           uses internal capitalization. Shift cancels Caps
-       caps:internal_nocancel  uses internal capitalization. Shift doesn't cancel Caps
+       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.