From 44f6c966b014bf4e76ba11c44ddbfc07048f4949 Mon Sep 17 00:00:00 2001
From: Eric Covener <covener@apache.org>
Date: Sat, 17 Sep 2016 20:39:20 +0000
Subject: [PATCH] expand third common in the expression functions doc

Explain some risks at looking at per-request environment variables
set by other modules within <If>.

http://stackoverflow.com/questions/39462011/htaccess-if-else-always-selects-else




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

diff --git a/docs/manual/expr.xml b/docs/manual/expr.xml
index 10b4fd72ea..cc63aba521 100644
--- a/docs/manual/expr.xml
+++ b/docs/manual/expr.xml
@@ -488,7 +488,7 @@ listfunction ::= listfuncname "<strong>(</strong>" word "<strong>)</strong>"
     <table border="1" style="zebra">
     <columnspec><column width=".2"/><column width=".4"/><column width=".4"/></columnspec>
 
-    <tr><th>Name</th><th>Description</th><th>Restricted</th></tr>
+    <tr><th>Name</th><th>Description</th><th>Special notes</th></tr>
     <tr><td><code>req</code>, <code>http</code></td>
         <td>Get HTTP request header; header names may be added to the Vary
             header, see below</td><td></td></tr>
@@ -500,15 +500,16 @@ listfunction ::= listfuncname "<strong>(</strong>" word "<strong>)</strong>"
             during <directive>&lt;If&gt;</directive>)</td><td></td></tr>
     <tr><td><code>reqenv</code></td>
         <td>Lookup request environment variable (as a shortcut,
-        <code>v</code> can be used too to access
-        variables)</td><td></td></tr>
+        <code>v</code> can also be used to access variables). 
+        </td>
+        <td>ordering</td></tr>
     <tr><td><code>osenv</code></td>
         <td>Lookup operating system environment variable</td><td></td></tr>
     <tr><td><code>note</code></td>
-        <td>Lookup request note</td><td></td></tr>
+        <td>Lookup request note</td><td>ordering</td></tr>
     <tr><td><code>env</code></td>
         <td>Return first match of <code>note</code>, <code>reqenv</code>,
-            <code>osenv</code></td><td></td></tr>
+            <code>osenv</code></td><td>ordering</td></tr>
     <tr><td><code>tolower</code></td>
         <td>Convert string to lower case</td><td></td></tr>
     <tr><td><code>toupper</code></td>
@@ -531,13 +532,13 @@ listfunction ::= listfuncname "<strong>(</strong>" word "<strong>)</strong>"
             encoding</td><td></td></tr>
     <tr><td><code>file</code></td>
         <td>Read contents from a file (including line endings, when present)
-        </td><td>yes</td></tr>
+        </td><td>restricted</td></tr>
     <tr><td><code>filemod</code></td>
         <td>Return last modification time of a file (or 0 if file does not exist
-            or is not regular file)</td><td>yes</td></tr>
+            or is not regular file)</td><td>restricted</td></tr>
     <tr><td><code>filesize</code></td>
         <td>Return size of a file (or 0 if file does not exist or is not
-            regular file)</td><td>yes</td></tr>
+            regular file)</td><td>restricted</td></tr>
     <tr><td><code>ldap</code></td>
         <td>Escape characters as required by LDAP distinguished name escaping
             (RFC4514) and LDAP filter escaping (RFC4515).</td><td></td></tr>
@@ -547,8 +548,29 @@ listfunction ::= listfuncname "<strong>(</strong>" word "<strong>)</strong>"
 
     </table>
 
-    <p>The functions marked as "restricted" are not available in some modules
-    like <module>mod_include</module>.</p>
+    <p>The functions marked as "restricted" in the final column are not 
+    available in some modules like <module>mod_include</module>.</p>
+
+    <p>The functions marked as "ordering" in the final column require some
+    consideration for the ordering of different components of the server,
+    especially when the function is used within the 
+    &lt;<directive module="core">If</directive>&gt; directive which is
+    evaluated relatively early.</p>
+    <note>
+    <title>Environment variable ordering</title>
+    When environment variables are looked up within an 
+    &lt;<directive module="core">If</directive>&gt; condition, it's important 
+    to consider how extremely early in request processing that this 
+    resolution occurs. As a guideline, any directive defined outside of virtual host 
+    context (directory, location, htaccess) is not likely to have yet had a 
+    chance to execute. <directive module="mod_setenvif">SetEnvIf</directive>
+    in virtual host scope is one directive that runs prior to this resolution
+    <br/>
+    <br/>
+    When <code>reqenv</code> is used outside of &lt;<directive module="core"
+    >If</directive>&gt;, the resolution will generally occur later, but the 
+    exact timing depends on the directive the expression has been used within.
+    </note>
 
     <p>When the functions <code>req</code> or <code>http</code> are used,
     the header name will automatically be added to the Vary header of the
-- 
2.50.1