twin/xmonad-contrib
1
0
Fork 0
mirror of https://github.com/xmonad/xmonad-contrib.git synced 2025-05-19 03:20:21 -07:00
Code Issues Packages Projects Releases Wiki Activity

update documentation in XMonad/Doc in preparation for 0.7 release

Browse Source
This commit is contained in:
Brent Yorgey 2008-03-26 19:57:41 +00:00
parent 6ada04c415
commit f0e7b48bda
4 changed files with 165 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
XMonad/Doc.hs
View File

@ -28,7 +28,7 @@ module XMonad.Doc
-- * Extending xmonad with the xmonad-contrib library
-- $extending
-- * Developing xmonad: an brief code commentary
-- * Developing xmonad: a brief code commentary
-- $developing
) where
@ -56,8 +56,8 @@ is available from <http://code.haskell.org/XMonadContrib> via darcs:
Each stable release of xmonad is accompanied by a stable release of
the contrib library, which you should use if (and only if) you're
using a stable release of xmonad. You can find the most recent
(Oct. 2007) tarball here:
<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/xmonad-contrib-0.5>
(Mar. 2008) tarball here:
<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/xmonad-contrib-0.7>
-}

9
XMonad/Doc/Configuring.hs
View File

@ -91,7 +91,7 @@ describe values that differ from the defaults.
As an alternative, you can copy the template @xmonad.hs@ file (found
either in the @man@ directory, if you have the xmonad source, or on
the xmonad wiki at
@http:\/\/haskell.org\/haskellwiki\/Xmonad\/Config_archive\/Template_Config.hs@)
@http:\/\/haskell.org\/haskellwiki\/Xmonad\/Config_archive\/Template_xmonad.hs@)
into your @~\/.xmonad\/@ directory. This template file contains all
the default settings spelled out, and you should be able to simply
change the ones you would like to change.
@ -122,14 +122,17 @@ Ok, looks good.
Note, however, that if you skip this step and try restarting xmonad
with errors in your xmonad.hs, it's not the end of the world; xmonad
will simply display a window showing the errors and continue with the
previous configuration settings.
previous configuration settings. (This assumes that you have the
\'xmessage\' utility installed; you probably do.)
-}
{- $load
#Loading_your_configuration#
To get xmonad to use your new settings, type @mod-q@. xmonad will
To get xmonad to use your new settings, type @mod-q@. (Remember, the
mod key is \'alt\' by default, but you can configure it to be
something else, such as your Windows key if you have one.) 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

29
XMonad/Doc/Developing.hs
View File

@ -8,22 +8,25 @@
-- Stability : unstable
-- Portability : portable
--
-- This module documents the xmonad internals. It is intended for
-- advanced users who are curious about the xmonad source code and
-- want an brief overview. This document may also be helpful for the
-- beginner\/intermediate Haskell programmer who is motivated to write
-- an xmonad extension as a way to deepen her understanding of this
-- powerful functional language; however, there is not space here to
-- go into much detail. A more comprehensive document introducing
-- beginner\/intermediate Haskell programmers to the xmonad source is
-- planned for the xmonad users' wiki
-- (<http://haskell.org/haskellwiki/Xmonad>).
-- This module gives a brief overview of the xmonad internals. It is
-- intended for advanced users who are curious about the xmonad source
-- code and want an brief overview. This document may also be helpful
-- for the beginner\/intermediate Haskell programmer who is motivated
-- to write an xmonad extension as a way to deepen her understanding
-- of this powerful functional language; however, there is not space
-- here to go into much detail. For a more comprehensive document
-- covering some of the same material in more depth, see the guided
-- tour of the xmonad source on the xmonad wiki:
-- <http://haskell.org/haskellwiki/Xmonad/Guided_tour_of_the_xmonad_source>.
--
-- If you write an extension module and think it may be useful for
-- others, consider releasing it. Coding guidelines and licensing
-- policies are covered at the end of this document, and must be
-- followed if you want your code to be included in the official
-- repositories.
-- repositories. For a basic tutorial on the nuts and bolts of
-- developing a new extension for xmonad, see the tutorial on the
-- wiki:
-- <http://haskell.org/haskellwiki/Xmonad/xmonad_development_tutorial>.
--
-----------------------------------------------------------------------------
@ -285,6 +288,10 @@ and then point your browser to @\/path\/to\/XMonadContrib\/dist\/doc\/html\/xmon
For more information, see the Haddock documentation:
<http://www.haskell.org/haddock/haddock-html-0.8/index.html>.
For more information on the nuts and bolts of how to develop your own
extension, see the tutorial on the wiki:
<http://haskell.org/haskellwiki/Xmonad/xmonad_development_tutorial>.
-}
{- $license

175
XMonad/Doc/Extending.hs
View File

@ -125,14 +125,17 @@ edit your key bindings.
* "XMonad.Actions.CopyWindow": duplicating windows on multiple
workspaces.
* "XMonad.Actions.CycleWS": move between workspaces.
* "XMonad.Actions.CycleSelectedLayouts": bind a key to cycle through a
particular subset of your layouts.
* "XMonad.Actions.CycleWS": move between workspaces in various ways.
* "XMonad.Actions.DeManage": cease management of a window without
unmapping it.
* "XMonad.Actions.DwmPromote": dwm-like master window swapping.
* "XMonad.Actions.DynamicWorkspaces": add and delete workspaces.
* "XMonad.Actions.DynamicWorkspaces": add, delete, and rename workspaces.
* "XMonad.Actions.FindEmptyWorkspace": find an empty workspace.
@ -148,6 +151,19 @@ edit your key bindings.
* "XMonad.Actions.MouseGestures": bind mouse gestures to actions.
* "XMonad.Actions.MouseResize": use with
"XMonad.Layout.WindowArranger" to resize windows with the mouse when
using a floating layout.
* "XMonad.Actions.NoBorders": forcibly remove borders from a window.
Not to be confused with "XMonad.Layout.NoBorders".
* "XMonad.Actions.PerWorkspaceKeys": configure keybindings
per-workspace.
* "XMonad.Actions.Promote": An action to move the focused window to
the master pane, or swap the master with the next window.
* "XMonad.Actions.RotSlaves": rotate non-master windows.
* "XMonad.Actions.Search": provide helpful functions for easily
@ -165,12 +181,16 @@ edit your key bindings.
* "XMonad.Actions.TagWindows": tag windows and select by tag.
* "XMonad.Actions.UpdatePointer": mouse-follows-focus.
* "XMonad.Actions.Warp": warp the pointer.
* "XMonad.Actions.WindowBringer": bring windows to you, and you to
windows.
* "XMonad.Actions.WmiiActions": wmii-style actions.
* "XMonad.Actions.WindowGo": travel to windows based on various
criteria; conditionally start a program if a window does not exist,
or travel to that window if it does.
-}
@ -223,13 +243,19 @@ Here is a list of the modules found in @XMonad.Hooks@:
putting in a status bar of some sort. See
"XMonad.Doc.Extending#The_log_hook_and_external_status_bars".
* "XMonad.Hooks.EventHook": a hook to handle X events at the layout level.
* "XMonad.Hooks.EwmhDesktops": support for pagers in panel applications.
* "XMonad.Hooks.ManageDocks": handle DOCK and STRUT windows appropriately.
* "XMonad.Hooks.ManageDocks": handle DOCK and STRUT windows (such as
status bars) appropriately, by de-managing them and creating
appropriate gaps so as not to place other windows covering them.
* "XMonad.Hooks.ManageHelpers": provide helper functions to be used
in @manageHook@.
* "XMonad.Hooks.ServerMode": example use of "XMonad.Hooks.EventHook".
* "XMonad.Hooks.SetWMName": set the WM name. Useful when e.g. running
Java GUI programs.
@ -265,13 +291,24 @@ For more information on using those modules for customizing your
* "XMonad.Layout.Combo": combine multiple layouts into one.
* "XMonad.Layout.Decoration": decorated layouts.
* "XMonad.Layout.DecorationMadness": some examples of decorated layouts.
* "XMonad.Layout.Dishes": stack extra windows underneath the master windows.
* "XMonad.Layout.DragPane": split the screen into two windows with a
draggable divider.
* "XMonad.Layout.DwmStyle": windows decorated in a dwm-like style.
* "XMonad.Layout.Grid": put windows in a square grid.
* "XMonad.Layout.HintedTile": gapless tiled layout that attempts to
obey window size hints.
* "XMonad.Layout.IM": a layout for multi-window instant message clients.
* "XMonad.Layout.LayoutCombinators": general layout combining.
* "XMonad.Layout.LayoutHints": make layouts respect window size hints.
@ -289,9 +326,6 @@ For more information on using those modules for customizing your
* "XMonad.Layout.Maximize": temporarily maximize the focused window.
* "XMonad.Layout.Mosaic": tries to give each window a
user-configurable relative area
* "XMonad.Layout.MosaicAlt": give each window a specified relative
amount of screen space.
@ -305,29 +339,48 @@ For more information on using those modules for customizing your
* "XMonad.Layout.PerWorkspace": configure layouts on a per-workspace basis.
* "XMonad.Layout.Reflect": reflect any layout vertically or horizontally.
* "XMonad.Layout.ResizableTile": tiled layout allowing you to change
width and height of windows.
* "XMonad.Layout.ResizeScreen": a layout modifier to change the screen
geometry on one side.
* "XMonad.Layout.Roledex": a \"completely pointless layout which acts
like Microsoft's Flip 3D\".
* "XMonad.Layout.ScratchWorkspace": implements a scratch workspace
which can be shown and hidden with keybindings.
* "XMonad.Layout.ShowWName": Show the name of the current workspace when switching.
* "XMonad.Layout.SimpleDecoration": add simple decorations to windows.
* "XMonad.Layout.SimpleFloat": a basic floating layout.
* "XMonad.Layout.Simplest": a basic, simple layout that just lays out
all windows with a fullscreen geometry. Used by
"XMonad.Layout.Tabbed".
* "XMonad.Layout.Spiral": Fibonacci spiral layout.
* "XMonad.Layout.Square": split the screen into a square area plus the rest.
* "XMonad.Layout.TabBarDecoration": add a bar of tabs to any layout.
* "XMonad.Layout.Tabbed": a tabbed layout.
* "XMonad.Layout.ThreeColumns": a layout with three columns instead of two.
* "XMonad.Layout.TilePrime": fill gaps created by resize hints.
* "XMonad.Layout.ToggleLayouts": toggle between two layouts.
* "XMonad.Layout.TwoPane": split the screen horizontally and show two
windows.
* "XMonad.Layout.WindowArranger": make any layout into a
pseudo-floating layout by allowing you to move and resize windows.
* "XMonad.Layout.WindowNavigation": navigate around a workspace
directionally instead of using mod-j\/k.
@ -347,21 +400,38 @@ modules.
These are the available prompts:
* "XMonad.Prompt.Directory"
* "XMonad.Prompt.AppendFile": append lines of text to a file.
* "XMonad.Prompt.Layout"
* "XMonad.Prompt.Directory": prompt for a directory.
* "XMonad.Prompt.Man"
* "XMonad.Prompt.DirExec": put a bunch of scripts you want in a
directory, then choose from among them with this prompt.
* "XMonad.Prompt.Shell"
* "XMonad.Prompt.Email": an example of "XMonad.Prompt.Input", send
simple short e-mails from a prompt.
* "XMonad.Prompt.Ssh"
* "XMonad.Prompt.Input": useful for building general actions requiring
input from a prompt.
* "XMonad.Prompt.Window"
* "XMonad.Prompt.Layout": choose a layout from a prompt.
* "XMonad.Prompt.Workspace"
* "XMonad.Prompt.Man": open man pages.
* "XMonad.Prompt.XMonad"
* "XMonad.Prompt.RunOrRaise": choose a program, and run it if not
already running, or raise its window if it is.
* "XMonad.Prompt.Shell": run a shell command.
* "XMonad.Prompt.Ssh": open an ssh connection.
* "XMonad.Prompt.Theme": choose a decoration theme.
* "XMonad.Prompt.Window": choose an open window.
* "XMonad.Prompt.Workspace": choose a workspace.
* "XMonad.Prompt.XMonad": perform various xmonad actions by choosing
one from a prompt.
Usually a prompt is called by some key binding. See
"XMonad.Doc.Extending#Editing_key_bindings", which includes examples
@ -380,16 +450,46 @@ external utilities.
A non complete list with a brief description:
* "XMonad.Util.Anneal": The goal is to bring the system, from an
arbitrary initial state, to a state with the minimum possible
energy.
* "XMonad.Util.CustomKeys": configure key bindings (see
"XMonad.Doc.Extending#Editing_key_bindings").
* "XMonad.Util.CustomKeys" or "XMonad.Util.EZConfig" can be used to
configure key bindings (see "XMonad.Doc.Extending#Editing_key_bindings");
* "XMonad.Util.Dmenu": a dmenu binding.
* "XMonad.Util.Dzen" "XMonad.Util.Dmenu" provide useful functions for
running dzen as a xmonad status bar and dmenu as a program launcher;
* "XMonad.Util.EZConfig": configure key bindings easily, including a
parser for writing key bindings in "M-C-x" style.
* "XMonad.Util.Font": A module for abstracting a font facility over
Core fonts and Xft
* "XMonad.Util.Invisible": a wrapper data type to store layout state
which should not be persisted across restarts.
* "XMonad.Util.Loggers": a collection of loggers that can be used in
conjunction with "XMonad.Hooks.DynamicLog".
* "XMonad.Util.NamedWindows": associate windows with their X titles.
Used by, e.g. "XMonad.Layout.Tabbed".
* "XMonad.Util.Run": a collection of functions for running external
processes.
* "XMonad.Util.Scratchpad": hotkey-launched floating terminal window.
* "XMonad.Util.Themes": a collection of themes to be used with
floating layouts.
* "XMonad.Util.Timer": set up a timer to handle deferred events.
* "XMonad.Util.WindowProperties": an EDSL for specifying and matching
on window properties.
* "XMonad.Util.WorkspaceCompare": general combinators for sorting
workspaces in various ways, used by several other modules which need
to sort workspaces (e.g. "XMonad.Hooks.DynamicLog").
* "XMonad.Util.XSelection" provide utilities for using the mouse
selection;
@ -421,6 +521,8 @@ Editing key bindings means changing the 'XMonad.Core.XConfig.keys'
field of the 'XMonad.Core.XConfig' record used by xmonad. For
example, you could write:
> import XMonad
>
> main = xmonad $ defaultConfig { keys = myKeys }
and provide an appropriate definition of @myKeys@, such as:
@ -430,14 +532,14 @@ and provide an appropriate definition of @myKeys@, such as:
> , ((modMask x, xK_F3 ), shellPrompt defaultXPConfig)
> ]
This particular definition also requires importing "Graphics.X11.Xlib"
(for the symbols such as @xK_F12@), "XMonad.Prompt",
This particular definition also requires importing "XMonad.Prompt",
"XMonad.Prompt.Shell", and "XMonad.Prompt.XMonad":
> import Graphics.X11.Xlib
> import XMonadPrompt
> import ... -- and so on
For a list of the names of particular keys (such as xK_F12, and so on), see
For a list of the names of particular keys (such as xK_F12, and so
on), see
<http://hackage.haskell.org/packages/archive/X11/1.4.1/doc/html/Graphics-X11-Types.html>.
Usually, rather than completely redefining the key bindings, as we did
@ -507,17 +609,10 @@ All together, your @~\/.xmonad\/xmonad.hs@ would now look like this:
> , ((modMask x, xK_F3 ), shellPrompt defaultXPConfig)
> ]
There are other ways of defining @newKeys@; for instance,
you could define it like this:
> newKeys x = foldr (uncurry M.insert) (keys defaultConfig x) (myKeys x)
However, the simplest way to add new key bindings is to use some
utilities provided by the xmonad-contrib library. For instance,
"XMonad.Util.EZConfig" and "XMonad.Util.CustomKeys" both provide
useful functions for editing your key bindings. Look, for instance, at
'XMonad.Util.EZConfig.additionalKeys'.
There are much simpler ways to accomplish this, however, if you are
willing to use an extension module to help you configure your keys.
For instance, "XMonad.Util.EZConfig" and "XMonad.Util.CustomKeys" both
provide useful functions for editing your key bindings; "XMonad.Util.EZConfig" even lets you use emacs-style keybinding descriptions like \"M-C-<F12>\".
-}
@ -767,6 +862,9 @@ Where @property@ can be:
* 'XMonad.ManageHook.className': the resource class name.
* 'XMonad.ManageHook.stringProperty' @somestring@: the contents of the
property @somestring@.
(You can retrieve the needed information using the X utility named
@xprop@; for example, to find the resource class name, you can type
@ -839,6 +937,9 @@ of the corresponding actions will be run (in the order in which they
are defined). This is a change from versions before 0.5, when only
the first rule that matched was run.
Finally, for additional rules and actions you can use in your
manageHook, check out the contrib module "XMonad.Hooks.ManageHelpers".
-}
{- $logHook