This programmers manual describes Mini-XML version 2.0, a small XML + parsing library that you can use to read and write XML and XML-like + data files in your application without requiring large non-standard + libraries. Mini-XML only requires an ANSI C compatible compiler (GCC + works, as do most vendors' ANSI C compilers) and a "make" program.
+Mini-XML provides the following functionality:
+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.
+ + +The Mini-XML library is copyright 2003-2004 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.
+ + +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,240 lines of code, + compared to 96,335 lines of code for libxml2 version 2.6.9. Aside from + Gimp-Print, Mini-XML is used for the following projects/software + applications:
+ +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.
+ + +This manual is organized into the following chapters and appendices:
+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. | |
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 +
+
++
+- 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) +
+
This chapter describes how to build, install, and package Mini-XML on + your system.
+Mini-XML comes with an autoconf-based configure script; just type the + following command to get things going:
++ ./configure ENTER ++
The default install prefix is /usr/local, which can be + overridden using the --prefix option:
++ ./configure --prefix=/foo ENTER ++
Other configure options can be found using the --help + option:
++ ./configure --help ENTER ++
Once you have configured the software, use the make(1) + program to do the build and run the test program to verify that things + are working, as follows:
++ make ENTER ++
Use the make command with the install target to + install Mini-XML in the configured directories:
++ make install ENTER ++
Mini-XML includes two files that can be used to create binary + packages. The first file is mxml.spec which is used by the +rpmbuild(8) software to create Red Hat Package Manager ("RPM") + packages which are commonly used on Linux. Since rpmbuild + wants to compile the software on its own, you can provide it with the + Mini-XML tar file to build the package:
++ rpmbuild -ta mxml-version.tar.gz ENTER ++
The second file is mxml.list which is used by the +epm(1) program to create software packages in a variety of formats. + The epm program is available from the following URL:
++ http://www.easysw.com/epm/ ++
Use the make command with the epm target to + create portable and native packages for your system:
++ make epm ENTER ++
The packages are stored in a subdirectory named dist for + your convenience. The portable packages utilize scripts and tar files + to install the software on the target system; this is especially useful + when installing on systems with different Linux distributions. Use the + mxml.install script to install the software and mxml.remove + script to remove the software.
+The native packages will be in the local OS's native format: RPM for + Red Hat Linux, DPKG for Debian Linux, PKG for Solaris, and so forth. + Use the corresponding commands to install the native packages.
This chapter describes how to write programs that use Mini-XML to + access data in an XML file.
+Mini-XML provides a single header file which you include:
++ #include <mxml.h> ++
The Mini-XML library is included with your program using the +-lmxml option:
++ gcc -o myprogram myprogram.c -lmxml ENTER ++
If you have the pkg-config(1) software installed, you can + use it to determine the proper compiler and linker options for your + installation:
++ pkg-config --cflags mxml ENTER + pkg-config --libs mxml ENTER ++
Every piece of information in an XML file (elements, text, numbers) + is stored in memory in "nodes". Nodes are defined by the +mxml_node_t structure. The type + member defines the node type (element, integer, opaque, real, or + text) which determines which value you want to look at in the +value union.
+New nodes can be created using the +mxmlNewElement(), +mxmlNewInteger(), mxmlNewOpaque() +, mxmlNewReal(), and +mxmlNewText() functions. Only elements can have child + nodes, and the top node must be an element, usually "?xml".
+Each node has pointers for the node above (parent), below ( +child), to the left (prev), and to the right (next +) of the current node. If you have an XML file like the following:
++ <?xml version="1.0"?> + <data> + <node>val1</node> + <node>val2</node> + <node>val3</node> + <group> + <node>val4</node> + <node>val5</node> + <node>val6</node> + </group> + <node>val7</node> + <node>val8</node> + <node>val9</node> + </data> ++
the node tree returned by mxmlLoadFile() would look like the + following in memory:
++ ?xml + | + data + | + node - node - node - group - node - node - node + | | | | | | | + val1 val2 val3 | val7 val8 val9 + | + node - node - node + | | | + val4 val5 val6 ++
where "-" is a pointer to the next node and "|" is a pointer to the + first child node.
+Once you are done with the XML data, use the +mxmlDelete() function to recursively free the memory that is + used for a particular node or the entire tree:
++ mxmlDelete(tree); ++
You load an XML file using the +mxmlLoadFile() function:
++ FILE *fp; + mxml_node_t *tree; + + fp = fopen("filename.xml", "r"); + tree = mxmlLoadFile(NULL, fp, MXML_NO_CALLBACK); + fclose(fp); ++
The third argument specifies a callback function which returns the + value type of the immediate children for a new element node: +MXML_INTEGER, MXML_OPAQUE, MXML_REAL, or +MXML_TEXT. This function is called after the element and its + attributes have been read, so you can look at the element name, + attributes, and attribute values to determine the proper value type to + return. The default value type is MXML_TEXT if no callback is used.
+Similarly, you save an XML file using the +mxmlSaveFile() function:
++ FILE *fp; + mxml_node_t *tree; + + fp = fopen("filename.xml", "w"); + mxmlSaveFile(tree, fp, MXML_NO_CALLBACK); + fclose(fp); ++
Callback functions for saving are used to optionally insert + whitespace before and after elements in the node tree. Your function + will be called up to four times for each element node with a pointer to + the node and a "where" value of MXML_WS_BEFORE_OPEN, +MXML_WS_AFTER_OPEN, MXML_WS_BEFORE_CLOSE, or +MXML_WS_AFTER_CLOSE. The callback function should return NULL + if no whitespace should be added and the string to insert (spaces, + tabs, carriage returns, and newlines) otherwise.
+The mxmlLoadString(), +mxmlSaveAllocString(), and +mxmlSaveString() functions load XML node trees from and save + XML node trees to strings:
++ char buffer[8192]; + char *ptr; + mxml_node_t *tree; + + ... + tree = mxmlLoadString(NULL, buffer, MXML_NO_CALLBACK); + + ... + mxmlSaveString(tree, buffer, sizeof(buffer), MXML_NO_CALLBACK); + + ... + ptr = mxmlSaveAllocString(tree, MXML_NO_CALLBACK); ++
The mxmlWalkPrev() and +mxmlWalkNext()functions can be used to iterate through the + XML node tree:
++ mxml_node_t *node = mxmlWalkPrev(current, tree, MXML_DESCEND); + + mxml_node_t *node = mxmlWalkNext(current, tree, MXML_DESCEND); ++
In addition, you can find a named element/node using the +mxmlFindElement() function:
++ mxml_node_t *node = mxmlFindElement(tree, tree, "name", "attr", + "value", MXML_DESCEND); ++
The name, attr, and value arguments can be + passed as NULL to act as wildcards, e.g.:
++ /* Find the first "a" element */ + node = mxmlFindElement(tree, tree, "a", NULL, NULL, MXML_DESCEND); + + /* Find the first "a" element with "href" attribute */ + node = mxmlFindElement(tree, tree, "a", "href", NULL, MXML_DESCEND); + + /* Find the first "a" element with "href" to a URL */ + node = mxmlFindElement(tree, tree, "a", "href", + "http://www.easysw.com/~mike/mxml/", MXML_DESCEND); + + /* Find the first element with a "src" attribute*/ + node = mxmlFindElement(tree, tree, NULL, "src", NULL, MXML_DESCEND); + + /* Find the first element with a "src" = "foo.jpg" */ + node = mxmlFindElement(tree, tree, NULL, "src", "foo.jpg", MXML_DESCEND); ++
You can also iterate with the same function:
++ 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 ... + } ++
The MXML_DESCEND argument can actually be one of three + constants:
++ ?xml + data + node + val1 + node + val2 + node + val3 + group + node + val4 + node + val5 + node + val6 + node + val7 + node + val8 + node + val9 ++
If you started at "val9" and walked using mxmlWalkPrev(), + the order would be reversed, ending at "?xml".
+This chapter shows additional ways to use the Mini-XML library in + your programs.
+This chapter describes how to use the mxmldoc(1) utility that comes with Mini-XML to automatically generate documentation for your programs.
+The mxmldoc utility scans C and C++ source and header files + and produces an XML file describing the library interface and an XHTML + file providing a human-readable reference to the code. Each source and + header file must conform to some simple code commenting conventions so + that mxmldoc can extract the necessary descriptive text.
+The mxmldoc command requires the name of an XML file to + store the code information; this file is created and updated as + necessary. The XML file is optionally followed by a list of source + files to scan. After scanning any source files on the command-line, +mxmldoc writes XHTML documentation to the standard output, which + can be redirected to the file using the >filename syntax:
++ mxmldoc myfile.xml >myfile.html ENTER + mxmldoc myfile.xml file1.c file2.cxx file3.h >myfile.html ENTER ++
If no source files are provided on the command-line, the current + contents of the XML file are converted to XHTML.
+As noted previously, source code must be commented properly for +mxmldoc to generate correct documentation for the code. Single line + comments can use the C++ // comment sequence, however all + multi-line comments must use the C /* ... */ comment sequence.
+All implementations of functions and methods must begin with a + comment header describing what the function does, the possible input + limits (if any), and the possible output values (if any), and any + special information needed, as follows:
+
+ /*
+ * 'do_this()' - Compute y = this(x).
+ *
+ * Notes: none.
+ */
+
+ float /* O - Inverse power value, 0.0 <= y <= 1.1 */
+ do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */
+ {
+ ...
+ return (y);
+ }
+
+Return/output values are indicated using an "O" prefix, input values + are indicated using the "I" prefix, and values that are both input and + output use the "IO" prefix for the corresponding in-line comment.
+Each variable or member must be declared on a separate line and must + be immediately followed by a comment describing the variable or member, + as follows:
++ int this_variable; /* The current state of this */ + int that_variable; /* The current state of that */ ++
Each type must have a comment block immediately before the typedef, + as follows:
++ /* + * This type is for foobar options. + */ + typedef int this_type_t; ++ + +
Each class, structure, and union must have a comment block + immediately before the definition, and each member must be documented + in accordance with the function and variable documentation + requirements, as follows:
+
+ /*
+ * This structure is for foobar options.
+ */
+ struct this_struct_s
+ {
+ int this_member; /* Current state for this */
+ int that_member; /* Current state for that */
+ };
+
+ /*
+ * This class is for barfoo options.
+ */
+ class this_class_c
+ {
+ int this_member; /* Current state for this */
+ int that_member; /* Current state for that */
+
+ /*
+ * 'get_this()' - Get the current state for this.
+ */
+ int /* O - Current state for this */
+ get_this()
+ {
+ return (this_member);
+ }
+ };
+
+Each enumeration must have a comment block immediately before the + definition describing what the enumeration is for, and each enumeration + value must have a comment immediately after the value, as follows:
+
+ /*
+ * Enumeration of media trays.
+ */
+ enum this_enum_e
+ {
+ THIS_TRAY, /* This tray */
+ THAT_TRAY /* That tray */
+ };
+
+
+
+Listing 4-1 shows the XML schema file mxmldoc.xsd which is + included with Mini-XML. This schema file can be used to convert the XML + files produced by mxmldoc into other formats.
+
++<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> + <xsd:annotation> + <xsd:documentation xml:lang="en"> + Mini-XML 2.0 documentation schema for mxmldoc output. + Copyright 2003-2004 by Michael Sweet. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + </xsd:documentation> + </xsd:annotation> + + <!-- basic element definitions --> + <xsd:element name="argument" type="argumentType"/> + <xsd:element name="class" type="classType"/> + <xsd:element name="constant" type="constantType"/> + <xsd:element name="description" type="xsd:string"/> + <xsd:element name="enumeration" type="enumerationType"/> + <xsd:element name="function" type="functionType"/> + <xsd:element name="mxmldoc" type="mxmldocType"/> + <xsd:element name="namespace" type="namespaceType"/> + <xsd:element name="returnvalue" type="returnvalueType"/> + <xsd:element name="seealso" type="identifierList"/> + <xsd:element name="struct" type="structType"/> + <xsd:element name="typedef" type="typedefType"/> + <xsd:element name="type" type="xsd:string"/> + <xsd:element name="union" type="unionType"/> + <xsd:element name="variable" type="variableType"/> + + <!-- descriptions of complex elements --> + <xsd:complexType name="argumentType"> + <xsd:sequence> + <xsd:element ref="type" minOccurs="1" maxOccurs="1"/> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + </xsd:sequence> + <xsd:attribute name="default" type="xsd:string" use="optional"/> + <xsd:attribute name="name" type="identifier" use="required"/> + <xsd:attribute name="direction" type="direction" use="optional" default="I"/> + </xsd:complexType> + + <xsd:complexType name="classType"> + <xsd:sequence> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + <xsd:choice minOccurs="0" maxOccurs="unbounded"> + <xsd:element ref="class"/> ++ |
++ <xsd:element ref="enumeration"/> + <xsd:element ref="function"/> + <xsd:element ref="struct"/> + <xsd:element ref="typedef"/> + <xsd:element ref="union"/> + <xsd:element ref="variable"/> + </xsd:choice> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + <xsd:attribute name="parent" type="xsd:string" use="optional"/> + </xsd:complexType> + + <xsd:complexType name="constantType"> + <xsd:sequence> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + </xsd:complexType> + + <xsd:complexType name="enumerationType"> + <xsd:sequence> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + <xsd:element ref="constant" minOccurs="1" maxOccurs="unbounded"/> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + </xsd:complexType> + + <xsd:complexType name="functionType"> + <xsd:sequence> + <xsd:element ref="returnvalue" minOccurs="0" maxOccurs="1"/> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + <xsd:element ref="argument" minOccurs="1" maxOccurs="unbounded"/> + <xsd:element ref="seealso" minOccurs="0" maxOccurs="1"/> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + <xsd:attribute name="scope" type="scope" use="optional"/> + </xsd:complexType> + + <xsd:complexType name="mxmldocType"> + <xsd:choice minOccurs="0" maxOccurs="unbounded"> + <xsd:element ref="class"/> + <xsd:element ref="enumeration"/> + <xsd:element ref="function"/> + <xsd:element ref="namespace"/> + <xsd:element ref="struct"/> + <xsd:element ref="typedef"/> + <xsd:element ref="union"/> + <xsd:element ref="variable"/> + </xsd:choice> + </xsd:complexType> + + <xsd:complexType name="namespaceType"> + <xsd:sequence> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + <xsd:choice minOccurs="0" maxOccurs="unbounded"> + <xsd:element ref="class"/> + <xsd:element ref="enumeration"/> + <xsd:element ref="function"/> ++ |
++ <xsd:element ref="struct"/> + <xsd:element ref="typedef"/> + <xsd:element ref="union"/> + <xsd:element ref="variable"/> + </xsd:choice> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + </xsd:complexType> + + <xsd:complexType name="returnvalueType"> + <xsd:sequence> + <xsd:element ref="type" minOccurs="1" maxOccurs="1"/> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + </xsd:sequence> + </xsd:complexType> + + <xsd:complexType name="structType"> + <xsd:sequence> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + <xsd:choice minOccurs="0" maxOccurs="unbounded"> + <xsd:element ref="variable"/> + <xsd:element ref="function"/> + </xsd:choice> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + </xsd:complexType> + + <xsd:complexType name="typedefType"> + <xsd:sequence> + <xsd:element ref="type" minOccurs="1" maxOccurs="1"/> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + </xsd:complexType> + + <xsd:complexType name="unionType"> + <xsd:sequence> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + <xsd:element ref="variable" minOccurs="0" maxOccurs="unbounded"/> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + </xsd:complexType> + + <xsd:complexType name="variableType"> + <xsd:sequence> + <xsd:element ref="type" minOccurs="1" maxOccurs="1"/> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + </xsd:complexType> + + <!-- data types --> + <xsd:simpleType name="direction"> + <xsd:restriction base="xsd:string"> + <xsd:enumeration value="I"/> + <xsd:enumeration value="O"/> + <xsd:enumeration value="IO"/> + </xsd:restriction> ++ |
++ </xsd:simpleType> + + <xsd:simpleType name="identifier"> + <xsd:restriction base="xsd:string"> + <xsd:pattern value="[a-zA-Z_(.]([a-zA-Z_(.,)* 0-9])*"/> + </xsd:restriction> + </xsd:simpleType> + + <xsd:simpleType name="identifierList"> + <xsd:list itemType="identifier"/> + </xsd:simpleType> + + <xsd:simpleType name="scope"> + <xsd:restriction base="xsd:string"> + <xsd:enumeration value=""/> + <xsd:enumeration value="private"/> + <xsd:enumeration value="protected"/> + <xsd:enumeration value="public"/> + </xsd:restriction> + </xsd:simpleType> +</xsd:schema> ++ |
The mxmldoc utility scans C and C++ source and header files and produces an XML file describing the library interface and an XHTML file providing a human-readable reference -to the code.
+to the code. Each source and header file must conform to some +simple code commenting conventions so that mxmldoc can +extract the necessary descriptive text. -The following poor-man's schema describes the format of the -XML files produced by mxmldoc: +
The mxmldoc command requires the name of an XML file +to store the code information; this file is created and updated +as necessary. The XML file is optionally followed by a list of +source files to scan. After scanning any source files on the +command-line, mxmldoc writes XHTML documentation to the +standard output, which can be redirected to the file using the +>filename syntax:
- <?xml version="1.0"?> - <namespace name=""> [optional...] - <constant name=""> - <description>descriptive text</description> - </constant> - - <enumeration name=""> - <constant name="">...</constant> - </enumeration> - - <typedef name=""> - <description>descriptive text</description> - <type>type string</type> - </typedef> - - <function name="" scope=""> - <description>descriptive text</description> - <argument name="" direction="I|O|IO" default=""> - <description>descriptive text</description> - <type>type string</type> - </argument> - <returnvalue> - <description>descriptive text</description> - <type>type string</type> - </returnvalue> - <seealso>function names separated by spaces</seealso> - </function> - - <variable name="" scope=""> - <description>descriptive text</description> - <type>type string</type> - </variable> - - <struct name=""> - <description>descriptive text</description> - <variable name="">...</variable> - <function name="">...</function> - </struct> - - <union name=""> - <description>descriptive text</description> - <variable name="">...</variable> - </union> - - <class name="" parent=""> - <description>descriptive text</description> - <class name="">...</class> - <enumeration name="">...</enumeration> - <function name="">...</function> - <struct name="">...</struct> - <variable name="">...</variable> - </class> - </namespace> + mxmldoc myfile.xml >myfile.html ENTER + mxmldoc myfile.xml file1.c file2.cxx file3.h >myfile.html ENTER+
If no source files are provided on the command-line, the +current contents of the XML file are converted to XHTML.
+ +As noted previously, source code must be commented properly +for mxmldoc to generate correct documentation for the +code. Single line comments can use the C++ // comment +sequence, however all multi-line comments must use the C /* +... */ comment sequence.
+ +All implementations of functions and methods must begin with +a comment header describing what the function does, the possible +input limits (if any), and the possible output values (if any), +and any special information needed, as follows:
+ +
+ /*
+ * 'do_this()' - Compute y = this(x).
+ *
+ * Notes: none.
+ */
+
+ float /* O - Inverse power value, 0.0 <= y <= 1.1 */
+ do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */
+ {
+ ...
+ return (y);
+ }
+
+
+Return/output values are indicated using an "O" prefix, input +values are indicated using the "I" prefix, and values that are +both input and output use the "IO" prefix for the corresponding +in-line comment.
+ +Each variable or member must be declared on a separate line +and must be immediately followed by a comment describing the +variable or member, as follows:
+ ++ int this_variable; /* The current state of this */ + int that_variable; /* The current state of that */ ++ +
Each type must have a comment block immediately before the +typedef, as follows:
+ ++ /* + * This type is for foobar options. + */ + typedef int this_type_t; ++ + +
Each class, structure, and union must have a comment block +immediately before the definition, and each member must be documented +in accordance with the function and variable documentation +requirements, as follows:
+ +
+ /*
+ * This structure is for foobar options.
+ */
+ struct this_struct_s
+ {
+ int this_member; /* Current state for this */
+ int that_member; /* Current state for that */
+ };
+
+ /*
+ * This class is for barfoo options.
+ */
+ class this_class_c
+ {
+ int this_member; /* Current state for this */
+ int that_member; /* Current state for that */
+
+ /*
+ * 'get_this()' - Get the current state for this.
+ */
+ int /* O - Current state for this */
+ get_this()
+ {
+ return (this_member);
+ }
+ };
+
+
+Each enumeration must have a comment block immediately before +the definition describing what the enumeration is for, and each +enumeration value must have a comment immediately after the +value, as follows:
+ +
+ /*
+ * Enumeration of media trays.
+ */
+ enum this_enum_e
+ {
+ THIS_TRAY, /* This tray */
+ THAT_TRAY /* That tray */
+ };
+
+
+
+Listing 4-1 shows the XML schema file mxmldoc.xsd +which is included with Mini-XML. This schema file can be used to +convert the XML files produced by mxmldoc into other +formats.
+ +
++<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> + <xsd:annotation> + <xsd:documentation xml:lang="en"> + Mini-XML 2.0 documentation schema for mxmldoc output. + Copyright 2003-2004 by Michael Sweet. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + </xsd:documentation> + </xsd:annotation> + + <!-- basic element definitions --> + <xsd:element name="argument" type="argumentType"/> + <xsd:element name="class" type="classType"/> + <xsd:element name="constant" type="constantType"/> + <xsd:element name="description" type="xsd:string"/> + <xsd:element name="enumeration" type="enumerationType"/> + <xsd:element name="function" type="functionType"/> + <xsd:element name="mxmldoc" type="mxmldocType"/> + <xsd:element name="namespace" type="namespaceType"/> + <xsd:element name="returnvalue" type="returnvalueType"/> + <xsd:element name="seealso" type="identifierList"/> + <xsd:element name="struct" type="structType"/> + <xsd:element name="typedef" type="typedefType"/> + <xsd:element name="type" type="xsd:string"/> + <xsd:element name="union" type="unionType"/> + <xsd:element name="variable" type="variableType"/> + + <!-- descriptions of complex elements --> + <xsd:complexType name="argumentType"> + <xsd:sequence> + <xsd:element ref="type" minOccurs="1" maxOccurs="1"/> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + </xsd:sequence> + <xsd:attribute name="default" type="xsd:string" use="optional"/> + <xsd:attribute name="name" type="identifier" use="required"/> + <xsd:attribute name="direction" type="direction" use="optional" default="I"/> + </xsd:complexType> + + <xsd:complexType name="classType"> + <xsd:sequence> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + <xsd:choice minOccurs="0" maxOccurs="unbounded"> + <xsd:element ref="class"/> ++ |
++ <xsd:element ref="enumeration"/> + <xsd:element ref="function"/> + <xsd:element ref="struct"/> + <xsd:element ref="typedef"/> + <xsd:element ref="union"/> + <xsd:element ref="variable"/> + </xsd:choice> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + <xsd:attribute name="parent" type="xsd:string" use="optional"/> + </xsd:complexType> + + <xsd:complexType name="constantType"> + <xsd:sequence> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + </xsd:complexType> + + <xsd:complexType name="enumerationType"> + <xsd:sequence> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + <xsd:element ref="constant" minOccurs="1" maxOccurs="unbounded"/> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + </xsd:complexType> + + <xsd:complexType name="functionType"> + <xsd:sequence> + <xsd:element ref="returnvalue" minOccurs="0" maxOccurs="1"/> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + <xsd:element ref="argument" minOccurs="1" maxOccurs="unbounded"/> + <xsd:element ref="seealso" minOccurs="0" maxOccurs="1"/> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + <xsd:attribute name="scope" type="scope" use="optional"/> + </xsd:complexType> + + <xsd:complexType name="mxmldocType"> + <xsd:choice minOccurs="0" maxOccurs="unbounded"> + <xsd:element ref="class"/> + <xsd:element ref="enumeration"/> + <xsd:element ref="function"/> + <xsd:element ref="namespace"/> + <xsd:element ref="struct"/> + <xsd:element ref="typedef"/> + <xsd:element ref="union"/> + <xsd:element ref="variable"/> + </xsd:choice> + </xsd:complexType> + + <xsd:complexType name="namespaceType"> + <xsd:sequence> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + <xsd:choice minOccurs="0" maxOccurs="unbounded"> + <xsd:element ref="class"/> + <xsd:element ref="enumeration"/> + <xsd:element ref="function"/> ++ |
++ <xsd:element ref="struct"/> + <xsd:element ref="typedef"/> + <xsd:element ref="union"/> + <xsd:element ref="variable"/> + </xsd:choice> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + </xsd:complexType> + + <xsd:complexType name="returnvalueType"> + <xsd:sequence> + <xsd:element ref="type" minOccurs="1" maxOccurs="1"/> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + </xsd:sequence> + </xsd:complexType> + + <xsd:complexType name="structType"> + <xsd:sequence> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + <xsd:choice minOccurs="0" maxOccurs="unbounded"> + <xsd:element ref="variable"/> + <xsd:element ref="function"/> + </xsd:choice> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + </xsd:complexType> + + <xsd:complexType name="typedefType"> + <xsd:sequence> + <xsd:element ref="type" minOccurs="1" maxOccurs="1"/> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + </xsd:complexType> + + <xsd:complexType name="unionType"> + <xsd:sequence> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + <xsd:element ref="variable" minOccurs="0" maxOccurs="unbounded"/> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + </xsd:complexType> + + <xsd:complexType name="variableType"> + <xsd:sequence> + <xsd:element ref="type" minOccurs="1" maxOccurs="1"/> + <xsd:element ref="description" minOccurs="0" maxOccurs="1"/> + </xsd:sequence> + <xsd:attribute name="name" type="identifier" use="required"/> + </xsd:complexType> + + <!-- data types --> + <xsd:simpleType name="direction"> + <xsd:restriction base="xsd:string"> + <xsd:enumeration value="I"/> + <xsd:enumeration value="O"/> + <xsd:enumeration value="IO"/> + </xsd:restriction> ++ |
++ </xsd:simpleType> + + <xsd:simpleType name="identifier"> + <xsd:restriction base="xsd:string"> + <xsd:pattern value="[a-zA-Z_(.]([a-zA-Z_(.,)* 0-9])*"/> + </xsd:restriction> + </xsd:simpleType> + + <xsd:simpleType name="identifierList"> + <xsd:list itemType="identifier"/> + </xsd:simpleType> + + <xsd:simpleType name="scope"> + <xsd:restriction base="xsd:string"> + <xsd:enumeration value=""/> + <xsd:enumeration value="private"/> + <xsd:enumeration value="protected"/> + <xsd:enumeration value="public"/> + </xsd:restriction> + </xsd:simpleType> +</xsd:schema> ++ |