diff options
Diffstat (limited to 'XMonad/Doc/Configuring.hs')
| -rw-r--r-- | XMonad/Doc/Configuring.hs | 159 |
1 files changed, 159 insertions, 0 deletions
diff --git a/XMonad/Doc/Configuring.hs b/XMonad/Doc/Configuring.hs new file mode 100644 index 0000000..f790195 --- /dev/null +++ b/XMonad/Doc/Configuring.hs @@ -0,0 +1,159 @@ +----------------------------------------------------------------------------- +-- | +-- Module : XMonad.Doc.Configuring +-- Copyright : (C) 2007 Don Stewart and Andrea Rossato +-- License : BSD3 +-- +-- Maintainer : andrea.rossato@unibz.it +-- Stability : unstable +-- Portability : portable +-- +-- This is a brief tutorial that will teach you how to quickly write a +-- basic and simple xmonad configuration and cutomization. +-- +-- For more detailed instructions on extending xmonad with the +-- xmonad-contrib library see "XMonad.Doc.Extending" +-- +----------------------------------------------------------------------------- + +module XMonad.Doc.Configuring + ( + -- * Configuring xmonad + -- $configure + + -- * A simple example + -- $example + + -- * Checking whether your xmonad.hs is correct + -- $check + + -- * Loading your configuration + -- $load + + -- * Where are the defaults? + -- $where + ) where + +-------------------------------------------------------------------------------- +-- +-- Configuring Xmonad +-- +-------------------------------------------------------------------------------- + +{- $configure +#Configuring_xmonad# +xmonad can be configured by creating and editing the Haskell file: + +> ~/.xmonad/xmonad.hs + +If this file does not exist, xmonad will simply use default settings; +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, 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. + +-} + +{- $example +#A_simple_example# + +Here is a basic example, which starts with the default xmonad +configuration 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 + +However, note that you should not edit Config.hs itself. + +-} + +{- $check +#Checking_whether_your_xmonad.hs_is_correct# + +After changing your configuration, it is a good idea to check that it +is syntactically and type correct. You can do this easily by loading +your configuration file 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 +#Loading_your_configuration# + +To get xmonad to use your new settings, type @mod-q@. 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 +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@. If GHC isn't in your path, you can +still compile @xmonad.hs@ yourself: + +> $ cd ~/.xmonad +> $ /path/to/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 +#Where_are_the_defaults?# + +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". + +-} + |