AIR/mxml
1
0
Fork 0
mirror of https://github.com/michaelrsweet/mxml.git synced 2025-02-22 02:05:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Switch to codedoc-generated documentation. Remove all old HTML docs.

Browse Source
This commit is contained in:
Michael R Sweet 2019-01-02 22:54:23 -05:00
parent 3e0c8eaa0e
commit bc27547035
No known key found for this signature in database
GPG Key ID: 999559A027815955
22 changed files with 1943 additions and 6861 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGES.md
View File

@ -1,4 +1,4 @@
# Changes in Mini-XML CURRENT
# Changes in Mini-XML 2.13
- Fixed a potential buffer overflow when writing floating point data
(Issue #233)

34
Makefile.in
View File

@ -331,33 +331,25 @@ testmxml.o: mxml.h
#
# mxml.xml (depends on separate codedoc utility)
# Documentation (depends on separate codedoc utility)
#
mxml.xml: mxml.h $(PUBLIBOBJS:.o=.c) \
doc/body.man doc/footer.man \
doc/reference.header
.PHONY: doc
doc: mxml.h $(PUBLIBOBJS:.o=.c) \
doc/body.md doc/body.man doc/footer.man \
doc/mxml-cover.png
echo Generating API documentation...
$(RM) mxml.xml
codedoc --header doc/reference.header \
--docversion @VERSION@ --author "Michael R Sweet" \
--copyright "Copyright 2003-2019, All Rights Reserved." \
--title "Mini-XML API Reference" \
mxml.xml mxml.h $(PUBLIBOBJS:.o=.c) >doc/reference.html
codedoc --man mxml --title "Mini-XML API" \
--body doc/body.man --footer doc/footer.man \
mxml.xml >doc/mxml.man
#
# mxml.epub (depends on separate codedoc utility)
#
mxml.epub: mxml.xml doc/body.md doc/mxml-cover.png
echo Generating EPUB API documentation...
codedoc --body doc/body.md \
--coverimage doc/mxml-cover.png \
--epub mxml.epub mxml.xml
mxml.xml mxml.h $(PUBLIBOBJS:.o=.c) >doc/mxml.html
codedoc --body doc/body.md \
--coverimage doc/mxml-cover.png \
--epub doc/mxml.epub mxml.xml
codedoc --man mxml --title "Mini-XML API" \
--body doc/body.man --footer doc/footer.man \
mxml.xml >doc/mxml.3
$(RM) mxml.xml
#

20
configure vendored
View File

@ -1,6 +1,6 @@
#! /bin/sh
# Guess values for system-dependent variables and create Makefiles.
# Generated by GNU Autoconf 2.69 for Mini-XML 2.12.
# Generated by GNU Autoconf 2.69 for Mini-XML 2.13.
#
# Report bugs to <https://github.com/michaelrsweet/mxml/issues>.
#
@ -580,8 +580,8 @@ MAKEFLAGS=
# Identity of this package.
PACKAGE_NAME='Mini-XML'
PACKAGE_TARNAME='mxml'
PACKAGE_VERSION='2.12'
PACKAGE_STRING='Mini-XML 2.12'
PACKAGE_VERSION='2.13'
PACKAGE_STRING='Mini-XML 2.13'
PACKAGE_BUGREPORT='https://github.com/michaelrsweet/mxml/issues'
PACKAGE_URL='https://michaelrsweet.github.io/mxml'
@ -1268,7 +1268,7 @@ if test "$ac_init_help" = "long"; then
# Omit some internal or obsolete options to make the list less imposing.
# This message is too long to be a string in the A/UX 3.1 sh.
cat <<_ACEOF
\`configure' configures Mini-XML 2.12 to adapt to many kinds of systems.
\`configure' configures Mini-XML 2.13 to adapt to many kinds of systems.
Usage: $0 [OPTION]... [VAR=VALUE]...
@ -1333,7 +1333,7 @@ fi
if test -n "$ac_init_help"; then
case $ac_init_help in
short | recursive ) echo "Configuration of Mini-XML 2.12:";;
short | recursive ) echo "Configuration of Mini-XML 2.13:";;
esac
cat <<\_ACEOF
@ -1433,7 +1433,7 @@ fi
test -n "$ac_init_help" && exit $ac_status
if $ac_init_version; then
cat <<\_ACEOF
Mini-XML configure 2.12
Mini-XML configure 2.13
generated by GNU Autoconf 2.69
Copyright (C) 2012 Free Software Foundation, Inc.
@ -1840,7 +1840,7 @@ cat >config.log <<_ACEOF
This file contains any messages produced by compilers while
running configure, to aid debugging if configure makes a mistake.
It was created by Mini-XML $as_me 2.12, which was
It was created by Mini-XML $as_me 2.13, which was
generated by GNU Autoconf 2.69. Invocation command line was
$ $0 $@
@ -2298,7 +2298,7 @@ host_os_version=`echo $host_os | sed -e '1,$s/^[^0-9.]*//g'`
ac_config_headers="$ac_config_headers config.h"
VERSION="2.12"
VERSION="2.13"
cat >>confdefs.h <<_ACEOF
#define MXML_VERSION "Mini-XML v$VERSION"
@ -5146,7 +5146,7 @@ cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1
# report actual input values of CONFIG_FILES etc. instead of their
# values after options handling.
ac_log="
This file was extended by Mini-XML $as_me 2.12, which was
This file was extended by Mini-XML $as_me 2.13, which was
generated by GNU Autoconf 2.69. Invocation command line was
CONFIG_FILES = $CONFIG_FILES
@ -5209,7 +5209,7 @@ _ACEOF
cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1
ac_cs_config="`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`"
ac_cs_version="\\
Mini-XML config.status 2.12
Mini-XML config.status 2.13
configured by $0, generated by GNU Autoconf 2.69,
with options \\"\$ac_cs_config\\"

2
configure.ac
View File

@ -13,7 +13,7 @@ dnl https://michaelrsweet.github.io/mxml
dnl
dnl Package name and version...
AC_INIT([Mini-XML], [2.12], [https://github.com/michaelrsweet/mxml/issues], [mxml], [https://michaelrsweet.github.io/mxml])
AC_INIT([Mini-XML], [2.13], [https://github.com/michaelrsweet/mxml/issues], [mxml], [https://michaelrsweet.github.io/mxml])
dnl This line is provided to ensure that you don't run the autoheader program
dnl against this project. Doing so is completely unsupported and WILL cause

633
doc/advanced.html
View File

@ -1,633 +0,0 @@
<html>
<body>
<h1 align='right'><a name='ADVANCED'>Chapter 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='LOAD_CALLBACKS'>Load Callbacks</a></h2>
<p><a href='#LOAD_XML'>Chapter 2</a> introduced the <a
href='#mxmlLoadFile'><tt>mxmlLoadFile()</tt></a> and <a
href='#mxmlLoadString'><tt>mxmlLoadString()</tt></a> functions.
The last argument to these functions is a callback function
which is used to determine the value type of each data node in
an XML document.</p>
<p>Mini-XML defines several standard callbacks for simple
XML data files:</p>
<ul>
<li><tt>MXML_INTEGER_CALLBACK</tt> - All data nodes
contain whitespace-separated integers.</li>
<li><tt>MXML_OPAQUE_CALLBACK</tt> - All data nodes
contain opaque strings ("CDATA").</li>
<li><tt>MXML_REAL_CALLBACK</tt> - All data nodes contain
whitespace-separated floating-point numbers.</li>
<li><tt>MXML_TEXT_CALLBACK</tt> - All data nodes contain
whitespace-separated strings.</li>
</ul>
<p>You can provide your own callback functions for more complex
XML documents. Your callback function will receive a pointer to
the current element node and must return the value type of the
immediate children for that element node: <tt>MXML_INTEGER</tt>,
<tt>MXML_OPAQUE</tt>, <tt>MXML_REAL</tt>, or <tt>MXML_TEXT</tt>.
The 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.</p>
<!-- NEED 2in -->
<p>The following callback function looks for an attribute named
"type" or the element name to determine the value type for its
child nodes:</p>
<pre>
mxml_type_t
type_cb(mxml_node_t *node)
{
const char *type;
/*
* You can lookup attributes and/or use the
* element name, hierarchy, etc...
*/
type = mxmlElementGetAttr(node, "type");
if (type == NULL)
type = mxmlGetElement(node);
if (!strcmp(type, "integer"))
return (MXML_INTEGER);
else if (!strcmp(type, "opaque"))
return (MXML_OPAQUE);
else if (!strcmp(type, "real"))
return (MXML_REAL);
else
return (MXML_TEXT);
}
</pre>
<p>To use this callback function, simply use the name when you
call any of the load functions:</p>
<pre>
FILE *fp;
mxml_node_t *tree;
fp = fopen("filename.xml", "r");
tree = mxmlLoadFile(NULL, fp, <b>type_cb</b>);
fclose(fp);
</pre>
<h2><a name='SAVE_CALLBACKS'>Save Callbacks</a></h2>
<p><a href='#LOAD_XML'>Chapter 2</a> also introduced the <a
href='#mxmlSaveFile'><tt>mxmlSaveFile()</tt></a>, <a
href='#mxmlSaveString'><tt>mxmlSaveString()</tt></a>, and <a
href='#mxmlSaveAllocString'><tt>mxmlSaveAllocString()</tt></a>
functions. The last argument to these functions is a callback
function which is used to automatically insert whitespace in an
XML document.</p>
<p>Your callback 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 following whitespace callback can be used to add
whitespace to XHTML output to make it more readable in a standard
text editor:</p>
<pre>
const char *
whitespace_cb(mxml_node_t *node,
int where)
{
const char *name;
/*
* We can conditionally break to a new line
* before or after any element. These are
* just common HTML elements...
*/
name = mxmlGetElement(node);
if (!strcmp(name, "html") ||
!strcmp(name, "head") ||
!strcmp(name, "body") ||
!strcmp(name, "pre") ||
!strcmp(name, "p") ||
!strcmp(name, "h1") ||
!strcmp(name, "h2") ||
!strcmp(name, "h3") ||
!strcmp(name, "h4") ||
!strcmp(name, "h5") ||
!strcmp(name, "h6"))
{
/*
* Newlines before open and after
* close...
*/
if (where == MXML_WS_BEFORE_OPEN ||
where == MXML_WS_AFTER_CLOSE)
return ("\n");
}
else if (!strcmp(name, "dl") ||
!strcmp(name, "ol") ||
!strcmp(name, "ul"))
{
/*
* Put a newline before and after list
* elements...
*/
return ("\n");
}
else if (!strcmp(name, "dd") ||
!strcmp(name, "dt") ||
!strcmp(name, "li"))
{
/*
* Put a tab before &lt;li>'s, * &lt;dd>'s,
* and &lt;dt>'s, and a newline after them...
*/
if (where == MXML_WS_BEFORE_OPEN)
return ("\t");
else if (where == MXML_WS_AFTER_CLOSE)
return ("\n");
}
/*
* Return NULL for no added whitespace...
*/
return (NULL);
}
</pre>
<p>To use this callback function, simply use the name when you
call any of the save functions:</p>
<pre>
FILE *fp;
mxml_node_t *tree;
fp = fopen("filename.xml", "w");
mxmlSaveFile(tree, fp, <b>whitespace_cb</b>);
fclose(fp);
</pre>
<!-- NEED 10 -->
<h2>Custom Data Types</h2>
<p>Mini-XML supports custom data types via global load and save
callbacks. Only a single set of callbacks can be active at any
time, however your callbacks can store additional information in
order to support multiple custom data types as needed. The
<tt>MXML_CUSTOM</tt> node type identifies custom data nodes.</p>
<p>The load callback receives a pointer to the current data node
and a string of opaque character data from the XML source with
character entities converted to the corresponding UTF-8
characters. For example, if we wanted to support a custom
date/time type whose value is encoded as "yyyy-mm-ddThh:mm:ssZ"
(ISO format), the load callback would look like the
following:</p>
<pre>
typedef struct
{
unsigned year, /* Year */
month, /* Month */
day, /* Day */
hour, /* Hour */
minute, /* Minute */
second; /* Second */
time_t unix; /* UNIX time */
} iso_date_time_t;
int
load_custom(mxml_node_t *node,
const char *data)
{
iso_date_time_t *dt;
struct tm tmdata;
/*
* Allocate data structure...
*/
dt = calloc(1, sizeof(iso_date_time_t));
/*
* Try reading 6 unsigned integers from the
* data string...
*/
if (sscanf(data, "%u-%u-%uT%u:%u:%uZ",
&amp;(dt->year), &amp;(dt->month),
&amp;(dt->day), &amp;(dt->hour),
&amp;(dt->minute),
&amp;(dt->second)) != 6)
{
/*
* Unable to read numbers, free the data
* structure and return an error...
*/
free(dt);
return (-1);
}
/*
* Range check values...
*/
if (dt->month < 1 || dt->month > 12 ||
dt->day < 1 || dt->day > 31 ||
dt->hour < 0 || dt->hour > 23 ||
dt->minute < 0 || dt->minute > 59 ||
dt->second < 0 || dt->second > 59)
{
/*
* Date information is out of range...
*/
free(dt);
return (-1);
}
/*
* Convert ISO time to UNIX time in
* seconds...
*/
tmdata.tm_year = dt->year - 1900;
tmdata.tm_mon = dt->month - 1;
tmdata.tm_day = dt->day;
tmdata.tm_hour = dt->hour;
tmdata.tm_min = dt->minute;
tmdata.tm_sec = dt->second;
dt->unix = gmtime(&amp;tmdata);
/*
* Assign custom node data and destroy
* function pointers...
*/
mxmlSetCustom(node, data, destroy);
/*
* Return with no errors...
*/
return (0);
}
</pre>
<p>The function itself can return 0 on success or -1 if it is
unable to decode the custom data or the data contains an error.
Custom data nodes contain a <tt>void</tt> pointer to the
allocated custom data for the node and a pointer to a destructor
function which will free the custom data when the node is
deleted.</p>
<!-- NEED 15 -->
<p>The save callback receives the node pointer and returns an
allocated string containing the custom data value. The following
save callback could be used for our ISO date/time type:</p>
<pre>
char *
save_custom(mxml_node_t *node)
{
char data[255];
iso_date_time_t *dt;
dt = (iso_date_time_t *)mxmlGetCustom(node);
snprintf(data, sizeof(data),
"%04u-%02u-%02uT%02u:%02u:%02uZ",
dt->year, dt->month, dt->day,
dt->hour, dt->minute, dt->second);
return (strdup(data));
}
</pre>
<p>You register the callback functions using the <a
href='#mxmlSetCustomHandlers'><tt>mxmlSetCustomHandlers()</tt></a>
function:</p>
<pre>
mxmlSetCustomHandlers(<b>load_custom</b>,
<b>save_custom</b>);
</pre>
<!-- NEED 20 -->
<h2>Changing Node Values</h2>
<p>All of the examples so far have concentrated on creating and
loading new XML data nodes. Many applications, however, need to
manipulate or change the nodes during their operation, so
Mini-XML provides functions to change node values safely and
without leaking memory.</p>
<p>Existing nodes can be changed using the <a
href='#mxmlSetElement'><tt>mxmlSetElement()</tt></a>, <a
href='#mxmlSetInteger'><tt>mxmlSetInteger()</tt></a>, <a
href='#mxmlSetOpaque'><tt>mxmlSetOpaque()</tt></a>, <a
href='#mxmlSetReal'><tt>mxmlSetReal()</tt></a>, <a
href='#mxmlSetText'><tt>mxmlSetText()</tt></a>, and <a
href='#mxmlSetTextf'><tt>mxmlSetTextf()</tt></a> functions. For
example, use the following function call to change a text node
to contain the text "new" with leading whitespace:</p>
<pre>
mxml_node_t *node;
mxmlSetText(node, 1, "new");
</pre>
<h2>Formatted Text</h2>
<p>The <a href='#mxmlNewTextf'><tt>mxmlNewTextf()</tt></a> and <a
href='#mxmlSetTextf'><tt>mxmlSetTextf()</tt></a> functions create
and change text nodes, respectively, using <tt>printf</tt>-style
format strings and arguments. For example, use the following
function call to create a new text node containing a constructed
filename:</p>
<pre>
mxml_node_t</a> *node;
node = mxmlNewTextf(node, 1, "%s/%s",
path, filename);
</pre>
<h2>Indexing</h2>
<p>Mini-XML provides functions for managing indices of nodes.
The current implementation provides the same functionality as
<a href='#mxmlFindElement'><tt>mxmlFindElement()</tt></a>.
The advantage of using an index is that searching and
enumeration of elements is significantly faster. The only
disadvantage is that each index is a static snapshot of the XML
document, so indices are not well suited to XML data that is
updated more often than it is searched. The overhead of creating
an index is approximately equal to walking the XML document
tree. Nodes in the index are sorted by element name and
attribute value.</p>
<p>Indices are stored in <a href='#mxml_index_t'><tt>mxml_index_t</tt></a>
structures. The <a href='#mxmlIndexNew'><tt>mxmlIndexNew()</tt></a> function
creates a new index:</p>
<pre>
mxml_node_t *tree;
mxml_index_t *ind;
ind = mxmlIndexNew(tree, "element",
"attribute");
</pre>
<p>The first argument is the XML node tree to index. Normally this
will be a pointer to the <tt>?xml</tt> element.</p>
<p>The second argument contains the element to index; passing
<tt>NULL</tt> indexes all element nodes alphabetically.</p>
<p>The third argument contains the attribute to index; passing
<tt>NULL</tt> causes only the element name to be indexed.</p>
<p>Once the index is created, the <a
href='#mxmlIndexEnum'><tt>mxmlIndexEnum()</tt></a>, <a
href='#mxmlIndexFind'><tt>mxmlIndexFind()</tt></a>, and <a
href='#mxmlIndexReset'><tt>mxmlIndexReset()</tt></a> functions
are used to access the nodes in the index. The <a
href='#mxmlIndexReset'><tt>mxmlIndexReset()</tt></a> function
resets the "current" node pointer in the index, allowing you to
do new searches and enumerations on the same index. Typically
you will call this function prior to your calls to <a
href='#mxmlIndexEnum'><tt>mxmlIndexEnum()</tt></a> and <a
href='#mxmlIndexFind'><tt>mxmlIndexFind()</tt></a>.</p>
<p>The <a href='#mxmlIndexEnum'><tt>mxmlIndexEnum()</tt></a>
function enumerates each of the nodes in the index and can be
used in a loop as follows:</p>
<pre>
mxml_node_t *node;
mxmlIndexReset(ind);
while ((node = mxmlIndexEnum(ind)) != NULL)
{
// do something with node
}
</pre>
<p>The <a href='#mxmlIndexFind'><tt>mxmlIndexFind()</tt></a>
function locates the next occurrence of the named element and
attribute value in the index. It can be used to find all
matching elements in an index, as follows:</p>
<pre>
mxml_node_t *node;
mxmlIndexReset(ind);
while ((node = mxmlIndexFind(ind, "element",
"attr-value"))
!= NULL)
{
// do something with node
}
</pre>
<p>The second and third arguments represent the element name and
attribute value, respectively. A <tt>NULL</tt> pointer is used
to return all elements or attributes in the index. Passing
<tt>NULL</tt> for both the element name and attribute value
is equivalent to calling <tt>mxmlIndexEnum</tt>.</p>
<p>When you are done using the index, delete it using the
<a href='#mxmlIndexDelete()'><tt>mxmlIndexDelete()</tt></a>
function:</p>
<pre>
mxmlIndexDelete(ind);
</pre>
<h2>SAX (Stream) Loading of Documents</h2>
<p>Mini-XML supports an implementation of the Simple API for XML
(SAX) which allows you to load and process an XML document as a
stream of nodes. Aside from allowing you to process XML documents of
any size, the Mini-XML implementation also allows you to retain
portions of the document in memory for later processing.</p>
<p>The <a href='#mxmlSAXLoad'><tt>mxmlSAXLoadFd</tt></a>, <a
href='#mxmlSAXLoadFile'><tt>mxmlSAXLoadFile</tt></a>, and <a
href='#mxmlSAXLoadString'><tt>mxmlSAXLoadString</tt></a> functions
provide the SAX loading APIs. Each function works like the
corresponding <tt>mxmlLoad</tt> function but uses a callback to
process each node as it is read.</p>
<p>The callback function receives the node, an event code, and
a user data pointer you supply:</p>
<pre>
void
sax_cb(mxml_node_t *node,
mxml_sax_event_t event,
void *data)
{
... do something ...
}
</pre>
<p>The event will be one of the following:</p>
<ul>
<li><tt>MXML_SAX_CDATA</tt> - CDATA was just read</li>
<li><tt>MXML_SAX_COMMENT</tt> - A comment was just read</li>
<li><tt>MXML_SAX_DATA</tt> - Data (custom, integer, opaque, real, or text) was just read</li>
<li><tt>MXML_SAX_DIRECTIVE</tt> - A processing directive was just read</li>
<li><tt>MXML_SAX_ELEMENT_CLOSE</tt> - A close element was just read (<tt>&lt;/element&gt;</tt>)</li>
<li><tt>MXML_SAX_ELEMENT_OPEN</tt> - An open element was just read (<tt>&lt;element&gt;</tt>)</li>
</ul>
<p>Elements are <em>released</em> after the close element is
processed. All other nodes are released after they are processed.
The SAX callback can <em>retain</em> the node using the <a
href='#mxmlRetain'><tt>mxmlRetain</tt></a> function. For example,
the following SAX callback will retain all nodes, effectively
simulating a normal in-memory load:</p>
<pre>
void
sax_cb(mxml_node_t *node,
mxml_sax_event_t event,
void *data)
{
if (event != MXML_SAX_ELEMENT_CLOSE)
mxmlRetain(node);
}
</pre>
<p>More typically the SAX callback will only retain a small portion
of the document that is needed for post-processing. For example, the
following SAX callback will retain the title and headings in an
XHTML file. It also retains the (parent) elements like <tt>&lt;html&gt;</tt>, <tt>&lt;head&gt;</tt>, and <tt>&lt;body&gt;</tt>, and processing
directives like <tt>&lt;?xml ... ?&gt;</tt> and <tt>&lt;!DOCTYPE ... &gt;</tt>:</p>
<!-- NEED 10 -->
<pre>
void
sax_cb(mxml_node_t *node,
mxml_sax_event_t event,
void *data)
{
if (event == MXML_SAX_ELEMENT_OPEN)
{
/*
* Retain headings and titles...
*/
char *name = mxmlGetElement(node);
if (!strcmp(name, "html") ||
!strcmp(name, "head") ||
!strcmp(name, "title") ||
!strcmp(name, "body") ||
!strcmp(name, "h1") ||
!strcmp(name, "h2") ||
!strcmp(name, "h3") ||
!strcmp(name, "h4") ||
!strcmp(name, "h5") ||
!strcmp(name, "h6"))
mxmlRetain(node);
}
else if (event == MXML_SAX_DIRECTIVE)
mxmlRetain(node);
else if (event == MXML_SAX_DATA)
{
if (mxmlGetRefCount(mxmlGetParent(node)) > 1)
{
/*
* If the parent was retained, then retain
* this data node as well.
*/
mxmlRetain(node);
}
}
}
</pre>
<p>The resulting skeleton document tree can then be searched just
like one loaded using the <tt>mxmlLoad</tt> functions. For example,
a filter that reads an XHTML document from stdin and then shows the
title and headings in the document would look like:</p>
<pre>
mxml_node_t *doc, *title, *body, *heading;
doc = mxmlSAXLoadFd(NULL, 0,
MXML_TEXT_CALLBACK,
<b>sax_cb</b>, NULL);
title = mxmlFindElement(doc, doc, "title",
NULL, NULL,
MXML_DESCEND);
if (title)
print_children(title);
body = mxmlFindElement(doc, doc, "body",
NULL, NULL,
MXML_DESCEND);
if (body)
{
for (heading = mxmlGetFirstChild(body);
heading;
heading = mxmlGetNextSibling(heading))
print_children(heading);
}
</pre>
</body>
</html>

590
doc/basics.html
View File

@ -1,590 +0,0 @@
<html>
<body>
<h1 align='right'><a name='BASICS'>Chapter 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. Mini-XML provides the following
functionality:</p>
<ul>
<li>Reading of UTF-8 and UTF-16 and 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>SAX (streamed) reading of XML files and strings to minimize memory usage.</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.</p>
<h2>The Basics</h2>
<p>Mini-XML provides a single header file which you include:</p>
<pre>
#include &lt;mxml.h&gt;
</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>Nodes</h2>
<p>Every piece of information in an XML file is stored in memory in "nodes".
Nodes are defined by the <a href='#mxml_node_t'><tt>mxml_node_t</tt></a>
structure. Each node has a typed value, optional user data, a parent node,
sibling nodes (previous and next), and potentially child nodes.</p>
<p>For example, if you have an XML file like the following:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;data&gt;
&lt;node&gt;val1&lt;/node&gt;
&lt;node&gt;val2&lt;/node&gt;
&lt;node&gt;val3&lt;/node&gt;
&lt;group&gt;
&lt;node&gt;val4&lt;/node&gt;
&lt;node&gt;val5&lt;/node&gt;
&lt;node&gt;val6&lt;/node&gt;
&lt;/group&gt;
&lt;node&gt;val7&lt;/node&gt;
&lt;node&gt;val8&lt;/node&gt;
&lt;/data&gt;
</pre>
<p>the node tree for the file would look like the following in memory:</p>
<pre>
?xml version="1.0" encoding="utf-8"?
|
data
|
node - node - node - group - node - node
| | | | | |
val1 val2 val3 | val7 val8
|
node - node - node
| | |
val4 val5 val6
</pre>
<p>where "-" is a pointer to the sibling node and "|" is a pointer
to the first child or parent node.</p>
<p>The <a href="#mxmlGetType"><tt>mxmlGetType</tt></a> function gets the type of
a node, one of <tt>MXML_CUSTOM</tt>, <tt>MXML_ELEMENT</tt>,
<tt>MXML_INTEGER</tt>, <tt>MXML_OPAQUE</tt>, <tt>MXML_REAL</tt>, or
<tt>MXML_TEXT</tt>. The parent and sibling nodes are accessed using the
<a href="#mxmlGetParent"><tt>mxmlGetParent</tt></a>,
<a href="#mxmlGetNext"><tt>mxmlGetNext</tt></a>, and
<a href="#mxmlGetPrevious"><tt>mxmlGetPrevious</tt></a> functions. The
<a href="#mxmlGetUserData"><tt>mxmlGetUserData</tt></a> function gets any user
data associated with the node.</p>
<h3>CDATA Nodes</h3>
<p>CDATA (<tt>MXML_ELEMENT</tt>) nodes are created using the
<a href="#mxmlNewCDATA"><tt>mxmlNewCDATA</tt></a> function. The
<a href="#mxmlGetCDATA"><tt>mxmlGetCDATA</tt></a> function retrieves the
CDATA string pointer for a node.</p>
<blockquote><b>Note:</b>
<p>CDATA nodes are currently stored in memory as special elements. This will
be changed in a future major release of Mini-XML.</p>
</blockquote>
<h3>Custom Nodes</h3>
<p>Custom (<tt>MXML_CUSTOM</tt>) nodes are created using the
<a href="#mxmlNewCustom"><tt>mxmlNewCustom</tt></a> function or using a custom
load callback specified using the
<a href="#mxmlSetCustomHandlers"><tt>mxmlSetCustomHandlers</tt></a> function.
The <a href="#mxmlGetCustom"><tt>mxmlGetCustom</tt></a> function retrieves the
custom value pointer for a node.</p>
<h3>Comment Nodes</h3>
<p>Comment (<tt>MXML_ELEMENT</tt>) nodes are created using the
<a href="#mxmlNewElement"><tt>mxmlNewElement</tt></a> function. The
<a href="#mxmlGetElement"><tt>mxmlGetElement</tt></a> function retrieves the
comment string pointer for a node, including the surrounding "!--" and "--"
characters.</p>
<blockquote><b>Note:</b>
<p>Comment nodes are currently stored in memory as special elements. This will
be changed in a future major release of Mini-XML.</p>
</blockquote>
<h3>Element Nodes</h3>
<p>Element (<tt>MXML_ELEMENT</tt>) nodes are created using the
<a href="#mxmlNewElement"><tt>mxmlNewElement</tt></a> function. The
<a href="#mxmlGetElement"><tt>mxmlGetElement</tt></a> function retrieves the
element name, the
<a href="#mxmlElementGetAttr"><tt>mxmlElementGetAttr</tt></a> function retrieves
the value string for a named attribute associated with the element, and the
<a href="#mxmlGetFirstChild"><tt>mxmlGetFirstChild</tt></a> and
<a href="#mxmlGetLastChild"><tt>mxmlGetLastChild</tt></a> functions retrieve the
first and last child nodes for the element, respectively.</p>
<h3>Integer Nodes</h3>
<p>Integer (<tt>MXML_INTEGER</tt>) nodes are created using the
<a href="#mxmlNewInteger"><tt>mxmlNewInteger</tt></a> function. The
<a href="#mxmlGetInteger"><tt>mxmlGetInteger</tt></a> function retrieves the
integer value for a node.</p>
<h3>Opaque String Nodes</h3>
<p>Opaque string (<tt>MXML_OPAQUE</tt>) nodes are created using the
<a href="#mxmlNewOpaque"><tt>mxmlNewOpaque</tt></a> function. The
<a href="#mxmlGetOpaque"><tt>mxmlGetOpaque</tt></a> function retrieves the
opaque string pointer for a node. Opaque nodes are like string nodes but
preserve all whitespace between nodes.</p>
<h3>Text String Nodes</h3>
<p>Text string (<tt>MXML_TEXT</tt>) nodes are created using the
<a href="#mxmlNewText"><tt>mxmlNewText</tt></a> and
<a href="#mxmlNewTextf"><tt>mxmlNewTextf</tt></a> functions. Each text node
consists of a single word string and (leading) whitespace value - the
<a href="#mxmlGetText"><tt>mxmlGetText</tt></a> function retrieves the
string pointer and whitespace value for a node.</p>
<!-- NEED 12 -->
<h3>Processing Instruction Nodes</h3>
<p>Processing instruction (<tt>MXML_ELEMENT</tt>) nodes are created using the
<a href="#mxmlNewElement"><tt>mxmlNewElement</tt></a> function. The
<a href="#mxmlGetElement"><tt>mxmlGetElement</tt></a> function retrieves the
processing instruction string for a node, including the surrounding "?"
characters.</p>
<blockquote><b>Note:</b>
<p>Processing instruction nodes are currently stored in memory as special
elements. This will be changed in a future major release of Mini-XML.</p>
</blockquote>
<h3>Real Number Nodes</h3>
<p>Real number (<tt>MXML_REAL</tt>) nodes are created using the
<a href="#mxmlNewReal"><tt>mxmlNewReal</tt></a> function. The
<a href="#mxmlGetReal"><tt>mxmlGetReal</tt></a> function retrieves the
CDATA string pointer for a node.</p>
<!-- NEED 15 -->
<h3>XML Declaration Nodes</h3>
<p>XML declaration (<tt>MXML_ELEMENT</tt>) nodes are created using the
<a href="#mxmlNewXML"><tt>mxmlNewXML</tt></a> function. The
<a href="#mxmlGetElement"><tt>mxmlGetElement</tt></a> function retrieves the
XML declaration string for a node, including the surrounding "?" characters.</p>
<blockquote><b>Note:</b>
<p>XML declaration nodes are currently stored in memory as special elements.
This will be changed in a future major release of Mini-XML.</p>
</blockquote>
<!-- NEW PAGE -->
<h2>Creating XML Documents</h2>
<p>You can create and update XML documents in memory using the
various <tt>mxmlNew</tt> functions. The following code will
create the XML document described in the previous section:</p>
<pre>
mxml_node_t *xml; /* &lt;?xml ... ?&gt; */
mxml_node_t *data; /* &lt;data&gt; */
mxml_node_t *node; /* &lt;node&gt; */
mxml_node_t *group; /* &lt;group&gt; */
xml = mxmlNewXML("1.0");
data = mxmlNewElement(xml, "data");
node = mxmlNewElement(data, "node");
mxmlNewText(node, 0, "val1");
node = mxmlNewElement(data, "node");
mxmlNewText(node, 0, "val2");
node = mxmlNewElement(data, "node");
mxmlNewText(node, 0, "val3");
group = mxmlNewElement(data, "group");
node = mxmlNewElement(group, "node");
mxmlNewText(node, 0, "val4");
node = mxmlNewElement(group, "node");
mxmlNewText(node, 0, "val5");
node = mxmlNewElement(group, "node");
mxmlNewText(node, 0, "val6");
node = mxmlNewElement(data, "node");
mxmlNewText(node, 0, "val7");
node = mxmlNewElement(data, "node");
mxmlNewText(node, 0, "val8");
</pre>
<!-- NEED 6 -->
<p>We start by creating the declaration node common to all XML files using the
<a href="#mxmlNewXML"><tt>mxmlNewXML</tt></a> function:</p>
<pre>
xml = mxmlNewXML("1.0");
</pre>
<p>We then create the <tt>&lt;data&gt;</tt> node used for this document using
the <a href="#mxmlNewElement"><tt>mxmlNewElement</tt></a> function. The first
argument specifies the parent node (<tt>xml</tt>) while the second specifies the
element name (<tt>data</tt>):</p>
<pre>
data = mxmlNewElement(xml, "data");
</pre>
<p>Each <tt>&lt;node&gt;...&lt;/node&gt;</tt> in the file is created using the
<tt>mxmlNewElement</tt> and <a href="#mxmlNewText"><tt>mxmlNewText</tt></a>
functions. The first argument of <tt>mxmlNewText</tt> specifies the parent node
(<tt>node</tt>). The second argument specifies whether whitespace appears before
the text - 0 or false in this case. The last argument specifies the actual text
to add:</p>
<pre>
node = mxmlNewElement(data, "node");
mxmlNewText(node, 0, "val1");
</pre>
<p>The resulting in-memory XML document can then be saved or processed just like
one loaded from disk or a string.</p>
<!-- NEED 15 -->
<h2>Loading XML</h2>
<p>You load an XML file using the <a
href='#mxmlLoadFile'><tt>mxmlLoadFile</tt></a>
function:</p>
<pre>
FILE *fp;
mxml_node_t *tree;
fp = fopen("filename.xml", "r");
tree = mxmlLoadFile(NULL, fp,
MXML_OPAQUE_CALLBACK);
fclose(fp);
</pre>
<p>The first argument specifies an existing XML parent node, if
any. Normally you will pass <tt>NULL</tt> for this argument
unless you are combining multiple XML sources. The XML file must
contain a complete XML document including the <tt>?xml</tt>
element if the parent node is <tt>NULL</tt>.</p>
<p>The second argument specifies the stdio file to read from, as
opened by <tt>fopen()</tt> or <tt>popen()</tt>. You can also use
<tt>stdin</tt> if you are implementing an XML filter
program.</p>
<p>The third argument specifies a callback function which returns
the value type of the immediate children for a new element node:
<tt>MXML_CUSTOM</tt>, <tt>MXML_IGNORE</tt>,
<tt>MXML_INTEGER</tt>, <tt>MXML_OPAQUE</tt>, <tt>MXML_REAL</tt>,
or <tt>MXML_TEXT</tt>. Load callbacks are described in detail in
<a href='#LOAD_CALLBACKS'>Chapter 3</a>. The example code uses
the <tt>MXML_OPAQUE_CALLBACK</tt> constant which specifies that all
data nodes in the document contain opaque string values with whitespace
preserved. Other standard callbacks include
<tt>MXML_IGNORE_CALLBACK</tt>, <tt>MXML_INTEGER_CALLBACK</tt>,
<tt>MXML_REAL_CALLBACK</tt>, and
<tt>MXML_TEXT_CALLBACK</tt>.</p>
<p>The <a href='#mxmlLoadString'><tt>mxmlLoadString</tt></a>
function loads XML node trees from a string:</p>
<!-- NEED 10 -->
<pre>
char buffer[8192];
mxml_node_t *tree;
...
tree = mxmlLoadString(NULL, buffer,
MXML_OPAQUE_CALLBACK);
</pre>
<p>The first and third arguments are the same as used for
<tt>mxmlLoadFile()</tt>. The second argument specifies the
string or character buffer to load and must be a complete XML
document including the <tt>?xml</tt> element if the parent node
is <tt>NULL</tt>.</p>
<!-- NEED 15 -->
<h2>Saving XML</h2>
<p>You save an XML file using the <a
href='#mxmlSaveFile'><tt>mxmlSaveFile</tt></a> function:</p>
<pre>
FILE *fp;
mxml_node_t *tree;
fp = fopen("filename.xml", "w");
mxmlSaveFile(tree, fp, MXML_NO_CALLBACK);
fclose(fp);
</pre>
<p>The first argument is the XML node tree to save. It should
normally be a pointer to the top-level <tt>?xml</tt> node in
your XML document.</p>
<p>The second argument is the stdio file to write to, as opened
by <tt>fopen()</tt> or <tt>popen()</tt>. You can also use
<tt>stdout</tt> if you are implementing an XML filter
program.</p>
<p>The third argument is the whitespace callback to use when
saving the file. Whitespace callbacks are covered in detail in <a
href='SAVE_CALLBACKS'>Chapter 3</a>. The previous example code
uses the <tt>MXML_NO_CALLBACK</tt> constant to specify that no
special whitespace handling is required.</p>
<p>The <a
href='#mxmlSaveAllocString'><tt>mxmlSaveAllocString</tt></a>,
and <a href='#mxmlSaveString'><tt>mxmlSaveString</tt></a>
functions save XML node trees to strings:</p>
<pre>
char buffer[8192];
char *ptr;
mxml_node_t *tree;
...
mxmlSaveString(tree, buffer, sizeof(buffer),
MXML_NO_CALLBACK);
...
ptr = mxmlSaveAllocString(tree, MXML_NO_CALLBACK);
</pre>
<p>The first and last arguments are the same as used for
<tt>mxmlSaveFile()</tt>. The <tt>mxmlSaveString</tt> function
takes pointer and size arguments for saving the XML document to
a fixed-size buffer, while <tt>mxmlSaveAllocString()</tt>
returns a string buffer that was allocated using
<tt>malloc()</tt>.</p>
<!-- NEED 15 -->
<h3>Controlling Line Wrapping</h3>
<p>When saving XML documents, Mini-XML normally wraps output
lines at column 75 so that the text is readable in terminal
windows. The <a
href='#mxmlSetWrapMargin'><tt>mxmlSetWrapMargin</tt></a> function
overrides the default wrap margin:</p>
<pre>
/* Set the margin to 132 columns */
mxmlSetWrapMargin(132);
/* Disable wrapping */
mxmlSetWrapMargin(0);
</pre>
<h2>Memory Management</h2>
<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>
<p>You can also use reference counting to manage memory usage. The
<a href="#mxmlRetain"><tt>mxmlRetain</tt></a> and
<a href="#mxmlRelease"><tt>mxmlRelease</tt></a> functions increment and
decrement a node's use count, respectively. When the use count goes to 0,
<tt>mxmlRelease</tt> will automatically call <tt>mxmlDelete</tt> to actually
free the memory used by the node tree. New nodes automatically start with a
use count of 1.</p>
<!-- NEW PAGE-->
<h2>Finding and Iterating Nodes</h2>
<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>
mxml_node_t *node;
node = mxmlWalkPrev(current, tree,
MXML_DESCEND);
node = mxmlWalkNext(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>
mxml_node_t *node;
node = mxmlFindElement(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>
<!-- NEED 4 -->
<pre>
/* Find the first "a" element */
node = mxmlFindElement(tree, tree, "a",
NULL, NULL,
MXML_DESCEND);
</pre>
<!-- NEED 5 -->
<pre>
/* Find the first "a" element with "href"
attribute */
node = mxmlFindElement(tree, tree, "a",
"href", NULL,
MXML_DESCEND);
</pre>
<!-- NEED 6 -->
<pre>
/* Find the first "a" element with "href"
to a URL */
node = mxmlFindElement(tree, tree, "a",
"href",
"http://www.example.com/",
MXML_DESCEND);
</pre>
<!-- NEED 5 -->
<pre>
/* Find the first element with a "src"
attribute */
node = mxmlFindElement(tree, tree, NULL,
"src", NULL,
MXML_DESCEND);
</pre>
<!-- NEED 5 -->
<pre>
/* Find the first element with a "src"
= "foo.jpg" */
node = mxmlFindElement(tree, tree, NULL,
"src", "foo.jpg",
MXML_DESCEND);
</pre>
<p>You can also iterate with the same function:</p>
<pre>
mxml_node_t *node;
for (node = mxmlFindElement(tree, tree,
"name",
NULL, NULL,
MXML_DESCEND);
node != NULL;
node = mxmlFindElement(node, tree,
"name",
NULL, NULL,
MXML_DESCEND))
{
... do something ...
}
</pre>
<!-- NEED 10 -->
<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.
<p>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.<br><br></p></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" and "group" elements under the "?xml" parent
node in the example above.
<p>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.<br><br></p></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".
<p>If you were to walk from the root node "?xml" to the end
of the tree with <tt>mxmlWalkNext()</tt>, the order would
be:</p>
<p><tt>?xml data node val1 node val2 node val3 group node
val4 node val5 node val6 node val7 node val8</tt></p>
<p>If you started at "val8" and walked using
<tt>mxmlWalkPrev()</tt>, the order would be reversed,
ending at "?xml".</p></li>
</ul>
<h2>Finding Specific Nodes</h2>
<p>You can find specific nodes in the tree using the <a
href='#mxmlFindValue'><tt>mxmlFindPath</tt></a>, for example:
<pre>
mxml_node_t *value;
value = mxmlFindPath(tree, "path/to/*/foo/bar");
</pre>
<p>The second argument is a "path" to the parent node. Each component of the
path is separated by a slash (/) and represents a named element in the document
tree or a wildcard (*) path representing 0 or more intervening nodes.</p>
</body>
</html>

4
doc/body.md
View File

@ -1,8 +1,8 @@
---
title: Mini-XML API Reference
author: Michael R Sweet
copyright: Copyright © 2003-2018, All Rights Reserved.
docversion: 2.12
copyright: Copyright © 2003-2019, All Rights Reserved.
docversion: 2.13
...
# Introduction

4
doc/footer.man
View File

@ -1,4 +1,4 @@
.SH SEE ALSO
mxmldoc(1), Mini-XML Programmers Manual, https://michaelrsweet.github.io/mxml
Mini-XML Programmers Manual, https://www.msweet.org/mxml
.SH COPYRIGHT
Copyright \[co] 2003-2017 by Michael R Sweet.
Copyright \[co] 2003-2019 by Michael R Sweet.

BIN
doc/hires/mxml.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 31 KiB

77
doc/install.html
View File

@ -1,77 +0,0 @@
<html>
<body>
<h1 align='right'><a name='INSTALL'>Chapter 1 - Building,
Installing, and Packaging Mini-XML</a></h1>
<p>This chapter describes how to build, install, and package
Mini-XML on your system from the source archive. You will need an
ANSI/ISO-C compatible compiler to build Mini-XML - GCC works, as
do most vendors' C compilers. If you are building Mini-XML on
Windows, we recommend using the Visual C++ environment with the
supplied solution file. For other operating systems, you'll need a
POSIX-compatible shell and <tt>make</tt> program in addition to
the C compiler.</p>
<h2>Compiling Mini-XML</h2>
<p>Mini-XML comes with both an autoconf-based configure script
and a Visual C++ solution that can be used to compile the library
and associated tools.</p>
<h3>Compiling with Visual C++</h3>
<p>Open the <VAR>mxml.sln</VAR> solution in the <VAR>vcnet</VAR>
folder. Choose the desired build configuration, "Debug" (the
default) or "Release", and then choose <VAR>Build Solution</VAR>
from the <VAR>Build</VAR> menu.</p>
<h3>Compiling with Command-Line Tools</h3>
<p>Type the following command to configure the Mini-XML source
code for your system:</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>Installing Mini-XML</h2>
<p>If you are using Visual C++, copy the <VAR>mxml.lib</VAR> and
and <VAR>mxml.h</VAR> files to the Visual C++ <VAR>lib</VAR> and
<VAR>include<VAR> directories, respectively.</p>
<p>Otherwise, 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>
</body>
</html>

181
doc/intro.html
View File

@ -1,181 +0,0 @@
<html>
<head>
<title>Mini-XML Programmers Manual, Version 2.12</title>
<meta name="copyright" content="Copyright 2003-2018">
<meta name="author" content="Michael R Sweet">
<meta name="keywords" content="XML, C, C++, library">
</head>
<body>
<h1 align="right"><a name="INTRO">Introduction</a></h1>
<p>This programmers manual describes Mini-XML version 2.12, a small
XML parsing library that you can use to read and write XML data
files in your C and C++ applications.</p>
<p>Mini-XML was initially developed for the <a
href="http://gutenprint.sf.net/">Gutenprint</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><em>It's bad enough that we require libxml2, but rolling
our own XML parser is a bit more than we can handle.</em></blockquote>
<p>I then replied with:</p>
<blockquote><em>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.</em></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 Gutenprint
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 3,792
lines of code, compared to 140,410 lines of code for libxml2
version 2.9.1.</p>
<p>Aside from Gutenprint, Mini-XML is used for the
following projects/software applications:</p>
<ul>
<li><a href="https://www.cups.org/">CUPS</a></li>
<li><a
href="http://zynaddsubfx.sourceforge.net">ZynAddSubFX</a></li>
</ul>
<p>Please file a bug on Github 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 1in -->
<h2>Organization of This Document</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>Appendix A, "<a href="#LICENSE">Mini-XML License</a>",
provides the terms and conditions for using and distributing
Mini-XML.</li>
<li>Appendix B, "<a href="#REFERENCE">Library
Reference</a>", contains a complete reference for
Mini-XML, generated by <tt>mxmldoc</tt>.</li>
</ul>
<!-- NEED 10 -->
<h2>Notation Conventions</h2>
<p>Various font and syntax conventions are used in this guide.
Examples and their meanings and uses are explained below:</p>
<dl>
<dt><code>mxmldoc</code><br>
<code>mxmldoc(1)</code></dt>
<dd>The names of commands; the first mention of a command
or function in a chapter is followed by a manual page
section number.<br><br></dd>
<dt><var>/var</var><br>
<var>/etc/hosts</var></dt>
<dd>File and directory names.<br><br></dd>
<dt><tt>Request ID is Printer-123</tt></dt>
<dd>Screen output.<br><br></dd>
<dt><kbd>lp -d printer filename ENTER</kbd></dt>
<dd>Literal user input; special keys like
<kbd>ENTER</kbd> are in ALL CAPS.<br><br></dd>
<dt>12.3</dt>
<dd>Numbers in the text are written using the period (.)
to indicate the decimal point.<br><br></dd>
</dl>
<!-- NEED 10 -->
<h2>Abbreviations</h2>
<p>The following abbreviations are used throughout this
manual:</p>
<dl>
<dt>Gb</dt>
<dd>Gigabytes, or 1073741824 bytes<br><br></dd>
<dt>kb</dt>
<dd>Kilobytes, or 1024 bytes<br><br></dd>
<dt>Mb</dt>
<dd>Megabytes, or 1048576 bytes<br><br></dd>
<dt>UTF-8, UTF-16</dt>
<dd>Unicode Transformation Format, 8-bit or 16-bit<br><br></dd>
<dt>W3C</dt>
<dd>World Wide Web Consortium<br><br></dd>
<dt>XML</dt>
<dd>Extensible Markup Language<br><br></dd>
</dl>
<!-- NEED 12 -->
<h2>Other References</h2>
<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><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><br></dd>
</dl>
<!-- NEED 6 -->
<h2>Legal Stuff</h2>
<p>The Mini-XML library is copyright 2003-2018 by Michael R Sweet. License terms
are described in <a href="#LICENSE">Appendix A - Mini-XML License</a>.</p>
</body>
</html>

593
doc/license.html
View File

@ -1,593 +0,0 @@
<html>
<body>
<h1 align='right'><a name='LICENSE'>Appendix A - Mini-XML
License</a></h1>
<p>The Mini-XML library and included programs are provided under
the terms of the GNU Library General Public License version 2
(LGPL2) with the following exceptions:</p>
<p><b>1.</b> Static linking of applications to the Mini-XML
library does not constitute a derivative work and does
not require the author to provide source code for the
application, use the shared Mini-XML libraries, or link
their applications against a user-supplied version of
Mini-XML.</p>
<p><i>If you link the application to a modified version
of Mini-XML, then the changes to Mini-XML must be
provided under the terms of the LGPL2 in sections 1, 2,
and 4.</i></p>
<p><b>2.</b> You do not have to provide a copy of the Mini-XML
license with programs that are linked to the Mini-XML
library, nor do you have to identify the Mini-XML license
in your program or documentation as required by section 6
of the LGPL2.</p>
<p>&nbsp;</p>
<p align=center><b>GNU LIBRARY GENERAL PUBLIC LICENSE</b></p>
<p align='center'>Version 2, June 1991
<br>Copyright (C) 1991 Free Software Foundation, Inc.
<br>59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
<br>Everyone is permitted to copy and distribute verbatim copies of
this license document, but changing it is not allowed.
<br>[This is the first released version of the library GPL. It is
numbered 2 because it goes with version 2 of the ordinary GPL.]</p>
<p><b>Preamble</b></p>
<p>The licenses for most software are designed to take away your freedom
to share and change it. By contrast, the GNU General Public Licenses
are intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.</p>
<p>This license, the Library General Public License, applies to some
specially designated Free Software Foundation software, and to any
other libraries whose authors decide to use it. You can use it for
your libraries, too.</p>
<p>When we speak of free software, we are referring to freedom,
not price. Our General Public Licenses are designed to make sure
that you have the freedom to distribute copies of free software
(and charge for this service if you wish), that you receive
source code or can get it if you want it, that you can change
the software or use pieces of it in new free programs; and that
you know you can do these things.</p>
<p>To protect your rights, we need to make restrictions that
forbid anyone to deny you these rights or to ask you to
surrender the rights. These restrictions translate to certain
responsibilities for you if you distribute copies of the
library, or if you modify it.</p>
<p>For example, if you distribute copies of the library, whether
gratis or for a fee, you must give the recipients all the rights
that we gave you. You must make sure that they, too, receive or
can get the source code. If you link a program with the library,
you must provide complete object files to the recipients so that
they can relink them with the library, after making changes to
the library and recompiling it. And you must show them these
terms so they know their rights.</p>
<p>Our method of protecting your rights has two steps: (1)
copyright the library, and (2) offer you this license which
gives you legal permission to copy, distribute and/or modify the
library.</p>
<p>Also, for each distributor's protection, we want to make
certain that everyone understands that there is no warranty for
this free library. If the library is modified by someone else
and passed on, we want its recipients to know that what they
have is not the original version, so that any problems
introduced by others will not reflect on the original authors'
reputations.</p>
<p>Finally, any free program is threatened constantly by
software patents. We wish to avoid the danger that companies
distributing free software will individually obtain patent
licenses, thus in effect transforming the program into
proprietary software. To prevent this, we have made it clear
that any patent must be licensed for everyone's free use or not
licensed at all.</p>
<p>Most GNU software, including some libraries, is covered by
the ordinary GNU General Public License, which was designed for
utility programs. This license, the GNU Library General Public
License, applies to certain designated libraries. This license
is quite different from the ordinary one; be sure to read it in
full, and don't assume that anything in it is the same as in the
ordinary license.</p>
<p>The reason we have a separate public license for some
libraries is that they blur the distinction we usually make
between modifying or adding to a program and simply using it.
Linking a program with a library, without changing the library,
is in some sense simply using the library, and is analogous to
running a utility program or application program. However, in a
textual and legal sense, the linked executable is a combined
work, a derivative of the original library, and the ordinary
General Public License treats it as such.</p>
<p>Because of this blurred distinction, using the ordinary
General Public License for libraries did not effectively promote
software sharing, because most developers did not use the
libraries. We concluded that weaker conditions might promote
sharing better.</p>
<p>However, unrestricted linking of non-free programs would
deprive the users of those programs of all benefit from the free
status of the libraries themselves. This Library General Public
License is intended to permit developers of non-free programs to
use free libraries, while preserving your freedom as a user of
such programs to change the free libraries that are incorporated
in them. (We have not seen how to achieve this as regards
changes in header files, but we have achieved it as regards
changes in the actual functions of the Library.) The hope is
that this will lead to faster development of free libraries.</p>
<p>The precise terms and conditions for copying, distribution
and modification follow. Pay close attention to the difference
between a &quot;work based on the libary&quot; and a &quot;work
that uses the library&quot;. The former contains code derived
from the library, while the latter only works together with the
library.</p>
<p>Note that it is possible for a library to be covered by the
ordinary General Public License rather than by this special
one.</p>
<p align='center'><b>TERMS AND CONDITIONS FOR COPYING,
DISTRIBUTION AND MODIFICATION</b></p>
<p><strong>0.</strong> This License Agreement applies to any
software library which contains a notice placed by the copyright
holder or other authorized party saying it may be distributed
under the terms of this Library General Public License (also
called &quot;this License&quot;). Each licensee is addressed as
&quot;you&quot;.
<p>A &quot;library&quot; means a collection of software
functions and/or data prepared so as to be conveniently linked
with application programs (which use some of those functions and
data) to form executables.</p>
<p>The &quot;Library&quot;, below, refers to any such software
library or work which has been distributed under these terms. A
&quot;work based on the Library&quot; means either the Library
or any derivative work under copyright law: that is to say, a
work containing the Library or a portion of it, either verbatim
or with modifications and/or translated straightforwardly into
another language. (Hereinafter, translation is included without
limitation in the term &quot;modification&quot;.)</p>
<p>&quot;Source code&quot; for a work means the preferred form
of the work for making modifications to it. For a library,
complete source code means all the source code for all modules
it contains, plus any associated interface definition files,
plus the scripts used to control compilation and installation of
the library.</p>
<p>Activities other than copying, distribution and modification
are not covered by this License; they are outside its scope. The
act of running a program using the Library is not restricted,
and output from such a program is covered only if its contents
constitute a work based on the Library (independent of the use
of the Library in a tool for writing it). Whether that is true
depends on what the Library does and what the program that uses
the Library does.</p>
<p><strong>1.</strong> You may copy and distribute verbatim
copies of the Library's complete source code as you receive it,
in any medium, provided that you conspicuously and appropriately
publish on each copy an appropriate copyright notice and
disclaimer of warranty; keep intact all the notices that refer
to this License and to the absence of any warranty; and
distribute a copy of this License along with the Library.</p>
<p>You may charge a fee for the physical act of transferring a
copy, and you may at your option offer warranty protection in
exchange for a fee.</p>
<p><strong>2.</strong> You may modify your copy or copies of the
Library or any portion of it, thus forming a work based on the
Library, and copy and distribute such modifications or work
under the terms of Section 1 above, provided that you also meet
all of these conditions:</p>
<ul>
<p><strong>a)</strong> The modified work must itself be
a software library.
<p><strong>b)</strong> You must cause the files modified
to carry prominent notices stating that you changed the
files and the date of any change.</p>
<p><strong>c)</strong> You must cause the whole of the
work to be licensed at no charge to all third parties
under the terms of this License.</p>
<p><strong>d)</strong> If a facility in the modified
Library refers to a function or a table of data to be
supplied by an application program that uses the
facility, other than as an argument passed when the
facility is invoked, then you must make a good faith
effort to ensure that, in the event an application does
not supply such function or table, the facility still
operates, and performs whatever part of its purpose
remains meaningful.</p>
<p>(For example, a function in a library to compute
square roots has a purpose that is entirely well-defined
independent of the application. Therefore, Subsection 2d
requires that any application-supplied function or table
used by this function must be optional: if the
application does not supply it, the square root function
must still compute square roots.)</p>
</ul>
<p>These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the
Library, and can be reasonably considered independent and
separate works in themselves, then this License, and its terms,
do not apply to those sections when you distribute them as
separate works. But when you distribute the same sections as
part of a whole which is a work based on the Library, the
distribution of the whole must be on the terms of this License,
whose permissions for other licensees extend to the entire
whole, and thus to each and every part regardless of who wrote
it.</p>
<p>Thus, it is not the intent of this section to claim rights or
contest your rights to work written entirely by you; rather, the
intent is to exercise the right to control the distribution of
derivative or collective works based on the Library.</p>
<p>In addition, mere aggregation of another work not based on
the Library with the Library (or with a work based on the
Library) on a volume of a storage or distribution medium does
not bring the other work under the scope of this License.</p>
<p><strong>3.</strong> You may opt to apply the terms of the
ordinary GNU General Public License instead of this License to a
given copy of the Library. To do this, you must alter all the
notices that refer to this License, so that they refer to the
ordinary GNU General Public License, version 2, instead of to
this License. (If a newer version than version 2 of the ordinary
GNU General Public License has appeared, then you can specify
that version instead if you wish.) Do not make any other change
in these notices.</p>
<p>Once this change is made in a given copy, it is irreversible
for that copy, so the ordinary GNU General Public License
applies to all subsequent copies and derivative works made from
that copy.</p>
<p>This option is useful when you wish to copy part of the code
of the Library into a program that is not a library.</p>
<p><strong>4.</strong> You may copy and distribute the Library
(or a portion or derivative of it, under Section 2) in object
code or executable form under the terms of Sections 1 and 2
above provided that you accompany it with the complete
corresponding machine-readable source code, which must be
distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.</p>
<p>If distribution of object code is made by offering access to
copy from a designated place, then offering equivalent access to
copy the source code from the same place satisfies the
requirement to distribute the source code, even though third
parties are not compelled to copy the source along with the
object code.</p>
<p><strong>5.</strong> A program that contains no derivative of
any portion of the Library, but is designed to work with the
Library by being compiled or linked with it, is called a
&quot;work that uses the Library&quot;. Such a work, in
isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.</p>
<p>However, linking a &quot;work that uses the Library&quot;
with the Library creates an executable that is a derivative of
the Library (because it contains portions of the Library),
rather than a &quot;work that uses the library&quot;. The
executable is therefore covered by this License. Section 6
states terms for distribution of such executables.</p>
<p>When a &quot;work that uses the Library&quot; uses material
from a header file that is part of the Library, the object code
for the work may be a derivative work of the Library even though
the source code is not. Whether this is true is especially
significant if the work can be linked without the Library, or if
the work is itself a library. The threshold for this to be true
is not precisely defined by law.</p>
<p>If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small
inline functions (ten lines or less in length), then the use of
the object file is unrestricted, regardless of whether it is
legally a derivative work. (Executables containing this object
code plus portions of the Library will still fall under Section
6.)</p>
<p>Otherwise, if the work is a derivative of the Library, you
may distribute the object code for the work under the terms of
Section 6. Any executables containing that work also fall under
Section 6, whether or not they are linked directly with the
Library itself.</p>
<p><strong>6.</strong> As an exception to the Sections above,
you may also compile or link a &quot;work that uses the
Library&quot; with the Library to produce a work containing
portions of the Library, and distribute that work under terms of
your choice, provided that the terms permit modification of the
work for the customer's own use and reverse engineering for
debugging such modifications.</p>
<p>You must give prominent notice with each copy of the work
that the Library is used in it and that the Library and its use
are covered by this License. You must supply a copy of this
License. If the work during execution displays copyright
notices, you must include the copyright notice for the Library
among them, as well as a reference directing the user to the
copy of this License. Also, you must do one of these things:</p>
<ul>
<strong>a)</strong> Accompany the work with the complete
corresponding machine-readable source code for the
Library including whatever changes were used in the work
(which must be distributed under Sections 1 and 2
above); and, if the work is an executable linked with
the Library, with the complete machine-readable
&quot;work that uses the Library&quot;, as object code
and/or source code, so that the user can modify the
Library and then relink to produce a modified executable
containing the modified Library. (It is understood that
the user who changes the contents of definitions files
in the Library will not necessarily be able to recompile
the application to use the modified definitions.)
<p><strong>b)</strong> Accompany the work with a written
offer, valid for at least three years, to give the same
user the materials specified in Subsection 6a, above,
for a charge no more than the cost of performing this
distribution.</p>
<p><strong>c)</strong> If distribution of the work is
made by offering access to copy from a designated place,
offer equivalent access to copy the above specified
materials from the same place.</p>
<p><strong>d)</strong> Verify that the user has already
received a copy of these materials or that you have
already sent this user a copy.</p>
</ul>
<p>For an executable, the required form of the &quot;work that
uses the Library&quot; must include any data and utility
programs needed for reproducing the executable from it. However,
as a special exception, the source code distributed need not
include anything that is normally distributed (in either source
or binary form) with the major components (compiler, kernel, and
so on) of the operating system on which the executable runs,
unless that component itself accompanies the executable.</p>
<p>It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system. Such a contradiction means you
cannot use both them and the Library together in an executable
that you distribute.</p>
<p><strong>7.</strong> You may place library facilities that are
a work based on the Library side-by-side in a single library
together with other library facilities not covered by this
License, and distribute such a combined library, provided that
the separate distribution of the work based on the Library and
of the other library facilities is otherwise permitted, and
provided that you do these two things:</p>
<ul>
<strong>a)</strong> Accompany the combined library with
a copy of the same work based on the Library, uncombined
with any other library facilities. This must be
distributed under the terms of the Sections above.
<p><strong>b)</strong> Give prominent notice with the
combined library of the fact that part of it is a work
based on the Library, and explaining where to find the
accompanying uncombined form of the same work.</p>
</ul>
<p><strong>8.</strong> You may not copy, modify, sublicense,
link with, or distribute the Library except as expressly
provided under this License. Any attempt otherwise to copy,
modify, sublicense, link with, or distribute the Library is
void, and will automatically terminate your rights under this
License. However, parties who have received copies, or rights,
from you under this License will not have their licenses
terminated so long as such parties remain in full
compliance.</p>
<p><strong>9.</strong> You are not required to accept this
License, since you have not signed it. However, nothing else
grants you permission to modify or distribute the Library or its
derivative works. These actions are prohibited by law if you do
not accept this License. Therefore, by modifying or distributing
the Library (or any work based on the Library), you indicate
your acceptance of this License to do so, and all its terms and
conditions for copying, distributing or modifying the Library or
works based on it.</p>
<p><strong>10.</strong> Each time you redistribute the Library
(or any work based on the Library), the recipient automatically
receives a license from the original licensor to copy,
distribute, link with or modify the Library subject to these
terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted
herein. You are not responsible for enforcing compliance by
third parties to this License.</p>
<p><strong>11.</strong> If, as a consequence of a court judgment
or allegation of patent infringement or for any other reason
(not limited to patent issues), conditions are imposed on you
(whether by court order, agreement or otherwise) that contradict
the conditions of this License, they do not excuse you from the
conditions of this License. If you cannot distribute so as to
satisfy simultaneously your obligations under this License and
any other pertinent obligations, then as a consequence you may
not distribute the Library at all. For example, if a patent
license would not permit royalty-free redistribution of the
Library by all those who receive copies directly or indirectly
through you, then the only way you could satisfy both it and
this License would be to refrain entirely from distribution of
the Library.</p>
<p>If any portion of this section is held invalid or
unenforceable under any particular circumstance, the balance of
the section is intended to apply, and the section as a whole is
intended to apply in other circumstances.</p>
<p>It is not the purpose of this section to induce you to
infringe any patents or other property right claims or to
contest validity of any such claims; this section has the sole
purpose of protecting the integrity of the free software
distribution system which is implemented by public license
practices. Many people have made generous contributions to the
wide range of software distributed through that system in
reliance on consistent application of that system; it is up to
the author/donor to decide if he or she is willing to distribute
software through any other system and a licensee cannot impose
that choice.</p>
<p>This section is intended to make thoroughly clear what is
believed to be a consequence of the rest of this License.</p>
<p><strong>12.</strong> If the distribution and/or use of the
Library is restricted in certain countries either by patents or
by copyrighted interfaces, the original copyright holder who
places the Library under this License may add an explicit
geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not
thus excluded. In such case, this License incorporates the
limitation as if written in the body of this License.</p>
<p><strong>13.</strong> The Free Software Foundation may publish
revised and/or new versions of the Library General Public
License from time to time. Such new versions will be similar in
spirit to the present version, but may differ in detail to
address new problems or concerns.</p>
<p>Each version is given a distinguishing version number. If the
Library specifies a version number of this License which applies
to it and &quot;any later version&quot;, you have the option of
following the terms and conditions either of that version or of
any later version published by the Free Software Foundation. If
the Library does not specify a license version number, you may
choose any version ever published by the Free Software
Foundation.</p>
<p><strong>14.</strong> If you wish to incorporate parts of the
Library into other free programs whose distribution conditions
are incompatible with these, write to the author to ask for
permission. For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we
sometimes make exceptions for this. Our decision will be guided
by the two goals of preserving the free status of all
derivatives of our free software and of promoting the sharing
and reuse of software generally.</p>
<p align='center'><b>NO WARRANTY</b></p>
<p><strong>15.</strong> BECAUSE THE LIBRARY IS LICENSED FREE OF
CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT
PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN
WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
LIBRARY &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF
THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU
ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
CORRECTION.</p>
<p><strong>16.</strong> IN NO EVENT UNLESS REQUIRED BY
APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT
HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE
THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY
(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES
OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.</p>
<p align='center'><b>END OF TERMS AND CONDITIONS</b></p>
<p><b>How to Apply These Terms to Your New Libraries</b></p>
<p>If you develop a new library, and you want it to be of the
greatest possible use to the public, we recommend making it free
software that everyone can redistribute and change. You can do so
by permitting redistribution under these terms (or, alternatively,
under the terms of the ordinary General Public License).
<p>To apply these terms, attach the following notices to the
library. It is safest to attach them to the start of each source
file to most effectively convey the exclusion of warranty; and each
file should have at least the "copyright" line and a pointer to
where the full notice is found.
<ul>
<p><var>one line to give the library's name and an idea of what it
does.</var><br>
Copyright (C) <var>year</var> <var>name of author</var>
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public License
as published by the Free Software Foundation; either version 2.1 of
the License, or (at your option) any later version.
<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
Lesser General Public License for more details.
<p>You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA
</ul>
<p>Also add information on how to contact you by electronic and paper mail.
<p>You should also get your employer (if you work as a programmer)
or your school, if any, to sign a "copyright disclaimer" for the
library, if necessary. Here is a sample; alter the names:
<ul>
<p>Yoyodyne, Inc., hereby disclaims all copyright interest in the
library `Frob' (a library for tweaking knobs) written by James
Random Hacker.
<p><var>signature of Ty Coon</var>, 1 April 1990 Ty Coon, President
of Vice
</ul>
<p>That's all there is to it!
</body>
</html>

24
doc/makedocs.sh
View File

@ -1,24 +0,0 @@
#!/bin/sh
#
# Script to make documentation...
#
# Copyright 2003-2017 by Michael R Sweet.
#
# These coded instructions, statements, and computer programs are the
# property of Michael R Sweet and are protected by Federal copyright
# law. Distribution and use rights are outlined in the file "COPYING"
# which should have been included with this file. If this file is
# missing or damaged, see the license at:
#
# https://michaelrsweet.github.io/mxml
#
htmldoc --verbose --path "hires;." --batch mxml.book -f mxml.pdf
htmldoc --verbose --batch mxml.book --no-title -f mxml.html
htmldoc --verbose --batch mxml.book --titleimage mxml-cover.png -f mxml.epub
rm -rf mxml.d
mkdir mxml.d
htmldoc --verbose --batch mxml.book --no-title -t html -d mxml.d

6
doc/mxml.man → doc/mxml.3
View File

@ -1,4 +1,4 @@
.TH mxml 3 "Mini-XML API" "12/01/18" "Mini-XML API"
.TH mxml 3 "Mini-XML API" "01/02/19" "Mini-XML API"
.SH NAME
mxml \- Mini-XML API
.SH INCLUDE FILE
@ -1348,6 +1348,6 @@ The XML node type.
typedef enum mxml_type_e mxml_type_t;
.fi
.SH SEE ALSO
mxmldoc(1), Mini-XML Programmers Manual, https://michaelrsweet.github.io/mxml
Mini-XML Programmers Manual, https://www.msweet.org/mxml
.SH COPYRIGHT
Copyright \[co] 2003-2017 by Michael R Sweet.
Copyright \[co] 2003-2019 by Michael R Sweet.

8
doc/mxml.book
View File

@ -1,8 +0,0 @@
#HTMLDOC 1.8.30
-t pdf14 -f "mxml.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 --embedfonts --pagemode outline --pagelayout single --firstpage c1 --pageeffect none --pageduration 10 --effectduration 1.0 --no-encryption --permissions all --owner-password "" --user-password "" --browserwidth 300 --no-strict --no-overflow
intro.html
install.html
basics.html
advanced.html
license.html
reference.html

BIN
doc/mxml.epub Normal file
View File

Binary file not shown.

4914
doc/mxml.html
View File

File diff suppressed because it is too large Load Diff

BIN
doc/mxml.pdf
View File

Binary file not shown.

1
doc/reference.header
View File

@ -1 +0,0 @@
<h1 align="right"><a name="REFERENCE">Appendix B - Library Reference</a></h1>

1674
doc/reference.html
View File

File diff suppressed because it is too large Load Diff

33
doc/title.html
View File

@ -1,33 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Mini-XML Programmers Manual</title>
<meta name="author" content="Michael R Sweet">
<meta name="copyright" content="Copyright 2003-2018">
</head>
<body>
<table width="100%" height="100%" border="0" cellpadding="0" cellspacing="0" summary="">
<tr><td height="100%">
<h1 align="center"><img src="mxml.png" width="50%"><br>
<font size="-1">Mini-XML Programmers Manual<br>
Version 2.12</h1>
<P ALIGN="CENTER">MICHAEL R. SWEET</P>
</td></tr>
</table>
<!-- NEW PAGE -->
<P><FONT SIZE="+1"><B>Mini-XML Programmers Manual, Version 2.12</B></FONT></P>
<P><B>Copyright &copy; 2003-2018 by Michael R Sweet</B></P>
<P><SMALL>Permission is granted to copy, distribute and/or modify
this document under the terms of the GNU Library General Public
License, Version 2. A copy of this license is included in <A
HREF="#LICENSE">Appendix A - Mini-XML License</A>.</SMALL></P>
</body>
</html>

4
vcnet/config.h
View File

@ -2,7 +2,7 @@
* Visual Studio configuration file for Mini-XML, a small XML file parsing
* library.
*
* Copyright 2003-2018 by Michael R Sweet.
* Copyright 2003-2019 by Michael R Sweet.
*
* These coded instructions, statements, and computer programs are the
* property of Michael R Sweet and are protected by Federal copyright
@ -63,7 +63,7 @@
* Version number...
*/
#define MXML_VERSION "Mini-XML v2.12"
#define MXML_VERSION "Mini-XML v2.13"
/*