From 785365904d7e4bd8c122f4ca9c9f52b5768c92e9 Mon Sep 17 00:00:00 2001
From: Graham Leggett <minfrin@apache.org>
Date: Mon, 30 Dec 2013 19:52:42 +0000
Subject: [PATCH] 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
---
 docs/manual/mod/core.xml      | 39 +++++++++++++++++++++++++++++++++++
 docs/manual/mod/mod_proxy.xml | 13 ++++++++++++
 docs/manual/sections.xml      | 12 +++++++++++
 3 files changed, 64 insertions(+)

diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml
index df059a1741..6e3c2ff9c8 100644
--- 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 95389b0b78..cbec774005 100644
--- 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 b3c93b7574..76eeb53d32 100644
--- 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>
-- 
2.40.0