httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rbo...@apache.org
Subject svn commit: r945931 - /httpd/httpd/trunk/docs/manual/rewrite/rewritemap.xml
Date Tue, 18 May 2010 22:25:03 GMT
Author: rbowen
Date: Tue May 18 22:25:03 2010
New Revision: 945931

URL: http://svn.apache.org/viewvc?rev=945931&view=rev
Log:
xmllint

Modified:
    httpd/httpd/trunk/docs/manual/rewrite/rewritemap.xml

Modified: httpd/httpd/trunk/docs/manual/rewrite/rewritemap.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/rewrite/rewritemap.xml?rev=945931&r1=945930&r2=945931&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/rewrite/rewritemap.xml (original)
+++ httpd/httpd/trunk/docs/manual/rewrite/rewritemap.xml Tue May 18 22:25:03 2010
@@ -1,8 +1,7 @@
-<?xml version="1.0" encoding="UTF-8" ?>
+<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
 <!-- $LastChangedRevision: 882992 $ -->
-
 <!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
@@ -19,98 +18,108 @@
  See the License for the specific language governing permissions and
  limitations under the License.
 -->
-
 <manualpage metafile="rewritemap.xml.meta">
   <parentdocument href="./">Rewrite</parentdocument>
-
-<title>Using RewriteMap</title>
-
-<summary>
-
-<p>This document supplements the <module>mod_rewrite</module> 
+  <title>Using RewriteMap</title>
+  <summary>
+    <p>This document supplements the <module>mod_rewrite</module> 
 <a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
 the use of the <directive module="mod_rewrite">RewriteMap</directive> directive,
 and provides examples of each of the various <code>RewriteMap</code> types.</p>
-
-<note type="warning">Note that many of these examples won't work unchanged in your
+    <note type="warning">Note that many of these examples won't work unchanged in your
 particular server configuration, so it's important that you understand
 them, rather than merely cutting and pasting the examples into your
 configuration.</note>
-
-</summary>
-<seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
-<seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
-<seealso><a href="remapping.html">Redirection and remapping</a></seealso>
-<seealso><a href="access.html">Controlling access</a></seealso>
-<seealso><a href="vhosts.html">Virtual hosts</a></seealso>
-<seealso><a href="proxy.html">Proxying</a></seealso>
-<seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso>
-<seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
-
-<section id="introduction"><title>Introduction</title>
-
-      <p>The <directive>RewriteMap</directive> directive defines a
+  </summary>
+  <seealso>
+    <a href="../mod/mod_rewrite.html">Module documentation</a>
+  </seealso>
+  <seealso>
+    <a href="intro.html">mod_rewrite introduction</a>
+  </seealso>
+  <seealso>
+    <a href="remapping.html">Redirection and remapping</a>
+  </seealso>
+  <seealso>
+    <a href="access.html">Controlling access</a>
+  </seealso>
+  <seealso>
+    <a href="vhosts.html">Virtual hosts</a>
+  </seealso>
+  <seealso>
+    <a href="proxy.html">Proxying</a>
+  </seealso>
+  <seealso>
+    <a href="advanced.html">Advanced techniques and tricks</a>
+  </seealso>
+  <seealso>
+    <a href="avoid.html">When not to use mod_rewrite</a>
+  </seealso>
+  <section id="introduction">
+    <title>Introduction</title>
+    <p>The <directive>RewriteMap</directive> directive defines a
       <em>Rewriting Map</em> which can be used inside rule
       substitution strings by the mapping-functions to
       insert/substitute fields through a key lookup. The source of
       this lookup can be of various types.</p>
-
-      <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a>
is
+    <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a>
is
       the name of the map and will be used to specify a
       mapping-function for the substitution strings of a rewriting
       rule via one of the following constructs:</p>
-
-      <p class="indent">
-        <strong><code>${</code> <em>MapName</em> <code>:</code>
-        <em>LookupKey</em> <code>}</code><br />
-         <code>${</code> <em>MapName</em> <code>:</code>
-        <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
-        <code>}</code></strong>
-      </p>
-
-      <p>When such a construct occurs, the map <em>MapName</em> is
+    <p class="indent">
+      <strong>
+        <code>${</code>
+        <em>MapName</em>
+        <code>:</code>
+        <em>LookupKey</em>
+        <code>}</code>
+        <br/>
+        <code>${</code>
+        <em>MapName</em>
+        <code>:</code>
+        <em>LookupKey</em>
+        <code>|</code>
+        <em>DefaultValue</em>
+        <code>}</code>
+      </strong>
+    </p>
+    <p>When such a construct occurs, the map <em>MapName</em> is
       consulted and the key <em>LookupKey</em> is looked-up. If the
       key is found, the map-function construct is substituted by
       <em>SubstValue</em>. If the key is not found then it is
       substituted by <em>DefaultValue</em> or by the empty string
       if no <em>DefaultValue</em> was specified.</p>
-
-      <p>For example, you might define a
+    <p>For example, you might define a
       <directive>RewriteMap</directive> as:</p>
-
-      <example>
+    <example>
       RewriteMap examplemap txt:/path/to/file/map.txt
       </example>
-
-      <p>You would then be able to use this map in a
+    <p>You would then be able to use this map in a
       <directive>RewriteRule</directive> as follows:</p>
-
-      <example>
+    <example>
       RewriteRule ^/ex/(.*) ${examplemap:$1}
       </example>
-
-      <p>The following combinations for <em>MapType</em> and
+    <p>The following combinations for <em>MapType</em> and
       <em>MapSource</em> can be used:</p>
   </section>
-
-    <section id="txt"><title>txt: Plain text maps</title>
-
-   <p>MapType: <code>txt</code>, MapSource: Unix filesystem
+  <section id="txt">
+    <title>txt: Plain text maps</title>
+    <p>MapType: <code>txt</code>, MapSource: Unix filesystem
       path to valid regular file</p>
-
-      <p>This is the standard rewriting map feature where the
+    <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>
+    <p class="indent">
+      <strong>
+        <em>MatchingKey</em>
+        <em>SubstValue</em>
+      </strong>
+    </p>
+    <example>
+      <title>Example</title>
+      <pre>
 ##
 ##  map.txt -- rewriting map
 ##
@@ -118,20 +127,16 @@ configuration.</note>
 Ralf.S.Engelschall    rse   # Bastard Operator From Hell
 Mr.Joe.Average        joe   # Mr. Average
 </pre>
-</example>
-
-<example>
+    </example>
+    <example>
 RewriteMap real-to-user txt:/path/to/file/map.txt
 </example>
-
-</section>
-
-<section id="rnd"><title>Randomized Plain Text</title>
-
-           <p>MapType: <code>rnd</code>, MapSource: Unix filesystem
+  </section>
+  <section id="rnd">
+    <title>rnd: Randomized Plain Text</title>
+    <p>MapType: <code>rnd</code>, MapSource: Unix filesystem
           path to valid regular file</p>
-
-          <p>This is identical to the Standard Plain Text variant
+    <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
@@ -142,10 +147,10 @@ RewriteMap real-to-user txt:/path/to/fil
           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>
+    <p>Example:</p>
+    <example>
+      <title>Rewrite map file</title>
+      <pre>
 ##
 ##  map.txt -- rewriting map
 ##
@@ -153,80 +158,62 @@ RewriteMap real-to-user txt:/path/to/fil
 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 />
+    </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 />
+[NC,P,L]<br/>
 RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
 </example>
-
-</section>
-
-<section id="dbm"><title>DBM Hash File</title>
-
-<p>MapType:
+  </section>
+  <section id="dbm">
+    <title>dbm: DBM Hash File</title>
+    <p>MapType:
           <code>dbm[=<em>type</em>]</code>, MapSource: Unix filesystem
           path to valid regular file</p>
-
-          <p>Here the source is a binary format DBM file containing
+    <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>
+    <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>
-</section>
-
-          <section id="int"><title>Internal Function</title>
-          <p>
+  </section>
+  <section id="int">
+    <title>int: Internal Function</title>
+    <p>
            MapType: <code>int</code>, MapSource: Internal Apache httpd
           function</p>
-
-          <p>Here, the source is an 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 />
+    <ul>
+      <li><strong>toupper</strong>:<br/>
              Converts the key to all upper case.</li>
-
-            <li><strong>tolower</strong>:<br />
+      <li><strong>tolower</strong>:<br/>
              Converts the key to all lower case.</li>
-
-            <li><strong>escape</strong>:<br />
+      <li><strong>escape</strong>:<br/>
              Translates special characters in the key to
             hex-encodings.</li>
-
-            <li><strong>unescape</strong>:<br />
+      <li><strong>unescape</strong>:<br/>
              Translates hex-encodings in the key back to
             special characters.</li>
-          </ul>
-</section>
-
-<section id="prg"><title>External Rewriting Program</title>
-<p>
+    </ul>
+  </section>
+  <section id="prg"><title>prg: External Rewriting Program</title><p>
            MapType: <code>prg</code>, MapSource: Unix filesystem
           path to valid regular file
-          </p>
-
-          <p>Here the source is a program, not a map file. To
+          </p><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
+          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
@@ -235,82 +222,59 @@ $ httxt2dbm -i mapfile.txt -o mapfile.ma
           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,
+          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
+          <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>
-
-<example>
-<pre>
+          key == value) could be:</p><example><pre>
 #!/usr/bin/perl
 $| = 1;
 while (&lt;STDIN&gt;) {
     # ...put here any transformations or lookups...
     print $_;
 }
-</pre>
-</example>
-
-          <p>But be very careful:</p>
-
-          <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>
-
-            <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>
-          </section>
-
-          <section id="dbd"><title>SQL Query</title>
-           <p>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>
+</pre></example><p>But be very careful:</p><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><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></section>
+  <section id="dbd">
+    <title>dbd or fastdbd: SQL Query</title>
+    <p>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>
-</section>
-
-<section id="summary"><title>Summary</title>
-
-      <p>The <directive>RewriteMap</directive> directive can occur more
than
+  </section>
+  <section id="summary">
+    <title>Summary</title>
+    <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
+    <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>
-
-</section>
-
-</manualpage> 
+  </section>
+</manualpage>



Mime
View raw message