X.H.InsertPosition: Add combinator

Users may not see the warning that insertPosition definitely needs to be
inserted at the leftmost position, which can cause undesired behaviour.
Having a combinator that handles this automatically seems like a sane
idea.

Fixes: https://github.com/xmonad/xmonad-contrib/issues/709

       (Note that `docs` wasn't changed since it already inserts itself
       rightmost.)

CHANGES.md

@@ -79,6 +79,11 @@
   - Added `directionMoveWindow` and `directionMoveWindow` as more
     alternatives to the existing functions.
 
+* `XMonad.Hooks.InsertPosition`
+
+  - Added `setupInsertPosition` as a combinator alternative to
+    `insertPosition`.
+
 ### Other changes
 
 ## 0.17.1 (September 3, 2022)

XMonad/Hooks/InsertPosition.hs

@@ -17,21 +17,30 @@
 module XMonad.Hooks.InsertPosition (
     -- * Usage
     -- $usage
-    insertPosition
+    setupInsertPosition, insertPosition
     ,Focus(..), Position(..)
     ) where
 
-import XMonad(ManageHook, MonadReader(ask))
+import XMonad (ManageHook, MonadReader (ask), XConfig (manageHook))
 import XMonad.Prelude (Endo (Endo), find)
 import qualified XMonad.StackSet as W
 
 -- $usage
--- You can use this module with the following in your @~\/.xmonad\/xmonad.hs@:
+-- You can use this module by importing it in your @~\/.xmonad\/xmonad.hs@:
 --
 -- > import XMonad.Hooks.InsertPosition
+--
+-- You then just have to add 'setupInsertPosition' to your @main@ function:
+--
+-- > main = xmonad $ … $ setupInsertPosition Master Newer $ def { … }
+--
+-- Alternatively (i.e., you should /not/ do this if you already have set
+-- up the above combinator), you can also directly insert
+-- 'insertPosition' into your manageHook:
+--
 -- > xmonad def { manageHook = insertPosition Master Newer <> myManageHook }
 --
--- You should you put the manageHooks that use 'doShift' to take effect
+-- NOTE: You should you put the manageHooks that use 'doShift' to take effect
 -- /before/ 'insertPosition', so that the window order will be consistent.
 -- Because ManageHooks compose from right to left (like function composition
 -- '.'), this means that 'insertPosition' should be the leftmost ManageHook.
@@ -39,6 +48,11 @@ import qualified XMonad.StackSet as W
 data Position = Master | End | Above | Below
 data Focus = Newer | Older
 
+-- | A combinator for setting up 'insertPosition'.
+setupInsertPosition :: Position -> Focus -> XConfig a -> XConfig a
+setupInsertPosition pos foc cfg =
+  cfg{ manageHook = insertPosition pos foc <> manageHook cfg }
+
 -- | insertPosition. A manage hook for placing new windows. XMonad's default is
 -- the same as using: @insertPosition Above Newer@.
 insertPosition :: Position -> Focus -> ManageHook