heads up: polish config.hs. moves tiling-local values into lexical scope. removes wide' as an explicit mode (it's mirror tall')

Config.hs

@@ -28,36 +28,33 @@ import qualified Data.Map as M
 import System.Exit
 import Graphics.X11.Xlib
 
--- The number of workspaces (virtual screens)
+--
+-- The number of workspaces (virtual screens, or window groups)
+--
 workspaces :: Int
 workspaces = 9
 
--- modMask lets you specify which modkey you want to use. The default is mod1Mask
--- ("left alt").  You may also consider using mod3Mask ("right alt"), which
--- does not conflict with emacs keybindings. The "windows key" is usually
--- mod4Mask.
+--
+-- modMask lets you specify which modkey you want to use. The default is
+-- mod1Mask ("left alt").  You may also consider using mod3Mask ("right
+-- alt"), which does not conflict with emacs keybindings. The "windows
+-- key" is usually mod4Mask.
 --
 modMask :: KeyMask
 modMask = mod1Mask
 
--- When resizing a window, this ratio specifies by what percent to
--- resize in a single step
-defaultDelta :: Rational
-defaultDelta = 3%100
-
--- The default number of windows in the master area
-defaultWindowsInMaster :: Int
-defaultWindowsInMaster = 1
-
+--
 -- Default offset of drawable screen boundaries from each physical screen.
 -- Anything non-zero here will leave a gap of that many pixels on the
--- given edge, on the that screen. A useful gap at top of screen for a menu bar (e.g. 15)
+-- given edge, on the that screen. A useful gap at top of screen for a
+-- menu bar (e.g. 15)
 --
 -- Fields are: top, bottom, left, right.
 --
 defaultGaps :: [(Int,Int,Int,Int)]
 defaultGaps = [(0,0,0,0)] -- 15 for default dzen
 
+--
 -- numlock handling:
 --
 -- The mask for the numlock key. You may need to change this on some systems.
@@ -71,24 +68,43 @@ defaultGaps = [(0,0,0,0)] -- 15 for default dzen
 numlockMask :: KeyMask
 numlockMask = mod2Mask
 
+--
 -- Border colors for unfocused and focused windows, respectively.
+--
 normalBorderColor, focusedBorderColor :: String
 normalBorderColor  = "#dddddd"
 focusedBorderColor = "#ff0000"
 
+--
 -- Width of the window border in pixels
+--
 borderWidth :: Dimension
 borderWidth = 1
 
--- The default set of Layouts:
+--
+-- The default set of tiling algorithms
+--
 defaultLayouts :: [Layout]
-defaultLayouts = [ tall defaultWindowsInMaster defaultDelta (1%2)
-                 , wide defaultWindowsInMaster defaultDelta (1%2)
-                 , full ]
+defaultLayouts = [ tiled , mirror tiled , full ]
+  where
+     -- default tiling algorithm partitions the screen into two panes
+     tiled   = tall nmaster delta ratio
+
+     -- The default number of windows in the master pane
+     nmaster = 1
+
+     -- Default proportion of screen occupied by master pane
+     ratio   = 1%2
+
+     -- Percent of screen to increment by when resizing panes
+     delta   = 3%100
 
 --
 -- The key bindings list.
 -- 
+-- The unusual comment format is used to generate the documentation
+-- automatically.
+--
 keys :: M.Map (KeyMask, KeySym) (X ())
 keys = M.fromList $
     -- launching and killing programs
@@ -142,9 +158,11 @@ keys = M.fromList $
         | (key, sc) <- zip [xK_w, xK_e, xK_r] [0..]
         , (f, m) <- [(view, 0), (shift, shiftMask)]]
 
+--
+-- default actions bound to mouse events
+--
 mouseBindings :: M.Map (KeyMask, Button) (Window -> X ())
 mouseBindings = M.fromList $
     [ ((modMask, button1), (\w -> focus w >> mouseMoveWindow w))
     , ((modMask, button2), (\w -> focus w >> swapMaster))
-    , ((modMask, button3), (\w -> focus w >> mouseResizeWindow w))
-    ]
+    , ((modMask, button3), (\w -> focus w >> mouseResizeWindow w)) ]

Operations.hs

@@ -312,7 +312,7 @@ sendMessage a = layout $ \x@(l, ls) -> maybe x (flip (,) ls) (modifyLayout l (So
 --
 --   fullscreen mode
 --   tall mode
---   wide mode
+--   wide mode (a mirror of tall mode)
 -- 
 -- The latter algorithms support the following operations:
 --
@@ -326,13 +326,27 @@ instance Message Resize
 data IncMasterN = IncMasterN Int deriving Typeable
 instance Message IncMasterN
 
+-- simple fullscreen mode, just render all windows fullscreen.
 full :: Layout
 full = Layout { doLayout     = \sc ws -> return [ (w,sc) | w <- ws ]
               , modifyLayout = const Nothing } -- no changes
 
-tall, wide :: Int -> Rational -> Rational -> Layout
-wide nmaster delta frac = mirrorLayout (tall nmaster delta frac)
+-- the true tiling mode of xmonad.
+--
+-- the screen is divided (currently) into two panes. all clients are
+-- then partioned between these two panes. one pane, the `master', by
+-- convention has the least number of windows in it (by default, 1). 
+-- the variable `nmaster' controls how many windows are rendered in the
+-- master pane.
+--
+-- `delta' specifies the ratio of the screen to resize by.
+--
+-- 'frac' specifies what proportion of the screen to devote to the
+-- master area.
+--
+-- 
 
+tall :: Int -> Rational -> Rational -> Layout
 tall nmaster delta frac =
     Layout { doLayout     = \r -> return . ap zip (tile frac r nmaster . length)
            , modifyLayout = \m -> fmap resize     (fromMessage m) `mplus`
@@ -346,11 +360,11 @@ tall nmaster delta frac =
 mirrorRect :: Rectangle -> Rectangle
 mirrorRect (Rectangle rx ry rw rh) = (Rectangle ry rx rh rw)
 
--- | Mirror a layout
-mirrorLayout :: Layout -> Layout
-mirrorLayout (Layout { doLayout = dl, modifyLayout = ml }) =
+-- | Mirror a layout, compute its 90 degree rotated form.
+mirror :: Layout -> Layout
+mirror (Layout { doLayout = dl, modifyLayout = ml }) =
               Layout { doLayout = \sc w -> map (second mirrorRect) `fmap` dl (mirrorRect sc) w
-                     , modifyLayout = fmap mirrorLayout . ml }
+                     , modifyLayout = fmap mirror . ml }
 
 -- | tile.  Compute the positions for windows in our default tiling modes
 -- Tiling algorithms in the core should satisify the constraint that
@@ -363,6 +377,7 @@ tile f r nmaster n | n <= nmaster = splitVertically n r
                    | otherwise    = splitVertically nmaster r1 ++ splitVertically (n-nmaster) r2
     where (r1,r2) = splitHorizontallyBy f r
 
+-- divide a rectangle, computing a number of subrectangles.
 splitVertically, splitHorizontally :: Int -> Rectangle -> [Rectangle]
 splitVertically n r | n < 2 = [r]
 splitVertically n (Rectangle sx sy sw sh) = Rectangle sx sy sw smallh :