aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAndrea Rossato <andrea.rossato@unibz.it>2007-11-16 11:48:27 +0100
committerAndrea Rossato <andrea.rossato@unibz.it>2007-11-16 11:48:27 +0100
commit677744eef0165886300d2f496f0b5773925337c4 (patch)
treebe4dee87dcf06e42328cff2d7f0188f97205cca0
parentb0d951ae83235f1c37513fbe514e42b66b9161b5 (diff)
downloadXMonadContrib-677744eef0165886300d2f496f0b5773925337c4.tar.gz
XMonadContrib-677744eef0165886300d2f496f0b5773925337c4.tar.xz
XMonadContrib-677744eef0165886300d2f496f0b5773925337c4.zip
Add Documentation.hs for documentation purposes
An empty module for documentation purpose with configuration instructions. darcs-hash:20071116104827-32816-366cb9be6b7204ce174a190fac64b493741a5d86.gz
-rw-r--r--Documentation.hs295
-rw-r--r--xmonad-contrib.cabal5
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