Moves most of the rewritemap stuff out into its own document where we

can give it the exhaustive treatment it deserves without making the
reference doc unmanageable.


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

1 files changed, 44 insertions, 203 deletions

diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml
index 0723e6a8f7..f0d37c3205 100644
--- a/docs/manual/mod/mod_rewrite.xml
+++ b/docs/manual/mod/mod_rewrite.xml
@@ -255,217 +255,58 @@ Apache HTTP Server 2.0.41 and later</compatibility>
       <p>The following combinations for <em>MapType</em> and
       <em>MapSource</em> can be used:</p>
 
-      <ul>
-        <li>
-          <strong>Standard Plain Text</strong><br />
-           MapType: <code>txt</code>, MapSource: Unix filesystem
-          path to valid regular file
-
-          <p>This is the standard rewriting map feature where the
-          <em>MapSource</em> is a plain ASCII file containing
-          either blank lines, comment lines (starting with a '#'
-          character) or pairs like the following - one per
-          line.</p>
-
-          <p class="indent">
-            <strong><em>MatchingKey</em>
-            <em>SubstValue</em></strong>
-          </p>
-
-<example><title>Example</title>
-<pre>
-##
-##  map.txt -- rewriting map
-##
-
-Ralf.S.Engelschall    rse   # Bastard Operator From Hell
-Mr.Joe.Average        joe   # Mr. Average
-</pre>
-</example>
-
-<example>
-RewriteMap real-to-user txt:/path/to/file/map.txt
-</example>
-        </li>
-
-        <li>
-          <strong>Randomized Plain Text</strong><br />
-           MapType: <code>rnd</code>, MapSource: Unix filesystem
-          path to valid regular file
-
-          <p>This is identical to the Standard Plain Text variant
-          above but with a special post-processing feature: After
-          looking up a value it is parsed according to contained
-          ``<code>|</code>'' characters which have the meaning of
-          ``or''. In other words they indicate a set of
-          alternatives from which the actual returned value is
-          chosen randomly. For example, you might use the following map
-          file and directives to provide a random load balancing between
-          several back-end server, via a reverse-proxy. Images are sent
-          to one of the servers in the 'static' pool, while everything
-          else is sent to one of the 'dynamic' pool.</p>
-          <p>Example:</p>
-
-<example><title>Rewrite map file</title>
-<pre>
-##
-##  map.txt -- rewriting map
-##
-
-static   www1|www2|www3|www4
-dynamic  www5|www6
-</pre>
-</example>
-
-<example><title>Configuration directives</title>
-RewriteMap servers rnd:/path/to/file/map.txt<br />
-<br />
-RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1
-[NC,P,L]<br />
-RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
-</example>
-        </li>
-
-        <li>
-          <strong>Hash File</strong><br /> MapType:
-          <code>dbm[=<em>type</em>]</code>, MapSource: Unix filesystem
-          path to valid regular file
-
-          <p>Here the source is a binary format DBM file containing
-          the same contents as a <em>Plain Text</em> format file, but
-          in a special representation which is optimized for really
-          fast lookups. The <em>type</em> can be sdbm, gdbm, ndbm, or
-          db depending on <a href="../install.html#dbm">compile-time
-          settings</a>.  If the <em>type</em> is omitted, the
-          compile-time default will be chosen.</p>
-
-          <p>To create a dbm file from a source text file, use the <a
-          href="../programs/httxt2dbm.html">httxt2dbm</a> utility.</p>
-
-<example>
-$ httxt2dbm -i mapfile.txt -o mapfile.map
-</example>
-        </li>
-
-        <li>
-          <strong>Internal Function</strong><br />
-           MapType: <code>int</code>, MapSource: Internal Apache httpd
-          function
-
-          <p>Here, the source is an internal Apache httpd function.
-          Currently you cannot create your own, but the following
-          functions already exist:</p>
-
-          <ul>
-            <li><strong>toupper</strong>:<br />
-             Converts the key to all upper case.</li>
+    <table>
+    <tr><th>Map Type</th>
+        <th>Description</th></tr>
 
-            <li><strong>tolower</strong>:<br />
-             Converts the key to all lower case.</li>
+    <tr>
+        <td><code>txt</code></td>
+        <td>A plain text file containing space-separated key-value
+        pairs, one per line.</td>
+        <td><a href="../rewrite/rewritemap.html#txt">Details ...</a></td>
+    </tr>
 
-            <li><strong>escape</strong>:<br />
-             Translates special characters in the key to
-            hex-encodings.</li>
+    <tr>
+        <td><code>rnd</code></td>
+        <td>Randomly selects an entry from a plain text file</td>
+        <td><a href="../rewrite/rewritemap.html#rnd">Details ...</a></td>
+    </tr>
 
-            <li><strong>unescape</strong>:<br />
-             Translates hex-encodings in the key back to
-            special characters.</li>
-          </ul>
-        </li>
+    <tr>
+        <td><code>dbm</code></td>
+        <td>Looks up an entry in a dbm file containing name, value
+        pairs. Hash is constructed from a plain text file format using
+        the <code><a href="../programs/httxt2dbm.html">httxt2dbm</a></code> 
+        utility.</td>
+        <td><a href="../rewrite/rewritemap.html#dbm">Details ...</a></td>
+    </tr>
 
-        <li>
-          <strong>External Rewriting Program</strong><br />
-           MapType: <code>prg</code>, MapSource: Unix filesystem
-          path to valid regular file
-
-          <p>Here the source is a program, not a map file. To
-          create it you can use a language of your choice, but
-          the result has to be an executable program (either
-          object-code or a script with the magic cookie trick
-          '<code>#!/path/to/interpreter</code>' as the first
-          line).</p>
-
-         <p>This program is started once, when the Apache httpd server
-          is started, and then communicates with the rewriting engine
-          via its <code>stdin</code> and <code>stdout</code>
-          file-handles. For each map-function lookup it will
-          receive the key to lookup as a newline-terminated string
-          on <code>stdin</code>. It then has to give back the
-          looked-up value as a newline-terminated string on
-          <code>stdout</code> or the four-character string
-          ``<code>NULL</code>'' if it fails (<em>i.e.</em>, there
-          is no corresponding value for the given key).</p>
-
-          <p>This feature utilizes the <code>rewrite-map</code> mutex,
-          which is required for reliable communication with the program.
-          The mutex mechanism and lock file can be configured with the
-          <directive module="core">Mutex</directive> directive.</p>
-
-          <p>External rewriting programs are not started if they're defined in a
-          context that does not have <directive>RewriteEngine</directive> set to
-          <code>on</code></p>.
-
-          <p>A trivial program which will implement a 1:1 map (<em>i.e.</em>,
-          key == value) could be:</p>
+    <tr>
+        <td><code>int</code></td>
+        <td>One of the four available internal functions provided by
+        <code>RewriteMap</code>: toupper, tolower, escape or
+        unescape.</td>
+        <td><a href="../rewrite/rewritemap.html#int">Details ...</a></td>
+    </tr>
 
-<example>
-<pre>
-#!/usr/bin/perl
-$| = 1;
-while (&lt;STDIN&gt;) {
-    # ...put here any transformations or lookups...
-    print $_;
-}
-</pre>
-</example>
+    <tr>
+        <td><code>prg</code></td>
+        <td>Calls an external program or script to process the
+        rewriting.</td>
+        <td><a href="../rewrite/rewritemap.html#prg">Details ...</a></td>
+    </tr>
 
-          <p>But be very careful:</p>
+    <tr>
+        <td><code>dbd</code> or <code>fastdbd</code></td>
+        <td>A SQL SELECT statement to be performed to look up the
+        rewrite target.</td>
+        <td><a href="../rewrite/rewritemap.html#dbd">Details ...</a></td>
+    </tr>
 
-          <ol>
-            <li>``<em>Keep it simple, stupid</em>'' (KISS).
-            If this program hangs, it will cause Apache httpd to hang
-            when trying to use the relevant rewrite rule.</li>
+    </table>
 
-            <li>A common mistake is to use buffered I/O on
-            <code>stdout</code>. Avoid this, as it will cause a deadloop!
-            ``<code>$|=1</code>'' is used above, to prevent this.</li>
-          </ol>
-        </li>
-        <li>
-          <p><strong>SQL Query</strong><br />
-           MapType: <code>dbd</code> or <code>fastdbd</code>,
-           MapSource: An SQL SELECT statement that takes a single
-                      argument and returns a single value.</p>
-          <p>This uses <module>mod_dbd</module> to implement a rewritemap
-          by lookup in an SQL database.  There are two forms:
-          <code>fastdbd</code> caches database lookups internally,
-          <code>dbd</code> doesn't.  So <code>dbd</code> incurs a
-          performance penalty but responds immediately if the database
-          contents are updated, while <code>fastdbd</code> is more
-          efficient but won't re-read database contents until server
-          restart.</p>
-          <p>If a query returns more than one row, a random row from
-          the result set is used.</p>
-<example>
-<title>Example</title>
-RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
-</example>
-        </li>
-      </ul>
-      <p>The <directive>RewriteMap</directive> directive can occur more than
-      once. For each mapping-function use one
-      <directive>RewriteMap</directive> directive to declare its rewriting
-      mapfile. While you cannot <strong>declare</strong> a map in
-      per-directory context it is of course possible to
-      <strong>use</strong> this map in per-directory context. </p>
-
-<note><title>Note</title> For plain text and DBM format files the
-looked-up keys are cached in-core until the <code>mtime</code> of the
-mapfile changes or the server does a restart. This way you can have
-map-functions in rules which are used for <strong>every</strong>
-request.  This is no problem, because the external lookup only happens
-once!
-</note>
+    <p>Further details, and numerous examples, may be found in the <a
+    href="../rewrite/rewritemap.html">RewriteMap HowTo</a></p>
 
 </usage>
 </directivesynopsis>