[gnunet] branch master updated: [doc] Add section "Config file format"

[gnunet]

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

ttn pushed a commit to branch master
in repository gnunet.

The following commit(s) were added to refs/heads/master by this push:
     new 52986bf33 [doc] Add section "Config file format"
52986bf33 is described below

commit 52986bf3356f25e65ca03bab0070c16c9bd60d7c
Author: Thien-Thi Nguyen <ttn@gnuvola.org>
AuthorDate: Tue Dec 15 03:26:26 2020 -0500

    [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(-)

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.

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