Add note about when to use <location>. This dupes what is already discussed

in sections.html, but it is important enough to repeat.

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

diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml
index 7fed697609317877ac68b758f95a5fc7ba9cf231..0b6de27d8fc27b47a0f38195304ee02e40b4c200 100644 (file)
--- a/docs/manual/mod/core.xml
+++ b/docs/manual/mod/core.xml
@@ -1667,17 +1667,31 @@ URLs</description>
     limits the scope of the enclosed directives by URL. It is similar to the
     <directive type="section" module="core">Directory</directive>
     directive, and starts a subsection which is terminated with a
-    <code>&lt;/Location&gt;</code> directive. <directive
+    <code>&lt;/Location&gt;</code> directive.  <directive
     type="section">Location</directive> sections are processed in the
     order they appear in the configuration file, after the <directive
     type="section" module="core">Directory</directive> sections and
     <code>.htaccess</code> files are read, and after the <directive
     type="section" module="core">Files</directive> sections.</p>
 
-    <p>Note that URLs do not have to line up with the filesystem at
-    all, it should be emphasized that <directive
-    type="section">Location</directive> operates completely
-    outside the filesystem.</p>
+    <p><directive type="section">Location</directive> sections operate
+    completely outside the filesystem.  This has several consequences.
+    Most importantly, <directive type="section">Location</directive>
+    directives should not be used to control access to filesystem
+    locations.  Since several different URLs may map to the same
+    filesystem location, such access controls may by circumvented.</p>
+
+    <note><title>When to use <directive 
+    type="section">Location</directive></title>
+
+    <p>Use <directive type="section">Location</directive> to apply
+    directives to content that lives outside the filesystem.  For
+    content that lives in the filesystem, use <directive
+    type="section" module="core">Directory</directive> and <directive
+    type="section" module="core">Files</directive>.  An exception is
+    <code>&lt;Location /&gt;</code>, which is an easy way to 
+    apply a configuration to the entire server.</p>
+    </note>
 
     <p>For all origin (non-proxy) requests, the URL to be matched is a
     URL-path of the form <code>/path/</code>.  No scheme, hostname,