flags.xml: Clarify DPI flag docs, replace "URI" with "URL-path", add example

In RFC terms, URI and URL are functionally interchangeable on the web
(all HTTP URLs are URIs; RFC 3986 subsumes both). However, in this
context the docs mean specifically the path component — no scheme, no
host, no port. "URL-path" (as defined in our own directive-dict.xml)
makes this unambiguous, and is consistent with the rest of the
mod_rewrite documentation which uses "URL-path" throughout.

Also add a concrete example showing DPI preventing PATH_INFO
duplication when rewriting a request.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1934232 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/docs/manual/rewrite/flags.xml b/docs/manual/rewrite/flags.xml
index 49a03d2f011b04902d2e5269dbf78650949d4770..7ba9f23ec8319020a2d39fa48fd878a0243ae330 100644 (file)
--- a/docs/manual/rewrite/flags.xml
+++ b/docs/manual/rewrite/flags.xml
@@ -284,23 +284,25 @@ minutes (24 hours) and is returned for all URIs.</p>
 </section>
 
 <section id="flag_dpi"><title>DPI|discardpath</title>
-<p>The DPI flag causes the PATH_INFO portion of the rewritten URI to be
+<p>The DPI flag causes the PATH_INFO portion of the rewritten URL-path to be
 discarded.</p>
-<p>In per-directory context, the URI each <directive>RewriteRule</directive>
-compares against is the concatenation of the current values of the URI
-and PATH_INFO.</p>
-
-<p>The current URI can be the initial URI as requested by the client, the
-result of a previous round of <module>mod_rewrite</module> processing, or the result of
-a prior rule in the current round of <module>mod_rewrite</module> processing.</p>
-
-<p>In contrast, the PATH_INFO that is appended to the URI before each
-rule reflects only the value of PATH_INFO before this round of
-<module>mod_rewrite</module> processing. As a consequence, if large portions
-of the URI are matched and copied into a substitution in multiple
+
+<p>In <glossary ref="perdirectory">per-directory context</glossary>,
+the URL-path each <directive>RewriteRule</directive> compares against
+is the concatenation of the current URL-path and PATH_INFO.</p>
+
+<p>The current URL-path can be the initial path as requested by the
+client, the result of a previous round of <module>mod_rewrite</module>
+processing, or the result of a prior rule in the current round of
+<module>mod_rewrite</module> processing.</p>
+
+<p>In contrast, the PATH_INFO that is appended to the URL-path before
+each rule reflects only the value of PATH_INFO before this round of
+<module>mod_rewrite</module> processing. As a consequence, if large
+portions of the URL-path are matched and copied into a substitution in multiple
 <directive>RewriteRule</directive> directives, without regard for
 which parts of the URI came from the current PATH_INFO, the final
-URI may have multiple copies of PATH_INFO appended to it.</p>
+URL-path may have multiple copies of PATH_INFO appended to it.</p>
 
 <p>Use this flag on any substitution where the PATH_INFO that resulted
 from the previous mapping of this request to the filesystem is not of
@@ -310,6 +312,18 @@ not be recalculated until the current round of <module>mod_rewrite</module> proc
 completes.  Subsequent rules during this round of processing will see
 only the direct result of substitutions, without any PATH_INFO
 appended.</p>
+
+<highlight language="config">
+# Request: /app/script.php/extra/path (PATH_INFO is /extra/path)
+# Without DPI, the substitution would see "script.php/extra/path"
+# and could inadvertently copy PATH_INFO into the result.
+RewriteRule "^script\.php(.*)$" "/new-app/handler$1" [DPI]
+</highlight>
+
+<p>The [DPI] flag discards <code>/extra/path</code> so that only the
+substitution result (<code>/new-app/handler</code>) is passed to
+subsequent rules or the final request.</p>
+
 </section>
 
 <section id="flag_e"><title>E|env</title>