mod_macro.xml.fr revision d5e8240ee767cced65a45a2b9d590ca08b3d3859
<?xml version="1.0"?>
<!-- English Revision: 1524240:1525431 (outdated) -->
<!-- French translation: Fabien Coelho -->
<!-- Updated by Lucien Gentis -->
<!--
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
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<modulesynopsis metafile="mod_macro.xml.meta">
<name>mod_macro</name>
<description>Ce module permet d'utiliser des macros dans les fichiers
de configuration Apache.</description>
<status>Base</status>
<identifier>macro_module</identifier>
<summary>
<p>Ce module permet de définir et d'utiliser des macros dans les fichiers
de configuration Apache. Ces macros peuvent avoir des paramètres qui sont
expansés à l'utilisation (les paramètres sont remplacés par la valeur
passée en argument), et le résultat de la substitution est traité
normalement.</p>
</summary>
<section id="features"><title>Caractéristiques</title>
<p>Définition d'une macro :</p>
<ul>
<li> dans une section <Macro> au style conforme à la
syntaxe des fichiers de configuration Apache.</li>
<li> l'utilisateur choisit le nom de la macro et de ses paramètres.</li>
<li> les noms de macro sont insensibles à la casse, comme les directives Apache.</li>
<li> les noms de paramètres sont par contre sensibles à la casse.</li>
<li> les paramètres d'une macro doivent avoir des noms distincts.</li>
<li> il y a une erreur si un paramètre a un nom vide.</li>
<li> la redéfinition d'une macro génère un avertissement.</li>
<li> des définitions de macros peuvent être imbriquées les unes dans les autres... (mais dans quel but ?)</li>
<li> les paramètres inutilisés génèrent un avertissement.</li>
<li> les noms de paramètre en préfixe les uns des autres génèrent un avertissement.</li>
<li> les noms de paramètre non préfixés par un des caractères '<code>$%@</code>' génèrent un
avertissement pour encourager cette bonne pratique.</li>
<li> les différents préfixes proposés permettent de gérer les interactions
avec d'autres directives comme <directive module="core">Define</directive>.</li>
<li> un conseil : il peut être utile d'ajouter des accolades autour du nom d'un
paramètre, par exemple <code>${foo}</code>, de manière à ce que le
paramètre puisse être utilisé entouré de caractères,
par exemple <code>bla${foo}bla</code>.</li>
<li> génère un avertissement si le contenu de la macro est vide.</li>
<li> génère un avertissement si le système détecte que les sections à l'intérieur
d'une macro ne sont pas correctement imbriquées.</li>
<li> la portée lexicale des paramètres d'une macro est restreinte au texte
de la macro elle-même... en particulier elle n'est pas propagée aux inclusions.</li>
<li> il n'y a pas de contrainte sur le contenu d'une macro.
<p>Cela signifie que vous pouvez mettre une section perl ou n'importe
quoi d'autre dans une macro. Il n'y a pas d'autre contrainte sur la
structure lexicale et syntaxique de la macro (guillemets, espaces...)
que d'attendre une séquence de ligne avec éventuellement des
continuations.</p></li>
</ul>
<p>Utilisation d'une macro:</p>
<ul>
<li> le nombre d'arguments doit être cohérent avec la définition.</li>
<li> toutes les occurences des paramètres sont substituées par leur valeur.</li>
<li> en cas de conflit, le nom le plus long est choisi.</li>
<li> une récursion dans l'expansion d'une macro est détectée et interrompue avec envoi d'un message d'erreur.</li>
<li> si un argument vide est détecté, un avertissement est généré.</li>
<li> le système s'efforce de générer une description précise de la localisation des erreurs.</li>
<li> les valeurs des paramètres préfixées par <code>$</code> et <code>%</code> ne sont pas échappées.</li>
<li> les valeurs des paramètres préfixées par <code>@</code> sont échappées par des guillemets.</li>
</ul>
<p>Suppression de la définition d'une macro :</p>
<ul>
<li> la macro supprimée doit avoir été définie auparavant.</li>
</ul>
<highlight language="config">
<Macro DirGroup $dir $group>
<Directory $dir>
require group $group
</Directory>
</Macro>
UndefMacro DirGroup
</highlight>
</section>
<section id="examples"><title>Exemples</title>
<p>Un exemple typique d'utilisation de <module>mod_macro</module> est la
création dynamique de serveurs virtuels.</p>
<highlight language="config">
## Définition d'une macro VHost pour les configurations répétitives
<Macro VHost $host $port $dir>
Listen $port
<VirtualHost *:$port>
ServerName $host
DocumentRoot $dir
<Directory $dir>
# directives propres au répertoire $dir ...
</Directory>
# restriction d'accès au sous-répertoire intranet.
Require ip 10.0.0.0/8
</Directory>
</VirtualHost>
</Macro>
## Utilisation de la macro VHost avec différents arguments.
</highlight>
</section>
<!-- Macro -->
<directivesynopsis type="section">
<name>Macro</name>
<description>Définition d'une macro dans un fichier de configuration</description>
<syntax>
<Macro <var>nom</var> [<var>par1</var> .. <var>parN</var>]>
... </Macro></syntax>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
</contextlist>
<usage>
<p>La directive <directive>Macro</directive> permet de définir une macro
dans un fichier de configuration Apache. Le premier argument est le nom
de la macro, et les arguments suivants sont les paramètres. Il
est de bon aloi de préfixer les noms des paramètres d'une macro
avec un caractère parmi '<code>$%@</code>', et d'éviter d'en faire
de même avec les noms de macros.
</p>
<highlight language="config">
<Macro LocalAccessPolicy>
</Macro>
<Macro RestrictedAccessPolicy $ipnumbers>
Require ip $ipnumbers
</Macro>
</highlight>
</usage>
</directivesynopsis>
<!-- Use -->
<directivesynopsis>
<name>Use</name>
<description>Utilisation d'une macro</description>
<syntax>Use <var>nom</var> [<var>valeur1</var> ... <var>valeurN</var>]
</syntax>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
</contextlist>
<usage>
<p> La directive <directive>Use</directive> permet d'utiliser une macro.
La macro considérée est expansée. Son nombre d'arguments doit être égal au
nombre de paramètres précisés dans sa définition. Les valeurs passées en
argument sont attribuées aux paramètres correspondants et
substituées avant l'interprétation du texte de la macro.</p>
<highlight language="config">
Use LocalAccessPolicy
...
</highlight>
<p>est équivalent, avec les macros définies ci-dessus à :</p>
<highlight language="config">
...
</highlight>
</usage>
</directivesynopsis>
<!-- UndefMacro -->
<directivesynopsis>
<name>undefMacro</name>
<description>Supprime une macro</description>
<syntax>UndefMacro <var>nom</var></syntax>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
</contextlist>
<usage>
<p>La directive <directive>UndefMacro</directive> annule la définition
d'une macro qui doit avoir été définie auparavant.</p>
<highlight language="config">
UndefMacro LocalAccessPolicy
UndefMacro RestrictedAccessPolicy
</highlight>
</usage>
</directivesynopsis>
</modulesynopsis>