Subdivide window manager integration

1 files changed, 128 insertions, 108 deletions

diff --git a/doc/plugins.org b/doc/plugins.org
index 99a850b..0516b67 100644
--- a/doc/plugins.org
+++ b/doc/plugins.org
@@ -1264,158 +1264,178 @@ and not new individual messages.
 Listed below are ways to interface xmobar with your window manager of
 choice.
 
-** =XMonadLog=
+** Property-based Logging
+*** =XMonadLog=
 
-- Aliases to 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.
+ - 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
+   #+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.
+   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=
+*** =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.
+ - 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!
+ - 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
+   #+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:
+ - 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
+   #+begin_src haskell
+     myPP = defaultPP { ppTitle = xmobarStrip }
+     main = xmonad $ def
+       { logHook = dynamicLogString myPP >>= xmonadPropLog
+       }
+   #+end_src
 
-** =StdinReader=
+*** =XPropertyLog PropName=
 
-- 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.
+ - 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.
 
-** =UnsafeStdinReader=
+*** =UnsafeXPropertyLog PropName=
 
-- 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=!
+ - 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.
 
-** =CommandReader "/path/to/program" Alias=
+*** =UnsafeStdinReader=
 
-- Runs the given program, and displays its standard output.
+ - 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=!
 
-** =PipeReader "default text:/path/to/pipe" Alias=
+** 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=
+ - 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=
+*** =MarqueePipeReader "default text:/path/to/pipe" (length, rate, sep) Alias=
 
-- Generally equivalent to PipeReader
+ - Generally equivalent to PipeReader
 
-- Text is displayed as marquee with the specified length, rate in 10th
-  seconds and separator when it wraps around
+ - 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
+   #+begin_src haskell
+     Run MarqueePipeReader "/tmp/testpipe" (10, 7, "+") "mpipe"
+   #+end_src
 
-- Expands environment variables in the first argument
+ - Expands environment variables in the first argument
 
-** =BufferedPipeReader Alias [(Timeout, Bool, "/path/to/pipe1"), ..]=
+*** =BufferedPipeReader Alias [(Timeout, Bool, "/path/to/pipe1"), ..]=
 
-- Display data from multiple pipes.
+ - 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.
+ - 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=
+ - 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.
+ - 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:
+ - 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
+   #+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.
+   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]]
+ - Take a look at [[http://github.com/jaor/xmobar/raw/master/examples/status.sh][examples/status.sh]]
 
-- Expands environment variables for the pipe path
+ - Expands environment variables for the pipe path
 
-** =HandleReader Handle Alias=
+** Handle-based Logging
+*** =HandleReader Handle Alias=
 
-- Display data from a Haskell =Handle=
+ - Display data from a Haskell =Handle=
 
-- This plugin is only useful if you are running xmobar from another
-  Haskell program like XMonad.
+ - 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:
+ - 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
+   #+begin_src haskell
+     (readHandle, writeHandle) <- createPipe
+     xmobarProcess <- forkProcess $ xmobar myConfig
+             { commands =
+                 Run (HandleReader readHandle "handle") : commands myConfig
+             }
+     hPutStr writeHandle "Hello World"
+   #+end_src
 
 * Executing External Commands