--- /dev/null
+# Rewrite Docs — Redundancy Cleanup TODO
+
+Working list of cross-file redundancies to resolve. Each item should
+result in one file "owning" the content and others cross-referencing it.
+
+## HIGH Priority
+
+- [ ] **Per-directory path stripping** explained in full across three files
+ (intro.xml, tech.xml, htaccess.xml) with near-identical comparison
+ tables in tech.xml and htaccess.xml.
+ → htaccess.xml owns it; others get a brief mention + xref.
+
+- [ ] **[L] vs [END] looping** fully described in three places
+ (htaccess.xml, plus both the [L] and [END] sections of flags.xml).
+ → htaccess.xml owns the full explanation; flags.xml slims down + xrefs.
+
+- [ ] **FallbackResource / front-controller** recipe appears in four
+ places across three files (avoid.xml, remapping.xml ×2, htaccess.xml).
+ → avoid.xml owns it; others cross-reference.
+
+## MEDIUM Priority
+
+- [x] **index.xml is a mini-intro, not a TOC** — duplicates module
+ description and complexity warnings from intro.xml.
+ → Rewritten as concise intro + structured guide overview.
+
+- [ ] **Duplicate SSRF warning in flags.xml** — two nearly identical
+ warning boxes within the [P] flag section.
+ → Remove the literal duplicate.
+
+- [ ] **Two hostname canonicalization sections in remapping.xml** —
+ "canonicalhost" and "www-resolve" cover the same concept.
+ → Merge "www-resolve" into "canonicalhost".
+
+- [ ] **HTTPS redirect** covered in both avoid.xml and remapping.xml.
+ → remapping.xml owns the recipe; avoid.xml references it.
+
+## LOW Priority
+
+- [ ] **Harmonize `<seealso>` blocks** — htaccess.xml not consistently
+ listed in other files' seealso despite being a major topic.
+
+- [ ] **Deprecated stub files** (access.xml, advanced.xml, proxy.xml) —
+ consider removal or ensure they don't appear in navigation.
+
+- [ ] **Figure numbering collision** — both intro.xml and tech.xml use
+ "Figure 1" for different images.
expression</a> rules. This allows you to map arbitrary URLs onto
your internal URL structure in any way you like.</p>
- <p>It supports an unlimited number of rules and an
- unlimited number of attached rule conditions for each rule to
- provide a really flexible and powerful URL manipulation
- mechanism. The URL manipulations can depend on various tests:
- server variables, environment variables, HTTP
- headers, time stamps, external database lookups, and various other
- external programs or handlers, can be used to achieve granular URL
- matching.</p>
-
- <p>Rewrite rules can operate on the full URLs, including the path-info
- and query string portions, and may be used in per-server context
- (<code>httpd.conf</code>), per-virtualhost context (<directive
- type="section" module="core">VirtualHost</directive> blocks), or
- <glossary ref="perdirectory">per-directory context</glossary>
- (<code>.htaccess</code> files and <directive
- type="section" module="core">Directory</directive> blocks). The
- rewritten result can lead to further rules, internal
- sub-processing, external request redirection, or proxy
- passthrough, depending on what <a href="flags.html">flags</a> you
- attach to the rules.</p>
-
- <p>Since <module>mod_rewrite</module> is so powerful, it can indeed be rather
- complex. This guide supplements the <a
- href="../mod/mod_rewrite.html">reference documentation</a>, and
- attempts to allay some of that complexity, and provide highly
- annotated examples of common scenarios that you may handle with
- <module>mod_rewrite</module>. But we also attempt to show you when you should not
- use <module>mod_rewrite</module>, and use other standard Apache features instead,
- thus avoiding this unnecessary complexity.</p>
-
-
-<ul>
-<li><a href="../mod/mod_rewrite.html">mod_rewrite reference
-documentation</a></li>
-<li><a href="intro.html">Introduction to regular expressions and mod_rewrite</a></li>
-<li><a href="htaccess.html">mod_rewrite in .htaccess files</a></li>
-<li><a href="flags.html">RewriteRule Flags</a></li>
-<li><a href="rewritemap.html">Using RewriteMap</a></li>
-<li><a href="avoid.html">When <strong>NOT</strong> to use mod_rewrite</a></li>
-<li><a href="remapping.html">Using mod_rewrite for redirection and remapping of URLs</a></li>
-<li><a href="vhosts.html">Dynamic virtual hosts with mod_rewrite</a></li>
-<li><a href="tech.html">Technical details</a></li>
-</ul>
+ <p>This guide supplements <a href="../mod/mod_rewrite.html">the
+ reference manual</a> with annotated examples, conceptual
+ explanations, and practical advice. It is organized as follows:</p>
+
+<dl>
+<dt><a href="intro.html">Introduction</a></dt>
+<dd>Core concepts: regular expression syntax, RewriteRule and
+RewriteCond basics, and how mod_rewrite fits into the request
+processing lifecycle.</dd>
+
+<dt><a href="htaccess.html">Per-directory Rewrites (.htaccess)</a></dt>
+<dd>The key differences between using rewrite rules in server
+configuration versus <code>.htaccess</code> files, including path
+stripping, RewriteBase, and the looping behavior of the [L] flag.</dd>
+
+<dt><a href="flags.html">RewriteRule Flags</a></dt>
+<dd>A complete reference for all flags that can modify the behavior of
+a RewriteRule, with examples for each.</dd>
+
+<dt><a href="rewritemap.html">Using RewriteMap</a></dt>
+<dd>How to use external lookup sources — text files, DBM databases,
+SQL queries, and internal functions — to drive your rewrite
+rules.</dd>
+
+<dt><a href="remapping.html">Redirection and Remapping</a></dt>
+<dd>Recipes for common tasks: HTTPS redirection, canonical hostnames,
+trailing slash normalization, front-controller routing, and more.</dd>
+
+<dt><a href="vhosts.html">Dynamic Virtual Hosts</a></dt>
+<dd>Using mod_rewrite to dynamically map hostnames to document roots
+without individual VirtualHost blocks.</dd>
+
+<dt><a href="avoid.html">When NOT to use mod_rewrite</a></dt>
+<dd>Many common tasks are better accomplished with simpler directives.
+This document shows the alternatives and when to prefer them.</dd>
+
+<dt><a href="tech.html">Technical Details</a></dt>
+<dd>How mod_rewrite hooks into the Apache request processing phases,
+and the order in which rules and conditions are evaluated.</dd>
+</dl>
</summary>
-<seealso><a href="../mod/mod_rewrite.html">mod_rewrite reference
-documentation</a></seealso>
+<seealso><a href="../mod/mod_rewrite.html">The Reference Manual</a></seealso>
<seealso><a href="../urlmapping.html">Mapping URLs to the Filesystem</a></seealso>
<seealso><a href="https://cwiki.apache.org/confluence/display/httpd/Rewrite">mod_rewrite
wiki</a></seealso>
projects / thirdparty / apache / httpd.git / commitdiff
