improve description of cnfvar.py command line usage

Try it out:

    $ ssh some-intranator '/usr/intranator/bin/get_cnf' |python3 src/cnfvar.py -

diff --git a/src/cnfvar.py b/src/cnfvar.py
index 04e97b2..58d078b 100644 (file)
--- a/src/cnfvar.py
+++ b/src/cnfvar.py
@@ -34,9 +34,10 @@ 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
+On the command line, raw CNF is accepted if the option ``-`` is given: ::
+
+    $ get_cnf routing 2 |python3 cnfvar.py - <<ENOUGH
     1 ROUTING,2: "192.168.55.0"
     2    (1) ROUTING_COMMENT,0: ""
     3    (1) ROUTING_DNS_RELAYING_ALLOWED,0: "1"
@@ -46,6 +47,24 @@ For example, the ::
     7    (1) ROUTING_NAT_INTO,0: "0"
     8    (1) ROUTING_NETMASK,0: "255.255.255.0"
     9    (1) ROUTING_PROXY_PROFILE_REF,0: "2"
+    ENOUGH
+
+    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"
+
+The input takes one round-trip through the parsers and will error out on
+problematic lines. Thus, ``cnfvar.py`` can be used to syntax-check CNF data.
+
+Note that line numbers may be arbitrarily reassigned in the process. Of course,
+parent references and the relative ordering of lines will be preserved in this
+case.
 
 .. todo::
     Decide on some facility for automatic fixup of line number values. The