1 files changed, 36 insertions, 33 deletions
diff --git a/xorg-server/xkeyboard-config/symbols/level3 b/xorg-server/xkeyboard-config/symbols/level3
index 2f5575c62..8f3da0da8 100644
--- a/xorg-server/xkeyboard-config/symbols/level3
+++ b/xorg-server/xkeyboard-config/symbols/level3
@@ -1,20 +1,18 @@
-// these variants assign various XKB keycodes to ISO_Level3_Shift so that
-// the third shift level can be reached
-//
+// These partial variants assign ISO_Level3_Shift to various XKB keycodes
+// so that the third shift level can be reached.
 
-// Ensure a mapping to a real modifier for LevelThree
+// Ensure a mapping to a real modifier for LevelThree.
 partial modifier_keys
 xkb_symbols "modifier_mapping" {
   key.type[Group1] = "ONE_LEVEL";
-
   replace key <LVL3> {
     symbols[Group1] = [ ISO_Level3_Shift ]
   };
   modifier_map Mod5 { <LVL3> };
 };
 
-// the default behavior is for the right Alt key (AltGr) to generate the
-// third engraved symbol
+// The default behaviour:
+// the right Alt key (AltGr) chooses the third symbol engraved on a key.
 default partial modifier_keys
 xkb_symbols "ralt_switch" {
   key <RALT> {
@@ -24,10 +22,10 @@ xkb_symbols "ralt_switch" {
   include "level3(modifier_mapping)"
 };
 
-// Right Alt key never chooses 3rd level.
-// This option attempts to undo the effect of a layout's
-// including ralt_switch.  You may also want to select another
-// level3 option that maps the level3 shift to some other key.
+// The right Alt key never chooses the third level.
+// This option attempts to undo the effect of a layout's inclusion of
+// 'ralt_switch'.  You may want to also select another level3 option
+// to map the level3 shift to some other key.
 partial modifier_keys
 xkb_symbols "ralt_alt" {
   key <RALT> { 
@@ -40,9 +38,11 @@ xkb_symbols "ralt_alt" {
     symbols[Group3] = [ Alt_R, Meta_R ], 
     symbols[Group4] = [ Alt_R, Meta_R ]
     };
-  modifier_map Mod1    { <RALT> };
+  modifier_map Mod1 { <RALT> };
 };
 
+// The right Alt key (while pressed) chooses the third shift level,
+// and Compose is mapped to its second level.
 partial modifier_keys
 xkb_symbols "ralt_switch_multikey" {
   key <RALT> {
@@ -52,14 +52,13 @@ xkb_symbols "ralt_switch_multikey" {
   include "level3(modifier_mapping)"
 };
 
-// special case or right Alt switch - for use with grp:alts_toggle
-//
+// A special case of the right-Alt switch -- for use with grp:alts_toggle.
 partial hidden modifier_keys
 xkb_symbols "ralt_switch_for_alts_toggle" {
- virtual_modifiers LAlt, AlGr;
+  virtual_modifiers LAlt, AltGr;
   key <LALT> {
     type[Group1]="PC_RALT_LEVEL2",
-    symbols[Group1] = [ Alt_L,  ISO_Prev_Group,  ISO_Prev_Group ],
+    symbols[Group1] = [ Alt_L, ISO_Prev_Group, ISO_Prev_Group ],
     virtualMods= LAlt
   };
   key <RALT> {
@@ -70,14 +69,15 @@ xkb_symbols "ralt_switch_for_alts_toggle" {
   include "level3(modifier_mapping)"
 };
 
-// using the level(alt_switch) map, either Alt key temporarily chooses
-// the third shift level.  (Mostly be used to imitate Mac OS functionality.)
+// Either Alt key (while pressed) chooses the third shift level.
+// (To be used mostly to imitate Mac OS functionality.)
 partial modifier_keys
 xkb_symbols "alt_switch" {
   include "level3(lalt_switch)"
   include "level3(ralt_switch)"
 };
 
+// The left Alt key (while pressed) chooses the third shift level.
 partial modifier_keys
 xkb_symbols "lalt_switch" {
   key <LALT> {
@@ -87,8 +87,7 @@ xkb_symbols "lalt_switch" {
   include "level3(modifier_mapping)"
 };
 
-// using the level(switch) map, the right Control key temporarily
-// chooses the third shift level (until it is released).
+// The right Ctrl key (while pressed) chooses the third shift level.
 partial modifier_keys
 xkb_symbols "switch" {
   key <RCTL> {
@@ -98,8 +97,7 @@ xkb_symbols "switch" {
   include "level3(modifier_mapping)"
 };
 
-// using the level(menu_switch) map, the Menu key temporarily
-// chooses the third shift level (until it is released).
+// The Menu key (while pressed) chooses the third shift level.
 partial modifier_keys
 xkb_symbols "menu_switch" {
   key <MENU> {
@@ -109,16 +107,14 @@ xkb_symbols "menu_switch" {
   include "level3(modifier_mapping)"
 };
 
-// using the level3(win_switch) map, the either Windows' logo key
-// temporarily chooses the third shift level.
+// Either Win key (while pressed) chooses the third shift level.
 partial modifier_keys
 xkb_symbols "win_switch" {
   include "level3(lwin_switch)"
   include "level3(rwin_switch)"
 };
 
-// using the level3(lwin_switch) map, the left Windows' logo key
-// temporarily chooses the third shift level.
+// The left Win key (while pressed) chooses the third shift level.
 partial modifier_keys
 xkb_symbols "lwin_switch" {
   key <LWIN> {
@@ -128,10 +124,9 @@ xkb_symbols "lwin_switch" {
   include "level3(modifier_mapping)"
 };
 
-// using the level(rwin_switch) map, the right Windows' logo key
-// temporarily chooses the third shift level.  If you use this map,
-// you should define your keyboard as pc101 or pc102 instead of pc104
-// or pc105.
+// The right Win key (while pressed) chooses the third shift level.
+// (When using this map, you should set your keyboard as pc101 or pc102
+// instead of pc104 or pc105.)
 partial modifier_keys
 xkb_symbols "rwin_switch" {
   key <RWIN> {
@@ -141,9 +136,8 @@ xkb_symbols "rwin_switch" {
   include "level3(modifier_mapping)"
 };
 
-// using the level3(enter_switch) map, the Enter key on the keypad
-// temporarily chooses the third shift level.  This is especially
-// useful for Mac laptops which miss the right Alt key.
+// The Enter key on the kepypad (while pressed) chooses the third shift level.
+// (This is especially useful for Mac laptops which miss the right Alt key.)
 partial modifier_keys
 xkb_symbols "enter_switch" {
   key <KPEN> {
@@ -153,6 +147,7 @@ xkb_symbols "enter_switch" {
   include "level3(modifier_mapping)"
 };
 
+// The CapsLock key (while pressed) chooses the third shift level.
 partial modifier_keys
 xkb_symbols "caps_switch" {
   key <CAPS> {
@@ -162,6 +157,7 @@ xkb_symbols "caps_switch" {
   include "level3(modifier_mapping)"
 };
 
+// The Backslash key (while pressed) chooses the third shift level.
 partial modifier_keys
 xkb_symbols "bksl_switch" {
   key <BKSL> {
@@ -171,6 +167,7 @@ xkb_symbols "bksl_switch" {
   include "level3(modifier_mapping)"
 };
 
+// The Less/Greater key (while pressed) chooses the third shift level.
 partial modifier_keys
 xkb_symbols "lsgt_switch" {
   key <LSGT> {
@@ -180,6 +177,8 @@ xkb_symbols "lsgt_switch" {
   include "level3(modifier_mapping)"
 };
 
+// The CapsLock key (while pressed) chooses the third shift level,
+// and latches when pressed together with another third-level chooser.
 partial modifier_keys
 xkb_symbols "caps_switch_latch" {
   key <CAPS> {
@@ -189,6 +188,8 @@ xkb_symbols "caps_switch_latch" {
   include "level3(modifier_mapping)"
 };
 
+// The Backslash key (while pressed) chooses the third shift level,
+// and latches when pressed together with another third-level chooser.
 partial modifier_keys
 xkb_symbols "bksl_switch_latch" {
   key <BKSL> {
@@ -198,6 +199,8 @@ xkb_symbols "bksl_switch_latch" {
   include "level3(modifier_mapping)"
 };
 
+// The Less/Greater key (while pressed) chooses the third shift level,
+// and latches when pressed together with another third-level chooser.
 partial modifier_keys
 xkb_symbols "lsgt_switch_latch" {
   key <LSGT> {