From a7e2bb9dfbf23fe6bd7c7cd4f45d039536f05d99 Mon Sep 17 00:00:00 2001
From: jao <jao@gnu.org>
Date: Sun, 24 Jul 2022 17:34:27 +0100
Subject: documentation: text mode moved to quick start guide

---
 doc/quick-start.org | 71 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 63 insertions(+), 8 deletions(-)

(limited to 'doc/quick-start.org')

diff --git a/doc/quick-start.org b/doc/quick-start.org
index 5ae9d1a..c214fdf 100644
--- a/doc/quick-start.org
+++ b/doc/quick-start.org
@@ -1,13 +1,11 @@
 #+title: Quick start: using xmobar
 
-Xmobar can either be configured using the configuration language, or
-used as a Haskell library (similar to xmonad) and compiled with your
-specific configuration. For an example of the latter, you can have a
-loot at [[../examples/xmobar.hs][examples/xmobar.hs]] or, for a more complicated example, peruse
-[[https://gitlab.com/jaor/xmobar-config/][the author's configuration]].
-
-There is also an example of a config using the configuration language
-available [[https://codeberg.org/xmobar/xmobar/src/branch/master/examples/xmobar.config][here]].
+Xmobar can either be configured using the configuration language, or [[file:using-haskell.org][used as a
+Haskell library]] (similar to xmonad) and compiled with your specific
+configuration. For an example of a configuration file using the plain
+configuration language, see [[file:~/usr/jao/xmobar/xmobar/examples/xmobar.config][examples/xmobar.config]], and you can have a look at
+[[../examples/xmobar.hs][examples/xmobar.hs]] for an example of how to write your own xmobar using
+Haskell.
 
 * Command Line Options
 
@@ -404,6 +402,63 @@ available [[https://codeberg.org/xmobar/xmobar/src/branch/master/examples/xmobar
    See below.
 
 * Runtime behaviour
+** Running xmobar in text mode
+   :PROPERTIES:
+   :CUSTOM_ID: text-mode
+   :END:
+
+   By default, xmobar will run as an X11 application, in a docked window, but
+   it is possible to redirect xmobar's output 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
+   :PROPERTIES:
+   :CUSTOM_ID: wayland
+   :END:
+
+   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 =i3status=
 
    xmobar can be used to display information generated by [[http://i3wm.org/i3status/][i3status]], a small
-- 
cgit v1.2.3