[master] Merge branch 'trac5112' (Developer's Guide page for parsers)

doc/Makefile.am

 SUBDIRS = guide design
 
 EXTRA_DIST  = version.ent.in Doxyfile Doxyfile-xml
+EXTRA_DIST += devel/bison.dox
 EXTRA_DIST += devel/config-backend.dox
 EXTRA_DIST += devel/contribute.dox
 EXTRA_DIST += devel/mainpage.dox
+EXTRA_DIST += devel/terminology.dox
 EXTRA_DIST += devel/unit-tests.dox
 
 nobase_dist_doc_DATA  = examples/agent/simple.json

doc/devel/mainpage.dox

@@ -119,6 +119,8 @@
  *   - @subpage cplSignals
  *
  * @section miscellaneousTopics Miscellaneous Topics
+ * - @subpage terminology
+ * - @subpage parser
  * - @subpage logKeaLogging
  *   - @subpage logBasicIdeas
  *   - @subpage logDeveloperUse

doc/devel/terminology.dox

+// Copyright (C) 2017 Internet Systems Consortium, Inc. ("ISC")
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+/**
+@page terminology Terminology
+
+This page explains some common abbreviations and terms:
+
+- CA - Control Agent. That's a separate module that talks with Kea DHCPv4, DHCPv6 (and soon also D2)
+  over control channel and exposes their internal commands using RESTful interface.
+
+- D2 - This is a nickname of DHCP-Dynamic DNS server module. Since using the full name is awkward,
+  we often use shortened version of it: D2.
+
+- DHCP - Dynamic Host Configuration Protocol. There are two similar, but operationally different
+  protocols: DHCPv4 and DHCPv6. When v4 or v6 is not specified, the DHCP expression applies to both.
+
+- DHCPv4 - Dynamic Host Configuration Protocol for IPv4, a protocol that defines how IPv4 hosts can
+  obtain IPv4 addresses and other configuration from the servers. Defined in RFC2131.
+
+- DHCPv6 - Dynamic Host Configuration Protocol for IPv6, a protocol that defines how IPv6 hosts and
+  router can obtain IPv6 addresses, IPv6 prefixes and other configuration from the servers. Defined
+  in RFC3315.
+
+*/

src/bin/dhcp6/dhcp6.dox

@@ -24,7 +24,7 @@ component implementation.
 
 @section dhcpv6ConfigParser Configuration Parsers in DHCPv6
 
-Three minutes overview. If you are here only to learn absolute minimum about
+This is a three minutes overview. If you are here only to learn absolute minimum about
 the new parser, here's how you use it:
 
 @code
@@ -39,6 +39,8 @@ the new parser, here's how you use it:
 Note: parsers are currently being migrated to @ref isc::data::SimpleParser. See
 @ref ccSimpleParser page for details.
 
+For more detailed background information about flex and bison, see @ref parser.
+
 The common configuration parsers for the DHCP servers are located in the
 src/lib/dhcpsrv/parsers/ directory. Parsers specific to the DHCPv6 component
 are located in the src/bin/dhcp6/json_config_parser.cc. These parsers derive
@@ -242,6 +244,8 @@ MapElement object, but does not remove it.
 
 @section dhcpv6ConfigSubParser Parsing Partial Configuration in DHCPv6
 
+For more generic description of the solution, see @ref parserSubgrammar.
+
 One another important capability required is the ability to parse not only the
 whole configuration, but a subset of it. This is done by introducing artificial
 tokens (e.g. TOPLEVEL_JSON and TOPLEVEL_DHCP6). For complete list of available
@@ -276,7 +280,7 @@ several new interesting ones, though. ParserTest.file loads all the
 config file examples we have in doc/examples/kea6. This ensures that the
 parser is able to load them and also checks that our examples are sane.
 
-@section dhcp6ParserIncludes Config File Includes
+@section dhcp6ParserIncludes Configuration Files Inclusion
 
 The new parser provides an ability to include files. The syntax was chosen
 to look similar to how Apache includes PHP scripts in HTML code. This
@@ -341,6 +345,8 @@ 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.
 
+For a generic description of the conflict avoidance, see @ref parserFlex.
+
 @section dhcpv6ConfigInherit DHCPv6 Configuration Inheritance
 
 One notable useful feature of DHCP configuration is its parameter inheritance.