explain some of the mystery quirks of the translate_name example, and introduce

one that does a more basic URI->filename.

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

diff --git a/docs/manual/mod/mod_lua.xml b/docs/manual/mod/mod_lua.xml
index 2488d1289d5e4b06891fbfd7c16562748acf051c..e9de427784dacc59fd4c5fe216bcbd2e2ac11b4d 100644 (file)
--- a/docs/manual/mod/mod_lua.xml
+++ b/docs/manual/mod/mod_lua.xml
@@ -140,7 +140,29 @@ they'll return OK, DONE, or DECLINED, which you can write in lua as
 <code>apache2.DECLINED</code>, or else an HTTP status code.</p>
 
 <example><title>translate_name.lua</title><pre>
--- example hook
+-- example hook that rewrites the URI to a filesystem path.
+
+require 'apache2'
+
+function translate_name(r)
+    if r.uri == "/translate-name" then
+        r.filename = r.document_root .. "/find_me.txt"
+        return apache2.OK
+    end
+    -- we don't care about this URL, give another module a chance
+    return apache2.DECLINED
+end
+</pre></example>
+
+<example><title>translate_name2.lua</title><pre>
+--[[ example hook that rewrites one URI to another URI. It returns a
+     apache2.DECLINED to give other URL mappers a chance to work on the
+     substitution, including the core translate_name hook which maps based
+     on the DocumentRoot.  
+
+     Note: It is currently undefined as to whether this runs before or after
+     mod_alias or any other module implementing the same hook.
+--]]
 
 require 'apache2'