extend cnfvar.py description

Also amend the formatting that got distorted by autopep8 in
Autotest.

diff --git a/src/cnfvar.py b/src/cnfvar.py
index 397661b..fe29150 100644 (file)
--- a/src/cnfvar.py
+++ b/src/cnfvar.py
@@ -20,37 +20,55 @@
 
 """
 
-SUMMARY
-------------------------------------------------------
+summary
+-------------------------------------------------------------------------------
+Represent CNF_VARs as recursive structures.
 
-Copyright: Intra2net AG
+Copyright: 2014–2017 Intra2net AG
 License:   GPLv2+
 
 
-CONTENTS
-------------------------------------------------------
-Represent CNF_VARs as recursive structures.
+contents
+-------------------------------------------------------------------------------
+
+This module provides read and write functionality for the Intra2net *CNF*
+format. Two different syntaxes are available: classical *CNF* and a JSON
+representation. Both versions are commonly understood by Intra2net software.
+For example, the ::
+
+    # get_cnf routing 2
+    1 ROUTING,2: "192.168.55.0"
+    2    (1) ROUTING_COMMENT,0: ""
+    3    (1) ROUTING_DNS_RELAYING_ALLOWED,0: "1"
+    4    (1) ROUTING_EMAIL_RELAYING_ALLOWED,0: "1"
+    5    (1) ROUTING_FIREWALL_RULESET_REF,0: "9"
+    6    (1) ROUTING_GATEWAY,0: "10.0.254.1"
+    7    (1) ROUTING_NAT_INTO,0: "0"
+    8    (1) ROUTING_NETMASK,0: "255.255.255.0"
+    9    (1) ROUTING_PROXY_PROFILE_REF,0: "2"
 
-.. todo:: Decide on some facility for automatic fixup of line number values. The
+.. todo::
+    Decide on some facility for automatic fixup of line number values. The
     internal representation is recursive so line numbers are not needed to
-    establish a variable hierarchy. They might as well be omitted from the
-    json input and only added when writing cnf. For the time being a lack
-    of the "number" field is interpreted as an error. Though it should at
-    least optionally be possible to omit the numbers entirely and have a
-    function add them after the fact. This might as well be added to
-    :py:func:`is_cnf` though it would be counterintuitive to have a predicate
-    mutate its argument. So maybe it could return a second argument to
-    indicate a valid structure that needs fixup or something like that.
-
-.. note:: The variable values of get_cnf seems to be encoded in latin1, and
-          set_cnf seems to require latin1-encoded values (not var names).
-          Function :py:func:`read_cnf` converts this to unicode and functions
-          :py:func:`dump_cnf_string`, :py:func:`print_cnf`, and
-          :py:func:`write_cnf` convert unicode back to latin1.
-
-
-INTERFACE
-------------------------------------------------------
+    establish a variable hierarchy. They might as well be omitted from the json
+    input and only added when writing cnf. For the time being a lack of the
+    "number" field is interpreted as an error. Though it should at least
+    optionally be possible to omit the numbers entirely and have a function add
+    them after the fact. This might as well be added to :py:func:`is_cnf`
+    though it would be counterintuitive to have a predicate mutate its
+    argument. So maybe it could return a second argument to indicate a valid
+    structure that needs fixup or something like that.
+
+.. note::
+    The variable values of get_cnf seems to be encoded in latin1, and set_cnf
+    seems to assume latin1-encoded values (not var names). Function
+    :py:func:`read_cnf` converts this to unicode and functions
+    :py:func:`dump_cnf_string`, :py:func:`print_cnf`, and :py:func:`write_cnf`
+    convert unicode back to latin1.
+
+
+implementation
+-------------------------------------------------------------------------------
 """
 
 import functools