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 docsformat.html
Date Thu, 14 Feb 2002 00:49:47 GMT
slive       02/02/13 16:49:47

  Added:       xdocs/docs-project docsformat.xml
               docs/docs-project docsformat.html
  Log:
  Documentation for the new module docs system.
  
  Revision  Changes    Path
  1.1                  httpd-site/xdocs/docs-project/docsformat.xml
  
  Index: docsformat.xml
  ===================================================================
  <?xml version="1.0"?>
  <document>
    <properties>
      <title>Module Format and Transformation</title>
    </properties>
  <body>
  <section>
  <title>Module Format and Transformation</title>
  
  <p>This document describes the format of the Apache HTTP Server module
  documentation xml source files and the technique used to transform
  them to html.</p>
  
  </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;context&gt;: ibid</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;.</li>
  </ul>
  
  <p>Finally, the following tags -- along with their usage and meaning
  -- are borrowed from xhtml.  Please try not to use any other xhtml
  tags, since this will make it more difficult to do transformations in
  the future.</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>
  
  </section>
  
  <section><title>Transformation</title>
  
  <p>The easiest way to view the tranformed docs is simply to open the
  xml file directly in a recent verions of MSIE, Netscape, or Mozilla.
  All these browsers will read the xsl file and perform the
  transformation for you automatically, so you can see what the final
  output will look like.  This means that you can work on the docs and
  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>
  
  <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>
  
  </section>
  </body>
  </document>
  
  
  1.1                  httpd-site/docs/docs-project/docsformat.html
  
  Index: docsformat.html
  ===================================================================
  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  <html>
   <head>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
        <title>Module Format and Transformation - The Apache HTTP Server Project</title>
   </head>
   <body bgcolor="#ffffff" text="#000000" link="#525D76">
  <p><a href="/"><img src="../images/httpd_logo_wide.gif" alt="The Apache HTTP
Server Project" border="0"/></a></p>
   <table border="0" width="100%" cellspacing="4">
     <tr>
      <!-- LEFT SIDE NAVIGATION -->
      <td valign="top" nowrap="nowrap">
             <p><b>Essentials</b></p>
      <menu compact="compact">
            <li><a href="/ABOUT_APACHE.html">About</a></li>
            <li><a href="http://www.apache.org/LICENSE.txt">License</a></li>
            <li><a href="/docs/misc/FAQ.html">FAQ</a></li>
            <li><a href="/security_report.html">Security<br />Reports</a></li>
          </menu>
        <p><b>Download!</b></p>
      <menu compact="compact">
            <li><a href="http://www.apache.org/dyn/closer.cgi">from a mirror</a></li>
            <li><a href="http://www.apache.org/dist/httpd/">from here</a></li>
          </menu>
        <p><b><a 
  href="/docs-project/">Documentation</a></b></p>
      <menu compact="compact">
            <li><a href="/docs/">Apache 1.3</a></li>
            <li><a href="/docs-2.0/">Apache 2.0</a></li>
          </menu>
        <p><b>Get Involved</b></p>
      <menu compact="compact">
            <li><a href="/lists.html">Mailing Lists</a></li>
            <li><a href="/bug_report.html">Bug Reports</a></li>
            <li><a href="/dev/">Developer Info</a></li>
          </menu>
        <p><b>Subprojects</b></p>
      <menu compact="compact">
            <li><a href="/docs-project/">Docs</a></li>
            <li><a href="/test/">Test</a></li>
          </menu>
        <p><b><a 
  href="/info/">Miscellaneous</a></b></p>
      <menu compact="compact">
            <li><a href="/contributors/">Contributors</a></li>
            <li><a href="/awards.html">Awards</a></li>
            <li><a href="http://nav.webring.org/navcgi?ring=apachesupport;list">Support<br
/>Webring</a></li>
          </menu>
      </td>
      <!-- RIGHT SIDE INFORMATION -->
      <td align="left" valign="top">
                  <table border="0" cellspacing="0" cellpadding="2" width="100%">
   <tr><td bgcolor="#525D76">
    <font color="#ffffff" face="arial,helvetica,sanserif">
     <strong>Module Format and Transformation</strong>
    </font>
   </td></tr>
   <tr><td>
    <blockquote>
  <p>This document describes the format of the Apache HTTP Server module
  documentation xml source files and the technique used to transform
  them to html.</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>Format</strong>
    </font>
   </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;context&gt;: ibid</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;.</li>
  </ul>
  <p>Finally, the following tags -- along with their usage and meaning
  -- are borrowed from xhtml.  Please try not to use any other xhtml
  tags, since this will make it more difficult to do transformations in
  the future.</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>
    </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>Transformation</strong>
    </font>
   </td></tr>
   <tr><td>
    <blockquote>
  <p>The easiest way to view the tranformed docs is simply to open the
  xml file directly in a recent verions of MSIE, Netscape, or Mozilla.
  All these browsers will read the xsl file and perform the
  transformation for you automatically, so you can see what the final
  output will look like.  This means that you can work on the docs and
  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>
  <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>
    </blockquote>
   </td></tr>
  </table>
           </td>
     </tr>
     <!-- FOOTER -->
     <tr><td colspan="2"><hr noshade="noshade" size="1"/></td></tr>
     <tr><td colspan="2" align="center">
          <font size="-1">
           <em>Copyright &#169; 1999-2002, The Apache Software Foundation</em>
          </font>
         </td>
     </tr>
    </table>
   </body>
  </html>
  
  
  

Mime
View raw message