doc: Write syntax definition in polybar.5

doc/CMakeLists.txt

@@ -59,3 +59,7 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/polybar.1
   DESTINATION ${CMAKE_INSTALL_MANDIR}/man1
   COMPONENT doc)
+
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/polybar.5
+  DESTINATION ${CMAKE_INSTALL_MANDIR}/man5
+  COMPONENT doc)

doc/conf.py

@@ -160,7 +160,8 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('man/polybar.1', 'polybar', 'A fast and easy-to-use tool status bar', [], 1)
+    ('man/polybar.1', 'polybar', 'A fast and easy-to-use tool status bar', [], 1),
+    ('man/polybar.5', 'polybar', 'configuration file for polybar(1)', [], 5)
 ]
 
 # -- Options for Texinfo output ----------------------------------------------

doc/index.rst

@@ -17,6 +17,7 @@ Welcome to the official polybar documentation.
    :caption: Manual Pages:
 
    man/polybar.1
+   man/polybar.5
 
 .. toctree::
    :maxdepth: 1

doc/man/polybar.1.rst

@@ -67,3 +67,11 @@ SEE ALSO
 --------
 | Full documentation at: <https://github.com/polybar/polybar>
 | Project wiki: <https://github.com/polybar/polybar/wiki>
+
+.. only:: man
+
+  :manpage:`polybar(5)`
+
+.. only:: not man
+
+  :doc:`polybar.5`

doc/man/polybar.5.rst

@@ -0,0 +1,158 @@
+.. highlight:: ini
+
+polybar(5)
+==========
+
+Description
+-----------
+
+The polybar configuration file defines the behavior and look of polybar. It uses
+a variant of the `INI <https://en.wikipedia.org/wiki/INI_file>`_ file format.
+The exact syntax is described below but first a small snippet to get familiar
+with the syntax:
+
+::
+
+  [section_name]
+  ; A comment
+  # Another comment
+
+  background = #ff992a
+  width = 90%
+  monitor = HDMI-0
+
+  screenchange-reload = false
+
+  ; Use double quotes if you want to keep the surrounding space.
+  text = " Some text "
+
+When started ``polybar`` will search for the config file in one of several
+places in the following order:
+
+* If the ``-c`` or ``--config`` command line argument is specified, it will use
+  the path given there.
+* If the environment variable ``XDG_CONFIG_HOME`` is set it will use
+  ``$XDG_CONFIG_HOME/polybar/config``
+* If the environment variable ``HOME`` is set it will use
+  ``$HOME/.config/polybar/config``
+
+Syntax
+------
+
+The entire config is line-based so everything is constrained to a single line.
+This means there are no multiline values or other multiline constructs (except
+for sections).
+Each line has one of four types:
+
+* Empty
+* Comment
+* Section Header
+* Key
+
+Spaces at the beginning and end of each line will be ignored.
+
+.. note::
+
+  In this context "spaces" include the regular space character as well as the
+  tab character and any other character for which :manpage:`isspace(3)` returns
+  ``true`` (e.g. ``\r``).
+
+Any line that doesn't fit into one of these four types is a syntax error.
+
+.. note::
+
+  It is recommended that `section header` names and `key` names only use
+  alphanumeric characters as well as dashes (``-``), underscores (``_``) and
+  forward slashes (``/``).
+
+  In practice all characters are allowed except for spaces and any of these:
+  ``"'=;#[](){}:.$\%``
+
+Section Headers
+^^^^^^^^^^^^^^^
+
+Sections are used to group config options together. For example each module is
+defined in its own section.
+
+A section is defined by placing the name of the section in square brackets
+(``[`` and ``]``). For example:
+
+::
+
+  [module/wm]
+
+This declares a section with the name ``module/wm`` and all keys defined after
+this line will belong to that section until a new section is declared.
+
+.. warning::
+  The first non-empty and non-comment line in the main config file must be a
+  section header. It cannot be a key because that key would not belong to any
+  section.
+
+.. note::
+  The following section names are reserved and cannot be used inside the config:
+  ``self``, ``root``, and ``BAR``.
+
+Keys
+^^^^
+
+Keys are defined by assigning a value to a name like this:
+
+
+::
+
+  name = value
+
+This assigns ``value`` to the key ``name`` in whatever section this line is in.
+Key names need to be unique per section.
+If the value is enclosed by double-quotes (``"``), the quotes will be ignored.
+So the following still assigns ``value`` to ``name``:
+
+::
+
+  name = "value"
+
+Spaces around the equal sign are ignored, the following are all equivalent:
+
+::
+
+  name=value
+  name = value
+  name =      value
+
+Because spaces at the beginning and end of the line are also ignored, if you
+want your value to begin and/or end with a space, the value needs to be enclosed
+in double-quotes:
+
+::
+
+  name = " value "
+
+Here ``name`` has a leading and trailing whitespace.
+
+Empty Lines & Comments
+^^^^^^^^^^^^^^^^^^^^^^
+
+Empty lines and comment lines are ignored when reading the config file, they do
+not affect polybar's behavior. Comment lines start with either the ``;`` or the
+``#`` character.
+
+.. note::
+
+  Inline comments are not supported. For example the following line does not end
+  with a comment, they value of ``name`` is actually set to ``value ; comment``:
+
+  ::
+
+    name = value ; comment
+
+SEE ALSO
+--------
+
+.. only:: man
+
+  :manpage:`polybar(1)`
+
+.. only:: not man
+
+  :doc:`polybar.1`