\input texinfo
@c -*-texinfo-*-

@c %**start of header
@setfilename guile-config.info
@documentencoding UTF-8
@settitle Guile Config Reference Manual
@c %**end of header
@syncodeindex tp fn
@syncodeindex cp fn

@include version.texi
@include macros.texi

@copying
Copyright @copyright{} 2015-2018 Alex Sassmannshausen

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end copying

@dircategory The Algorithmic Language Scheme
@direntry
* Guile Config: (guile-config).      Declarative program configuration
@end direntry

@titlepage
@title The Guile Config Manual
@author Alex Sassmannshausen

@page
@vskip 0pt plus 1filll
Edition @value{EDITION} @*
@value{UPDATED} @*

@insertcopying
@end titlepage

@contents

@c *********************************************************************
@node Top
@top Guile Config

This document describes Guile Config version @value{VERSION}.

@menu
* Introduction::                The need for Guile Config.
* Overview::                    The low-down on usage.
* Detailed API Reference::      The deep dive.
* On Inheritance::              Inheritance fully explained.

* Contributing::                Contributing to the Guile Config project.
* Acknowledgments::             Thanks!
* Function Index::              Functions.
@end menu

@c *********************************************************************
@node Introduction
@chapter Introduction

Guile Config removes the headache from managing complicated command-line
applications.  And it is lovely to work with.  Think of it as a kind of
mutated version of getopt-long.

Throughout this document I will refer to command-line arguments to the
application as options.

But of course there are different kind of options you may wish to use in
your app: You've got your switches, your settings and sometimes, you've
got your secrets.  We handle them all.

@itemize
@item
You can declare:
@itemize
@item
Application internal configuration variables (secrets).
@item
Command-line configuration options (switches).
@item
Configuration file & command-line configuration options (settings).
@item
Positional command-line parameters (arguments).
@item
Sub-commands with their own set of secrets, switches, settings and
arguments & inheritance from parent specifications.
@item
Whether to automatically generate the standard @option{--help},
@option{--usage} and @option{--version} command-line options (the
library will do so by default).
@item
Authors, licenses, copyright years, synopses & descriptions.
@item
Where to install configuration files, with syntactic sugar for common
cases such as in home directory and in invocation directory
configuration files.
@item
Support for different configuration file parsing backends (only a sexp
and identity parser are currently provided)
@end itemize

@item
You can parse through:
@itemize
@item
@code{getopt-config} or @code{getopt-config-auto}, which parse
command-line arguments and return objects that can be used in the same
manner as the object returned by @code{getopt-long}.
@item
If you use the @emph{-auto} version, your program will automatically
emit help or version messages unless suppressed and exit with code 0, if
a @option{--help}, @option{--usage} or @option{--version} command-line
argument was detected.
@end itemize
@item
You can access the values of individual configuration options using the
@code{option-ref} function in the same manner that you would when using
@code{getopt-long}.
@end itemize

Guile Config builds upon the excellent @code{(ice-9 getopt-long)}
module, augmenting it with configuration file management, and recursive
sub-command management.

@c *********************************************************************
@node Overview
@chapter Overview

This chapter will provide you with concrete examples of the use of the
config library.

@menu
* Declaration::                     How to declare a configuration
* Using the darn thing::            How to use a declared configuration
@end menu

@c *********************************************************************
@node Declaration
@section Declaration

The work pony of this library is the @code{configuration}
@pxref{Configuration} command, through which you can declare your
application's options. Here follow 2 examples, the first bare-bones, the
second more elaborate.

Behind the scenes we request automatic help, usage and version
messages. Our version message will be bare-bones as we have not
specified copyright, version, license or author.

@lisp
@include @value{EXAMPLES}/simple.scm
@end lisp

In this second example we will declare a configuration with 2
sub-commands.  As above, we request automatically generated help, usage
and version messages.  We also declare the author, copyright and the
license of the application for greater accuracy in the emitted
@option{--version} message.

We tell one of the sub-commands to inherit the keywords from the root
configuration using the @code{wanted} field of the @code{configuration}
record type.

@lisp
@include @value{EXAMPLES}/frobnigator.scm
@end lisp

@c *********************************************************************
@node Using the darn thing
@section Using the darn thing

Usage is incredibly simple.  In most cases, you will simply want to
use @code{getopt-config-auto}, which will return a @code{codex} that you
can query with @code{option-ref}.

Using @code{getopt-config-auto} not only resolves the command-line flags
and configuration files for your application. It also scans command-line
arguments automatically for help usage & version flags and, unless our
configuration was told not too, emits messages for them.

Let us look at a fully fledged small program to show you how we might
use the entire (guile config) user API.:

@lisp
@include @value{EXAMPLES}/hello-world.scm
@end lisp

Note the usage of the @code{full-command} procedure to dispatch on the
subcommand we might be using!

Alternatively, you can give up some convenience for more control.  Using
@code{getopt-config} means you won't automatically parse the
command-line arguments for version or help flags.  We will have to do so
manually, and invoke the appropriate message generators:

@lisp
;; We assume we are operating on a file that defines a configuration
;; named config.

(let ((options (getopt-config (command-line) config)))
  (cond ((or (option-ref options 'usage #f)
             (option-ref options 'help #f))
         (emit-help options)
         (exit 0))
        ((option-ref options 'version #f)
         (emit-version options)
         (exit 0))
        (else 'do-stuff)))
@end lisp

This latter usage is closer to the @code{getopt-long} style, but can
still benefit from our emitters.  Of course you are free to write your
own version or usage emitters.

@c *********************************************************************
@node Detailed API Reference
@chapter Detailed API Reference

This chapter provides you with an in-depth reference to all user-visible
commands exposed by the config library.

@menu
* Configuration::               The configuration.
* Secrets::                     Internal configuration options.
* Switches::                    Commandline options.
* Settings::                    Configuration file options.
* Arguments::                   Positional or free parameters.
* Initializers::                Parsing command-line and config-file input.
* Accessing Options::           Accessing options in your program.
* Utilities::                   Icing on the cake.
@end menu

@c *********************************************************************
@node Configuration
@section Configuration

The configuration data type is at the core of the Config library.  Every
application using it will have at least one configuration defined.  This
root configuration in turn can contain further sub-configurations and
options (see below). Sub-configurations, define subcommands that can be
invoked by the end-user.

@deftp {Data Type} configuration

@code{configuration} allows you to create a new configuration or
sub-configuration.  You should use this form when declaring your
program's configurations.

@code{configuration}'s @code{generate-help?}, @code{generate-usage?} &
@code{generate-version?} default to #t.  @code{directory} is optional
unless you have @code{setting}s in your @code{keywords} list.  The
@code{parser} defaults to @code{identity-parser}, which does not
generate configuration files.

Finally, @code{license}, @code{copyright} and @code{author} can be
omitted, but doing so will result in a very limited @emph{version}
string.

@table @asis
@item @code{name}
A symbol specifying the application/sub-command name.

@item @code{synopsis}
A string of less than 40 characters providing a brief explanation of
this configuration.

@item @code{long}
A string providing a detailed explanation of this configuration.

@item @code{wanted}
An association list, which defaults to '(), specifying what keywords and
arguments should be inherited @pxref{On Inheritance} from the parent
configuration.  The keys of the association list can only be
@code{keywords} or @code{arguments}.

@example
`((keywords . (length author))
  (arguments . (input-file)))
@end example

@item @code{keywords}
A list containing @code{secret}s, @code{switch}es and/or
@code{setting}s.

@item @code{arguments}
A list containing @code{argument}s. Arguments define positional
parameters for your program.

@item @code{subcommands}
A list containing further @code{configuration}s.  These configurations
are considered @emph{sub-configurations} of this
@emph{parent-configuration}.  If there is no
@emph{parent-configuration}, the current configuration is also referred
to as the @emph{root-configuration}.

@emph{sub-configurations} define subcommands that can be invoked by the
end-user when running your application.

@item @code{directory}
Either a single @code{path}, or a list of @code{path}s, depending on
whether your application has a single location defining configuration
files or multiple locations, where one takes precedence over the other.

The ordering of the list defines which locations take precedence over
others, with those towards the end overriding those at the beginning.

@item @code{version}
A simple string defining the version of this application.  This is used
when generating the @emph{--version} string.

@item @code{license}
A @code{license} record.  We have many pre-defined licenses that we
copypasta'd from the @emph{Guix} project, so any licenses defined there
should work here.

@item @code{copyright}
A list of years for which the author of this program or sub-command
claims copyright.

@item @code{author}
A string containing the name of the author of this program or
sub-command.

@item @code{parser}
A @code{parser} record, which in turn provides a means to parse and
write this configuration's configuration file.

This defaults to the @emph{identity-parser}, which does not actually
generate configuration files, and thus ignores the @code{directory}
field.

Currently the only alternative parser that comes out of the box is the
@emph{sexp-parser}, which generates s-expression based configuration
files.

@item @code{alias}
A symbol providing an alternative name for this configuration.  This can
be useful for sub-commands, in order to provide shorter, alternative
means of invocation.

@item @code{generate-help?}
A boolean value indicating whether we should automatically provide the
@emph{--help} switch.

This defaults to #t.

@item @code{generate-usage?}
A boolean value indicating whether we should automatically provide the
@emph{--usage} switch.

This defaults to #t.

@item @code{generate-version?}
A boolean value indicating whether we should automatically provide the
@emph{--version} switch.

This defaults to #t.

@item @code{generate-cmdtree?}
A boolean value indicating whether we should automatically provide the
@emph{--cmdtree} switch.  This switch emits an outline of the
subcommands available in your application.

This defaults to #f.
@end table
@end deftp

@c *********************************************************************
@node Secrets
@section Secrets

@code{secret}s are configuration values that cannot be manipulated by
the end user, either through command-line arguments or through
configuration files.  In short, these might be any configuration
variables that you want to set within your application.  Using the
secret data type for this allows you to use the configuration API.

Secrets are also inheritable using the @code{wanted} field of
@code{configuration}s.

@deftp {Data Type} secret

@table @asis
@item @code{name}
A symbol specifying the name of the secret.

@item @code{synopsis}
A string of less than 40 characters providing a brief explanation of
this secret.

@item @code{default}
The value of this secret.
@end table
@end deftp

@c *********************************************************************
@node Switches
@section Switches

@code{switch}es are configuration parameters that can be set by
the end-user using command-line parameters to this program or
sub-command.

@deftp {Data Type} switch

@table @asis
@item @code{name}
A symbol specifying the name of the switch.

@item @code{synopsis}
A string of less than 40 characters providing a brief explanation.

@item @code{description}
A string providing a detailed explanation of this switch.

@item @code{default}
The default value of this switch.  This can be any value that passes the
predicate defined with @code{test}.  If you do not specify a value then
it will be associated with an @code{<empty>} value.  Leaving the default
value unspecified makes this a mandatory switch!

This defaults to @code{<empty>}, making switches by default mandatory.

@item @code{character}
If specified this should be the character that you want to use as the
@emph{short version} for this option.  By default this library generates
short options from the first letter of a switch or setting.  If you
would rather not generate a short option, simply set this to @code{#f}.

@item @code{test}
A predicate with which we test the value in @code{default} or by the
end-user on the command-line.  If you would like this switch to be a
@emph{flag}, i.e. an option such that the user does not need to provide
a value, then you should set @code{test} to @code{boolean?}.

In this case it behooves you to set @code{default} to @code{#f}: leaving
@code{default} undefined makes the flag mandatory, which means the value
will always end up being @code{#t} in practice. On the other hand,
setting @code{default} to @code{#t} means there is simply no way to
switch off this flag.

If this public option should not be @emph{flag}, but rather an option
that the end user should provide a value for, then @code{test} should
either be @code{string?}, or you should specify @code{handler} to
transform the value specified by the end user on the command line,
inevitably a string, into a value that will pass @code{test}.

For instance, if we expect the end user to provide a number as input to
this switch, then we can set @code{test} to @code{number?} and
@code{handler} to @code{string->number}.

Finally, if you would like to create a @emph{hybrid} option, one that
can act either as a flag, or to which the end user may specify a value,
then you should:
@enumerate
@item
Specify a test that can handle either boolean or other values.
@item
Specify a handler that expects either boolean or string input values.
@item
Set the @code{optional?} field described below to @code{#t}.
@end enumerate

Whatever approach above you choose, @code{test} can optionally be a
procedure of exactly 2 arguments, instead of the usual 1 argument.  In
this case the procedure will be passed the codex as well as the input
value. The codex will come with all switches, settings and arguments
populated with the values passed through the commandline and settings
files.  You can use this feature to carry out introspection on the
codex.  For instance, you could use the @code{option-ref} procedure to
test that another switch or setting has been set, and thus create
@emph{companion switches or settings}, i.e. switches or settings that
depend on each-other.

@item @code{handler}
A procedure of one argument that will be applied to the value supplied
by the end-user on the command-line to transform that value (which will
always be a string) into a different type that can pass @code{test}.

This interplay between @code{test} and @code{handler} allows us to
perform input validation entirely at the configuration parsing stage,
thus freeing the programmer from having to do this in the body of the
program itself.

@item @code{example}
A string providing an example value which will be displayed to the
end-user when they request @code{--help}, or @code{--usage}.

@item @code{optional?}
This defaults to @code{#f}. @code{optional?} is a field that allows you
to specify whether this @code{switch} should act as a flag/option
@emph{hybrid}, i.e. whether the end user is able to either provide a
value or no value on the command line.

An example use case might be a @code{--verbosity} option which can
either be called as is (@code{--verbosity}) for a default verbosity
level or with a value for a specific level (e.g. @code{--verbosity=5}).

To create a @emph{hybrid}, simply set this field to @code{#t}.

@item @code{merge-strategy}
A procedure specifying what to do when the switch is provided multiple
times on the commandline. By default we simply return the first value
provided, so this option defaults to @code{(lambda (e p) e)}.

@item @code{error}
A procedure specifying what to do when we encounter an error whilst
processing the value provided to this switch.  The default value results
in generic error messages that work, if you squint at them, in most
cases.  You can override the default by providing a procedure of 4
arguments: the reason for the error, the keyword or argument for which
the error occured, the value that caused the error and the full codex.
In other words, the procedure specified here will be invoked as follows:
@code{(error-handler reason kwd/arg value cdx)}.
@end table
@end deftp

@c *********************************************************************
@node Settings
@section Settings

@code{settings} are configuration parameters that can be set by the
end-user using command-line parameters or using a configuration file.
If you attach settings to a @code{configuration}, but you don't specify
a @code{directory}, or continue to use the @code{identity-parser}, then
your @code{settings} will not be written to configuration files.

@code{setting}s will cause the program to generate configuration files
if they do not yet exist, on the following conditions:
- you are not using the @code{identity-parser}
- you have at least one @code{directory} set
- you have at least one eager @code{directory} set.

After configuration files are generated we then try to read them, and
merge them as fall-backs into the command-line passed options.

@deftp {Data Type} setting

@table @asis
@item @code{name}
A symbol specifying the name of the switch.

@item @code{synopsis}
A string of less than 40 characters providing a brief explanation.

@item @code{description}
A string providing a detailed explanation of this setting.

@item @code{default}
The default value of this setting.  This can be any value that passes
the predicate defined with @code{test}.  For @code{setting}s, this field
is mandatory: all settings are always optional, with a default value
specified in the configuration file.

This field is mandatory and has no default.

@item @code{character}
If specified this should be the character that you want to use as the
@emph{short version} for this option.  By default this library generates
short options from the first letter of a setting or setting.  If you
would rather not generate a short option, simply set this to @code{#f}.

@item @code{test}
A predicate with which we test the value in @code{default} or by the
end-user on the command-line.  If you would like this setting to be a
@emph{flag}, i.e. an option such that the user does not need to provide
a value, then you should set @code{test} to @code{boolean?}.

In this case it behooves you to set @code{default} to @code{#f}: leaving
@code{default} undefined makes the flag mandatory, which means the value
will always end up being @code{#t} in practice. On the other hand,
setting @code{default} to @code{#t} means there is simply no way to
switch off this flag.

If this public option should not be @emph{flag}, but rather an option
that the end user should provide a value for, then @code{test} should
either be @code{string?}, or you should specify @code{handler} to
transform the value specified by the end user on the command line,
inevitably a string, into a value that will pass @code{test}.

For instance, if we expect the end user to provide a number as input to
this setting, then we can set @code{test} to @code{number?} and
@code{handler} to @code{string->number}.

Finally, if you would like to create a @emph{hybrid} option, one that
can act either as a flag, or to which the end user may specify a value,
then you should:
@enumerate
@item
Specify a test that can handle either boolean or other values.
@item
Specify a handler that expects either boolean or string input values.
@item
Set the @code{optional?} field described below to @code{#t}.
@end enumerate

Whatever approach above you choose, @code{test} can optionally be a
procedure of exactly 2 arguments, instead of the usual 1 argument.  In
this case the procedure will be passed the codex as well as the input
value. The codex will come with all switches, settings and arguments
populated with the values passed through the commandline and settings
files.  You can use this feature to carry out introspection on the
codex.  For instance, you could use the @code{option-ref} procedure to
test that another switch or setting has been set, and thus create
@emph{companion switches or settings}, i.e. switches or settings that
depend on each-other.

@item @code{handler}
A procedure of one argument that will be applied to the value supplied
by the end-user on the command-line to transform that value (which will
always be a string) into a different type that can pass @code{test}.

This interplay between @code{test} and @code{handler} allows us to
perform input validation entirely at the configuration parsing stage,
thus freeing the programmer from having to do this in the body of the
program itself.

This handler will not be applied to the value returned from a
configuration file, unless a backend specifically implements this.

@item @code{example}
A string providing an example value which will be displayed to the
end-user when they request @code{--help}, or @code{--usage}.

@item @code{optional?}
This defaults to @code{#f}. @code{optional?} is a field that allows you
to specify whether this @code{setting} should act as a flag/option
@emph{hybrid}, i.e. whether the end user is able to either provide a
value or no value on the command line.

An example use case might be a @code{--verbosity} option which can
either be called as is (@code{--verbosity}) for a default verbosity
level or with a value for a specific level (e.g. @code{--verbosity=5}).

To create a @emph{hybrid}, simply set this field to @code{#t}.

@item @code{merge-strategy}
A procedure specifying what to do when the setting is provided multiple
times on the commandline. By default we simply return the first value
provided, so this option defaults to @code{(lambda (e p) e)}.

@item @code{error}
A procedure specifying what to do when we encounter an error whilst
processing the value provided to this setting.  The default value results
in generic error messages that work, if you squint at them, in most
cases.  You can override the default by providing a procedure of 4
arguments: the reason for the error, the keyword or argument for which
the error occured, the value that caused the error and the full codex.
In other words, the procedure specified here will be invoked as follows:
@code{(error-handler reason kwd/arg value cdx)}.
@end table
@end deftp

@c *********************************************************************
@node Arguments
@section Arguments

@code{argument}sa are positional command-line parameters for your
application. The ordering in the list of @code{arguments} naturally
matters.  Please also bear in mind that, for the same reason, all
arguments after your first optional argument must be optional too!

@deftp {Data Type} argument

@table @asis
@item @code{name}
A symbol specifying the name of the argument.

@item @code{synopsis}
A string of less than 40 characters providing a brief explanation of
this argument.

@item @code{description}
A string providing a detailed explanation of this argument.

@item @code{default}
The default value of this argument, if it is not overriden on the
command-line by the end user.  This can be an arbitrary value, but it
should pass the predicate defined with @code{test}.

This defaults to @code{<empty>}, which makes it a @emph{mandatory}
argument. To make the argument @emph{optional}, it suffices to assign
some other default value.

@item @code{test}
A predicate to evaluate the value passed by the end user.  We will throw
an error if that value does not satisfy this predicate.

Test can optionally be a procedure of exactly 2 arguments, instead of
the usual 1 argument.  In this case the procedure will be passed the
codex, populated with the values passed through the commandline and
settings files.  You can use this feature to carry out introspection on
the codex.  For instance, you could use the @code{option-ref} procedure
to test that another setting or setting has been set, and thus create
@emph{companion switches or settings}, i.e. switches or settings that
depend on each-other.

@item @code{handler}
A procedure of one argument that will be applied to the value supplied
by the end-user on the command-line to transform that value (which will
always be a string) into a different type that can pass @code{test}.

This interplay between @code{test} and @code{handler} allows us to
perform input validation entirely at the configuration parsing stage,
thus freeing the programmer from having to do this in the body of the
program itself.

@item @code{example}
A string providing an example value which will be displayed to the
end-user when they request @code{--help}, or @code{--usage}.  If
@code{example} is not provided, we will use the name of the free
parameter instead.

@item @code{error}
A procedure specifying what to do when we encounter an error whilst
processing the value provided to this argument.  The default value
results in generic error messages that work, if you squint at them, in
most cases.  You can override the default by providing a procedure of 4
arguments: the reason for the error, the keyword or argument for which
the error occured, the value that caused the error and the full codex.
In other words, the procedure specified here will be invoked as follows:
@code{(error-handler reason kwd/arg value cdx)}.
@end table
@end deftp

@c *********************************************************************
@node Initializers
@section Initializers

These procedures are all available in the (config) module.

After declaring your configurations you will still need to initialize
your program.  This is done by passing the command-line parameters the
script was invoked with, and your declared configuration to an
initializer.

@deffn {Scheme Procedure} getopt-config @var{args} @var{config}
@deffnx {Scheme Procedure} getopt-config-auto @var{args} @var{config}

The above procedures work very similarly.  Both have taken their
inspiration from @code{getopt-long}'s way of doing things: @var{args}
should be the command-line arguments passed to the script and
@var{config} should be the declared configuration.

The second procedure will automatically check whether the end-user
requested @emph{--help}, @emph{--usage}, or @emph{--version} and will
emit an appropriate message and exit the program if so.
@end deffn

@deffn {Scheme Procedure} full-command @var{codex}

This procedure returns a list, where each element is a string with the
name of each configuration traversed during invocation by the end user.
It returns, in essence, a breadcrumb trail of the user's invocation.

@lisp
;; in a configuration called 'blargh' with a subcommand called 'flurb',
;; when a user enters:
;; blargh flurb

(let ((options (getopt-config-auto (command-line) config)))
  (full-command options))

;; returns: '("blargh" "flurb")
@end lisp

@code{full-command} will always return the string version of a
configuration's @var{name}, even if the user entered the configuration's
@var{alias}!
@end deffn

@c *********************************************************************
@node Accessing Options
@section Accessing Options

At its heart, (guile config) aims to easily replace (ice-9
getopt-long).  Because of this the library exports @code{option-ref},
which behaves almost identically to (ice-9 getopt-long)'s
@code{option-ref}.

@deffn {Scheme Procedure} option-ref @var{codex} @var{key} [@var{default}]
Try to find the value for @var{key} in @var{codex}, returning
@var{default} if the value is unset or cannot be found.

@var{key} should be:
@itemize
@item
a symbol if you want to retrieve a keyword from @var{codex};
@item
a list of exactly one symbol, if you want to retrieve an argument from
@var{codex};
@item
or the empty list if you want to retrieve all arguments from
@var{codex}.
@end itemize
@end deffn

@c *********************************************************************
@node Utilities
@section Utilities

@deffn {Scheme Procedure} emit-help @var{codex} [@var{port}]

Generate and emit a help message for @code{codex} to @code{port}.
@end deffn

@deffn {Scheme Procedure} emit-version @var{codex} [@var{port}]

Generate and emit a version message for @code{codex} to @code{port}.
@end deffn

@deffn {Scheme Procedure} options-write @var{codex} [@var{configuration} @var{eager-only?}]

Write @code{codex} to its configuration files.  Normally this means
writing the @code{settings} contained in @code{codex}, as well as some
meta-information, and documentation.  If @code{eager-only?} is @code{#t}
then we only write to those directories specified in the
@code{directory} field of the codex that are eager.

We only write to configuration files that do not yet exist — if a
configuration file exists where we would write one, we do nothing.
@end deffn

@c *********************************************************************
@node On Inheritance
@chapter On Inheritance

Inheritance can mean many things.  In our context, inheritance can be
thought of as a means to achieve two things:

@itemize
@item
Economy - there is no need to repeat common option declarations.
@item
Consistency - we can ensure we expose the same options for the same
functionality, without having to manually ensure consistency.
@end itemize

There are 2 uses of inheritance in this library.

Within the (guile config) API, inheritance is implemented at the
@code{configuration} level, through the @code{wanted} field.  This field
can be set in any sub-configuration to indicate which precise keywords
or arguments should be inherited from its parent.  In this way options
can be passed down through the configuration graph as far as required.

There are some limitations to this approach, namely:
@itemize
@item
It is not possible to automate inheritance.
@item
Every inherited option must be explicitly specified.
@end itemize

In addition to inheritance through the @code{wanted} field, we also have
automatic inheritance in the following @code{configuration} fields:
@itemize
@item
directory
@item
version
@item
license
@item
copyright
@item
author
@item
parser
@item
generate-help?
@item
generate-usage?
@item
generate-version?
@end itemize

This means that you only have to set these fields once, in the
@emph{root-configuration}.  After this, if you want to change a field in
one of the children, you can just set that field in the child
configuration.

@c *********************************************************************
@node Contributing
@chapter Contributing

Guile Config is an open project and I actively invite contribution.  Get
in touch with the project on @email{alex@@pompo.co}.  The project
welcomes ideas, bug reports, patches, or feedback.

Please see the HACKING file that comes with the Guile Config source code
for practical details about contributions.

@c *********************************************************************
@node Acknowledgments
@chapter Acknowledgments

Guile Config is intended as a gift to the Guile & Guix communities,
without whom I would never have learned to program.

@c *********************************************************************
@node Function Index
@unnumbered Function Index
@printindex fn

@bye

@c Local Variables:
@c ispell-local-dictionary: "american";
@c End:
