content/docs-project/mod_template.txt

<?xml version="1.0"?> 
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> 
<!-- $LastChangedRevision: 926436 $ -->

<!--
Upon adding a new module XML doc, you will need to:

svn ps svn:eol-style native <alltextfiles>
svn ps svn:keywords LastChangedRevision mod_template.xml

in order for it to rebuild correctly.

-->
                                                                                                                                  
<!--                                                                                                                              
 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

 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> is the root tag and must surround all other tags.
The sequence of tags is important and must be followed in order for
the document to validate. -->

<modulesynopsis metafile="mod_template.xml.meta"> 

<!-- module name in lower case; must be identical to base filename -->
<name>mod_template</name>

<!-- A very short (less than one sentence) description of the
module; begins with a capital, but does not end with a period, nor
does it refer to "this module" -->
<description>Demonstrates the module documentation format</description>

<!-- From:
https://httpd.apache.org/docs/2.2/mod/module-dict.html#Status -->
<status>experimental</status>

<!-- As in:
https://httpd.apache.org/docs/2.2/mod/module-dict.html#SourceFile -->
<sourcefile>mod_template.c</sourcefile>

<!-- As in:
https://httpd.apache.org/docs/2.2/mod/module-dict.html#ModuleIdentifier -->
<identifier>template_module</identifier>

<!-- Optional: as in:
https://httpd.apache.org/docs/2.2/mod/module-dict.html#Compatibility -->
<compatibility>Not actually available in any version</compatibility>


<summary>
<!-- Optional but strongly recommended: A one to three paragraph
summary of what the module does and how to use it.  Text cannot be
placed directly, but rather must be inside paragraphs, examples,
notes, etc. -->

<p>This is a template and demonstration of the proper documentation format
for Apache HTTP Server modules.</p>

<example><title>Example</title>
# Examples are always helpful.<br />
TemplateDirective On<br />
</example>

<note type="warning">
Don't try to actually use this module, since it doesn't exist.
</note>

</summary>

<!-- References to other documents or directives -->
<seealso><a href="...">Useful document</a></seealso>
<seealso><directive module="mod_useful">Useful</directive></seealso>
<seealso><module>mod_useful</module></seealso>

<!-- Any number of sections may be included below -->
<section id="moredocs"><title>Additional Documentation</title>

<p>More detailed information about the module in general (as opposed to
the individual directives) can follow in sections containing titles.</p>

<p>The <code>id</code> attribute will be translated into a hypertext
anchor target.</p>

<p>References to directives should use the directive tag: <directive
module="mod_template">TemplateDirective</directive>.  References to
modules should use the module tag
<module>mod_template.xml</module>.</p>

</section>


<directivesynopsis>
<!-- Exact name of directive in mixed case -->
<name>TemplateDirective</name>

<!-- A very short (less than one sentence) description of the
directive; begins with a capital, but does not end with a period -->
<description>Changes absolutely nothing</description>

<!-- As in:
https://httpd.apache.org/docs/2.2/mod/directive-dict.html#Syntax -->
<syntax>TemplateDirective One|Two|Thee <em>file-path</em> 
[<em>env-variable</em>] [<em>env-variable</em>] ...</syntax>

<!-- Optional: Plain text only, exactly as the dirctive would appear in
the config file, as in:
https://httpd.apache.org/docs/2.2/mod/directive-dict.html#Default -->
<default>TemplateDirective Two /usr/local/apache</default>

<!-- Each context as in:
https://httpd.apache.org/docs/2.2/mod/directive-dict.html#Context
is placed in a separate context tag -->
<contextlist><context>Directory</context><context>.htaccess</context>
</contextlist>

<!-- Required if and only if the contextlist includes .htacccess, as in
https://httpd.apache.org/docs/2.2/mod/directive-dict.html#Override -->
<override>FileInfo</override>

<!-- Used only if the same directive is implemented by multiple modules.
Otherwise, the module will be automatically be grabbed from above. -->
<modulelist><module>mod_template</module>
<module>mod_othermodule</module>
</modulelist>

<!-- Used only if the status for the directive differs from the status
for the module as a whole.  As in:
https://httpd.apache.org/docs/2.2/mod/directive-dict.html#Status -->
<status>Experimental</status>

<!-- Optional, as in:
https://httpd.apache.org/docs/2.2/mod/directive-dict.html#Compatibility -->
<compatibility>Does not really exist</compatibility>

<!-- Detailed description of what the directive does and how to use it -->
<usage>

<p>Only the block tags p, example, note, blockquote, ul, and ol can be
used directly under usage.  The pre tag is also allowed, but its use
is discourage.  Inside a paragraph, the tags em, strong, a, code,
directive, module, and br are allowed.</p>

<p>The directive tag (when the module attribute is given) and the
module tag automatically create links.  For "section" directives like
&lt;Directory&gt;, a special format is used: <directive module="core"
type="section">Directory</directive>.  The angle brackets will be
added automatically for display.</p>

<p>The example and note tag have optional &lt;title&gt;s.  The note
tag also has a "type" attribute that can be set to "warning".</p>

<p>All content must be well-formed xml.  This means closing tags must
be used in the correct places, and unclosed tags must be written as such:
&lt;br /&gt;.</p>
</usage>

<!-- Any number of seealso references can be used for each directive -->
<seealso><directive module="template.xml">Location</directive></seealso>
</directivesynopsis>

<!-- If a directive from this module is documented in another module,
then a special format of the directivesynopsis tag can be used to
reference it. -->
<directivesynopsis location="othermodule">
<name>OtherDirective</name>
</directivesynopsis>

<!-- If the directive marks a "section" like Directory, Location, etc,
another special format is used -->
<directivesynopsis type="section">
<!-- The angle brackets are *not* included in the name.  They will be
added automatically for display -->
<name>Location</name>
<!-- Continue as before -->
</directivesynopsis>

</modulesynopsis>