From 52986bf3356f25e65ca03bab0070c16c9bd60d7c Mon Sep 17 00:00:00 2001
From: Thien-Thi Nguyen <ttn@gnuvola.org>
Date: Tue, 15 Dec 2020 03:26:26 -0500
Subject: [doc] Add section "Config file format"

This is based on a similar fragment in Taler docs.git.
I am certain it contains inaccuracies; please take a critical look.
---
 doc/handbook/chapters/configuration.texi | 74 +++++++++++++++++++++++++++++++-
 1 file changed, 73 insertions(+), 1 deletion(-)

(limited to 'doc/handbook/chapters/configuration.texi')

diff --git a/doc/handbook/chapters/configuration.texi b/doc/handbook/chapters/configuration.texi
index 286c72e7a..adff956a9 100644
--- a/doc/handbook/chapters/configuration.texi
+++ b/doc/handbook/chapters/configuration.texi
@@ -1,5 +1,77 @@
 @node Configuration Handbook
 @chapter Configuration Handbook
 
-This chapter has yet to be written. It is intended to be about in-depth
+This chapter has yet to be fully written.  It is intended to be about in-depth
 configuration of GNUnet.
+
+
+@menu
+* Config file format::
+@end menu
+
+
+@node Config file format
+@section Config file format
+
+In GNUnet realm, all components obey the same pattern to get configuration
+values.  According to this pattern, once the component has been installed, the
+installation deploys default values in @file{$prefix/share/gnunet/config.d/},
+in @file{.conf} files.  In order to override these defaults, the user can
+write a custom @file{.conf} file and either pass it to the component at
+execution time, or name it @file{gnunet.conf} and place it under
+@file{$HOME/.config/}.
+
+A config file is a text file containing sections, and each section
+contains its values.  The right format follows:
+
+@example
+[section1]
+value1 = string
+value2 = 23
+
+[section2]
+value21 = string
+value22 = /path22
+@end example
+
+Throughout any configuration file, it is possible to use @code{$}-prefixed
+variables, like @code{$VAR}, especially when they represent filenames in in
+the filesystem.  It is also possible to provide defaults values for those
+variables that are unset, by using the following syntax:
+
+@example
+${VAR:-default}
+@end example
+
+@noindent
+However, there are two ways a user can set @cide{$}-prefixable variables:
+(a) by defining them under a @code{[paths]} section
+
+@example
+[paths]
+GNUNET_DEPLOYMENT_SHARED = ${HOME}/shared-data
+..
+[section-x]
+path-x = ${GNUNET_DEPLOYMENT_SHARED}/x
+@end example
+
+@noindent
+or (b) by setting them in the environment
+
+@example
+$ export VAR=/x
+@end example
+
+@noindent
+The configuration loader will give precedence to variables set under
+@code{[path]}, though.
+
+The utility @samp{gnunet-config}, which gets installed along with GNUnet,
+serves to get and set configuration values without directly editing the
+@file{.conf} file.  The option @samp{-f} is particularly useful to resolve
+filenames, when they use several levels of @code{$}-expanded variables.
+See @samp{gnunet-config --help}.
+
+Note that, in this stage of development, the file
+@file{$HOME/.config/gnunet.conf} can contain sections for @strong{all} the
+components.
-- 
cgit v1.2.3


From 93d69ab5433fd156ba5d064e55ea6e677d777c85 Mon Sep 17 00:00:00 2001
From: Thien-Thi Nguyen <ttn@gnuvola.org>
Date: Tue, 15 Dec 2020 05:06:59 -0500
Subject: fix typo; quote { and } (six instances)

---
 doc/handbook/chapters/configuration.texi | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'doc/handbook/chapters/configuration.texi')

diff --git a/doc/handbook/chapters/configuration.texi b/doc/handbook/chapters/configuration.texi
index adff956a9..27efc82e2 100644
--- a/doc/handbook/chapters/configuration.texi
+++ b/doc/handbook/chapters/configuration.texi
@@ -40,19 +40,19 @@ the filesystem.  It is also possible to provide defaults values for those
 variables that are unset, by using the following syntax:
 
 @example
-${VAR:-default}
+$@{VAR:-default@}
 @end example
 
 @noindent
-However, there are two ways a user can set @cide{$}-prefixable variables:
+However, there are two ways a user can set @code{$}-prefixable variables:
 (a) by defining them under a @code{[paths]} section
 
 @example
 [paths]
-GNUNET_DEPLOYMENT_SHARED = ${HOME}/shared-data
+GNUNET_DEPLOYMENT_SHARED = $@{HOME@}/shared-data
 ..
 [section-x]
-path-x = ${GNUNET_DEPLOYMENT_SHARED}/x
+path-x = $@{GNUNET_DEPLOYMENT_SHARED@}/x
 @end example
 
 @noindent
-- 
cgit v1.2.3