Help doc writer to spot places where:

[apache] / docs / manual / configuring.xml

diff --git a/docs/manual/configuring.xml b/docs/manual/configuring.xml
index 0c4c322a6d8cb417e02d6b4c5987aadff3e61062..672491b2a8198e1bfe4726808306b99f18ddef88 100644 (file)
--- a/docs/manual/configuring.xml
+++ b/docs/manual/configuring.xml
@@ -1,14 +1,15 @@
 <?xml version='1.0' encoding='UTF-8' ?>
 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
 <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
 <?xml version='1.0' encoding='UTF-8' ?>
 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
 <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>

-<!-- $Revision: 1.10 $ -->
+<!-- $LastChangedRevision$ -->

 
 <!--
 
 <!--

- Copyright 2002-2004 The Apache Software Foundation
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at

 
      http://www.apache.org/licenses/LICENSE-2.0
 
 
      http://www.apache.org/licenses/LICENSE-2.0
 


@@ -24,8 +25,8 @@
   <title>Configuration Files</title>
 
 <summary>
   <title>Configuration Files</title>
 
 <summary>

-<p>This document describes the files used to configure the Apache
-HTTP server.</p>
+<p>This document describes the files used to configure Apache HTTP
+Server.</p>

 </summary>
 
   <section id="main">
 </summary>
 
   <section id="main">


@@ -41,7 +42,7 @@ HTTP server.</p>
       </directivelist>
     </related>
 
       </directivelist>
     </related>
 

-    <p>Apache is configured by placing <a
+    <p>Apache HTTP Server is configured by placing <a

     href="mod/directives.html">directives</a> in plain text
     configuration files. The main configuration file is usually called
     <code>httpd.conf</code>. The location of this file is set at
     href="mod/directives.html">directives</a> in plain text
     configuration files. The main configuration file is usually called
     <code>httpd.conf</code>. The location of this file is set at


@@ -50,8 +51,8 @@ HTTP server.</p>
     added using the <directive module="core">Include</directive>
     directive, and wildcards can be used to include many configuration
     files. Any directive may be placed in any of these configuration
     added using the <directive module="core">Include</directive>
     directive, and wildcards can be used to include many configuration
     files. Any directive may be placed in any of these configuration

-    files.  Changes to the main configuration files are only
-    recognized by Apache when it is started or restarted.</p>
+    files. Changes to the main configuration files are only
+    recognized by httpd when it is started or restarted.</p>

 
     <p>The server also reads a file containing mime document types;
     the filename is set by the <directive
 
     <p>The server also reads a file containing mime document types;
     the filename is set by the <directive


@@ -62,24 +63,59 @@ HTTP server.</p>
   <section id="syntax">
     <title>Syntax of the Configuration Files</title>
 
   <section id="syntax">
     <title>Syntax of the Configuration Files</title>
 

-    <p>Apache configuration files contain one directive per line.
-    The back-slash "\" may be used as the last character on a line
+    <p>httpd configuration files contain one directive per line.
+    The backslash "\" may be used as the last character on a line

     to indicate that the directive continues onto the next line.
     There must be no other characters or white space between the
     to indicate that the directive continues onto the next line.
     There must be no other characters or white space between the

-    back-slash and the end of the line.</p>
+    backslash and the end of the line.</p>
+
+    <p>Arguments to directives are separated by whitespace. If an
+    argument contains spaces, you must enclose that argument in quotes.</p>

 
     <p>Directives in the configuration files are case-insensitive,
     but arguments to directives are often case sensitive. Lines
     that begin with the hash character "#" are considered
     comments, and are ignored. Comments may <strong>not</strong> be
 
     <p>Directives in the configuration files are case-insensitive,
     but arguments to directives are often case sensitive. Lines
     that begin with the hash character "#" are considered
     comments, and are ignored. Comments may <strong>not</strong> be

-    included on a line after a configuration directive. Blank lines
-    and white space occurring before a directive are ignored, so
-    you may indent directives for clarity.</p>
+    included on the same line as a configuration directive.
+    White space occurring before a directive is ignored, so
+    you may indent directives for clarity. Blank lines are also ignored.</p>
+
+    <p>The values of variables defined with the <directive
+    module="core">Define</directive> of or shell environment variables can
+    be used in configuration file lines using the syntax <code>${VAR}</code>.
+    If "VAR" is the name of a valid variable, the value of that variable is
+    substituted into that spot in the configuration file line, and processing
+    continues as if that text were found directly in the configuration file.
+    Variables defined with <directive module="core">Define</directive> take
+    precedence over shell environment variables.
+    If the "VAR" variable is not found, the characters <code>${VAR}</code>
+    are left unchanged, and a warning is logged.
+    Variable names may not contain colon ":" characters, to avoid clashes with
+    <directive module="mod_rewrite">RewriteMap</directive>'s syntax.</p>
+
+    <p>Only shell environment variables defined before the server is started
+    can be used in expansions. Environment variables defined in the
+    configuration file itself, for example with <directive
+    module="mod_env">SetEnv</directive>, take effect too late to be used for
+    expansions in the configuration file.</p>
+
+    <p>The maximum length of a line in normal configuration files, after
+    variable substitution and joining any continued lines, is approximately
+    16 MiB. In <a href="configuring.html#htaccess">.htaccess files</a>, the
+    maximum length is 8190 characters.</p>

 
     <p>You can check your configuration files for syntax errors
     without starting the server by using <code>apachectl
     configtest</code> or the <code>-t</code> command line
     option.</p>
 
     <p>You can check your configuration files for syntax errors
     without starting the server by using <code>apachectl
     configtest</code> or the <code>-t</code> command line
     option.</p>

+
+    <p>You can use <module>mod_info</module>'s <code>-DDUMP_CONFIG</code> to
+    dump the configuration with all included files and environment
+    variables resolved and all comments and non-matching
+    <directive module="core" type="section">IfDefine</directive> and
+    <directive module="core" type="section">IfModule</directive> sections
+    removed. However, the output does not reflect the merging or overriding
+    that may happen for repeated directives.</p>

   </section>
 
   <section id="modules">
   </section>
 
   <section id="modules">


@@ -95,24 +131,29 @@ HTTP server.</p>
       </directivelist>
     </related>
 
       </directivelist>
     </related>
 

-    <p>Apache is a modular server. This implies that only the most
+    <p>httpd is a modular server. This implies that only the most

     basic functionality is included in the core server. Extended
     features are available through <a
     href="mod/">modules</a> which can be loaded
     basic functionality is included in the core server. Extended
     features are available through <a
     href="mod/">modules</a> which can be loaded

-    into Apache. By default, a <a
+    into httpd. By default, a <a

     href="mod/module-dict.html#Status">base</a> set of modules is
     included in the server at compile-time. If the server is
     compiled to use <a href="dso.html">dynamically loaded</a>
     modules, then modules can be compiled separately and added at
     any time using the <directive module="mod_so">LoadModule</directive>
     directive.
     href="mod/module-dict.html#Status">base</a> set of modules is
     included in the server at compile-time. If the server is
     compiled to use <a href="dso.html">dynamically loaded</a>
     modules, then modules can be compiled separately and added at
     any time using the <directive module="mod_so">LoadModule</directive>
     directive.

-    Otherwise, Apache must be recompiled to add or remove modules.
+    Otherwise, httpd must be recompiled to add or remove modules.

     Configuration directives may be included conditional on a
     Configuration directives may be included conditional on a

-    presence of a particular module by enclosing them in an<directive
-    module="core" type="section">IfModule</directive> block.</p>
+    presence of a particular module by enclosing them in an <directive
+    module="core" type="section">IfModule</directive> block. However,
+    <directive type="section">IfModule</directive> blocks are not
+    required, and in some cases may mask the fact that you're missing an
+    important module.</p>

 
     <p>To see which modules are currently compiled into the server,
 
     <p>To see which modules are currently compiled into the server,

-    you can use the <code>-l</code> command line option.</p>
+    you can use the <code>-l</code> command line option. You can also
+    see what modules are loaded dynamically using the <code>-M</code>
+    command line option.</p>

   </section>
 
   <section id="scope">
   </section>
 
   <section id="scope">


@@ -145,7 +186,7 @@ HTTP server.</p>
     locations or URLs. They can also be nested, allowing for very
     fine grained configuration.</p>
 
     locations or URLs. They can also be nested, allowing for very
     fine grained configuration.</p>
 

-    <p>Apache has the capability to serve many different websites
+    <p>httpd has the capability to serve many different websites

     simultaneously. This is called <a href="vhosts/">Virtual
     Hosting</a>. Directives can also be scoped by placing them
     inside <directive module="core" type="section">VirtualHost</directive>
     simultaneously. This is called <a href="vhosts/">Virtual
     Hosting</a>. Directives can also be scoped by placing them
     inside <directive module="core" type="section">VirtualHost</directive>


@@ -173,7 +214,7 @@ HTTP server.</p>
       </directivelist>
     </related>
 
       </directivelist>
     </related>
 

-    <p>Apache allows for decentralized management of configuration
+    <p>httpd allows for decentralized management of configuration

     via special files placed inside the web tree. The special files
     are usually called <code>.htaccess</code>, but any name can be
     specified in the <directive module="core">AccessFileName</directive>
     via special files placed inside the web tree. The special files
     are usually called <code>.htaccess</code>, but any name can be
     specified in the <directive module="core">AccessFileName</directive>