svn commit: r1934203 - in httpd/httpd/trunk/docs/manual: . rewrite

[rb...@apache.org]

Author: rbowen
Date: Thu May 14 20:30:43 2026
New Revision: 1934203

Log:
rewrite guide: document REDIRECT_ prefix for [E=] environment variables

flags.xml: expand the [E] flag section with a note box explaining
that per-directory rewrites rename env vars with a REDIRECT_ prefix
after internal redirect, with an example showing how to reference the
renamed variable and a note about prefix stacking.

env.xml: add cross-reference from the REDIRECT_ variables section
back to rewrite/flags.html#flag_e for mod_rewrite-specific details.

Modified:
   httpd/httpd/trunk/docs/manual/env.xml
   httpd/httpd/trunk/docs/manual/rewrite/TODO.md
   httpd/httpd/trunk/docs/manual/rewrite/flags.xml

Modified: httpd/httpd/trunk/docs/manual/env.xml
==============================================================================
--- httpd/httpd/trunk/docs/manual/env.xml	Thu May 14 20:12:01 2026	(r1934202)
+++ httpd/httpd/trunk/docs/manual/env.xml	Thu May 14 20:30:43 2026	(r1934203)
@@ -537,6 +537,12 @@
     about REDIRECT_ variables in the context of error documents,
     see <a href="custom-error.html">Custom Error Responses</a>.</p>
 
+    <p>This renaming is especially relevant when using
+    <module>mod_rewrite</module>'s
+    <a href="rewrite/flags.html#flag_e">[E] flag</a> to set variables,
+    since per-directory rewrites always trigger an internal redirect.
+    See that section for examples and workarounds.</p>
+
    </section>
 
   <section id="examples">

Modified: httpd/httpd/trunk/docs/manual/rewrite/TODO.md
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/TODO.md	Thu May 14 20:12:01 2026	(r1934202)
+++ httpd/httpd/trunk/docs/manual/rewrite/TODO.md	Thu May 14 20:30:43 2026	(r1934203)
@@ -72,7 +72,7 @@ address. Sorted by priority.
       explanation exists in the guide. Could be a new section in
       intro.xml or tech.xml.
 
-- [ ] **REDIRECT_ prefix for environment variables** — env vars set by
+- [x] **REDIRECT_ prefix for environment variables** — env vars set by
       [E=] are renamed to REDIRECT_FOO after internal redirects. Not
       mentioned in the [E] flag section at all. Add to flags.xml.
 

Modified: httpd/httpd/trunk/docs/manual/rewrite/flags.xml
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/flags.xml	Thu May 14 20:12:01 2026	(r1934202)
+++ httpd/httpd/trunk/docs/manual/rewrite/flags.xml	Thu May 14 20:30:43 2026	(r1934203)
@@ -376,10 +376,34 @@ RewriteCond "%{ENV:rewritten}"  =1
 
 <p>Note that environment variables do not survive an external
 redirect. You might consider using the [CO] flag to set a
-cookie. For per-directory rewrites, where the final
-substitution is processed as an internal redirect, environment
-variables from the previous round of rewriting are prefixed with
-"REDIRECT_". </p>
+cookie.</p>
+
+    <note><title>REDIRECT_ prefix after internal redirects</title>
+    <p>In <glossary ref="perdirectory">per-directory context</glossary>,
+    a successful substitution triggers an internal redirect. When this
+    happens, all environment variables set during the previous pass —
+    including those created with <code>[E=VAR:VAL]</code> — are renamed
+    with a <code>REDIRECT_</code> prefix. A variable you set as
+    <code>rewritten</code> becomes <code>REDIRECT_rewritten</code> in
+    the redirected request.</p>
+
+    <p>To test for the renamed variable, reference it with the
+    prefix:</p>
+    </note>
+
+<highlight language="config">
+RewriteRule   "^/horses/(.*)" "/ponies/$1" [E=rewritten:1]
+
+# In the next pass, the variable has been renamed:
+RewriteCond "%{ENV:REDIRECT_rewritten}" =1
+RewriteRule "^/ponies/(.*)" "-" [E=seen_redirect:1,L]
+</highlight>
+
+    <p>If the request is redirected multiple times, the prefix stacks:
+    <code>REDIRECT_REDIRECT_rewritten</code>, and so on. See
+    <a href="../env.html#redirect-vars">REDIRECT_ variables</a> for
+    the complete description of this mechanism.</p>
+
 </section>
 
 <section id="flag_end"><title>END</title>