diff options
| -rw-r--r-- | XMonad/Doc.hs | 90 | ||||
| -rw-r--r-- | XMonad/Doc/Configuring.hs | 159 | ||||
| -rw-r--r-- | XMonad/Doc/Developing.hs | 147 | ||||
| -rw-r--r-- | XMonad/Doc/Extending.hs (renamed from Documentation.hs) | 325 | ||||
| -rw-r--r-- | xmonad-contrib.cabal | 8 |
5 files changed, 432 insertions, 297 deletions
diff --git a/XMonad/Doc.hs b/XMonad/Doc.hs new file mode 100644 index 0000000..a77bb09 --- /dev/null +++ b/XMonad/Doc.hs @@ -0,0 +1,90 @@ +----------------------------------------------------------------------------- +-- | +-- Module : XMonad.Doc +-- Copyright : (C) 2007 Andrea Rossato +-- License : BSD3 +-- +-- Maintainer : andrea.rossato@unibz.it +-- Stability : unstable +-- Portability : portable +-- +-- This is the main documentation module for the xmonad-contrib +-- library. +-- +-- The module provides a brief overview of xmonad and a link to the +-- documentation for configuring and extending your xmonad window +-- manager. +-- +-- A link to the module describing xmonad internals is also provided. +-- This module is mainly dedicated to those wanting to contribute code +-- for this library and for the curious ones, who want to know what's +-- going on behind the scene. +----------------------------------------------------------------------------- + +module XMonad.Doc + ( + -- * Overview + -- $overview + + -- * Configuring xmonad + -- $configuring + module XMonad.Doc.Configuring, + + -- * Extending xmonad with the xmonad-contrib library + -- $extending + module XMonad.Doc.Extending, + + -- * Developing xmonad: an brief code commentary + -- $developing + module XMonad.Doc.Developing + + ) where + + +import XMonad.Doc.Configuring +import XMonad.Doc.Extending +import XMonad.Doc.Developing + +-------------------------------------------------------------------------------- +-- +-- Overview +-- +-------------------------------------------------------------------------------- + +{- $overview +#Overview# + +xmonad is a tiling window manager for X. This library collects third +party tiling algorithms, hooks, configurations and scripts to xmonad. +The source for this library is available via darcs get +<http://code.haskell.org/XMonadContrib> + +Each stable release of xmonad comes with a stable release of the +contrib library too, which should be used if you're using the stable +release. You can find the tarball here +(<http://www.xmonad.org/XMonadContrib-0.4.tar.gz>) (Oct 2007) + +-} + +{- $configuring + +This module is dedicated at configuring xmonad. A brief tutorial will +guide you through the basic configuration steps. + +-} + +{- $extending + +This module is dedicated at extending xmonad with the xmonad-contrib +library. You will find an overview of the library and instruction on +installing contributed extensions. + +-} + +{- $developing + +This module consists of a brief description of the xmonad internals. +It is mainly intended for contributors and basically provides a brief +code commentary with link to the source code documentation. + +-}
\ No newline at end of file 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". + +-} + diff --git a/XMonad/Doc/Developing.hs b/XMonad/Doc/Developing.hs new file mode 100644 index 0000000..e23ce79 --- /dev/null +++ b/XMonad/Doc/Developing.hs @@ -0,0 +1,147 @@ +----------------------------------------------------------------------------- +-- | +-- Module : Documentation +-- Copyright : (C) 2007 Andrea Rossato +-- License : BSD3 +-- +-- Maintainer : andrea.rossato@unibz.it +-- Stability : unstable +-- Portability : portable +-- +-- This module documents the xmonad internals. +-- +-- It is intended for the advanced users who are curious about the +-- xmonad code and want an brief overview of it. +-- +-- It may be useful also for those who would like to extend xmonad. If +-- you think your extension may be useful for other users too, you may +-- consider about releasing it. +-- +-- Coding guidelines and licencing policies must be followed if you +-- want your code to be included in the official repositories. +-- +----------------------------------------------------------------------------- + +module XMonad.Doc.Developing + ( + -- * Writing new extensions + -- $writing + + -- * Libraries for writing window managers + -- $xmonad-libs + + -- * xmonad internals + -- $internals + + -- ** The @main@ entry point + -- $main + + -- ** The X monad and the internal state + -- $internalState + + -- ** Event handling and messages + -- $events + + -- ** The 'LayoutClass' + -- $layoutClass + + -- * Coding style + -- $style + + -- * Licensing policy + -- $license + ) where + +-------------------------------------------------------------------------------- +-- +-- Writing Extensions +-- +-------------------------------------------------------------------------------- + +{- $writing + +Writing Other Extensions + +-} + +{- $xmonad-libs + +xmonad and xmonad-contrib are just libraries for letting users write +their own window managers. This is what makes xmonad such a powerful +and still simple application. + +Give some examples: +arossato_vm +droundy_wm + +In the previous sections we show how simple it can be to write your +own window manager by using the core code (xmonad) and some of the +contributed code (xmonad-contrib). + +In this section we will give you a brief overview of the programming +techniques that have been used in order to make writing new extensions +very simple. + +-} + +{- $internals + +TODO + +-} + +{- $main +#The_main_entry_point# + +TODO + +-} + +{- $internalState + +TODO + +-} + +{- $events + +TODO + +-} + +{- $layoutClass +#The_LayoutClass# +TODO + +-} + +{- $style + +These are the coding guidelines for contributing to xmonad and the +xmonad contributed extensions. + +* Comment every top level function (particularly exported funtions), and + provide a type signature. + +* Use Haddock syntax in the comments. + +* Follow the coding style of the other modules. + +* Code should be compilable with -Wall -Werror. There should be no warnings. + +* Partial functions should be avoided: the window manager should not + crash, so do not call 'error' or 'undefined' + +* Tabs are /illegal/. Use 4 spaces for indenting. + +* Any pure function added to the core should have QuickCheck properties + precisely defining its behaviour. + +-} + +{- $license + +New modules should identify the author, and be submitted under the +same license as xmonad (BSD3 license or freer). + +-} diff --git a/Documentation.hs b/XMonad/Doc/Extending.hs index 9aa0b05..dd0f4dd 100644 --- a/Documentation.hs +++ b/XMonad/Doc/Extending.hs @@ -1,6 +1,6 @@ ----------------------------------------------------------------------------- -- | --- Module : Documentation +-- Module : XMonad.Doc.Extending -- Copyright : (C) 2007 Andrea Rossato -- License : BSD3 -- @@ -8,30 +8,24 @@ -- Stability : unstable -- Portability : portable -- --- This is a module for documenting the xmonad-contrib library. +-- This is a module for documenting the xmonad-contrib library and +-- describing how to use it to extend xmonad capabilities. +-- +-- While it should not require a deep knowledge of Haskell. this +-- document is intended also for the more advanced users, which +-- requires a reference to some features of Haskell. Still we hope the +-- examples may be useful also for those users who do not Haskell and +-- do not want to start learning it. +-- +-- More configuration examples may be fond on the Haskell wiki at this +-- address: +-- +-- <http://haskell.org/haskellwiki/Xmonad/Config_archive> -- ----------------------------------------------------------------------------- -module Documentation +module XMonad.Doc.Extending ( - -- * Overview - -- $overview - - -- * Configuring xmonad - -- $configure - - -- ** A simple example - -- $example - - -- ** Checking whether your xmonad.hs is correct - -- $check - - -- ** Loading your configuration - -- $load - - -- ** Where are the defaults? - -- $where - -- * The xmonad-contrib library -- $library @@ -76,178 +70,10 @@ module Documentation -- ** The log hook and external status bars -- $logHook - - -- * Writing new extensions - -- $writing - - -- ** Libraries for writing window managers - -- $xmonad-libs - - -- ** xmonad internals - -- $internals - - -- *** The @main@ entry point - -- $main - - -- *** The X monad and the internal state - -- $internalState - - -- *** Event handling and messages - -- $events - - -- *** The 'LayoutClass' - -- $layoutClass - - -- ** Coding style - -- $style - - -- ** Licensing policy - -- $license ) where -------------------------------------------------------------------------------- -- --- Overview --- --------------------------------------------------------------------------------- - -{- $overview -#Overview# - -xmonad is a tiling window manager for X. This library collects -third party tiling algorithms, hooks, configurations and scripts to -xmonad. The source for this library is available via darcs get <http://code.haskell.org/XMonadContrib> - -Each stable release of xmonad comes with a stable release of the contrib -library too, which should be used if you're using the stable release. -You can find the tarball here (<http://www.xmonad.org/XMonadContrib-0.4.tar.gz>) (Oct 2007) --} - --------------------------------------------------------------------------------- --- --- 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". - --} - --------------------------------------------------------------------------------- --- -- The XmonadContrib Library -- -------------------------------------------------------------------------------- @@ -278,7 +104,7 @@ various functions that are usually intended to be bound to key combinations or mouse actions, in order to provide functionality beyond the standard keybindings provided by xmonad. -See "Documentation#Editing_key_bindings" for instructions on how to +See "XMonad.Doc.Extending#Editing_key_bindings" for instructions on how to edit your key bindings. * "XMonad.Actions.Commands": running internal xmonad actions @@ -361,7 +187,7 @@ most important hooks are: accordingly. For instance, we can configure xmonad to put windows belonging to a given application in the float layer, not to manage dock applications, or open them in a given workspace. See - "Documentation#Editing_the_manage_hook" for more information on + "XMonad.Doc.Extending#Editing_the_manage_hook" for more information on customizing the 'XMonad.Core.manageHook'. * 'XMonad.Core.logHook': this hook is called when the stack of windows @@ -370,7 +196,7 @@ most important hooks are: "XMonad.Hooks.DynamicLog" will produce a string (whose format can be configured) to be printed to the standard output. This can be used to display some information about the xmonad state in a Status Bar. - See "Documentation#The_log_hook_and_external_status_bars" for more + See "XMonad.Doc.Extending#The_log_hook_and_external_status_bars" for more information. -} @@ -390,7 +216,8 @@ interface for writing layout modifiers is implemented in "XMonad.Layout.LayoutModifier". For more information on using those modules for customizing your -'XMonad.Core.layoutHook' see "Documentation#Editing_the_layout_hook". +'XMonad.Core.layoutHook' see "XMonad.Doc.Extending#Editing_the_layout_hook". + -} @@ -421,7 +248,7 @@ These are the available prompts: * "XMonad.Prompt.XMonad" Usually a prompt is called by some key binding. See -"Documentation#Editing_key_bindings" on how to configure xmonad to use +"XMonad.Doc.Extending#Editing_key_bindings" on how to configure xmonad to use some prompts. The give examples include adding some prompts. -} @@ -438,7 +265,7 @@ external utilities. A non complete list with a brief description: * "XMonad.Util.CustomKeys" or "XMonad.Util.EZConfig" can be used to - configure key bindings (see "Documentation#Editing_key_bindings"); + configure key bindings (see "XMonad.Doc.Extending#Editing_key_bindings"); * "XMonad.Util.Dzen" "XMonad.Util.Dmenu" provide useful functions for running dzen as a xmonad status bar and dmenu as a program launcher; @@ -650,20 +477,22 @@ workspace's layout, xmonad will use the 'XMonad.Core.layoutHook' for reordering the visible windows on the visible workspace(s). Since different layouts may be attached to different workspaces, and -you can change them, xmonad needs to know which one to pick up, so, -the layoutHook may be thought as a stack, or even better a combination -of layouts. This also means an order, i.e. a list. +you can change them, xmonad needs to know which one to pick up. In +this sense the layoutHook may be thought as the combination, or the +list, of layouts that xmonad will use for ordering windows on the +screen(s) The problem is that the layout subsystem is implemented with an advanced feature of the Haskell programming language: type classes. This allows us to very easily write new layouts, combine or modify existing layouts, have some of them with a state, etc. See -"Documentation#The_LayoutClass" for more information. +"XMonad.Doc.Extending#The_LayoutClass" for more information. The price we have to pay to get all that for free - which is something that makes xmonad so powerful with such a ridiculously low number of lines - is that we cannot simply have a list of layouts as we used to -have before the 0.5 release. +have before the 0.5 release: a list requires every member to belong to +the same type! Instead the combination of layouts to be used by xmonad is created with a specific layout combinator: 'XMonad.Layouts.|||' @@ -701,7 +530,7 @@ may write: > mylayoutHook = Full ||| noBorders (tabbed shrinkText defaultTConf) ||| Accordion -The @~\/.xmonad\/xmonad.hs@ will now look like this: +Our @~\/.xmonad\/xmonad.hs@ will now look like this: > import XMonad.Layouts > @@ -729,97 +558,3 @@ TODO: Manage Hook TODO: Log Hook -} - --------------------------------------------------------------------------------- --- --- Writing Extensions --- --------------------------------------------------------------------------------- - -{- $writing - -Writing Other Extensions - --} - -{- $xmonad-libs - -xmonad and xmonad-contrib are just libraries for letting users write -their own window managers. This is what makes xmonad such a powerful -and still simple application. - -Give some examples: -arossato_vm -droundy_wm - -In the previous sections we show how simple it can be to write your -own window manager by using the core code (xmonad) and some of the -contributed code (xmonad-contrib). - -In this section we will give you a brief overview of the programming -techniques that have been used in order to make writing new extensions -very simple. - --} - -{- $internals - -TODO - --} - -{- $main -#The_main_entry_point# - -TODO - --} - -{- $internalState - -TODO - --} - -{- $events - -TODO - --} - -{- $layoutClass -#The_LayoutClass# -TODO - --} - -{- $style - -These are the coding guidelines for contributing to xmonad and the -xmonad contributed extensions. - -* Comment every top level function (particularly exported funtions), and - provide a type signature. - -* Use Haddock syntax in the comments. - -* Follow the coding style of the other modules. - -* Code should be compilable with -Wall -Werror. There should be no warnings. - -* Partial functions should be avoided: the window manager should not - crash, so do not call 'error' or 'undefined' - -* Tabs are /illegal/. Use 4 spaces for indenting. - -* Any pure function added to the core should have QuickCheck properties - precisely defining its behaviour. - --} - -{- $license - -New modules should identify the author, and be submitted under the -same license as xmonad (BSD3 license or freer). - --} diff --git a/xmonad-contrib.cabal b/xmonad-contrib.cabal index aa98b07..38c5af5 100644 --- a/xmonad-contrib.cabal +++ b/xmonad-contrib.cabal @@ -6,7 +6,8 @@ description: Third party tiling algorithms, configurations and scripts to xmonad, a tiling window manager for X. . - "Documentation" on building, configuring and using xmonad extensions. + Documentation on building, configuring and using xmonad + extensions: "XMonad.Doc" category: System license: BSD3 license-file: LICENSE @@ -36,7 +37,10 @@ library build-depends: mtl, unix, X11==1.3.0.20071111, xmonad==0.4 ghc-options: -Wall -Werror - exposed-modules: Documentation + exposed-modules: XMonad.Doc + XMonad.Doc.Configuring + XMonad.Doc.Extending + XMonad.Doc.Developing XMonad.Actions.Commands XMonad.Actions.ConstrainedResize XMonad.Actions.CopyWindow |