compat/*: Tweaking and harmonizing some comments.

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

16 files changed, 81 insertions, 80 deletions

diff --git a/compat/README b/compat/README
index 00d591e7..3c5747bb 100644
--- a/compat/README
+++ b/compat/README
@@ -1,7 +1,7 @@
 The core protocol interpretation of keyboard modifiers does not include direct
 support for multiple keyboard groups, so XKB reports the effective keyboard
-group to XKB-aware clients using some of reserved bits in the state field of
-some core protocol events. This modified state field would not be interpreted
+group to XKB-aware clients using some of the reserved bits in the state field
+of some core protocol events. This modified state field would not be interpreted
 correctly by XKB-unaware clients, so XKB provides a group compatibility mapping
 which remaps the keyboard group into a core modifier mask that has similar
 effects, when possible.
@@ -15,8 +15,8 @@ XKB-unaware clients(*) work as well as possible:
 - The compatibility grab state which is the nearest core-protocol equivalent
   of the grab state.
 
-Compatibility state are essentially the corresponding XKB states, but with
-keyboard group possibly encoded as one or more modifiers. 
+Compatibility states are essentially the corresponding XKB states, but with
+the keyboard group possibly encoded as one or more modifiers.
 
 Modifiers that correspond to each keyboard group are described in this
 group compatibility map.
@@ -25,9 +25,9 @@ group compatibility map.
 ----
 (*) The implementation of XKB invisibly extends the X library to use the
 keyboard extension if it is present. That means, clients that use library or
-toolkit routines to interpret keyboard events automatically use all of XKB
-features; clients that directly interpret the state field of core protocol
-events or the keymap direcly may be affected by some of the XKB differences.
+toolkit routines to interpret keyboard events automatically use all of XKB's
+features; clients that directly interpret the state field of core-protocol
+events or the keymap directly may be affected by some of the XKB differences.
 Thus most clients can take all advantages without modification but it also
 means that XKB state can be reported to clients that have not explicitly
 requested the keyboard extension.
diff --git a/compat/basic b/compat/basic
index 393c3244..cfba5f5a 100644
--- a/compat/basic
+++ b/compat/basic
@@ -1,6 +1,6 @@
 // Minimal set of symbol interpretations to provide 
-// reasonable default behavior (Num lock, shift and 
-// caps lock and mode switch) and set up the 
+// reasonable default behavior (Num lock, Shift lock,
+// Caps lock, and Mode switch) and set up the
 // automatic updating of common keyboard LEDs.
 
 default xkb_compatibility "basic"  {
diff --git a/compat/caps b/compat/caps
index d787ab63..d0b7bdd9 100644
--- a/compat/caps
+++ b/compat/caps
@@ -1,11 +1,10 @@
 partial xkb_compatibility "caps_lock"  {
-    // Keysym Caps_Lock locks Lock modifier.
-    // With this, the keysym Caps_Lock can be used without binding the whole
-    // key to a real modifier.
-	// This is essential when you don't want to use caps lock on the first
-	// level.
-	// This should not have any compatibility issues when used together with
-	// other layouts which don't utilize this capability.
+    // Keysym Caps_Lock locks the Lock modifier.
+    // With this definition, the keysym Caps_Lock can be used without binding
+    // the whole key to a real modifier.  This is essential when you don't
+    // want to use Caps_Lock on the first level.
+    // This should not have any compatibility issues when used together with
+    // other layouts which don't utilize this capability.
     interpret Caps_Lock {
         action = LockMods(modifiers = Lock);
     };
diff --git a/compat/iso9995 b/compat/iso9995
index 76188d1f..a92a5201 100644
--- a/compat/iso9995
+++ b/compat/iso9995
@@ -1,5 +1,5 @@
 // Fairly complete set of symbol interpretations 
-// to provide reasonable default behavior
+// to provide reasonable default behavior.
 
 default partial xkb_compatibility "default"  {
     virtual_modifiers LevelThree,AltGr;
diff --git a/compat/japan b/compat/japan
index ab4f85e4..b16f2e7f 100644
--- a/compat/japan
+++ b/compat/japan
@@ -1,9 +1,9 @@
-// Japanese keyboards need Eisu and Kana shift and 
-// lock keys, which are typically bound to the
-// second shift level for some other modifier key.
+// Japanese keyboards need the Eisu and Kana Shift
+// and Lock keys, which are typically bound to the
+// second shift level of some other modifier key.
 // These interpretations disable the default
 // interpretation (which would have these keys set
-// the same modifier as the level one symbol).
+// to the same modifier as the level one symbol).
 
 default partial xkb_compatibility "japan"  {
 
@@ -26,8 +26,8 @@ default partial xkb_compatibility "japan"  {
     };
 };
 
-// Some Japanese keyboards have an explict Kana Lock key & matching LED
-
+// Some Japanese keyboards have an explict
+// Kana Lock key and matching LED.
 partial xkb_compatibility "kana_lock"  {
 
     virtual_modifiers Kana_Lock;
diff --git a/compat/ledcaps b/compat/ledcaps
index fc3084ee..c0ffcc72 100644
--- a/compat/ledcaps
+++ b/compat/ledcaps
@@ -1,4 +1,5 @@
-// Use Caps Lock LED to show either Caps Lock, Group, or Shift Lock state
+// Use the Caps Lock LED to show either
+// Caps Lock, Group, or Shift Lock state.
 
 default partial xkb_compatibility "caps_lock"   {
    indicator "Caps Lock" {
diff --git a/compat/lednum b/compat/lednum
index 24a60a59..da240144 100644
--- a/compat/lednum
+++ b/compat/lednum
@@ -1,4 +1,5 @@
-// Use Num Lock LED to show either Num Lock, Group, or Shift Lock state
+// Use the Num Lock LED to show either
+// Num Lock, Group, or Shift Lock state.
 
 default partial xkb_compatibility "num_lock"   {
     indicator "Num Lock" {
diff --git a/compat/ledscroll b/compat/ledscroll
index ca5a82c4..0237330b 100644
--- a/compat/ledscroll
+++ b/compat/ledscroll
@@ -1,4 +1,5 @@
-// Use Scroll Lock LED to show either Scroll Lock, Group, or Shift Lock state
+// Use the Scroll Lock LED to show either
+// Scroll Lock, Group, or Shift Lock state.
 
 default partial xkb_compatibility "scroll_lock"   {
    indicator "Scroll Lock" {
diff --git a/compat/level5 b/compat/level5
index 8e0cc9c3..ac5799e1 100644
--- a/compat/level5
+++ b/compat/level5
@@ -1,5 +1,5 @@
 // Fairly complete set of symbol interpretations 
-// to provide reasonable default behavior
+// to provide reasonable default behavior.
 
 default partial xkb_compatibility "default"  {
     virtual_modifiers LevelFive;
@@ -39,12 +39,13 @@ default partial xkb_compatibility "default"  {
 	action= LockMods(modifiers=LevelFive);
     };
 };
+
 partial xkb_compatibility "level5_lock"  {
-	// This defines a Level5-Lock using the NumLock real modifier in order to
-	// create arbitrary level-behaviour, which would not be possible with the
-	// virtual modifier.
-	// See also: types/level5 : EIGHT_LEVEL_LEVEL_FIVE_LOCK
-	// See also: symbols/level5(lock)
+    // This defines a Level5-Lock using the NumLock real modifier
+    // in order to create arbitrary level-behaviour, which would
+    // not be possible with the virtual modifier.
+    // See also: types/level5 : EIGHT_LEVEL_LEVEL_FIVE_LOCK
+    // See also: symbols/level5(lock)
     virtual_modifiers NumLock;
     
     interpret ISO_Level5_Lock {
diff --git a/compat/misc b/compat/misc
index cfe9a39b..bc0cb7a0 100644
--- a/compat/misc
+++ b/compat/misc
@@ -2,7 +2,7 @@ default partial xkb_compatibility "misc"  {
 
     virtual_modifiers	Alt,Meta,Super,Hyper,ScrollLock;
 
-    // Interpretations for some other useful keys
+    // Interpretations for some other useful keys.
 
     interpret Terminate_Server {
         action = Terminate();
@@ -10,7 +10,7 @@ default partial xkb_compatibility "misc"  {
 
     setMods.clearLocks= True;
 
-    // Sets the "Alt" virtual modifier
+    // Sets the "Alt" virtual modifier.
 
     interpret Alt_L+Any     {
         //useModMapMods= level1;
@@ -32,10 +32,10 @@ default partial xkb_compatibility "misc"  {
 	action = SetMods(modifiers=Alt);
     };
 
-    // Sets the "Meta" virtual modifier
+    // Sets the "Meta" virtual modifier.
 
     interpret Meta_L+Any     {
-//        useModMapMods= level1;
+        //useModMapMods= level1;
 	virtualModifier= Meta;
 	action = SetMods(modifiers=modMapMods);
     };
@@ -54,10 +54,10 @@ default partial xkb_compatibility "misc"  {
 	action = SetMods(modifiers=Meta);
     };
 
-    // Sets the "Super" virtual modifier
+    // Sets the "Super" virtual modifier.
 
     interpret Super_L+Any     {
-//        useModMapMods= level1;
+        //useModMapMods= level1;
 	virtualModifier= Super;
 	action = SetMods(modifiers=modMapMods);
     };
@@ -76,10 +76,10 @@ default partial xkb_compatibility "misc"  {
 	action = SetMods(modifiers=Super);
     };
 
-    // Sets the "Hyper" virtual modifier
+    // Sets the "Hyper" virtual modifier.
 
     interpret Hyper_L+Any     {
-//        useModMapMods= level1;
+        //useModMapMods= level1;
 	virtualModifier= Hyper;
 	action = SetMods(modifiers=modMapMods);
     };
@@ -112,8 +112,8 @@ default partial xkb_compatibility "misc"  {
 };
 
 partial xkb_compatibility "assign_shift_left_action"  {
-    // Because of the irrevertable modifier mapping in symbols/pc <LFSH> is 
-    // getting bound to the Lock modifier when using 
+    // Because of the irrevertable modifier mapping in symbols/pc,
+    // <LFSH> is getting bound to the Lock modifier when using
     // symbols/shift(both_capslock), creating unwanted behaviour. 
     // This is a quirk, to circumvent the problem.
     interpret Shift_L {
diff --git a/compat/mousekeys b/compat/mousekeys
index f60c756c..82c87b80 100644
--- a/compat/mousekeys
+++ b/compat/mousekeys
@@ -1,12 +1,12 @@
-// Interpretations for arrow keys and a bunch of other 
-// common keysyms which make it possible to bind "mouse" 
-// keys using xmodmap and activate or deactivate them 
-// from the keyboard.
+// Interpretations for arrow keys and a bunch of
+// other common keysyms which make it possible to
+// bind "mouse" keys using xmodmap and activate or
+// deactivate them from the keyboard.
 
 default partial xkb_compatibility "mousekeys" {
 
     // Keypad actions.
-    //
+
     interpret.repeat= True;
 
     interpret KP_1 { 
@@ -114,7 +114,8 @@ default partial xkb_compatibility "mousekeys" {
 	action = LockPointerButton(button=default,affect=unlock); 
     };
 
-    // Additional mappings for Solaris keypad compatibility
+    // Additional mappings for Solaris keypad compatibility.
+
     interpret F25 { // aka KP_Divide
 	action = SetPtrDflt(affect=defaultButton,button=1); 
     };
@@ -139,9 +140,8 @@ default partial xkb_compatibility "mousekeys" {
 
     interpret.repeat= False;
 
+    // New keysym actions.
 
-    // New Keysym Actions.
-    //
     interpret Pointer_Button_Dflt {
 	action= PointerButton(button=default);
     };
@@ -192,10 +192,9 @@ default partial xkb_compatibility "mousekeys" {
 	action= SetPtrDflt(affect=defaultButton,button= -1);
     };
 
-
     // Allow an indicator for MouseKeys.
     indicator "Mouse Keys" {
-//	!allowExplicit;
+        //!allowExplicit;
 	indicatorDrivesKeyboard;
 	controls= MouseKeys;
     };
diff --git a/compat/olpc b/compat/olpc
index a7a2cc42..6eae12d9 100644
--- a/compat/olpc
+++ b/compat/olpc
@@ -1,7 +1,7 @@
 //
-// Created by Bernardo Innocenti <bernie@codewiz.org>
+// Map the OLPC game keys to virtual modifiers.
 //
-// Map the OLPC game keys to virtual modifiers
+// Created by Bernardo Innocenti <bernie@codewiz.org>
 //
 
 default xkb_compatibility "olpc"  {
@@ -11,41 +11,41 @@ default xkb_compatibility "olpc"  {
 
     interpret KP_Home+Any     {
         //useModMapMods= level1;
-       virtualModifier= Square;
-       action = SetMods(modifiers=modMapMods);
+        virtualModifier= Square;
+        action = SetMods(modifiers=modMapMods);
     };
 
     interpret KP_Home  {
-       action = SetMods(modifiers=Square);
+        action = SetMods(modifiers=Square);
     };
 
     interpret KP_Next+Any     {
         //useModMapMods= level1;
-       virtualModifier= Cross;
-       action = SetMods(modifiers=modMapMods);
+        virtualModifier= Cross;
+        action = SetMods(modifiers=modMapMods);
     };
 
     interpret KP_Next  {
-       action = SetMods(modifiers=Cross);
+        action = SetMods(modifiers=Cross);
     };
 
     interpret KP_End+Any     {
         //useModMapMods= level1;
-       virtualModifier= Circle;
-       action = SetMods(modifiers=modMapMods);
+        virtualModifier= Circle;
+        action = SetMods(modifiers=modMapMods);
     };
 
     interpret KP_End   {
-       action = SetMods(modifiers=Circle);
+        action = SetMods(modifiers=Circle);
     };
 
     interpret KP_Prior+Any     {
         //useModMapMods= level1;
-       virtualModifier= Triangle;
-       action = SetMods(modifiers=modMapMods);
+        virtualModifier= Triangle;
+        action = SetMods(modifiers=modMapMods);
     };
 
     interpret KP_Prior {
-       action = SetMods(modifiers=Triangle);
+        action = SetMods(modifiers=Triangle);
     };
 };
diff --git a/compat/pc b/compat/pc
index e970795c..4eef0d9c 100644
--- a/compat/pc
+++ b/compat/pc
@@ -1,6 +1,6 @@
 default partial xkb_compatibility "pc"  {
 
-    // Sets the "Alt" virtual modifier
+    // Sets the "Alt" virtual modifier.
 
     virtual_modifiers	Alt;
 
diff --git a/compat/pc98 b/compat/pc98
index f7e40014..32655997 100644
--- a/compat/pc98
+++ b/compat/pc98
@@ -1,7 +1,7 @@
 // Minimal set of symbol interpretations to provide 
-// reasonable default behavior (Num lock, shift and 
-// caps lock and mode switch) and set up the 
-// automatic updating of common keyboard LEDs.
+// reasonable default behavior (Num lock, Shift lock,
+// and Mode switch) and set up the automatic updating
+// of common keyboard LEDs.
 
 default xkb_compatibility "basic"  {
     virtual_modifiers NumLock,AltGr;
diff --git a/compat/xfree86 b/compat/xfree86
index 52e661dc..313f1a27 100644
--- a/compat/xfree86
+++ b/compat/xfree86
@@ -1,4 +1,4 @@
-//  XFree86 special keysyms
+// XFree86 special keysyms.
 
 default partial xkb_compatibility "basic"  {
 
diff --git a/compat/xtest b/compat/xtest
index 5ee88ccf..0f534f5a 100644
--- a/compat/xtest
+++ b/compat/xtest
@@ -1,15 +1,14 @@
 default xkb_compatibility "xtest"  {
 
     // Minimal set of symbol interpretations to provide
-    // reasonable behavior for testing.   The X Test 
-    // Suite assumes that it can set any modifier by 
-    // simulating a KeyPress and clear it by simulating 
-    // a KeyRelease.  Because of the way that XKB 
-    // implements locking/latching modifiers, this 
-    // approach fails in some cases (typically the 
-    // lock or num lock modifiers).  These symbol
-    // interpretations make all modifier keys just
-    // set the corresponding modifier so that xtest
+    // reasonable behavior for testing.
+    // The X Test Suite assumes that it can set any modifier
+    // by simulating a KeyPress and clear it by simulating a
+    // KeyRelease.  Because of the way that XKB implements
+    // locking/latching modifiers, this approach fails in
+    // some cases (typically the Lock or NumLock modifiers).
+    // These symbol interpretations make all modifier keys
+    // just set the corresponding modifier so that xtest
     // will see the behavior it expects.
 
     virtual_modifiers NumLock,AltGr;