Add fragment that describes common FOO.conf(5) syntax

* frags/common-conf-syntax.rst: New.

1 files changed, 32 insertions, 0 deletions

diff --git a/frags/common-conf-syntax.rst b/frags/common-conf-syntax.rst
new file mode 100644
index 00000000..3d837174
--- /dev/null
+++ b/frags/common-conf-syntax.rst
@@ -0,0 +1,32 @@
+The configuration file is line-oriented.
+Blank lines and whitespace at the beginning and end of a line are ignored.
+Comments start with ``#`` or ``%`` in the first column
+(after any beginning-of-line whitespace) and go to the end of the line.
+
+The file is split into sections.
+Every section begins with “[SECTIONNAME]” and
+contains a number of options of the form “OPTION=VALUE”.
+There may be whitespace around the ``=`` (equal sign).
+Section names and options are *case-insensitive*.
+
+The values, however, are *case-sensitive*.
+In particular, boolean values are one of ``YES`` or ``NO``.
+Values can include whitespace by surrounding
+the entire value with ``"`` (double quote).
+Note, however, that there are no escape characters in such strings;
+all characters between the double quotes (including other double quotes)
+are taken verbatim.
+
+Values that represent filenames can begin with a ``/bin/sh``-like
+variable reference.
+This can be simple, such as ``$TMPDIR/foo``, or complex,
+such as ``${TMPDIR:-${TMP:-/tmp}}/foo``.
+See ``[PATHS]`` (below).
+
+Values that represent a time duration are represented as a series
+of one or more ``NUMBER UNIT`` pairs, e.g. ``60 s``, ``4 weeks 1 day``,
+``5 years 2 minutes``.
+
+Values that represent an amount are in the usual amount syntax:
+``CURRENCY:VALUE.FRACTION``, e.g. ``EUR:1.50``.
+The ``FRACTION`` portion may extend up to 8 places.