httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sl...@apache.org
Subject cvs commit: httpd-site/docs/docs-project mod_template.txt docsformat.html index.html
Date Tue, 12 Mar 2002 20:56:44 GMT
slive       02/03/12 12:56:44

  Modified:    xdocs/docs-project docsformat.xml index.xml
               docs/docs-project docsformat.html index.html
  Added:       xdocs/docs-project mod_template.txt
               docs/docs-project mod_template.txt
  Log:
  Document the documentation.  Details on the new xml format.
  
  Submitted by:	Brad Miller <brad@beldamar.com>, Joshua Slive
  
  Revision  Changes    Path
  1.3       +29 -75    httpd-site/xdocs/docs-project/docsformat.xml
  
  Index: docsformat.xml
  ===================================================================
  RCS file: /home/cvs/httpd-site/xdocs/docs-project/docsformat.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -d -b -u -r1.2 -r1.3
  --- docsformat.xml	19 Feb 2002 18:19:26 -0000	1.2
  +++ docsformat.xml	12 Mar 2002 20:56:44 -0000	1.3
  @@ -14,71 +14,18 @@
   </section>
   <section><title>Format</title>
   
  -<p>A formal DTD or schema would be nice, but in the meantime, here is
  -a sketch of the tags used to document modules.</p>
  -
  -<p>The document as a whole is enclosed in a
  -<code>&lt;modulesynopsis&gt;</code> section.  At the first level under
  -that section, the following tags are allowed:</p>
  -
  -<ul>
  -<li>&lt;name&gt;: the name of the module as in <code>mod_setenvif</code></li>
  -<li>&lt;description&gt;: a one-sentence description of the module</li>
  -<li><a href="http://httpd.apache.org/docs-2.0/mod/module-dict.html#Status">&lt;status&gt;</a>
</li>
  -<li><a href="http://httpd.apache.org/docs-2.0/mod/module-dict.html#ModuleIdentifier">&lt;identifier&gt;</a>
</li>
  -<li><a href="http://httpd.apache.org/docs-2.0/mod/module-dict.html#SourceFile">&lt;sourcefile&gt;</a>
</li>
  -<li><a href="http://httpd.apache.org/docs-2.0/mod/module-dict.html#Compatibility">&lt;compatibility&gt;</a></li>
  -<li>&lt;summary&gt;: A one to three paragraph summary of what the module
does.</li>
  -<li>&lt;seealso&gt;: References to other directives, modules, documents,
etc.  Any number of of these are permitted</li>
  -<li>&lt;section&gt;: Additional documentation for the module as a whole.
 Must contain a &lt;title&gt;.</li>
  -<li>&lt;directivesynopsis&gt;: Documentation for a directive.</li>
  -</ul>
  -
  -<p>Inside the <code>&lt;directivesynopsis&gt;</code>, the following
  -are allowed.</p>
  -
  -<ul>
  -<li>&lt;name&gt;: Name of the directive as in <code>SetEnvIf</code></li>
  -<li>&lt;description&gt;: A one sentence description of the directive</li>
  -<li>&lt;syntax&gt;: As described in the <a href="http://httpd.apache.org/docs-2.0/mod/directive-dict.html">directive
dictionary</a></li>
  -<li>&lt;default&gt;: ibid</li>
  -<li>&lt;contextlist&gt;: ibid; contains a list of &lt;context&gt;s</li>
  -<li>&lt;override&gt;: ibid</li>
  -<li>&lt;compatibility&gt;: ibid</li>
  -<li>&lt;usage&gt;: a detailed description of what the directive does, and
how to use it, with examples.</li>
  -<li>&lt;seealso&gt;: References to other directives, modules, documents,
etc.  Any number of these are permitted</li>
  -</ul>
  -
  -<p>In addition, the following "utility" tags are available to use inside &lt;summary&gt;,
&lt;section&gt;, &lt;usage&gt;, etc.</p>
  -
  -<ul>
  -<li>&lt;example&gt;: A block level example with an optional
  -&lt;title&gt;.  This will be presented in a fixed-width font, but 
  -not in a &lt;pre&gt; so white space is not significant and you must
  -use &lt;br /&gt; if you want to force line breaks.</li>
  -
  -<li>&lt;note&gt;: A block level call-out, containing an optional
  -&lt;title&gt;.  Used to set something off from the text.</li>
  -
  -<li>&lt;module&gt;: Used to mark the name of a module.  A link will be
  -automatically created to the named module.</li>
  -
  -<li>&lt;directive&gt;: Used to mark the name of a directive.  A link
  -will be created to the directive if the <code>module</code> attribute
  -is given, as in &lt;directive
  -module="mod_setenvif"&gt;BrowserMatch&lt;/directive&gt;.  If the
  -<code>type</code> attribute is set to <code>section</code>, then
  -the directive will be surrounded by &gt; and &lt; when displayed.</li>
  -</ul>
  -
  -<p>Finally, the following tags -- along with their usage and meaning
  --- are borrowed from xhtml.  Other tags will also be passed through,
  -but the more tags we use, the more difficult will be future
  -transormations.</p>
  +<p>A DTD is located at <a
  +href="http://httpd.apache.org/docs-2.0/style/modulesynopsis.dtd">docs/manual/style/modulesynopsis.dtd</a>.
  +An example of the format with extensive comments is also available in
  +<a href="mod_template.txt">mod_template.txt</a>.  Obviously, the file
  +extension should be <code>xml</code>.  It was changed to make online
  +viewing simpler.</p>
   
  -<p>&lt;p&gt; &lt;ul&gt; &lt;ol&gt; &lt;li&gt; &lt;strong&gt;
  -&lt;em&gt; &lt;br&gt; &lt;code&gt; &lt;blockquote&gt; &lt;table&gt;
  -&lt;tr&gt; &lt;td&gt; &lt;dl&gt; &lt;dt&gt; &lt;dd&gt;</p>
  +<p>To assure that your documentation follows the defined format, you
  +should parse it using the DTD.  Some help using Emacs with XML files
  +is availble from <a
  +href="http://www-106.ibm.com/developerworks/xml/library/x-emacs/">IBM
  +developerWorks</a>.</p>
   
   </section>
   
  @@ -93,21 +40,28 @@
   
   <p>For the final presentation, it is still necessary to transform to
   html to accomodate older browsers.  Any standards-compliant xslt
  -engine should do.  The one we will discuss here is Xalan+Xerces with
  -build automation from ant.  These are all Apache projects distributed
  -under the Apache license.</p>
  +engine should do.  The one we will discuss here is Xalan+Xerces Java.
  +These are all Apache projects distributed under the Apache
  +license.</p>
   
   <p>Assuming that you already have <code>httpd-2.0/docs/manual</code>
   checked out from CVS, the requirements to do the transformation are a
   Java 1.2 JVM (which you can obtain free from Sun), and the jars for
  -Xalan, Xerces, and Ant, which you can download <a
  -href="jars.tar.gz">in a bundle</a>.  Place these jars in the
  -<code>httpd-2.0/docs/manual/style/lib/</code> directory.  Then all you
  -need to do to transform the docs is to run the shell script
  -<code>./build.sh</code>.  If you are on win32, the shell script will
  -work if you have cygwin installed.  Alternatively, you can run ant
  -directly, but you will need to download and install it separately.</p>
  +the <a href="http://xml.apache.org/xalan-j/getstarted.html">Xalan
  +distribution</a>.  If you just want to transform one document at a
  +time, you can simple follow the directions on the Xalan webpage.</p>
  +
  +<p>Eventually, we will need a better system for updating the
  +transformations on all the documents at once.</p>
  +</section>
  +
  +<section><title>Special Files</title>
  +
  +<p>When adding a new module, the name of the xml file must be added to
  +<code>mod/allmodules.xml</code>.  In this way, the new module will
  +be included in the automatic index generation procedures.</p>
   
   </section>
  +
   </body>
   </document>
  
  
  
  1.5       +4 -0      httpd-site/xdocs/docs-project/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/httpd-site/xdocs/docs-project/index.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -d -b -u -r1.4 -r1.5
  --- index.xml	31 Jan 2002 18:43:02 -0000	1.4
  +++ index.xml	12 Mar 2002 20:56:44 -0000	1.5
  @@ -50,6 +50,10 @@
   <a href="http://apache-server.com/tutorials/ATdocs-project.html"
   >Documentation Project Tutorial</a>.</p>
   
  +<p>For information on our project to use XML in the documentation, see
  +our <a href="docsformat.html">Documentation Format and
  +Transformation</a> page.</p>
  +
   </section>
   <section>
   <title>Translation Projects</title>
  
  
  
  1.1                  httpd-site/xdocs/docs-project/mod_template.txt
  
  Index: mod_template.txt
  ===================================================================
  <?xml version="1.0"?> 
  <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
  <?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> 
  
  <!--<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>
  
  <!-- 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:
  http://httpd.apache.org/docs-2.0/mod/module-dict.html#Status -->
  <status>experimental</status>
  
  <!-- As in:
  http://httpd.apache.org/docs-2.0/mod/module-dict.html#SourceFile -->
  <sourcefile>mod_template.c</sourcefile>
  
  <!-- As in:
  http://httpd.apache.org/docs-2.0/mod/module-dict.html#ModuleIdentifier -->
  <identifier>template_module</identifier>
  
  <!-- Optional: as in:
  http://httpd.apache.org/docs-2.0/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:
  http://httpd.apache.org/docs-2.0/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:
  http://httpd.apache.org/docs-2.0/mod/directive-dict.html#Default -->
  <default>TemplateDirective Two /usr/local/apache</default>
  
  <!-- Each context as in:
  http://httpd.apache.org/docs-2.0/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
  http://httpd.apache.org/docs-2.0/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:
  http://httpd.apache.org/docs-2.0/mod/directive-dict.html#Status -->
  <status>Experimental</status>
  
  <!-- Optional, as in:
  http://httpd.apache.org/docs-2.0/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 /&gr;.</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>
  
  
  
  
  1.3       +31 -66    httpd-site/docs/docs-project/docsformat.html
  
  Index: docsformat.html
  ===================================================================
  RCS file: /home/cvs/httpd-site/docs/docs-project/docsformat.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -d -b -u -r1.2 -r1.3
  --- docsformat.html	19 Feb 2002 18:19:26 -0000	1.2
  +++ docsformat.html	12 Mar 2002 20:56:44 -0000	1.3
  @@ -72,63 +72,15 @@
    </td></tr>
    <tr><td>
     <blockquote>
  -<p>A formal DTD or schema would be nice, but in the meantime, here is
  -a sketch of the tags used to document modules.</p>
  -<p>The document as a whole is enclosed in a
  -<code>&lt;modulesynopsis&gt;</code> section.  At the first level under
  -that section, the following tags are allowed:</p>
  -<ul>
  -<li>&lt;name&gt;: the name of the module as in <code>mod_setenvif</code></li>
  -<li>&lt;description&gt;: a one-sentence description of the module</li>
  -<li><a href="http://httpd.apache.org/docs-2.0/mod/module-dict.html#Status">&lt;status&gt;</a>
</li>
  -<li><a href="http://httpd.apache.org/docs-2.0/mod/module-dict.html#ModuleIdentifier">&lt;identifier&gt;</a>
</li>
  -<li><a href="http://httpd.apache.org/docs-2.0/mod/module-dict.html#SourceFile">&lt;sourcefile&gt;</a>
</li>
  -<li><a href="http://httpd.apache.org/docs-2.0/mod/module-dict.html#Compatibility">&lt;compatibility&gt;</a></li>
  -<li>&lt;summary&gt;: A one to three paragraph summary of what the module
does.</li>
  -<li>&lt;seealso&gt;: References to other directives, modules, documents,
etc.  Any number of of these are permitted</li>
  -<li>&lt;section&gt;: Additional documentation for the module as a whole.
 Must contain a &lt;title&gt;.</li>
  -<li>&lt;directivesynopsis&gt;: Documentation for a directive.</li>
  -</ul>
  -<p>Inside the <code>&lt;directivesynopsis&gt;</code>, the following
  -are allowed.</p>
  -<ul>
  -<li>&lt;name&gt;: Name of the directive as in <code>SetEnvIf</code></li>
  -<li>&lt;description&gt;: A one sentence description of the directive</li>
  -<li>&lt;syntax&gt;: As described in the <a href="http://httpd.apache.org/docs-2.0/mod/directive-dict.html">directive
dictionary</a></li>
  -<li>&lt;default&gt;: ibid</li>
  -<li>&lt;contextlist&gt;: ibid; contains a list of &lt;context&gt;s</li>
  -<li>&lt;override&gt;: ibid</li>
  -<li>&lt;compatibility&gt;: ibid</li>
  -<li>&lt;usage&gt;: a detailed description of what the directive does, and
how to use it, with examples.</li>
  -<li>&lt;seealso&gt;: References to other directives, modules, documents,
etc.  Any number of these are permitted</li>
  -</ul>
  -<p>In addition, the following "utility" tags are available to use inside &lt;summary&gt;,
&lt;section&gt;, &lt;usage&gt;, etc.</p>
  -<ul>
  -<li>&lt;example&gt;: A block level example with an optional
  -&lt;title&gt;.  This will be presented in a fixed-width font, but 
  -not in a &lt;pre&gt; so white space is not significant and you must
  -use &lt;br /&gt; if you want to force line breaks.</li>
  -
  -<li>&lt;note&gt;: A block level call-out, containing an optional
  -&lt;title&gt;.  Used to set something off from the text.</li>
  -
  -<li>&lt;module&gt;: Used to mark the name of a module.  A link will be
  -automatically created to the named module.</li>
  -
  -<li>&lt;directive&gt;: Used to mark the name of a directive.  A link
  -will be created to the directive if the <code>module</code> attribute
  -is given, as in &lt;directive
  -module="mod_setenvif"&gt;BrowserMatch&lt;/directive&gt;.  If the
  -<code>type</code> attribute is set to <code>section</code>, then
  -the directive will be surrounded by &gt; and &lt; when displayed.</li>
  -</ul>
  -<p>Finally, the following tags -- along with their usage and meaning
  --- are borrowed from xhtml.  Other tags will also be passed through,
  -but the more tags we use, the more difficult will be future
  -transormations.</p>
  -<p>&lt;p&gt; &lt;ul&gt; &lt;ol&gt; &lt;li&gt; &lt;strong&gt;
  -&lt;em&gt; &lt;br&gt; &lt;code&gt; &lt;blockquote&gt; &lt;table&gt;
  -&lt;tr&gt; &lt;td&gt; &lt;dl&gt; &lt;dt&gt; &lt;dd&gt;</p>
  +<p>A DTD is located at <a href="http://httpd.apache.org/docs-2.0/style/modulesynopsis.dtd">docs/manual/style/modulesynopsis.dtd</a>.
  +An example of the format with extensive comments is also available in
  +<a href="mod_template.txt">mod_template.txt</a>.  Obviously, the file
  +extension should be <code>xml</code>.  It was changed to make online
  +viewing simpler.</p>
  +<p>To assure that your documentation follows the defined format, you
  +should parse it using the DTD.  Some help using Emacs with XML files
  +is availble from <a href="http://www-106.ibm.com/developerworks/xml/library/x-emacs/">IBM
  +developerWorks</a>.</p>
     </blockquote>
    </td></tr>
   </table>
  @@ -148,18 +100,31 @@
   check your work without any special transformation setup.</p>
   <p>For the final presentation, it is still necessary to transform to
   html to accomodate older browsers.  Any standards-compliant xslt
  -engine should do.  The one we will discuss here is Xalan+Xerces with
  -build automation from ant.  These are all Apache projects distributed
  -under the Apache license.</p>
  +engine should do.  The one we will discuss here is Xalan+Xerces Java.
  +These are all Apache projects distributed under the Apache
  +license.</p>
   <p>Assuming that you already have <code>httpd-2.0/docs/manual</code>
   checked out from CVS, the requirements to do the transformation are a
   Java 1.2 JVM (which you can obtain free from Sun), and the jars for
  -Xalan, Xerces, and Ant, which you can download <a href="jars.tar.gz">in a bundle</a>.
 Place these jars in the
  -<code>httpd-2.0/docs/manual/style/lib/</code> directory.  Then all you
  -need to do to transform the docs is to run the shell script
  -<code>./build.sh</code>.  If you are on win32, the shell script will
  -work if you have cygwin installed.  Alternatively, you can run ant
  -directly, but you will need to download and install it separately.</p>
  +the <a href="http://xml.apache.org/xalan-j/getstarted.html">Xalan
  +distribution</a>.  If you just want to transform one document at a
  +time, you can simple follow the directions on the Xalan webpage.</p>
  +<p>Eventually, we will need a better system for updating the
  +transformations on all the documents at once.</p>
  +  </blockquote>
  + </td></tr>
  +</table>
  +           <table border="0" cellspacing="0" cellpadding="2" width="100%">
  + <tr><td bgcolor="#525D76">
  +  <font color="#ffffff" face="arial,helvetica,sanserif">
  +   <strong>Special Files</strong>
  +  </font>
  + </td></tr>
  + <tr><td>
  +  <blockquote>
  +<p>When adding a new module, the name of the xml file must be added to
  +<code>mod/allmodules.xml</code>.  In this way, the new module will
  +be included in the automatic index generation procedures.</p>
     </blockquote>
    </td></tr>
   </table>
  
  
  
  1.10      +3 -0      httpd-site/docs/docs-project/index.html
  
  Index: index.html
  ===================================================================
  RCS file: /home/cvs/httpd-site/docs/docs-project/index.html,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -d -b -u -r1.9 -r1.10
  --- index.html	3 Feb 2002 15:26:16 -0000	1.9
  +++ index.html	12 Mar 2002 20:56:44 -0000	1.10
  @@ -97,6 +97,9 @@
   <a href="mailto:docs-subscribe@httpd.apache.org">docs-subscribe@httpd.apache.org</a>.
 For details on how to
   contribute, the best place to start is Ken Coar's
   <a href="http://apache-server.com/tutorials/ATdocs-project.html">Documentation Project
Tutorial</a>.</p>
  +<p>For information on our project to use XML in the documentation, see
  +our <a href="docsformat.html">Documentation Format and
  +Transformation</a> page.</p>
     </blockquote>
    </td></tr>
   </table>
  
  
  
  1.1                  httpd-site/docs/docs-project/mod_template.txt
  
  Index: mod_template.txt
  ===================================================================
  <?xml version="1.0"?> 
  <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
  <?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> 
  
  <!--<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>
  
  <!-- 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:
  http://httpd.apache.org/docs-2.0/mod/module-dict.html#Status -->
  <status>experimental</status>
  
  <!-- As in:
  http://httpd.apache.org/docs-2.0/mod/module-dict.html#SourceFile -->
  <sourcefile>mod_template.c</sourcefile>
  
  <!-- As in:
  http://httpd.apache.org/docs-2.0/mod/module-dict.html#ModuleIdentifier -->
  <identifier>template_module</identifier>
  
  <!-- Optional: as in:
  http://httpd.apache.org/docs-2.0/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:
  http://httpd.apache.org/docs-2.0/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:
  http://httpd.apache.org/docs-2.0/mod/directive-dict.html#Default -->
  <default>TemplateDirective Two /usr/local/apache</default>
  
  <!-- Each context as in:
  http://httpd.apache.org/docs-2.0/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
  http://httpd.apache.org/docs-2.0/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:
  http://httpd.apache.org/docs-2.0/mod/directive-dict.html#Status -->
  <status>Experimental</status>
  
  <!-- Optional, as in:
  http://httpd.apache.org/docs-2.0/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 /&gr;.</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>
  
  
  
  

Mime
View raw message