Interfacing with window managers: new doc file

2 files changed, 228 insertions, 225 deletions

diff --git a/doc/plugins.org b/doc/plugins.org
index 0d61b5f..052ff6f 100644
--- a/doc/plugins.org
+++ b/doc/plugins.org
@@ -35,6 +35,10 @@
       100
   #+end_src
 
+  See also [[./window-managers.org][Interfacing with window managers]] for a collection of
+  plugins that let you interact and control xmobar from window
+  managers.
+
 *** Icon Patterns
 
     Some monitors allow usage of strings that depend on some integer
@@ -1274,231 +1278,6 @@
           Run UVMeter "Brisbane" ["-H", "3", "-L", "3", "--low", "green", "--high", "red"] 900
         #+end_src
 
-* Interfacing with Window Managers
-
-  Listed below are ways to interface xmobar with your window manager
-  of choice.
-
-*** Property-based Logging
-***** =XMonadLog=
-
-      - Aliases to XMonadLog
-
-      - Displays information from xmonad's =_XMONAD_LOG=. You can use
-        this by using functions from the [[https://hackage.haskell.org/package/xmonad-contrib-0.16/docs/XMonad-Hooks-DynamicLog.html][XMonad.Hooks.DynamicLog]]
-        module. By using the =xmonadPropLog= function in your logHook,
-        you can write the the above property. The following shows a
-        minimal xmonad configuration that spawns xmobar and then
-        writes to the =_XMONAD_LOG= property.
-
-        #+begin_src haskell
-          main = do
-            spawn "xmobar"
-            xmonad $ def
-              { logHook = dynamicLogString defaultPP >>= xmonadPropLog
-              }
-        #+end_src
-
-        This plugin can be used as a sometimes more convenient
-        alternative to =StdinReader=. For instance, it allows you to
-        (re)start xmobar outside xmonad.
-
-***** =UnsafeXMonadLog=
-
-      - Aliases to UnsafeXMonadLog
-      - Displays any text received by xmobar on the =_XMONAD_LOG= atom.
-      - Will not do anything to the text received. This means you can pass
-        xmobar dynamic actions. Be careful to escape (using =<raw=…>=) or
-        remove tags from dynamic text that you pipe through to xmobar in this
-        way.
-
-      - Sample usage: Send the list of your workspaces, enclosed by actions
-        tags, to xmobar.  This enables you to switch to a workspace when you
-        click on it in xmobar!
-
-        #+begin_src shell
-          <action=`xdotool key alt+1`>ws1</action> <action=`xdotool key alt+1`>ws2</action>
-        #+end_src
-
-      - If you use xmonad, It is advised that you still use =xmobarStrip= for
-        the =ppTitle= in your logHook:
-
-        #+begin_src haskell
-          myPP = defaultPP { ppTitle = xmobarStrip }
-          main = xmonad $ def
-            { logHook = dynamicLogString myPP >>= xmonadPropLog
-            }
-        #+end_src
-
-***** =XPropertyLog PropName=
-
-      - Aliases to =PropName=
-      - Reads the X property named by =PropName= (a string) and displays its
-        value. The [[https://github.com/jaor/xmobar/raw/master/examples/xmonadpropwrite.hs][examples/xmonadpropwrite.hs script]] in xmobar's distribution
-        can be used to set the given property from the output of any other
-        program or script.
-
-***** =UnsafeXPropertyLog PropName=
-
-      - Aliases to =PropName=
-      - Same as =XPropertyLog= but the input is not filtered to avoid
-        injection of actions (cf. =UnsafeXMonadLog=). The program writing the
-        value of the read property is responsible of performing any needed
-        cleanups.
-
-***** =NamedXPropertyLog PropName Alias=
-
-      - Aliases to =Alias=
-      - Same as =XPropertyLog= but a custom alias can be specified.
-
-***** =UnsafeNamedXPropertyLog PropName Alias=
-
-      - Aliases to =Alias=
-      - Same as =UnsafeXPropertyLog=, but a custom alias can be specified.
-
-*** Logging via Stdin
-***** =StdinReader=
-
-      - Aliases to StdinReader
-      - Displays any text received by xmobar on its standard input.
-      - Strips actions from the text received. This means you can't pass
-        dynamic actions via stdin. This is safer than =UnsafeStdinReader=
-        because there is no need to escape the content before passing it to
-        xmobar's standard input.
-
-***** =UnsafeStdinReader=
-
-      - Aliases to UnsafeStdinReader
-      - Displays any text received by xmobar on its standard input.
-      - Similar to [[=UnsafeXMonadLog=][UnsafeXMonadLog]], in the sense that it does not strip any
-        actions from the received text, only using =stdin= and not a property
-        atom of the root window. Please be equally carefully when using this
-        as when using =UnsafeXMonadLog=!
-
-*** Pipe-based Logging
-***** =PipeReader "default text:/path/to/pipe" Alias=
-
-      - Reads its displayed output from the given pipe.
-      - Prefix an optional default text separated by a colon
-      - Expands environment variables in the first argument of syntax =${VAR}=
-        or =$VAR=
-
-***** =MarqueePipeReader "default text:/path/to/pipe" (length, rate, sep) Alias=
-
-      - Generally equivalent to PipeReader
-
-      - Text is displayed as marquee with the specified length, rate in 10th
-        seconds and separator when it wraps around
-
-        #+begin_src haskell
-          Run MarqueePipeReader "/tmp/testpipe" (10, 7, "+") "mpipe"
-        #+end_src
-
-      - Expands environment variables in the first argument
-
-***** =BufferedPipeReader Alias [(Timeout, Bool, "/path/to/pipe1"), ..]=
-
-      - Display data from multiple pipes.
-
-      - Timeout (in tenth of seconds) is the value after which the
-        previous content is restored i.e. if there was already
-        something from a previous pipe it will be put on display
-        again, overwriting the current status.
-
-      - A pipe with Timeout of 0 will be displayed permanently, just
-        like =PipeReader=
-
-      - The boolean option indicates whether new data for this pipe
-        should make xmobar appear (unhide, reveal). In this case, the
-        Timeout additionally specifies when the window should be
-        hidden again. The output is restored in any case.
-
-      - Use it for OSD-like status bars e.g. for setting the volume or
-        brightness:
-
-        #+begin_src haskell
-          Run BufferedPipeReader "bpr"
-              [ (  0, False, "/tmp/xmobar_window"  )
-              , ( 15,  True, "/tmp/xmobar_status"  )
-              ]
-        #+end_src
-
-        Have your window manager send window titles to
-        =/tmp/xmobar_window=.  They will always be shown and not reveal
-        your xmobar. Sending some status information to
-        =/tmp/xmobar_status= will reveal xmonad for 1.5 seconds and
-        temporarily overwrite the window titles.
-
-      - Take a look at [[http://github.com/jaor/xmobar/raw/master/examples/status.sh][examples/status.sh]]
-
-      - Expands environment variables for the pipe path
-
-*** Handle-based Logging
-***** =HandleReader Handle Alias=
-
-      - Display data from a Haskell =Handle=
-
-      - This plugin is only useful if you are running xmobar from another
-        Haskell program like XMonad.
-
-      - You can use =System.Process.createPipe= to create a pair of =read= &
-        =write= Handles. Pass the =read= Handle to HandleReader and write your
-        output to the =write= Handle:
-
-        #+begin_src haskell
-          (readHandle, writeHandle) <- createPipe
-          xmobarProcess <- forkProcess $ xmobar myConfig
-                  { commands =
-                      Run (HandleReader readHandle "handle") : commands myConfig
-                  }
-          hPutStr writeHandle "Hello World"
-        #+end_src
-
-*** Software Transactional Memory
-
-    When invoking xmobar from other Haskell code it can be easier and
-    more performant to use shared memory.  The following plugins
-    leverage =Control.Concurrent.STM= to realize these gains for xmobar.
-
-***** =QueueReader (TQueue a) (a -> String) String=
-
-      - Display data from a Haskell =TQueue a=.
-
-      - This plugin is only useful if you are running xmobar from another
-        haskell program like xmonad.
-
-      - You should make an =IO= safe =TQueue a= with
-        =Control.Concurrent.STM.newTQueueIO=.  Write to it from the user
-        code with =writeTQueue=, and read with =readTQueue=.  A common use
-        is to overwite =ppOutput= from =XMonad.Hooks.DynamicLog= as shown
-        below.
-
-        #+begin_src haskell
-          main :: IO ()
-          main = do
-            q <- STM.newTQueueIO @String
-            bar <- forkIO $ xmobar myConf
-              { commands = Run (QueueReader q id "XMonadLog") : commands myConf }
-            xmonad $ def { logHook = logWorkspacesToQueue q }
-
-          logWorkspacesToQueue :: STM.TQueue String -> X ()
-          logWorkspacesToQueue q =
-            dynamicLogWithPP def { ppOutput = STM.atomically . STM.writeTQueue q }
-            where
-              -- Manage the PrettyPrinting configuration here.
-              ppLayout' :: String -> String
-              ppLayout' "Spacing Tall"        = xpm "layout-spacing-tall"
-              ppLayout' "Spacing Mirror Tall" = xpm "layout-spacing-mirror"
-              ppLayout' "Spacing Full"        = xpm "layout-full"
-              ppLayout' x = x
-
-              icon :: String -> String
-              icon path = "<icon=" ++ path ++ "/>"
-
-              xpm :: String -> String
-              xpm = icon . (++ ".xpm")
-        #+end_src
-
 * Executing External Commands
 
   In order to execute an external command you can either write the
diff --git a/doc/window-managers.org b/doc/window-managers.org
new file mode 100644
index 0000000..3a194c8
--- /dev/null
+++ b/doc/window-managers.org
@@ -0,0 +1,224 @@
+#+title: Interfacing with window managers
+
+Listed below are ways to interface xmobar with your window manager of
+choice.
+
+*** Property-based Logging
+***** =XMonadLog=
+
+      - Aliases to XMonadLog
+
+      - Displays information from xmonad's =_XMONAD_LOG=. You can use
+        this by using functions from the [[https://hackage.haskell.org/package/xmonad-contrib-0.16/docs/XMonad-Hooks-DynamicLog.html][XMonad.Hooks.DynamicLog]]
+        module. By using the =xmonadPropLog= function in your logHook,
+        you can write the the above property. The following shows a
+        minimal xmonad configuration that spawns xmobar and then
+        writes to the =_XMONAD_LOG= property.
+
+        #+begin_src haskell
+          main = do
+            spawn "xmobar"
+            xmonad $ def
+              { logHook = dynamicLogString defaultPP >>= xmonadPropLog
+              }
+        #+end_src
+
+        This plugin can be used as a sometimes more convenient
+        alternative to =StdinReader=. For instance, it allows you to
+        (re)start xmobar outside xmonad.
+
+***** =UnsafeXMonadLog=
+
+      - Aliases to UnsafeXMonadLog
+      - Displays any text received by xmobar on the =_XMONAD_LOG= atom.
+      - Will not do anything to the text received. This means you can pass
+        xmobar dynamic actions. Be careful to escape (using =<raw=…>=) or
+        remove tags from dynamic text that you pipe through to xmobar in this
+        way.
+
+      - Sample usage: Send the list of your workspaces, enclosed by actions
+        tags, to xmobar.  This enables you to switch to a workspace when you
+        click on it in xmobar!
+
+        #+begin_src shell
+          <action=`xdotool key alt+1`>ws1</action> <action=`xdotool key alt+1`>ws2</action>
+        #+end_src
+
+      - If you use xmonad, It is advised that you still use =xmobarStrip= for
+        the =ppTitle= in your logHook:
+
+        #+begin_src haskell
+          myPP = defaultPP { ppTitle = xmobarStrip }
+          main = xmonad $ def
+            { logHook = dynamicLogString myPP >>= xmonadPropLog
+            }
+        #+end_src
+
+***** =XPropertyLog PropName=
+
+      - Aliases to =PropName=
+      - Reads the X property named by =PropName= (a string) and displays its
+        value. The [[https://github.com/jaor/xmobar/raw/master/examples/xmonadpropwrite.hs][examples/xmonadpropwrite.hs script]] in xmobar's distribution
+        can be used to set the given property from the output of any other
+        program or script.
+
+***** =UnsafeXPropertyLog PropName=
+
+      - Aliases to =PropName=
+      - Same as =XPropertyLog= but the input is not filtered to avoid
+        injection of actions (cf. =UnsafeXMonadLog=). The program writing the
+        value of the read property is responsible of performing any needed
+        cleanups.
+
+***** =NamedXPropertyLog PropName Alias=
+
+      - Aliases to =Alias=
+      - Same as =XPropertyLog= but a custom alias can be specified.
+
+***** =UnsafeNamedXPropertyLog PropName Alias=
+
+      - Aliases to =Alias=
+      - Same as =UnsafeXPropertyLog=, but a custom alias can be specified.
+
+*** Logging via Stdin
+***** =StdinReader=
+
+      - Aliases to StdinReader
+      - Displays any text received by xmobar on its standard input.
+      - Strips actions from the text received. This means you can't pass
+        dynamic actions via stdin. This is safer than =UnsafeStdinReader=
+        because there is no need to escape the content before passing it to
+        xmobar's standard input.
+
+***** =UnsafeStdinReader=
+
+      - Aliases to UnsafeStdinReader
+      - Displays any text received by xmobar on its standard input.
+      - Similar to [[=UnsafeXMonadLog=][UnsafeXMonadLog]], in the sense that it does not strip any
+        actions from the received text, only using =stdin= and not a property
+        atom of the root window. Please be equally carefully when using this
+        as when using =UnsafeXMonadLog=!
+
+*** Pipe-based Logging
+***** =PipeReader "default text:/path/to/pipe" Alias=
+
+      - Reads its displayed output from the given pipe.
+      - Prefix an optional default text separated by a colon
+      - Expands environment variables in the first argument of syntax =${VAR}=
+        or =$VAR=
+
+***** =MarqueePipeReader "default text:/path/to/pipe" (length, rate, sep) Alias=
+
+      - Generally equivalent to PipeReader
+
+      - Text is displayed as marquee with the specified length, rate in 10th
+        seconds and separator when it wraps around
+
+        #+begin_src haskell
+          Run MarqueePipeReader "/tmp/testpipe" (10, 7, "+") "mpipe"
+        #+end_src
+
+      - Expands environment variables in the first argument
+
+***** =BufferedPipeReader Alias [(Timeout, Bool, "/path/to/pipe1"), ..]=
+
+      - Display data from multiple pipes.
+
+      - Timeout (in tenth of seconds) is the value after which the
+        previous content is restored i.e. if there was already
+        something from a previous pipe it will be put on display
+        again, overwriting the current status.
+
+      - A pipe with Timeout of 0 will be displayed permanently, just
+        like =PipeReader=
+
+      - The boolean option indicates whether new data for this pipe
+        should make xmobar appear (unhide, reveal). In this case, the
+        Timeout additionally specifies when the window should be
+        hidden again. The output is restored in any case.
+
+      - Use it for OSD-like status bars e.g. for setting the volume or
+        brightness:
+
+        #+begin_src haskell
+          Run BufferedPipeReader "bpr"
+              [ (  0, False, "/tmp/xmobar_window"  )
+              , ( 15,  True, "/tmp/xmobar_status"  )
+              ]
+        #+end_src
+
+        Have your window manager send window titles to
+        =/tmp/xmobar_window=.  They will always be shown and not reveal
+        your xmobar. Sending some status information to
+        =/tmp/xmobar_status= will reveal xmonad for 1.5 seconds and
+        temporarily overwrite the window titles.
+
+      - Take a look at [[http://github.com/jaor/xmobar/raw/master/examples/status.sh][examples/status.sh]]
+
+      - Expands environment variables for the pipe path
+
+*** Handle-based Logging
+***** =HandleReader Handle Alias=
+
+      - Display data from a Haskell =Handle=
+
+      - This plugin is only useful if you are running xmobar from another
+        Haskell program like XMonad.
+
+      - You can use =System.Process.createPipe= to create a pair of =read= &
+        =write= Handles. Pass the =read= Handle to HandleReader and write your
+        output to the =write= Handle:
+
+        #+begin_src haskell
+          (readHandle, writeHandle) <- createPipe
+          xmobarProcess <- forkProcess $ xmobar myConfig
+                  { commands =
+                      Run (HandleReader readHandle "handle") : commands myConfig
+                  }
+          hPutStr writeHandle "Hello World"
+        #+end_src
+
+*** Software Transactional Memory
+
+    When invoking xmobar from other Haskell code it can be easier and
+    more performant to use shared memory.  The following plugins
+    leverage =Control.Concurrent.STM= to realize these gains for xmobar.
+
+***** =QueueReader (TQueue a) (a -> String) String=
+
+      - Display data from a Haskell =TQueue a=.
+
+      - This plugin is only useful if you are running xmobar from another
+        haskell program like xmonad.
+
+      - You should make an =IO= safe =TQueue a= with
+        =Control.Concurrent.STM.newTQueueIO=.  Write to it from the user
+        code with =writeTQueue=, and read with =readTQueue=.  A common use
+        is to overwite =ppOutput= from =XMonad.Hooks.DynamicLog= as shown
+        below.
+
+        #+begin_src haskell
+          main :: IO ()
+          main = do
+            q <- STM.newTQueueIO @String
+            bar <- forkIO $ xmobar myConf
+              { commands = Run (QueueReader q id "XMonadLog") : commands myConf }
+            xmonad $ def { logHook = logWorkspacesToQueue q }
+
+          logWorkspacesToQueue :: STM.TQueue String -> X ()
+          logWorkspacesToQueue q =
+            dynamicLogWithPP def { ppOutput = STM.atomically . STM.writeTQueue q }
+            where
+              -- Manage the PrettyPrinting configuration here.
+              ppLayout' :: String -> String
+              ppLayout' "Spacing Tall"        = xpm "layout-spacing-tall"
+              ppLayout' "Spacing Mirror Tall" = xpm "layout-spacing-mirror"
+              ppLayout' "Spacing Full"        = xpm "layout-full"
+              ppLayout' x = x
+
+              icon :: String -> String
+              icon path = "<icon=" ++ path ++ "/>"
+
+              xpm :: String -> String
+              xpm = icon . (++ ".xpm")
+        #+end_src