caddyfile: Update rewrite and path matcher docs

Regarding URI encoding and path cleaning

src/docs/markdown/caddyfile/directives/rewrite.md

@@ -4,9 +4,9 @@ title: rewrite (Caddyfile directive)
 
 # rewrite
 
-Rewrites the request internally. A rewrite changes some or all of the request URI.
+Rewrites the request internally. A rewrite changes some or all of the request URI. Note that the URI does not include scheme or authority (host & port), and clients typically do not send fragments. Thus, this directive is mostly used for path and query string manipulation.
 
-The `rewrite` directive implies the intent to accept the request, but with modifications. It is mutually exclusive to other `rewrite` directives in the same block, so it is safe to define rewrites that would otherwise cascade into each other; only the first matching rewrite will be executed.
+The `rewrite` directive implies the intent to accept the request, but with modifications. It is mutually exclusive to other `rewrite` directives in the same block, so it is safe to define rewrites that would otherwise cascade into each other as only the first matching rewrite will be executed.
 
 Because `rewrite` essentially performs an internal redirect, the Caddyfile adapter will not fold any subsequent, adjacent handlers into the same route if their matchers happen to be exactly the same. This allows the matchers of the next handlers to be deferred until after the rewrite. In other words, a matcher that matches a request before the `rewrite` might not match the same request after the `rewrite`. If you want your `rewrite` to share a route with other handlers, use the [`route`](route) or [`handle`](handle) directives.
 
@@ -17,7 +17,7 @@ Because `rewrite` essentially performs an internal redirect, the Caddyfile adapt
 rewrite [<matcher>] <to>
 ```
 
-- **&lt;to&gt;** is the URI to set on the request. Only designated parts will be replaced. The URI path is any substring that comes before `?`. If `?` is omitted, then the whole token is considered to be the path.
+- **&lt;to&gt;** is the URI to rewrite the request to. Only the components of the URI (path or query string) that are specified in the rewrite will be operated on. The URI path is any substring that comes before `?`. If `?` is omitted, then the whole token is considered to be the path.
 
 
 ## Examples

src/docs/markdown/caddyfile/directives/uri.md

@@ -6,7 +6,7 @@ title: uri (Caddyfile directive)
 
 Manipulates a request's URI. It can strip path prefix/suffix or replace substrings on the whole URI.
 
-This directive is distinct from [`rewrite`](rewrite) in that `uri` _partially_ changes the URI, rather than setting it to something completely different as `rewrite` does. While `rewrite` is treated specially as an internal redirect, `uri` is just another handler.
+This directive is distinct from [`rewrite`](rewrite) in that `uri` _differentiably_ changes the URI, rather than resetting it to something completely different as `rewrite` does. While `rewrite` is treated specially as an internal redirect, `uri` is just another middleware.
 
 
 ## Syntax
@@ -21,21 +21,24 @@ uri [<matcher>] path_regexp  <target> <replacement>
 ```
 
 - The first (non-matcher) argument specifies the operation:
-	- **strip_prefix** strips a prefix from the path, if it has the prefix.
-	- **strip_suffix** strips a suffix from the path, if it has the suffix.
+	- **strip_prefix** strips the prefix from the path.
+	- **strip_suffix** strips the suffix from the path.
 	- **replace** performs a substring replacement across the whole URI.
 	- **path_regexp** performs a regular expression replacement on the path portion of the URI.
 - **&lt;target&gt;** is the prefix, suffix, or search string/regular expression. If a prefix, the leading forward slash may be omitted, since paths always start with a forward slash.
 - **&lt;replacement&gt;** is the replacement string (only valid with `replace` and `path_regexp`). Supports using capture groups with `$name` or `${name}` syntax, or with a number for the index, such as `$1`. See the [Go documentation](https://golang.org/pkg/regexp/#Regexp.Expand) for details.
 - **&lt;limit&gt;** is an optional limit to the maximum number of replacements (only valid with `replace`).
 
+URI mutations occur on the normalized or unescaped form of the URI. However, escape sequences can be used in the prefix or suffix patterns to match only those literal escapes at those positions in the request path. For example, `uri strip_prefix /a/b` will rewrite both `/a/b/c` and `/a%2Fb/c` to `/c`; and `uri strip_prefix /a%2Fb` will rewrite `/a%2Fb/c` to `/c`, but won't match `/a/b/c`.
+
+The URI path is cleaned of directory traversal dots before modifications. Additionally, multiple slashes (such as `//`) are merged unless the `<target>` contains multiple slashes too.
 
 ## Similar directives
 
 Some other directives can also manipulate the request URI.
 
-- [`rewrite`](rewrite) will change the entire path and query to a new value, instead of doing a partial change like `uri` does.
-- [`handle_path`](handle_path) does the same as [`handle`](handle), but it strips a prefix from the request before running its handlers. Can be used instead of `uri strip_prefix` to save a line of config in many situations.
+- [`rewrite`](rewrite) changes the entire path and query to a new value instead of partially changing the value.
+- [`handle_path`](handle_path) does the same as [`handle`](handle), but it strips a prefix from the request before running its handlers. Can be used instead of `uri strip_prefix` to eliminate one extra line of configuration in many cases.
 
 
 ## Examples