work on #8017

4 files changed, 62 insertions, 35 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index ceebd005..b5931a65 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -146,18 +146,23 @@ such as the implemented version of the protocol and the currency used.
       // supported currencies and how to render them.
       currency: string;
 
-      // How wallets should render currencies supported
+      // How services should render currencies supported
       // by this backend.  Maps
       // currency codes (e.g. "EUR" or "KUDOS") to
       // the respective currency specification.
       // All currencies in this map are supported by
-      // the backend.
+      // the backend.  Note that the actual currency
+      // specifications are a *hint* for applications
+      // that would like *advice* on how to render amounts.
+      // Applications *may* ignore the currency specification
+      // if they know how to render currencies that they are
+      // used with.
       currencies: { currency : CurrencySpecification};
 
       // Array of exchanges trusted by the merchant.
       // Since protocol v6.
       exchanges: ExchangeConfigInfo[];
-      
+
     }
 
   .. ts:def:: ExchangeConfigInfo
diff --git a/frags/using-taler-config.rst b/frags/using-taler-config.rst
index 5e8ffcaa..ba4febb4 100644
--- a/frags/using-taler-config.rst
+++ b/frags/using-taler-config.rst
@@ -3,7 +3,9 @@ Using taler-config
 
 The tool ``taler-config`` can be used to extract or manipulate configuration
 values; however, the configuration use the well-known INI file format and is
-generally better edited by hand to preserve comments and structure.
+generally better edited by hand to preserve comments and structure.  Thus, ``taler-config`` should primarily be used
+to inspect or understand a configuration that is in place,
+and not to update it!
 
 Run
 
@@ -22,7 +24,9 @@ Run
 to extract the respective configuration value for option ``$OPTION`` in
 section ``$SECTION``.
 
-Finally, to change a setting, run
+Finally, to change a setting and clobber your entire
+configuration file structure, inlining all values and
+removing all comments, run
 
 .. code-block:: console
 
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index 72a4418f..301edc6d 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -521,11 +521,6 @@ can use the ``taler-config`` helper:
 .. include:: frags/configuration-format.rst
 
 
-.. _Using-taler_002dconfig-exchange:
-
-.. include:: frags/using-taler-config.rst
-
-
 Exchange Database Setup
 =======================
 
@@ -2130,6 +2125,13 @@ After enough time has passed, the money should arrive at the specified IBAN.
 For more information on the taler-wallet-cli tool, see
 :doc:`taler-wallet`.
 
+taler-config
+------------
+
+.. _Using-taler_002dconfig-exchange:
+
+.. include:: frags/using-taler-config.rst
+
 
 Private key storage
 -------------------
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index c48ce3c0..78d10454 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -385,7 +385,6 @@ Installing the GNU Taler binary packages on Ubuntu
 How to configure the merchant’s backend
 =======================================
 
-.. index:: taler-config
 .. index:: taler.conf
 
 The installation already provides reasonable defaults for most of the
@@ -394,13 +393,11 @@ database that the backend should use. By default, the file
 ``$HOME/.config/taler.conf`` is where the Web shop administrator specifies
 configuration values that augment or override the defaults.
 Note that when using our binary packages, the systemd service files
-force the use of ``/etc/taler.conf`` as the main configuration file.
+force the use of ``/etc/taler/taler.conf`` as the main configuration file.
 
 
 .. include:: frags/configuration-format.rst
 
-.. include:: frags/using-taler-config.rst
-
 
 .. _Backend-options:
 
@@ -426,12 +423,17 @@ modified. Here, the notation ``[$SECTION]/$OPTION`` denotes the option
 Service address
 ^^^^^^^^^^^^^^^
 
-The following option sets the transport layer address used by the
-merchant backend:
+The service address specifies where the taler-merchant-httpd should listen for
+requests. When using the Debian/Ubuntu packages, these options will already be
+configured correctly for the included Nginx and Apache configurations and will
+not need any changes.
+
+The following option sets the transport protocol used by the merchant backend:
 
 .. code-block:: ini
 
-      [MERCHANT]/SERVE = tcp | unix
+      [MERCHANT]
+      SERVE = unix # or tcp
 
 If this option is set to
 
@@ -449,23 +451,27 @@ the backend to the network.
 
 To run the Taler backend on TCP port 8888, use:
 
-.. code-block:: console
+.. code-block:: ini
 
-   $ taler-config -s MERCHANT -o SERVE -V tcp
-   $ taler-config -s MERCHANT -o PORT -V 8888
+   [MERCHANT]
+   SERVE = tcp
+   PORT = 8888
 
 .. note::
 
-   When using the Debian/Ubuntu packages, these options are already
-   configured in the ``/etc/taler/conf.d/merchant.conf`` configuration file.
-
-   If you need to change them, you should edit
-   ``/etc/taler/merchant-overrides.conf``.  By default, the Taler merchant
-   package will use a UNIX domain socket at
+   If you need to change where the taler-merchant-httpd listens for requests,
+   you should edit ``/etc/taler/merchant-overrides.conf``.  By default, the
+   Taler merchant package will use a UNIX domain socket at
    ``/run/taler/merchant-httpd/merchant-http.sock``. For the best possible
    security it is recommended to leave this in place and configure a reverse
    proxy (Nginx or Apache) as described below.
 
+   When using the Debian/Ubuntu packages, the use of a UNIX domain socket
+   is already pre-configured in the ``/etc/taler/conf.d/merchant.conf``
+   configuration file.  Suitable reverse proxy configuration
+   file templates (``taler-merchant``) are be installed in the
+   respective ``sites-available`` directories of Apache and Nginx.
+
 
 
 Currency
@@ -476,15 +482,17 @@ specified using the option
 
 .. code-block:: ini
 
-      [TALER]/CURRENCY
+      [TALER]
+      CURRENCY = EUR # or USD, ...
 
 When testing with the Taler demonstration exchange at
 https://exchange.demo.taler.net/ you must set this
 value to ``KUDOS``:
 
-.. code-block:: console
+.. code-block:: ini
 
-   $ taler-config -s TALER -o CURRENCY -V KUDOS
+       [TALER]
+       CURRENCY = KUDOS
 
 .. note::
 
@@ -504,7 +512,8 @@ The option
 
 .. code-block:: ini
 
-      [MERCHANT]/DB
+      [MERCHANT]
+      DB = postgres
 
 specifies which DBMS is to be used. However, currently only the value
 ``postgres`` is supported. This is also the default.
@@ -524,14 +533,14 @@ For the ``postgres`` backend, you need to specify:
 
 .. code-block:: ini
 
-      [MERCHANTDB-postgres]
-      CONFIG = "postgres://..."
+      [merchantdb-postgres]
+      CONFIG = "postgres:///taler-merchant"
 
 This option specifies a PostgreSQL access path, typicallly using the format
 ``postgres:///$DBNAME``, where ``$DBNAME`` is the name of the PostgreSQL
-database you want to use. Suppose ``$USER`` is the name of the user who will
-run the backend process (usually ``taler-merchant-httpd``). Then, you need to
-first run:
+database you want to use (here, ``taler-merchant`` on the local machine).
+Suppose ``$USER`` is the name of the user who will run the backend process
+(usually ``taler-merchant-httpd``). Then, you need to first run:
 
 .. code-block:: console
 
@@ -1023,6 +1032,13 @@ processes, either via your systemd or init system, or directly.
 Advanced topics
 ===============
 
+taler-config
+------------
+
+.. index:: taler-config
+
+.. include:: frags/using-taler-config.rst
+
 .. _MerchantDatabaseScheme:
 
 Database Scheme