This is the second in a series of clean-ups of the

environment variable docs.  Here is what I have done:

1. Removed some obsolete CERN references and done a tiny
bit of cleanup of mod_env.html.

2. Included references from mod_env.html and mod_setenvif.html
to env.html.

3. Prettied-up env.html a little bit by including sub-headings.

4. Added some "caveats" to env.html:
- No overriding basic CGI variables
- suexec restrictions
- no non-alphanumeric characters in env variable names


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

1 files changed, 67 insertions, 23 deletions

diff --git a/docs/manual/env.html b/docs/manual/env.html
index b32847fbbf..f436e32819 100644
--- a/docs/manual/env.html
+++ b/docs/manual/env.html
@@ -54,23 +54,60 @@ explains some of the ways to use environment variables in Apache.</p>
 <A HREF="mod/mod_env.html#unsetenv">UnsetEnv</A><br>
 </td></tr></table>
 
+<h3>Basic Environment Manipulation</h3>
+
 <p>The most basic way to set an environment variable in Apache is
 using the unconditional <code>SetEnv</code> directive.  Variables
-may also be passed from the environment when Apache is started
-using the <code>PassEnv</code> directive.</p>
+may also be passed from the environment of the shell which started
+the server using the <code>PassEnv</code> directive.</p>
+
+<h3>Conditional Per-Request Settings</h3>
+
+<p>For additional flexibility, the directives provided by mod_setenvif
+allow environment variables to be set on a per-request basis,
+conditional on characteristics of particular requests.  For example, a
+variable could be set only when a specific browser (User-Agent) is
+making a request, or only when a specific Referer [sic] header is
+found.  Even more flexibility is available through the mod_rewrite's
+<code>RewriteRule</code> which uses the <code>[E=...]</code> option to
+set environment variables.</p>
 
-<p>The directives provided by mod_setenvif allow environment variables
-to be set on a per-request basis based on characteristics of particular
-requests.  For example, a variable could be set only when a specific
-browser (User-Agent) is making a request, or only when a specific
-Referer header is found.  Even more flexibility is available through the
-mod_rewrite's <code>RewriteRule</code> which uses the
-<code>[E=...]</code> option to set environment variables.</p>
+<h3>Unique Identifiers</h3>
 
 <p>Finally, mod_unique_id sets the environment variable
 <code>UNIQUE_ID</code> for each request to a value which is guaranteed
 to be unique across "all" requests under very specific conditions.</p>
 
+<h3>Standard CGI Variables</h3>
+
+<p>In addition to all environment variables set within the Apache
+configuration and passed from the shell, CGI scripts and SSI pages are
+provided with a set of environment variables containing
+meta-information about the request as required by the <a
+href="misc/FAQ.html#cgi-spec">CGI specification</a>.</p>
+
+<h3>Some Caveats</h3>
+
+<ul>
+
+<li>It is not possible to override or change the standard CGI
+variables using the environment manipulation directives.</li> 
+
+<li>When <a href="suexec.html">suexec</a> is used to launch CGI
+scripts, the environment will be cleaned down to a set of
+<em>safe</em> variables before CGI scripts are launched.  The list of
+<em>safe</em> variables is defined at compile-time in
+<code>suexec.c</code>.</li>
+
+<li>For portability reasons, the names of environment variables
+may contain only letters, numbers, and the underscore character.
+In addition, the first character may not be a number.  Characters
+which do not match this restriction will be replaced by an
+underscore when passed to CGI scripts and SSI pages.</li>
+
+</ul>
+
+
 <hr>
 
 <h2><a name="using">Using Environment Variables</a></h2>
@@ -87,34 +124,37 @@ to be unique across "all" requests under very specific conditions.</p>
 </td><td valign="top">
 <strong>Related Directives</strong><br><br>
 
-<A HREF="mod/mod_access.html#allowfromenv">Allow from env=</A><br>
-<a href="mod/mod_log_config.html#customlog-conditional">CustomLog
-(conditional)</a><br>
-<A HREF="mod/mod_access.html#denyfromenv">Deny from env=</A><br>
+<A HREF="mod/mod_access.html#allow">Allow</A><br>
+<a href="mod/mod_log_config.html#customlog">CustomLog</a><br>
+<A HREF="mod/mod_access.html#deny">Deny</A><br>
 <a href="mod/mod_log_config.html#logformat">LogFormat</a><br>
 <A HREF="mod/mod_rewrite.html#RewriteCond">RewriteCond</A><br>
 <A HREF="mod/mod_rewrite.html#RewriteRule">RewriteRule</A><br>
 
 </td></tr></table>
 
+<h3>CGI Scripts</h3>
+
 <p>One of the primary uses of environment variables is to communicate
-information to CGI scripts.  In addition to all environment variables
-set within Apache, CGI scripts are provided with a set of
-meta-information about the request as provided for in the <a
-href="misc/FAQ.html#cgi-spec">CGI specification</a>.  If you are using
-<a href="suexec.html">Suexec</a> to execute CGI scripts under
-different userids, note that the environment will be cleaned down to a
-set of <em>safe</em> environment variables before the CGI script is
-executed.  The set of safe environment variables is defined at
-compile time in <code>suexec.c</code>.
+information to CGI scripts.  As discussed above, the environment
+passed to CGI scripts includes standard meta-information about the request
+in addition to any variables set within the Apache configuration.
+For more details, see the <a href="howto/cgi.html">CGI tutorial</a>.
 </p>
 
+<h3>SSI Pages</h3>
+
 <p>Server-parsed (SSI) documents processed by mod_include's
 <code>server-parsed</code> handler can print environment variables
 using the <code>echo</code> element, and can use environment variables
-in flow control elements.
+in flow control elements to makes parts of a page conditional on
+characteristics of a request.  Apache also provides SSI pages with the
+standard CGI environment variables as discussed above.  For more
+details, see the <a href="howto/ssi.html">SSI tutorial</a>.
 </p>
 
+<h3>Access Control</h3>
+
 <p>Access to the server can be controlled based on the value of
 environment variables using the <code>allow from env=</code> and
 <code>deny from env=</code></a> directives.  In combination with
@@ -124,6 +164,8 @@ can use these directives to deny access to a particular browser
 (User-Agent).
 </p>
 
+<h3>Conditional Logging</h3>
+
 <p>Environment variables can be logged in the access log using the
 <code>LogFormat</code> option <code>%e</code>.  In addition, the
 decision on whether or not to log requests can be made based on the
@@ -135,6 +177,8 @@ for filenames ending in <code>gif</code>, or you can choose to only
 log requests from clients which are outside your subnet.
 </p>
 
+<h3>URL Rewriting</h3>
+
 <p>The <code>%{ENV:...}</code> form of <em>TestString</em> in the
 <code>RewriteCond</code> allows mod_rewrite's rewrite engine to make
 decisions conditional on environment variables.  Note that the