From d075e3ec1725183b137384e4e3dc2e90f1eae3b2 Mon Sep 17 00:00:00 2001
From: Daniel Akulenok <gitlab@valid.dk>
Date: Wed, 28 Jan 2026 23:03:25 +0100
Subject: [PATCH] docs: update README.md with port/tls parameter patterns

- Add clarification on different parameter combinations (port/dscp vs port/tls)
- Replace generic 'IP_PORT_DSCP_OPTION' with 'ADDRESS_PORT_TLS_OPTION' example
- Update all configuration examples to show port/tls parameters
- Document usage of forwarders with TLS support
- Improve documentation of flexible configuration formats
---
 README.md | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 8330195..9491dee 100644
--- a/README.md
+++ b/README.md
@@ -126,38 +126,43 @@ Simple options are defined just as that.
 ```
 
 Some options have several optional parameters. For those, a somewhat flexible 
-configuration format has been created
+configuration format has been created. Common patterns include:
+
+- **Address with Port/DSCP**: Used by options like `primaries`, `parental_agents` (e.g., `address [ port <port> ] [ dscp <dscp> ]`)
+- **Address with Port/TLS**: Used by options like `forwarders` (e.g., `address [ port <port> ] [ tls <tls> ]`)
+
 ```
-      IP_PORT_DSCP_OPTION: # Any option that is defined as one of:
-      #  <option> [ port <port> ] [ dscp <dscp> ] { <address> [ port <port> ] [ dscp <dscp> ]; ... }
-      #  <option> [ port <port> ] [ dscp <dscp> ] { <address> [ port <port> ] [ key <key> ] [ tls <tls> ]; ... }
+      ADDRESS_PORT_TLS_OPTION: # Example: forwarders option
+      # <option> [ port <port> ] [ tls <tls> ] { <address> [ port <port> ] [ tls <tls> ]; ... }
       # has a few optional syntaxes 
       # Example 1: Simple address list
         - ADDRESS1
         - ADDRESS2
-      # Example 2: To define source port/dscp, use 'addresses' sub-element
+      # Example 2: To define global port/tls, use 'addresses' sub-element
         [ port: PORT ]
-        [ dscp: DSCP ]
+        [ tls: TLS_NAME ]
         addresses:
           - ADDRESS1
           - ADDRESS2
           - 127.0.0.1
-      # Example 3: To define target port/dscp, use 'addresses' as a list of dicts
+      # Example 3: To define per-address port/tls, use 'addresses' as a list of dicts
         addresses:
           - address: ADDRESS
             [ port: PORT ]
-            [ dscp: DSCP ]
+            [ tls: TLS_NAME ]
           - address: 127.0.0.1
             port: 53
           - address: 127.0.0.1
-            dscp: 42
-          - address: 127.0.0.1
-            port: 5353
-            dscp: 42
+            port: 853
+            tls: dot-tls
+          - address: 8.8.8.8
+            port: 853
+            tls: google-tls
       # Example 4: The various formats can be mixed and matched within the main element
         - ADDRESS1
         - address: ADDRESS2
           port: PORT
+          tls: TLS_NAME
 ```