Try to clarify rewrite docs (#1795)

making response rewrites more prominent

1 files changed, 19 insertions, 13 deletions

diff --git a/plugin/rewrite/README.md b/plugin/rewrite/README.md
index de2fae64c..a25017ebf 100644
--- a/plugin/rewrite/README.md
+++ b/plugin/rewrite/README.md
@@ -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.
+