backport r1308327 from trunk -- clarify RewriteBase example/info

<name>RewriteBase</name>

<description>Sets the base URL for per-directory rewrites</description>

<syntax>RewriteBase <em>URL-path</em></syntax>

<default>See usage for information.</default>

<default>None</default>

<contextlist><context>directory</context><context>.htaccess</context>

</contextlist>

<override>FileInfo</override>

<usage>

      <p>The <directive>RewriteBase</directive> directive explicitly

      sets the base URL for per-directory rewrites. As you will see

      below, <directive module="mod_rewrite">RewriteRule</directive>

      can be used in per-directory config files

      (<code>.htaccess</code>). In such a case, it will act locally,

      stripping the local directory prefix before processing, and applying

      rewrite rules only to the remainder. When processing is complete, the 

      prefix is automatically added back to the

      path. The default setting is; <directive>RewriteBase</directive> <em>physical-directory-path</em></p>

      <p>When a substitution occurs for a new URL, this module has

      to re-inject the URL into the server processing. To be able

      to do this it needs to know what the corresponding URL-prefix

      or URL-base is. By default this prefix is the corresponding

      filepath itself. <strong>However, for most websites, URLs are NOT

      directly related to physical filename paths, so this

      assumption will often be wrong!</strong> Therefore, you can 

      use the <code>RewriteBase</code> directive to specify the

      correct URL-prefix.</p>

<note> If your webserver's URLs are <strong>not</strong> directly

related to physical file paths, you will need to use

<directive>RewriteBase</directive> in every <code>.htaccess</code>

file where you want to use <directive

module="mod_rewrite">RewriteRule</directive> directives.

</note>

        <p> For example, assume the following per-directory config file:</p>

      <p>The <directive>RewriteBase</directive> directive specifies the

      URL prefix to be used for per-directory (htaccess) 

      <directive>RewriteRule</directive> directives that substitute a relative

      path.</p>

      <p> This directive is <em>required</em> when you use a relative path

      in a substitution in per-directory (htaccess) context unless either

      of the following conditions are true:

      <ul>

          <li> The original request, and the substitution, are underneath the 

               <directive module="core">DocumentRoot</directive>

               (as opposed to reachable by other means, such as 

               <directive module="mod_alias">Alias</directive>).</li>

          <li> The <em>filesystem</em> path to the directory containing the

               <directive>RewriteRule</directive>, suffixed by the relative 

               substitution is also valid as a URL path on the server 

               (this is rare).</li>

      </ul>

      </p>

<p> In the example below, <directive>RewriteBase</directive> is necessary

    to avoid rewriting to http://example.com/opt/myapp-1.2.3/welcome.html

    since the resource was not relative to the document root.  This 

    misconfiguration would normally cause the server to look for an "opt"

    directory under the document root.</p>

<example>

<pre>

#

#  /abc/def/.htaccess -- per-dir config file for directory /abc/def

#  Remember: /abc/def is the physical path of /xyz, <em>i.e.</em>, the server

#            has a 'Alias /xyz /abc/def' directive <em>e.g.</em>

#

DocumentRoot /var/www/example.com

Alias /myapp /opt/myapp-1.2.3

<Directory /opt/myapp-1.2.3>

RewriteEngine On

#  let the server know that we were reached via /xyz and not

#  via the physical path prefix /abc/def

RewriteBase   /xyz

#  now the rewriting rules

RewriteRule   ^oldstuff\.html$  newstuff.html

RewriteBase /myapp/

RewriteRule ^index\.html$  welcome.html 

</Directory>

</pre>

</example>

        <p>In the above example, a request to

        <code>/xyz/oldstuff.html</code> gets correctly rewritten to

        the physical file <code>/abc/def/newstuff.html</code>.</p>

<note><title>For Apache Hackers</title>

<p>The following list gives detailed information about

              the internal processing steps:</p>

<pre>

Request:

  /xyz/oldstuff.html

Internal Processing:

  /xyz/oldstuff.html     -> /abc/def/oldstuff.html  (per-server Alias)

  /abc/def/oldstuff.html -> /abc/def/newstuff.html  (per-dir    RewriteRule)

  /abc/def/newstuff.html -> /xyz/newstuff.html      (per-dir    RewriteBase)

  /xyz/newstuff.html     -> /abc/def/newstuff.html  (per-server Alias)

Result:

  /abc/def/newstuff.html

</pre>

              <p>This seems very complicated, but is in fact

              correct Apache internal processing. Because the

              per-directory rewriting comes late in the

              process, the rewritten request

              has to be re-injected into the Apache kernel, as if it

              were a new request. (See <a

              href="../rewrite/tech.html">mod_rewrite technical

              details</a>.)

              This is not the serious overhead it may seem to be - 

              this re-injection is completely internal to the 

	      Apache server (and the same procedure is used by 

	      many other operations within Apache).</p> 

</note>

</usage>

</directivesynopsis>

<directivesynopsis>