From 955163389fb98e808f3643de8bf484ca8c3bde8e Mon Sep 17 00:00:00 2001
From: brectanus <brectanus@9017d574-64ec-4062-9424-5e00b32a252b>
Date: Wed, 2 Apr 2008 16:09:09 +0000
Subject: [PATCH] Add docs for macro expansion.  See #462.

---
 doc/modsecurity2-apache-reference.xml | 29 +++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/doc/modsecurity2-apache-reference.xml b/doc/modsecurity2-apache-reference.xml
index 7b6cab37..36b5ef84 100644
--- a/doc/modsecurity2-apache-reference.xml
+++ b/doc/modsecurity2-apache-reference.xml
@@ -4,7 +4,7 @@
   Manual</title>
 
   <articleinfo>
-    <releaseinfo>Version 2.6.0-trunk (March 19, 2008)</releaseinfo>
+    <releaseinfo>Version 2.6.0-trunk (April 02, 2008)</releaseinfo>
 
     <copyright>
       <year>2004-2008</year>
@@ -5574,6 +5574,31 @@ SecRule REQUEST_METHOD "!<emphasis>@within %{tx.allowed_methods}</emphasis>" t:l
     </section>
   </section>
 
+  <section>
+    <title>Macro Expansion</title>
+
+    <para>Macros allow for using place holders in rules that will be expanded
+    out to their values at runtime. Currently only variable expansion is
+    supported, however more options may be added in future versions of
+    ModSecurity.</para>
+
+    <para>Format:</para>
+
+    <programlisting format="linespecific">%{VARIABLE}
+%{COLLECTION.VARIABLE}</programlisting>
+
+    <para>Macro expansion can be used in actions such as initcol, setsid,
+    setuid, setvar, setenv, logdata. Operators that are evaluated at runtime
+    support expansion and are noted above. Such operators include @beginsWith,
+    @endsWith, @contains, @within and @streq. You cannot use macro expansion
+    for operators that are "compiled" such as @pm, @rx, etc. as these
+    operators have their values fixed at configure time for efficiency.</para>
+
+    <para>Some values you may want to expand include: TX, REMOTE_ADDR, USERID,
+    HIGHEST_SEVERITY, MATCHED_VAR, MATCHED_VAR_NAME, MULTIPART_STRICT_ERROR,
+    RULE, SESSION, USERID, among others.</para>
+  </section>
+
   <section>
     <title>Data Formats</title>
 
@@ -6065,4 +6090,4 @@ Server: Apache/2.x.x
       </section>
     </section>
   </section>
-</article>
+</article>
\ No newline at end of file