Try to clarify rewrite docs
making response rewrites more prominent
@@ -11,24 +11,20 @@ Rewrites are invisible to the client. There are simple rewrites (fast) and compl
## Syntax
+A simplified/easy to digest syntax for *rewrite* is...
~~~
rewrite [continue|stop] FIELD FROM TO
~~~
-* **FIELD** is (`type`, `class`, `name`, ...)
-* **FROM** is the exact name of type to match
-* **TO** is the destination name or type to rewrite to
-
-When the FIELD is `type` and FROM is (`A`, `MX`, etc.), the type of the message will be rewritten;
+* **FIELD** indicates what part of the request/response is being re-written.
+ * `type` - the type field of the request will be rewritten. FROM/TO must be a DNS record type (`A`, `MX`, etc);
e.g., to rewrite ANY queries to HINFO, use `rewrite type ANY HINFO`.
-
-When the FIELD is `class` and FROM is (`IN`, `CH`, or `HS`) the class of the message will be
-rewritten; e.g., to rewrite CH queries to IN use `rewrite class CH IN`.
-
-When the FIELD is `name` the query name in the message is rewritten; this
-needs to be a full match of the name, e.g., `rewrite name miek.nl example.org`.
-
-When the FIELD is `edns0` an EDNS0 option can be appended to the request as described below.
+ * `class` - the class of the message will be rewritten. FROM/TO must be a DNS class type (`IN`, `CH`, or `HS`) e.g., to rewrite CH queries to IN use `rewrite class CH IN`.
+ * `name` - the query name in the _request_ is rewritten; by default this is a full match of the name, e.g., `rewrite name miek.nl example.org`. Other match types are supported, see the **Name Field Rewrites** section below.
+ * `answer name` - the query name in the _response_ is rewritten. This option has special restrictions and requirements, in particular it must always combined with a `name` rewrite. See below in the **Response Rewrites** section.
+ * `edns0` - an EDNS0 option can be appended to the request as described below in the **EDNS0 Options** section.
+* **FROM** is the name or type to match
+* **TO** is the destination name or type to rewrite to
If you specify multiple rules and an incoming query matches on multiple rules, the rewrite
will behave as following
@@ -235,3 +231,13 @@ rewrite edns0 subnet set 24 56
* If the query has source IP as IPv4, the first 24 bits in the IP will be the network subnet.
* If the query has source IP as IPv6, the first 56 bits in the IP will be the network subnet.
+
+## Full Syntax
+
+The full plugin usage syntax is harder to digest...
+~~~
+rewrite [continue|stop] {type|class|edns0|name [exact|prefix|suffix|substring|regex [FROM TO answer name]]} FROM TO
+~~~
+
+The syntax above doesn't cover the multi line block option for specifying a name request+response rewrite rule described in the **Response Rewrite** section.
+
