Improve the docs

* doc/pies.texi: Describe the use of xenv as a preprocessor.

1 files changed, 216 insertions, 5 deletions

diff --git a/doc/pies.texi b/doc/pies.texi
index e39295c..8eba588 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -3958,11 +3958,11 @@ in this case @command{pies} uses its regular configuration file.
 
 @opindex --no-init
 When started with PID 1 from a docker container, @command{pies}
-detects the fact automatically and switches to the entrypoint mode.
-Up to version 1.4.90, automatical detection was not implemented, and
-it was necessary to use the @option{--no-init} option to discern
-between the @code{entrypoint} and @code{init} modes.  This is no longer
-the case.  The option, however, is still retained.
+tries to detect the fact automatically and switch to the entrypoint
+mode.  As of version @value{VERSION}, this detection might fail in
+containers run under Kubernetes.  For such cases, use the
+@option{--no-init} option to inform @command{pies} that it should
+run in @code{entrypoint} mode.
 
 The following @file{Dockerfile} fragment illustrates how to configure
 @command{pies} to be run from a container:
@@ -3998,6 +3998,19 @@ undefined), use:
   command "syslogd -n -R $@{LOGHOST:-172.19.255.255@}";
 @end example
 
+Quite often a need arises to expand environment variables in other
+parts of the configuration file and to conditionally exclude portions
+of configuration, depending on whether a particular variable is set.
+The following sections describe two approaches to solving this problem.
+
+@menu
+* m4 environment::  Expanding Environment Variables in GNU m4.
+* xenv::            Specialized Preprocessor Program.
+@end menu
+
+@node m4 environment
+@section Expanding Environment Variables in GNU m4
+
 Configuration preprocessing (@pxref{Preprocessor}) can be used to
 conditionally enable parts of the @file{pies.conf} file, depending
 on the value of an environment variable.  The technique described
@@ -4077,6 +4090,204 @@ Place both macros in a single file and include it at the top of your
 you can place them in the @file{pp-setup} file (@pxref{pp-setup}),
 in which case they will be included automatically.
 
+@node xenv
+@section Using xenv
+@prindex xenv
+
+Another way to expand environment variables in the configuration file
+is to use @command{xenv}.  @command{xenv} is a specialized
+preprocessor that expands environment variables in its input.  It is
+also able to conditionally include parts of text depending on whether
+the environment variable is defined.  The program is described in
+@uref{https://www.gnu.org.ua/software/xenv/}.
+
+To use @command{xenv} as preprocessor, start @command{pies} as
+follows:
+
+@example
+pies --foreground --stderr --preprocessor="xenv -s"
+@end example
+
+The @option{-s} option instructs @command{xenv} to emit
+@dfn{synchronization lines}, that inform @command{pies} about actual
+location of configuration statements in case when the expansion adds
+or removes portions of text spanning several lines.
+
+You can also combine the functionality of @command{m4} and
+@command{xenv} by running
+
+@example
+pies --foreground --stderr --preprocessor="xenv -s -m"
+@end example
+
+In this case @command{xenv} will automatically feed its output to the
+standard input of @command{m4}, started for this purpose.
+
+By default, @command{xenv} uses the shell syntax to expand the
+variables.  For example, in the following configuration file
+fragment, @samp{$WORKDIR} will expand to the actual value of
+the @env{WORKDIR} environment variable:
+
+@example
+component @{
+  chdir "$WORKDIR";
+  ...
+@}  
+@end example
+
+There are two ways to conditionally include portions of text.  The first
+one is to use the @samp{$@{X:+W@}} construct.  For example:
+
+@example
+component @{
+  $@{WORKDIR:+chdir "$WORKDIR";@}
+  ...
+@}  
+@end example
+
+Another way is to use the @command{xenv} @samp{$$ifset} (or
+@samp{$$ifdef}) statement:
+
+@example
+component @{
+$$ifset WORKDIR
+  chdir "$WORKDIR";
+$$endif  
+  ...
+@}  
+@end example
+
+The difference between @samp{$$ifset X} and @samp{$$ifdef X} is the
+same as between @samp{$@{X:+W@}} and @samp{$@{X+W@}},
+i.e. @samp{$$ifset} tests whether the variable is set and not-null,
+and @samp{$$ifdef} tests only whether it is set, no matter its value.
+
+@command{xenv} extends the shell syntax by providing a @dfn{ternary}
+operator.  The construct @samp{$@{X|A|B@}} expands to @samp{A} if
+the variable @env{X} is set and to @samp{B} otherwise (as usual,
+placing the colon before first @samp{|} checks if the variable is set
+and not null).  This allows for writing compact conditionals:
+
+@example
+@group
+component syslogd @{
+   mode respawn;
+   command "/sbin/syslogd -n $@{LOGHOST:|-R $LOGHOST|-O /proc/1/fd/1@}";
+@}
+@end group
+@end example
+
+In this example @command{syslogd} is instructed to relay messages to
+the IP address specified by the @env{LOGHOST} variable and to send
+messages to the container stdout otherwise.
+
+Using shell indirection operator @samp{$} can be confusing in parts of
+@command{pies} configuration file that deal with environment variables
+by themselves.  The common point of confusion is using @code{env} and
+@code{command} statements when @code{shell} or @code{expandenv} flag
+is set.  For example:
+
+@example
+@group
+component X @{
+   env @{
+      set "HOME=/var/lib/nobody";
+   @}
+   flags shell;
+   command "marb -C $HOME";
+@}
+@end group
+@end example
+
+Here, the intent is to pass @samp{/var/lib/nobody} as the command line
+argument to @command{marb}.  However, if @command{pies} was started
+with @command{xenv} as preprocessor, the reference @samp{$HOME} will
+be expanded by @command{xenv} at the early stage to whatever value the
+@env{HOME} variable had at @command{pies} startup.   Consequently,
+when it comes to launching the @samp{X} component, the intended
+expansion won't take place.
+
+There are three options to handle such cases:
+
+@enumerate 1
+@item Escape the @samp{$}
+
+Use backslash to suppress expansion by @command{xenv}:
+
+@example
+@group
+component X @{
+   env @{
+      set "HOME=/var/lib/nobody";
+   @}
+   flags shell;
+   command "marb -C \$HOME";
+@}
+@end group
+@end example
+
+@item Use the @dfn{verbatim} operator
+
+This allows to reproduce the desired part of text verbatim.  There are
+two verbatim operators: inline operator @samp{$[...]} and block
+operator @samp{$$verbatim ... $$end}.  Examples:
+
+@example
+@group
+component X @{
+   env @{
+      set "HOME=/var/lib/nobody";
+   @}
+   flags shell;
+   $[command "marb -C $HOME";]
+@}
+@end group
+@end example
+
+or
+
+@example
+@group
+component X @{
+   env @{
+      set "HOME=/var/lib/nobody";
+   @}
+   flags shell;
+$$verbatim   
+   command "marb -C $HOME";
+$$end   
+@}
+@end group
+@end example
+
+@item Change the indirection operator
+
+The indirection operator @samp{$} can be changed either globally,
+by using the @option{-S} option, or locally by using the
+@samp{$$sigil} statement.  E.g.:
+
+@example
+@group
+$$sigil @@
+# From this point on, $ looses its special meaning in xenv.
+
+component X @{
+   env @{
+      set "HOME=/var/lib/nobody";
+   @}
+   flags shell;
+   command "marb -C $HOME @@FILE";
+@}
+@end group
+@end example
+
+In the @code{command} line of this example, @code{@@FILE} will be
+expanded by @command{xenv} when processing the configuration file,
+and @code{$HOME} will be expanded by shell (to the value
+@samp{/var/lib/nobody}, set by the @code{env} statement) when
+@command{pies} will start the command.
+@end enumerate
+
 @node Configuration Examples
 @chapter Configuration Examples
   In this section we provide several examples of working @command{pies}