expand taler.conf(5) Description; do various fixups

Most of the issues raised by Florian in <https://bugs.gnunet.org/view.php?id=6134>
are addressed, at least for the Taler side of things.  If this is accepted, we
can look to generalize it (and/or do some Sphinx #include magic) for GNUnet as
well.

In addition to the Description text, there are various small fixes:
- mark up terms
- add period at end of sentence
- do s/i.e./e.g./ almost globally (one remaining "i.e." instance)
- fold long lines into proper paragraphs
- add a blank line

Lastly, i include a comment on the ‘@INLINE@’ feature.  PTAL.

1 files changed, 90 insertions, 55 deletions

diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst
index 174587ed..ae870c2e 100644
--- a/manpages/taler.conf.5.rst
+++ b/manpages/taler.conf.5.rst
@@ -12,13 +12,34 @@ taler.conf(5)
 Description
 ===========
 
-The basic structure of the configuration file is the following. The file
-is split into sections. Every section begins with “[SECTIONNAME]” and
-contains a number of options of the form “OPTION=VALUE”. Empty lines and
-lines beginning with a “#” are treated as comments. Files containing
-default values for many of the options described below are installed
-under $TALER_PREFIX/share/taler/config.d/. The configuration file given
-with **-c** to Taler binaries overrides these defaults.
+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 be quoted by surrounding them with ``"`` (double quote).
+
+.. The @INLINE@ feature should remain undocumented since in practice, using
+   it (even correctly) elicits a warning and does not actually include the
+   specified file.  Maybe this will change in the future?  --ttn
+
+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``.
+
+Files containing default values for many of the options described below
+are installed under ``$TALER_PREFIX/share/taler/config.d/``.
+The configuration file given with **-c** to Taler binaries
+overrides these defaults.
 
 Global Options
 --------------
@@ -27,7 +48,7 @@ The following options are from the “[taler]” section and used by
 virtually all Taler components.
 
 CURRENCY
-  Name of the currency, i.e. “EUR” for Euro.
+  Name of the currency, e.g. “EUR” for Euro.
 
 The “[PATHS]” section is special in that it contains paths that can be
 referenced using “$” in other configuration values that specify
@@ -38,16 +59,16 @@ TALER_HOME
   testcases by setting ${TALER_TEST_HOME}.
 
 TALER_DATA_HOME
-  Where should Taler store its long-term data. Usually
-  “${TALER_HOME}/.local/share/taler/”
+  Where should Taler store its long-term data.
+  Usually “${TALER_HOME}/.local/share/taler/”.
 
 TALER_CONFIG_HOME
-  Where is the Taler configuration kept. Usually
-  “${TALER_HOME}/.config/taler/”
+  Where is the Taler configuration kept.
+  Usually “${TALER_HOME}/.config/taler/”.
 
 TALER_CACHE_HOME
-  Where should Taler store cached data. Usually
-  “${TALER_HOME}/.cache/taler/”
+  Where should Taler store cached data.
+  Usually “${TALER_HOME}/.cache/taler/”.
 
 TALER_RUNTIME_DIR
   Where should Taler store system runtime data (like UNIX domain
@@ -60,26 +81,26 @@ The following options are from the “[exchange]” section and used by most
 exchange tools.
 
 DB
-  Plugin to use for the database, i.e. “postgres”
+  Plugin to use for the database, e.g. “postgres”.
 
 PORT
-  Port on which the HTTP server listens, i.e. 8080.
+  Port on which the HTTP server listens, e.g. 8080.
 
 MASTER_PUBLIC_KEY
   Crockford Base32-encoded master public key, public version of the
-  exchange´s long-time offline signing key.
+  exchange's long-time offline signing key.
 
 MASTER_PRIV_FILE
   Location of the master private key on disk. Only used by tools that
   can be run offline (as the master key is for offline signing).
 
 BASE_URL
-  Specifies the base URL under which the exchange can be reached. Added
-  to wire transfers to enable tracking by merchants.
+  The base URL under which the exchange can be reached.
+  Added to wire transfers to enable tracking by merchants.
 
 AGGREGATOR_IDLE_SLEEP_INTERVAL
-  For how long should the aggregator sleep when it is idle before trying
-  to look for more work? Default is 60 seconds.
+  For how long should the aggregator sleep when it is idle
+  before trying to look for more work? Default is 60 seconds.
 
 SIGNKEY_DURATION
   For how long is a signing key valid?
@@ -95,7 +116,15 @@ LOOKAHEAD_PROVIDE
   to clients?
 
 TERMS_DIR
-  Directory where the terms of service of the exchange operator can be fund. The directory must contain sub-directories for every supported language, using the two-character language code in lower case, i.e. "en/" or "fr/".  Each subdirectory must then contain files with the terms of service in various formats.  The basename of the file of the current policy must be specified under TERMS_ETAG.  The extension defines the mime type. Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg", "png" and "gif".  For example, using a TERMS_ETAG of "0", the structure could be the following:
+  Directory where the terms of service of the exchange operator can be fund.
+  The directory must contain sub-directories for every supported language,
+  using the two-character language code in lower case, e.g. "en/" or "fr/".
+  Each subdirectory must then contain files with the terms of service in
+  various formats.  The basename of the file of the current policy must be
+  specified under ``TERMS_ETAG``.  The extension defines the mime type.
+  Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg",
+  "png" and "gif".  For example, using a ``TERMS_ETAG`` of "0", the structure
+  could be the following:
    - $TERMS_DIR/en/0.pdf
    - $TERMS_DIR/en/0.html
    - $TERMS_DIR/en/0.txt
@@ -104,12 +133,20 @@ TERMS_DIR
    - $TERMS_DIR/de/0.txt
 
 TERMS_ETAG
-  Basename of the file(s) in the TERMS_DIR with the current terms of service.  The value is also used for the "Etag" in the HTTP request to control caching. Whenever the terms of service change, the TERMS_ETAG MUST also change, and old values MUST NOT be repeated.  For example, the date or version number of the terms of service SHOULD be used for the Etag.  If there are minor (i.e. spelling) fixes to the terms of service, the TERMS_ETAG probably SHOULD NOT be changed. However, whenever users must approve the new terms, the TERMS_ETAG MUST change.
+  Basename of the file(s) in the ``TERMS_DIR`` with the current terms of service.
+  The value is also used for the "Etag" in the HTTP request to control
+  caching.  Whenever the terms of service change, the ``TERMS_ETAG`` MUST also
+  change, and old values MUST NOT be repeated.  For example, the date or
+  version number of the terms of service SHOULD be used for the Etag.  If
+  there are minor (e.g. spelling) fixes to the terms of service, the
+  ``TERMS_ETAG`` probably SHOULD NOT be changed. However, whenever users must
+  approve the new terms, the ``TERMS_ETAG`` MUST change.
 
 PRIVACY_DIR
-  Works the same as TERMS_DIR, just for the privacy policy.
+  Works the same as ``TERMS_DIR``, just for the privacy policy.
+
 PRIVACY_ETAG
-  Works the same as TERMS_ETAG, just for the privacy policy.
+  Works the same as ``TERMS_ETAG``, just for the privacy policy.
 
 
 EXCHANGE DATABASE OPTIONS
@@ -121,7 +158,7 @@ DURATION_OVERLAP
   How much should validity periods for coins overlap?
   Should be long enough to avoid problems with
   wallets picking one key and then due to network latency
-  another key being valid.  The DURATION_WITHDRAW period
+  another key being valid.  The ``DURATION_WITHDRAW`` period
   must be longer than this value.
 
 IDLE_RESERVE_EXPIRATION_TIME
@@ -138,7 +175,7 @@ The following options must be in section “[exchangedb-postgres]” if the
 “postgres” plugin was selected for the database.
 
 CONFIG
-  How to access the database, i.e. “postgres:///taler” to use the
+  How to access the database, e.g. “postgres:///taler” to use the
   “taler” database. Testcases use “talercheck”.
 
 
@@ -146,7 +183,7 @@ EXCHANGE ACCOUNT OPTIONS
 ------------------------
 
 An exchange (or merchant) can have multiple bank accounts. The following
-options are for sections named “[exchange-account-SOMETHING]”. The SOMETHING is
+options are for sections named “[exchange-account-SOMETHING]”. The ``SOMETHING`` is
 arbitrary and should be chosen to uniquely identify the bank account for
 the operator.
 
@@ -161,10 +198,10 @@ WIRE_GATEWAY_URL
   URL of the wire gateway.  Typically of the form
   ``https://$HOSTNAME[:$PORT]/taler-wire-gateway/$USERNAME/``
   where $HOSTNAME is the hostname of the system running the bank
-  (such as the Taler Python bank or the Nexus) and $USERNAME is
+  (such as the Taler Python bank or the Nexus) and ``$USERNAME`` is
   the username of the exchange's bank account (usually matching
   the ``USERNAME`` option used for authentication).  Example:
-  ``https://bank.demo.taler.net/taler-wire-gateway/Exchange/``
+  ``https://bank.demo.taler.net/taler-wire-gateway/Exchange/``.
 
 WIRE_GATEWAY_AUTH_METHOD
   This option determines how the exchange (auditor/wirewatch/aggregator)
@@ -186,11 +223,11 @@ WIRE_RESPONSE
   uniqueness.
 
 ENABLE_DEBIT
-  Must be set to YES for the accounts that the
+  Must be set to ``YES`` for the accounts that the
   taler-exchange-aggregator and taler-exchange-closer should debit.
 
 ENABLE_CREDIT
-  Must be set to YES for the accounts that the taler-exchange-wirewatch
+  Must be set to ``YES`` for the accounts that the taler-exchange-wirewatch
   should check for credits. It is yet uncertain if the merchant
   implementation may check this flag as well.
 
@@ -208,12 +245,11 @@ in advance.
 
 WIRE-FEE-YEAR
   Aggregate wire transfer fee merchants are charged in YEAR. Specified
-  as a Taler amount using the usual amount syntax
-  (CURRENCY:VALUE.FRACTION).
+  as a Taler amount using the usual amount syntax.
 
 CLOSING-FEE-YEAR
   Reserve closing fee customers are charged in YEAR. Specified as a
-  Taler amount using the usual amount syntax (CURRENCY:VALUE.FRACTION).
+  Taler amount using the usual amount syntax.
 
 EXCHANGE COIN OPTIONS
 ---------------------
@@ -222,7 +258,7 @@ The following options must be in sections starting with ``"[coin_]"`` and
 are used by taler-exchange-keyup to create denomination keys.
 
 VALUE
-   Value of the coin, i.e. “EUR:1.50” for 1 Euro and 50 Cents (per
+   Value of the coin, e.g. “EUR:1.50” for 1 Euro and 50 Cents (per
    coin).
 
 DURATION_WITHDRAW
@@ -251,7 +287,6 @@ FEE_REFUND
 RSA_KEYSIZE
    What is the RSA keysize modulos (in bits)?
 
-
 MERCHANT OPTIONS
 ----------------
 
@@ -259,10 +294,10 @@ The following options are from the “[merchant]” section and used by the
 merchant backend.
 
 DB
-   Plugin to use for the database, i.e._“postgres”
+   Plugin to use for the database, e.g._“postgres”.
 
 PORT
-   Port on which the HTTP server listens, i.e. 8080.
+   Port on which the HTTP server listens, e.g. 8080.
 
 LEGAL_PRESERVATION
    How long do we keep data in the database for tax audits after the
@@ -270,8 +305,8 @@ LEGAL_PRESERVATION
 
 FORCE_AUDIT
    Force the merchant to report every transaction to the auditor
-   (if the exchange has an auditor).  Default is NO. Do not change
-   except for testing.
+   (if the exchange has an auditor)?  Default is ``NO``.
+   Do not change except for testing.
 
 
 MERCHANT POSTGRES BACKEND DATABASE OPTIONS
@@ -281,7 +316,7 @@ The following options must be in section “[merchantdb-postgres]” if the
 “postgres” plugin was selected for the database.
 
 CONFIG
-   How to access the database, i.e. “postgres:///taler” to use the
+   How to access the database, e.g. “postgres:///taler” to use the
    “taler” database. Testcases use “talercheck”.
 
 
@@ -295,42 +330,42 @@ $NAME is a merchant-given name for the exchange. The following options
 must be given in each “[exchange-$NAME]” section.
 
 EXCHANGE_BASE_URL
-   Base URL of the exchange, i.e. “https://exchange.demo.taler.net/”
+   Base URL of the exchange, e.g. “https://exchange.demo.taler.net/”
 
 MASTER_KEY
    Crockford Base32 encoded master public key, public version of the
-   exchange´s long-time offline signing key.  Can be omitted, in that
+   exchange's long-time offline signing key.  Can be omitted, in that
    case the exchange will NOT be trusted unless it is audited by
    a known auditor.
-   Omitting the MASTER_KEY can be useful if we do not trust the exchange
+   Omitting ``MASTER_KEY`` can be useful if we do not trust the exchange
    without an auditor, but should pre-load the keys of this
    particular exchange on startup instead of waiting for it to be
    required by a client.
 
 CURRENCY
-   Name of the currency for which this exchange is used, i.e. “KUDOS”.
+   Name of the currency for which this exchange is used, e.g. “KUDOS”.
    The entire section is ignored if the currency does not match the currency
-   we use, which must be given in the [taler] section.
+   we use, which must be given in the ``[taler]`` section.
 
 KNOWN AUDITORS (for merchants)
 ------------------------------
 
 The merchant configuration can include a list of known exchanges if the
 merchant wants to specify that certain auditors are explicitly trusted.
-For each trusted exchange, a section [merchant-auditor-$NAME] must exist, where
-$NAME is a merchant-given name for the auditor. The following options
+For each trusted exchange, a section “[merchant-auditor-$NAME]” must exist, where
+``$NAME`` is a merchant-given name for the auditor. The following options
 must be given in each “[merchant-auditor-$NAME]” section.
 
 AUDITOR_BASE_URL
-  Base URL of the auditor, i.e. “https://auditor.demo.taler.net/”
+  Base URL of the auditor, e.g. “https://auditor.demo.taler.net/”
 
 AUDITOR_KEY
   Crockford Base32 encoded auditor public key.
 
 CURRENCY
-  Name of the currency for which this auditor is trusted, i.e. “KUDOS”
+  Name of the currency for which this auditor is trusted, e.g. “KUDOS”
   The entire section is ignored if the currency does not match the currency
-  we use, which must be given in the [taler] section.
+  we use, which must be given in the ``[taler]`` section.
 
 
 AUDITOR OPTIONS
@@ -340,10 +375,10 @@ The following options must be in section “[auditor]” for the Taler
 auditor.
 
 DB
-  Plugin to use for the database, i.e. “postgres”
+  Plugin to use for the database, e.g. “postgres”
 
 AUDITOR_PRIV_FILE
-  Name of the file containing the auditor’s private key
+  Name of the file containing the auditor’s private key.
 
 
 AUDITOR POSTGRES BACKEND DATABASE OPTIONS
@@ -353,7 +388,7 @@ The following options must be in section “[auditordb-postgres]” if the
 “postgres” plugin was selected for the database.
 
 CONFIG
-  How to access the database, i.e. "postgres:///taler" to use the
+  How to access the database, e.g. "postgres:///taler" to use the
   "taler" database. Testcases use “talercheck”.