revise exchange manual

2 files changed, 40 insertions, 40 deletions

diff --git a/frags/configuration-format.rst b/frags/configuration-format.rst
index 6f7ad869..dc24fba3 100644
--- a/frags/configuration-format.rst
+++ b/frags/configuration-format.rst
@@ -1,16 +1,22 @@
 Configuration format
 --------------------
 
-In Taler realm, any component obeys to the same pattern to get
-configuration values. According to this pattern, once the component has
-been installed, the installation deploys default values in
-${prefix}/share/taler/config.d/, in .conf files. In order to override
-these defaults, the user can write a custom .conf file and either pass
-it to the component at execution time, or name it taler.conf and place
-it under $HOME/.config/.
+All GNU Taler components are designed to possibly share the same
+configuration files.  When installing a GNU Taler component, the
+installation deploys default values in configuration files located
+at ${prefix}/share/taler/config.d/ where ${prefix} is the installation
+prefix. Different components must be installed to the same prefix.
+
+In order to override these defaults, the user can write a custom configuration
+file and either pass it to the component at execution time using the *-c*
+option, or name it taler.conf and place it under $HOME/.config/ which is where
+components will look by default. Note that the systemd service files pass ``-c
+/etc/taler.conf``, thus making ``/etc/taler.conf`` the primary location for
+the configuration.
 
 A config file is a text file containing sections, and each section
-contains its values. The right format follows:
+contains maps options to their values.  Configuration files follow
+basically the INI syntax:
 
 .. code-block:: ini
 
@@ -22,16 +28,16 @@ contains its values. The right format follows:
    value21 = string
    value22 = /path22
 
-Throughout any configuration file, it is possible to use ``$``-prefixed
-variables, like ``$VAR``, especially when they represent filesystem
-paths. It is also possible to provide defaults values for those
+Comments start with a hash (``#``).  Throughout the configuration, it is
+possible to use ``$``-substitution for options relating to names of files or
+directories. It is also possible to provide defaults values for those
 variables that are unset, by using the following syntax:
-``${VAR:-default}``. However, there are two ways a user can set
-``$``-prefixable variables:
+``${VAR:-default}``. There are two ways a user can set the value
+of ``$``-prefixable variables:
 
-by defining them under a ``[paths]`` section, see example below,
+  (1) by defining them under a ``[paths]`` section:
 
-.. code-block:: ini
+     .. code-block:: ini
 
    [paths]
    TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data
@@ -39,26 +45,21 @@ by defining them under a ``[paths]`` section, see example below,
    [section-x]
    path-x = ${TALER_DEPLOYMENT_SHARED}/x
 
-or by setting them in the environment:
+  (2) or by setting them in the environment:
 
-.. code-block:: console
+     .. code-block:: console
 
    $ export VAR=/x
 
 The configuration loader will give precedence to variables set under
-``[path]``, though.
+``[path]`` over environment variables.
 
-The utility ``taler-config``, which gets installed along with the
-exchange, serves to get and set configuration values without directly
-editing the .conf. The option ``-f`` is particularly useful to resolve
+The utility ``taler-config``, which gets installed along with the exchange,
+can be used get and set configuration values without directly editing the
+configuration file. The option ``-f`` is particularly useful to resolve
 pathnames, when they use several levels of ``$``-expanded variables. See
 ``taler-config --help``.
 
-Note that, in this stage of development, the file
-``$HOME/.config/taler.conf`` can contain sections for *all* the
-component. For example, both an exchange and a bank can read values from
-it.
-
-The repository ``git://git.taler.net/deployment`` contains examples of
-configuration file used in our demos. See under ``deployment/config``.
+The repository ``git://git.taler.net/deployment`` contains example code
+for generating configuration files under ``deployment/netzbon/``.
 
diff --git a/frags/using-taler-config.rst b/frags/using-taler-config.rst
index 9e6df14a..5e8ffcaa 100644
--- a/frags/using-taler-config.rst
+++ b/frags/using-taler-config.rst
@@ -1,9 +1,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 can also be edited by hand.
+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.
 
 Run
 
@@ -17,19 +17,19 @@ Run
 
 .. code-block:: console
 
-   $ taler-config -s $section -o $option
+   $ taler-config -s $SECTION -o $OPTION
 
-to extract the respective configuration value for option ``$option`` in
-section ``$section``.
+to extract the respective configuration value for option ``$OPTION`` in
+section ``$SECTION``.
 
 Finally, to change a setting, run
 
 .. code-block:: console
 
-   $ taler-config -s $section -o $option -V $value
+   $ taler-config -s $SECTION -o $OPTION -V $VALUE
 
-to set the respective configuration value to ``$value``. Note that you
-have to manually restart the Taler backend after you change the
+to set the respective configuration value to ``$VALUE``. Note that you
+have to manually restart affected Taler components after you change the
 configuration to make the new configuration go into effect.
 
 Some default options will use $-variables, such as ``$DATADIR`` within
@@ -43,6 +43,5 @@ compare:
    $ taler-config -f --section exchange-offline --option MASTER_PRIV_FILE
 
 While the configuration file is typically located at
-``$HOME/.config/taler.conf``, an alternative location can be specified
-to ``taler-merchant-httpd`` and ``taler-config`` using the ``-c``
-option.
+``$HOME/.config/taler.conf``, an alternative location can be specified to any
+GNU Taler component using the ``-c`` option.