From: Rich Bowen Date: Sun, 22 Sep 2013 20:12:54 +0000 (+0000) Subject: Rebuild mod_macro docs X-Git-Tag: 2.5.0-alpha~5032 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=9e1074c931892b2345f4093068346450ced05d02;p=apache Rebuild mod_macro docs git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1525428 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_macro.html.en b/docs/manual/mod/mod_macro.html.en index cb74996f95..5fa9cb8cf2 100644 --- a/docs/manual/mod/mod_macro.html.en +++ b/docs/manual/mod/mod_macro.html.en @@ -34,10 +34,12 @@

Summary

-

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.

+

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.

+

Directives

Topics

top
-

Features

- -

Definition of a macro:

- - - -

Use of a macro:

- - - -

Removal of a macro definition:

+

Usage

- +

Macros are defined using <Macro> 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.

+ +

For example, you might use a macro to define a <VirtualHost> block, in order to define +multiple similar virtual hosts:

-<Macro DirGroup $dir $group>
-  <Directory $dir>
-    require group $group
-  </Directory>
+<Macro VHost $name $domain>
+<VirtualHost *:80>
+    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
+>/VirtualHost>
 </Macro>
+
-Use DirGroup /www/apache/private private -Use DirGroup /www/apache/server admin -UndefMacro DirGroup +

Macro names are case-insensitive, like httpd configuration +directives. However, variable names are case sensitive.

+ +

You would then invoke this macro several times to create virtual +hosts:

+ +
+Use VHost example example.com
+Use VHost myhost hostname.org
+Use VHost apache apache.org
+
+UndefMacro VHost
+
+ + +

At server startup time, each of these Use +invocations would be expanded into a full virtualhost, as +described by the Macro definition.

+ +

The UndefMacro directive is used so that later +macros using the same variable names don't result in conflicting +definitions.

+ +

A more elaborate version of this example may be seen below in the +Examples section.

+ +
top
+
+

Technical details

+ +

Parameter names should begin with a sigil such as $, +%, or @, so that they are clearly +identifiable, and also in order to help deail with interactions with +other directives, such as the core Define 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.

+ +

Parameters prefixed with either $ or % are +not escaped. Parameters prefixes with @ are escaped in +quotes.

+ +

Avoid using a parameter which contains another parameter as a prefix, +(For example, $win and $winter) as this may +cause confusion at expression evaluation time. In the event of such +confusion, the longest possible parameter name is used.

+ +

If you want to use a value within another string, it is useful to +surround the parameter in braces, to avoid confusion:

+ +
+<Macro DocRoot ${docroot}>
+    DocumentRoot /var/www/${docroot}/htdocs
+</Macro>
@@ -125,6 +139,10 @@ UndefMacro DirGroup

Examples

+ +

Virtual Host Definition

+ +

A common usage of mod_macro is for the creation of dynamically-generated virtual hosts.

@@ -138,8 +156,9 @@ dynamically-generated virtual hosts.

ServerName $host DocumentRoot $dir + # Public document root <Directory $dir> - # do something here... + Require all granted </Directory> # limit access to intranet subdir. @@ -156,6 +175,30 @@ Use VHost example.org 8080 /vhosts/example/htdocs Use VHost www.example.fr 1234 /vhosts/example.fr/htdocs + + +

Removal of a macro definition

+ + +
    +
  • the macro must be already defined.
    • +
+ +
+<Macro DirGroup $dir $group>
+  <Directory $dir>
+    Require group $group
+  </Directory>
+</Macro>
+
+Use DirGroup /www/apache/private private
+Use DirGroup /www/apache/server  admin
+
+UndefMacro DirGroup
+
+ + +
top
diff --git a/docs/manual/mod/mod_macro.xml.fr b/docs/manual/mod/mod_macro.xml.fr index 9c4a22e51d..7617768f10 100644 --- a/docs/manual/mod/mod_macro.xml.fr +++ b/docs/manual/mod/mod_macro.xml.fr @@ -1,7 +1,7 @@ - +