Restructure the mod_macro doc a little, with a 'usage', 'details', and

'examples' section. More examples to come.


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

1 files changed, 110 insertions, 67 deletions

diff --git a/docs/manual/mod/mod_macro.xml b/docs/manual/mod/mod_macro.xml
index 11e0b4d5c0..337870c057 100644
--- a/docs/manual/mod/mod_macro.xml
+++ b/docs/manual/mod/mod_macro.xml
@@ -30,83 +30,101 @@
 
 <summary>
 
-    <p>This module provides macros within apache httpd runtime configuration files.
-    These macros may have parameters. They are expanded when used (parameters are
-    substituted by their values given as an argument), and the result is
-    processed normally.</p>
+    <p>Provides macros within Apache httpd runtime configuration files,
+    to ease the process of creating numerous similar configuration
+    blocks. When the server starts up, the macros are expanded using the
+    provided parameters, and the result is processed as along with the
+    rest of the configuration file.</p>
+
 </summary>
 
-<section id="features"><title>Features</title>
-
-<p>Definition of a macro:</p>
-
-    <ul>
-    <li> macro definition within a <directive type="section">Macro</directive> section, following
-         the httpd configuration style.</li>
-    <li> user defined names for the macro and its parameters.</li>
-    <li> macro names are case-insensitive, like httpd directives.</li>
-    <li> macro parameter names are case sensitive.</li>
-    <li> macro parameters must have distinct names.</li>
-    <li> error on empty parameter names.</li>
-    <li> redefining a macro generates a warning.</li>
-    <li> macro definitions can be nested... (but what for?)</li>
-    <li> warn about unused macro parameters.</li>
-    <li> warn about macro parameter names which prefix one another.</li>
-    <li> warn if a parameter is not prefixed by any of '<code>$%@</code>'
-         (good practice).</li>
-    <li> the available prefixes help deal with interactions with other
-         directives such as <directive module="core">Define</directive>.</li>
-    <li> tip: it may be useful to define a macro parameter with surrounding
-         braces, say <code>${foo}</code> so that the name can appear with
-	 surrounding characters such as <code>bla${foo}bla</code>.</li>
-    <li> warn about empty macro contents.</li>
-    <li> warns if sections are not properly nested within a macro.
-         (if it is detected so).</li>
-    <li> the lexical scope of macro parameters is restricted to the macro text,
-         it is not forwarded to includes for instance.</li>
-    <li> arbitrary contents in macros.
-         <p>It means you can put perl sections or whatever you like in a macro.
-	 No assumption is made about the lexical structure (quotes, spaces or
-         whatever) within the macro contents but to expect a set of
-         backslash-continued independent lines.</p></li>
-    </ul>
-
-<p>Use of a macro:</p>
-
-    <ul>
-    <li> number of arguments must match the definition.</li>
-    <li> all occurences of macro parameters are substituted by their values.</li>
-    <li> in case of conflicts, the longest parameter name is chosen.</li>
-    <li> macro expansion recursion is detected and stopped (error).</li>
-    <li> warn about empty arguments when used.</li>
-    <li> on errors, try to describe precisely where the error occured.</li>
-    <li> <code>$</code> and <code>%</code>-prefixed parameters are not
-          escaped.</li>
-    <li> <code>@</code>-prefixed parameters are escaped in quotes.</li>
-    </ul>
-
-<p>Removal of a macro definition:</p>
+<section id="usage"><title>Usage</title>
 
-   <ul>
-   <li> the macro must be already defined.</li>
-   </ul>
+<p>Macros are defined using <directive
+type="section">Macro</directive> blocks, which contain the portion of
+your configuration that needs to be repeated, complete with variables
+for those parts that will need to be substituted.</p>
+
+<p>For example,  you might use a macro to define a <directive
+type="section">VirtualHost</directive> block, in order to define
+multiple similar virtual hosts:</p>
 
 <highlight language="config">
-&lt;Macro DirGroup $dir $group&gt;
-  &lt;Directory $dir&gt;
-    require group $group
-  &lt;/Directory&gt;
+&lt;Macro VHost $name $domain&gt;
+&lt;VirtualHost *:80&gt;
+    ServerName $domain
+    ServerAlias www.$domain
+
+    DocumentRoot /var/www/vhosts/$name
+    ErrorLog /var/log/httpd/$name.error_log
+    CustomLog /var/log/httpd/name.access_log combined
+&gt;/VirtualHost&gt;
 &lt;/Macro&gt;
+</highlight>
 
-Use DirGroup /www/apache/private private
-Use DirGroup /www/apache/server  admin
+<p>Macro names are case-insensitive, like httpd configuration
+directives. However, variable names are case sensitive.</p>
 
-UndefMacro DirGroup
+<p>You would then invoke this macro several times to create virtual
+hosts:</p>
+
+<highlight language="config">
+Use VHost example example.com
+Use VHost myhost hostname.org
+Use VHost apache apache.org
+
+UndefMacro VHost
+</highlight>
+
+<p>At server startup time, each of these <directive>Use</directive>
+invocations would be expanded into a full virtualhost, as
+described by the <directive>Macro</directive> definition.</p>
+
+<p>The <directive>UndefMacro</directive> directive is used so that later
+macros using the same variable names don't result in conflicting
+definitions.</p>
+
+<p>A more elaborate version of this example may be seen below in the
+Examples section.</p>
+
+</section>
+
+<section id="details"><title>Technical details</title>
+
+<p>Parameter names should begin with a sigil such as <code>$</code>,
+<code>%</code>, or <code>@</code>, so that they are clearly
+identifiable, and also in order to help deail with interactions with
+other directives, such as the core <directive
+module="core">Define</directive> directive. Failure to do so will 
+result in a warning. Nevertheless, you are encouraged to have a good
+knowledge of your entire server configuration in order to avoid reusing
+the same variables in different scopes, which can cause confusion.</p>
+
+<p>Parameters prefixed with either <code>$</code> or <code>%</code> are
+not escaped. Parameters prefixes with <code>@</code> are escaped in
+quotes.</p>
+
+<p>Avoid using a parameter which contains another parameter as a prefix,
+(For example, <code>$win</code> and <code>$winter</code>) as this may
+cause confusion at expression evaluation time. In the event of such
+confusion, the longest possible parameter name is used.</p>
+
+<p>If you want to use a value within another string, it is useful to
+surround the parameter in braces, to avoid confusion:</p>
+
+<highlight language="config">
+&lt;Macro DocRoot ${docroot}&gt;
+    DocumentRoot /var/www/${docroot}/htdocs
+&lt;/Macro&gt;
 </highlight>
 
 </section>
 
-<section id="examples"><title>Examples</title>
+<section id="examples">
+<title>Examples</title>
+
+<section>
+<title>Virtual Host Definition</title>
 
 <p>A common usage of <module>mod_macro</module> is for the creation of
 dynamically-generated virtual hosts.</p>
@@ -121,8 +139,9 @@ dynamically-generated virtual hosts.</p>
     ServerName $host
     DocumentRoot $dir
 
+    # Public document root
     &lt;Directory $dir&gt;
-      # do something here...
+        Require all granted
     &lt;/Directory&gt;
 
     # limit access to intranet subdir.
@@ -138,8 +157,31 @@ Use VHost www.apache.org 80 /vhosts/apache/htdocs
 Use VHost example.org 8080 /vhosts/example/htdocs
 Use VHost www.example.fr 1234 /vhosts/example.fr/htdocs
 </highlight>
+</section> <!-- Vhosts -->
 
-</section>
+<section>
+<title>Removal of a macro definition</title>
+
+   <ul>
+   <li> the macro must be already defined.</li>
+   </ul>
+
+<highlight language="config">
+&lt;Macro DirGroup $dir $group&gt;
+  &lt;Directory $dir&gt;
+    Require group $group
+  &lt;/Directory&gt;
+&lt;/Macro&gt;
+
+Use DirGroup /www/apache/private private
+Use DirGroup /www/apache/server  admin
+
+UndefMacro DirGroup
+</highlight>
+
+</section> <!-- UndefMacro -->
+
+</section> <!-- Example -->
 
 <!-- Macro -->
 <directivesynopsis type="section">
@@ -233,4 +275,5 @@ UndefMacro RestrictedAccessPolicy
     </highlight>
 </usage>
 </directivesynopsis>
+
 </modulesynopsis>