Interfacing with window managers: new doc file

1 files changed, 224 insertions, 0 deletions

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