more documentation for WindowNavigation and UrgencyHook

XMonad/Actions/WindowNavigation.hs

@@ -1,17 +1,27 @@
 -----------------------------------------------------------------------------
 -- |
--- Module      :  XMonad.Layout.WindowNavigation
+-- Module      :  XMonad.Actions.WindowNavigation
 -- Copyright   :  (c) 2007  David Roundy <droundy@darcs.net>,
 --                          Devin Mullins <me@twifkak.com>
 -- Maintainer  :  Devin Mullins <me@twifkak.com>
 -- License     :  BSD3-style (see LICENSE)
 --
--- This is a rewrite of "XMonad.Layout.WindowNavigation", for the purposes of
--- code cleanup and Xinerama support. It's not complete, so you'll want to
--- use that one for now.
+-- This is a rewrite of "XMonad.Layout.WindowNavigation".  WindowNavigation
+-- lets you assign keys to move up\/down\/left\/right, based on actual cartesian
+-- window coordinates, rather than just going j\/k on the stack.
 --
--- WindowNavigation lets you assign keys to move up/down/left/right, based on
--- actual cartesian window coordinates, rather than just going j/k on the stack.
+-- This module differs from the other in a few ways:
+--
+--   (1) You can go up\/down\/left\/right across multiple screens.
+--
+--   (2) It doesn't provide little border colors for your neighboring windows.
+--
+--   (3) It doesn't provide the \'Move\' action, which seems to be related to
+--      the XMonad.Layout.Combo extension.
+--
+--   (4) It tries to be slightly smarter about tracking your current position.
+--
+--   (5) Configuration is different.
 --
 -----------------------------------------------------------------------------
 
@@ -42,12 +52,29 @@ import Graphics.X11.Xlib
 
 -- $usage
 --
--- Don't use it! What, are you crazy?
+-- To use it, you're going to apply the 'withWindowNavigation' function.
+-- 'withWindowNavigation' performs some IO operations, so the syntax you'll use
+-- is the same as the spawnPipe example in "XMonad.Hooks.DynamicLog".
+-- In particular:
+--
+-- > main = do
+-- >     config <- withWindowNavigation (xK_w, xK_a, xK_s, xK_d)
+-- >             $ defaultConfig { ... }
+-- >     xmonad config
+--
+-- Here, we pass in the keys for navigation in counter-clockwise order from up.
+-- It creates keybindings for @modMask@ to move to window, and @modMask .|. shiftMask@
+-- to swap windows.
+--
+-- If you want more flexibility over your keybindings, you can use
+-- 'withWindowNavigationKeys', which takes a list of @keys@-esque entries rather
+-- than a tuple of the four directional keys. See the source code of
+-- 'withWindowNavigation' for an example.
 
 -- TODO:
---  - documentation :)
 --  - monad for WNState?
 --  - cleanup (including inr)
+--  - more documentation
 --  - tests? (esp. for edge cases in currentPosition)
 --  - solve the 2+3, middle right to bottom left problem
 --  - manageHook to draw window decos?

XMonad/Hooks/UrgencyHook.hs

@@ -32,6 +32,9 @@ module XMonad.Hooks.UrgencyHook (
                                  -- ** Note
                                  -- $note
 
+                                 -- * Troubleshooting
+                                 -- $troubleshooting
+
                                  -- * Example: Setting up irssi + rxvt-unicode
                                  -- $example
 
@@ -124,6 +127,29 @@ import Foreign (unsafePerformIO)
 -- urgency hook and restart xmonad, you may need to rejigger your layout by
 -- hitting mod-shift-space.
 
+-- $troubleshooting
+--
+-- There are three steps to get right:
+--
+-- 1. The X client must set the UrgencyHint flag. How to configure this
+--    depends on the application. If you're using a terminal app, this is in
+--    two parts:
+--
+--      * The console app must send a ^G (bell). In bash, a helpful trick is
+--        @sleep 1; echo -e \'\a\'@.
+--
+--      * The terminal must convert the bell into UrgencyHint.
+--
+-- 2. XMonad must be configured to notice UrgencyHints. If you've added
+--    withUrgencyHook, you may need to hit mod-shift-space to reset the layout.
+--
+-- 3. The dzen must run when told. Run @dzen2 -help@ and make sure that it
+--    supports all of the arguments you told DzenUrgencyHook to pass it. Also,
+--    set up a keybinding to the 'dzen' action in "XMonad.Util.Dzen" to test
+--    if that works.
+--
+-- As best you can, try to isolate which one(s) of those is failing.
+
 -- $example
 --
 -- This is a commonly asked example. By default, the window doesn't get flagged