AI-Assisted survey of the last 20 years of users@ identified a number of

questions that we *could* answer in this Rewrite Guide, but are not yet
doing so. This is more recipe-based, Q&A stuff, and none of it is
terribly high priority, but gives an opportunity to give high-quality
answers to common questions and combat some misinformation.

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

diff --git a/docs/manual/rewrite/TODO.md b/docs/manual/rewrite/TODO.md
index 0439af1a8f502d96449917cd93e7806c50428b49..d897d585bf711abc3fcb59884201dce3391e1d37 100644 (file)
--- a/docs/manual/rewrite/TODO.md
+++ b/docs/manual/rewrite/TODO.md
@@ -45,3 +45,64 @@ result in one file "owning" the content and others cross-referencing it.
 
 - [ ] **Figure numbering collision** — both intro.xml and tech.xml use
       "Figure 1" for different images.
+
+---
+
+## Potential Topics to Cover
+
+Based on 20 years of users@httpd.apache.org questions, these are the
+most common mod_rewrite pain points that the guide does not adequately
+address. Sorted by priority.
+
+### HIGH — Widely asked, not covered
+
+- [ ] **Redirect vs. RewriteRule processing order** — mod_rewrite runs
+      *before* mod_alias regardless of config file order. Mixing them
+      in the same context confuses users every year. Belongs in avoid.xml
+      or tech.xml.
+
+- [ ] **%{HTTPS} behind a load balancer / SSL terminator** — %{HTTPS}
+      queries mod_ssl directly; it is not an environment variable.
+      Behind a reverse proxy, check %{HTTP:X-Forwarded-Proto} instead.
+      Add to the HTTPS redirect recipe in remapping.xml.
+
+- [ ] **URL encoding pipeline** — Apache decodes percent-encoded chars
+      before pattern matching. %{THE_REQUEST} preserves the raw form.
+      AllowEncodedSlashes, [B]/[NE]/[BNP] flags. No coherent
+      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
+      [E=] are renamed to REDIRECT_FOO after internal redirects. Not
+      mentioned in the [E] flag section at all. Add to flags.xml.
+
+- [ ] **RewriteRule inside `<If>` or `<Location>` switches to
+      per-directory context** — counter-intuitive behavior even when
+      the block is inside a VirtualHost. Add a warning to htaccess.xml
+      or tech.xml.
+
+- [ ] **Query string is NOT part of the RewriteRule pattern** — users
+      put `?query` or full URLs in their patterns. Make this explicit
+      in intro.xml's RewriteRule basics section.
+
+### MEDIUM — Common, easy to add
+
+- [ ] **Let's Encrypt ACME challenge exemption** — one-liner recipe,
+      universally needed alongside HTTPS redirect. Add to remapping.xml.
+
+- [ ] **301 caching by browsers** — users fix their config but still
+      see the old broken redirect. Mention in htaccess.xml or intro.xml.
+
+- [ ] **[R=4xx] sends a redirect header, not a status response** — add
+      a warning to the [R] flag section in flags.xml.
+
+- [ ] **"Don't start .htaccess patterns with /"** — implicit in the
+      current path-stripping section but never called out as a warning
+      box. Add to htaccess.xml.
+
+### LOW — Niche but prevents support questions
+
+- [ ] **prg: RewriteMap must flush stdout** — add note to rewritemap.xml.
+
+- [ ] **mod_rewrite cannot inspect POST body** — one-sentence note in
+      intro.xml.