docs: compilation instructions clean ups

2 files changed, 101 insertions, 88 deletions

diff --git a/doc/compiling.org b/doc/compiling.org
index 6c707e5..4e0125e 100644
--- a/doc/compiling.org
+++ b/doc/compiling.org
@@ -1,104 +1,114 @@
-#+title: Compiling xmobar from source
+#+title: Compiling xmobar
 
-If you don't have =cabal-install= installed, you can get xmobar's source
-code in a variety of ways:
+* Getting the source
 
-- From [[http://hackage.haskell.org/package/xmobar/][Hackage]]. Just download the latest release from xmobar's hackage
-  page.
+  If you don't have =cabal-install= installed, you can get xmobar's source
+  code in a variety of ways:
 
-- From [[http://codeberg.org/xmobar/xmobar/][Codeberg]]. There are also tarballs available for every tagged
-  release on [[https://codeberg.org/xmobar/xmobar/releases][Codeberg's releases page]]
+  - From [[http://hackage.haskell.org/package/xmobar/][Hackage]]. Just download the latest release from xmobar's hackage
+    page.
 
-- From the bleeding edge repo. If you prefer to live dangerously, just
-  get the latest and greatest (and buggiest, I guess) using git:
+  - From [[http://codeberg.org/xmobar/xmobar/][Codeberg]]. There are also tarballs available for every tagged
+    release on [[https://codeberg.org/xmobar/xmobar/releases][Codeberg's releases page]]
+
+  - From the bleeding edge repo. If you prefer to live dangerously, just
+    get the latest and greatest (and buggiest, I guess) using git:
+
+    #+begin_src shell
+      git clone git://codeberg.org/xmobar/xmobar
+    #+end_src
+
+* C library dependencies
+  :PROPERTIES:
+  :CUSTOM_ID: c-libraries
+  :END:
+
+  To build xmobar you will need the Xorg and Pango/Cairo C-libraries and
+  headers installed in your system.  In Debian and derivatives that's easily
+  accomplished via
 
   #+begin_src shell
-    git clone git://codeberg.org/xmobar/xmobar
+    apt-get install -y xorg-dev libxrandr-dev libpango1.0-dev
   #+end_src
 
-If you have cabal installed, you can now use it from within xmobar's
-source tree:
-
-#+begin_src shell
-  cabal install --flags="all_extensions"
-#+end_src
+  and, optionally, in order to be able to build all available extensions and
+  plugins:
 
-There is also a =stack.yaml= file that will allow you to install the
-xmobar executable with
+  #+begin_src shell
+    apt-get install -y libasound2-dev libxpm-dev libmpd-dev
+  #+end_src
 
-#+begin_src shell
-  stack install
-#+end_src
+* Compilation using cabal
 
-See the =stack.yaml= file for the enabled extensions. You can also pass
-them to =stack= directly:
+  If you have cabal installed, you can now use it from within xmobar's source
+  tree:
 
-#+begin_src shell
-  stack install --flag xmobar:all_extensions
-#+end_src
+  #+begin_src shell
+    cabal install --flags="all_extensions"
+  #+end_src
 
-** Optional features
-   :PROPERTIES:
-   :CUSTOM_ID: optional-features
-   :END:
+* Compilation using stack
 
-   You can configure xmobar to include some optional plugins and
-   features, which are not compiled by default. To that end, you need
-   to add one or more flags to either the cabal install command or
-   the configure setup step, as shown in the examples above.
+  There is also a =stack.yaml= file that will allow you to install the
+  xmobar executable with
 
-   Extensions need additional libraries (listed below) that will be
-   automatically downloaded and installed if you're using cabal
-   install.  Otherwise, you'll need to install them yourself.
+  #+begin_src shell
+    stack install
+  #+end_src
 
-   - =with_dbus= Enables support for DBUS by making xmobar to publish a
-     service on the session bus. Requires the [[http://hackage.haskell.org/package/dbus][dbus]] package.
+  See the =stack.yaml= file for the enabled extensions. You can also pass
+  them to =stack= directly:
 
-   - =with_threaded= Uses GHC's threaded runtime. Use this option if xmobar
-     enters a high-CPU regime right after starting.
+  #+begin_src shell
+    stack install --flag xmobar:all_extensions
+  #+end_src
 
-   - =with_cairo= Antialiased fonts via Cairo/Pango. For fonts, you can use
-     their fontconfig name, e.g
+* Compilation flags
+  :PROPERTIES:
+  :CUSTOM_ID: optional-features
+  :END:
 
-     #+begin_src haskell
-       font = "Iosevka Medium 10"
-       font = "DejaVu Sans Mono italic 9"
-     #+end_src
+   You can configure xmobar to include some optional plugins and features,
+   which are not compiled by default. To that end, you need to add one or more
+   flags to either the cabal install command or the configure setup step.
 
-     Or to have fallback fonts, just separate them by commas:
+   Extensions need additional Haskell packages (listed below) that will be
+   automatically downloaded and installed if you're using cabal install.
+   Otherwise, you'll need to install them yourself.
 
-     #+begin_src haskell
-       font = "Open Sans,WenQuanYi Zen Hei 9"
-     #+end_src
+** Optional features
 
-     For backwards compatibility, font names with `xft:` are also supported.
+   - =with_dbus= Enables support for DBUS by making xmobar to publish a
+     service on the session bus. Requires the [[http://hackage.haskell.org/package/dbus][dbus]] package.
 
-     #+begin_src haskell
-       font = "xft:DejaVu Sans Mono-10"
-     #+end_src
+   - =with_threaded= Uses GHC's threaded runtime. Use this option if xmobar
+     enters a high-CPU regime right after starting.
 
    - =with_xrender= Enables the main bar background alpha parameter.  Requires
      the [[http://hackage.haskell.org/package/X11-xft/][X11-xft]] package.
 
+   - =with_xpm= Support for xpm image file format. This will allow loading
+     .xpm files in =<icon>=. Requires the [[http://cgit.freedesktop.org/xorg/lib/libXpm][libXpm]] C library.
+
+** Optional plugins
+
+   The following plugins and monitors are optional.  You can enable them all
+   at once using the flag ~all_extensions~, or one by one with the following
+   flags:
+
    - =with_mpd= Enables support for the [[http://mpd.wikia.com/][MPD]] daemon. Requires the [[http://hackage.haskell.org/package/libmpd/][libmpd]]
      package.
 
-   - =with_mpris= Enables support for MPRIS v1/v2 protocol. Requires the
-     [[http://hackage.haskell.org/package/dbus][dbus]] and [[http://hackage.haskell.org/package/text][text]] packages.
+   - =with_mpris= Enables support for MPRIS v1/v2 protocol used by the plugins
+     of the same name. Requires the [[http://hackage.haskell.org/package/dbus][dbus]] and [[http://hackage.haskell.org/package/text][text]] packages.
 
-   - =with_inotify= Support for inotify in modern Linux kernels. This
-     option is needed for the MBox and Mail plugins to work. Requires the
-     [[http://hackage.haskell.org/package/hinotify/][hinotify]] package.
+   - =with_inotify= Support for inotify in modern Linux kernels. This option is
+     needed for the ~MBox~ and ~Mail~ plugins to work. Requires the [[http://hackage.haskell.org/package/hinotify/][hinotify]]
+     package.
 
    - =with_nl80211= Support for wireless cards on Linux via nl80211 (all
-     upstream drivers). Enables the Wireless plugin. Requires [netlink] and
-     [cereal] packages.
-
-   - =with_iwlib= Support for wireless cards via Wext ioctls (deprecated).
-     Enables the Wireless plugin. No Haskell library is required, but you
-     will need the [[http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html][iwlib]] C library and headers in your system (e.g.,
-     install =libiw-dev= in Debian-based systems or =wireless_tools= on
-     Arch Linux). Conflicts with =with_nl80211=.
+     upstream drivers). Enables the ~Wireless~ plugin. Requires [[http://hackage.haskell.org/package/netlink][netlink]] and
+     [[http://hackage.haskell.org/package/cereal/][cereal]] packages.
 
    - =with_alsa= Support for ALSA sound cards. Enables the Volume plugin.
      Requires the [[http://hackage.haskell.org/package/alsa-mixer][alsa-mixer]] package.  To install the latter, you'll need
@@ -108,13 +118,17 @@ them to =stack= directly:
    - =with_datezone= Support for other timezones. Enables the DateZone
      plugin. Requires [[http://hackage.haskell.org/package/timezone-olson][timezone-olson]] and [[http://hackage.haskell.org/package/timezone-series][timezone-series]] package.
 
-   - =with_xpm= Support for xpm image file format. This will allow loading
-     .xpm files in =<icon>=. Requires the [[http://cgit.freedesktop.org/xorg/lib/libXpm][libXpm]] C library.
+   - =with_weather= Support to display weather information. Enables Weather
+     plugin.
 
-   - =with_uvmeter= Enables UVMeter plugin. The plugin shows UV data for
+   Finally, the following flags enable plugins not included by ~all_extensions~:
+
+   - =with_uvmeter= Enables the ~UVMeter~ plugin. The plugin shows UV data for
      Australia.
 
-   - =with_weather= Support to display weather information. Enables Weather
-     plugin.
+   - =with_kraken= Enables the ~Kraken~ plugin.
 
-   - =all_extensions= Enables all the extensions above.
+   - =with_iwlib= Support for wireless cards via Wext ioctls (deprecated).
+     Enables the ~Wireless~ plugin. You will need the [[http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html][iwlib]] C library and
+     headers in your system (e.g., install =libiw-dev= in Debian-based systems
+     or =wireless_tools= on Arch Linux). Conflicts with =with_nl80211=.
diff --git a/readme.org b/readme.org
index ee93fdc..f9226e9 100644
--- a/readme.org
+++ b/readme.org
@@ -64,29 +64,28 @@ channel, ~#xmobar~, at [[ircs://irc.libera.chat][Libera]].
        emerge --ask xmobar
      #+end_src
 
-** Using cabal-install
+** Using cabal or stack
 
-   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 compile and install it using
+   =cabal-install=, making sure the [[doc/compiling.org#c-libraries][required C libraries]] are in place. For a
+   full build with all available extensions:
 
    #+begin_src shell
-     cabal install xmobar
+     # required C librarises
+     apt-get install xorg-dev libxrandr-dev libpango1.0-dev
+     # optional C libraries for additional plugins
+     apt-get install libasound2-dev libxpm-dev libmpd-dev
+
+     cabal install xmobar -fall_extensions
    #+end_src
 
-   Starting with version 0.35.1, xmobar now requires at least GHC version
+   Starting with version 0.35.1, xmobar 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#optional-features][here]] 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
-
-** From source
+   optional plugins.
 
-   See [[file:doc/compiling.org][compiling]].
+   See [[file:doc/compiling.org][compiling]] for full compilation instructions starting from source.
 
 * Running xmobar
 ** Running xmobar with a configuration file