-----------------------------------------------------------------------------
-- |
-- 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
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 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 defaultConfig x) (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 functions to edit you key bindings.
-}
{- $keyDel
keyDel
-}
{- $keyAddDel
keyAddDel
-}
{- $layout
layouts
-}
{- $hooks
-}
--------------------------------------------------------------------------------
--
-- Writing Extensions
--
--------------------------------------------------------------------------------
{- $writing
Writing Other Extensions
-}
