mirror of
https://github.com/michaelrsweet/mxml.git
synced 2024-11-08 13:39:58 +00:00
Documentation updates.
This commit is contained in:
Michael R Sweet
parent
08896f33e5
commit
40db9196f3
@ -2,5 +2,6 @@
|
||||
*.bak
|
||||
mxml.0
|
||||
mxml.3
|
||||
mxml.d
|
||||
mxmldoc.0
|
||||
mxmldoc.1
|
||||
|
||||
29
doc/makedocs.sh
Executable file
29
doc/makedocs.sh
Executable file
@ -0,0 +1,29 @@
|
||||
#!/bin/sh
|
||||
#
|
||||
# "$Id: makedocs.sh,v 1.1 2004/05/03 03:21:16 mike Exp $"
|
||||
#
|
||||
# Script to make documentation...
|
||||
#
|
||||
# Copyright 2003-2004 by Michael Sweet.
|
||||
#
|
||||
# This program is free software; you can redistribute it and/or
|
||||
# modify it under the terms of the GNU Library General Public
|
||||
# License as published by the Free Software Foundation; either
|
||||
# version 2, or (at your option) any later version.
|
||||
#
|
||||
# This program is distributed in the hope that it will be useful,
|
||||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
# GNU General Public License for more details.
|
||||
#
|
||||
|
||||
htmldoc --verbose --batch mxml.book -f mxml.pdf
|
||||
htmldoc --verbose --batch mxml.book -f mxml.html
|
||||
|
||||
rm -rf mxml.d
|
||||
mkdir mxml.d
|
||||
htmldoc --verbose --batch mxml.book -t htmlsep -d mxml.d
|
||||
|
||||
#
|
||||
# End of "$Id: makedocs.sh,v 1.1 2004/05/03 03:21:16 mike Exp $".
|
||||
#
|
||||
872
doc/mxml.html
872
doc/mxml.html
@ -1,7 +1,9 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<TITLE>Documentation</TITLE>
|
||||
<TITLE>Mini-XML Programmers Manual, Version 2.0</TITLE>
|
||||
<META NAME="author" CONTENT="Michael Sweet">
|
||||
<META NAME="copyright" CONTENT="Copyright 2003-2004">
|
||||
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-iso-8859-1">
|
||||
<STYLE TYPE="text/css"><!--
|
||||
BODY { font-family: serif }
|
||||
@ -17,22 +19,60 @@ PRE { font-family: monospace }
|
||||
--></STYLE>
|
||||
</HEAD>
|
||||
<BODY>
|
||||
<CENTER><A HREF="#CONTENTS"><H1>Documentation</H1></A><BR>
|
||||
<CENTER><A HREF="#CONTENTS"><H1>Mini-XML Programmers Manual, Version 2.0</H1></A><BR>
|
||||
Michael Sweet<BR>
|
||||
Copyright 2003-2004<BR>
|
||||
</CENTER>
|
||||
<HR>
|
||||
<H1 ALIGN="CENTER"><A NAME="CONTENTS">Table of Contents</A></H1>
|
||||
<BR>
|
||||
<BR><B><A HREF="#INTRO">Introduction</A></B>
|
||||
<BR>
|
||||
<BR><B><A HREF="#INSTALL">1 - Building and Installing Mini-XML</A></B>
|
||||
<BR>
|
||||
<BR><B><A HREF="#BASICS">2 - Getting Started with Mini-XML</A></B>
|
||||
<BR>
|
||||
<BR><B><A HREF="#ADVANCED">3 - More Mini-XML Programming Techniques</A></B>
|
||||
<BR>
|
||||
<BR><B><A HREF="#MXMLDOC">3 - Using the mxmldoc Utility</A></B>
|
||||
<BR>
|
||||
<BR><B><A HREF="#LICENSE">A - GNU Library General Public License</A></B>
|
||||
<UL>
|
||||
<LI><A HREF="#1_1">Legal Stuff</A></LI>
|
||||
<LI><A HREF="#1_2">History</A></LI>
|
||||
<LI><A HREF="#1_3">Organization of This Document</A></LI>
|
||||
<LI><A HREF="#1_4">Notation Conventions</A></LI>
|
||||
<LI><A HREF="#1_5">Abbreviations</A></LI>
|
||||
<LI><A HREF="#1_6">Other References</A></LI>
|
||||
</UL>
|
||||
<B><A HREF="#INSTALL">1 - Building, Installing, and Packaging Mini-XML</A>
|
||||
</B>
|
||||
<UL>
|
||||
<LI><A HREF="#2_1">Compiling Mini-XML</A></LI>
|
||||
<LI><A HREF="#2_2">Installing Mini-XML</A></LI>
|
||||
<LI><A HREF="#2_3">Creating Mini-XML Packages</A></LI>
|
||||
</UL>
|
||||
<B><A HREF="#BASICS">2 - Getting Started with Mini-XML</A></B>
|
||||
<UL>
|
||||
<LI><A HREF="#3_1">The Basics</A></LI>
|
||||
<LI><A HREF="#3_2">Nodes</A></LI>
|
||||
<LI><A HREF="#3_3">Loading and Saving XML Files</A></LI>
|
||||
<UL>
|
||||
<LI><A HREF="#3_3_1">Finding and Iterating Nodes</A></LI>
|
||||
</UL>
|
||||
</UL>
|
||||
<B><A HREF="#ADVANCED">3 - More Mini-XML Programming Techniques</A></B>
|
||||
<UL>
|
||||
<LI><A HREF="#4_1">Load Callbacks</A></LI>
|
||||
<LI><A HREF="#4_2">Save Callbacks</A></LI>
|
||||
<LI><A HREF="#4_3">Changing Node Values</A></LI>
|
||||
<LI><A HREF="#4_4">Formatted Text</A></LI>
|
||||
<LI><A HREF="#4_5">Indexing</A></LI>
|
||||
</UL>
|
||||
<B><A HREF="#MXMLDOC">4 - Using the mxmldoc Utility</A></B>
|
||||
<UL>
|
||||
<LI><A HREF="#5_1">The Basics</A></LI>
|
||||
<LI><A HREF="#5_2">Code Documentation Conventions</A></LI>
|
||||
<UL>
|
||||
<LI><A HREF="#5_2_1">Functions and Methods</A></LI>
|
||||
<LI><A HREF="#5_2_2">Variables and Class/Structure/Union Members</A></LI>
|
||||
<LI><A HREF="#5_2_3">Types</A></LI>
|
||||
<LI><A HREF="#5_2_4">Classes, Structures, and Unions</A></LI>
|
||||
<LI><A HREF="#5_2_5">Enumerations</A></LI>
|
||||
</UL>
|
||||
<LI><A HREF="#5_3">XML Schema</A></LI>
|
||||
</UL>
|
||||
<B><A HREF="#LICENSE">A - GNU Library General Public License</A></B>
|
||||
<BR>
|
||||
<BR><B><A HREF="#RELNOTES">B - Release Notes</A></B>
|
||||
<UL>
|
||||
@ -109,19 +149,814 @@ PRE { font-family: monospace }
|
||||
</UL>
|
||||
<HR>
|
||||
<H1 align="right"><A name="INTRO">Introduction</A></H1>
|
||||
<HR>
|
||||
<H1 align="right"><A name="INSTALL">1 - Building and Installing Mini-XML</A>
|
||||
</H1>
|
||||
<P>This programmers manual describes Mini-XML version 2.0, a small XML
|
||||
parsing library that you can use to read and write XML and XML-like
|
||||
data files in your application without requiring large non-standard
|
||||
libraries. Mini-XML only requires an ANSI C compatible compiler (GCC
|
||||
works, as do most vendors' ANSI C compilers) and a "make" program.</P>
|
||||
<P>Mini-XML provides the following functionality:</P>
|
||||
<UL>
|
||||
<LI>Reading of UTF-8 and UTF-16 encoded XML files and strings.</LI>
|
||||
<LI>Writing of UTF-8 encoded XML files and strings.</LI>
|
||||
<LI>Data is stored in a linked-list tree structure, preserving the XML
|
||||
data hierarchy.</LI>
|
||||
<LI>Supports arbitrary element names, attributes, and attribute values
|
||||
with no preset limits, just available memory.</LI>
|
||||
<LI>Supports integer, real, opaque ("cdata"), and text data types in
|
||||
"leaf" nodes.</LI>
|
||||
<LI>Functions for creating and managing trees of data.</LI>
|
||||
<LI>"Find" and "walk" functions for easily locating and navigating trees
|
||||
of data.</LI>
|
||||
</UL>
|
||||
<P>Mini-XML doesn't do validation or other types of processing on the
|
||||
data based upon schema files or other sources of definition
|
||||
information, nor does it support character entities other than those
|
||||
required by the XML specification.</P>
|
||||
|
||||
<!-- NEED 4in -->
|
||||
<H2><A NAME="1_1">Legal Stuff</A></H2>
|
||||
<P>The Mini-XML library is copyright 2003-2004 by Michael Sweet.</P>
|
||||
<P>This library is free software; you can redistribute it and/or modify
|
||||
it under the terms of the <A href="#LICENSE">GNU Library General Public
|
||||
License</A> as published by the Free Software Foundation; either
|
||||
version 2 of the License, or (at your option) any later version.</P>
|
||||
<P>This library is distributed in the hope that it will be useful, but
|
||||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||||
Library General Public License for more details.</P>
|
||||
|
||||
<!-- NEED 4in -->
|
||||
<H2><A NAME="1_2">History</A></H2>
|
||||
<P>Mini-XML was initially developed for the <A href="http://gimp-print.sf.net/">
|
||||
Gimp-Print</A> project to replace the rather large and unwieldy <TT>
|
||||
libxml2</TT> library with something substantially smaller and
|
||||
easier-to-use. It all began one morning in June of 2003 when Robert
|
||||
posted the following sentence to the developer's list:</P>
|
||||
<BLOCKQUOTE>It's bad enough that we require libxml2, but rolling our own
|
||||
XML parser is a bit more than we can handle.</BLOCKQUOTE>
|
||||
<P>I then replied with:</P>
|
||||
<BLOCKQUOTE>Given the limited scope of what you use in XML, it should be
|
||||
trivial to code a mini-XML API in a few hundred lines of code.</BLOCKQUOTE>
|
||||
<P>I took my own challenge and coded furiously for two days to produced
|
||||
the initial public release of Mini-XML, total lines of code: 696.
|
||||
Robert promptly integrated Mini-XML into Gimp-Print and removed
|
||||
libxml2.</P>
|
||||
<P>Thanks to lots of feedback and support from various developers,
|
||||
Mini-XML has evolved since then to provide a more complete XML
|
||||
implementation and now stands at a whopping 2,240 lines of code,
|
||||
compared to 96,335 lines of code for libxml2 version 2.6.9. Aside from
|
||||
Gimp-Print, Mini-XML is used for the following projects/software
|
||||
applications:</P>
|
||||
<UL>
|
||||
<LI><A href="http://www.cups.org/">Common UNIX Printing System</A></LI>
|
||||
<LI><A href="http://www.cups.org/ddk.php">CUPS Driver Development Kit</A>
|
||||
</LI>
|
||||
<LI><A href="http://www.easysw.com/printpro/">ESP Print Pro</A></LI>
|
||||
<LI><A href="http://zynaddsubfx.sourceforge.net">ZynAddSubFX</A></LI>
|
||||
</UL>
|
||||
<P>Please email me (mxml @ easysw . com) if you would like your project
|
||||
added or removed from this list, or if you have any comments/quotes you
|
||||
would like me to publish about your experiences with Mini-XML.</P>
|
||||
|
||||
<!-- NEED 3in -->
|
||||
<H2><A NAME="1_3">Organization of This Document</A></H2>
|
||||
<P>This manual is organized into the following chapters and appendices:</P>
|
||||
<UL>
|
||||
<LI>Chapter 1, "<A href="#INSTALL">Building, Installing, and Packaging
|
||||
Mini-XML</A>", provides compilation, installation, and packaging
|
||||
instructions for Mini-XML.</LI>
|
||||
<LI>Chapter 2, "<A href="#BASICS">Getting Started with Mini-XML</A>",
|
||||
shows how to use the Mini-XML library in your programs.</LI>
|
||||
<LI>Chapter 3, "<A href="#ADVANCED">More Mini-XML Programming Techniques</A>
|
||||
", shows additional ways to use the Mini-XML library.</LI>
|
||||
<LI>Chapter 4, "<A href="#MXMLDOC">Using the mxmldoc Utility</A>",
|
||||
describes how to use the <TT>mxmldoc(1)</TT> program to generate
|
||||
software documentation.</LI>
|
||||
<LI>Appendix A, "<A href="#LICENSE">GNU Library General Public License</A>
|
||||
", provides the terms and conditions for using and distributing
|
||||
Mini-XML.</LI>
|
||||
<LI>Appendix B, "<A href="#RELNOTES">Release Notes</A>", lists the
|
||||
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>
|
||||
</UL>
|
||||
|
||||
<!-- NEED 4in -->
|
||||
<H2><A NAME="1_4">Notation Conventions</A></H2>
|
||||
<P>Various font and syntax conventions are used in this guide. Examples
|
||||
and their meanings and uses are explained below:</P>
|
||||
<CENTER>
|
||||
<TABLE width="80%">
|
||||
<TR><TH>Example</TH><TD> </TD><TH>Description</TH></TR>
|
||||
<TR><TD colspan="3"> </TD></TR>
|
||||
<TR valign="top"><TD><CODE>lpstat</CODE>
|
||||
<BR /> <CODE>lpstat(1)</CODE></TD><TD> </TD><TD>The names of commands;
|
||||
the first mention of a command or function in a chapter is followed by
|
||||
a manual page section number.</TD></TR>
|
||||
<TR><TD colspan="3"> </TD></TR>
|
||||
<TR valign="top"><TD><VAR>/var</VAR>
|
||||
<BR /><VAR> /usr/share/cups/data/testprint.ps</VAR></TD><TD> </TD><TD>
|
||||
File and directory names.</TD></TR>
|
||||
<TR><TD colspan="3"> </TD></TR>
|
||||
<TR valign="top"><TD nowrap><TT>Request ID is Printer-123</TT></TD><TD>
|
||||
</TD><TD>Screen output.</TD></TR>
|
||||
<TR><TD colspan="3"> </TD></TR>
|
||||
<TR valign="top"><TD nowrap><KBD>lp -d printer filename ENTER</KBD></TD><TD>
|
||||
</TD><TD>Literal user input; special keys like <KBD>ENTER</KBD> are
|
||||
in ALL CAPS.</TD></TR>
|
||||
<TR><TD colspan="3"> </TD></TR>
|
||||
<TR valign="top"><TD>12.3</TD><TD> </TD><TD>Numbers in the text are
|
||||
written using the period (.) to indicate the decimal point.</TD></TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
|
||||
<!-- NEED 4in -->
|
||||
<H2><A NAME="1_5">Abbreviations</A></H2>
|
||||
<P>The following abbreviations are used throughout this manual:</P>
|
||||
<BLOCKQUOTE>
|
||||
<DL>
|
||||
<DT>Gb</DT>
|
||||
<DD>Gigabytes, or 1073741824 bytes
|
||||
<BR /> </DD>
|
||||
<DT>kb</DT>
|
||||
<DD>Kilobytes, or 1024 bytes
|
||||
<BR /> </DD>
|
||||
<DT>Mb</DT>
|
||||
<DD>Megabytes, or 1048576 bytes
|
||||
<BR /> </DD>
|
||||
<DT>UTF-8, UTF-16</DT>
|
||||
<DD>Unicode Transformation Format, 8-bit or 16-bit
|
||||
<BR /> </DD>
|
||||
<DT>W3C</DT>
|
||||
<DD>World Wide Web Consortium
|
||||
<BR /> </DD>
|
||||
<DT>XML</DT>
|
||||
<DD>Extensible Markup Language
|
||||
<BR /> </DD>
|
||||
</DL>
|
||||
</BLOCKQUOTE>
|
||||
<H2><A NAME="1_6">Other References</A></H2>
|
||||
<BLOCKQUOTE>
|
||||
<DL>
|
||||
<DT>The Unicode Standard, Version 4.0, Addison-Wesley, ISBN
|
||||
0-321-18578-1</DT>
|
||||
<DD>The definition of the Unicode character set which is used for XML.
|
||||
<BR /> </DD>
|
||||
<DT><A href="http://www.w3.org/TR/2004/REC-xml-20040204/">Extensible
|
||||
Markup Language (XML) 1.0 (Third Edition)</A></DT>
|
||||
<DD>The XML specification from the World Wide Web Consortium (W3C)
|
||||
<BR /> </DD>
|
||||
</DL>
|
||||
</BLOCKQUOTE><HR>
|
||||
<H1 align="right"><A name="INSTALL">1 - Building, Installing, and
|
||||
Packaging Mini-XML</A></H1>
|
||||
<P>This chapter describes how to build, install, and package Mini-XML on
|
||||
your system.</P>
|
||||
<H2><A NAME="2_1">Compiling Mini-XML</A></H2>
|
||||
<P>Mini-XML comes with an autoconf-based configure script; just type the
|
||||
following command to get things going:</P>
|
||||
<PRE>
|
||||
<KBD>./configure ENTER</KBD>
|
||||
</PRE>
|
||||
<P>The default install prefix is<VAR> /usr/local</VAR>, which can be
|
||||
overridden using the <KBD>--prefix</KBD> option:</P>
|
||||
<PRE>
|
||||
<KBD>./configure --prefix=/foo ENTER</KBD>
|
||||
</PRE>
|
||||
<P>Other configure options can be found using the <KBD>--help</KBD>
|
||||
option:</P>
|
||||
<PRE>
|
||||
<KBD>./configure --help ENTER</KBD>
|
||||
</PRE>
|
||||
<P>Once you have configured the software, use the <TT>make(1)</TT>
|
||||
program to do the build and run the test program to verify that things
|
||||
are working, as follows:</P>
|
||||
<PRE>
|
||||
<KBD>make ENTER</KBD>
|
||||
</PRE>
|
||||
<H2><A NAME="2_2">Installing Mini-XML</A></H2>
|
||||
<P>Use the <TT>make</TT> command with the <KBD>install</KBD> target to
|
||||
install Mini-XML in the configured directories:</P>
|
||||
<PRE>
|
||||
<KBD>make install ENTER</KBD>
|
||||
</PRE>
|
||||
<H2><A NAME="2_3">Creating Mini-XML Packages</A></H2>
|
||||
<P>Mini-XML includes two files that can be used to create binary
|
||||
packages. The first file is<VAR> mxml.spec</VAR> which is used by the <TT>
|
||||
rpmbuild(8)</TT> software to create Red Hat Package Manager ("RPM")
|
||||
packages which are commonly used on Linux. Since <TT>rpmbuild</TT>
|
||||
wants to compile the software on its own, you can provide it with the
|
||||
Mini-XML tar file to build the package:</P>
|
||||
<PRE>
|
||||
<KBD>rpmbuild -ta mxml-<I>version</I>.tar.gz ENTER</KBD>
|
||||
</PRE>
|
||||
<P>The second file is<VAR> mxml.list</VAR> which is used by the <TT>
|
||||
epm(1)</TT> program to create software packages in a variety of formats.
|
||||
The <TT>epm</TT> program is available from the following URL:</P>
|
||||
<PRE>
|
||||
<A href="http://www.easysw.com/epm/">http://www.easysw.com/epm/</A>
|
||||
</PRE>
|
||||
<P>Use the <TT>make</TT> command with the <KBD>epm</KBD> target to
|
||||
create portable and native packages for your system:</P>
|
||||
<PRE>
|
||||
<KBD>make epm ENTER</KBD>
|
||||
</PRE>
|
||||
<P>The packages are stored in a subdirectory named<VAR> dist</VAR> for
|
||||
your convenience. The portable packages utilize scripts and tar files
|
||||
to install the software on the target system; this is especially useful
|
||||
when installing on systems with different Linux distributions. Use the<VAR>
|
||||
mxml.install</VAR> script to install the software and<VAR> mxml.remove</VAR>
|
||||
script to remove the software.</P>
|
||||
<P>The native packages will be in the local OS's native format: RPM for
|
||||
Red Hat Linux, DPKG for Debian Linux, PKG for Solaris, and so forth.
|
||||
Use the corresponding commands to install the native packages.</P>
|
||||
<HR>
|
||||
<H1 align="right"><A name="BASICS">2 - Getting Started with Mini-XML</A></H1>
|
||||
<P>This chapter describes how to write programs that use Mini-XML to
|
||||
access data in an XML file.</P>
|
||||
<H2><A NAME="3_1">The Basics</A></H2>
|
||||
<P>Mini-XML provides a single header file which you include:</P>
|
||||
<PRE>
|
||||
#include <mxml.h>
|
||||
</PRE>
|
||||
<P>The Mini-XML library is included with your program using the <KBD>
|
||||
-lmxml</KBD> option:</P>
|
||||
<PRE>
|
||||
<KBD>gcc -o myprogram myprogram.c -lmxml ENTER</KBD>
|
||||
</PRE>
|
||||
<P>If you have the <TT>pkg-config(1)</TT> software installed, you can
|
||||
use it to determine the proper compiler and linker options for your
|
||||
installation:</P>
|
||||
<PRE>
|
||||
<KBD>pkg-config --cflags mxml ENTER</KBD>
|
||||
<KBD>pkg-config --libs mxml ENTER</KBD>
|
||||
</PRE>
|
||||
<H2><A NAME="3_2">Nodes</A></H2>
|
||||
<P>Every piece of information in an XML file (elements, text, numbers)
|
||||
is stored in memory in "nodes". Nodes are defined by the <A href="#mxml_node_t">
|
||||
<TT>mxml_node_t</TT></A> structure. The <A href="#mxml_type_t"><TT>type</TT>
|
||||
</A> member defines the node type (element, integer, opaque, real, or
|
||||
text) which determines which value you want to look at in the <A href="#mxml_value_t">
|
||||
<TT>value</TT></A> union.</P>
|
||||
<P>New nodes can be created using the <A href="#mxmlNewElement"><TT>
|
||||
mxmlNewElement()</TT></A>, <A href="#mxmlNewInteger"><TT>
|
||||
mxmlNewInteger()</TT></A>, <A href="#mxmlNewOpaque"><TT>mxmlNewOpaque()</TT>
|
||||
</A>, <A href="#mxmlNewReal"><TT>mxmlNewReal()</TT></A>, and <A href="#mxmlNewText">
|
||||
<TT>mxmlNewText()</TT></A> functions. Only elements can have child
|
||||
nodes, and the top node must be an element, usually "?xml".</P>
|
||||
<P>Each node has pointers for the node above (<TT>parent</TT>), below (<TT>
|
||||
child</TT>), to the left (<TT>prev</TT>), and to the right (<TT>next</TT>
|
||||
) of the current node. If you have an XML file like the following:</P>
|
||||
<PRE>
|
||||
<?xml version="1.0"?>
|
||||
<data>
|
||||
<node>val1</node>
|
||||
<node>val2</node>
|
||||
<node>val3</node>
|
||||
<group>
|
||||
<node>val4</node>
|
||||
<node>val5</node>
|
||||
<node>val6</node>
|
||||
</group>
|
||||
<node>val7</node>
|
||||
<node>val8</node>
|
||||
<node>val9</node>
|
||||
</data>
|
||||
</PRE>
|
||||
<P>the node tree returned by <TT>mxmlLoadFile()</TT> would look like the
|
||||
following in memory:</P>
|
||||
<PRE>
|
||||
?xml
|
||||
|
|
||||
data
|
||||
|
|
||||
node - node - node - group - node - node - node
|
||||
| | | | | | |
|
||||
val1 val2 val3 | val7 val8 val9
|
||||
|
|
||||
node - node - node
|
||||
| | |
|
||||
val4 val5 val6
|
||||
</PRE>
|
||||
<P>where "-" is a pointer to the next node and "|" is a pointer to the
|
||||
first child node.</P>
|
||||
<P>Once you are done with the XML data, use the <A href="#mxmlDelete"><TT>
|
||||
mxmlDelete()</TT></A> function to recursively free the memory that is
|
||||
used for a particular node or the entire tree:</P>
|
||||
<PRE>
|
||||
mxmlDelete(tree);
|
||||
</PRE>
|
||||
<H2><A NAME="3_3">Loading and Saving XML Files</A></H2>
|
||||
<P>You load an XML file using the <A href="#mxmlLoadFile"><TT>
|
||||
mxmlLoadFile()</TT></A> function:</P>
|
||||
<PRE>
|
||||
FILE *fp;
|
||||
<A href="#mxml_node_t">mxml_node_t</A> *tree;
|
||||
|
||||
fp = fopen("filename.xml", "r");
|
||||
tree = <A href="#mxmlLoadFile">mxmlLoadFile</A>(NULL, fp, MXML_NO_CALLBACK);
|
||||
fclose(fp);
|
||||
</PRE>
|
||||
<P>The third argument specifies a callback function which returns the
|
||||
value type of the immediate children for a new element node: <TT>
|
||||
MXML_INTEGER</TT>, <TT>MXML_OPAQUE</TT>, <TT>MXML_REAL</TT>, or <TT>
|
||||
MXML_TEXT</TT>. This function is called<I> after</I> the element and its
|
||||
attributes have been read, so you can look at the element name,
|
||||
attributes, and attribute values to determine the proper value type to
|
||||
return. The default value type is MXML_TEXT if no callback is used.</P>
|
||||
<P>Similarly, you save an XML file using the <A href="#mxmlSaveFile"><TT>
|
||||
mxmlSaveFile()</TT></A> function:</P>
|
||||
<PRE>
|
||||
FILE *fp;
|
||||
<A href="#mxml_node_t">mxml_node_t</A> *tree;
|
||||
|
||||
fp = fopen("filename.xml", "w");
|
||||
<A href="#mxmlSaveFile">mxmlSaveFile</A>(tree, fp, MXML_NO_CALLBACK);
|
||||
fclose(fp);
|
||||
</PRE>
|
||||
<P>Callback functions for saving are used to optionally insert
|
||||
whitespace before and after elements in the node tree. Your function
|
||||
will be called up to four times for each element node with a pointer to
|
||||
the node and a "where" value of <TT>MXML_WS_BEFORE_OPEN</TT>, <TT>
|
||||
MXML_WS_AFTER_OPEN</TT>, <TT>MXML_WS_BEFORE_CLOSE</TT>, or <TT>
|
||||
MXML_WS_AFTER_CLOSE</TT>. The callback function should return <TT>NULL</TT>
|
||||
if no whitespace should be added and the string to insert (spaces,
|
||||
tabs, carriage returns, and newlines) otherwise.</P>
|
||||
<P>The <A href="#mxmlLoadString"><TT>mxmlLoadString()</TT></A>, <A href="#mxmlSaveAllocString">
|
||||
<TT>mxmlSaveAllocString()</TT></A>, and <A href="#mxmlSaveString"><TT>
|
||||
mxmlSaveString()</TT></A> functions load XML node trees from and save
|
||||
XML node trees to strings:</P>
|
||||
<PRE>
|
||||
char buffer[8192];
|
||||
char *ptr;
|
||||
<A href="#mxml_node_t">mxml_node_t</A> *tree;
|
||||
|
||||
...
|
||||
tree = <A href="#mxmlLoadString">mxmlLoadString</A>(NULL, buffer, MXML_NO_CALLBACK);
|
||||
|
||||
...
|
||||
<A href="#mxmlSaveString">mxmlSaveString</A>(tree, buffer, sizeof(buffer), MXML_NO_CALLBACK);
|
||||
|
||||
...
|
||||
ptr = <A href="#mxmlSaveAllocString">mxmlSaveAllocString</A>(tree, MXML_NO_CALLBACK);
|
||||
</PRE>
|
||||
<H3><A NAME="3_3_1">Finding and Iterating Nodes</A></H3>
|
||||
<P>The <A href="#mxmlWalkPrev"><TT>mxmlWalkPrev()</TT></A> and <A href="#mxmlWalkNext">
|
||||
<TT>mxmlWalkNext()</TT></A>functions can be used to iterate through the
|
||||
XML node tree:</P>
|
||||
<PRE>
|
||||
<A href="#mxml_node_t">mxml_node_t</A> *node = <A href="#mxmlWalkPrev">mxmlWalkPrev</A>(current, tree, MXML_DESCEND);
|
||||
|
||||
<A href="#mxml_node_t">mxml_node_t</A> *node = <A href="#mxmlWalkNext">mxmlWalkNext</A>(current, tree, MXML_DESCEND);
|
||||
</PRE>
|
||||
<P>In addition, you can find a named element/node using the <A href="#mxmlFindElement">
|
||||
<TT>mxmlFindElement()</TT></A> function:</P>
|
||||
<PRE>
|
||||
<A href="#mxml_node_t">mxml_node_t</A> *node = <A href="#mxmlFindElement">mxmlFindElement</A>(tree, tree, "name", "attr",
|
||||
"value", MXML_DESCEND);
|
||||
</PRE>
|
||||
<P>The <TT>name</TT>, <TT>attr</TT>, and <TT>value</TT> arguments can be
|
||||
passed as <TT>NULL</TT> to act as wildcards, e.g.:</P>
|
||||
<PRE>
|
||||
/* Find the first "a" element */
|
||||
node = <A href="#mxmlFindElement">mxmlFindElement</A>(tree, tree, "a", NULL, NULL, MXML_DESCEND);
|
||||
|
||||
/* Find the first "a" element with "href" attribute */
|
||||
node = <A href="#mxmlFindElement">mxmlFindElement</A>(tree, tree, "a", "href", NULL, MXML_DESCEND);
|
||||
|
||||
/* Find the first "a" element with "href" to a URL */
|
||||
node = <A href="#mxmlFindElement">mxmlFindElement</A>(tree, tree, "a", "href",
|
||||
"http://www.easysw.com/~mike/mxml/", MXML_DESCEND);
|
||||
|
||||
/* Find the first element with a "src" attribute*/
|
||||
node = <A href="#mxmlFindElement">mxmlFindElement</A>(tree, tree, NULL, "src", NULL, MXML_DESCEND);
|
||||
|
||||
/* Find the first element with a "src" = "foo.jpg" */
|
||||
node = <A href="#mxmlFindElement">mxmlFindElement</A>(tree, tree, NULL, "src", "foo.jpg", MXML_DESCEND);
|
||||
</PRE>
|
||||
<P>You can also iterate with the same function:</P>
|
||||
<PRE>
|
||||
<A href="#mxml_node_t">mxml_node_t</A> *node;
|
||||
|
||||
for (node = <A href="#mxmlFindElement">mxmlFindElement</A>(tree, tree, "name", NULL, NULL, MXML_DESCEND);
|
||||
node != NULL;
|
||||
node = <A href="#mxmlFindElement">mxmlFindElement</A>(node, tree, "name", NULL, NULL, MXML_DESCEND))
|
||||
{
|
||||
... do something ...
|
||||
}
|
||||
</PRE>
|
||||
<P>The <TT>MXML_DESCEND</TT> argument can actually be one of three
|
||||
constants:</P>
|
||||
<UL>
|
||||
<LI><TT>MXML_NO_DESCEND</TT> means to not to look at any child nodes in
|
||||
the element hierarchy, just look at siblings at the same level or
|
||||
parent nodes until the top node or top-of-tree is reached. The previous
|
||||
node from "group" would be the "node" element to the left, while the
|
||||
next node from "group" would be the "node" element to the right.</LI>
|
||||
<LI><TT>MXML_DESCEND_FIRST</TT> means that it is OK to descend to the
|
||||
first child of a node, but not to descend further when searching.
|
||||
You'll normally use this when iterating through direct children of a
|
||||
parent node, e.g. all of the "node" elements under the "?xml" parent
|
||||
node in the example above. This mode is only applicable to the search
|
||||
function; the walk functions treat this as <TT>MXML_DESCEND</TT> since
|
||||
every call is a first time.</LI>
|
||||
<LI><TT>MXML_DESCEND</TT> means to keep descending until you hit the
|
||||
bottom of the tree. The previous node from "group" would be the "val3"
|
||||
node and the next node would be the first node element under "group".
|
||||
If you were to walk from the root node "?xml" to the end of the tree
|
||||
with <TT>mxmlWalkNext()</TT>, the order would be:
|
||||
<PRE>
|
||||
?xml
|
||||
data
|
||||
node
|
||||
val1
|
||||
node
|
||||
val2
|
||||
node
|
||||
val3
|
||||
group
|
||||
node
|
||||
val4
|
||||
node
|
||||
val5
|
||||
node
|
||||
val6
|
||||
node
|
||||
val7
|
||||
node
|
||||
val8
|
||||
node
|
||||
val9
|
||||
</PRE>
|
||||
<P>If you started at "val9" and walked using <TT>mxmlWalkPrev()</TT>,
|
||||
the order would be reversed, ending at "?xml".</P>
|
||||
</LI>
|
||||
</UL>
|
||||
<HR>
|
||||
<H1 align="right"><A name="ADVANCED">3 - More Mini-XML Programming
|
||||
Techniques</A></H1>
|
||||
<P>This chapter shows additional ways to use the Mini-XML library in
|
||||
your programs.</P>
|
||||
<H2><A NAME="4_1">Load Callbacks</A></H2>
|
||||
<H2><A NAME="4_2">Save Callbacks</A></H2>
|
||||
<H2><A NAME="4_3">Changing Node Values</A></H2>
|
||||
<H2><A NAME="4_4">Formatted Text</A></H2>
|
||||
<H2><A NAME="4_5">Indexing</A></H2>
|
||||
<HR>
|
||||
<H1 align="right"><A name="MXMLDOC">3 - Using the mxmldoc Utility</A></H1>
|
||||
<H1 align="right"><A name="MXMLDOC">4 - Using the mxmldoc Utility</A></H1>
|
||||
<P>This chapter describes how to use the <TT>mxmldoc(1)</TT> utility
|
||||
that comes with Mini-XML to automatically generate documentation for
|
||||
your programs.</P>
|
||||
<H2><A NAME="5_1">The Basics</A></H2>
|
||||
<P>The <TT>mxmldoc</TT> utility scans C and C++ source and header files
|
||||
and produces an XML file describing the library interface and an XHTML
|
||||
file providing a human-readable reference to the code. Each source and
|
||||
header file must conform to some simple code commenting conventions so
|
||||
that <TT>mxmldoc</TT> can extract the necessary descriptive text.</P>
|
||||
<P>The <TT>mxmldoc</TT> command requires the name of an XML file to
|
||||
store the code information; this file is created and updated as
|
||||
necessary. The XML file is optionally followed by a list of source
|
||||
files to scan. After scanning any source files on the command-line, <TT>
|
||||
mxmldoc</TT> writes XHTML documentation to the standard output, which
|
||||
can be redirected to the file using the <KBD>>filename</KBD> syntax:</P>
|
||||
<PRE>
|
||||
<KBD>mxmldoc myfile.xml >myfile.html ENTER</KBD>
|
||||
<KBD>mxmldoc myfile.xml file1.c file2.cxx file3.h >myfile.html ENTER</KBD>
|
||||
</PRE>
|
||||
<P>If no source files are provided on the command-line, the current
|
||||
contents of the XML file are converted to XHTML.</P>
|
||||
<H2><A NAME="5_2">Code Documentation Conventions</A></H2>
|
||||
<P>As noted previously, source code must be commented properly for <TT>
|
||||
mxmldoc</TT> to generate correct documentation for the code. Single line
|
||||
comments can use the C++ <TT>//</TT> comment sequence, however all
|
||||
multi-line comments must use the C <TT>/* ... */</TT> comment sequence.</P>
|
||||
<H3><A NAME="5_2_1">Functions and Methods</A></H3>
|
||||
<P>All implementations of functions and methods must begin with a
|
||||
comment header describing what the function does, the possible input
|
||||
limits (if any), and the possible output values (if any), and any
|
||||
special information needed, as follows:</P>
|
||||
<PRE>
|
||||
/*
|
||||
* 'do_this()' - Compute y = this(x).
|
||||
*
|
||||
* Notes: none.
|
||||
*/
|
||||
|
||||
float /* O - Inverse power value, 0.0 <= y <= 1.1 */
|
||||
do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */
|
||||
{
|
||||
...
|
||||
return (y);
|
||||
}
|
||||
</PRE>
|
||||
<P>Return/output values are indicated using an "O" prefix, input values
|
||||
are indicated using the "I" prefix, and values that are both input and
|
||||
output use the "IO" prefix for the corresponding in-line comment.</P>
|
||||
<H3><A NAME="5_2_2">Variables and Class/Structure/Union Members</A></H3>
|
||||
<P>Each variable or member must be declared on a separate line and must
|
||||
be immediately followed by a comment describing the variable or member,
|
||||
as follows:</P>
|
||||
<PRE>
|
||||
int this_variable; /* The current state of this */
|
||||
int that_variable; /* The current state of that */
|
||||
</PRE>
|
||||
<H3><A NAME="5_2_3">Types</A></H3>
|
||||
<P>Each type must have a comment block immediately before the typedef,
|
||||
as follows:</P>
|
||||
<PRE>
|
||||
/*
|
||||
* This type is for foobar options.
|
||||
*/
|
||||
typedef int this_type_t;
|
||||
</PRE>
|
||||
|
||||
<!-- NEED 5in -->
|
||||
<H3><A NAME="5_2_4">Classes, Structures, and Unions</A></H3>
|
||||
<P>Each class, structure, and union must have a comment block
|
||||
immediately before the definition, and each member must be documented
|
||||
in accordance with the function and variable documentation
|
||||
requirements, as follows:</P>
|
||||
<PRE>
|
||||
/*
|
||||
* This structure is for foobar options.
|
||||
*/
|
||||
struct this_struct_s
|
||||
{
|
||||
int this_member; /* Current state for this */
|
||||
int that_member; /* Current state for that */
|
||||
};
|
||||
|
||||
/*
|
||||
* This class is for barfoo options.
|
||||
*/
|
||||
class this_class_c
|
||||
{
|
||||
int this_member; /* Current state for this */
|
||||
int that_member; /* Current state for that */
|
||||
|
||||
/*
|
||||
* 'get_this()' - Get the current state for this.
|
||||
*/
|
||||
int /* O - Current state for this */
|
||||
get_this()
|
||||
{
|
||||
return (this_member);
|
||||
}
|
||||
};
|
||||
</PRE>
|
||||
<H3><A NAME="5_2_5">Enumerations</A></H3>
|
||||
<P>Each enumeration must have a comment block immediately before the
|
||||
definition describing what the enumeration is for, and each enumeration
|
||||
value must have a comment immediately after the value, as follows:</P>
|
||||
<PRE>
|
||||
/*
|
||||
* Enumeration of media trays.
|
||||
*/
|
||||
enum this_enum_e
|
||||
{
|
||||
THIS_TRAY, /* This tray */
|
||||
THAT_TRAY /* That tray */
|
||||
};
|
||||
</PRE>
|
||||
|
||||
<!-- NEW PAGE -->
|
||||
<H2><A NAME="5_3">XML Schema</A></H2>
|
||||
<P>Listing 4-1 shows the XML schema file<VAR> mxmldoc.xsd</VAR> which is
|
||||
included with Mini-XML. This schema file can be used to convert the XML
|
||||
files produced by <TT>mxmldoc</TT> into other formats.</P>
|
||||
<CENTER>
|
||||
<TABLE bgcolor="#cccccc" border="1" cellpadding="5" cellspacing="0"><CAPTION
|
||||
align="bottom"><I> Listing 4-1, XML Schema File "mxmldoc.xsd"</I></CAPTION>
|
||||
<TR><TD>
|
||||
<PRE>
|
||||
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
|
||||
<xsd:annotation>
|
||||
<xsd:documentation xml:lang="en">
|
||||
Mini-XML 2.0 documentation schema for mxmldoc output.
|
||||
Copyright 2003-2004 by Michael Sweet.
|
||||
|
||||
This program is free software; you can redistribute it and/or
|
||||
modify it under the terms of the GNU Library General Public
|
||||
License as published by the Free Software Foundation; either
|
||||
version 2, or (at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
</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"/>
|
||||
</PRE>
|
||||
</TD></TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
|
||||
<!-- NEW PAGE -->
|
||||
<CENTER>
|
||||
<TABLE bgcolor="#cccccc" border="1" cellpadding="5" cellspacing="0"><CAPTION
|
||||
align="bottom"><I> Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)</I>
|
||||
</CAPTION>
|
||||
<TR><TD>
|
||||
<PRE>
|
||||
<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"/>
|
||||
</PRE>
|
||||
</TD></TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
|
||||
<!-- NEW PAGE -->
|
||||
<CENTER>
|
||||
<TABLE bgcolor="#cccccc" border="1" cellpadding="5" cellspacing="0"><CAPTION
|
||||
align="bottom"><I> Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)</I>
|
||||
</CAPTION>
|
||||
<TR><TD>
|
||||
<PRE>
|
||||
<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>
|
||||
</PRE>
|
||||
</TD></TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
|
||||
<!-- NEW PAGE -->
|
||||
<CENTER>
|
||||
<TABLE bgcolor="#cccccc" border="1" cellpadding="5" cellspacing="0"><CAPTION
|
||||
align="bottom"><I> Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)</I>
|
||||
</CAPTION>
|
||||
<TR><TD>
|
||||
<PRE>
|
||||
</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>
|
||||
</PRE>
|
||||
</TD></TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
<HR>
|
||||
<H1 align="right"><A name="LICENSE">A - GNU Library General Public
|
||||
License</A></H1>
|
||||
@ -502,10 +1337,13 @@ PRE { font-family: monospace }
|
||||
<H1 align="right"><A name="RELNOTES">B - Release Notes</A></H1>
|
||||
<H2><A NAME="7_1">Changes in Mini-XML 2.0</A></H2>
|
||||
<UL>
|
||||
<LI>New programmers manual.</LI>
|
||||
<LI>The mxmldoc utility now produces XML output which conforms to an
|
||||
updated XML schema, described in the file "doc/mxmldoc.xsd".</LI>
|
||||
<LI>Changed the whitespace callback interface to return strings instead
|
||||
of a single character, allowing for greater control over the formatting
|
||||
of XML files written using Mini-XML. THIS CHANGE WILL REQUIRE CHANGES
|
||||
TO YOUR CODE IF YOU USE WHITESPACE CALLBACKS.</LI>
|
||||
TO YOUR 1.x CODE IF YOU USE WHITESPACE CALLBACKS.</LI>
|
||||
<LI>The mxmldoc utility is now capable of documenting C++ classes,
|
||||
functions, and structures, and correctly handles C++ comments.</LI>
|
||||
<LI>Added new modular tests for mxmldoc.</LI>
|
||||
|
||||
BIN
doc/mxml.pdf
BIN
doc/mxml.pdf
Binary file not shown.
414
doc/mxmldoc.html
414
doc/mxmldoc.html
@ -13,68 +13,366 @@ documentation for your programs.</p>
|
||||
<p>The <tt>mxmldoc</tt> utility scans C and C++ source and
|
||||
header files and produces an XML file describing the library
|
||||
interface and an XHTML file providing a human-readable reference
|
||||
to the code.</p>
|
||||
to the code. Each source and header file must conform to some
|
||||
simple code commenting conventions so that <tt>mxmldoc</tt> can
|
||||
extract the necessary descriptive text.</p>
|
||||
|
||||
<h2>XML Schema</h2>
|
||||
|
||||
<p>The following poor-man's schema describes the format of the
|
||||
XML files produced by <tt>mxmldoc</tt>:
|
||||
<p>The <tt>mxmldoc</tt> command requires the name of an XML file
|
||||
to store the code information; this file is created and updated
|
||||
as necessary. The XML file is optionally followed by a list of
|
||||
source files to scan. After scanning any source files on the
|
||||
command-line, <tt>mxmldoc</tt> writes XHTML documentation to the
|
||||
standard output, which can be redirected to the file using the
|
||||
<kbd>>filename</kbd> syntax:</p>
|
||||
|
||||
<pre>
|
||||
<?xml version="1.0"?>
|
||||
<namespace name=""> [optional...]
|
||||
<constant name="">
|
||||
<description>descriptive text</description>
|
||||
</constant>
|
||||
|
||||
<enumeration name="">
|
||||
<constant name="">...</constant>
|
||||
</enumeration>
|
||||
|
||||
<typedef name="">
|
||||
<description>descriptive text</description>
|
||||
<type>type string</type>
|
||||
</typedef>
|
||||
|
||||
<function name="" scope="">
|
||||
<description>descriptive text</description>
|
||||
<argument name="" direction="I|O|IO" default="">
|
||||
<description>descriptive text</description>
|
||||
<type>type string</type>
|
||||
</argument>
|
||||
<returnvalue>
|
||||
<description>descriptive text</description>
|
||||
<type>type string</type>
|
||||
</returnvalue>
|
||||
<seealso>function names separated by spaces</seealso>
|
||||
</function>
|
||||
|
||||
<variable name="" scope="">
|
||||
<description>descriptive text</description>
|
||||
<type>type string</type>
|
||||
</variable>
|
||||
|
||||
<struct name="">
|
||||
<description>descriptive text</description>
|
||||
<variable name="">...</variable>
|
||||
<function name="">...</function>
|
||||
</struct>
|
||||
|
||||
<union name="">
|
||||
<description>descriptive text</description>
|
||||
<variable name="">...</variable>
|
||||
</union>
|
||||
|
||||
<class name="" parent="">
|
||||
<description>descriptive text</description>
|
||||
<class name="">...</class>
|
||||
<enumeration name="">...</enumeration>
|
||||
<function name="">...</function>
|
||||
<struct name="">...</struct>
|
||||
<variable name="">...</variable>
|
||||
</class>
|
||||
</namespace>
|
||||
<kbd>mxmldoc myfile.xml >myfile.html ENTER</kbd>
|
||||
<kbd>mxmldoc myfile.xml file1.c file2.cxx file3.h >myfile.html ENTER</kbd>
|
||||
</pre>
|
||||
|
||||
<p>If no source files are provided on the command-line, the
|
||||
current contents of the XML file are converted to XHTML.</p>
|
||||
|
||||
<h2>Code Documentation Conventions</h2>
|
||||
|
||||
<p>As noted previously, source code must be commented properly
|
||||
for <tt>mxmldoc</tt> to generate correct documentation for the
|
||||
code. Single line comments can use the C++ <tt>//</tt> comment
|
||||
sequence, however all multi-line comments must use the C <tt>/*
|
||||
... */</tt> comment sequence.</p>
|
||||
|
||||
<h3>Functions and Methods</h3>
|
||||
|
||||
<p>All implementations of functions and methods must begin with
|
||||
a comment header describing what the function does, the possible
|
||||
input limits (if any), and the possible output values (if any),
|
||||
and any special information needed, as follows:</p>
|
||||
|
||||
<pre>
|
||||
/*
|
||||
* 'do_this()' - Compute y = this(x).
|
||||
*
|
||||
* Notes: none.
|
||||
*/
|
||||
|
||||
float /* O - Inverse power value, 0.0 <= y <= 1.1 */
|
||||
do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */
|
||||
{
|
||||
...
|
||||
return (y);
|
||||
}
|
||||
</pre>
|
||||
|
||||
<p>Return/output values are indicated using an "O" prefix, input
|
||||
values are indicated using the "I" prefix, and values that are
|
||||
both input and output use the "IO" prefix for the corresponding
|
||||
in-line comment.</p>
|
||||
|
||||
<h3>Variables and Class/Structure/Union Members</h3>
|
||||
|
||||
<p>Each variable or member must be declared on a separate line
|
||||
and must be immediately followed by a comment describing the
|
||||
variable or member, as follows:</p>
|
||||
|
||||
<pre>
|
||||
int this_variable; /* The current state of this */
|
||||
int that_variable; /* The current state of that */
|
||||
</pre>
|
||||
|
||||
<h3>Types</h3>
|
||||
|
||||
<p>Each type must have a comment block immediately before the
|
||||
typedef, as follows:</p>
|
||||
|
||||
<pre>
|
||||
/*
|
||||
* This type is for foobar options.
|
||||
*/
|
||||
typedef int this_type_t;
|
||||
</pre>
|
||||
|
||||
<!-- NEED 5in -->
|
||||
<h3>Classes, Structures, and Unions</h3>
|
||||
|
||||
<p>Each class, structure, and union must have a comment block
|
||||
immediately before the definition, and each member must be documented
|
||||
in accordance with the function and variable documentation
|
||||
requirements, as follows:</p>
|
||||
|
||||
<pre>
|
||||
/*
|
||||
* This structure is for foobar options.
|
||||
*/
|
||||
struct this_struct_s
|
||||
{
|
||||
int this_member; /* Current state for this */
|
||||
int that_member; /* Current state for that */
|
||||
};
|
||||
|
||||
/*
|
||||
* This class is for barfoo options.
|
||||
*/
|
||||
class this_class_c
|
||||
{
|
||||
int this_member; /* Current state for this */
|
||||
int that_member; /* Current state for that */
|
||||
|
||||
/*
|
||||
* 'get_this()' - Get the current state for this.
|
||||
*/
|
||||
int /* O - Current state for this */
|
||||
get_this()
|
||||
{
|
||||
return (this_member);
|
||||
}
|
||||
};
|
||||
</pre>
|
||||
|
||||
<h3>Enumerations</h3>
|
||||
|
||||
<p>Each enumeration must have a comment block immediately before
|
||||
the definition describing what the enumeration is for, and each
|
||||
enumeration value must have a comment immediately after the
|
||||
value, as follows:</p>
|
||||
|
||||
<pre>
|
||||
/*
|
||||
* Enumeration of media trays.
|
||||
*/
|
||||
enum this_enum_e
|
||||
{
|
||||
THIS_TRAY, /* This tray */
|
||||
THAT_TRAY /* That tray */
|
||||
};
|
||||
</pre>
|
||||
|
||||
<!-- NEW PAGE -->
|
||||
<h2>XML Schema</h2>
|
||||
|
||||
<p>Listing 4-1 shows the XML schema file <var>mxmldoc.xsd</var>
|
||||
which is included with Mini-XML. This schema file can be used to
|
||||
convert the XML files produced by <tt>mxmldoc</tt> into other
|
||||
formats.</p>
|
||||
|
||||
<center><table border='1' bgcolor='#cccccc' cellpadding='5' cellspacing='0'>
|
||||
<caption align='bottom'><i>Listing 4-1, XML Schema File "mxmldoc.xsd"</i></caption>
|
||||
<tr><td>
|
||||
<pre>
|
||||
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
|
||||
<xsd:annotation>
|
||||
<xsd:documentation xml:lang="en">
|
||||
Mini-XML 2.0 documentation schema for mxmldoc output.
|
||||
Copyright 2003-2004 by Michael Sweet.
|
||||
|
||||
This program is free software; you can redistribute it and/or
|
||||
modify it under the terms of the GNU Library General Public
|
||||
License as published by the Free Software Foundation; either
|
||||
version 2, or (at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
</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"/>
|
||||
</pre>
|
||||
</td></tr>
|
||||
</table></center>
|
||||
<!-- NEW PAGE -->
|
||||
<center><table border='1' bgcolor='#cccccc' cellpadding='5' cellspacing='0'>
|
||||
<caption align='bottom'><i>Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)</i></caption>
|
||||
<tr><td>
|
||||
<pre>
|
||||
<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"/>
|
||||
</pre>
|
||||
</td></tr>
|
||||
</table></center>
|
||||
<!-- NEW PAGE -->
|
||||
<center><table border='1' bgcolor='#cccccc' cellpadding='5' cellspacing='0'>
|
||||
<caption align='bottom'><i>Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)</i></caption>
|
||||
<tr><td>
|
||||
<pre>
|
||||
<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>
|
||||
</pre>
|
||||
</td></tr>
|
||||
</table></center>
|
||||
<!-- NEW PAGE -->
|
||||
<center><table border='1' bgcolor='#cccccc' cellpadding='5' cellspacing='0'>
|
||||
<caption align='bottom'><i>Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)</i></caption>
|
||||
<tr><td>
|
||||
<pre>
|
||||
</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>
|
||||
</pre>
|
||||
</td></tr>
|
||||
</table></center>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user