[3418] Minor clean-ups here and there.

doc/guide/.gitignore

@@ -1,4 +1,4 @@
-/bind10-guide.html
-/bind10-guide.txt
-/bind10-messages.html
-/bind10-messages.xml
+/kea-guide.html
+/kea-guide.txt
+/kea-messages.html
+/kea-messages.xml

doc/guide/config.xml

@@ -3,98 +3,112 @@
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
 <!ENTITY mdash  "&#x2014;" >
 ]>
-  <chapter id="kea-config">
-    <title>Kea configuration</title>
-
-    <para>Depending on configuration backend chosen  (see <xref
-    linkend="dhcp-config-backend"/>), configuration mechanisms are
-    different. The following sections describe details of specific configuration
-    backends. Note that only one configuration backend can be used and its
-    selection is determined during compilation time.</para>
-
-    <section id="bundy-backend">
-      <title>Bundy configuration backend</title>
-      <para>This legacy configuration backend allows Kea to use former BIND10
-      framework. That framework and this Kea configuration backend is no longer
-      supported by ISC. It is currently developed as part of Bundy project (see
-      <ulink url="http://bundy-dns.de">Bundy homepage</ulink>). See Bundy
-      project documentation regarding configuration.</para>
-    </section>
-
-    <section id="json-backend">
-      <title>JSON configuration backend</title>
-      <para>JSON is the default configuration backend and the only one supported
-      as of 0.9 release. It assumes that the servers are started from command
-      line (either directly or using a script, see TODO for details). JSON
-      backend uses certain signals to influence certain behaviors. The
-      configuration file is specified upon startup using -c parameter.</para>
-
-      <section id="json-format">
-	<title>JSON syntax</title>
-	<para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are
-	defined in extended JSON format. The basic JSON is defined in <ulink
-	url="http://tools.ietf.org/html/rfc4627">RFC 4627</ulink>.  Kea
-	components use extended JSON, which extends basic format by allowing
-	bash-style comments in the file. Comment lines must have hash (#) in the
-	first column.</para>
-
-	<para>Configuration file consists of a single object (often colloquially
-	called a map) started with a curly bracket. It consists "Dhcp4",
-	"Dhcp6", "DhcpDdns" and/or "Logging" objects. It is possible to define
-	additional elements, but they will be ignored. That principle was chosen
-	to ease configuration management. For example, it is possible to define
-	Dhcp4, Dhcp6 and Logging elements in one configuration file that can be
-	used to start both DHCPv4 and DHCPv6 components.  When starting, DHCPv4
-	component will use Dhcp4 object to configure itself and Logging to
-	configure logging parameters, while ignoring Dhcp6 object.</para>
-
-	<para>For example, a very simple configuration for Dhcp6 could look
-	like this:
+<chapter id="kea-config">
+  <title>Kea configuration</title>
+
+  <para>Depending on configuration backend chosen (see <xref
+  linkend="dhcp-config-backend"/>), configuration mechanisms are different. The
+  following sections describe details of specific configuration backends. Note
+  that only one configuration backend can be used and its selection is
+  determined during compilation time.</para>
+
+  <section id="bundy-backend">
+    <title>Bundy configuration backend</title>
+    <para>This legacy configuration backend allows Kea to use former BIND10
+    framework. That framework and this Kea configuration backend is no longer
+    supported by ISC. It is currently developed as part of Bundy project (see
+    <ulink url="http://bundy-dns.de">Bundy homepage</ulink>). See Bundy project
+    documentation regarding configuration.</para>
+  </section>
+
+  <section id="json-backend">
+    <title>JSON configuration backend</title>
+    <para>JSON is the default configuration backend and the only one supported
+    as of 0.9 release. It assumes that the servers are started from command line
+    (either directly or using a script, see TODO for details). JSON backend uses
+    certain signals to influence certain behaviors. The configuration file is
+    specified upon startup using -c parameter.</para>
+
+    <section id="json-format">
+      <title>JSON syntax</title>
+      <para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined
+      in extended JSON format. The basic JSON is defined in <ulink
+      url="http://tools.ietf.org/html/rfc4627">RFC 4627</ulink>.  Kea components
+      use extended JSON, which extends basic format by allowing bash-style
+      comments in the file. Comment lines must have hash (#) in the first
+      column.</para>
+
+      <para>Configuration file consists of a single object (often colloquially
+      called a map) started with a curly bracket. It consists "Dhcp4", "Dhcp6",
+      "DhcpDdns" and/or "Logging" objects. It is possible to define additional
+      elements, but they will be ignored. That principle was chosen to ease
+      configuration management. For example, it is possible to define Dhcp4,
+      Dhcp6 and Logging elements in one configuration file that can be used to
+      start both DHCPv4 and DHCPv6 components.  When starting, DHCPv4 component
+      will use Dhcp4 object to configure itself and Logging to configure logging
+      parameters, while ignoring Dhcp6 object.</para>
+
+      <para>For example, a very simple configuration for both DHCPv4 and DHCPv6
+      could look like this:
 <screen>
+# The whole configuration starts here.
 {
 
-# DHCPv6 specific configuration starts here.
-"Dhcp6": {
-
-# These are DHCPv6-specific parameters. They will be explained in later sections.
+# DHCPv4 specific configuration starts here.
+"Dhcp4": {
     "interfaces": [ "eth0" ],
+    "valid-lifetime": 4000,
+    "renew-timer": 1000,
+    "rebind-timer": 2000,
+    "subnet4": [{
+       "pool": "192.0.2.1-192.0.2.200",
+       "subnet": "192.0.2.0/24"
+    }],
+    ...
+},
+# DHCPv4 specific configuration ends here.
 
+# DHCPv6 specific configuration starts here.
+"Dhcp6": {
+    "interfaces": [ "eth1" ],
     "preferred-lifetime": 3000,
     "valid-lifetime": 4000,
     "renew-timer": 1000,
     "rebind-timer": 2000,
-
-# The following list defines subnets. Each subnet consists of at
-# least subnet and pool entries.
     "subnet6": [{
-    "pool": [ "2001:db8:1::/80" ],
-       "subnet": "2001:db8:1::/64"
-    }]
+       "pool": "2001:db8::/80",
+       "subnet": "2001:db8::/64"
+    }],
+    ...
 },
 # DHCPv6 specific configuration ends here.
 
 # Logger parameters (that could be shared among several components) start here.
+# That section can be used by both DHCPv4 and DHCPv6 servers.
 "Logging": {
-
-# These are Logger-specific parameters. They will be explained in later sections.
    "loggers": [{
         "name": "*",
         "severity": "DEBUG"
-    }]
+    }],
+    ...
 }
 # Logger parameters end here.
 
+# The whole configuration structure ends here.
 }
 </screen>
 	</para>
 
-        <para>
-          More examples are available in the Kea source code in the
-          <filename>doc/examples</filename> directory.
-        </para>
-	
-      </section>
+        <para>More examples are available in the Kea source code in the
+        <filename>doc/examples</filename> directory.</para>
 
+        <para>To avoid repetition of mostly similar structures, specific
+        examples will showcase only subset of parameters appropriate for a given
+        context. For example, when discussing IPv6 subnets configuration in
+        DHCPv6, only subnet6 parameters will be mentioned. It is implied that
+        remaining elements (global that holds Dhcp6, Logging and possibly
+        DhcpDdns) are present, but are omitted for clarity. </para>
+      </section>
       
       <!-- @todo Add a reference here after #3422 is done -->
     </section>