From 0a4236052cc3fb8bb1a2b9eee7e5373733e9e628 Mon Sep 17 00:00:00 2001
From: Luca Toscano <elukey@apache.org>
Date: Tue, 16 Feb 2016 12:32:08 +0000
Subject: [PATCH] Expanding sections.xml to address Bug: 58789

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1730673 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/sections.xml | 42 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 38 insertions(+), 4 deletions(-)

diff --git a/docs/manual/sections.xml b/docs/manual/sections.xml
index f8aa84183bf..e77961c18f5 100644
--- a/docs/manual/sections.xml
+++ b/docs/manual/sections.xml
@@ -405,13 +405,13 @@ see the <a href="vhosts/">Virtual Host Documentation</a>.</p>
 and <directive type="section" module="mod_proxy">ProxyMatch</directive>
 containers apply enclosed configuration directives only
 to sites accessed through <module>mod_proxy</module>'s proxy server
-that match the specified URL.  For example, the following configuration
-will prevent the proxy server from being used to access the
-<code>www.example.com</code> website.</p>
+that match the specified URL. For example, the following configuration
+will allow only a subset of clients to access the
+<code>www.example.com</code> website using the proxy server:</p>
 
 <highlight language="config">
 &lt;Proxy http://www.example.com/*&gt;
-    Require all granted
+    Require host yournetwork.example.com
 &lt;/Proxy&gt;
 </highlight>
 </section>
@@ -510,12 +510,17 @@ are interpreted, it is important to understand how this works.</p>
     type="section">Directory</directive> container in the processing
     order.</p>
 
+<note><title>Merge is not always Override</title>
     <p>Later sections override earlier ones, however each module is responsible
     for interpreting what form this override takes.  A later configuration section
     with directives from a given module might cause a conceptual "merge" of some
     directives, all directives, or a complete replacement of the modules
     configuration with the module defaults and directives explicitly listed in
     the later context.</p>
+    <p><directive>Directory</directive>, <directive>FilesMatch</directive>, 
+    <directive>Location</directive> and the other directives discussed in this section 
+    implement the same merging strategy, namely "override" when applied to the same target.</p>
+</note>
 
 <note><title>Technical Note</title>
       There is actually a
@@ -559,6 +564,35 @@ E.</p>
 
 </highlight>
 
+<p>Another interesting example is the following one. As described above, 
+<directive>FilesMatch</directive> is merged after <directive>Directory</directive>, 
+therefore a request for <code>/var/www/index.html</code> will eventually get the "foo" Header set to
+the value "two", not "three" as somebody might expect from a first look.
+</p>
+
+<highlight language="config">
+&lt;Directory "/"&gt;
+    Header set foo one
+    &lt;FilesMatch ".*"&gt;
+        Header set foo two
+    &lt;/FilesMatch&gt;
+&lt;/Directory&gt;
+
+&lt;Directory "/var/www"&gt;
+    Header set foo three
+&lt;/Directory&gt;
+ 
+</highlight>
+
+<p>The chain of values that the "foo" header will get is: "one", "three" and "two". 
+It is important to notice that <directive>Directory</directive> and <directive>FilesMatch</directive> 
+implement the same merging strategy, namely "override" when 
+applied to the same path. In this example it means that the last directive applied in the merging order,
+<directive>FilesMatch</directive>, sets the final value for the "foo" header. 
+</p>
+<p>This is true for .htaccess too, since they have the same priority as <directive>Directory</directive>
+in the merging order.</p>
+
 <p>For a more concrete example, consider the following.  Regardless of
 any access restrictions placed in <directive module="core"
 type="section">Directory</directive> sections, the <directive
-- 
2.47.3