[RFC PATCH 1/2] Improve documentation for the "include" setting.

[dirson@debian.org]

From: Yann Dirson <ydirson@free.fr>

---
 pod/multistrap |   22 ++++++++++++++++++++--
 1 files changed, 20 insertions(+), 2 deletions(-)

To follow up to http://bugs.debian.org/630258 here is an attempt at documenting
a couple of things I found not so obvious from existing doc, and should be
useful to others.

If patches to the pod/manpage are not the prefered way to ship documentation
within the package, I'm open to suggestions.  Debian tools usually use Docbook,
but that's a bit heavyweight on the doc writer.  What about Asciidoc ?

diff --git a/pod/multistrap b/pod/multistrap
index a737d28..5560f6d 100644
--- a/pod/multistrap
+++ b/pod/multistrap
@@ -133,6 +133,9 @@ configuration files should be C<bootstrap> instead.
 
 =head1 General settings:
 
+'include' specifies a config file to cascade from, see the C<Cascading
+configuration> for details.
+
 'arch' can be overridden on the command line using the C<--arch> option.
 
 'directory' specifies the top level directory where the bootstrap
@@ -368,8 +371,9 @@ See also
 =head1 Cascading configuration
 
 To support multiple variants of a basic (common) configuration,
-C<multistrap> allows configuration files to include other (more general)
-configuration files. i.e. the most detailed / specific configuration
+C<multistrap> allows configuration files to include other (more
+general) configuration files, using the 'include' settings of the
+"General" section. i.e. the most detailed / specific configuration
 file is specified on the command line and that file includes another
 file which is shared by other configurations.
 
@@ -393,6 +397,20 @@ B<not warn you> if a configuration file contains an unrecognised
 option (for future compatibility with backported configurations), so a
 simple typo can result in an option not being set.
 
+Some notes about cascading:
+
+=over 1
+
+=item contents of 'debootstrap' and 'aptsources' in the current config
+file are merged with the contents of the included file.
+
+=item boolean settings such 'cleanup', 'noauth', 'addimportant',
+'omitrequired', 'allowrecommends', and 'explicitsuite' are of the "one
+set wins all" kind: they are not overriden by a 'false' setting in the
+current config file.
+
+=back
+
 =head1 Machine:variant support
 
 The old packages.conf variables from emsandbox can all be converted
-- 
1.7.5.4