From 251a78d8251f78258a8e737b482216ab1131dfbf Mon Sep 17 00:00:00 2001
From: Daniel Akulenok <dak@keepit.com>
Date: Tue, 23 Aug 2022 13:17:19 +0200
Subject: [PATCH] readme

---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 38 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 0b4787a..3b1be19 100644
--- a/README.md
+++ b/README.md
@@ -29,20 +29,42 @@ If you are missing some statements in your resulting config, it is most likely b
 
 The main configuration variable used are a series of bind_*_config variables (See [Role Variables]) that have the following syntax
 
+Every config starts by defining the file name. Each file can contain any amount of top-level statements,
+as permitted by named.conf 
+
 ```
 bind9_host_config:
-  - name: FILENAME # The filename of your desired config file. Will overwrite and manage by BIND if used
-    SECTION_NAME: # The section name of the bind config you want to define. Can be 'acl', 'options', 'zone', etc.
+  - name: FILENAME # The filename of your desired config file.
+                   # You also need to specify a corresponding `include:` for the file
+    SECTION_NAME: # The section name of the bind config you want to define.
+                  # Can be 'acl', 'options', 'zone', etc.
                   # See: https://bind9.readthedocs.io/en/v9_18_4/reference.html#configuration-file-grammar
+    SECTION_2_NAME: # Every file can have as many sections as needed. Generally, try to keep 
+                    # all definitions and references together in a file.
+```
 
-      OPTION: # Any option that is valid within the section
-        - name: # Any option that can be repeated and has a name, will need to have a unique "name" var
-          addresses: # Any list of addresses, will need to include a list of addresses like so.
-                     # Even if they only contain one element
-            - 127.0.0.1
-            - 127.0.0.2
+Any option that can be defined multiple times in a named.conf, must be defined as a list
+```
+bind9_host_config:
+  - name: named.conf.local
+    acl:
+      - name: ELEMENT_NAME
+        addresses: 
+          - 127.0.0.1
+          - 127.0.0.2
+      - name: ELEMENT_2_NAME
+        addresses:
+          - 127.0.0.3
+```
+
+Simple options are defined just as that.
+```
       SIMPLE_OPTION: string, boolean or integer value
+```
 
+Some options have several optional parameters. For those, a somewhat flexible 
+configuration format has been created
+```
       IP_PORT_DSCP_OPTION: # Any option that is defined as:
       #  <option> [ port <port> ] [ dscp <dscp> ] { <address> [ port <port> ] [ dscp <dscp> ]; ... }
       # has a few optional syntaxes 
@@ -55,19 +77,23 @@ bind9_host_config:
         addresses:
           - ADDRESS1
           - ADDRESS2
+          - 127.0.0.1
       # Example 3: To define target port/dscp, use 'addresses' as a list of dicts
         addresses:
           - address: ADDRESS
             [ port: PORT ]
             [ dscp: DSCP ]
+          - address: 127.0.0.1
+            port: 53
+          - address: 127.0.0.1
+            dscp: 42
+          - address: 127.0.0.1
+            port: 5353
+            dscp: 42
       # Example 4: The various formats can be mixed and matched within the main element
         - ADDRESS1
         - address: ADDRESS2
           port: PORT
-            
-    acl: # Sections that can contain multiple elements, or specified multiple times, are always defined as a list
-         # Even when they contain only a single item.
-      - name: my_acl_name # If the variable 
 ```
 
 Role Variables