Michael R Sweet
17 years ago
parent
0a79a46ac3
commit
463a190a55
Binary file not shown.
|
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 |
Binary file not shown.
@ -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 |
||||
File diff suppressed because it is too large
Load Diff
@ -1,43 +1,192 @@ |
||||
<html> |
||||
<body> |
||||
|
||||
<h1 align='right'><a name='MXMLDOC'>4 - Using the mxmldoc |
||||
Utility</a></h1> |
||||
<h1 align='right'><a name='MXMLDOC'><img src="4.gif" align="right" |
||||
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> |
||||
|
||||
<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> |
||||
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> |
||||
|
||||
<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>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 |
||||
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>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>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> |
||||
|
||||
</body> |
||||
</html> |
||||
|
||||
@ -1,9 +1,11 @@ |
||||
<html> |
||||
<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> |
||||
</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 |
Binary file not shown.
Loading…
Reference in new issue