[taler-docs] branch master updated (6eb60c0 -> 7371821)

[gnunet]

This is an automated email from the git hooks/post-receive script.

ttn pushed a change to branch master
in repository docs.

    from 6eb60c0  manpages: move Bugs section after See Also (three instances)
     new fce2162  add frags/ subdir
     new f72a46f  add frag: configuration-format.rst
     new 207adf4  add frag: using-taler-config.rst
     new d18a6a8  fix typo
     new 7371821  replace ‘Configuration format’ and ‘Using taler-config’ w/ 
‘include’ directives

The 5 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 frags/README.md                |  10 ++++
 frags/configuration-format.rst |  69 ++++++++++++++++++++++++
 frags/using-taler-config.rst   |  53 ++++++++++++++++++
 taler-exchange-manual.rst      | 120 +----------------------------------------
 4 files changed, 134 insertions(+), 118 deletions(-)
 create mode 100644 frags/README.md
 create mode 100644 frags/configuration-format.rst
 create mode 100644 frags/using-taler-config.rst

diff --git a/frags/README.md b/frags/README.md
new file mode 100644
index 0000000..9facc4c
--- /dev/null
+++ b/frags/README.md
@@ -0,0 +1,10 @@
+# docs.git/frags
+
+This directory contains fragments to be included by the directive:
+
+  .. include:: RELATIVE-FILE-NAME
+
+If the fragment includes headers, you MUST include it at top-level.
+Otherwise, you MUST include it only at "block" level.
+
+See 
<https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment>.
diff --git a/frags/configuration-format.rst b/frags/configuration-format.rst
new file mode 100644
index 0000000..f9b28e1
--- /dev/null
+++ b/frags/configuration-format.rst
@@ -0,0 +1,69 @@
+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/.
+
+A config file is a text file containing sections, and each section
+contains its values. The right format follows:
+
+.. code-block:: ini
+
+   [section1]
+   value1 = string
+   value2 = 23
+
+   [section2]
+   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
+variables that are unset, by using the following syntax:
+``${VAR:-default}``. However, there are two ways a user can set
+``$``-prefixable variables:
+
+by defining them under a ``[paths]`` section, see example below,
+
+.. code-block:: ini
+
+   [paths]
+   TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data
+   ..
+   [section-x]
+   path-x = ${TALER_DEPLOYMENT_SHARED}/x
+
+or by setting them in the environment:
+
+.. code-block:: console
+
+   $ export VAR=/x
+
+The configuration loader will give precedence to variables set under
+``[path]``, though.
+
+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
+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://taler.net/deployment`` contains examples of
+configuration file used in our demos. See under ``deployment/config``.
+
+   **Note**
+
+   Expectably, some components will not work just by using default
+   values, as their work is often interdependent. For example, a
+   merchant needs to know an exchange URL, or a database name.
diff --git a/frags/using-taler-config.rst b/frags/using-taler-config.rst
new file mode 100644
index 0000000..d7c28b2
--- /dev/null
+++ b/frags/using-taler-config.rst
@@ -0,0 +1,53 @@
+.. _Using-taler_002dconfig-exchange:
+
+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.
+
+Run
+
+.. code-block:: console
+
+   $ taler-config -s $SECTION
+
+to list all of the configuration values in section ``$SECTION``.
+
+Run
+
+.. code-block:: console
+
+   $ taler-config -s $section -o $option
+
+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
+
+to set the respective configuration value to ``$value``. Note that you
+have to manually restart the Taler backend after you change the
+configuration to make the new configuration go into effect.
+
+Some default options will use $-variables, such as ``$DATADIR`` within
+their value. To expand the ``$DATADIR`` or other $-variables in the
+configuration, pass the ``-f`` option to ``taler-config``. For example,
+compare:
+
+.. code-block:: console
+
+   $ taler-config -s ACCOUNT-bank \
+                  -o WIRE_RESPONSE
+   $ taler-config -f -s ACCOUNT-bank \
+                  -o WIRE_RESPONSE
+
+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.
+
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index e68bdf8..468950b 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -297,128 +297,12 @@ This chapter provides an overview of the exchange 
configuration. Or at
 least eventually will do so, for now it is a somewhat wild description
 of some of the options.
 
-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/.
+.. include:: frags/configuration-format.rst
 
-A config file is a text file containing sections, and each section
-contains its values. The right format follows:
 
-.. code-block:: ini
-
-   [section1]
-   value1 = string
-   value2 = 23
-
-   [section2]
-   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
-variables that are unset, by using the following syntax:
-``${VAR:-default}``. However, there are two ways a user can set
-``$``-prefixable variables:
-
-by defining them under a ``[paths]`` section, see example below,
-
-.. code-block:: ini
-
-   [paths]
-   TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data
-   ..
-   [section-x]
-   path-x = ${TALER_DEPLOYMENT_SHARED}/x
-
-or by setting them in the environment:
-
-.. code-block:: console
-
-   $ export VAR=/x
-
-The configuration loader will give precedence to variables set under
-``[path]``, though.
-
-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
-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://taler.net/deployment`` contains examples of
-configuration file used in our demos. See under ``deployment/config``.
-
-   **Note**
-
-   Expectably, some components will not work just by using default
-   values, as their work is often interdependent. For example, a
-   merchant needs to know an exchange URL, or a database name.
-
-.. _Using-taler_002dconfig-exchange:
-
-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.
-
-Run
-
-.. code-block:: console
-
-   $ taler-config -s $SECTION
-
-to list all of the configuration values in section ``$SECTION``.
-
-Run
-
-.. code-block:: console
-
-   $ taler-config -s $section -o $option
-
-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
-
-to set the respective configuration value to ``$value``. Note that you
-have to manually restart the Taler backend after you change the
-configuration to make the new configuration go into effect.
-
-Some default options will use $-variables, such as ``$DATADIR`` within
-their value. To expand the ``$DATADIR`` or other $-variables in the
-configuration, pass the ``-f`` option to ``taler-config``. For example,
-compare:
-
-.. code-block:: console
-
-   $ taler-config -s ACCOUNT-bank \
-                  -o WIRE_RESPONSE
-   $ taler-config -f -s ACCOUNT-bank \
-                  -o WIRE_RESPONSE
+.. include:: frags/using-taler-config.rst
 
-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.
 
 .. _Keying:
 

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.