Update README.md (#2856)

General syntactic cleanup.

plugin/rewrite/README.md

@@ -11,16 +11,16 @@ Rewrites are invisible to the client. There are simple rewrites (fast) and compl
 
 ## Syntax
 
-A simplified/easy to digest syntax for *rewrite* is...
+A simplified/easy-to-digest syntax for *rewrite* is...
 ~~~
 rewrite [continue|stop] FIELD [FROM TO|FROM TTL]
 ~~~
 
 * **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);
+   * `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`.
-   * `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`.
+   * `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 example.net 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.
@@ -31,37 +31,37 @@ e.g., to rewrite ANY queries to HINFO, use `rewrite type ANY HINFO`.
 * **TO** is the destination name or type to rewrite to
 * **TTL** is the number of seconds to set the TTL value to
 
-If you specify multiple rules and an incoming query matches on multiple rules, the rewrite
-will behave as following
-* `continue` will continue apply the next rule in the rule list.
-* `stop` will consider the current rule is the last rule and will not continue.  Default behaviour
-for not specifying this rule processing mode is `stop`
+If you specify multiple rules and an incoming query matches multiple rules, the rewrite
+will behave as follows:
+
+   * `continue` will continue applying the next rule in the rule list.
+   * `stop` will consider the current rule the last rule and will not continue.  The default behaviour is `stop`
 
 ### Name Field Rewrites
 
-The `rewrite` plugin offers the ability to match on the name in the question section of
-a DNS request. The match could be exact, substring, or based on a prefix, suffix, or regular
-expression. If the newly used name is not a legal domain name the plugin returns an error to the
+The `rewrite` plugin offers the ability to match the name in the question section of
+a DNS request. The match could be exact, a substring match, or based on a prefix, suffix, or regular
+expression. If the newly used name is not a legal domain name, the plugin returns an error to the
 client.
 
-The syntax for the name re-writing is as follows:
+The syntax for name rewriting is as follows:
 
 ```
 rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING
 ```
 
-The match type, i.e. `exact`, `substring`, etc., triggers re-write:
+The match type, e.g., `exact`, `substring`, etc., triggers rewrite:
 
-* **exact** (default): on exact match of the name in the question section of a request
+* **exact** (default): on an exact match of the name in the question section of a request
 * **substring**: on a partial match of the name in the question section of a request
 * **prefix**: when the name begins with the matching string
 * **suffix**: when the name ends with the matching string
 * **regex**: when the name in the question section of a request matches a regular expression
 
-If the match type is omitted, the `exact` match type is being assumed.
+If the match type is omitted, the `exact` match type is assumed.
 
-The following instruction allows re-writing the name in the query that
-contains `service.us-west-1.example.org` substring.
+The following instruction allows rewriting names in the query that
+contain the substring `service.us-west-1.example.org`:
 
 ```
 rewrite name substring service.us-west-1.example.org service.us-west-1.consul
@@ -70,10 +70,10 @@ rewrite name substring service.us-west-1.example.org service.us-west-1.consul
 Thus:
 
 * Incoming Request Name: `ftp.service.us-west-1.example.org`
-* Re-written Request Name: `ftp.service.us-west-1.consul`
+* Rewritten Request Name: `ftp.service.us-west-1.consul`
 
-The following instruction uses regular expressions. The name in a request
-matching `(.*)-(us-west-1)\.example\.org` regular expression is being replaces with
+The following instruction uses regular expressions. Names in requests
+matching the regular expression `(.*)-(us-west-1)\.example\.org` are replaced with
 `{1}.service.{2}.consul`, where `{1}` and `{2}` are regular expression match groups.
 
 ```
@@ -83,7 +83,7 @@ rewrite name regex (.*)-(us-west-1)\.example\.org {1}.service.{2}.consul
 Thus:
 
 * Incoming Request Name: `ftp-us-west-1.example.org`
-* Re-written Request Name: `ftp.service.us-west-1.consul`
+* Rewritten Request Name: `ftp.service.us-west-1.consul`
 
 The following example rewrites the `schmoogle.com` suffix to `google.com`.
 
@@ -93,9 +93,9 @@ rewrite name suffix .schmoogle.com. .google.com.
 
 ### Response Rewrites
 
-When re-writing incoming DNS requests' names, CoreDNS re-writes the `QUESTION SECTION`
-section of the requests. It may be necessary to re-write the `ANSWER SECTION` of the
-requests, because some DNS resolvers would treat the mismatch between `QUESTION SECTION`
+When rewriting incoming DNS requests' names, CoreDNS re-writes the `QUESTION SECTION`
+section of the requests. It may be necessary to rewrite the `ANSWER SECTION` of the
+requests, because some DNS resolvers treat mismatches between the `QUESTION SECTION`
 and `ANSWER SECTION` as a man-in-the-middle attack (MITM).
 
 For example, a user tries to resolve `ftp-us-west-1.coredns.rocks`. The
@@ -105,9 +105,9 @@ CoreDNS configuration file has the following rule:
 rewrite name regex (.*)-(us-west-1)\.coredns\.rocks {1}.service.{2}.consul
 ```
 
-CoreDNS instance re-wrote the request to `ftp-us-west-1.coredns.rocks` with
+CoreDNS rewrote the request from `ftp-us-west-1.coredns.rocks` to
 `ftp.service.us-west-1.consul` and ultimately resolved it to 3 records.
-The resolved records, see `ANSWER SECTION`, were not from `coredns.rocks`, but
+The resolved records, in the `ANSWER SECTION` below, were not from `coredns.rocks`, but
 rather from `service.us-west-1.consul`.
 
 
@@ -130,10 +130,10 @@ ftp.service.us-west-1.consul. 0    IN A    10.20.20.20
 ftp.service.us-west-1.consul. 0    IN A    10.30.30.30
 ```
 
-The above is the mismatch.
+The above is a mismatch between the question asked and the answer provided.
 
-The following configuration snippet allows for the re-writing of the
-`ANSWER SECTION`, provided that the `QUESTION SECTION` was re-written:
+The following configuration snippet allows for rewriting of the
+`ANSWER SECTION`, provided that the `QUESTION SECTION` was rewritten:
 
 ```
     rewrite stop {
@@ -172,21 +172,21 @@ rewrite [continue|stop] {
 }
 ```
 
-Note that the above syntax is strict.  For response rewrites only `name`
+Note that the above syntax is strict.  For response rewrites, only `name`
 rules are allowed to match the question section, and only by match type
-`regex`. The answer rewrite must be after the name, as ordered in the
+`regex`. The answer rewrite must be after the name, as in the
 syntax example. There must only be two lines (a `name` followed by an
-`answer`) in the brackets, additional rules are not supported.
+`answer`) in the brackets; additional rules are not supported.
 
-An alternate syntax for the rewrite of DNS request and response is as
+An alternate syntax for rewriting a DNS request and response is as
 follows:
 
 ```
 rewrite [continue|stop] name regex STRING STRING answer name STRING STRING
 ```
 
-When using `exact` name rewrite rules, answer gets re-written automatically,
-and there is no need defining `answer name` instruction. The below rule
+When using `exact` name rewrite rules, the answer gets rewritten automatically,
+and there is no need to define `answer name`. The rule below
 rewrites the name in a request from `RED` to `BLUE`, and subsequently
 rewrites the name in a corresponding response from `BLUE` to `RED`. The
 client in the request would see only `RED` and no `BLUE`.
@@ -197,9 +197,9 @@ rewrite [continue|stop] name exact RED BLUE
 
 ### TTL Field Rewrites
 
-At times, the need for rewriting TTL value could arise. For example, a DNS server
-may prevent caching by setting TTL as low as zero (`0`). An administrator
-may want to increase the TTL to prevent caching, e.g. to 15 seconds.
+At times, the need to rewrite a TTL value could arise. For example, a DNS server
+may not cache records with a TTL of zero (`0`). An administrator
+may want to increase the TTL to ensure it is cached, e.g., by increasing it to 15 seconds.
 
 In the below example, the TTL in the answers for `coredns.rocks` domain are
 being set to `15`:
@@ -210,8 +210,8 @@ being set to `15`:
     }
 ```
 
-By the same token, an administrator may use this feature to force caching by
-setting TTL value really low.
+By the same token, an administrator may use this feature to prevent or limit caching by
+setting the TTL value really low.
 
 
 The syntax for the TTL rewrite rule is as follows. The meaning of
@@ -223,7 +223,7 @@ rewrite [continue|stop] ttl [exact|prefix|suffix|substring|regex] STRING SECONDS
 
 ## EDNS0 Options
 
-Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the request.
+Using the FIELD edns0, you can set, append, or replace specific EDNS0 options in the request.
 
 * `replace` will modify any "matching" option with the specified option. The criteria for "matching" varies based on EDNS0 type.
 * `append` will add the option only if no matching option exists
@@ -235,7 +235,7 @@ Currently supported are `EDNS0_LOCAL`, `EDNS0_NSID` and `EDNS0_SUBNET`.
 
 This has two fields, code and data. A match is defined as having the same code. Data may be a string or a variable.
 
-* A string data can be treated as hex if it starts with `0x`. Example:
+* A string data is treated as hex if it starts with `0x`. Example:
 
 ~~~ corefile
 . {
@@ -244,7 +244,7 @@ This has two fields, code and data. A match is defined as having the same code.
 }
 ~~~
 
-rewrites the first local option with code 0xffee, setting the data to "abcd". Equivalent:
+rewrites the first local option with code 0xffee, setting the data to "abcd". This is equivalent to:
 
 ~~~ corefile
 . {
@@ -256,8 +256,8 @@ rewrites the first local option with code 0xffee, setting the data to "abcd". Eq
   {qname}, {qtype}, {client_ip}, {client_port}, {protocol}, {server_ip}, {server_port}.
 
 * If the metadata plugin is enabled, then labels are supported as variables if they are presented within curly brackets.
-the variable data will be filled with the value associated with that label. If that label is not provided,
-the variable will be silently substitute by an empty string.
+The variable data will be replaced with the value associated with that label. If that label is not provided,
+the variable will be silently substituted with an empty string.
 
 Examples:
 
@@ -289,8 +289,8 @@ Example:
 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.
+* If the query's source IP address is an IPv4 address, the first 24 bits in the IP will be the network subnet.
+* If the query's source IP address is an IPv6 address, the first 56 bits in the IP will be the network subnet.
 
 ## Full Syntax
 
@@ -299,4 +299,4 @@ 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.
+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.