From 34af6ebed131ce1fd85cea5c27f15507643bf3d6 Mon Sep 17 00:00:00 2001
From: slotThe <soliditsallgood@mailbox.org>
Date: Sun, 29 Aug 2021 09:58:24 +0200
Subject: [PATCH] X.L.Spacing: Extend documentation

Users are having trouble with this module all the time.  Now that
certain helper functions are undeprecated, we should tell users how they
may use them.  It is also worth explaining the scary-looking
`spacingRaw` command a bit further.

Related: https://github.com/xmonad/xmonad-contrib/pull/597
---
 XMonad/Layout/Spacing.hs | 36 +++++++++++++++++++++++++++++++++---
 1 file changed, 33 insertions(+), 3 deletions(-)

diff --git a/XMonad/Layout/Spacing.hs b/XMonad/Layout/Spacing.hs
index fb558cb1..55081f63 100644
--- a/XMonad/Layout/Spacing.hs
+++ b/XMonad/Layout/Spacing.hs
@@ -61,10 +61,40 @@ import           XMonad.Actions.MessageFeedback
 --
 -- > import XMonad.Layout.Spacing
 --
--- and modifying your layoutHook as follows (for example):
+-- and, for example, modifying your @layoutHook@ as follows:
 --
--- > layoutHook = spacingRaw True (Border 0 10 10 10) True (Border 10 10 10 10) True $
--- >              layoutHook def
+-- > main :: IO ()
+-- > main = xmonad $ def
+-- >   { layoutHook = spacingWithEdge 10 $ myLayoutHook
+-- >   }
+-- >
+-- > myLayoutHook = Full ||| ...
+--
+-- The above would add a 10 pixel gap around windows on all sides, as
+-- well as add the same amount of spacing around the edges of the
+-- screen.  If you only want to add spacing around windows, you can use
+-- 'spacing' instead.
+--
+-- There is also the 'spacingRaw' command, for more fine-grained
+-- control.  For example:
+--
+-- > layoutHook = spacingRaw True (Border 0 10 10 10) True (Border 10 10 10 10) True
+-- >            $ myLayoutHook
+--
+-- Breaking this down, the above would do the following:
+--
+--   - @True@: Enable the 'smartBorder' to not apply borders when there
+--     is only one window.
+--
+--   - @(Border 0 10 10 10)@: Add a 'screenBorder' of 10 pixels in every
+--     direction but the top.
+--
+--   - @True@: Enable the 'screenBorder'.
+--
+--   - @(Border 10 10 10 10)@: Add a 'windowBorder' of 10 pixels in
+--     every direction.
+--
+--   - @True@: Enable the 'windowBorder'.
 
 -- | Represent the borders of a rectangle.
 data Border = Border