Update docos.

pull/193/head
Michael R Sweet 17 years ago
parent 92abe20fb4
commit 7d8801c7dd
  1. 2
      doc/makedocs.sh
  2. 363
      doc/mxml.html

@ -17,7 +17,7 @@
# GNU General Public License for more details.
#
htmldoc --verbose --path hires:. --batch mxml.book -f mxml.pdf
htmldoc --verbose --path "hires;." --batch mxml.book -f mxml.pdf
htmldoc --verbose --batch mxml.book --no-title -f mxml.html

@ -68,9 +68,7 @@ A { text-decoration: none }
<UL>
<LI><A HREF="#5_1">The Basics</A></LI>
<LI><A HREF="#5_2">Commenting Your Code</A></LI>
<LI><A HREF="#5_3">Creating HTML Documentation</A></LI>
<LI><A HREF="#5_4">Creating Man Pages</A></LI>
<LI><A HREF="#5_5">The XML Schema</A></LI>
<LI><A HREF="#5_3">Titles, Sections, and Introductions</A></LI>
</UL>
<B><A HREF="#LICENSE">Mini-XML License</A></B>
<BR>
@ -174,6 +172,8 @@ A { text-decoration: none }
</UL>
</LI>
</UL>
<B><A HREF="#SCHEMA">XML Schema</A></B>
<UL></UL>
<HR NOSHADE>
<H1 align="right"><A name="INTRO"><IMG align="right" alt="0" height="100"
hspace="10" src="0.gif" width="100"></A>Introduction</H1>
@ -229,6 +229,8 @@ libxml2</TT> library with something substantially smaller and
changes in each release of Mini-XML.</LI>
<LI>Appendix C, &quot;<A href="#REFERENCE">Library Reference</A>&quot;, contains a
complete reference for Mini-XML, generated by <TT>mxmldoc</TT>.</LI>
<LI>Appendix D, &quot;<A href="#SCHEMA">XML Schema</A>&quot;, shows the XML schema
used for the XML files produced by <TT>mxmldoc</TT>.</LI>
</UL>
<!-- NEED 10 -->
@ -1345,28 +1347,148 @@ mxmlRetain</TT></A> function. For example, the following SAX callback
<HR NOSHADE>
<H1 align="right"><A name="MXMLDOC"><IMG align="right" alt="4" height="100"
hspace="10" src="4.gif" width="100"></A>Using the mxmldoc Utility</H1>
<P>This chapter describes how to use <TT>mxmldoc(1)</TT> program to
automatically generate documentation from C and C++ source files.</P>
<H2><A NAME="5_1">The Basics</A></H2>
<P>Originally developed to generate the Mini-XML and CUPS API
documentation, the <TT>mxmldoc(1)</TT> program converts C and C++
source files into an intermediate XML format and uses in-line comments
rather than comment headers to annotate functions, types, and
constants.</P>
<P></P>
documentation, <TT>mxmldoc</TT> is now a general-purpose utility which
scans C and C++ source files to produce HTML and man page documentation
along with an XML file representing the functions, types, and
definitions in those source files. Unlike popular documentation
generators like Doxygen or Javadoc, <TT>mxmldoc</TT> uses in-line
comments rather than comment headers, allowing for more &quot;natural&quot; code
documentation.</P>
<P>By default, <TT>mxmldoc</TT> produces HTML documentation. For
example, the following command will scan all of the C source and header
files in the current directory and produce a HTML documentation file
called<VAR> filename.html</VAR>:</P>
<PRE>
<KBD>mxmldoc *.h *.c &gt;filename.html ENTER</KBD>
</PRE>
<P>You can also specify an XML file to create which contains all of the
information from the source files. For example, the following command
creates an XML file called<VAR> filename.xml</VAR> in addition to the
HTML file:</P>
<PRE>
<KBD>mxmldoc filename.xml *.h *.c &gt;filename.html ENTER</KBD>
</PRE>
<P>The <TT>--no-output</TT> option disables the normal HTML output:</P>
<PRE>
<KBD>mxmldoc --no-output filename.xml *.h *.c ENTER</KBD>
</PRE>
<P>You can then run <TT>mxmldoc</TT> again with the XML file alone to
generate the HTML documentation:</P>
<PRE>
<KBD>mxmldoc filename.xml &gt;filename.html ENTER</KBD>
</PRE>
<P>The <TT>--man filename</TT> option tells <TT>mxmldoc</TT> to create a
man page instead of HTML documentation, for example:</P>
<PRE>
<KBD>mxmldoc --man filename filename.xml \
&gt;filename.man ENTER</KBD>
<KBD>mxmldoc --man filename *.h *.c \
&gt;filename.man ENTER</KBD>
<KBD>mxmldoc --man filename filename.xml *.h *.c \
&gt;filename.man ENTER</KBD>
</PRE>
<H2><A NAME="5_2">Commenting Your Code</A></H2>
<H2><A NAME="5_3">Creating HTML Documentation</A></H2>
<H2><A NAME="5_4">Creating Man Pages</A></H2>
<H2><A NAME="5_5">The XML Schema</A></H2>
<P><I>mxmldoc</I> scans the specified C and C++ source files to produce
an XML representation of globally accessible classes, constants,
enumerations, functions, structures, typedefs, unions, and variables.
The XML file is updated as necessary and a HTML representation of the
XML file is written to the standard output. If no source files are
specified then the current XML file is converted to HTML on the
standard output.</P>
<P>In general, any C or C++ source code is handled by<I> mxmldoc</I>,
however it was specifically written to handle code with documentation
that is formatted according to the CUPS Configuration Management Plan
which is available at &quot;http://www.cups.org/documentation.php&quot;.</P>
<P>As noted previously, <TT>mxmldoc</TT> looks for in-line comments to
describe the functions, types, and constants in your code. <TT>Mxmldoc</TT>
will document all public names it finds in your source files - any
names starting with the underscore character (_) or names that are
documented with the <A HREF="#ATDIRECTIVES">@private@</A> directive are
treated as private and are undocumented.</P>
<P>Comments appearing directly before a function or type definition are
used to document that function or type. Comments appearing after
argument, definition, return type, or variable declarations are used to
document that argument, definition, return type, or variable. For
example, the following code excerpt defines a key/value structure and a
function that creates a new instance of that structure:</P>
<PRE>
/* A key/value pair. This is used with the
dictionary structure. */
struct keyval
{
char *key; /* Key string */
char *val; /* Value string */
};
/* Create a new key/value pair. */
struct keyval * /* New key/value pair */
new_keyval(
const char *key, /* Key string */
const char *val) /* Value string */
{
...
}
</PRE>
<P><TT>Mxmldoc</TT> also knows to remove extra asterisks (*) from the
comment string, so the comment string:</P>
<PRE>
/*
* Compute the value of PI.
*
* The function connects to an Internet server
* that streams audio of mathematical monks
* chanting the first 100 digits of PI.
*/
</PRE>
<P>will be shown as:</P>
<PRE>
Compute the value of PI.
The function connects to an Internet server
that streams audio of mathematical monks
chanting the first 100 digits of PI.
</PRE>
<P><A name="ATDIRECTIVES">Comments</A> can also include the following
special <TT>@name ...@</TT> directive strings:</P>
<UL>
<LI><TT>@deprecated@</TT> - flags the item as deprecated to discourage
its use</LI>
<LI><TT>@private@</TT> - flags the item as private so it will not be
included in the documentation</LI>
<LI><TT>@since ...@</TT> - flags the item as new since a particular
release. The text following the <TT>@since</TT> up to the closing <TT>@</TT>
is highlighted in the generated documentation, e.g. <TT>@since CUPS
1.3@</TT>.</LI>
</UL>
<!-- NEED 10 -->
<H2><A NAME="5_3">Titles, Sections, and Introductions</A></H2>
<P><TT>Mxmldoc</TT> also provides options to set the title, section, and
introduction text for the generated documentation. The <TT>--title text</TT>
option specifies the title for the documentation. The title string is
usually put in quotes:</P>
<PRE>
<KBD>mxmldoc filename.xml \
--title &quot;My Famous Documentation&quot; \
&gt;filename.html ENTER</KBD>
</PRE>
<P>The <TT>--section name</TT> option specifies the section for the
documentation. For HTML documentation, the name is placed in a HTML
comment such as:</P>
<PRE>
&lt;!-- SECTION: name --&gt;
</PRE>
<P>For man pages, the section name is usually just a number (&quot;3&quot;), or a
number followed by a vendor name (&quot;3acme&quot;). The section name is used in
the <TT>.TH</TT> directive in the man page:</P>
<PRE>
.TH mylibrary 3acme &quot;My Title&quot; ...
</PRE>
<P>The default section name for man page output is &quot;3&quot;. There is no
default section name for HTML output.</P>
<P>Finally, the <TT>--intro filename</TT> option specifies a file to
embed after the title and section but before the generated
documentation. For HTML documentation, the file must consist of valid
HTML without the usual <TT>DOCTYPE</TT>, <TT>html</TT>, and <TT>body</TT>
elements. For man page documentation, the file must consist of valid <TT>
nroff(1)</TT> text.</P>
<HR NOSHADE>
<H1 align="right"><A name="LICENSE"><IMG align="right" alt="A" height="100"
hspace="10" src="A.gif" width="100"></A>Mini-XML License</H1>
@ -3461,7 +3583,7 @@ width="80%"><THEAD></THEAD>
<!-- NEW PAGE -->
<H3 class="title"><A name="mxml_attr_s">mxml_attr_s</A></H3>
<H4>Description</H4>
<P>Data types...</P>
<P>An XML element attribute value.</P>
<H4>Definition</H4>
<P> <TT>struct mxml_attr_s
<BR> {
@ -3623,7 +3745,7 @@ width="80%"><THEAD></THEAD>
<!-- NEW PAGE -->
<H3 class="title"><A name="mxml_attr_t">mxml_attr_t</A></H3>
<H4>Description</H4>
<P>Data types...</P>
<P>An XML element attribute value.</P>
<H4>Definition</H4>
<P> <TT>typedef struct <A href="#mxml_attr_s">mxml_attr_s</A>
mxml_attr_t;</TT></P>
@ -3777,5 +3899,196 @@ mxml_node_t</A> *, int);</TT></P>
<TR><TD><TT>real</TT></TD><TD>Real number</TD></TR>
<TR><TD><TT>text</TT></TD><TD>Text fragment</TD></TR>
</TABLE>
</DIV></BODY>
</DIV><HR NOSHADE>
<H1 align="right"><A name="SCHEMA"><IMG align="right" alt="D" height="100"
hspace="10" src="D.gif" width="100"></A>XML Schema</H1>
<P>This appendix provides the XML schema that is used for the XML files
produced by <TT>mxmldoc</TT>. This schema is available on-line at:</P>
<PRE>
http://www.easysw.com/~mike/mxmldoc.xsd
</PRE>
<H2><A NAME="9_1">mxmldoc.xsd</A></H2>
<PRE><SMALL>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;xsd:schema xmlns:xsd=&quot;http://www.w3.org/2001/XMLSchema&quot;&gt;
&lt;xsd:annotation&gt;
&lt;xsd:documentation xml:lang=&quot;en&quot;&gt;
Mini-XML 2.3 documentation schema for mxmldoc output.
Copyright 2003-2007 by Michael Sweet.
&lt;/xsd:documentation&gt;
&lt;/xsd:annotation&gt;
&lt;!-- basic element definitions --&gt;
&lt;xsd:element name=&quot;argument&quot; type=&quot;argumentType&quot;/&gt;
&lt;xsd:element name=&quot;class&quot; type=&quot;classType&quot;/&gt;
&lt;xsd:element name=&quot;constant&quot; type=&quot;constantType&quot;/&gt;
&lt;xsd:element name=&quot;description&quot; type=&quot;xsd:string&quot;/&gt;
&lt;xsd:element name=&quot;enumeration&quot; type=&quot;enumerationType&quot;/&gt;
&lt;xsd:element name=&quot;function&quot; type=&quot;functionType&quot;/&gt;
&lt;xsd:element name=&quot;mxmldoc&quot; type=&quot;mxmldocType&quot;/&gt;
&lt;xsd:element name=&quot;namespace&quot; type=&quot;namespaceType&quot;/&gt;
&lt;xsd:element name=&quot;returnvalue&quot; type=&quot;returnvalueType&quot;/&gt;
&lt;xsd:element name=&quot;seealso&quot; type=&quot;identifierList&quot;/&gt;
&lt;xsd:element name=&quot;struct&quot; type=&quot;structType&quot;/&gt;
&lt;xsd:element name=&quot;typedef&quot; type=&quot;typedefType&quot;/&gt;
&lt;xsd:element name=&quot;type&quot; type=&quot;xsd:string&quot;/&gt;
&lt;xsd:element name=&quot;union&quot; type=&quot;unionType&quot;/&gt;
&lt;xsd:element name=&quot;variable&quot; type=&quot;variableType&quot;/&gt;
&lt;!-- descriptions of complex elements --&gt;
&lt;xsd:complexType name=&quot;argumentType&quot;&gt;
&lt;xsd:sequence&gt;
&lt;xsd:element ref=&quot;type&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;xsd:element ref=&quot;description&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;/xsd:sequence&gt;
&lt;xsd:attribute name=&quot;default&quot; type=&quot;xsd:string&quot; use=&quot;optional&quot;/&gt;
&lt;xsd:attribute name=&quot;name&quot; type=&quot;identifier&quot; use=&quot;required&quot;/&gt;
&lt;xsd:attribute name=&quot;direction&quot; type=&quot;direction&quot; use=&quot;optional&quot;
default=&quot;I&quot;/&gt;
&lt;/xsd:complexType&gt;
&lt;xsd:complexType name=&quot;classType&quot;&gt;
&lt;xsd:sequence&gt;
&lt;xsd:element ref=&quot;description&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;xsd:choice minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot;&gt;
&lt;xsd:element ref=&quot;class&quot;/&gt;
&lt;xsd:element ref=&quot;enumeration&quot;/&gt;
&lt;xsd:element ref=&quot;function&quot;/&gt;
&lt;xsd:element ref=&quot;struct&quot;/&gt;
&lt;xsd:element ref=&quot;typedef&quot;/&gt;
&lt;xsd:element ref=&quot;union&quot;/&gt;
&lt;xsd:element ref=&quot;variable&quot;/&gt;
&lt;/xsd:choice&gt;
&lt;/xsd:sequence&gt;
&lt;xsd:attribute name=&quot;name&quot; type=&quot;identifier&quot; use=&quot;required&quot;/&gt;
&lt;xsd:attribute name=&quot;parent&quot; type=&quot;xsd:string&quot; use=&quot;optional&quot;/&gt;
&lt;/xsd:complexType&gt;
&lt;xsd:complexType name=&quot;constantType&quot;&gt;
&lt;xsd:sequence&gt;
&lt;xsd:element ref=&quot;description&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;/xsd:sequence&gt;
&lt;xsd:attribute name=&quot;name&quot; type=&quot;identifier&quot; use=&quot;required&quot;/&gt;
&lt;/xsd:complexType&gt;
&lt;xsd:complexType name=&quot;enumerationType&quot;&gt;
&lt;xsd:sequence&gt;
&lt;xsd:element ref=&quot;description&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;xsd:element ref=&quot;constant&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;unbounded&quot;/&gt;
&lt;/xsd:sequence&gt;
&lt;xsd:attribute name=&quot;name&quot; type=&quot;identifier&quot; use=&quot;required&quot;/&gt;
&lt;/xsd:complexType&gt;
&lt;xsd:complexType name=&quot;functionType&quot;&gt;
&lt;xsd:sequence&gt;
&lt;xsd:element ref=&quot;returnvalue&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;xsd:element ref=&quot;description&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;xsd:element ref=&quot;argument&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;unbounded&quot;/&gt;
&lt;xsd:element ref=&quot;seealso&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;/xsd:sequence&gt;
&lt;xsd:attribute name=&quot;name&quot; type=&quot;identifier&quot; use=&quot;required&quot;/&gt;
&lt;xsd:attribute name=&quot;scope&quot; type=&quot;scope&quot; use=&quot;optional&quot;/&gt;
&lt;/xsd:complexType&gt;
&lt;xsd:complexType name=&quot;mxmldocType&quot;&gt;
&lt;xsd:choice minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot;&gt;
&lt;xsd:element ref=&quot;class&quot;/&gt;
&lt;xsd:element ref=&quot;enumeration&quot;/&gt;
&lt;xsd:element ref=&quot;function&quot;/&gt;
&lt;xsd:element ref=&quot;namespace&quot;/&gt;
&lt;xsd:element ref=&quot;struct&quot;/&gt;
&lt;xsd:element ref=&quot;typedef&quot;/&gt;
&lt;xsd:element ref=&quot;union&quot;/&gt;
&lt;xsd:element ref=&quot;variable&quot;/&gt;
&lt;/xsd:choice&gt;
&lt;/xsd:complexType&gt;
&lt;xsd:complexType name=&quot;namespaceType&quot;&gt;
&lt;xsd:sequence&gt;
&lt;xsd:element ref=&quot;description&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;xsd:choice minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot;&gt;
&lt;xsd:element ref=&quot;class&quot;/&gt;
&lt;xsd:element ref=&quot;enumeration&quot;/&gt;
&lt;xsd:element ref=&quot;function&quot;/&gt;
&lt;xsd:element ref=&quot;struct&quot;/&gt;
&lt;xsd:element ref=&quot;typedef&quot;/&gt;
&lt;xsd:element ref=&quot;union&quot;/&gt;
&lt;xsd:element ref=&quot;variable&quot;/&gt;
&lt;/xsd:choice&gt;
&lt;/xsd:sequence&gt;
&lt;xsd:attribute name=&quot;name&quot; type=&quot;identifier&quot; use=&quot;required&quot;/&gt;
&lt;/xsd:complexType&gt;
&lt;xsd:complexType name=&quot;returnvalueType&quot;&gt;
&lt;xsd:sequence&gt;
&lt;xsd:element ref=&quot;type&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;xsd:element ref=&quot;description&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;/xsd:sequence&gt;
&lt;/xsd:complexType&gt;
&lt;xsd:complexType name=&quot;structType&quot;&gt;
&lt;xsd:sequence&gt;
&lt;xsd:element ref=&quot;description&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;xsd:choice minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot;&gt;
&lt;xsd:element ref=&quot;variable&quot;/&gt;
&lt;xsd:element ref=&quot;function&quot;/&gt;
&lt;/xsd:choice&gt;
&lt;/xsd:sequence&gt;
&lt;xsd:attribute name=&quot;name&quot; type=&quot;identifier&quot; use=&quot;required&quot;/&gt;
&lt;/xsd:complexType&gt;
&lt;xsd:complexType name=&quot;typedefType&quot;&gt;
&lt;xsd:sequence&gt;
&lt;xsd:element ref=&quot;type&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;xsd:element ref=&quot;description&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;/xsd:sequence&gt;
&lt;xsd:attribute name=&quot;name&quot; type=&quot;identifier&quot; use=&quot;required&quot;/&gt;
&lt;/xsd:complexType&gt;
&lt;xsd:complexType name=&quot;unionType&quot;&gt;
&lt;xsd:sequence&gt;
&lt;xsd:element ref=&quot;description&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;xsd:element ref=&quot;variable&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot;/&gt;
&lt;/xsd:sequence&gt;
&lt;xsd:attribute name=&quot;name&quot; type=&quot;identifier&quot; use=&quot;required&quot;/&gt;
&lt;/xsd:complexType&gt;
&lt;xsd:complexType name=&quot;variableType&quot;&gt;
&lt;xsd:sequence&gt;
&lt;xsd:element ref=&quot;type&quot; minOccurs=&quot;1&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;xsd:element ref=&quot;description&quot; minOccurs=&quot;0&quot; maxOccurs=&quot;1&quot;/&gt;
&lt;/xsd:sequence&gt;
&lt;xsd:attribute name=&quot;name&quot; type=&quot;identifier&quot; use=&quot;required&quot;/&gt;
&lt;/xsd:complexType&gt;
&lt;!-- data types --&gt;
&lt;xsd:simpleType name=&quot;direction&quot;&gt;
&lt;xsd:restriction base=&quot;xsd:string&quot;&gt;
&lt;xsd:enumeration value=&quot;I&quot;/&gt;
&lt;xsd:enumeration value=&quot;O&quot;/&gt;
&lt;xsd:enumeration value=&quot;IO&quot;/&gt;
&lt;/xsd:restriction&gt;
&lt;/xsd:simpleType&gt;
&lt;xsd:simpleType name=&quot;identifier&quot;&gt;
&lt;xsd:restriction base=&quot;xsd:string&quot;&gt;
&lt;xsd:pattern value=&quot;[a-zA-Z_(.]([a-zA-Z_(.,)* 0-9])*&quot;/&gt;
&lt;/xsd:restriction&gt;
&lt;/xsd:simpleType&gt;
&lt;xsd:simpleType name=&quot;identifierList&quot;&gt;
&lt;xsd:list itemType=&quot;identifier&quot;/&gt;
&lt;/xsd:simpleType&gt;
&lt;xsd:simpleType name=&quot;scope&quot;&gt;
&lt;xsd:restriction base=&quot;xsd:string&quot;&gt;
&lt;xsd:enumeration value=&quot;&quot;/&gt;
&lt;xsd:enumeration value=&quot;private&quot;/&gt;
&lt;xsd:enumeration value=&quot;protected&quot;/&gt;
&lt;xsd:enumeration value=&quot;public&quot;/&gt;
&lt;/xsd:restriction&gt;
&lt;/xsd:simpleType&gt;
&lt;/xsd:schema&gt;
</SMALL></PRE>
</BODY>
</HTML>

Loading…
Cancel
Save