[STUMP] [PATCH] Add docs on modifiers (namely, how to set up super properly).

[John Li]

---

"How to make the super key work" is a rather frequent question on
#stumpwm. I also added a bit on Meta and Alt, as well as setting up a
Hyper key.

There's one FIXME: I'm not sure if gdm, kdm, xdm, etc. will run
xmodmap with a user's xmodmap file when they log in. I've seen mention
that gdm will run it if the file in named .Xmodmap, but I haven't
tested this (and I kind of suspect that it's Gnome that runs it). But
maybe no StumpWM users care about graphical login managers :).

 stumpwm.texi.in |  139 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 137 insertions(+), 2 deletions(-)

diff --git a/stumpwm.texi.in b/stumpwm.texi.in
index e76304c..95b6c93 100644
--- a/stumpwm.texi.in
+++ b/stumpwm.texi.in
@@ -309,6 +309,7 @@ mimics GNU Screen's keyboard handling. StumpWM's default 
prefix key is
 @menu
 * List of Default Keybindings::  
 * Binding Keys::                
+* Modifiers::
 @end menu
 
 @node List of Default Keybindings, Binding Keys, Key Bindings, Key Bindings
@@ -538,7 +539,7 @@ List all key sequences that are bound to the specified 
command
 Describe the specified command.
 @end table
 
address@hidden Binding Keys,  , List of Default Keybindings, Key Bindings
address@hidden Binding Keys, Modifiers, List of Default Keybindings, Key 
Bindings
 @section Binding Keys
 
 @@@ define-key
@@ -553,7 +554,141 @@ Describe the specified command.
 ### *groups-map*
 
 !!! bind
- 
+
address@hidden Modifiers,  , Binding Keys, Key Bindings
address@hidden Modifiers
+
+Many users have had some difficulty with setting up modifiers for
+StumpWM keybindings. This is caused by a combination of how StumpWM
+handles modifiers and the default modifiers list for many users' X
+servers.
+
address@hidden
+
address@hidden
+My ``Super'' key doesn't work!
+
+This is most likely caused by having the Hyper and Super keys listed
+as the same modifier in the modifier list.
+
address@hidden
+$ xmodmap
+xmodmap:  up to 3 keys per modifier, (keycodes in parentheses):
+
+shift       Shift_L (0x32),  Shift_R (0x3e)
+lock        Caps_Lock (0x42)
+control     Control_L (0x25),  Control_R (0x6d)
+mod1        Alt_L (0x40),  Alt_R (0x71),  Meta_L (0x9c)
+mod2        Num_Lock (0x4d)
+mod3
+mod4        Super_L (0x7f),  Hyper_L (0x80)
+mod5        Mode_switch (0x5d),  ISO_Level3_Shift (0x7c)
address@hidden example
+
+The problem is in the line beginning with ``mod4''. The way to set up
+the modifier list correctly is to have just the Super key as the mod4
+modifier. The following xmodmap commands will do just that.
+
address@hidden
+# clear out the mod4 modifier
+$ xmodmap -e 'clear mod4'
+$ xmodmap
+xmodmap:  up to 3 keys per modifier, (keycodes in parentheses):
+
+shift       Shift_L (0x32),  Shift_R (0x3e)
+lock        Caps_Lock (0x42)
+control     Control_L (0x25),  Control_R (0x6d)
+mod1        Alt_L (0x40),  Alt_R (0x71),  Meta_L (0x9c)
+mod2        Num_Lock (0x4d)
+mod3
+mod4
+mod5        Mode_switch (0x5d),  ISO_Level3_Shift (0x7c)
+
+# add Super as a mod4 modifier
+$ xmodmap -e 'add mod4 = Super_L'
+$ xmodmap
+xmodmap:  up to 3 keys per modifier, (keycodes in parentheses):
+
+shift       Shift_L (0x32),  Shift_R (0x3e)
+lock        Caps_Lock (0x42)
+control     Control_L (0x25),  Control_R (0x6d)
+mod1        Alt_L (0x40),  Alt_R (0x71),  Meta_L (0x9c)
+mod2        Num_Lock (0x4d)
+mod3
+mod4        Super_L (0x73),  Super_L (0x7f)
+mod5        Mode_switch (0x5d),  ISO_Level3_Shift (0x7c)
address@hidden example
+
+You can automate this by storing the commands in a file and calling
+xmodmap when you start your X session.
+
address@hidden
+$ cat ~/.Xmodmap
+clear mod4
+add mod4 = Super_L
address@hidden example
+
+If you use "startx", modify your ~/.xsession or ~/.xinitrc file.
+
address@hidden
+$ cat ~/.xsession
+#!/bin/sh
+
+xmodmap ~/.Xmodmap
+exec /usr/bin/stumpwm
address@hidden example
+
+If you use a graphical login manager (GDM, KDM, etc.), your ~/.Xmodmap
+file should fed to xmodmap when you log in. FIXME: verify this.
+
address@hidden
+Handling Meta and Alt: when do I use ``M-'' and ``A-''?
+
+If you have no Meta keys defined (see the output of the ``xmodmap''
+command), then StumpWM will treat the ``M-'' prefix in keybindings to
+mean Alt. However, if there are Meta keys defined, then the ``M-''
+prefix refers to them, and the ``A-'' prefix refers to Alt.
+
+Most users will simply use ``M-'' to refer to their Alt keys. However,
+users that define separate Meta and Alt keys will use ``M-'' to refer
+to the former, and ``A-'' to refer to the latter.
+
address@hidden
+How can I set up a Hyper key and use it with StumpWM?
+
+To set up a Hyper key, you need to do two things: bind a physical key
+to be a Hyper key, and add that key to the modifiers list.
+
+The following example shows how to bind the control key at the
+bottom-left of most keyboards to be Hyper. This is useful if you've
+made Caps Lock into a control key, and have no use for the bottom-left
+key.
+
address@hidden
+$ xmodmap -e 'keycode 37 = Hyper_L'
+$ xmodmap -e 'clear mod5'
+$ xmodmap -e 'add mod5 = Hyper_L'
address@hidden example
+
+To use a different key for Hyper, replace the keycode ``37'' above.
+Use the ``xev'' program to see the keycode that any physical key has.
+Refer to the section above on setting up the Super key to see how to
+automate setting the Hyper key when you start X.
+
+Now you can use ``H-'' as a prefix in StumpWM bindings.
+
address@hidden
+(define-key *top-map* (kbd "H-RET") "fullscreen")
+(define-key *top-map* (kbd "H-Left") "gprev")
+(define-key *top-map* (kbd "H-Right") "gnext")
+(define-key *top-map* (kbd "H-TAB") "other")
address@hidden example
+
+Since essentially no programs have Hyper bindings, you can safely bind
+commands to the top-map.
+
address@hidden itemize
+
 @node Commands, Message and Input Bar, Key Bindings, Top
 @chapter Commands
 If you've used emacs before you'll find commands and functions
-- 
1.5.6.3