<commit_before>{-# LANGUAGE CPP #-}
-- We need to link to the current version of xmonad-docs, but both
-- CURRENT_PACKAGE_VERSION and VERSION_xmonad_contrib contain quotation marks
-- that we can't get rid of using CPP, so as a workaround we define the
-- components separately in cpp-options and check that they're still in sync.
#if !__HLINT__ && \
    !( MIN_VERSION_xmonad_contrib(XMONAD_CONTRIB_VERSION_MAJOR, XMONAD_CONTRIB_VERSION_MINOR, XMONAD_CONTRIB_VERSION_PATCH) \
    && !MIN_VERSION_xmonad_contrib(XMONAD_CONTRIB_VERSION_MAJOR, XMONAD_CONTRIB_VERSION_MINOR, XMONAD_CONTRIB_VERSION_PATCH + 1) \
    )
#error "Please update XMONAD_CONTRIB_VERSION_* in xmonad-contrib.cabal"
#endif

-----------------------------------------------------------------------------
-- |
-- Module      :  XMonad.Doc.Extending
-- Description :  A module to document the xmonad-contrib library.
-- Copyright   :  (C) 2007 <NAME>
-- License     :  BSD3
--
-- Maintainer  :  <EMAIL>
-- Stability   :  unstable
-- Portability :  portable
--
-- This module documents the xmonad-contrib library and guides you
-- through some more advanced parts of extending the capabilities of
-- xmonad.  If you're new to xmonad, you should first check out the
-- <https://xmonad.org/TUTORIAL.html tutorial> and treat this document
-- as supplemental reading.
--
-- Knowing Haskell is by no means a prerequisite for configuring xmonad
-- and the tutorial emphasizes this.  This document, however, does
-- assume a basic familiarity with the language.  This is so that we can
-- dive a bit deeper into what the different hooks do, or how to write
-- our own little functions to configure xmonad.
--
-- Those wishing to be totally hardcore and develop their own xmonad
-- extensions (it's easier than it sounds, we promise!) should read the
-- documentation in "XMonad.Doc.Developing".
--
-- More configuration examples can be found
-- <https://xmonad.org/TUTORIAL.html#closing-thoughts here>.
--
-----------------------------------------------------------------------------

module XMonad.Doc.Extending
    (
    -- * The xmonad-contrib library
    -- $library

    -- ** Actions
    -- $actions

    -- ** Hooks
    -- $hooks

    -- ** Layouts
    -- $layouts

    -- ** Prompts
    -- $prompts

    -- ** Utilities
    -- $utils

    -- * Extending xmonad
    -- $extending

    -- ** Adding key bindings
    -- $keys

    -- *** Removing key bindings
    -- $keyDel

    -- *** Adding and removing key bindings
    -- $keyAddDel

    -- ** Editing mouse bindings
    -- $mouse

    -- ** Editing the layout hook
    -- $layoutHook

    -- ** Editing the manage hook
    -- $manageHook

    -- ** The log hook and external status bars
    -- $logHook
    ) where

--------------------------------------------------------------------------------
--
--  The XmonadContrib Library
--
--------------------------------------------------------------------------------

{- $library

The xmonad-contrib library is a set of extension modules contributed
by xmonad hackers and users that provide additional features to
xmonad.  Examples include various layout modes (tabbed, spiral,
three-column...), prompts, program launchers, the ability to
manipulate windows and workspaces in various ways, alternate
navigation modes, and much more.  There are also \"meta-modules\"
which make it easier to write new modules and extensions.

This is a description of the different namespaces in xmonad-contrib.
For more information about any particular module, go to the root of
the documentation and just click on its name to view its Haddock
documentation; each module should come with extensive documentation.
If you find a module that could be better documented, or has incorrect
documentation, please report it as a bug
(<https://github.com/xmonad/xmonad-contrib/issues>)!

First and foremost, xmonad defines its own prelude for commonly used
functions, as well as re-exports from @base@.

* "XMonad.Prelude":
    Utility functions and re-exports for a more ergonomic developing
    experience.

There are also other documentation modules, showing you around
individual parts of xmonad:

* "XMonad.Doc.Configuring":
    Brief tutorial that will teach you how to create a basic
    xmonad configuration.

* "XMonad.Doc.Developing":
    A brief overview of xmonad's internals.

A list of the contrib modules can be found at
<https://xmonad.github.io/xmonad-docs/xmonad-contrib-XMONAD_CONTRIB_VERSION_MAJOR.XMONAD_CONTRIB_VERSION_MINOR.XMONAD_CONTRIB_VERSION_PATCH/>
-}

{- $actions

In the @XMonad.Actions@ namespace you can find modules exporting
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.

-}

{- $hooks

In the @XMonad.Hooks@ namespace you can find modules exporting
hooks. Hooks are actions that xmonad performs when certain events
occur. The three most important hooks are:

* 'XMonad.Core.manageHook': this hook is called when a new window that
  xmonad must take care of is created. This is a very powerful hook,
  since it lets us examine the new window's properties and act
  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
  "XMonad.Doc.Extending#Editing_the_manage_hook" for more information
  on customizing 'XMonad.Core.manageHook'.

* 'XMonad.Core.logHook': this hook is called when the stack of windows
  managed by xmonad has been changed; for example, this is invoked at
  the end of the 'XMonad.Operations.windows' function. For instance
  "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 "XMonad.Doc.Extending#The_log_hook_and_external_status_bars" for
  more information.

* 'XMonad.Core.handleEventHook': this hook is called on all events handled
  by xmonad, thus it is extremely powerful. See "Graphics.X11.Xlib.Extras"
  and xmonad source and development documentation for more details.

-}

{- $layouts

In the @XMonad.Layout@ namespace you can find modules exporting
contributed layout algorithms, such as a tabbed layout, a circle, a spiral,
three columns, and so on.

You will also find modules which provide facilities for combining
different layouts, such as "XMonad.Layout.Combo", "XMonad.Layout.ComboP",
"XMonad.Layout.LayoutBuilder", "XMonad.Layout.SubLayouts", or
"XMonad.Layout.LayoutCombinators".

Layouts can be also modified with layout modifiers. A general
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 "XMonad.Doc.Extending#Editing_the_layout_hook".

-}

{- $prompts

In the @XMonad.Prompt@ name space you can find modules providing
graphical prompts for getting user input and using it to perform
various actions.

The "XMonad.Prompt" module provides a library for easily writing new
prompts.

-}

{- $utils

In the @XMonad.Util@ namespace you can find modules exporting various
utility functions that are used by the other modules of the<commit_msg>X.D.Extending: Add links to headings<commit_after>{-# LANGUAGE CPP #-}
-- We need to link to the current version of xmonad-docs, but both
-- CURRENT_PACKAGE_VERSION and VERSION_xmonad_contrib contain quotation marks
-- that we can't get rid of using CPP, so as a workaround we define the
-- components separately in cpp-options and check that they're still in sync.
#if !__HLINT__ && \
    !( MIN_VERSION_xmonad_contrib(XMONAD_CONTRIB_VERSION_MAJOR, XMONAD_CONTRIB_VERSION_MINOR, XMONAD_CONTRIB_VERSION_PATCH) \
    && !MIN_VERSION_xmonad_contrib(XMONAD_CONTRIB_VERSION_MAJOR, XMONAD_CONTRIB_VERSION_MINOR, XMONAD_CONTRIB_VERSION_PATCH + 1) \
    )
#error "Please update XMONAD_CONTRIB_VERSION_* in xmonad-contrib.cabal"
#endif

-----------------------------------------------------------------------------
-- |
-- Module      :  XMonad.Doc.Extending
-- Description :  A module to document the xmonad-contrib library.
-- Copyright   :  (C) 2007 <NAME>
-- License     :  BSD3
--
-- Maintainer  :  <EMAIL>
-- Stability   :  unstable
-- Portability :  portable
--
-- This module documents the xmonad-contrib library and guides you
-- through some more advanced parts of extending the capabilities of
-- xmonad.  If you're new to xmonad, you should first check out the
-- <https://xmonad.org/TUTORIAL.html tutorial> and treat this document
-- as supplemental reading.
--
-- Knowing Haskell is by no means a prerequisite for configuring xmonad
-- and the tutorial emphasizes this.  This document, however, does
-- assume a basic familiarity with the language.  This is so that we can
-- dive a bit deeper into what the different hooks do, or how to write
-- our own little functions to configure xmonad.
--
-- Those wishing to be totally hardcore and develop their own xmonad
-- extensions (it's easier than it sounds, we promise!) should read the
-- documentation in "XMonad.Doc.Developing".
--
-- More configuration examples can be found
-- <https://xmonad.org/TUTORIAL.html#closing-thoughts here>.
--
-----------------------------------------------------------------------------

module XMonad.Doc.Extending
    (
    -- * The xmonad-contrib library
    -- $library

    -- ** Actions
    -- $actions

    -- ** Hooks
    -- $hooks

    -- ** Layouts
    -- $layouts

    -- ** Prompts
    -- $prompts

    -- ** Utilities
    -- $utils

    -- * Extending xmonad
    -- $extending

    -- ** Adding key bindings
    -- $keys

    -- *** Removing key bindings
    -- $keyDel

    -- *** Adding and removing key bindings
    -- $keyAddDel

    -- ** Editing mouse bindings
    -- $mouse

    -- ** Editing the layout hook #LayoutHook#
    -- $layoutHook

    -- ** Editing the manage hook #ManageHook#
    -- $manageHook

    -- ** The log hook and external status bars #LogHook#
    -- $logHook
    ) where

--------------------------------------------------------------------------------
--
--  The XmonadContrib Library
--
--------------------------------------------------------------------------------

{- $library

The xmonad-contrib library is a set of extension modules contributed
by xmonad hackers and users that provide additional features to
xmonad.  Examples include various layout modes (tabbed, spiral,
three-column...), prompts, program launchers, the ability to
manipulate windows and workspaces in various ways, alternate
navigation modes, and much more.  There are also \"meta-modules\"
which make it easier to write new modules and extensions.

This is a description of the different namespaces in xmonad-contrib.
For more information about any particular module, go to the root of
the documentation and just click on its name to view its Haddock
documentation; each module should come with extensive documentation.
If you find a module that could be better documented, or has incorrect
documentation, please report it as a bug
(<https://github.com/xmonad/xmonad-contrib/issues>)!

First and foremost, xmonad defines its own prelude for commonly used
functions, as well as re-exports from @base@.

* "XMonad.Prelude":
    Utility functions and re-exports for a more ergonomic developing
    experience.

There are also other documentation modules, showing you around
individual parts of xmonad:

* "XMonad.Doc.Configuring":
    Brief tutorial that will teach you how to create a basic
    xmonad configuration.

* "XMonad.Doc.Developing":
    A brief overview of xmonad's internals.

A list of the contrib modules can be found at
<https://xmonad.github.io/xmonad-docs/xmonad-contrib-XMONAD_CONTRIB_VERSION_MAJOR.XMONAD_CONTRIB_VERSION_MINOR.XMONAD_CONTRIB_VERSION_PATCH/>
-}

{- $actions

In the @XMonad.Actions@ namespace you can find modules exporting
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.

-}

{- $hooks

In the @XMonad.Hooks@ namespace you can find modules exporting
hooks. Hooks are actions that xmonad performs when certain events
occur. The three most important hooks are:

* 'XMonad.Core.manageHook': this hook is called when a new window that
  xmonad must take care of is created. This is a very powerful hook,
  since it lets us examine the new window's properties and act
  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
  "XMonad.Doc.Extending#Editing_the_manage_hook" for more information
  on customizing 'XMonad.Core.manageHook'.

* 'XMonad.Core.logHook': this hook is called when the stack of windows
  managed by xmonad has been changed; for example, this is invoked at
  the end of the 'XMonad.Operations.windows' function. For instance
  "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 "XMonad.Doc.Extending#The_log_hook_and_external_status_bars" for
  more information.

* 'XMonad.Core.handleEventHook': this hook is called on all events handled
  by xmonad, thus it is extremely powerful. See "Graphics.X11.Xlib.Extras"
  and xmonad source and development documentation for more details.

-}

{- $layouts

In the @XMonad.Layout@ namespace you can find modules exporting
contributed layout algorithms, such as a tabbed layout, a circle, a spiral,
three columns, and so on.

You will also find modules which provide facilities for combining
different layouts, such as "XMonad.Layout.Combo", "XMonad.Layout.ComboP",
"XMonad.Layout.LayoutBuilder", "XMonad.Layout.SubLayouts", or
"XMonad.Layout.LayoutCombinators".

Layouts can be also modified with layout modifiers. A general
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 [Editing the layout hook](#g:LayoutHook).

-}

{- $prompts

In the @XMonad.Prompt@ namespace you can find modules providing
graphical prompts for getting user input and using it to perform
various actions.

The "XMonad.Prompt" module provides a library for easily writing new
prompts.

-}

{- $utils

In the @XMonad.Util@ namespace you can find modules exporting various
utility functions that are used by the other modules of the
{'fraction_non_alphanumeric': 0.11555193039695487, 'fraction_numerical': 0.001087547580206634, 'mean_word_length': 3.0554024255788312, 'pattern_counts': {'":': 6, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4190779', 'n_tokens_mistral': 4218, 'n_tokens_neox': 4070, 'n_words': 1686}