From 9a1e5261d6ab19ad735e5eb06c512466dbac8ac3 Mon Sep 17 00:00:00 2001
From: Tobias Brunner <tobias@strongswan.org>
Date: Fri, 12 Nov 2010 13:51:28 +0100
Subject: [PATCH] Added documentation about new features of settings_t.

---
 man/strongswan.conf.5.in     | 55 ++++++++++++++++++++++++++++++++++++++++++++
 src/libstrongswan/settings.h | 50 ++++++++++++++++++++++++++++++++++++++--
 2 files changed, 103 insertions(+), 2 deletions(-)

diff --git a/man/strongswan.conf.5.in b/man/strongswan.conf.5.in
index 77db9a3..9438312 100644
--- a/man/strongswan.conf.5.in
+++ b/man/strongswan.conf.5.in
@@ -67,6 +67,61 @@ With reference to the example above, accessing
 will return
 .BR xxx .
 
+.SH INCLUDING FILES
+Using the
+.B include
+statement it is possible to include other files into strongswan.conf, e.g.
+.PP
+.EX
+	include /some/path/*.conf
+.EE
+.PP
+If the file name is not an absolute path, it is considered to be relative
+to the directory of the file containing the include statement. The file name
+may include shell wildcards (see
+.IR sh (1)).
+Also, such inclusions can be nested.
+.PP
+Sections loaded from included files
+.I extend
+previously loaded sections; already existing values are
+.IR replaced .
+It is important to note that settings are added relative to the section the
+include statment is in.
+.PP
+As an example, the following three files result in the same final
+config as the one given above:
+.PP
+.EX
+	a = b
+	section-one {
+		somevalue = before include
+		include include.conf
+	}
+	include other.conf
+
+include.conf:
+	# settings loaded from this file are added to section-one
+	# the following replaces the previous value
+	somevalue = asdf
+	subsection {
+		othervalue = yyy
+	}
+	yetanother = zz
+
+other.conf:
+	# this extends section-one and subsection
+	section-one {
+		subsection {
+			# this replaces the previous value
+			othervalue = xxx
+		}
+	}
+	section-two {
+		x = 12
+	}
+.EE
+
 .SH DEFINED KEYS
 The following keys are currently defined (using dot notation). The default
 value (if any) is listed in brackets after the key.
diff --git a/src/libstrongswan/settings.h b/src/libstrongswan/settings.h
index 92aa3f3..ab4f26e 100644
--- a/src/libstrongswan/settings.h
+++ b/src/libstrongswan/settings.h
@@ -1,4 +1,5 @@
 /*
+ * Copyright (C) 2010 Tobias Brunner
  * Copyright (C) 2008 Martin Willi
  * Hochschule fuer Technik Rapperswil
  *
@@ -30,11 +31,11 @@ typedef struct settings_t settings_t;
  * Generic configuration options read from a config file.
  *
  * The syntax is quite simple:
- *
+ * @code
  * settings := (section|keyvalue)*
  * section  := name { settings }
  * keyvalue := key = value\n
- *
+ * @endcode
  * E.g.:
  * @code
 	a = b
@@ -54,6 +55,51 @@ typedef struct settings_t settings_t;
  *
  * Currently only a limited set of printf format specifiers are supported
  * (namely %s, %d and %N, see implementation for details).
+ *
+ * \section includes Including other files
+ * Other files can be included, using the include statement e.g.
+ * @code
+ *   include /somepath/subconfig.conf
+ * @endcode
+ * Shell patterns like *.conf are possible.
+ *
+ * If the path is relative, the directory of the file containing the include
+ * statement is used as base.
+ *
+ * Sections loaded from included files extend previously loaded sections,
+ * already existing values are replaced.
+ *
+ * All settings included from files are added relative to the section the
+ * include statment is in.
+ *
+ * The following files result in the same final config as above:
+ *
+ * @code
+	a = b
+	section-one {
+		somevalue = before include
+		include include.conf
+	}
+	include two.conf
+	@endcode
+ * include.conf
+ * @code
+	somevalue = asdf
+	subsection {
+		othervalue = yyy
+	}
+	yetanother = zz
+	@endcode
+ * two.conf
+ * @code
+	section-one {
+		subsection {
+			othervalue = xxx
+		}
+	}
+	section-two {
+	}
+	@endcode
  */
 struct settings_t {
 
-- 
2.7.4