[taler-docs] branch master updated: document environment variable substitution (#7013)

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 295d1e98 document environment variable substitution (#7013)
295d1e98 is described below

commit 295d1e9853ee4dfee799b7cc81d57e0e3dbfdf93
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Fri Aug 25 13:02:05 2023 +0200

    document environment variable substitution (#7013)
---
 frags/common-conf-syntax.rst | 62 +++++++++++++++++++++-----------------------
 1 file changed, 30 insertions(+), 32 deletions(-)

diff --git a/frags/common-conf-syntax.rst b/frags/common-conf-syntax.rst
index 2740b169..b2c364c0 100644
--- a/frags/common-conf-syntax.rst
+++ b/frags/common-conf-syntax.rst
@@ -1,27 +1,18 @@
-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).
+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 a time duration are represented as a series
 of one or more ``NUMBER UNIT`` pairs, e.g. ``60 s``, ``4 weeks 1 day``,
@@ -31,17 +22,24 @@ 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.
 
+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``.  The variables are expanded either using
+key-values from the ``[PATHS]`` section (see below) or from the environment
+(``getenv()``). The values from ``[PATHS]`` take precedence over those from
+the environment.
 
-The “[PATHS]” section is special in that it contains paths that can be
-referenced using “$” in other configuration values that specify
+The ``[PATHS]`` section is special in that it contains paths that can be
+referenced using ``$`` in other configuration values that specify
 *filenames*. Note that configuration options that are not specifically
 retrieved by the application as *filenames* will not see “$”-expressions
-expanded. To expand “$”-expressions when using ``taler-config``, you must pass
+expanded. To expand ``$``-expressions when using ``taler-config``, you must 
pass
 the ``-f`` command-line option.
 
-The system automatically pre-populates the “[PATHS]” section with a few values
-at run-time in addition to the values that are in the actual configuration
-file.  These automatically generated values refer to installation properties
+The system automatically pre-populates the ``[PATHS]`` section with a few 
values
+at run-time (in addition to the values that are in the actual configuration
+file and automatically overwriting those values if they are present).
+These automatically generated values refer to installation properties
 from `GNU autoconf
 <https://www.gnu.org/prep/standards/html_node/Directory-Variables.html>`_. The
 values are usually dependent on an ``INSTALL_PREFIX`` which is determined by
@@ -58,5 +56,5 @@ the ``--prefix`` option given to configure.  The canonical 
values are:
 
 Note that on some platforms, the given paths may differ depending
 on how the system was compiled or installed, the above are just the
-canonical locations of the various resources.
-
+canonical locations of the various resources.  These
+automatically generated values are never written to disk.

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