Split out contributing and quick-start part from readme

The contributing.org file also contains information on how to write a
new monitor for xmobar.

The quick-start guide got reworked a bit to inline similar parts.

4 files changed, 498 insertions, 428 deletions

diff --git a/contributing.org b/contributing.org
new file mode 100644
index 0000000..4a59145
--- /dev/null
+++ b/contributing.org
@@ -0,0 +1,119 @@
+* Contributing Changes/Patches to xmobar
+
+Want to contribute to xmobar? You've come to the right place! This
+document will help guide you in this endeavour.
+
+In case you want to make any non-trivial change to xmobar, it's always
+best to talk with the community first. Currently the best way to do that
+is to create an issue on GitHub. There, you can talk through the
+problems you are having, as well as the proposed solution.
+
+** Making the Change
+
+It's best to create a separate branch in your clone of the [[https://github.com/jaor/xmobar/][xmobar repo]]
+and then push this branch to your fork.
+
+If your pull request undergoes several iterations and =master= has
+changed in the meantime, you may be asked to rebase on top of it; in
+this case please don't merge any branches, but actually rebase! This is
+a very nifty feature that =git= offers in order to remain a clean
+history.
+
+Give your commits descriptive names!  Further, it's also highly recommended to
+add a description of /why/ you made a certain change.  The syntax for this is
+*commit message*, blank line, *more description*.  For example:
+
+  #+begin_src shell
+    Commit Message (max. 50 characters)
+
+    Some more useful information of why this change was made; possibly
+    how it connects with other commits in this same pr (wrapped at 72
+    characters).
+  #+end_src
+
+** Opening a Pull Request
+
+Once you have pushed the branch to your fork, making a pull request is
+as easy as visiting that branch; GitHub will then even prompt you for
+it!
+
+Please include the following information in the description of your pull
+request:
+
+- Does your pull request close, or is related to, any existing issues?
+- What does your pull request do?  If you add a new feature, an example
+  of how you would use it would be most appreciated.
+- 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 you should update the [[./doc/plugins.org][plugins documentation]].
+
+* Writing Your Own 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 1 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 [[https://github.com/jaor/xmobar/blob/master/examples/xmobar.hs][examples/xmobar.hs]] for an example of
+a plugin that runs just once, and [[https://github.com/jaor/xmobar/blob/master/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
+
+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.
+
+** Using a Plugin
+
+To use your new plugin, you need to use a pure Haskell configuration for
+xmobar, and load your definitions there. 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/plugins.org b/doc/plugins.org
index f4d0754..59be7fd 100644
--- a/doc/plugins.org
+++ b/doc/plugins.org
@@ -7,9 +7,18 @@ xmobar. Some of them are only installed when an optional build option is
 set: we mention that fact, when needed, in their description.
 
 Each monitor has an =alias= to be used in the output template. Monitors
-have default aliases. The sections below describe every monitor in turn,
-but before we provide a list of the configuration options (or /monitor
-arguments/) they all share.
+may have default aliases, see the documentation of the monitor in
+question.
+
+There are two types of arguments: ones that all monitors share (the so
+called /default monitor arguments/) and arguments that are specific to a
+certain monitor.
+
+All Monitors accept a common set of arguments, described below in
+[[Default Monitor Arguments]]. Some monitors also accept additional options
+that are specific to them. When specifying the list of arguments in your
+configuration, the common options come first, followed by =--=, followed
+by any monitor-specific options.
 
 ** Icon patterns
 
@@ -34,13 +43,7 @@ brightness value.
 
 ** Default Monitor Arguments
 
-Monitors accept a common set of arguments, described in the first
-subsection below. In addition, some monitors accept additional options
-that are specific to them. When specifying the list of arguments in your
-configuration, the common options come first, followed by =--=, followed
-by any monitor-specific options.
-
-These are the options available for all monitors below:
+These are the options available for all monitors:
 
 - =-t= /string/ Output template
 
@@ -1544,78 +1547,3 @@ unmap events as well (which =docksEventHook= doesn't).
       where w  = ev_window e
           et = ev_event_type e
 #+end_src
-
-* User plugins
-** Writing a Plugin
-
-Writing a plugin for xmobar should be very simple. 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 1 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 [[https://github.com/jaor/xmobar/blob/master/examples/xmobar.hs][examples/xmobar.hs]] for an example of
-a plugin that runs just once, and [[https://github.com/jaor/xmobar/blob/master/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
-
-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.
-
-** Using a Plugin
-
-To use your new plugin, you need to use a pure Haskell configuration for
-xmobar, and load your definitions there. 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!
-
-** Configurations written in pure Haskell
-
-xmobar can be used as a pure Haskell program, that is compiled with your
-specific configuration, expressed as Haskell source code. For an
-example, see [[https://gitlab.com/jaor/xmobar-config/][the author's configuration]].
diff --git a/doc/quick-start.org b/doc/quick-start.org
new file mode 100644
index 0000000..596d043
--- /dev/null
+++ b/doc/quick-start.org
@@ -0,0 +1,361 @@
+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 [[http://github.com/jaor/xmobar/raw/master/examples/xmobar.config][here]].
+
+* Configuration Options
+
+Here are all the global configuration options that you can set within
+the =Config= block in your configuration.
+
+- =font= Name of the font to be used. Use the =xft:= prefix for XFT
+  fonts.
+
+- =additionalFonts= Haskell-style list of fonts to be used with the
+  =fn=-template. Use the =xft:= prefix for XFT fonts. See also
+  =textOffsets= below. For example:
+
+  #+begin_src haskell
+    additionalFonts = [iconFont, altIconFont]
+  #+end_src
+
+- =bgColor= Background color.
+
+- =fgColor= Default font color.
+
+- =alpha= The transparency. 0 is transparent, 255 is opaque.
+
+- =position= Top, TopP, TopW, TopSize, Bottom, BottomP, BottomW,
+  BottomSize or Static (with x, y, width and height).
+
+  TopP and BottomP take 2 arguments: left padding and right padding.
+
+  TopW and BottomW take 2 arguments: an alignment parameter (L for left,
+  C for centered, R for Right) and an integer for the percentage width
+  xmobar window will have in respect to the screen width.
+
+  TopSize and BottomSize take 3 arguments: an alignment parameter, an
+  integer for the percentage width, and an integer for the minimum pixel
+  height that the xmobar window will have.
+
+  For example:
+
+  #+begin_src haskell
+    position = BottomW C 75
+  #+end_src
+
+  to place xmobar at the bottom, centered with the 75% of the screen
+  width. Or
+
+  #+begin_src haskell
+    position = BottomP 120 0
+  #+end_src
+
+  to place xmobar at the bottom, with 120 pixel indent of the left. Or
+
+  #+begin_src haskell
+    position = Static { xpos = 0 , ypos = 0, width = 1024, height = 15 }
+  #+end_src
+
+  or
+
+  #+begin_src haskell
+    position = Top
+  #+end_src
+
+- =textOffset= The vertical offset, in pixels, for the text baseline. If
+  negative or not given, xmobar will try to center text vertically.
+
+- =textOffsets= A list of vertical offsets, in pixels, for the text
+  baseline, to be used with the each of the fonts in =additionalFonts=
+  (if any). If negative or not given, xmobar will try to center text
+  vertically for that font.
+
+- =iconOffset= The vertical offset, in pixels, for icons bottom line. If
+  negative or not given, xmobar will try to center icons vertically.
+
+- =lowerOnStart= When True the window is sent the bottom of the window
+  stack initially.
+
+- =hideOnStart= When set to True the window is initially not mapped,
+  i.e. hidden. It then can be toggled manually (for example using the
+  dbus interface) or automatically (by a plugin) to make it reappear.
+
+- =allDesktops= When set to True (the default), xmobar will tell the
+  window manager explicitly to be shown in all desktops, by setting
+  =_NET_WM_DESKTOP= to 0xffffffff.
+
+- =overrideRedirect= If you're running xmobar in a tiling window
+  manager, you might need to set this option to =False= so that it
+  behaves as a docked application. Defaults to =True=.
+
+- =pickBroadest= When multiple displays are available, xmobar will
+  choose by default the first one to place itself. With this flag set to
+  =True= (the default is =False=) it will choose the broadest one
+  instead.
+
+- =persistent= When True the window status is fixed i.e. hiding or
+  revealing is not possible. This option can be toggled at runtime.
+  Defaults to False.
+
+- =border= TopB, TopBM, BottomB, BottomBM, FullB, FullBM or NoBorder
+  (default).
+
+  TopB, BottomB, FullB take no arguments, and request drawing a border
+  at the top, bottom or around xmobar's window, respectively.
+
+  TopBM, BottomBM, FullBM take an integer argument, which is the margin,
+  in pixels, between the border of the window and the drawn border.
+
+- =borderColor= Border color.
+
+- =borderWidth= Border width in pixels.
+
+- =iconRoot= Root folder where icons are stored. For =<icon=path/>= if
+  path start with =/=, =./= or =../= it is interpreted as it is.
+  Otherwise it will have
+
+  #+begin_src haskell
+    iconRoot ++ "/"
+  #+end_src
+
+  prepended to it. Default is =.=.
+
+- =commands= For setting the options of the programs to run (optional).
+
+- =sepChar= The character to be used for indicating commands in the
+  output template (default '%').
+
+- =alignSep= a 2 character string for aligning text in the output
+  template. The text before the first character will be align to left,
+  the text in between the 2 characters will be centered, and the text
+  after the second character will be align to the right.
+
+- =template= The output template.
+
+- =wmClass= The value for the window's X11 WM_CLASS property. Defaults
+  to "xmobar".
+
+- =wmName= The value for the window's X11 WM_NAME property. Defaults to
+  "xmobar".
+
+** The Output =template=
+
+The output template is how xmobar will end up printing all of your
+configured commands. It must contain at least one command. Xmobar will
+parse the template and search for the command to be executed in the
+=commands= configuration option. First an =alias= will be searched (some
+plugins, such as =Weather= or =Network=, have default aliases, see the
+[[./plugins.org][plugin documentation]]).  After that, the command name will be tried. If a
+command is found, the arguments specified in the =commands= list will be
+used.
+
+If no command is found in the =commands= list, xmobar will ask the
+operating system to execute a program with the name found in the
+template. If the execution is not successful an error will be reported.
+
+The syntax for the output template is as follows:
+
+- =%command%= will execute command and print the output. The output may
+  contain markups to change the characters' color.
+
+- =<fc=#FF0000>string</fc>= will print =string= with =#FF0000= color
+  (red). =<fc=#FF0000,#000000>string</fc>= will print =string= in red
+  with a black background (=#000000=). Background absolute offsets can
+  be specified for XFT fonts. =<fc=#FF0000,#000000:0>string</fc>= will
+  have a background matching the bar's height.
+
+- =<box>string</box>= will print string surrounded by a box in the
+  foreground color. The =box= tag accepts several optional arguments to
+  tailor its looks:
+
+  - =type=: =Top=, =Bottom=, =VBoth= (a single line above or below
+    string, or both), =Left=, =Right=, =HBoth= (single vertical lines),
+    =Full= (a rectangle, the default).
+  - =color=: the color of the box lines.
+  - =width=: the width of the box lines.
+  - =offset=: an alignment char (L, C or R) followed by the amount of
+    pixels to offset the box lines; the alignment denotes the position
+    of the resulting line, with L/R meaning top/bottom for the vertical
+    lines, and left/right for horizontal ones.
+  - =mt=, =mb=, =ml=, =mr= specify margins to be added at the top,
+    bottom, left and right lines.
+
+  For example, a box underlining its text with a red line of width 2:
+
+  #+begin_src shell
+    <box type=Bottom width=2 color=red>string</box>
+  #+end_src
+
+  and if you wanted an underline and an overline with a margin of 2
+  pixels either side:
+
+  #+begin_src shell
+    <box type=VBoth mt=2 mb=2>string</box>
+  #+end_src
+
+- =<fn=1>string</fn>= will print =string= with the first font from
+  =additionalFonts=. The index =0= corresponds to the standard font.
+
+- =<icon=/path/to/icon.xbm/>= will insert the given bitmap. XPM image
+  format is also supported when compiled with the =with_xpm= flag.
+
+- =<action=`command` button=12345>= will execute given command when
+  clicked with specified buttons. If not specified, button is equal to 1
+  (left mouse button). Using old syntax (without backticks surrounding
+  =command=) will result in =button= attribute being ignored.
+
+- =<raw=len:str/>= allows the encapsulation of arbitrary text =str=
+  (which must be =len= =Char=s long, where =len= is encoded as a decimal
+  sequence). Careful use of this and =UnsafeStdinReader=, for example,
+  permits window managers to feed xmobar strings with =<action>= tags
+  mixed with un-trusted content (e.g. window titles). For example, if
+  xmobar is invoked as
+
+  #+begin_src shell
+    xmobar -c "[Run UnsafeStdinReader]" -t "%UnsafeStdinReader%"
+  #+end_src
+
+  and receives on standard input the line
+
+  #+begin_src shell
+    <action=`echo test` button=1><raw=41:<action=`echo mooo` button=1>foo</action>/></action>`
+  #+end_src
+
+  then it will display the text
+  =<action=`echo mooo` button=1>foo</action>=, which, when clicked, will
+  cause =test= to be echoed.
+
+*** Bitmap Icons
+
+It's possible to insert in the global templates icon directives of the
+form:
+
+#+begin_src shell
+  <icon=/path/to/bitmap.xbm/>
+#+end_src
+
+which will produce the expected result. Accepted image formats are XBM
+and XPM (when =with_xpm= flag is enabled). If path does not start with
+=/=, =./=, =../= it will have
+
+#+begin_src haskell
+  iconRoot ++ "/"
+#+end_src
+
+prepended to it.
+
+*** Action Directives
+
+It's also possible to use action directives of the form:
+
+#+begin_src shell
+  <action=`command` button=12345>
+#+end_src
+
+which will be executed when clicked on with specified mouse buttons.
+This tag can be nested, allowing different commands to be run depending
+on button clicked.
+
+** The =commands= Configuration Option
+
+The =commands= configuration option is a list of commands information
+and arguments to be used by xmobar when parsing the output template.
+Each member of the list consists in a command prefixed by the =Run=
+keyword. Each command has arguments to control the way xmobar is going
+to execute it.
+
+The option consists in a list of commands separated by a comma and
+enclosed by square parenthesis.
+
+Example:
+
+#+begin_src haskell
+  [Run Memory ["-t","Mem: <usedratio>%"] 10, Run Swap [] 10]
+#+end_src
+
+to run the Memory monitor plugin with the specified template, and the
+swap monitor plugin, with default options, every second. And here's an
+example of a template for the commands above using an icon:
+
+#+begin_src haskell
+  template = "<icon=/home/jao/.xmobar/mem.xbm/><memory> <swap>"
+#+end_src
+
+This example will run "xclock" command when date is clicked:
+
+#+begin_src haskell
+  template = "<action=`xclock`>%date%</action>"
+#+end_src
+
+The only internal available command is =Com= (see below Executing
+External Commands). All other commands are provided by plugins. xmobar
+comes with some plugins, providing a set of system monitors, a standard
+input reader, an Unix named pipe reader, a configurable date plugin, and
+much more: we list all available plugins below.
+
+Other commands can be created as plugins with the Plugin infrastructure.
+See below.
+** Running xmobar with =i3status=
+
+xmobar can be used to display information generated by [[http://i3wm.org/i3status/][i3status]], a small
+program that gathers system information and outputs it in formats
+suitable for being displayed by the dzen2 status bar, wmii's status bar
+or xmobar's =StdinReader=. See [[http://i3wm.org/i3status/manpage.html#_using_i3status_with_xmobar][i3status manual]] for further details.
+
+** Dynamically sizing xmobar
+
+See [[https://github.com/jaor/xmobar/issues/239#issuecomment-233206552][this idea]] by Jonas Camillus Jeppensen for a way of adapting
+dynamically xmobar's size and run it alongside a system tray widget such
+as trayer or stalonetray (although the idea is not limited to trays,
+really). For your convenience, there is a version of Jonas' script in
+[[./examples/padding-icon.sh][examples/padding-icon.sh]].
+
+* Command Line Options
+
+xmobar can be either configured with a configuration file or with
+command line options. In the second case, the command line options will
+overwrite the corresponding options set in the configuration file.
+
+Example:
+
+#+begin_src shell
+  xmobar -B white -a right -F blue -t '%LIPB%' -c '[Run Weather "LIPB" [] 36000]'
+#+end_src
+
+This is the list of command line options (the output of =xmobar --help=):
+
+#+begin_src shell
+  Usage: xmobar [OPTION...] [FILE]
+  Options:
+    -h, -?        --help                 This help
+    -v            --verbose              Emit verbose debugging messages
+    -r            --recompile            Force recompilation
+    -V            --version              Show version information
+    -f font name  --font=font name       Font name
+    -N font name  --add-font=font name   Add to the list of additional fonts
+    -w class      --wmclass=class        X11 WM_CLASS property
+    -n name       --wmname=name          X11 WM_NAME property
+    -B bg color   --bgcolor=bg color     The background color. Default black
+    -F fg color   --fgcolor=fg color     The foreground color. Default grey
+    -i path       --iconroot=path        Root directory for icon pattern paths. Default '.'
+    -A alpha      --alpha=alpha          Transparency: 0 is transparent, 255 is opaque. Default: 255
+    -o            --top                  Place xmobar at the top of the screen
+    -b            --bottom               Place xmobar at the bottom of the screen
+    -d            --dock                 Don't override redirect from WM and function as a dock
+    -a alignsep   --alignsep=alignsep    Separators for left, center and right text
+                                         alignment. Default: '}{'
+    -s char       --sepchar=char         Character used to separate commands in
+                                         the output template. Default '%'
+    -t template   --template=template    Output template
+    -c commands   --commands=commands    List of commands to be executed
+    -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
+
+  Mail bug reports and suggestions to <mail@jao.io>
+#+end_src
diff --git a/readme.org b/readme.org
index 0407bce..159c8da 100644
--- a/readme.org
+++ b/readme.org
@@ -204,351 +204,13 @@ Since 0.14 xmobar reacts to SIGUSR1 and SIGUSR2:
 - After receiving SIGUSR2 xmobar repositions itself on the current
   screen.
 
-* Configuration
-** Quick Start
+* Configuration and Further Links
 
-See [[http://github.com/jaor/xmobar/raw/master/examples/xmobar.config][examples/xmobar.config]] for an example.
+- If you want to jump straight into configuring xmobar, head over to the
+  [[./doc/quick-start.org][quick-start]] guide.
 
-For the output template:
-
-- =%command%= will execute command and print the output. The output may
-  contain markups to change the characters' color.
-
-- =<fc=#FF0000>string</fc>= will print =string= with =#FF0000= color
-  (red). =<fc=#FF0000,#000000>string</fc>= will print =string= in red
-  with a black background (=#000000=). Background absolute offsets can
-  be specified for XFT fonts. =<fc=#FF0000,#000000:0>string</fc>= will
-  have a background matching the bar's height.
-
-- =<box>string</box>= will print string surrounded by a box in the
-  foreground color. The =box= tag accepts several optional arguments to
-  tailor its looks:
-
-  - =type=: =Top=, =Bottom=, =VBoth= (a single line above or below
-    string, or both), =Left=, =Right=, =HBoth= (single vertical lines),
-    =Full= (a rectangle, the default).
-  - =color=: the color of the box lines.
-  - =width=: the width of the box lines.
-  - =offset=: an alignment char (L, C or R) followed by the amount of
-    pixels to offset the box lines; the alignment denotes the position
-    of the resulting line, with L/R meaning top/bottom for the vertical
-    lines, and left/right for horizontal ones.
-  - =mt=, =mb=, =ml=, =mr= specify margins to be added at the top,
-    bottom, left and right lines.
-
-  For example, a box underlining its text with a red line of width 2:
-
-  #+begin_src shell
-    <box type=Bottom width=2 color=red>string</box>
-  #+end_src
-
-  and if you wanted an underline and an overline with a margin of 2
-  pixels either side:
-
-  #+begin_src shell
-    <box type=VBoth mt=2 mb=2>string</box>
-  #+end_src
-
-- =<fn=1>string</fn>= will print =string= with the first font from
-  =additionalFonts=. The index =0= corresponds to the standard font.
-
-- =<icon=/path/to/icon.xbm/>= will insert the given bitmap. XPM image
-  format is also supported when compiled with the =with_xpm= flag.
-
-- =<action=`command` button=12345>= will execute given command when
-  clicked with specified buttons. If not specified, button is equal to 1
-  (left mouse button). Using old syntax (without backticks surrounding
-  =command=) will result in =button= attribute being ignored.
-
-- =<raw=len:str/>= allows the encapsulation of arbitrary text =str=
-  (which must be =len= =Char=s long, where =len= is encoded as a decimal
-  sequence). Careful use of this and =UnsafeStdinReader=, for example,
-  permits window managers to feed xmobar strings with =<action>= tags
-  mixed with un-trusted content (e.g. window titles). For example, if
-  xmobar is invoked as
-
-  #+begin_src shell
-    xmobar -c "[Run UnsafeStdinReader]" -t "%UnsafeStdinReader%"
-  #+end_src
-
-  and receives on standard input the line
-
-  #+begin_src shell
-    <action=`echo test` button=1><raw=41:<action=`echo mooo` button=1>foo</action>/></action>`
-  #+end_src
-
-  then it will display the text
-  =<action=`echo mooo` button=1>foo</action>=, which, when clicked, will
-  cause =test= to be echoed.
-
-Other configuration options:
-
-- =font= Name of the font to be used. Use the =xft:= prefix for XFT
-  fonts.
-
-- =additionalFonts= Haskell-style list of fonts to be used with the
-  =fn=-template. Use the =xft:= prefix for XFT fonts. See also
-  =textOffsets= below.
-
-- =bgColor= Background color.
-
-- =fgColor= Default font color.
-
-- =alpha= The transparency. 0 is transparent, 255 is opaque.
-
-- =position= Top, TopP, TopW, TopSize, Bottom, BottomP, BottomW,
-  BottomSize or Static (with x, y, width and height).
-
-  TopP and BottomP take 2 arguments: left padding and right padding.
-
-  TopW and BottomW take 2 arguments: an alignment parameter (L for left,
-  C for centered, R for Right) and an integer for the percentage width
-  xmobar window will have in respect to the screen width.
-
-  TopSize and BottomSize take 3 arguments: an alignment parameter, an
-  integer for the percentage width, and an integer for the minimum pixel
-  height that the xmobar window will have.
-
-  For example:
-
-  #+begin_src haskell
-    position = BottomW C 75
-  #+end_src
-
-  to place xmobar at the bottom, centered with the 75% of the screen
-  width. Or
-
-  #+begin_src haskell
-    position = BottomP 120 0
-  #+end_src
-
-  to place xmobar at the bottom, with 120 pixel indent of the left. Or
-
-  #+begin_src haskell
-    position = Static { xpos = 0 , ypos = 0, width = 1024, height = 15 }
-  #+end_src
-
-  or
-
-  #+begin_src haskell
-    position = Top
-  #+end_src
-
-- =textOffset= The vertical offset, in pixels, for the text baseline. If
-  negative or not given, xmobar will try to center text vertically.
-
-- =textOffsets= A list of vertical offsets, in pixels, for the text
-  baseline, to be used with the each of the fonts in =additionalFonts=
-  (if any). If negative or not given, xmobar will try to center text
-  vertically for that font.
-
-- =iconOffset= The vertical offset, in pixels, for icons bottom line. If
-  negative or not given, xmobar will try to center icons vertically.
-
-- =lowerOnStart= When True the window is sent the bottom of the window
-  stack initially.
-
-- =hideOnStart= When set to True the window is initially not mapped,
-  i.e. hidden. It then can be toggled manually (for example using the
-  dbus interface) or automatically (by a plugin) to make it reappear.
-
-- =allDesktops= When set to True (the default), xmobar will tell the
-  window manager explicitly to be shown in all desktops, by setting
-  =_NET_WM_DESKTOP= to 0xffffffff.
-
-- =overrideRedirect= If you're running xmobar in a tiling window
-  manager, you might need to set this option to =False= so that it
-  behaves as a docked application. Defaults to =True=.
-
-- =pickBroadest= When multiple displays are available, xmobar will
-  choose by default the first one to place itself. With this flag set to
-  =True= (the default is =False=) it will choose the broadest one
-  instead.
-
-- =persistent= When True the window status is fixed i.e. hiding or
-  revealing is not possible. This option can be toggled at runtime.
-  Defaults to False.
-
-- =border= TopB, TopBM, BottomB, BottomBM, FullB, FullBM or NoBorder
-  (default).
-
-  TopB, BottomB, FullB take no arguments, and request drawing a border
-  at the top, bottom or around xmobar's window, respectively.
-
-  TopBM, BottomBM, FullBM take an integer argument, which is the margin,
-  in pixels, between the border of the window and the drawn border.
-
-- =borderColor= Border color.
-
-- =borderWidth= Border width in pixels.
-
-- =iconRoot= Root folder where icons are stored. For =<icon=path/>= if
-  path start with =/=, =./= or =../= it is interpreted as it is.
-  Otherwise it will have
-
-  #+begin_src haskell
-    iconRoot ++ "/"
-  #+end_src
-
-  prepended to it. Default is =.=.
-
-- =commands= For setting the options of the programs to run (optional).
-
-- =sepChar= The character to be used for indicating commands in the
-  output template (default '%').
-
-- =alignSep= a 2 character string for aligning text in the output
-  template. The text before the first character will be align to left,
-  the text in between the 2 characters will be centered, and the text
-  after the second character will be align to the right.
-
-- =template= The output template.
-
-- =wmClass= The value for the window's X11 WM_CLASS property. Defaults
-  to "xmobar".
-
-- =wmName= The value for the window's X11 WM_NAME property. Defaults to
-  "xmobar".
-
-*** Running xmobar with i3status
-
-xmobar can be used to display information generated by [[http://i3wm.org/i3status/][i3status]], a small
-program that gathers system information and outputs it in formats
-suitable for being displayed by the dzen2 status bar, wmii's status bar
-or xmobar's =StdinReader=. See [[http://i3wm.org/i3status/manpage.html#_using_i3status_with_xmobar][i3status manual]] for further details.
-
-*** Dynamically sizing xmobar
-
-See [[https://github.com/jaor/xmobar/issues/239#issuecomment-233206552][this idea]] by Jonas Camillus Jeppensen for a way of adapting
-dynamically xmobar's size and run it alongside a system tray widget such
-as trayer or stalonetray (although the idea is not limited to trays,
-really). For your convenience, there is a version of Jonas' script in
-[[./examples/padding-icon.sh][examples/padding-icon.sh]].
-
-** Command Line Options
-
-xmobar can be either configured with a configuration file or with
-command line options. In the second case, the command line options will
-overwrite the corresponding options set in the configuration file.
-
-Example:
-
-#+begin_src shell
-  xmobar -B white -a right -F blue -t '%LIPB%' -c '[Run Weather "LIPB" [] 36000]'
-#+end_src
-
-This is the list of command line options (the output of xmobar --help):
-
-#+begin_src shell
-  Usage: xmobar [OPTION...] [FILE]
-  Options:
-    -h, -?        --help                 This help
-    -v            --verbose              Emit verbose debugging messages
-    -r            --recompile            Force recompilation
-    -V            --version              Show version information
-    -f font name  --font=font name       Font name
-    -N font name  --add-font=font name   Add to the list of additional fonts
-    -w class      --wmclass=class        X11 WM_CLASS property
-    -n name       --wmname=name          X11 WM_NAME property
-    -B bg color   --bgcolor=bg color     The background color. Default black
-    -F fg color   --fgcolor=fg color     The foreground color. Default grey
-    -i path       --iconroot=path        Root directory for icon pattern paths. Default '.'
-    -A alpha      --alpha=alpha          Transparency: 0 is transparent, 255 is opaque. Default: 255
-    -o            --top                  Place xmobar at the top of the screen
-    -b            --bottom               Place xmobar at the bottom of the screen
-    -d            --dock                 Don't override redirect from WM and function as a dock
-    -a alignsep   --alignsep=alignsep    Separators for left, center and right text
-                                         alignment. Default: '}{'
-    -s char       --sepchar=char         Character used to separate commands in
-                                         the output template. Default '%'
-    -t template   --template=template    Output template
-    -c commands   --commands=commands    List of commands to be executed
-    -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
-
-  Mail bug reports and suggestions to <mail@jao.io>
-#+end_src
-
-** The Output Template
-
-The output template must contain at least one command. xmobar will parse
-the template and will search for the command to be executed in the
-=commands= configuration option. First an =alias= will be searched
-(plugins such as Weather or Network have default aliases, see below).
-After that, the command name will be tried. If a command is found, the
-arguments specified in the =commands= list will be used.
-
-If no command is found in the =commands= list, xmobar will ask the
-operating system to execute a program with the name found in the
-template. If the execution is not successful an error will be reported.
-
-It's possible to insert in the global templates icon directives of the
-form:
-
-#+begin_src shell
-  <icon=/path/to/bitmap.xbm/>
-#+end_src
-
-which will produce the expected result. Accepted image formats are XBM
-and XPM (when =with_xpm= flag is enabled). If path does not start with
-=/=, =./=, =../= it will have
-
-#+begin_src haskell
-  iconRoot ++ "/"
-#+end_src
-
-prepended to it.
-
-It's also possible to use action directives of the form:
-
-#+begin_src shell
-  <action=`command` button=12345>
-#+end_src
-
-which will be executed when clicked on with specified mouse buttons.
-This tag can be nested, allowing different commands to be run depending
-on button clicked.
-
-** The =commands= Configuration Option
-
-The =commands= configuration option is a list of commands information
-and arguments to be used by xmobar when parsing the output template.
-Each member of the list consists in a command prefixed by the =Run=
-keyword. Each command has arguments to control the way xmobar is going
-to execute it.
-
-The option consists in a list of commands separated by a comma and
-enclosed by square parenthesis.
-
-Example:
-
-#+begin_src haskell
-  [Run Memory ["-t","Mem: <usedratio>%"] 10, Run Swap [] 10]
-#+end_src
-
-to run the Memory monitor plugin with the specified template, and the
-swap monitor plugin, with default options, every second. And here's an
-example of a template for the commands above using an icon:
-
-#+begin_src haskell
-  template="<icon=/home/jao/.xmobar/mem.xbm/><memory> <swap>"
-#+end_src
-
-This example will run "xclock" command when date is clicked:
-
-#+begin_src haskell
-  template="<action=`xclock`>%date%</action>
-#+end_src
-
-The only internal available command is =Com= (see below Executing
-External Commands). All other commands are provided by plugins. xmobar
-comes with some plugins, providing a set of system monitors, a standard
-input reader, an Unix named pipe reader, a configurable date plugin, and
-much more: we list all available plugins below.
-
-Other commands can be created as plugins with the Plugin infrastructure.
-See below.
+- If you want to know how to write your own plugin, or how to contribute
+  to the xmobar project, check out [[contributing.org][contributing]].
 
 * Authors and credits