update documentation in XMonad/Doc in preparation for 0.7 release

darcs-hash:20080326195741-bd4d7-74a11c8d28951cf24caaf0e6102cad2fc40635d1.gz

4 files changed, 165 insertions, 54 deletions

diff --git a/XMonad/Doc.hs b/XMonad/Doc.hs
index 6ced181..eabb05e 100644
--- a/XMonad/Doc.hs
+++ b/XMonad/Doc.hs
@@ -28,7 +28,7 @@ module XMonad.Doc
     -- * Extending xmonad with the xmonad-contrib library
     -- $extending
 
-    -- * Developing xmonad: an brief code commentary
+    -- * Developing xmonad: a brief code commentary
     -- $developing
 
     ) where
@@ -56,8 +56,8 @@ is available from <http://code.haskell.org/XMonadContrib> via darcs:
 Each stable release of xmonad is accompanied by a stable release of
 the contrib library, which you should use if (and only if) you're
 using a stable release of xmonad.  You can find the most recent
-(Oct. 2007) tarball here:
-<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/xmonad-contrib-0.5>
+(Mar. 2008) tarball here:
+<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/xmonad-contrib-0.7>
 
 -}
 
diff --git a/XMonad/Doc/Configuring.hs b/XMonad/Doc/Configuring.hs
index 4af629e..9d682f8 100644
--- a/XMonad/Doc/Configuring.hs
+++ b/XMonad/Doc/Configuring.hs
@@ -91,7 +91,7 @@ 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_Config.hs@)
+@http:\/\/haskell.org\/haskellwiki\/Xmonad\/Config_archive\/Template_xmonad.hs@)
 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.
@@ -122,14 +122,17 @@ Ok, looks good.
 Note, however, that if you skip this step and try restarting xmonad
 with errors in your xmonad.hs, it's not the end of the world; xmonad
 will simply display a window showing the errors and continue with the
-previous configuration settings.
+previous configuration settings. (This assumes that you have the
+\'xmessage\' utility installed; you probably do.)
 
 -}
 
 {- $load
 #Loading_your_configuration#
 
-To get xmonad to use your new settings, type @mod-q@. xmonad will
+To get xmonad to use your new settings, type @mod-q@. (Remember, the
+mod key is \'alt\' by default, but you can configure it to be
+something else, such as your Windows key if you have one.) xmonad will
 attempt to compile this file, and run it.  If everything goes well,
 xmonad will seamlessly restart itself with the new settings, keeping
 all your windows, layouts, etc. intact.  (If you change anything
diff --git a/XMonad/Doc/Developing.hs b/XMonad/Doc/Developing.hs
index 91867ae..60796a8 100644
--- a/XMonad/Doc/Developing.hs
+++ b/XMonad/Doc/Developing.hs
@@ -8,22 +8,25 @@
 -- Stability   :  unstable
 -- Portability :  portable
 --
--- This module documents the xmonad internals. It is intended for
--- advanced users who are curious about the xmonad source code and
--- want an brief overview. This document may also be helpful for the
--- beginner\/intermediate Haskell programmer who is motivated to write
--- an xmonad extension as a way to deepen her understanding of this
--- powerful functional language; however, there is not space here to
--- go into much detail.  A more comprehensive document introducing
--- beginner\/intermediate Haskell programmers to the xmonad source is
--- planned for the xmonad users' wiki
--- (<http://haskell.org/haskellwiki/Xmonad>).
+-- This module gives a brief overview of the xmonad internals. It is
+-- intended for advanced users who are curious about the xmonad source
+-- code and want an brief overview. This document may also be helpful
+-- for the beginner\/intermediate Haskell programmer who is motivated
+-- to write an xmonad extension as a way to deepen her understanding
+-- of this powerful functional language; however, there is not space
+-- here to go into much detail.  For a more comprehensive document
+-- covering some of the same material in more depth, see the guided
+-- tour of the xmonad source on the xmonad wiki:
+-- <http://haskell.org/haskellwiki/Xmonad/Guided_tour_of_the_xmonad_source>.
 --
 -- If you write an extension module and think it may be useful for
 -- others, consider releasing it.  Coding guidelines and licensing
 -- policies are covered at the end of this document, and must be
 -- followed if you want your code to be included in the official
--- repositories.
+-- repositories.  For a basic tutorial on the nuts and bolts of
+-- developing a new extension for xmonad, see the tutorial on the
+-- wiki:
+-- <http://haskell.org/haskellwiki/Xmonad/xmonad_development_tutorial>.
 --
 -----------------------------------------------------------------------------
 
@@ -285,6 +288,10 @@ and then point your browser to @\/path\/to\/XMonadContrib\/dist\/doc\/html\/xmon
 For more information, see the Haddock documentation:
 <http://www.haskell.org/haddock/haddock-html-0.8/index.html>.
 
+For more information on the nuts and bolts of how to develop your own
+extension, see the tutorial on the wiki:
+<http://haskell.org/haskellwiki/Xmonad/xmonad_development_tutorial>.
+
 -}
 
 {- $license
diff --git a/XMonad/Doc/Extending.hs b/XMonad/Doc/Extending.hs
index d0537fc..244ec43 100644
--- a/XMonad/Doc/Extending.hs
+++ b/XMonad/Doc/Extending.hs
@@ -125,14 +125,17 @@ edit your key bindings.
 * "XMonad.Actions.CopyWindow": duplicating windows on multiple
   workspaces.
 
-* "XMonad.Actions.CycleWS": move between workspaces.
+* "XMonad.Actions.CycleSelectedLayouts": bind a key to cycle through a
+  particular subset of your layouts.
+
+* "XMonad.Actions.CycleWS": move between workspaces in various ways.
 
 * "XMonad.Actions.DeManage": cease management of a window without
   unmapping it.
 
 * "XMonad.Actions.DwmPromote": dwm-like master window swapping.
 
-* "XMonad.Actions.DynamicWorkspaces": add and delete workspaces.
+* "XMonad.Actions.DynamicWorkspaces": add, delete, and rename workspaces.
 
 * "XMonad.Actions.FindEmptyWorkspace": find an empty workspace.
 
@@ -148,6 +151,19 @@ edit your key bindings.
 
 * "XMonad.Actions.MouseGestures": bind mouse gestures to actions.
 
+* "XMonad.Actions.MouseResize": use with
+  "XMonad.Layout.WindowArranger" to resize windows with the mouse when
+  using a floating layout.
+
+* "XMonad.Actions.NoBorders": forcibly remove borders from a window.
+  Not to be confused with "XMonad.Layout.NoBorders".
+
+* "XMonad.Actions.PerWorkspaceKeys": configure keybindings
+  per-workspace.
+
+* "XMonad.Actions.Promote": An action to move the focused window to
+  the master pane, or swap the master with the next window.
+
 * "XMonad.Actions.RotSlaves": rotate non-master windows.
 
 * "XMonad.Actions.Search": provide helpful functions for easily
@@ -165,12 +181,16 @@ edit your key bindings.
 
 * "XMonad.Actions.TagWindows": tag windows and select by tag.
 
+* "XMonad.Actions.UpdatePointer": mouse-follows-focus.
+
 * "XMonad.Actions.Warp": warp the pointer.
 
 * "XMonad.Actions.WindowBringer": bring windows to you, and you to
   windows.
 
-* "XMonad.Actions.WmiiActions": wmii-style actions.
+* "XMonad.Actions.WindowGo": travel to windows based on various
+  criteria; conditionally start a program if a window does not exist,
+  or travel to that window if it does.
 
 -}
 
@@ -223,13 +243,19 @@ Here is a list of the modules found in @XMonad.Hooks@:
   putting in a status bar of some sort. See
   "XMonad.Doc.Extending#The_log_hook_and_external_status_bars".
 
+* "XMonad.Hooks.EventHook": a hook to handle X events at the layout level.
+
 * "XMonad.Hooks.EwmhDesktops": support for pagers in panel applications.
 
-* "XMonad.Hooks.ManageDocks": handle DOCK and STRUT windows appropriately.
+* "XMonad.Hooks.ManageDocks": handle DOCK and STRUT windows (such as
+  status bars) appropriately, by de-managing them and creating
+  appropriate gaps so as not to place other windows covering them.
 
 * "XMonad.Hooks.ManageHelpers": provide helper functions to be used
   in @manageHook@.
 
+* "XMonad.Hooks.ServerMode": example use of "XMonad.Hooks.EventHook".
+
 * "XMonad.Hooks.SetWMName": set the WM name.  Useful when e.g. running
   Java GUI programs.
 
@@ -265,13 +291,24 @@ For more information on using those modules for customizing your
 
 * "XMonad.Layout.Combo": combine multiple layouts into one.
 
+* "XMonad.Layout.Decoration": decorated layouts.
+
+* "XMonad.Layout.DecorationMadness": some examples of decorated layouts.
+
 * "XMonad.Layout.Dishes": stack extra windows underneath the master windows.
 
 * "XMonad.Layout.DragPane": split the screen into two windows with a
   draggable divider.
 
+* "XMonad.Layout.DwmStyle": windows decorated in a dwm-like style.
+
 * "XMonad.Layout.Grid": put windows in a square grid.
 
+* "XMonad.Layout.HintedTile": gapless tiled layout that attempts to
+  obey window size hints.
+
+* "XMonad.Layout.IM": a layout for multi-window instant message clients.
+
 * "XMonad.Layout.LayoutCombinators": general layout combining.
 
 * "XMonad.Layout.LayoutHints": make layouts respect window size hints.
@@ -289,9 +326,6 @@ For more information on using those modules for customizing your
 
 * "XMonad.Layout.Maximize": temporarily maximize the focused window.
 
-* "XMonad.Layout.Mosaic": tries to give each window a
-  user-configurable relative area
-
 * "XMonad.Layout.MosaicAlt": give each window a specified relative
   amount of screen space.
 
@@ -305,29 +339,48 @@ For more information on using those modules for customizing your
 
 * "XMonad.Layout.PerWorkspace": configure layouts on a per-workspace basis.
 
+* "XMonad.Layout.Reflect": reflect any layout vertically or horizontally.
+
 * "XMonad.Layout.ResizableTile": tiled layout allowing you to change
   width and height of windows.
 
+* "XMonad.Layout.ResizeScreen": a layout modifier to change the screen
+  geometry on one side.
+
 * "XMonad.Layout.Roledex": a \"completely pointless layout which acts
   like Microsoft's Flip 3D\".
 
+* "XMonad.Layout.ScratchWorkspace": implements a scratch workspace
+  which can be shown and hidden with keybindings.
+
 * "XMonad.Layout.ShowWName": Show the name of the current workspace when switching.
 
+* "XMonad.Layout.SimpleDecoration": add simple decorations to windows.
+
+* "XMonad.Layout.SimpleFloat": a basic floating layout.
+
+* "XMonad.Layout.Simplest": a basic, simple layout that just lays out
+  all windows with a fullscreen geometry.  Used by
+  "XMonad.Layout.Tabbed".
+
 * "XMonad.Layout.Spiral": Fibonacci spiral layout.
 
 * "XMonad.Layout.Square": split the screen into a square area plus the rest.
 
+* "XMonad.Layout.TabBarDecoration": add a bar of tabs to any layout.
+
 * "XMonad.Layout.Tabbed": a tabbed layout.
 
 * "XMonad.Layout.ThreeColumns": a layout with three columns instead of two.
 
-* "XMonad.Layout.TilePrime": fill gaps created by resize hints.
-
 * "XMonad.Layout.ToggleLayouts": toggle between two layouts.
 
 * "XMonad.Layout.TwoPane": split the screen horizontally and show two
   windows.
 
+* "XMonad.Layout.WindowArranger": make any layout into a
+  pseudo-floating layout by allowing you to move and resize windows.
+
 * "XMonad.Layout.WindowNavigation": navigate around a workspace
   directionally instead of using mod-j\/k.
 
@@ -347,21 +400,38 @@ modules.
 
 These are the available prompts:
 
-* "XMonad.Prompt.Directory"
+* "XMonad.Prompt.AppendFile": append lines of text to a file.
+
+* "XMonad.Prompt.Directory": prompt for a directory.
 
-* "XMonad.Prompt.Layout"
+* "XMonad.Prompt.DirExec": put a bunch of scripts you want in a
+  directory, then choose from among them with this prompt.
 
-* "XMonad.Prompt.Man"
+* "XMonad.Prompt.Email": an example of "XMonad.Prompt.Input", send
+  simple short e-mails from a prompt.
 
-* "XMonad.Prompt.Shell"
+* "XMonad.Prompt.Input": useful for building general actions requiring
+  input from a prompt.
 
-* "XMonad.Prompt.Ssh"
+* "XMonad.Prompt.Layout": choose a layout from a prompt.
 
-* "XMonad.Prompt.Window"
+* "XMonad.Prompt.Man": open man pages.
 
-* "XMonad.Prompt.Workspace"
+* "XMonad.Prompt.RunOrRaise": choose a program, and run it if not
+  already running, or raise its window if it is.
 
-* "XMonad.Prompt.XMonad"
+* "XMonad.Prompt.Shell": run a shell command.
+
+* "XMonad.Prompt.Ssh": open an ssh connection.
+
+* "XMonad.Prompt.Theme": choose a decoration theme.
+
+* "XMonad.Prompt.Window": choose an open window.
+
+* "XMonad.Prompt.Workspace": choose a workspace.
+
+* "XMonad.Prompt.XMonad": perform various xmonad actions by choosing
+  one from a prompt.
 
 Usually a prompt is called by some key binding. See
 "XMonad.Doc.Extending#Editing_key_bindings", which includes examples
@@ -380,16 +450,46 @@ external utilities.
 
 A non complete list with a brief description:
 
-* "XMonad.Util.Anneal": The goal is to bring the system, from an
-  arbitrary initial state, to a state with the minimum possible
-  energy.
+* "XMonad.Util.CustomKeys": configure key bindings (see
+  "XMonad.Doc.Extending#Editing_key_bindings").
 
-* "XMonad.Util.CustomKeys" or "XMonad.Util.EZConfig" can be used to
-  configure key bindings (see "XMonad.Doc.Extending#Editing_key_bindings");
+* "XMonad.Util.Dmenu": a dmenu binding.
 
 * "XMonad.Util.Dzen" "XMonad.Util.Dmenu" provide useful functions for
   running dzen as a xmonad status bar and dmenu as a program launcher;
 
+* "XMonad.Util.EZConfig": configure key bindings easily, including a
+  parser for writing key bindings in "M-C-x" style.
+
+* "XMonad.Util.Font": A module for abstracting a font facility over
+  Core fonts and Xft
+
+* "XMonad.Util.Invisible": a wrapper data type to store layout state
+  which should not be persisted across restarts.
+
+* "XMonad.Util.Loggers": a collection of loggers that can be used in
+  conjunction with "XMonad.Hooks.DynamicLog".
+
+* "XMonad.Util.NamedWindows": associate windows with their X titles.
+  Used by, e.g. "XMonad.Layout.Tabbed".
+
+* "XMonad.Util.Run": a collection of functions for running external
+  processes.
+
+* "XMonad.Util.Scratchpad": hotkey-launched floating terminal window.
+
+* "XMonad.Util.Themes": a collection of themes to be used with
+  floating layouts.
+
+* "XMonad.Util.Timer": set up a timer to handle deferred events.
+
+* "XMonad.Util.WindowProperties": an EDSL for specifying and matching
+  on window properties.
+
+* "XMonad.Util.WorkspaceCompare": general combinators for sorting
+  workspaces in various ways, used by several other modules which need
+  to sort workspaces (e.g. "XMonad.Hooks.DynamicLog").
+
 * "XMonad.Util.XSelection" provide utilities for using the mouse
   selection;
 
@@ -421,6 +521,8 @@ Editing key bindings means changing the 'XMonad.Core.XConfig.keys'
 field of the 'XMonad.Core.XConfig' record used by xmonad.  For
 example, you could write:
 
+>    import XMonad
+>
 >    main = xmonad $ defaultConfig { keys = myKeys }
 
 and provide an appropriate definition of @myKeys@, such as:
@@ -430,14 +532,14 @@ and provide an appropriate definition of @myKeys@, such as:
 >             , ((modMask x, xK_F3 ), shellPrompt  defaultXPConfig)
 >             ]
 
-This particular definition also requires importing "Graphics.X11.Xlib"
-(for the symbols such as @xK_F12@), "XMonad.Prompt",
+This particular definition also requires importing "XMonad.Prompt",
 "XMonad.Prompt.Shell", and "XMonad.Prompt.XMonad":
 
-> import Graphics.X11.Xlib
+> import XMonadPrompt
 > import ...  -- and so on
 
-For a list of the names of particular keys (such as xK_F12, and so on), see
+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>.
 
 Usually, rather than completely redefining the key bindings, as we did
@@ -507,17 +609,10 @@ All together, your @~\/.xmonad\/xmonad.hs@ would now look like this:
 >             , ((modMask x, xK_F3 ), shellPrompt  defaultXPConfig)
 >             ]
 
-
-There are other ways of defining @newKeys@; for instance,
-you could define it like this:
-
->    newKeys x = foldr (uncurry M.insert) (keys defaultConfig x) (myKeys x)
-
-However, the simplest way to add new key bindings is to use some
-utilities provided by the xmonad-contrib library.  For instance,
-"XMonad.Util.EZConfig" and "XMonad.Util.CustomKeys" both provide
-useful functions for editing your key bindings.  Look, for instance, at
-'XMonad.Util.EZConfig.additionalKeys'.
+There are much simpler ways to accomplish this, however, if you are
+willing to use an extension module to help you configure your keys.
+For instance, "XMonad.Util.EZConfig" and "XMonad.Util.CustomKeys" both
+provide useful functions for editing your key bindings; "XMonad.Util.EZConfig" even lets you use emacs-style keybinding descriptions like \"M-C-<F12>\".
 
  -}
 
@@ -767,6 +862,9 @@ Where @property@ can be:
 
 * 'XMonad.ManageHook.className': the resource class name.
 
+* 'XMonad.ManageHook.stringProperty' @somestring@: the contents of the
+  property @somestring@.
+
 (You can retrieve the needed information using the X utility named
 @xprop@; for example, to find the resource class name, you can type
 
@@ -839,6 +937,9 @@ of the corresponding actions will be run (in the order in which they
 are defined).  This is a change from versions before 0.5, when only
 the first rule that matched was run.
 
+Finally, for additional rules and actions you can use in your
+manageHook, check out the contrib module "XMonad.Hooks.ManageHelpers".
+
 -}
 
 {- $logHook