mirror of
https://github.com/michaelrsweet/mxml.git
synced 2024-11-08 13:39:58 +00:00
Update docos.
This commit is contained in:
Michael R Sweet
parent
92abe20fb4
commit
7d8801c7dd
@ -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
|
||||
|
||||
|
||||
363
doc/mxml.html
363
doc/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, "<A href="#REFERENCE">Library Reference</A>", contains a
|
||||
complete reference for Mini-XML, generated by <TT>mxmldoc</TT>.</LI>
|
||||
<LI>Appendix D, "<A href="#SCHEMA">XML Schema</A>", 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 "natural" 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 >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 >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 >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 \
|
||||
>filename.man ENTER</KBD>
|
||||
|
||||
<KBD>mxmldoc --man filename *.h *.c \
|
||||
>filename.man ENTER</KBD>
|
||||
|
||||
<KBD>mxmldoc --man filename filename.xml *.h *.c \
|
||||
>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 "http://www.cups.org/documentation.php".</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 "My Famous Documentation" \
|
||||
>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>
|
||||
<!-- SECTION: name -->
|
||||
</PRE>
|
||||
<P>For man pages, the section name is usually just a number ("3"), or a
|
||||
number followed by a vendor name ("3acme"). The section name is used in
|
||||
the <TT>.TH</TT> directive in the man page:</P>
|
||||
<PRE>
|
||||
.TH mylibrary 3acme "My Title" ...
|
||||
</PRE>
|
||||
<P>The default section name for man page output is "3". 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>
|
||||
<?xml version="1.0"?>
|
||||
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
|
||||
<xsd:annotation>
|
||||
<xsd:documentation xml:lang="en">
|
||||
Mini-XML 2.3 documentation schema for mxmldoc output.
|
||||
Copyright 2003-2007 by Michael Sweet.
|
||||
</xsd:documentation>
|
||||
</xsd:annotation>
|
||||
|
||||
<!-- basic element definitions -->
|
||||
<xsd:element name="argument" type="argumentType"/>
|
||||
<xsd:element name="class" type="classType"/>
|
||||
<xsd:element name="constant" type="constantType"/>
|
||||
<xsd:element name="description" type="xsd:string"/>
|
||||
<xsd:element name="enumeration" type="enumerationType"/>
|
||||
<xsd:element name="function" type="functionType"/>
|
||||
<xsd:element name="mxmldoc" type="mxmldocType"/>
|
||||
<xsd:element name="namespace" type="namespaceType"/>
|
||||
<xsd:element name="returnvalue" type="returnvalueType"/>
|
||||
<xsd:element name="seealso" type="identifierList"/>
|
||||
<xsd:element name="struct" type="structType"/>
|
||||
<xsd:element name="typedef" type="typedefType"/>
|
||||
<xsd:element name="type" type="xsd:string"/>
|
||||
<xsd:element name="union" type="unionType"/>
|
||||
<xsd:element name="variable" type="variableType"/>
|
||||
|
||||
<!-- descriptions of complex elements -->
|
||||
<xsd:complexType name="argumentType">
|
||||
<xsd:sequence>
|
||||
<xsd:element ref="type" minOccurs="1" maxOccurs="1"/>
|
||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
|
||||
</xsd:sequence>
|
||||
<xsd:attribute name="default" type="xsd:string" use="optional"/>
|
||||
<xsd:attribute name="name" type="identifier" use="required"/>
|
||||
<xsd:attribute name="direction" type="direction" use="optional"
|
||||
default="I"/>
|
||||
</xsd:complexType>
|
||||
|
||||
<xsd:complexType name="classType">
|
||||
<xsd:sequence>
|
||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
|
||||
<xsd:choice minOccurs="0" maxOccurs="unbounded">
|
||||
<xsd:element ref="class"/>
|
||||
<xsd:element ref="enumeration"/>
|
||||
<xsd:element ref="function"/>
|
||||
<xsd:element ref="struct"/>
|
||||
<xsd:element ref="typedef"/>
|
||||
<xsd:element ref="union"/>
|
||||
<xsd:element ref="variable"/>
|
||||
</xsd:choice>
|
||||
</xsd:sequence>
|
||||
<xsd:attribute name="name" type="identifier" use="required"/>
|
||||
<xsd:attribute name="parent" type="xsd:string" use="optional"/>
|
||||
</xsd:complexType>
|
||||
|
||||
<xsd:complexType name="constantType">
|
||||
<xsd:sequence>
|
||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
|
||||
</xsd:sequence>
|
||||
<xsd:attribute name="name" type="identifier" use="required"/>
|
||||
</xsd:complexType>
|
||||
|
||||
<xsd:complexType name="enumerationType">
|
||||
<xsd:sequence>
|
||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
|
||||
<xsd:element ref="constant" minOccurs="1" maxOccurs="unbounded"/>
|
||||
</xsd:sequence>
|
||||
<xsd:attribute name="name" type="identifier" use="required"/>
|
||||
</xsd:complexType>
|
||||
|
||||
<xsd:complexType name="functionType">
|
||||
<xsd:sequence>
|
||||
<xsd:element ref="returnvalue" minOccurs="0" maxOccurs="1"/>
|
||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
|
||||
<xsd:element ref="argument" minOccurs="1" maxOccurs="unbounded"/>
|
||||
<xsd:element ref="seealso" minOccurs="0" maxOccurs="1"/>
|
||||
</xsd:sequence>
|
||||
<xsd:attribute name="name" type="identifier" use="required"/>
|
||||
<xsd:attribute name="scope" type="scope" use="optional"/>
|
||||
</xsd:complexType>
|
||||
|
||||
<xsd:complexType name="mxmldocType">
|
||||
<xsd:choice minOccurs="0" maxOccurs="unbounded">
|
||||
<xsd:element ref="class"/>
|
||||
<xsd:element ref="enumeration"/>
|
||||
<xsd:element ref="function"/>
|
||||
<xsd:element ref="namespace"/>
|
||||
<xsd:element ref="struct"/>
|
||||
<xsd:element ref="typedef"/>
|
||||
<xsd:element ref="union"/>
|
||||
<xsd:element ref="variable"/>
|
||||
</xsd:choice>
|
||||
</xsd:complexType>
|
||||
|
||||
<xsd:complexType name="namespaceType">
|
||||
<xsd:sequence>
|
||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
|
||||
<xsd:choice minOccurs="0" maxOccurs="unbounded">
|
||||
<xsd:element ref="class"/>
|
||||
<xsd:element ref="enumeration"/>
|
||||
<xsd:element ref="function"/>
|
||||
<xsd:element ref="struct"/>
|
||||
<xsd:element ref="typedef"/>
|
||||
<xsd:element ref="union"/>
|
||||
<xsd:element ref="variable"/>
|
||||
</xsd:choice>
|
||||
</xsd:sequence>
|
||||
<xsd:attribute name="name" type="identifier" use="required"/>
|
||||
</xsd:complexType>
|
||||
|
||||
<xsd:complexType name="returnvalueType">
|
||||
<xsd:sequence>
|
||||
<xsd:element ref="type" minOccurs="1" maxOccurs="1"/>
|
||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
|
||||
</xsd:sequence>
|
||||
</xsd:complexType>
|
||||
|
||||
<xsd:complexType name="structType">
|
||||
<xsd:sequence>
|
||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
|
||||
<xsd:choice minOccurs="0" maxOccurs="unbounded">
|
||||
<xsd:element ref="variable"/>
|
||||
<xsd:element ref="function"/>
|
||||
</xsd:choice>
|
||||
</xsd:sequence>
|
||||
<xsd:attribute name="name" type="identifier" use="required"/>
|
||||
</xsd:complexType>
|
||||
|
||||
<xsd:complexType name="typedefType">
|
||||
<xsd:sequence>
|
||||
<xsd:element ref="type" minOccurs="1" maxOccurs="1"/>
|
||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
|
||||
</xsd:sequence>
|
||||
<xsd:attribute name="name" type="identifier" use="required"/>
|
||||
</xsd:complexType>
|
||||
|
||||
<xsd:complexType name="unionType">
|
||||
<xsd:sequence>
|
||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
|
||||
<xsd:element ref="variable" minOccurs="0" maxOccurs="unbounded"/>
|
||||
</xsd:sequence>
|
||||
<xsd:attribute name="name" type="identifier" use="required"/>
|
||||
</xsd:complexType>
|
||||
|
||||
<xsd:complexType name="variableType">
|
||||
<xsd:sequence>
|
||||
<xsd:element ref="type" minOccurs="1" maxOccurs="1"/>
|
||||
<xsd:element ref="description" minOccurs="0" maxOccurs="1"/>
|
||||
</xsd:sequence>
|
||||
<xsd:attribute name="name" type="identifier" use="required"/>
|
||||
</xsd:complexType>
|
||||
|
||||
<!-- data types -->
|
||||
<xsd:simpleType name="direction">
|
||||
<xsd:restriction base="xsd:string">
|
||||
<xsd:enumeration value="I"/>
|
||||
<xsd:enumeration value="O"/>
|
||||
<xsd:enumeration value="IO"/>
|
||||
</xsd:restriction>
|
||||
</xsd:simpleType>
|
||||
|
||||
<xsd:simpleType name="identifier">
|
||||
<xsd:restriction base="xsd:string">
|
||||
<xsd:pattern value="[a-zA-Z_(.]([a-zA-Z_(.,)* 0-9])*"/>
|
||||
</xsd:restriction>
|
||||
</xsd:simpleType>
|
||||
|
||||
<xsd:simpleType name="identifierList">
|
||||
<xsd:list itemType="identifier"/>
|
||||
</xsd:simpleType>
|
||||
|
||||
<xsd:simpleType name="scope">
|
||||
<xsd:restriction base="xsd:string">
|
||||
<xsd:enumeration value=""/>
|
||||
<xsd:enumeration value="private"/>
|
||||
<xsd:enumeration value="protected"/>
|
||||
<xsd:enumeration value="public"/>
|
||||
</xsd:restriction>
|
||||
</xsd:simpleType>
|
||||
</xsd:schema>
|
||||
</SMALL></PRE>
|
||||
</BODY>
|
||||
</HTML>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user