Doc namespace minor updates

Ignore-this: b3fd7de477f0a9ba6af1d8c78eb47754
Most signifigant changes are use unversioned links to external html,
fix a couple of key binding examples, and double quotes that should
have been single.

darcs-hash:20091023184905-18562-289dca9ef6140e899ff6820bc8d2940cea2488bf.gz

4 files changed, 61 insertions, 37 deletions

diff --git a/XMonad/Actions/CycleWindows.hs b/XMonad/Actions/CycleWindows.hs
index 1a21957..a1d2fee 100644
--- a/XMonad/Actions/CycleWindows.hs
+++ b/XMonad/Actions/CycleWindows.hs
@@ -9,7 +9,9 @@
 -- Portability  : unportable
 --
 -- Provides bindings to cycle windows up or down on the current workspace
--- stack while maintaining focus in place. Bindings are available to:
+-- stack while maintaining focus in place.
+--
+-- Bindings are available to:
 --
 -- * Cycle nearby or nth windows into the focused frame
 --
diff --git a/XMonad/Config/Desktop.hs b/XMonad/Config/Desktop.hs
index 1ed164d..a90bc74 100644
--- a/XMonad/Config/Desktop.hs
+++ b/XMonad/Config/Desktop.hs
@@ -72,7 +72,7 @@ import qualified Data.Map as M
 -- To configure xmonad for use with a DE or with DE tools like panels
 -- and pagers, in place of @defaultConfig@ in your @~\/.xmonad/xmonad.hs@,
 -- use @desktopConfig@ or one of the other desktop configs from the
--- @XMonad.Config@ hierarchy. The following setup and customization examples
+-- @XMonad.Config@ namespace. The following setup and customization examples
 -- work the same way for the other desktop configs as for @desktopConfig@.
 -- If you are using a specific DE config, import its module instead, and
 -- use its config in place of @desktopConfig@ in the following examples.
diff --git a/XMonad/Doc/Configuring.hs b/XMonad/Doc/Configuring.hs
index c80219e..4e3486d 100644
--- a/XMonad/Doc/Configuring.hs
+++ b/XMonad/Doc/Configuring.hs
@@ -49,16 +49,25 @@ if it does exist, xmonad will use whatever settings you specify.  Note
 that this file can contain arbitrary Haskell code, which means that
 you have quite a lot of flexibility in configuring xmonad.
 
-NOTE for users of previous versions (< 0.5) of xmonad: this is a major
-change in the way xmonad is configured.  Prior to version 0.5,
-configuring xmonad required editing an xmonad source file called
-Config.hs, recompiling xmonad, and then restarting.  From version 0.5
-onwards, however, you should NOT edit this file.  All you have to do
-is edit xmonad.hs and restart with @mod-q@; xmonad does the
-recompiling itself.  The format of the configuration file has also
-changed; it is now simpler and much shorter, only requiring you to
-list those settings which are different from the defaults.
-
+HISTORICAL NOTE regarding upgrading from versions (< 0.5) of xmonad
+or using old documentation:
+
+xmonad-0.5 delivered a major change in the way xmonad is configured.  Prior
+to version 0.5, configuring xmonad required editing a source file called
+Config.hs, manually recompiling xmonad, and then restarting.  From
+version 0.5 onwards, however, you should NOT edit this file or manually
+compile with ghc --make.  All you have to do is edit xmonad.hs and restart
+with @mod-q@; xmonad does the recompiling itself. The format of the
+configuration file also changed with version 0.5; enabling simpler and
+much shorter xmonad.hs files that only require listing those settings which
+are different from the defaults.
+
+While the complicated template.hs (man/xmonad.hs) files listing all default
+settings are still provided for reference, once you wish to make substantial
+changes to your configuration, the template.hs style configuration is not
+recommended. It is fine to use top-level definitions to organize your
+xmonad.hs, but wherever possible it is better to leave out settings that
+simply duplicate defaults.
 -}
 
 {- $example
@@ -90,8 +99,8 @@ describe values that differ from the defaults.
 
 As an alternative, you can copy the template @xmonad.hs@ file (found
 either in the @man@ directory, if you have the xmonad source, or on
-the xmonad wiki at
-@http:\/\/haskell.org\/haskellwiki\/Xmonad\/Config_archive\/Template_xmonad.hs@)
+the xmonad wiki config archive at
+<http://haskell.org/haskellwiki/Xmonad/Config_archive>)
 into your @~\/.xmonad\/@ directory.  This template file contains all
 the default settings spelled out, and you should be able to simply
 change the ones you would like to change.
@@ -135,7 +144,8 @@ all your windows, layouts, etc. intact.  (If you change anything
 related to your layouts, you may need to hit @mod-shift-space@ after
 restarting to see the changes take effect.)  If something goes wrong,
 the previous (default) settings will be used.  Note this requires that
-GHC and xmonad are in your @$PATH@.
+GHC and xmonad are in the @$PATH@ in the environment from which xmonad
+is started.
 
 -}
 
diff --git a/XMonad/Doc/Extending.hs b/XMonad/Doc/Extending.hs
index 8d16deb..b57bc2e 100644
--- a/XMonad/Doc/Extending.hs
+++ b/XMonad/Doc/Extending.hs
@@ -142,7 +142,7 @@ edit your key bindings.
 * "XMonad.Actions.CycleWS":
     Provides bindings to cycle forward or backward through the list of
     workspaces, to move windows between workspaces, and to cycle
-    between screens. Replaces "XMonad.Actions.RotView".
+    between screens. Replaces the former XMonad.Actions.RotView.
 
 * "XMonad.Actions.CycleWindows":
     Provides bindings to cycle windows up or down on the current workspace
@@ -233,8 +233,8 @@ edit your key bindings.
     Provides a simple binding to dzen2 to print the date as a popup menu.
 
 * "XMonad.Actions.SinkAll":
-    Provides a simple binding that pushes all floating windows on the
-    current workspace back into tiling. Use the more general general
+    (Deprecated) Provides a simple binding that pushes all floating windows on the
+    current workspace back into tiling. Instead, use the more general
     "XMonad.Actions.WithAll"
 
 * "XMonad.Actions.SpawnOn":
@@ -301,10 +301,13 @@ own configuration, possibly with some modifications.
     This module specifies my xmonad defaults.
 
 * "XMonad.Config.Azerty"
+    Fixes some keybindings for users of French keyboard layouts.
 
 * "XMonad.Config.Desktop"
-    This module provides a config suitable for use with a desktop
-    environment such as KDE or GNOME.
+    This module provides core desktop environment settings used
+    in the Gnome, Kde, and Xfce config configs. It is also useful
+    for people using other environments such as lxde, or using
+    tray or panel applications without full desktop environments.
 
 * "XMonad.Config.Gnome"
 
@@ -314,7 +317,6 @@ own configuration, possibly with some modifications.
 
 * "XMonad.Config.Xfce"
 
-
 -}
 
 {- $hooks
@@ -341,6 +343,10 @@ occur. The two most important hooks are:
   See "XMonad.Doc.Extending#The_log_hook_and_external_status_bars" for more
   information.
 
+* 'XMonad.Core.handleEventHook': this hook is called on all events handled
+  by xmonad, thus it is extremely powerful. See "Graphics.X11.Xlib.Extras"
+  and xmonad source and development documentation for more details.
+
 Here is a list of the modules found in @XMonad.Hooks@:
 
 * "XMonad.Hooks.DynamicHooks":
@@ -391,8 +397,7 @@ Here is a list of the modules found in @XMonad.Hooks@:
 * "XMonad.Hooks.ServerMode": Allows sending commands to a running xmonad process.
 
 * "XMonad.Hooks.SetCursor":
-    Set a default cursor on startup.
-    Thanks to Andres Salomon for his initial idea for this startup hook.
+    Set a default mouse cursor on startup.
 
 * "XMonad.Hooks.SetWMName":
     Sets the WM name to a given string, so that it could be detected using
@@ -421,7 +426,8 @@ contributed tiling algorithms, such as a tabbed layout, a circle, a spiral,
 three columns, and so on.
 
 You will also find modules which provide facilities for combining
-different layouts, such as "XMonad.Layout.Combo", or
+different layouts, such as "XMonad.Layout.Combo", "XMonad.Layout.ComboP",
+"XMonad.Layout.LayoutBuilder", "XMonad.Layout.SubLayouts", or
 "XMonad.Layout.LayoutCombinators".
 
 Layouts can be also modified with layout modifiers. A general
@@ -457,7 +463,7 @@ For more information on using those modules for customizing your
     instead of center.
 
 * "XMonad.Layout.Circle":
-    Circle is an elliptical, overlapping layout, by Peter De Wachter
+    Circle is an elliptical, overlapping layout.
 
 * "XMonad.Layout.Column":
     Provides Column layout that places all windows in one column. Windows
@@ -490,7 +496,7 @@ For more information on using those modules for customizing your
     Layouts that splits the screen either horizontally or vertically and
     shows two windows.  The first window is always the master window, and
     the other is either the currently focused window or the second window in
-    layout order.
+    layout order. See also "XMonad.Layout.MouseResizableTall"
 
 * "XMonad.Layout.DwmStyle":
     A layout modifier for decorating windows in a dwm like style.
@@ -553,7 +559,7 @@ For more information on using those modules for customizing your
     functionality to other layouts.  If you ever find yourself writing
     a layout which takes another layout as a parameter, chances are you
     should be writing a LayoutModifier instead!
-   
+
     In case it is not clear, this module is not intended to help you
     configure xmonad, it is to help you write other extension modules.
     So get hacking!
@@ -625,7 +631,8 @@ For more information on using those modules for customizing your
     length of the window title.
 
 * "XMonad.Layout.OneBig":
-    Provides layout named OneBig. It places one (master) window at top left corner of screen, and other (slave) windows at top
+    Places one (master) window at top left corner of screen, and other (slave)
+    windows at the top.
 
 * "XMonad.Layout.PerWorkspace":
     Configure layouts on a per-workspace basis: use layouts and apply
@@ -636,6 +643,7 @@ For more information on using those modules for customizing your
 
 * "XMonad.Layout.ResizableTile":
     More useful tiled layout that allows you to change a width\/height of window.
+    See also "XMonad.Layout.MouseResizableTile".
 
 * "XMonad.Layout.ResizeScreen":
     A layout transformer to have a layout respect a given screen
@@ -658,7 +666,8 @@ For more information on using those modules for customizing your
     A basic floating layout.
 
 * "XMonad.Layout.Simplest":
-    A very simple layout. The simplest, afaik.
+    A very simple layout. The simplest, afaik. Used as a base for
+    decorated layouts.
 
 * "XMonad.Layout.SimplestFloat":
     A basic floating layout like SimpleFloat but without the decoration.
@@ -709,6 +718,7 @@ For more information on using those modules for customizing your
 
 * "XMonad.Layout.WindowNavigation":
     WindowNavigation is an extension to allow easy navigation of a workspace.
+    See also "XMonad.Actions.WindowNavigation".
 
 * "XMonad.Layout.WorkspaceDir":
     WorkspaceDir is an extension to set the current directory in a workspace.
@@ -843,7 +853,8 @@ A non complete list with a brief description:
     keybindings.
 
 * "XMonad.Util.NamedScratchpad":
-    Named scratchpads that support several arbitrary applications at the same time.
+    Like "XMonad.Util.Scratchpad" toggle windows to and from the current
+    workspace. Supports several arbitrary applications at the same time.
 
 * "XMonad.Util.NamedWindows":
     This module allows you to associate the X titles of windows with
@@ -863,7 +874,7 @@ A non complete list with a brief description:
     XMonad.Util.RunInXTerm (by Andrea Rossato).
 
 * "XMonad.Util.Scratchpad":
-    Very handy hotkey-launched floating terminal window.
+    Very handy hotkey-launched toggleable floating terminal window.
 
 * "XMonad.Util.StringProp":
     Internal utility functions for storing Strings with the root window.
@@ -921,7 +932,7 @@ example, you could write:
 
 and provide an appropriate definition of @myKeys@, such as:
 
->    myKeys x =
+> myKeys conf@(XConfig {XMonad.modMask = modm}) =
 >             [ ((modm, xK_F12), xmonadPrompt defaultXPConfig)
 >             , ((modm, xK_F3 ), shellPrompt  defaultXPConfig)
 >             ]
@@ -934,7 +945,7 @@ This particular definition also requires importing "XMonad.Prompt",
 
 For a list of the names of particular keys (such as xK_F12, and so
 on), see
-<http://hackage.haskell.org/packages/archive/X11/1.4.1/doc/html/Graphics-X11-Types.html>.
+<http://hackage.haskell.org/packages/archive/X11/latest/doc/html/Graphics-X11-Types.html>
 
 Usually, rather than completely redefining the key bindings, as we did
 above, we want to simply add some new bindings and\/or remove existing
@@ -945,8 +956,9 @@ ones.
 {- $keyAdding
 #Adding_key_bindings#
 
-Adding key bindings can be done in different ways. The type signature
-of 'XMonad.Core.XConfig.keys' is:
+Adding key bindings can be done in different ways. See the end of this
+section for the easiest ways. The type signature of
+'XMonad.Core.XConfig.keys' is:
 
 >    keys :: XConfig Layout -> M.Map (ButtonMask,KeySym) (X ())
 
@@ -965,7 +977,7 @@ module, before starting we must first import this modules:
 For instance, if you have defined some additional key bindings like
 these:
 
->    myKeys x =
+>    myKeys conf@(XConfig {XMonad.modMask = modm}) =
 >             [ ((modm, xK_F12), xmonadPrompt defaultXPConfig)
 >             , ((modm, xK_F3 ), shellPrompt  defaultXPConfig)
 >             ]
@@ -998,7 +1010,7 @@ All together, your @~\/.xmonad\/xmonad.hs@ would now look like this:
 >
 >    newKeys x = M.union (keys defaultConfig x) (M.fromList (myKeys x))
 >
->    myKeys x =
+>    myKeys conf@(XConfig {XMonad.modMask = modm}) =
 >             [ ((modm, xK_F12), xmonadPrompt defaultXPConfig)
 >             , ((modm, xK_F3 ), shellPrompt  defaultXPConfig)
 >             ]