Merge branch 'master' of git+ssh://gnunet.org/gnunet

3 files changed, 84 insertions, 5 deletions

diff --git a/doc/handbook/chapters/configuration.texi b/doc/handbook/chapters/configuration.texi
index 286c72e7a..27efc82e2 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 @code{$}-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.
diff --git a/doc/handbook/chapters/installation.texi b/doc/handbook/chapters/installation.texi
index d7b2fb590..40a23e738 100644
--- a/doc/handbook/chapters/installation.texi
+++ b/doc/handbook/chapters/installation.texi
@@ -327,8 +327,8 @@ Now GNS should work in browsers that are configured to use a SOCKS proxy on
 
 @node Minimal configuration
 @section Minimal configuration
-GNUnet needs a configuration file to start. For the @emph{single-user setup}
-an empty file is sufficient:
+GNUnet needs a configuration file to start (@pxref{Config file format}).
+For the @emph{single-user setup} an empty file is sufficient:
 
 @example
 $ touch ~/.config/gnunet.conf
@@ -2493,4 +2493,3 @@ Furthermore, 'make install' will silently fail to set the DNS binaries to
 be owned by group "gnunetdns" unless that group already exists (!).
 An alternative name for the "gnunetdns" group can be specified using the
 @code{--with-gnunetdns=GRPNAME} configure option.
-
diff --git a/doc/handbook/gnunet.texi b/doc/handbook/gnunet.texi
index 5ff33d94c..ca74c347d 100644
--- a/doc/handbook/gnunet.texi
+++ b/doc/handbook/gnunet.texi
@@ -78,7 +78,7 @@ This document is the Reference Manual for GNUnet version @value{VERSION}.
 @c * Vocabulary::                      Vocabulary
 * Installing GNUnet::               Installing GNUnet
 * Using GNUnet::                    Using GNUnet
-@c * Configuration Handbook::          Configuring GNUnet
+* Configuration Handbook::          Configuring GNUnet
 * GNUnet Contributors Handbook::    Contributing to GNUnet
 * GNUnet Developer Handbook::       Developing GNUnet
 * GNU Free Documentation License::  The license of this manual
@@ -137,6 +137,10 @@ Using GNUnet
 * reclaimID Identity Provider::
 * Using the Virtual Public Network::
 
+Configuration Handbook
+
+* Config file format::
+
 GNUnet Contributors Handbook
 
 * Contributing to GNUnet::
@@ -209,6 +213,10 @@ GNUnet Developer Handbook
 @include chapters/user.texi
 @c *********************************************************************
 
+@c *********************************************************************
+@include chapters/configuration.texi
+@c *********************************************************************
+
 @include chapters/contributing.texi
 
 @c *********************************************************************