[5036] Changes after review:

 - clarified JSON usage in admin guide (True/False not allowed)
 - fixed incorrect reference to hosts4-storage
 - clarified that empty mac-sources entry is not allowed
 - added extra text about syntactic contexts
 - corrected several typos

doc/guide/config.xml

@@ -6,15 +6,18 @@
 <chapter id="kea-config">
   <title>Kea Configuration</title>
 
-  <para>Kea is designed to allow different methods by which it can be
-    configured, each method being implemented by a component known as a
-    configuration backend.  At present, only one such backend is
-    available, that allowing configuration by means of a JSON file.</para>
-
-  <section id="json-backend">
-    <title>JSON Configuration Backend</title>
-    <para>JSON is the default configuration backend.
-    It assumes that the servers are started from the command line
+  <para>Kea is using JSON structures to handle configuration. Previously
+  we there was a concept of other configuration backends, but that never was
+  implemented and the idea was abandoned.</para>
+
+  <section id="json">
+    <title>JSON Configuration</title>
+    <para>JSON is notation used throughout the Kea project. The most obvious
+    usage is for configuration file, but it is also used for sending commands
+    over Management API (see <xref linkend="ctrl-channel"/>) and for
+    communicating between DHCP servers and DDNS update daemon.</para>
+
+    <para>Typical usage assumes that the servers are started from the command line
     (either directly or using a script, e.g. <filename>keactrl</filename>).
     The JSON backend uses certain signals to influence Kea. The
     configuration file is specified upon startup using the -c parameter.</para>
@@ -23,9 +26,14 @@
       <title>JSON Syntax</title>
       <para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined
       in an extended JSON format. Basic JSON is defined in <ulink
-      url="http://tools.ietf.org/html/rfc4627">RFC 4627</ulink>.  Kea components
-      use an extended JSON with additional features allowed:
-      in that they allow shell-style
+      url="http://tools.ietf.org/html/rfc7159">RFC 7159</ulink>. Note that Kea
+      1.2 introduces a new parser that is better at following the JSON spec.  In
+      particular, the only values allowed for boolean are true or false (all
+      lowercase). The capitalized versions (True or False) are not accepted.
+      </para>
+
+      <para>Kea components use an extended JSON with additional features
+      allowed:
       <itemizedlist>
         <listitem>
           <simpara>shell comments: any text after the hash (#)
@@ -116,7 +124,7 @@
 # The whole configuration structure ends here.
 }
 </screen>
-	</para>
+        </para>
 
         <para>More examples are available in the installed
         <filename>share/doc/kea/examples</filename> directory.</para>
@@ -140,7 +148,7 @@
         valid-lifetime in the Dhcp6 component can be referred to as
         Dhcp6/valid-lifetime and the pool in the first subnet defined in the DHCPv6
         configuration as Dhcp6/subnet6[0]/pool.</para>
-      
+
       <!-- @todo Add a reference here after #3422 is done -->
     </section>
 

doc/guide/dhcp4-srv.xml

@@ -2978,7 +2978,7 @@ It is merely echoed by the server
 
       <para>
         It is possible to store host reservations in MySQL or PostgreSQL database. See
-        <xref linkend="hosts-storage4"/> for information on how to configure Kea to use
+        <xref linkend="hosts4-storage"/> for information on how to configure Kea to use
         reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated
         tools for managing reservations in a database. The Kea wiki <ulink
         url="http://kea.isc.org/wiki/HostReservationsHowTo" /> provides detailed

doc/guide/dhcp6-srv.xml

@@ -4,7 +4,7 @@
 <!ENTITY mdash  "&#x2014;" >
 ]>
 
-  <chapter id="dhcp6">
+ <chapter id="dhcp6">
     <title>The DHCPv6 Server</title>
 
     <section id="dhcp6-start-stop">
@@ -3496,7 +3496,8 @@ If not specified, the default value is:
       provided by the clients.
       </para>
       <para>
-      The configuration is controlled by the <command>mac-sources</command>parameter as follows:
+      The configuration is controlled by the <command>mac-sources</command>
+      parameter as follows:
         <screen>
 "Dhcp6": {
     <userinput>"mac-sources": [ "method1", "method2", "method3", ... ]</userinput>,
@@ -3543,7 +3544,7 @@ If not specified, the default value is:
         that those addresses are based on EUI-64, which contains MAC address. This
         method is not completely reliable, as clients may use other link-local address
         types.  In particular, privacy extensions, defined in
-        <ulink utl="http://tools.ietf.org/html/rfc4941">RFC 4941</ulink>, do not use
+        <ulink url="http://tools.ietf.org/html/rfc4941">RFC 4941</ulink>, do not use
         MAC addresses.  Also note that successful extraction requires that the
         address's u-bit must be set to 1 and its g-bit set to 0, indicating that it
         is an interface identifier as per
@@ -3600,7 +3601,11 @@ If not specified, the default value is:
         </simpara>
       </listitem>
     </itemizedlist>
-    </para>
+  </para>
+
+  <para>Empty mac-sources is not allowed. If you do not want to specify it,
+  either simply omit mac-sources definition or specify it with the "any" value
+  which is the default.</para>
   </section>
 
     <section id="dhcp6-decline">

src/bin/dhcp6/dhcp6.dox

@@ -245,8 +245,9 @@ tokens (e.g. TOPLEVEL_JSON and TOPLEVEL_DHCP6). For complete list of available
 starting contexts, see @ref isc::dhcp::Parser6Context::ParserType. The
 Parse6Context::parse() method takes one parameter that specifies, whether the
 data to be parsed is expected to have a generic JSON or the whole configuration
-(DHCP6). This is only a proof-of-concept, but similar approach can be implemented
-to parse only subnets, host reservations, options or basically any other elements.
+(DHCP6). This feature is currently mostly used by unit-tests (which often skip
+the '{ "Dhcp6": {' preamble), but it is expected to be soon used for parsing
+subnets only, host reservations only, options or basically any other elements.
 For example, to add the ability to parse only pools, the following could be added:
 
 @code
@@ -256,15 +257,15 @@ start: TOPLEVEL_GENERIC_JSON sub_json
      ;
 @endcode
 
-The code on trac5036 branch contains the code definition and the
-Kea-dhcp6 updated to use that new parser. I'm sure that parser does
-not cover 100% of all parameters, but so far it is able to load all
-examples from doc/example/kea6. It is also able to parser # comments
-(bash style, starting at the beginning or middle of the line), //
-comments (C++ style, can start anywhere) or / * * / comments (C style,
-can span multiple lines).
+The parser code contains the code definition and the Kea-dhcp6 updated
+to use that new parser. That parser is able to to load all examples
+from doc/example/kea6. It is also able to parser # comments (bash
+style, starting at the beginning or middle of the line), // comments
+(C++ style, can start anywhere) or / * * / comments (C style, can span
+multiple lines).
 
-This parser is currently used. See configure() method in kea_controller.cc.
+This parser is currently used in production code. See configure()
+method in kea_controller.cc.
 
 There are several new unit-tests written, but the code mostly reuses existing
 one to verify that existing functionality was not compromised. There are
@@ -310,21 +311,29 @@ check if it's a valid JSON syntax, but also check that the resulting structures
 match expected syntax (if subnet6 are really an array, not a map, if
 timers are expressed as integers, not as strings etc.).
 
-However, there are times when we need to parse a string as arbitrary JSON.
-For example, if we're in Dhcp6 and the config contains entries for DhcpDdns
-or Dhcp4. If we were to use naive approach, the lexer would go through
-that content and most likely find some tokens that are also used in Dhcp6.
-for example 'renew-timer' would be detected and the parser would complain
-that it was not expected. To avoid this problem, parser context was
-introduced. When the syntactic parser expects certain type of content,
-it calls @ref isc::dhcp::Parser6Context::enter() method to indicate what
-type of content is expected. For example, when Dhcp6 parser discovers
+However, there are times when we need to parse a string as arbitrary
+JSON.  For example, if we're in Dhcp6 and the config contains entries
+for DhcpDdns or Dhcp4. If we were to use naive approach, the lexer
+would go through that content and most likely find some tokens that
+are also used in Dhcp6.  for example 'renew-timer' would be detected
+and the parser would complain that it was not expected. To avoid this
+problem, syntactic context was introduced. When the syntactic parser
+expects certain type of content, it calls @ref
+isc::dhcp::Parser6Context::enter() method to indicate what type of
+content is expected. For example, when Dhcp6 parser discovers
 uninteresting content like Dhcp4, it enters NO_KEYWORD mode. In this
 mode, everything is parsed as generic maps, lists, integers, booleans
 or strings. This results in generic JSON structures without any syntax
-checking. Of course a corresponding/balanced @ref
-isc::dhcp::Parser6Context::leave() call is required before leaving
-the context to come back to the previous context.
+checking. A corresponding/balanced @ref
+isc::dhcp::Parser6Context::leave() call is required before leaving the
+context to come back to the previous context.
+
+Entering a new syntactic context is useful in several ways.  First, it allows
+the parser to avoid conflicts. Second, it allows the lexer to return different
+tokens depending on context (e.g. if "renew-timer" string is detected, the lexer
+will return STRING token if in JSON mode or RENEW_TIMER if in DHCP6
+mode). Finally, the syntactic context allows the error message to be more
+descriptive if the input string does not parse properly.
 
 Details of the refactor of the classes derived from DhcpConfigParser are
 documented in http://kea.isc.org/wiki/SimpleParser.

src/bin/dhcp6/parser_context.h

@@ -286,13 +286,14 @@ public:
 
     /// @brief Enter a new syntactic context
     ///
-    /// Entering a nex syntactic context is useful in several ways.
+    /// Entering a new syntactic context is useful in several ways.
     /// First, it allows the parser to avoid conflicts. Second, it
     /// allows the lexer to return different tokens depending on
     /// context (e.g. if "renew-timer" string is detected, the lexer
     /// will return STRING token if in JSON mode or RENEW_TIMER if
-    /// in DHCP6 mode. Finally, the stntactic context allows the
-    /// error message to be more descriptive.
+    /// in DHCP6 mode. Finally, the syntactic context allows the
+    /// error message to be more descriptive if the input string
+    /// does not parse properly.
     ///
     /// @param ctx the syntactic context to enter into
     void enter(const ParserContext& ctx);