From 38adaf0ded1ca40bd7366af82f8e5bae737233ae Mon Sep 17 00:00:00 2001
From: Guy Gastineau <strings.stringsandstrings@gmail.com>
Date: Tue, 14 Sep 2021 20:43:30 -0400
Subject: Add documentation for QueueReader.

I added `QueueReader` as a section under `Software Transational
Memory`, but it is all alone.  Some other plugins actually use STM,
and maybe they should actually go in that section too.

I didn't make a safe versions since the plugin is not readable.  It
still would be nice to have, but I think exposing `stripActions` is
the appropriate solution.  That should be handled in a new PR I guess.
---
 doc/plugins.org | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/doc/plugins.org b/doc/plugins.org
index 48999c2..a1fa4df 100644
--- a/doc/plugins.org
+++ b/doc/plugins.org
@@ -1436,6 +1436,50 @@ choice.
      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 command
-- 
cgit v1.2.3