From d9f39319c8a587d37e3b9c93e787c06cd6177db1 Mon Sep 17 00:00:00 2001
From: Rich Bowen <rbowen@apache.org>
Date: Wed, 19 May 2010 01:07:27 +0000
Subject: [PATCH] More information for the dbm map type.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@945987 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/rewrite/rewritemap.html.en | 52 +++++++++++++++++++------
 docs/manual/rewrite/rewritemap.xml     | 53 ++++++++++++++++++++------
 2 files changed, 81 insertions(+), 24 deletions(-)

diff --git a/docs/manual/rewrite/rewritemap.html.en b/docs/manual/rewrite/rewritemap.html.en
index 0c85cc4214..608100db6e 100644
--- a/docs/manual/rewrite/rewritemap.html.en
+++ b/docs/manual/rewrite/rewritemap.html.en
@@ -222,20 +222,48 @@ static   www1|www1|www2|www3|www4
 <div class="section">
 <h2><a name="dbm" id="dbm">dbm: DBM Hash File</a></h2>
     
-    <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
-          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>
-    <div class="example"><p><code>
+
+    <p>When a MapType of <code>dbm</code> is used, the MapSource is a
+    filesystem path to a DBM database file containing key/value pairs to
+    be used in the mapping. This works exactly the same way as the
+    <code>txt</code> map, but is much faster, because a DBM is indexed,
+    whereas a text file is not. This allows more rapid access to the
+    desired key.</p>
+
+    <p>You may optionally specify a particular dbm type:</p>
+
+ <div class="example"><p><code>
+ RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
+ </code></p></div>
+
+    <p>The type can be sdbm, gdbm, ndbm or db.
+    However, it is recommended that you just use the <a href="../programs/httxt2dbm.html">httxt2dbm</a> utility that is
+    provided with Apache HTTP Server, as it will use the correct DBM library,
+    matching the one that was used when httpd itself was built.</p>
+
+    <p>To create a dbm file, first create a text map file as described
+    in the <a href="#txt">txt</a> section. Then run
+    <code>httxt2dbm</code>:</p>
+
+<div class="example"><p><code>
 $ httxt2dbm -i mapfile.txt -o mapfile.map
 </code></p></div>
+
+<p>You can then reference the resulting file in your
+<code>RewriteMap</code> directive:</p>
+
+<div class="example"><p><code>
+RewriteMap mapname dbm:/etc/apache/mapfile.map
+</code></p></div>
+
+<div class="note">
+<p>Note that with some dbm types, more than one file is generated, with
+a common base name. For example, you may have two files named
+<code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
+normal, and you need only use the base name <code>mapfile.map</code> in
+your <code>RewriteMap</code> directive.</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="int" id="int">int: Internal Function</a></h2>
diff --git a/docs/manual/rewrite/rewritemap.xml b/docs/manual/rewrite/rewritemap.xml
index 74f8dc9545..d2fe1d3c7e 100644
--- a/docs/manual/rewrite/rewritemap.xml
+++ b/docs/manual/rewrite/rewritemap.xml
@@ -224,20 +224,49 @@ static   www1|www1|www2|www3|www4
 
   <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
-          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>When a MapType of <code>dbm</code> is used, the MapSource is a
+    filesystem path to a DBM database file containing key/value pairs to
+    be used in the mapping. This works exactly the same way as the
+    <code>txt</code> map, but is much faster, because a DBM is indexed,
+    whereas a text file is not. This allows more rapid access to the
+    desired key.</p>
+
+    <p>You may optionally specify a particular dbm type:</p>
+
+ <example>
+ RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
+ </example>
+
+    <p>The type can be sdbm, gdbm, ndbm or db.
+    However, it is recommended that you just use the <a
+    href="../programs/httxt2dbm.html">httxt2dbm</a> utility that is
+    provided with Apache HTTP Server, as it will use the correct DBM library,
+    matching the one that was used when httpd itself was built.</p>
+
+    <p>To create a dbm file, first create a text map file as described
+    in the <a href="#txt">txt</a> section. Then run
+    <code>httxt2dbm</code>:</p>
+
+<example>
 $ httxt2dbm -i mapfile.txt -o mapfile.map
 </example>
+
+<p>You can then reference the resulting file in your
+<code>RewriteMap</code> directive:</p>
+
+<example>
+RewriteMap mapname dbm:/etc/apache/mapfile.map
+</example>
+
+<note>
+<p>Note that with some dbm types, more than one file is generated, with
+a common base name. For example, you may have two files named
+<code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
+normal, and you need only use the base name <code>mapfile.map</code> in
+your <code>RewriteMap</code> directive.</p>
+</note>
+
   </section>
   <section id="int">
     <title>int: Internal Function</title>
-- 
2.40.0