mxml/doc/intro.html

<html>
<head>
	<title>Mini-XML Programmers Manual, Version 2.7</title>
	<meta name="copyright" content="Copyright 2003-2011">
	<meta name="author" content="Michael R. Sweet">
	<meta name="keywords" content="XML, C, C++, library">
</head>
<body>

<h1 align="right"><a name="INTRO"><img src="0.gif" align="right"
hspace="10" width="100" height="100" alt="0"></a>Introduction</h1>

<p>This programmers manual describes Mini-XML version 2.7, 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,965
lines of code, compared to 103,893 lines of code for libxml2
version 2.6.9.</p>

<p>Aside from Gutenprint, Mini-XML is used for the
following projects/software applications:</p>

<ul>

	<li><a href="http://www.cups.org/">CUPS</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 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>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">Mini-XML 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>

	<li>Appendix D, "<a href="#SCHEMA">XML Schema</a>", shows
	the XML schema used for the XML files produced by
	<tt>mxmldoc</tt>.</li>

</ul>

<!-- NEED 10 -->
<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-2011 by Michael Sweet. License terms
are described in <a href="#LICENSE">Appendix A - Mini-XML License</a>.</p>

</body>
</html>
Start with new docos. 2004-05-01 23:41:52 +00:00			`<html>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`<head>`
Doco updates. 2010-09-19 08:50:54 +00:00			`<title>Mini-XML Programmers Manual, Version 2.7</title>`
Implemment getters for all of mxml_node_t and mxml_index_t fields (STR #118) Make mxml_node_s and mxml_index_s private (but still in the public header for 2.x). 2011-01-01 23:42:17 +00:00			`<meta name="copyright" content="Copyright 2003-2011">`
Doco updates. 2010-09-19 08:50:54 +00:00			`<meta name="author" content="Michael R. Sweet">`
			`<meta name="keywords" content="XML, C, C++, library">`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`</head>`
Start with new docos. 2004-05-01 23:41:52 +00:00			`<body>`

Doco updates. 2010-09-19 08:50:54 +00:00			`<h1 align="right"><a name="INTRO"><img src="0.gif" align="right"`
Don't install or create formatted man pages. New logo. Documentation updates. 2007-04-26 22:21:37 +00:00			`hspace="10" width="100" height="100" alt="0"></a>Introduction</h1>`
Start with new docos. 2004-05-01 23:41:52 +00:00
Doco updates. 2010-09-19 08:50:54 +00:00			`<p>This programmers manual describes Mini-XML version 2.7, a small`
Don't install or create formatted man pages. New logo. Documentation updates. 2007-04-26 22:21:37 +00:00			`XML parsing library that you can use to read and write XML data`
			`files in your C and C++ applications.</p>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
			`<p>Mini-XML was initially developed for the <a`
Doco updates. 2010-09-19 08:50:54 +00:00			`href="http://gutenprint.sf.net/">Gutenprint</a> project to replace`
Don't install or create formatted man pages. New logo. Documentation updates. 2007-04-26 22:21:37 +00:00			`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>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
Don't install or create formatted man pages. New logo. Documentation updates. 2007-04-26 22:21:37 +00:00			`<blockquote><em>It's bad enough that we require libxml2, but rolling`
Doco updates. 2010-09-19 08:50:54 +00:00			`our own XML parser is a bit more than we can handle.</em></blockquote>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
			`<p>I then replied with:</p>`

Don't install or create formatted man pages. New logo. Documentation updates. 2007-04-26 22:21:37 +00:00			`<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>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
			`<p>I took my own challenge and coded furiously for two days to`
			`produced the initial public release of Mini-XML, total lines of`
Save documentation updates. 2007-04-18 19:25:26 +00:00			`code: 696. Robert promptly integrated Mini-XML into Gutenprint`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`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`
Rename mxmlFindValue to mxmlFindPath. Rename mxmlGetPrevious to mxmlGetPrevSibling. Rename mxmlGetNext to mxmlGetNextSibling. Update documentation. 2011-01-03 02:03:29 +00:00			`complete XML implementation and now stands at a whopping 3,965`
Revise line-of-code count for libxml2. 2004-05-21 12:34:26 +00:00			`lines of code, compared to 103,893 lines of code for libxml2`
Save documentation updates. 2007-04-18 19:25:26 +00:00			`version 2.6.9.</p>`

			`<p>Aside from Gutenprint, Mini-XML is used for the`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`following projects/software applications:</p>`

			`<ul>`

Doco updates. 2010-09-19 08:50:54 +00:00			`<li><a href="http://www.cups.org/">CUPS</a></li>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
			`<li><a`
Doco updates. 2010-09-19 08:50:54 +00:00			`href="http://zynaddsubfx.sourceforge.net">ZynAddSubFX</a></li>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
			`</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>`

Update documentation. 2009-05-17 06:04:58 +00:00			`<!-- NEED 1in -->`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`<h2>Organization of This Document</h2>`

			`<p>This manual is organized into the following chapters and`
			`appendices:</p>`

			`<ul>`

Doco updates. 2010-09-19 08:50:54 +00:00			`<li>Chapter 1, "<a href="#INSTALL">Building,`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`Installing, and Packaging Mini-XML</a>", provides`
			`compilation, installation, and packaging instructions for`
			`Mini-XML.</li>`

Doco updates. 2010-09-19 08:50:54 +00:00			`<li>Chapter 2, "<a href="#BASICS">Getting`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`Started with Mini-XML</a>", shows how to use the`
			`Mini-XML library in your programs.</li>`

Doco updates. 2010-09-19 08:50:54 +00:00			`<li>Chapter 3, "<a href="#ADVANCED">More`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`Mini-XML Programming Techniques</a>", shows additional`
			`ways to use the Mini-XML library.</li>`

Doco updates. 2010-09-19 08:50:54 +00:00			`<li>Chapter 4, "<a href="#MXMLDOC">Using the`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`mxmldoc Utility</a>", describes how to use the`
			`<tt>mxmldoc(1)</tt> program to generate software`
			`documentation.</li>`

Doco updates. 2010-09-19 08:50:54 +00:00			`<li>Appendix A, "<a href="#LICENSE">Mini-XML License</a>",`
Save work on documentation. Add SAX load APIs. Add man page output for mxmldoc. Add types for various callback functions. 2007-04-23 21:48:03 +00:00			`provides the terms and conditions for using and distributing`
			`Mini-XML.</li>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
Doco updates. 2010-09-19 08:50:54 +00:00			`<li>Appendix B, "<a href="#RELNOTES">Release Notes</a>",`
Forgot to commit... 2004-05-21 02:06:04 +00:00			`lists the changes in each release of Mini-XML.</li>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
Doco updates. 2010-09-19 08:50:54 +00:00			`<li>Appendix C, "<a href="#REFERENCE">Library`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`Reference</a>", contains a complete reference for`
			`Mini-XML, generated by <tt>mxmldoc</tt>.</li>`

Doco updates. 2010-09-19 08:50:54 +00:00			`<li>Appendix D, "<a href="#SCHEMA">XML Schema</a>", shows`
Don't install or create formatted man pages. New logo. Documentation updates. 2007-04-26 22:21:37 +00:00			`the XML schema used for the XML files produced by`
			`<tt>mxmldoc</tt>.</li>`

More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`</ul>`

Save documentation updates. 2007-04-18 19:25:26 +00:00			`<!-- NEED 10 -->`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`<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>`

Save documentation updates. 2007-04-18 19:25:26 +00:00			`<dl>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
Don't embed links or other markup in title attributes. Update copyright/license stuff. 2009-01-13 08:13:46 +00:00			`<dt><code>mxmldoc</code><br>`
			`<code>mxmldoc(1)</code></dt>`
Save documentation updates. 2007-04-18 19:25:26 +00:00
			`<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>`
Don't embed links or other markup in title attributes. Update copyright/license stuff. 2009-01-13 08:13:46 +00:00			`<var>/etc/hosts</var></dt>`
Save documentation updates. 2007-04-18 19:25:26 +00:00
			`<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 -->`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`<h2>Abbreviations</h2>`

			`<p>The following abbreviations are used throughout this`
			`manual:</p>`

			`<dl>`

			`<dt>Gb</dt>`
Save documentation updates. 2007-04-18 19:25:26 +00:00			`<dd>Gigabytes, or 1073741824 bytes<br><br></dd>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
			`<dt>kb</dt>`
Save documentation updates. 2007-04-18 19:25:26 +00:00			`<dd>Kilobytes, or 1024 bytes<br><br></dd>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
			`<dt>Mb</dt>`
Save documentation updates. 2007-04-18 19:25:26 +00:00			`<dd>Megabytes, or 1048576 bytes<br><br></dd>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
			`<dt>UTF-8, UTF-16</dt>`
Save documentation updates. 2007-04-18 19:25:26 +00:00			`<dd>Unicode Transformation Format, 8-bit or 16-bit<br><br></dd>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
			`<dt>W3C</dt>`
Save documentation updates. 2007-04-18 19:25:26 +00:00			`<dd>World Wide Web Consortium<br><br></dd>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
			`<dt>XML</dt>`
Save documentation updates. 2007-04-18 19:25:26 +00:00			`<dd>Extensible Markup Language<br><br></dd>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
			`</dl>`

Save documentation updates. 2007-04-18 19:25:26 +00:00			`<!-- NEED 12 -->`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`<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`
Save documentation updates. 2007-04-18 19:25:26 +00:00			`used for XML.<br><br></dd>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
			`<dt><a`
Doco updates. 2010-09-19 08:50:54 +00:00			`href="http://www.w3.org/TR/2004/REC-xml-20040204/">Extensible`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00			`Markup Language (XML) 1.0 (Third Edition)</a></dt>`

			`<dd>The XML specification from the World Wide Web`
Save documentation updates. 2007-04-18 19:25:26 +00:00			`Consortium (W3C)<br><br></dd>`
More documentation fun. Move version definition to configure script. Add XML schema for the mxmldoc output. 2004-05-02 16:04:40 +00:00
			`</dl>`
Start with new docos. 2004-05-01 23:41:52 +00:00
Don't install or create formatted man pages. New logo. Documentation updates. 2007-04-26 22:21:37 +00:00			`<!-- NEED 6 -->`
			`<h2>Legal Stuff</h2>`

Implemment getters for all of mxml_node_t and mxml_index_t fields (STR #118) Make mxml_node_s and mxml_index_s private (but still in the public header for 2.x). 2011-01-01 23:42:17 +00:00			`<p>The Mini-XML library is copyright 2003-2011 by Michael Sweet. License terms`
Doco updates. 2010-09-19 08:50:54 +00:00			`are described in <a href="#LICENSE">Appendix A - Mini-XML License</a>.</p>`
Don't install or create formatted man pages. New logo. Documentation updates. 2007-04-26 22:21:37 +00:00
Start with new docos. 2004-05-01 23:41:52 +00:00			`</body>`
			`</html>`