Documentation for the support of named groups and backreferences.

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

diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml
index df059a1741853b59b8eede0b40e72647a05fd00e..6e3c2ff9c8006b213bf1d3d2debdbf170b774f79 100644 (file)
--- a/docs/manual/mod/core.xml
+++ b/docs/manual/mod/core.xml
@@ -885,6 +885,19 @@ the contents of file-system directories matching a regular expression.</descript
       not end in a trailing slash, so expressions that are anchored to the
       end of line ($) must be written with care.
     </note>
+
+    <p>From 2.5.0 onwards, named groups and backreferences are captured and
+    written to the environment with the corresponding name in upper case.
+    This allows elements of paths to be referenced from within
+    <a href="expr.html">expressions</a> and modules like
+    <module>mod_rewrite</module>. In order to prevent confusion, numbered
+    (unnamed) backreferences are ignored. Use named groups instead.</p>
+
+<highlight language="config">
+&lt;DirectoryMatch ^/var/www/combined/(?&lt;SITENAME&gt;[^/]+)&gt;
+    require ldap-group cn=%{env:SITENAME},ou=combined,o=Example
+&lt;/DirectoryMatch&gt;
+</highlight>
 </usage>
 <seealso><directive type="section" module="core">Directory</directive> for
 a description of how regular expressions are mixed in with normal
@@ -1735,6 +1748,19 @@ filenames</description>
 </highlight>
 
     <p>would match most common Internet graphics formats.</p>
+
+    <p>From 2.5.0 onwards, named groups and backreferences are captured and
+    written to the environment with the corresponding name in upper case.
+    This allows elements of files to be referenced from within
+    <a href="expr.html">expressions</a> and modules like
+    <module>mod_rewrite</module>. In order to prevent confusion, numbered
+    (unnamed) backreferences are ignored. Use named groups instead.</p>
+
+<highlight language="config">
+&lt;FileMatch ^(?&lt;SITENAME&gt;[^/]+)&gt;
+    require ldap-group cn=%{env:SITENAME},ou=combined,o=Example
+&lt;/FileMatch&gt;
+</highlight>
 </usage>
 
 <seealso><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;
@@ -2688,6 +2714,19 @@ matching URLs</description>
 
     <p>would match URLs that contained the substring <code>/extra/data</code>
     or <code>/special/data</code>.</p>
+
+    <p>From 2.5.0 onwards, named groups and backreferences are captured and
+    written to the environment with the corresponding name in upper case.
+    This allows elements of URLs to be referenced from within
+    <a href="expr.html">expressions</a> and modules like
+    <module>mod_rewrite</module>. In order to prevent confusion, numbered
+    (unnamed) backreferences are ignored. Use named groups instead.</p>
+
+<highlight language="config">
+&lt;LocationMatch ^/combined/(?&lt;SITENAME&gt;[^/]+)&gt;
+    require ldap-group cn=%{env:SITENAME},ou=combined,o=Example
+&lt;/LocationMatch&gt;
+</highlight>
 </usage>
 
 <seealso><a href="../sections.html">How &lt;Directory&gt;, &lt;Location&gt;

diff --git a/docs/manual/mod/mod_proxy.xml b/docs/manual/mod/mod_proxy.xml
index 95389b0b787cf8687906ae0999e5fc9ac08f53d2..cbec7740052674e25f87fb5f28c2467a7fcd9a5a 100644 (file)
--- a/docs/manual/mod/mod_proxy.xml
+++ b/docs/manual/mod/mod_proxy.xml
@@ -528,6 +528,19 @@ proxied resources</description>
     identical to the <directive module="mod_proxy"
     type="section">Proxy</directive> directive, except it matches URLs
     using <glossary ref="regex">regular expressions</glossary>.</p>
+
+    <p>From 2.5.0 onwards, named groups and backreferences are captured and
+    written to the environment with the corresponding name in upper case.
+    This allows elements of URLs to be referenced from within
+    <a href="expr.html">expressions</a> and modules like
+    <module>mod_rewrite</module>. In order to prevent confusion, numbered
+    (unnamed) backreferences are ignored. Use named groups instead.</p>
+
+<highlight language="config">
+&lt;ProxyMatch ^http://(?&lt;SITENAME&gt;[^/]+)&gt;
+    require ldap-group cn=%{env:SITENAME},ou=combined,o=Example
+&lt;/ProxyMatch&gt;
+</highlight>
 </usage>
 <seealso><directive type="section" module="mod_proxy">Proxy</directive></seealso>
 </directivesynopsis>

diff --git a/docs/manual/sections.xml b/docs/manual/sections.xml
index b3c93b75746e8c3ac753a7bb9150863bd952d78e..76eeb53d32a5900367be3eba3e2acacbe690c146 100644 (file)
--- a/docs/manual/sections.xml
+++ b/docs/manual/sections.xml
@@ -296,6 +296,18 @@ at once:</p>
 &lt;/FilesMatch&gt;
 </highlight>
 
+<p>Regular expressions containing <strong>named groups and
+backreferences</strong> are added to the environment with the
+corresponding name in uppercase. This allows elements of filename paths
+and URLs to be referenced from within <a href="expr.html">expressions</a>
+and modules like <module>mod_rewrite</module>.</p>
+
+<highlight language="config">
+&lt;DirectoryMatch ^/var/www/combined/(?&lt;SITENAME&gt;[^/]+)&gt;
+    require ldap-group cn=%{env:SITENAME},ou=combined,o=Example
+&lt;/DirectoryMatch&gt;
+</highlight>
+
 </section>
 
 <section id="expressions"><title>Boolean expressions</title>