documentation: improvements for xmobar-in-haskell docs

4 files changed, 254 insertions, 239 deletions

diff --git a/contributing.org b/contributing.org
index f5ea875..62ae6cb 100644
--- a/contributing.org
+++ b/contributing.org
@@ -46,7 +46,6 @@ problems you are having, as well as the proposed solution.
     - A brief summary of how your commits fit together to achieve this
       (if necessary).
 
-    Please also remember to update the =changelog.md= file, as well as
-    any other documentation that your pull request touches upon.  For
-    example, if you add a new plugin (see [[./doc/write-your-own-plugin.org][here]] for more information)
-    you should update the [[./doc/plugins.org][plugins documentation]].
+    Please also remember to update the =changelog.md= file, as well as any other
+    documentation that your pull request touches upon.  For example, if you
+    add a new plugin you should update the [[./doc/plugins.org][plugins documentation]].
diff --git a/doc/using-haskell.org b/doc/using-haskell.org
new file mode 100644
index 0000000..5c48c06
--- /dev/null
+++ b/doc/using-haskell.org
@@ -0,0 +1,125 @@
+#+title: Using Haskell
+
+* Writing your own xmobar in Haskell
+  :PROPERTIES:
+  :CUSTOM_ID: xmobar-in-haskell
+  :END:
+
+  Besides an standalone program, ~xmobar~ is also a Haskell library providing
+  an interface to write your own status bar. You can write, instead of a
+  configuration file, a real Haskell program that will be compiled and run
+  when you invoke =xmobar=.
+
+  Make sure that ~ghc~ will be able to locate the xmobar library, e.g. with
+
+  #+begin_src shell
+    cabal install --lib xmobar
+  #+end_src
+
+  and then write your Haskell configuration and main function using the
+  functions and types exported in the library, which closely resemble those
+  used in configuration files.  Here's a small example:
+
+  #+begin_src haskell
+    import Xmobar
+
+    config :: Config
+    config =
+      defaultConfig
+        { font = "xft:Terminus-8",
+          allDesktops = True,
+          alpha = 200,
+          commands =
+            [ Run XMonadLog,
+              Run $ Memory ["t", "Mem: <usedratio>%"] 10,
+              Run $ Kbd [],
+              Run $ Date "%a %_d %b %Y <fc=#ee9a00>%H:%M:%S</fc>" "date" 10
+            ],
+          template = "%XMonadLog% }{ %kbd% | %date% | %memory%",
+          alignSep = "}{"
+        }
+
+    main :: IO ()
+    main = xmobar config
+  #+end_src
+
+  You can then for instance run =ghc --make xmobar.hs= to create a new xmobar
+  executable running exactly the monitors defined above.  Or put your
+  =xmobar.hs= program in =~/.config/xmobar/xmobar.hs= and, when running the
+  system-wide xmobar, it will notice that you have your own implementation
+  and (re)compile and run it as needed.
+
+* Writing a plugin
+  :PROPERTIES:
+  :CUSTOM_ID: writing-a-plugin
+  :END:
+  Writing a plugin for xmobar is very simple!
+
+  First, you need to create a data type with at least one constructor.  Next
+  you must declare this data type an instance of the =Exec= class, by defining
+  the one needed method (alternatively =start= or =run=) and 3 optional ones
+  (=alias=, =rate=, and =trigger=):
+
+  #+begin_src haskell
+    start   :: e -> (String -> IO ()) -> IO ()
+    run     :: e -> IO String
+    rate    :: e -> Int
+    alias   :: e -> String
+    trigger :: e -> (Maybe SignalType -> IO ()) -> IO ()
+  #+end_src
+
+  =start= must receive a callback to be used to display the =String= produced by
+  the plugin. This method can be used for plugins that need to perform
+  asynchronous actions. See =src/Xmobar/Plugins/PipeReader.hs= for an example.
+
+  =run= can be used for simpler plugins. If you define only =run= the plugin
+  will be run every second. To overwrite this default you just need to
+  implement =rate=, which must return the number of tenth of seconds between
+  every successive runs. See [[../examples/xmobar.hs][examples/xmobar.hs]] for an example of a plugin
+  that runs just once, and [[../src/Xmobar/Plugins/Date.hs][src/Xmobar/Plugins/Date.hs]] for one that
+  implements =rate=.
+
+  Notice that Date could be implemented as:
+
+  #+begin_src haskell
+    instance Exec Date where
+        alias (Date _ a _) = a
+        start (Date f _ r) = date f r
+
+    date :: String -> Int -> (String -> IO ()) -> IO ()
+    date format r callback = do go
+        where go = do
+                t <- toCalendarTime =<< getClockTime
+                callback $ formatCalendarTime defaultTimeLocale format t
+                tenthSeconds r >> go
+  #+end_src
+
+  Modulo some technicalities like refreshing the time-zone in a clever way,
+  this implementation is equivalent to the one you can read in
+  =Plugins/Date.hs=.
+
+  =alias= is the name to be used in the output template. Default alias will be
+  the data type constructor.
+
+  After that your type constructor can be used as an argument for the
+  Runnable type constructor =Run= in the =commands= list of the configuration
+  options.
+
+  If your plugin only implements =alias= and =start=, then it is advisable to
+  put it into the =Xmobar/Plugins/Monitors= directory and use one of the many
+  =run*= functions in [[../src/Xmobar/Plugins/Monitors/Common/Run.hs][Xmobar.Plugins.Monitors.Run]] in order to define
+  =start=. The =Exec= instance should then live in [[../src/Xmobar/Plugins/Monitors.hs][Xmobar.Plugins.Monitors]].
+
+* Using a Plugin
+
+  To use your new plugin, you just need to use a pure Haskell configuration
+  for xmobar (as explained [[#xmobar-in-haskell][above]]) and load your definitions in your =xmobar.hs=
+  file. You can see an example in [[../examples/xmobar.hs][examples/xmobar.hs]] showing you how to write
+  a Haskell configuration that uses a new plugin, all in one file.
+
+  When xmobar runs with the full path to that Haskell file as its argument
+  (or if you put it in =~/.config/xmobar/xmobar.hs=), and with the xmobar
+  library installed (e.g., with =cabal install --lib xmobar=), the Haskell
+  code will be compiled as needed, and the new executable spawned for you.
+
+  That's it!
diff --git a/doc/write-your-own-plugin.org b/doc/write-your-own-plugin.org
deleted file mode 100644
index fb1ca85..0000000
--- a/doc/write-your-own-plugin.org
+++ /dev/null
@@ -1,73 +0,0 @@
-#+title: Writing your own plugin
-
-*** Writing a plugin
-    Writing a plugin for xmobar is very simple!
-
-    First, you need to create a data type with at least one constructor.  Next
-    you must declare this data type an instance of the =Exec= class, by defining
-    the one needed method (alternatively =start= or =run=) and 3 optional ones
-    (=alias=, =rate=, and =trigger=):
-
-    #+begin_src haskell
-      start   :: e -> (String -> IO ()) -> IO ()
-      run     :: e -> IO String
-      rate    :: e -> Int
-      alias   :: e -> String
-      trigger :: e -> (Maybe SignalType -> IO ()) -> IO ()
-    #+end_src
-
-    =start= must receive a callback to be used to display the =String= produced by
-    the plugin. This method can be used for plugins that need to perform
-    asynchronous actions. See =src/Xmobar/Plugins/PipeReader.hs= for an example.
-
-    =run= can be used for simpler plugins. If you define only =run= the plugin
-    will be run every second. To overwrite this default you just need to
-    implement =rate=, which must return the number of tenth of seconds between
-    every successive runs. See [[../examples/xmobar.hs][examples/xmobar.hs]] for an example of a plugin
-    that runs just once, and [[../src/Xmobar/Plugins/Date.hs][src/Xmobar/Plugins/Date.hs]] for one that
-    implements =rate=.
-
-    Notice that Date could be implemented as:
-
-    #+begin_src haskell
-      instance Exec Date where
-          alias (Date _ a _) = a
-          start (Date f _ r) = date f r
-
-      date :: String -> Int -> (String -> IO ()) -> IO ()
-      date format r callback = do go
-          where go = do
-                  t <- toCalendarTime =<< getClockTime
-                  callback $ formatCalendarTime defaultTimeLocale format t
-                  tenthSeconds r >> go
-    #+end_src
-
-    Modulo some technicalities like refreshing the time-zone in a clever way,
-    this implementation is equivalent to the one you can read in
-    =Plugins/Date.hs=.
-
-    =alias= is the name to be used in the output template. Default alias will be
-    the data type constructor.
-
-    After that your type constructor can be used as an argument for the
-    Runnable type constructor =Run= in the =commands= list of the configuration
-    options.
-
-    If your plugin only implements =alias= and =start=, then it is advisable to
-    put it into the =Xmobar/Plugins/Monitors= directory and use one of the many
-    =run*= functions in [[../src/Xmobar/Plugins/Monitors/Common/Run.hs][Xmobar.Plugins.Monitors.Run]] in order to define
-    =start=. The =Exec= instance should then live in [[../src/Xmobar/Plugins/Monitors.hs][Xmobar.Plugins.Monitors]].
-
-*** Using a Plugin
-
-    To use your new plugin, you need to use a pure Haskell configuration for
-    xmobar (as explained [[../readme.org#xmobar-in-haskell][here)]] and load your definitions in your =xmobar.hs=
-    file. You can see an example in [[../examples/xmobar.hs][examples/xmobar.hs]] showing you how to
-    write a Haskell configuration that uses a new plugin, all in one file.
-
-    When xmobar runs with the full path to that Haskell file as its argument
-    (or if you put it in =~/.config/xmobar/xmobar.hs=), and with the xmobar
-    library installed (e.g., with =cabal install --lib xmobar=), the Haskell
-    code will be compiled as needed, and the new executable spawned for you.
-
-    That's it!
diff --git a/readme.org b/readme.org
index 23758fa..017e3d9 100644
--- a/readme.org
+++ b/readme.org
@@ -33,179 +33,143 @@ channel, ~#xmobar~, at [[ircs://irc.libera.chat][Libera]].
   :PROPERTIES:
   :CUSTOM_ID: installation
   :END:
-*** From your system's package manager
+** From your system's package manager
 
-    Xmobar is probably available from your distributions package
-    manager!  Most distributions compile xmobar with the =all_extensions=
-    flag, so you don't have to.
+   Xmobar is probably available from your distributions package
+   manager!  Most distributions compile xmobar with the =all_extensions=
+   flag, so you don't have to.
 
-    - Arch Linux
-      #+begin_src shell
-        pacman -S xmobar
-      #+end_src
+   - Arch Linux
+     #+begin_src shell
+       pacman -S xmobar
+     #+end_src
 
-    - Debian/Ubuntu based
-      #+begin_src shell
-        apt install xmobar
-      #+end_src
+   - Debian/Ubuntu based
+     #+begin_src shell
+       apt install xmobar
+     #+end_src
 
-    - OpenSUSE
-      #+begin_src shell
-        zypper install xmobar
-      #+end_src
+   - OpenSUSE
+     #+begin_src shell
+       zypper install xmobar
+     #+end_src
 
-    - Void Linux
-      #+begin_src shell
-        xbps-install xmobar
-      #+end_src
+   - Void Linux
+     #+begin_src shell
+       xbps-install xmobar
+     #+end_src
 
-    - Gentoo
-      #+begin_src shell
-        emerge --ask xmobar
-      #+end_src
+   - Gentoo
+     #+begin_src shell
+       emerge --ask xmobar
+     #+end_src
 
-*** Using cabal-install
+** Using cabal-install
 
-    Xmobar is available from [[http://hackage.haskell.org/package/xmobar/][Hackage]], and you can install it using
-    =cabal-install=:
+   Xmobar is available from [[http://hackage.haskell.org/package/xmobar/][Hackage]], and you can install it using
+   =cabal-install=:
 
-    #+begin_src shell
-      cabal install xmobar
-    #+end_src
+   #+begin_src shell
+     cabal install xmobar
+   #+end_src
 
-    Starting with version 0.35.1, xmobar now requires at least GHC
-    version 8.4.x. to build. See [[https://codeberg.org/xmobar/xmobar/issues/461][this issue]] for more information.
+   Starting with version 0.35.1, xmobar now requires at least GHC
+   version 8.4.x. to build. See [[https://codeberg.org/xmobar/xmobar/issues/461][this issue]] for more information.
 
-    See [[file:doc/compiling.org][compiling]] for a list of optional compilation flags that will
-    enable some optional plugins. For instance, to install xmobar with
-    all the bells and whistles (this is probably what you want), use:
+   See [[file:doc/compiling.org][compiling]] for a list of optional compilation flags that will
+   enable some optional plugins. For instance, to install xmobar with
+   all the bells and whistles (this is probably what you want), use:
 
-    #+begin_src shell
-      cabal install xmobar --flags="all_extensions"
-    #+end_src
+   #+begin_src shell
+     cabal install xmobar --flags="all_extensions"
+   #+end_src
 
-*** From source
+** From source
 
-    See [[file:doc/compiling.org][compiling]].
+   See [[file:doc/compiling.org][compiling]].
 
 * Running xmobar
-*** Running xmobar with a configuration file
-  You can run xmobar with:
-
-  #+begin_src shell
-    xmobar /path/to/config &
-  #+end_src
-
-  or
-
-  #+begin_src shell
-    xmobar &
-  #+end_src
-
-  if you have the default configuration file saved as
-  =$XDG_CONFIG_HOME/xmobar/xmobarrc= (defaulting to
-  =~/.config/xmobar/xmobarrc=), or =~/.xmobarrc=.
-
-*** Writing your own xmobar in Haskell
-    :PROPERTIES:
-    :CUSTOM_ID: xmobar-in-haskell
-    :END:
-
-    It is possible to install xmobar as a library and use it to write your own
-    xmobar using Haskell instead of using a configuration file.  (This is very
-    similar to how [[http://xmonad.org][xmonad]] works.)
-
-    Make sure that ~ghc~ will be able to locate the xmobar library, e.g. with
-
-    #+begin_src shell
-      cabal install --lib xmobar
-    #+end_src
-
-    and then write your Haskell configuration and main function using the
-    functions and types exported in the library, which closely resemble those
-    used in configuration files.  Here's a small example:
-
-    #+begin_src haskell
-      import Xmobar
-
-      config :: Config
-      config =
-        defaultConfig
-          { font = "xft:Terminus-8",
-            allDesktops = True,
-            alpha = 200,
-            commands =
-              [ Run XMonadLog,
-                Run $ Memory ["t", "Mem: <usedratio>%"] 10,
-                Run $ Kbd [],
-                Run $ Date "%a %_d %b %Y <fc=#ee9a00>%H:%M:%S</fc>" "date" 10
-              ],
-            template = "%XMonadLog% }{ %kbd% | %date% | %memory%",
-            alignSep = "}{"
-          }
-
-      main :: IO ()
-      main = xmobar config
-    #+end_src
-
-    You can then for instance run =ghc --make xmobar.hs= to create a new xmobar
-    executable running exactly the monitors defined above.  Or put your
-    =xmobar.hs= program in =~/.config/xmobar/xmobar.hs= and, when running the
-    system-wide xmobar, it will notice that you have your own implementation
-    and (re)compile and run it as needed.  See also this [[./examples/xmobar.hs][extended example]].
-
-*** Running xmobar in text mode
-
-    By default, xmobar will run as an X11 application, in a docked
-    window, but it is possible to redirect xmobar's to the standard
-    output, optionally with color escape sequences.  In this mode,
-    xmobar can be run inside a terminal o console, or its output piped
-    to other applications, and there is no need for an X11 display
-    (so, for instance, you could pipe xmobar's output to a Wayland
-    application, such as swaybar.)
-
-    To run xmobar in text mode, either pass the =-T= flag to its
-    invocation:
-
-    #+begin_src shell
-      xmobar -T /path/to/config &
-    #+end_src
-
-    or set the parameter =textOutput= to True in its configuration.  You
-    can also specify the format of color escapes, for instance,
-    omitting them altogether with ~Plain~:
-
-    #+begin_src shell
-      xmobar -TPlain /path/to/config &
-    #+end_src
-
-    Other options are ~Ansi~, ~Pango~, and ~Swaybar~.
-
-*** Using xmobar in Wayland with swaybar or waybar
-
-    In text mode, xmobar can be told to ouput its information using
-    pango markup for colors and fonts, and it that way you can use it
-    with swaybar or waybar, if you don't have actions or boxes in your
-    template.  Here's a minimal ~bar~ configuration for sway's
-    configuration file:
-
-    #+begin_src conf
-      bar {
-        status_command xmobar -TPango
-        pango_markup enabled
-      }
-    #+end_src
-
-    In case you want to use boxes around text or click actions in your
-    template, you can use instead the format ~Swaybar~, which supports
-    both.  This output format follows the JSON /swaybar-protocol/
-    defined by swaybar.  Configure it simply with:
-
-    #+begin_src conf
-      bar {
-        status_command xmobar -TSwaybar
-      }
-    #+end_src
+** Running xmobar with a configuration file
+   You can run xmobar with:
+
+   #+begin_src shell
+     xmobar /path/to/config &
+   #+end_src
+
+   or
+
+   #+begin_src shell
+     xmobar &
+   #+end_src
+
+   if you have the default configuration file saved as
+   =$XDG_CONFIG_HOME/xmobar/xmobarrc= (defaulting to =~/.config/xmobar/xmobarrc=),
+   or =~/.xmobarrc=.
+
+   All the available command line switches and configuration parameters are
+   described in [[file:quick-start.org][the quick start guide]] and [[file:plugins.org][the plugins documentation]].
+** Writing your own xmobar in Haskell
+
+   One can use ~xmobar~ as a regular program, via its configuration file,
+   without having to write any code. It also is possible to install xmobar as
+   a library and use it to write your own xmobar using Haskell instead of
+   using a configuration file.  (This is very similar to how [[http://xmonad.org][xmonad]] works.)
+   That gives you the ability of using Haskell and its libraries to extend
+   xmobar to your heart's content. If you are a programmer, take a look at
+   [[file:doc/using-haskell.org][here]] to learn more.
+
+** Running xmobar in text mode
+
+   By default, xmobar will run as an X11 application, in a docked
+   window, but it is possible to redirect xmobar's to the standard
+   output, optionally with color escape sequences.  In this mode,
+   xmobar can be run inside a terminal o console, or its output piped
+   to other applications, and there is no need for an X11 display
+   (so, for instance, you could pipe xmobar's output to a Wayland
+   application, such as swaybar.)
+
+   To run xmobar in text mode, either pass the =-T= flag to its
+   invocation:
+
+   #+begin_src shell
+     xmobar -T /path/to/config &
+   #+end_src
+
+   or set the parameter =textOutput= to True in its configuration.  You
+   can also specify the format of color escapes, for instance,
+   omitting them altogether with ~Plain~:
+
+   #+begin_src shell
+     xmobar -TPlain /path/to/config &
+   #+end_src
+
+   Other options are ~Ansi~, ~Pango~, and ~Swaybar~.
+
+** Using xmobar in Wayland with swaybar or waybar
+
+   In text mode, xmobar can be told to ouput its information using
+   pango markup for colors and fonts, and it that way you can use it
+   with swaybar or waybar, if you don't have actions or boxes in your
+   template.  Here's a minimal ~bar~ configuration for sway's
+   configuration file:
+
+   #+begin_src conf
+     bar {
+     status_command xmobar -TPango
+     pango_markup enabled
+     }
+   #+end_src
+
+   In case you want to use boxes around text or click actions in your
+   template, you can use instead the format ~Swaybar~, which supports
+   both.  This output format follows the JSON /swaybar-protocol/
+   defined by swaybar.  Configure it simply with:
+
+   #+begin_src conf
+     bar {
+     status_command xmobar -TSwaybar
+     }
+   #+end_src
 
 * Configuration and further Links
 
@@ -221,7 +185,7 @@ channel, ~#xmobar~, at [[ircs://irc.libera.chat][Libera]].
   - If you want to know how to contribute to the xmobar project, check out
     [[contributing.org][contributing]].
 
-  - If you want to write your own plugins, see [[./doc/write-your-own-plugin.org][Write your own plugin]].
+  - If you want to write your own plugins, see [[./doc/using-haskell.org#writing-a-plugin][writing a plugin]].
 
   - For elaborated examples of how to use xmobar as a Haskell library
     to create your monitors, see [[https://codeberg.org/jao/xmobar-config][this repo at jao/xmobar-config]].
@@ -264,9 +228,9 @@ channel, ~#xmobar~, at [[ircs://irc.libera.chat][Libera]].
 
 * License
 
-This software is released under a BSD-style license. See [[https://codeberg.org/xmobar/xmobar/src/branch/master/license][license]] for more
-details.
+  This software is released under a BSD-style license. See [[https://codeberg.org/xmobar/xmobar/src/branch/master/license][license]] for more
+  details.
 
-Copyright © 2010-2022 Jose Antonio Ortega Ruiz
+  Copyright © 2010-2022 Jose Antonio Ortega Ruiz
 
-Copyright © 2007-2010 Andrea Rossato
+  Copyright © 2007-2010 Andrea Rossato