Better explanation of example for rnd: type RewriteMap

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

2 files changed, 74 insertions, 44 deletions

diff --git a/docs/manual/rewrite/rewritemap.html.en b/docs/manual/rewrite/rewritemap.html.en
index 1557b3c964..0c85cc4214 100644
--- a/docs/manual/rewrite/rewritemap.html.en
+++ b/docs/manual/rewrite/rewritemap.html.en
@@ -119,7 +119,7 @@ may be used, and give examples of each.</p>
     file.</p>
 
     <p class="indent">
-      # Comment line
+      # Comment line<br />
       <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
       <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
     </p>
@@ -174,20 +174,19 @@ telephone  328
 <div class="section">
 <h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
     
-    <p>MapType: <code>rnd</code>, MapSource: Unix filesystem
-          path to valid regular file</p>
-    <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>
+
+    <p>When a MapType of <code>rnd</code> is used, the MapSource is a
+    filesystem path to a plain-text mapping file, each line of which
+    contains a key, and one or more values separated by <code>|</code>.
+    One of these values will be chosen at random if the key is
+    matched.</p>
+
+    <p>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>
+
     <div class="example"><h3>Rewrite map file</h3><pre>
 ##
 ##  map.txt -- rewriting map
@@ -196,13 +195,29 @@ telephone  328
 static   www1|www2|www3|www4
 dynamic  www5|www6
 </pre></div>
+
     <div class="example"><h3>Configuration directives</h3><p><code>
-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]
-</code></p></div>
+    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]
+    </code></p></div>
+
+    <p>So, when an image is requested and the first of these rules is
+    matched, <code>RewriteMap</code> looks up the string
+    <code>static</code> in the map file, which returns one of the
+    specified hostnames at random, which is then used in the
+    <code>RewriteRule</code> target.</p>
+
+    <p>If you wanted to have one of the servers more likely to be chosen
+    (for example, if one of the server has more memory than the others,
+    and so can handle more requests) simply list it more times in the
+    map file.</p>
+
+    <div class="example"><p><code>
+static   www1|www1|www2|www3|www4
+    </code></p></div>
+
   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="dbm" id="dbm">dbm: DBM Hash File</a></h2>
diff --git a/docs/manual/rewrite/rewritemap.xml b/docs/manual/rewrite/rewritemap.xml
index 4173ab7fb5..74f8dc9545 100644
--- a/docs/manual/rewrite/rewritemap.xml
+++ b/docs/manual/rewrite/rewritemap.xml
@@ -118,7 +118,7 @@ may be used, and give examples of each.</p>
     file.</p>
 
     <p class="indent">
-      # Comment line
+      # Comment line<br />
       <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
       <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
     </p>
@@ -174,22 +174,20 @@ telephone  328
   </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
-          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>
+
+    <p>When a MapType of <code>rnd</code> is used, the MapSource is a
+    filesystem path to a plain-text mapping file, each line of which
+    contains a key, and one or more values separated by <code>|</code>.
+    One of these values will be chosen at random if the key is
+    matched.</p>
+
+    <p>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>
+
+    <example><title>Rewrite map file</title>
       <pre>
 ##
 ##  map.txt -- rewriting map
@@ -199,14 +197,31 @@ 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>
+    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>
+
+    <p>So, when an image is requested and the first of these rules is
+    matched, <code>RewriteMap</code> looks up the string
+    <code>static</code> in the map file, which returns one of the
+    specified hostnames at random, which is then used in the
+    <code>RewriteRule</code> target.</p>
+
+    <p>If you wanted to have one of the servers more likely to be chosen
+    (for example, if one of the server has more memory than the others,
+    and so can handle more requests) simply list it more times in the
+    map file.</p>
+
+    <example>
+static   www1|www1|www2|www3|www4
+    </example>
+
   </section>
+
   <section id="dbm">
     <title>dbm: DBM Hash File</title>
     <p>MapType: