types/*: Correcting, tweaking, and harmonizing some comments.

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>

9 files changed, 58 insertions, 56 deletions

diff --git a/types/README b/types/README
index 1a1e2c01..ff0f61b9 100644
--- a/types/README
+++ b/types/README
@@ -1,4 +1,4 @@
 The types component of a keyboard mapping specifies the key types that can be
-associated with the various keyboard keys. The types component can also
-optionally contain real modifiers binding and symbolic names for one
-or more virtual modifiers.
+associated with the various keyboard keys. The types component can optionally
+contain also real modifier bindings and symbolic names for one or more virtual
+modifiers.
diff --git a/types/basic b/types/basic
index 552b8340..95e85bc2 100644
--- a/types/basic
+++ b/types/basic
@@ -1,7 +1,7 @@
 default xkb_types "basic" {
 
     // Fairly standard definitions for
-    // the four required key types
+    // the three required key types.
 
     virtual_modifiers NumLock;
 
diff --git a/types/caps b/types/caps
index dd7fa2ea..11dd779f 100644
--- a/types/caps
+++ b/types/caps
@@ -1,5 +1,5 @@
-// CapsLock uses internal capitalization rules
-// Shift "pauses" CapsLock
+// CapsLock uses internal capitalization rules,
+// Shift "pauses" CapsLock.
 partial xkb_types "internal" {
     type "ALPHABETIC" {
 	modifiers = Shift+Lock;
@@ -42,8 +42,9 @@ partial xkb_types "internal" {
 	level_name[Level4] = "Shift Alt";
     };
 };
-// CapsLock uses internal capitalization rules
-// Shift doesn't cancel CapsLock
+
+// CapsLock uses internal capitalization rules,
+// Shift doesn't cancel CapsLock.
 partial xkb_types "internal_nocancel" {
     type "ALPHABETIC" {
 	modifiers = Shift;
@@ -77,8 +78,9 @@ partial xkb_types "internal_nocancel" {
 	level_name[Level4] = "Shift Alt";
     };
 };
-// CapsLock acts as Shift with locking
-// Shift "pauses" CapsLock
+
+// CapsLock acts as Shift with locking,
+// Shift "pauses" CapsLock.
 partial xkb_types "shift" {
     type "ALPHABETIC" {
 	modifiers = Shift+Lock;
@@ -120,8 +122,9 @@ partial xkb_types "shift" {
 	level_name[Level4] = "Shift Alt";
     };
 };
-// CapsLock acts as Shift with locking
-// Shift doesn't cancel CapsLock
+
+// CapsLock acts as Shift with locking,
+// Shift doesn't cancel CapsLock.
 partial xkb_types "shift_nocancel" {
     type "ALPHABETIC" {
 	modifiers = Shift+Lock;
diff --git a/types/extra b/types/extra
index 465796b5..5e5fa24e 100644
--- a/types/extra
+++ b/types/extra
@@ -1,7 +1,7 @@
 partial default xkb_types "default" {
-    // Definition for a key type used for the czech keymap, for instance.
-    // Defines style a with four level shift. It is similar to three_level
-    // type used for iso9995 but it lets the shift key behave "normally".
+
+    // Defines a type with a four-level shift, similar to the three-level
+    // type used for iso9995, but it lets the Shift key behave "normally".
 
     virtual_modifiers LevelThree;
 
@@ -49,11 +49,9 @@ partial default xkb_types "default" {
 	level_name[Level4] = "Shift Alt";
     };
 
-    // Another four level keypad variant
-    // First two levels are controled by NumLock (with active Shift-ing like
-    // in KEYPAD). LevelThree overrides this mode, with two additional
-    // Shift-ed levels
-    // NumLock state is intentionnaly ignored when LevelThree is active
+    // A four-level keypad variant. The first two levels are controlled by
+    // NumLock (with active shifting like in KEYPAD).  LevelThree overrides
+    // this mode, with two additional shifted levels.
     type "FOUR_LEVEL_MIXED_KEYPAD" {
         modifiers = Shift+NumLock+LevelThree;
         map[None] = Level1;
@@ -70,7 +68,7 @@ partial default xkb_types "default" {
         level_name[Level4] = "Shift Alt";
     };
 
-    // Base level, two Shift-ed LevelThree levels, one Ctrl+Alt command level
+    // Base level, two shifted LevelThree levels, one Ctrl+Alt command level.
     type "FOUR_LEVEL_X" {
         modifiers = Shift+LevelThree+Control+Alt;
         map[None] = Level1;
@@ -83,10 +81,10 @@ partial default xkb_types "default" {
 	level_name[Level4] = "Ctrl+Alt";
     };
 
-// Special type for keys used in Serbian Latin Unicode map
+// A special type for keys used in the Serbian Latin Unicode keymap.
 // It makes it possible to use all three forms of latin letters 
 // present in Unicode that are made up of two separate letters 
-// (forms like LJ, Lj, and lj; NJ, Nj, and nj; etc)
+// (forms like LJ, Lj, and lj; NJ, Nj, and nj; etcetera).
 
     type "SEPARATE_CAPS_AND_SHIFT_ALPHABETIC" {
         modifiers = Shift+Lock+LevelThree;
@@ -105,21 +103,20 @@ partial default xkb_types "default" {
         level_name[Level4] = "Shift AltGr";
     };
 
-// type for e.g. german ssharp which is capitalized SS.
+// A key type for the German ssharp (for example), which is capitalized as SS.
 // CHARACTERISTICS:
-// It is FOUR_LEVEL with the exception that the fifth level
-// is mapped to the Lock modifier.
-// If other modifiers are used, the Lock state is ignored.
+// It is FOUR_LEVEL with the exception that the fifth level is mapped to the
+// Lock modifier.  If other modifiers are used, the Lock state is ignored.
 // DETAILS ABOUT GERMAN:
-// The capital form of ssharp (called sharp s) only exists for
-// completely capitalized Text, not at the beginning of sentences
-// or nouns (nouns have a captial letter at the beginning in german).
-// The ssharp key, to the right of the zero key, takes this into
-// account and has a questionmark mapped on shift-ssharp since
-// normally no capital version is needed.
-// When typing with active capsLock, this key type is needed to
-// output two capital letters S because this is the only german key
-// whose capital letter is not the same as the one typed with shift.
+// The capital form of ssharp (called sharp s) only exists for completely
+// capitalized text, not for words at the beginning of sentences nor for
+// nouns (nouns in German normally start with a captial letter).
+// The ssharp key, to the right of the zero key, takes this into account
+// and has a questionmark mapped to Shift-ssharp since normally no capital
+// version is needed.
+// When typing with active CapsLock, this key type is needed to
+// output two capital letters S because this is the only German key
+// whose capital letter is not the same as the one typed with Shift.
 
     type "FOUR_LEVEL_PLUS_LOCK" {
         modifiers = Shift+Lock+LevelThree;
@@ -139,7 +136,7 @@ partial default xkb_types "default" {
     };
 };
 
-// This enables the four level shifting also for the keypad.
+// This enables the four-level shifting also for the keypad.
 partial xkb_types "keypad" {
     virtual_modifiers LevelThree;
 
diff --git a/types/iso9995 b/types/iso9995
index 0cf34203..d3c4e0bf 100644
--- a/types/iso9995
+++ b/types/iso9995
@@ -1,8 +1,8 @@
 partial default xkb_types "default" {
 
-    // Definition for a key type which 
-    // can be used to implement ISO9995
-    // style level three shift
+    // A key type which can be used to implement
+    // an ISO9995-style level-three shift.
+
     virtual_modifiers LevelThree;
 
     type "THREE_LEVEL" {
diff --git a/types/level5 b/types/level5
index 672f0a1b..19676f99 100644
--- a/types/level5
+++ b/types/level5
@@ -1,7 +1,7 @@
 partial default xkb_types "default" {
-    // Definition for a key type used for the czech keymap, for instance.
-    // Defines style a with four level shift. It is similar to three_level
-    // type used for iso9995 but it lets the shift key behave "normally".
+
+    // Defines a type with an eight-level shift, similar to the three-level
+    // type used for iso9995, but it lets the Shift key behave "normally".
 
     virtual_modifiers LevelThree,ScrollLock,LevelFive;
 
diff --git a/types/nokia b/types/nokia
index f77d8868..c877ecf4 100644
--- a/types/nokia
+++ b/types/nokia
@@ -1,6 +1,7 @@
 partial default xkb_types "default" {
 
-    // Some types that are used by Nokia devices and keyboard.
+    // Some types that are used by Nokia devices and keyboards.
+
     virtual_modifiers LevelThree;
 
     type "PC_FN_LEVEL2" {
diff --git a/types/numpad b/types/numpad
index 7888d7db..5861f118 100644
--- a/types/numpad
+++ b/types/numpad
@@ -11,7 +11,7 @@ partial default xkb_types "pc" {
     include "extra(keypad)"
 };
 
-// On Mac keypads, level 1 and 2 are swapped
+// On Mac keypads, level 1 and 2 are swapped.
 partial xkb_types "mac" {
     type "KEYPAD" {
 	modifiers = None;
@@ -33,11 +33,11 @@ partial xkb_types "microsoft" {
     include "extra(keypad)"
 };
 
-// Swiss-German style numeric keypad: Shift and NumLock operates as
+// Swiss-German style numeric keypad: Shift and NumLock operate as
 // two independent modifiers; however, since we want shift state for
 // the cursor keys, only three levels are used from the key mappings.
-// Closest type is actually FOUR_LEVEL_X, but most numpad layouts uses
-// FOUR_LEVEL_MIXED_KEYPAD so that's the one we are going to override.
+// Closest type is actually FOUR_LEVEL_X, but most numpad layouts use
+// FOUR_LEVEL_MIXED_KEYPAD, so that's the one we are going to override.
 partial xkb_types "shift3" {
     type "FOUR_LEVEL_MIXED_KEYPAD" {
         modifiers = Shift+NumLock+Control+Alt;
diff --git a/types/pc b/types/pc
index daebe744..17e494b3 100644
--- a/types/pc
+++ b/types/pc
@@ -2,7 +2,8 @@ partial default xkb_types "default" {
 
     // Some types that are necessary
     // for a full implementation of
-    // a PC compatible keyboard.
+    // a PC-compatible keyboard.
+
     virtual_modifiers Alt;
     virtual_modifiers LevelThree;
     virtual_modifiers LAlt;
@@ -74,13 +75,13 @@ partial default xkb_types "default" {
         level_name[Level5] = "Ctrl+Alt";
     };
 
-   // Local eight level
-   // Needed when you want part of your layout eight-level but can not use
-   // LevelFive as modifier, as this will take over right ctrl by default
-   // for all the layout and is too invasive for your average four-level user
-   // Needed to fix bug #9529
-   // FIXME Should really use RControl but it's seems not to be enabled by
-   // default and touching this requires a lot of testing
+   // Local eight level.
+   // Needed when you want part of your layout eight-level but cannot use
+   // LevelFive as modifier, as this will take over the right Ctrl by default
+   // for the whole layout and is too invasive for the average four-level user.
+   // Needed to fix bug #9529.
+   // FIXME: Should really use RControl but it seems not to be enabled by
+   // default and touching this requires a lot of testing.
    type "LOCAL_EIGHT_LEVEL" {
 	modifiers = Shift+Lock+LevelThree+Control;