# Introduction

This programmers manual describes Mini-XML version 2.2.1, a small XML parsing library that you can use to read and write XML and XML-like data files in your application without requiring large non-standard libraries. Mini-XML only requires an ANSI C compatible compiler (GCC works, as do most vendors' ANSI C compilers) and a "make" program.

Mini-XML provides the following functionality:

- Reading of UTF-8 and UTF-16 encoded XML files and strings.
- Writing of UTF-8 encoded XML files and strings.
- Data is stored in a linked-list tree structure, preserving the XML data hierarchy.
- Supports arbitrary element names, attributes, and attribute values with no preset limits, just available memory.
- Supports integer, real, opaque ("cdata"), and text data types in "leaf" nodes.
- Functions for creating and managing trees of data.
- "Find" and "walk" functions for easily locating and navigating trees of data.

Mini-XML doesn't do validation or other types of processing on the data based upon schema files or other sources of definition information, nor does it support character entities other than those required by the XML specification.

## Legal Stuff

The Mini-XML library is copyright 2003-2005 by Michael Sweet.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

## History

Mini-XML was initially developed for the Gimp-Print project to replace the rather large and unwieldy `libxml2` 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:

> It's bad enough that we require libxml2, but rolling our own XML parser is a bit more than we can handle.

I then replied with:

> 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.

I took my own challenge and coded furiously for two days to produced the initial public release of Mini-XML, total lines of code: 696. Robert promptly integrated Mini-XML into Gimp-Print and removed libxml2.

Thanks to lots of feedback and support from various developers, Mini-XML has evolved since then to provide a more complete XML implementation and now stands at a whopping 2,974 lines of code, compared to 103,893 lines of code for libxml2 version 2.6.9. Aside from Gimp-Print, Mini-XML is used for the following projects/software applications:

- Common UNIX Printing System
- CUPS Driver Development Kit
- ESP Print Pro
- ZynAddSubFX

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.

## Organization of This Document

This manual is organized into the following chapters and appendices:

- Chapter 1, "Building, Installing, and Packaging Mini-XML", provides compilation, installation, and packaging instructions for Mini-XML.
- Chapter 2, "Getting Started with Mini-XML", shows how to use the Mini-XML library in your programs.
- Chapter 3, "More Mini-XML Programming Techniques", shows additional ways to use the Mini-XML library.
- Chapter 4, "Using the mxmldoc Utility", describes how to use the `mxmldoc(1)` program to generate software documentation.
- Appendix A, "GNU Library General Public License", provides the terms and conditions for using and distributing Mini-XML.
- Appendix B, "Release Notes", lists the changes in each release of Mini-XML.
- Appendix C, "Library Reference", contains a complete reference for Mini-XML, generated by `mxmldoc`.

## Notation Conventions

Various font and syntax conventions are used in this guide. Examples and their meanings and uses are explained below:

Example |  | Description
`lpstat` `lpstat(1)` |  | The names of commands; the first mention of a command or function in a chapter is followed by a manual page section number.
/var /usr/share/cups/data/testprint.ps |  | File and directory names.
`Request ID is Printer-123` |  | Screen output.
`lp -d printer filename ENTER` |  | Literal user input; special keys like `ENTER` are in ALL CAPS.
12.3 |  | Numbers in the text are written using the period (.) to indicate the decimal point.

## Abbreviations

The following abbreviations are used throughout this manual:

> Gb
>   Gigabytes, or 1073741824 bytes
> kb
>   Kilobytes, or 1024 bytes
> Mb
>   Megabytes, or 1048576 bytes
> UTF-8, UTF-16
>   Unicode Transformation Format, 8-bit or 16-bit
> W3C
>   World Wide Web Consortium
> XML
>   Extensible Markup Language

## Other References

> The Unicode Standard, Version 4.0, Addison-Wesley, ISBN 0-321-18578-1
>   The definition of the Unicode character set which is used for XML.
> Extensible Markup Language (XML) 1.0 (Third Edition)
>   The XML specification from the World Wide Web Consortium (W3C)