After Width: | Height: | Size: 4.6 KiB |
After Width: | Height: | Size: 2.7 KiB |
After Width: | Height: | Size: 4.0 KiB |
After Width: | Height: | Size: 4.3 KiB |
After Width: | Height: | Size: 3.3 KiB |
After Width: | Height: | Size: 4.0 KiB |
After Width: | Height: | Size: 4.6 KiB |
After Width: | Height: | Size: 3.3 KiB |
After Width: | Height: | Size: 4.8 KiB |
After Width: | Height: | Size: 4.7 KiB |
After Width: | Height: | Size: 4.0 KiB |
After Width: | Height: | Size: 3.8 KiB |
After Width: | Height: | Size: 4.5 KiB |
After Width: | Height: | Size: 3.9 KiB |
After Width: | Height: | Size: 2.2 KiB |
After Width: | Height: | Size: 2.1 KiB |
After Width: | Height: | Size: 17 KiB |
After Width: | Height: | Size: 5.7 KiB |
Before Width: | Height: | Size: 35 KiB |
@ -1,10 +0,0 @@ |
|||||||
#HTMLDOC 1.8.27.1 |
|
||||||
-t pdf14 -f "mxml-pocket.pdf" --book --toclevels 3 --no-numbered --toctitle "Table of Contents" --title --titleimage "title.html" --linkstyle plain --size 4.25x6.875in --left 0.750in --right 0.50in --top 0.50in --bottom 0.50in --header .t. --header1 ... --footer h.1 --nup 1 --tocheader .t. --tocfooter ..i --duplex --portrait --color --no-pscommands --no-xrxcomments --compression=9 --jpeg=95 --fontsize 9.0 --fontspacing 1.2 --headingfont Helvetica --bodyfont Helvetica --headfootsize 8.0 --headfootfont Helvetica-Oblique --charset iso-8859-1 --links --no-embedfonts --pagemode outline --pagelayout single --firstpage c1 --pageeffect none --pageduration 10 --effectduration 1.0 --no-encryption --permissions all --owner-password "" --user-password "" --browserwidth 680 --no-strict --no-overflow |
|
||||||
intro.html |
|
||||||
install.html |
|
||||||
basics.html |
|
||||||
advanced.html |
|
||||||
mxmldoc.html |
|
||||||
license.html |
|
||||||
relnotes.html |
|
||||||
refapp.html |
|
@ -1,43 +1,192 @@ |
|||||||
<html> |
<html> |
||||||
<body> |
<body> |
||||||
|
|
||||||
<h1 align='right'><a name='MXMLDOC'>4 - Using the mxmldoc |
<h1 align='right'><a name='MXMLDOC'><img src="4.gif" align="right" |
||||||
Utility</a></h1> |
hspace="10" width="100" height="100" alt="4"></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>The Basics</h2> |
<h2>The Basics</h2> |
||||||
|
|
||||||
<p>Originally developed to generate the Mini-XML and CUPS API |
<p>Originally developed to generate the Mini-XML and CUPS API |
||||||
documentation, the <tt>mxmldoc(1)</tt> program converts C and C++ |
documentation, <tt>mxmldoc</tt> is now a general-purpose utility |
||||||
source files into an intermediate XML format and uses in-line |
which scans C and C++ source files to produce HTML and man page |
||||||
comments rather than comment headers to annotate functions, types, |
documentation along with an XML file representing the functions, |
||||||
and constants.</p> |
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> |
||||||
|
|
||||||
<p></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>Commenting Your Code</h2> |
<h2>Commenting Your Code</h2> |
||||||
|
|
||||||
<h2>Creating HTML Documentation</h2> |
<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>Titles, Sections, and Introductions</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> |
||||||
|
|
||||||
<h2>Creating Man Pages</h2> |
<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> |
||||||
|
|
||||||
<h2>The XML Schema</h2> |
<pre> |
||||||
|
.TH mylibrary 3acme "My Title" ... |
||||||
|
</pre> |
||||||
|
|
||||||
<p><i>mxmldoc</i> scans the specified C and C++ source files to |
<p>The default section name for man page output is "3". There is no |
||||||
produce an XML representation of globally accessible classes, |
default section name for HTML output.</p> |
||||||
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>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>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> |
||||||
|
|
||||||
</body> |
</body> |
||||||
</html> |
</html> |
||||||
|
@ -1,9 +1,11 @@ |
|||||||
<html> |
<html> |
||||||
<body> |
<body> |
||||||
|
|
||||||
<h1 align='right'><a name='REFERENCE'>C - Library Reference</a></h1> |
<h1 align='right'><a name='REFERENCE'><img src="C.gif" align="right" |
||||||
|
hspace="10" width="100" height="100" alt="C"></a>Library |
||||||
|
Reference</h1> |
||||||
|
|
||||||
<embed src='reference.html'/> |
<embed src='reference.html'> |
||||||
|
|
||||||
</body> |
</body> |
||||||
</html> |
</html> |
||||||
|
@ -0,0 +1,201 @@ |
|||||||
|
<html> |
||||||
|
<body> |
||||||
|
|
||||||
|
<h1 align='right'><a name='SCHEMA'><img src="D.gif" align="right" |
||||||
|
hspace="10" width="100" height="100" alt="D"></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 _hd_omit_toc>mxmldoc.xsd</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> |
Before Width: | Height: | Size: 3.6 KiB After Width: | Height: | Size: 3.6 KiB |
Before Width: | Height: | Size: 1.8 KiB |
Before Width: | Height: | Size: 35 KiB |