Add Documentation.hs for documentation purposes

An empty module for documentation purpose with configuration
instructions.

darcs-hash:20071116104827-32816-366cb9be6b7204ce174a190fac64b493741a5d86.gz

2 files changed, 299 insertions, 1 deletions

diff --git a/Documentation.hs b/Documentation.hs
new file mode 100644
index 0000000..8723ed0
--- /dev/null
+++ b/Documentation.hs
@@ -0,0 +1,295 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module      :  Documentation
+-- Copyright   :  (C) 2007 Andrea Rossato
+-- License     :  BSD3
+--
+-- Maintainer  :  andrea.rossato@unibz.it
+-- Stability   :  unstable
+-- Portability :  unportable
+--
+-- This is a module for documenting the xmonad-contrib library
+--
+-----------------------------------------------------------------------------
+
+module Documentation
+    ( 
+    -- * Configuring XMonad: A Quick Start 
+    -- $configure
+      
+    -- ** A simple example
+    -- $example
+    
+    -- ** Checking your xmonad.hs is correct
+    -- $check
+    
+    -- ** Loading your configuration
+    -- $load
+    
+    -- ** Where are the defaults?
+    -- $where
+    
+    -- * The XmonadContrib Library
+    -- $library
+    
+    -- * Extending XMonad
+    -- $extending
+    
+    -- ** Editing Key Bindings
+    -- $keys
+
+    -- *** Adding Key Bindings
+    -- $keyAdding
+
+    -- *** Removing Key Bindings
+    -- $keyDel
+
+    -- *** Adding and Removing Key Bindings
+    -- $keyAddDel
+
+
+    -- ** Adding\/Removing Layouts
+    -- $layout
+
+    -- ** Hooks Management
+    -- $hooks
+
+    -- * Writing Other Extensions
+    -- $writing
+    ) where
+
+--------------------------------------------------------------------------------
+--
+--  Configuring Xmonad
+--
+--------------------------------------------------------------------------------
+
+{- $configure
+
+xmonad is configure by creating and editing the Haskell file:
+
+>    ~/.xmonad/xmonad.hs
+
+xmonad then uses default settings from this file as arguments to the
+window manager.
+
+-}
+
+{- $example
+
+Here is a basic example, which takes defaults from xmonad, and overrides 
+the border width, default terminal, and some colours:
+
+>    --
+>    -- An example, simple ~/.xmonad/xmonad.hs file.
+>    -- It overrides a few basic settings, reusing all the other defaults,
+>    -- 
+>
+>    import XMonad
+>
+>    main = xmonad $ defaultConfig
+>        { borderWidth        = 2
+>        , terminal           = "urxvt"
+>        , normalBorderColor  = "#cccccc"
+>        , focusedBorderColor = "#cd8b00" }
+
+This will run \'xmonad\', the window manager, with your settings passed as
+arguments.
+
+Overriding default settings like this (using \"record update syntax\"),
+will yield the shortest config file, as you only have to describe values
+that differ from the defaults.
+
+An alternative is to inline the entire default config file from xmonad,
+and edit values you wish to change. This is requires more work, but some
+users may find this easier. You can find the defaults in the file:
+
+>    XMonad/Config.hs
+
+-}
+
+{- $check
+
+Place this text in @~/.xmonad/xmonad.hs@, and then check that it is
+syntactically and type correct, by loading it in the Haskell
+interpreter:
+
+>    $ ghci ~/.xmonad/xmonad.hs  
+>    GHCi, version 6.8.1: http://www.haskell.org/ghc/  :? for help
+>    Loading package base ... linking ... done.
+>    Ok, modules loaded: Main.
+>
+>    Prelude Main> :t main
+>    main :: IO ()
+
+Ok, looks good.  
+
+-}
+
+{- $load
+
+To have xmonad start using your settings, try @mod-q@. xmonad will
+attempt to compile this file, and run it. If it is unable to, the
+defaults are used. This requires GHC and xmonad are in your @$PATH@
+settings. If GHC isn't in your path, you can still compile the
+@xmonad.hs@ file yourself:
+
+>    $ cd ~/.xmonad
+>    $ ghc --make xmonad.hs
+>    $ ls
+>    xmonad    xmonad.hi xmonad.hs xmonad.o
+
+When you hit @mod-q@, this newly compiled xmonad will be used.
+
+-}
+
+{- $where
+
+The default configuration values are defined in the source file:
+
+>   XMonad/Config.hs 
+
+the 'XMonad.Core.XConfig' data structure itself is defined in:
+
+>    XMonad/Core.hs
+
+See "XMonad.Core".
+-}
+
+--------------------------------------------------------------------------------
+--
+--  The XmonadContrib Library
+--
+--------------------------------------------------------------------------------
+
+{- $library
+
+Put here an overview of the library with a description of the various
+directories: Actions, Config, Hooks, Layout, Prompt, and Util.
+
+-}
+
+--------------------------------------------------------------------------------
+--
+--  Extending Xmonad
+--
+--------------------------------------------------------------------------------
+
+{- $extending
+
+Extending XMonad
+
+Since the @xmonad.hs@ file is just another Haskell module, you may
+import and use any Haskell code or libraries you wish, such as
+extensions from the xmonad-contrib library, or other code you write
+yourself.
+
+-}
+
+{- $keys
+
+Editing key bindings means changing the 'XMonad.Core.XConfig.keys'
+record of the 'XMonad.Core.XConfig' data type, like:
+
+>    main = xmonad defaultConfig { keys = myKeys }
+
+and by providing a proper definition of @myKeys@ such as:
+
+>       myKeys x   = 
+>          [ ((modMask x              , xK_F12   ), xmonadPrompt      defaultXPConfig    )
+>          , ((modMask x              , xK_F3    ), shellPrompt       defaultXPConfig    )
+>          ]
+
+Remember that this definition requires importing "Graphics.X11.Xlib",
+"XMonad.Prompt", "XMonad.Prompt.Shell", and "XMonad.Prompt.XMonad"
+
+-}
+
+{- $keyAdding
+
+Adding key bindings can be done in different ways. The type signature
+of "XMonad.Core.XConfig.keys" is:
+
+> keys :: XConfig Layout -> M.Map (ButtonMask,KeySym) (X ())
+
+which means you need to use 'Data.Map.insert' in order to add some
+bindings to the map of the existing key bindings.
+
+For instance, if you have defined some additional key bindings like
+these:
+
+>       myKeys x   = 
+>          [ ((modMask x              , xK_F12   ), xmonadPrompt      defaultXPConfig    )
+>          , ((modMask x              , xK_F3    ), shellPrompt       defaultXPConfig    )
+>          ]
+
+you may wish to edit accordingly the default configuration
+'XMonad.Core.XConfig.keys' record:
+
+>    main = xmonad defaultConfig { keys = newKeys }
+>           where newKeys x  = foldr (uncurry Data.Map.insert) (keys defaultKeys) (myKeys x)
+
+And that's it.
+
+At the end you @~\/.xmonad\/xmonad.hs@ would look like this:
+
+
+> module Main (main) where
+> 
+> import XMonad
+> 
+> import qualified Data.Map as M
+> import Graphics.X11.Xlib
+> import XMonad.Prompt
+> import XMonad.Prompt.Shell
+> import XMonad.Prompt.XMonad
+>
+> main :: IO ()
+> main = xmonad defaultConfig { keys = newKeys }
+>        where newKeys x  = foldr (uncurry M.insert) (keys defaultConfig x) (myKeys x)
+>
+> myKeys x   =
+>         [ ((modMask x              , xK_F12   ), xmonadPrompt      defaultXPConfig    )
+>         , ((modMask x              , xK_F3    ), shellPrompt       defaultXPConfig    )
+>          ]                                                                             
+
+
+Alternatively you may wish to use some of the utilities provided by
+the xmonad-contrib library.
+
+For instance, "XMonad.Util.EZConfig" and "XMonad.Util.CustomKeys"
+provide useful function to edit you key bindings.
+
+ -}
+
+{- $keyDel
+
+keyDel
+-}
+
+{- $keyAddDel
+
+keyAddDel
+
+-}
+
+{- $layout
+
+layouts
+-}
+
+{- $hooks
+
+-}
+
+--------------------------------------------------------------------------------
+--
+--  Writing Extensions
+--
+--------------------------------------------------------------------------------
+
+{- $writing
+
+Writing Other Extensions
+
+-}
\ No newline at end of file
diff --git a/xmonad-contrib.cabal b/xmonad-contrib.cabal
index 056cf5e..1d7ab29 100644
--- a/xmonad-contrib.cabal
+++ b/xmonad-contrib.cabal
@@ -4,6 +4,8 @@ homepage:           http://xmonad.org/
 synopsis:           Third party extensions for xmonad
 description:
     Third party tiling algorithms, configurations and scripts to xmonad.
+    .
+    As a starting point you can have a look at the "Documentation".
 category:           System
 license:            BSD3
 license-file:       LICENSE
@@ -26,7 +28,8 @@ library
 
     build-depends:      mtl, unix, X11==1.3.0.20071111, xmonad==0.4
     ghc-options:        -Wall -Werror
-    exposed-modules:    XMonad.Actions.Commands
+    exposed-modules:    Documentation
+                        XMonad.Actions.Commands
                         XMonad.Actions.ConstrainedResize
                         XMonad.Actions.CopyWindow
                         XMonad.Actions.CycleWS