From fab8437ff133a0f154bf181ff173ed979fc8666f Mon Sep 17 00:00:00 2001 From: patrick96 Date: Thu, 3 Oct 2019 22:42:47 +0200 Subject: [PATCH] doc: Write syntax definition in polybar.5 --- doc/CMakeLists.txt | 4 ++ doc/conf.py | 3 +- doc/index.rst | 1 + doc/man/polybar.1.rst | 8 +++ doc/man/polybar.5.rst | 158 ++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 173 insertions(+), 1 deletion(-) create mode 100644 doc/man/polybar.5.rst diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 01d44852..b7e80b8a 100644 --- a/doc/CMakeLists.txt +++ b/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) diff --git a/doc/conf.py b/doc/conf.py index 6035f206..20d4ab45 100644 --- a/doc/conf.py +++ b/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 ---------------------------------------------- diff --git a/doc/index.rst b/doc/index.rst index ae7a4558..e8678df7 100644 --- a/doc/index.rst +++ b/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 diff --git a/doc/man/polybar.1.rst b/doc/man/polybar.1.rst index b129e644..58845034 100644 --- a/doc/man/polybar.1.rst +++ b/doc/man/polybar.1.rst @@ -67,3 +67,11 @@ SEE ALSO -------- | Full documentation at: | Project wiki: + +.. only:: man + + :manpage:`polybar(5)` + +.. only:: not man + + :doc:`polybar.5` diff --git a/doc/man/polybar.5.rst b/doc/man/polybar.5.rst new file mode 100644 index 00000000..4e32fce7 --- /dev/null +++ b/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 `_ 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`