Documentation bits

3 files changed, 108 insertions, 72 deletions

diff --git a/changelog.md b/changelog.md
index 80fab20..a575e53 100644
--- a/changelog.md
+++ b/changelog.md
@@ -1,3 +1,7 @@
+## Version 0.42 (unreleased)
+
+  - New text mode (thanks to Pavel Kagulin, see issue #601)
+
 ## Version 0.41 (January, 2022)
 
 _New features_
diff --git a/doc/quick-start.org b/doc/quick-start.org
index c51be3e..2f8591d 100644
--- a/doc/quick-start.org
+++ b/doc/quick-start.org
@@ -157,6 +157,15 @@ the =Config= block in your configuration.
 - =wmName= The value for the window's X11 WM_NAME property. Defaults to
   "xmobar".
 
+- =textOutput= When True, instead of running as an X11 application,
+  write output to stdout, with optional color escape sequences.  In
+  this mode, icon and action specifications are ignored.  Default is
+  False.
+
+- =textOutputColors= NoColors, Ansi or Pango, to emit, when in text
+  mode, escape color sequences using ANSI controls (for terminals) or
+  pango markup.  Default is Ansi.
+
 ** The Output =template=
 
 The output template is how xmobar will end up printing all of your
@@ -374,6 +383,7 @@ This is the list of command line options (the output of =xmobar --help=):
     -C command    --add-command=command  Add to the list of commands to be executed
     -x screen     --screen=screen        On which X screen number to start
     -p position   --position=position    Specify position of xmobar. Same syntax as in config file
+    -T            --text                 Write output to stdout
 
   Mail bug reports and suggestions to <mail@jao.io>
 #+end_src
diff --git a/readme.org b/readme.org
index fb4845f..36ad94a 100644
--- a/readme.org
+++ b/readme.org
@@ -8,7 +8,8 @@
 
   Xmobar was inspired by the [[http://tuomov.iki.fi/software/][Ion3]] status bar, and supports similar
   features, like dynamic color management, icons, output templates,
-  and extensibility through plugins.
+  and extensibility through plugins.  It is also able to write to
+  standard output, optionally with color escape sequences.
 
   These are some xmobar [[file:doc/screenshots][screenshots]] using the author's configuration:
 
@@ -18,67 +19,68 @@
 
 [[file:doc/screenshots/xmobar-exwm.png]]
 
-  Check the [[./changelog.md][the change log]] for our release history.
+  Check [[./changelog.md][the change log]] for our release history.  We also have an IRC
+  channel, ~#xmobar~ at [[ircs://irc.libera.chat][Libera]].
 
 * Installation
-** 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
+***** Arch Linux
 
-#+begin_src shell
-  pacman -S xmobar
-#+end_src
+  #+begin_src shell
+    pacman -S xmobar
+  #+end_src
 
-*** Debian/Ubuntu based
+***** Debian/Ubuntu based
 
-#+begin_src shell
-  apt install xmobar
-#+end_src
+  #+begin_src shell
+    apt install xmobar
+  #+end_src
 
-*** OpenSUSE
+***** OpenSUSE
 
-#+begin_src shell
-  zypper install xmobar
-#+end_src
+  #+begin_src shell
+    zypper install xmobar
+  #+end_src
 
-*** Void Linux
+***** Void Linux
 
-#+begin_src shell
-  xbps-install xmobar
-#+end_src
+  #+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://github.com/jaor/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://github.com/jaor/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
 
@@ -98,6 +100,25 @@
   =$XDG_CONFIG_HOME/xmobar/xmobarrc= (defaulting to
   =~/.config/xmobar/xmobarrc=), or =~/.xmobarrc=.
 
+*** 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 waybar.)
+
+    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.
+
 * Configuration and further Links
 
   - If you want to jump straight into configuring xmobar, head over to the
@@ -125,36 +146,37 @@
   Ben Boeckel, Ivan Brennan, Duncan Burke, Roman Cheplyaka, Patrick
   Chilton, Antoine Eiche, Nathaniel Wesley Filardo, Guy Gastineau,
   John Goerzen, Reto Hablützel, Juraj Hercek, Tomáš Janoušek, Ada
-  Joule, Spencer Janssen, Roman Joost, Jochen Keil, Sam Kirby, Lennart
-  Kolmodin, Krzysztof Kosciuszkiewicz, Dmitry Kurochkin, Todd Lunter,
-  Vanessa McHale, Robert J. Macomber, Dmitry Malikov, David McLean,
-  Joan MIlev, Marcin Mikołajczyk, Dino Morelli, Tony Morris, Eric
-  Mrak, Thiago Negri, Edward O'Callaghan, Svein Ove, Martin Perner,
-  Jens Petersen, Alexander Polakov, Sibi Prabakaran, Pavan Rikhi, Petr
-  Rockai, Andrew Emmanuel Rosa, Sackville-West, Amir Saeid, Markus
-  Scherer, Daniel Schüssler, Olivier Schneider, Alexander Shabalin,
-  Valentin Shirokov, Peter Simons, Alexander Solovyov, Will Song, John
-  Soo, John Soros, Felix Springer, Travis Staton, Artem Tarasov,
-  Samuli Thomasson, Edward Tjörnhammar, Sergei Trofimovich, Thomas
-  Tuegel, John Tyree, Jan Vornberger, Anton Vorontsov, Daniel Wagner,
-  Zev Weiss, Phil Xiaojun Hu, Nikolay Yakimov, Edward Z. Yang, Leo
-  Zhang, Norbert Zeh, and Michal Zielonka.
-
-** Thanks
-
-*Andrea Rossato*:
-
-Thanks to Robert Manea and Spencer Janssen for their help in
-understanding how X works. They gave me suggestions on how to solve many
-problems with xmobar.
-
-Thanks to Claus Reinke for make me understand existential types (or at
-least for letting me think I grasp existential types...;-).
-
-*jao*:
-
-Thanks to Andrea for creating xmobar in the first place, and for giving
-me the chance to contribute.
+  Joule, Spencer Janssen, Roman Joost, Pavel Kalugin, Jochen Keil, Sam
+  Kirby, Lennart Kolmodin, Krzysztof Kosciuszkiewicz, Dmitry
+  Kurochkin, Todd Lunter, Vanessa McHale, Robert J. Macomber, Dmitry
+  Malikov, David McLean, Joan MIlev, Marcin Mikołajczyk, Dino Morelli,
+  Tony Morris, Eric Mrak, Thiago Negri, Edward O'Callaghan, Svein Ove,
+  Martin Perner, Jens Petersen, Alexander Polakov, Sibi Prabakaran,
+  Pavan Rikhi, Petr Rockai, Andrew Emmanuel Rosa, Sackville-West, Amir
+  Saeid, Markus Scherer, Daniel Schüssler, Olivier Schneider,
+  Alexander Shabalin, Valentin Shirokov, Peter Simons, Alexander
+  Solovyov, Will Song, John Soo, John Soros, Felix Springer, Travis
+  Staton, Artem Tarasov, Samuli Thomasson, Edward Tjörnhammar, Sergei
+  Trofimovich, Thomas Tuegel, John Tyree, Jan Vornberger, Anton
+  Vorontsov, Daniel Wagner, Zev Weiss, Phil Xiaojun Hu, Nikolay
+  Yakimov, Edward Z. Yang, Leo Zhang, Norbert Zeh, and Michal
+  Zielonka.
+
+*** Thanks
+
+  *Andrea Rossato*:
+
+  Thanks to Robert Manea and Spencer Janssen for their help in
+  understanding how X works. They gave me suggestions on how to solve many
+  problems with xmobar.
+
+  Thanks to Claus Reinke for make me understand existential types (or at
+  least for letting me think I grasp existential types...;-).
+
+  *jao*:
+
+  Thanks to Andrea for creating xmobar in the first place, and for giving
+  me the chance to contribute.
 
 
 * License