-
Mini-XML Programmers Manual, Version 2.2.3
+
+
Mini-XML Programmers Manual, Version 2.3
Michael Sweet
Copyright 2003-2005
-
-
- Changes in Mini-XML 2.2.3 -
- Changes in Mini-XML 2.2.2 -
- Changes in Mini-XML 2.2.1 -
- Changes in Mini-XML 2.2 -
- Changes in Mini-XML 2.1 -
- Changes in Mini-XML 2.0 -
- Changes in Mini-XML 1.3 -
- Changes in Mini-XML 1.2 -
- Changes in Mini-XML 1.1.2 -
- Changes in Mini-XML 1.1.1 -
- Changes in Mini-XML 1.1 -
- Changes in Mini-XML 1.0 -
- Changes in Mini-XML 0.93 -
- Changes in Mini-XML 0.92 -
- Changes in Mini-XML 0.91 -
- Changes in Mini-XML 0.9 +
- Changes in Mini-XML 2.3 +
- Changes in Mini-XML 2.2.2 +
- Changes in Mini-XML 2.2.1 +
- Changes in Mini-XML 2.2 +
- Changes in Mini-XML 2.1 +
- Changes in Mini-XML 2.0 +
- Changes in Mini-XML 1.3 +
- Changes in Mini-XML 1.2 +
- Changes in Mini-XML 1.1.2 +
- Changes in Mini-XML 1.1.1 +
- Changes in Mini-XML 1.1 +
- Changes in Mini-XML 1.0 +
- Changes in Mini-XML 0.93 +
- Changes in Mini-XML 0.92 +
- Changes in Mini-XML 0.91 +
- Changes in Mini-XML 0.9
-
-
- Contents -
- Enumerations +
- Contents +
- Enumerations -
- Functions +
- Functions
- mxmlAdd()
- mxmlDelete() @@ -127,8 +116,8 @@ Copyright 2003-2005
- mxmlLoadFd()
- mxmlLoadFile()
- mxmlLoadString() -
- mxmlNewCDATA() -
- mxmlNewCustom() +
- Mini-XML 2.3 mxmlNewCDATA() +
- Mini-XML 2.1 mxmlNewCustom()
- mxmlNewElement()
- mxmlNewInteger()
- mxmlNewOpaque() @@ -140,8 +129,8 @@ Copyright 2003-2005
- mxmlSaveFd()
- mxmlSaveFile()
- mxmlSaveString() -
- mxmlSetCDATA() -
- mxmlSetCustom() +
- Mini-XML 2.3 mxmlSetCDATA() +
- Mini-XML 2.1 mxmlSetCustom()
- mxmlSetCustomHandlers()
- mxmlSetElement()
- mxmlSetErrorCallback() @@ -154,20 +143,22 @@ Copyright 2003-2005
- mxmlWalkPrev()
- - Structures +
- Structures -
- Types +
- Types
- mxml_attr_t -
- mxml_custom_t +
- mxml_custom_load_cb_t +
- mxml_custom_save_cb_t +
- Mini-XML 2.1 mxml_custom_t
- mxml_element_t
- mxml_index_t
- mxml_node_t @@ -175,7 +166,7 @@ Copyright 2003-2005
- mxml_value_t
- - Unions +
- Unions
@@ -183,7 +174,7 @@ Copyright 2003-2005
Introduction
-This programmers manual describes Mini-XML version 2.2.3, a small XML +
This programmers manual describes Mini-XML version 2.3, 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 @@ -1053,364 +1044,63 @@ mxmlIndexEnum.
mxmlIndexDelete(ind);-
4 - Using the mxmldoc Utility
-This chapter describes how to use the mxmldoc(1) utility - that comes with Mini-XML to automatically generate documentation for - your programs.
-The Basics
-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.
-Code Documentation Conventions
-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.
-Functions and Methods
-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.
-Variables and Class/Structure/Union Members
-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 */ --
Types
-Each type must have a comment block immediately before the typedef, - as follows:
-- /* - * This type is for foobar options. - */ - typedef int this_type_t; -- - -
Classes, Structures, and Unions
-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);
- }
- };
-
-Enumerations
-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 */
- };
-
-
-
-XML Schema
-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.2 documentation schema for mxmldoc output. - Copyright 2003-2005 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> -- |
-
A - GNU Library General Public - License
+ + + +mxmldoc(1)
+Name
+ mxmldoc - mini-xml documentation generator +Synopsis
+ mxmldoc [ --intro introfile.html ] [ --section section + ] [ --title title ] [ filename.xml ] [ source file(s) + ] > filename.html +Description
+ mxmldoc scans the specified C and C++ source files to produce an + XML representation of globally accessible classes, constants, + enumerations, functions, structures, typedefs, unions, and variables. + The XML file is updated as necessary and a HTML representation of the + XML file is written to the standard output. If no source files are + specified then the current XML file is converted to HTML on the + standard output. +In general, any C or C++ source code is handled by mxmldoc, + however it was specifically written to handle code with documentation + that is formatted according to the CUPS Configuration Management Plan + which is available at "http://www.cups.org/documentation.php".
+Options
+-
+
- --intro introfile.html +
- Inserts the specified file at the top of the output documentation. +
- --section section +
- Sets the section/keywords in the output documentation. +
- --title title +
- Sets the title of the output documentation. +
See Also
+ mxml(3), Mini-XML Programmers Manual, http://www.easysw.com/~mike/mxml/ +Copyright
+ Copyright 2003-2005 by Michael Sweet.+
A - Mini-XML License
+October 18, 2005
+The Mini-XML library and included programs are provided under the + terms of the GNU Library General Public License (LGPL) with the + following exceptions:
+-
+
- 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.
+
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 + LGPL in sections 1, 2, and 4.
+
+ - 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 LGPL. +
+
GNU LIBRARY GENERAL PUBLIC LICENSE
Version 2, June 1991
Copyright (C) 1991 Free Software Foundation, Inc.
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
@@ -1784,7 +1474,7 @@ mxmldoc to generate correct documentation for the code. Single line
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
END OF TERMS AND CONDITIONS
-How to Apply These Terms to Your New Libraries
+How to Apply These Terms to Your New Libraries
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 @@ -1829,9 +1519,18 @@ Ty Coon, President of Vice
That's all there is to it!
B - Release Notes
-Changes in Mini-XML 2.2.3
+Changes in Mini-XML 2.3
-
-
- The mxmldoc program now supports --title and --intro options. +
- Added two exceptions to the LGPL to support static linking of + applications against Mini-XML. +
- The mxmldoc program now generates correct HTML 4.0 output + (previously it generated invalid XHTML...) +
- The mxmldoc program now supports "@deprecated@, "@private@", and + "@since version@" comments. +
- Fixed function and enumeraion type bugs in mxmldoc. +
- Fixed XML schema for mxmldoc. +
- The mxmldoc program now supports --intro, --section, and --title + options.
- The mxmlLoad*() functions could leak a node on an error (STR #27)
- The mxml_vsnprintf() function could get in an infinite loop on a buffer overflow (STR #25) @@ -1842,12 +1541,12 @@ Ty Coon, President of Vice
- mxmlLoad*() did not treat custom data as opaque, so whitespace characters would be lost.
Changes in Mini-XML 2.2.2
+Changes in Mini-XML 2.2.2
- mxmlLoad*() did not treat custom data as opaque, so whitespace characters would be lost.
Changes in Mini-XML 2.2.1
+Changes in Mini-XML 2.2.1
- mxmlLoadFd(), mxmlLoadFile(), and mxmlLoadString() now correctly return NULL on error (STR #21) @@ -1858,7 +1557,7 @@ Ty Coon, President of Vice proper permissions on UNIX/Linux/OSX.
- Fixed a MingW/Cygwin compilation problem (STR #18)
Changes in Mini-XML 2.2
+Changes in Mini-XML 2.2
- Added shared library support (STR #17)
- mxmlLoad*() now returns an error when an XML stream contains illegal @@ -1872,7 +1571,7 @@ Ty Coon, President of Vice
- Added checking for invalid comment termination ("--->" is not allowed)
Changes in Mini-XML 2.1
+Changes in Mini-XML 2.1
- Added support for custom data nodes (STR #6)
- Now treat UTF-8 sequences which are longer than necessary as an @@ -1883,7 +1582,7 @@ Ty Coon, President of Vice
- Added mxmlLoadFd() and mxmlSaveFd() functions.
- Fixed multi-word UTF-16 handling.
Changes in Mini-XML 2.0
+Changes in Mini-XML 2.0
- New programmers manual.
- Added Visual C++ project files for Microsoft Windows users. @@ -1916,7 +1615,7 @@ Ty Coon, President of Vice destination path and install path. This caused problems when building and installing with MingW.
Changes in Mini-XML 1.3
+Changes in Mini-XML 1.3
- Fixes for mxmldoc.
- Added support for reading standard HTML entity names. @@ -1932,7 +1631,7 @@ Ty Coon, President of Vice
- The load and save functions now properly handle quoted element and attribute name strings properly, e.g. for !DOCTYPE declarations.
Changes in Mini-XML 1.2
+Changes in Mini-XML 1.2
- Added new "set" methods to set the value of a node.
- Added new formatted text methods mxmlNewTextf() and mxmlSetTextf() @@ -1945,13 +1644,13 @@ Ty Coon, President of Vice
- Added --with/without-snprintf configure option to control the snprintf() and vsnprintf() function checks.
Changes in Mini-XML 1.1.2
+Changes in Mini-XML 1.1.2
- The mxml(3) man page wasn't updated for the string functions.
- mxmlSaveString() returned the wrong number of characters.
- mxml_add_char() updated the buffer pointer in the wrong place.
Changes in Mini-XML 1.1.1
+Changes in Mini-XML 1.1.1
- The private mxml_add_ch() function did not update the start-of-buffer pointer which could cause a crash when using @@ -1962,7 +1661,7 @@ Ty Coon, President of Vice
- Added a mxmlSaveAllocString() convenience function for saving an XML node tree to an allocated string.
Changes in Mini-XML 1.1
+Changes in Mini-XML 1.1
- The mxmlLoadFile() function now uses dynamically allocated string buffers for element names, attribute names, and attribute values. @@ -1974,7 +1673,7 @@ Ty Coon, President of Vice
- Add emulation of strdup() if the local platform does not provide the function.
Changes in Mini-XML 1.0
+Changes in Mini-XML 1.0
- The mxmldoc program now handles function arguments, structures, unions, enumerations, classes, and typedefs properly. @@ -1982,7 +1681,7 @@ Ty Coon, President of Vice code.
- Added man pages and packaging files.
Changes in Mini-XML 0.93
+Changes in Mini-XML 0.93
- New mxmldoc example program that is also used to create and update code documentation using XML and produce HTML reference pages. @@ -2007,57 +1706,59 @@ Ty Coon, President of Vice
- mxmlSaveFile() now supports a whitespace callback to provide more human-readable XML output under program control.
Changes in Mini-XML 0.92
+Changes in Mini-XML 0.92
- mxmlSaveFile() didn't return a value on success.
Changes in Mini-XML 0.91
+Changes in Mini-XML 0.91
- mxmlWalkNext() would go into an infinite loop.
Changes in Mini-XML 0.9
+Changes in Mini-XML 0.9
- Initial public release.
C - Library Reference
-Contents
+Contents
-
-
- Enumerations -
- Functions -
- Structures -
- Types -
- Unions +
- Enumerations +
- Functions +
- Structures +
- Types +
- Unions
Enumerations
+Enumerations
-mxml_type_e
-+
mxml_type_e
Description
The XML node type.
Values
- -| Name | Description |
|---|
| Name | Description |
|---|---|
| MXML_CUSTOM | Custom data |
| MXML_CUSTOM + + Mini-XML 2.1 | Custom data |
| MXML_ELEMENT | XML element with attributes |
| MXML_IGNORE | Ignore/throw away node |
| MXML_IGNORE + + Mini-XML 2.3 | Ignore/throw away node |
| MXML_INTEGER | Integer value |
| MXML_OPAQUE | Opaque string |
| MXML_REAL | Real value |
| MXML_TEXT | Text fragment |
Functions
+Functions
- mxmlAdd()
- mxmlDelete() @@ -2078,8 +1779,12 @@ Ty Coon, President of Vice
- mxmlLoadFd()
- mxmlLoadFile()
- mxmlLoadString() -
- mxmlNewCDATA() -
- mxmlNewCustom() +
- mxmlNewCDATA() + + Mini-XML 2.3 +
- mxmlNewCustom() + + Mini-XML 2.1
- mxmlNewElement()
- mxmlNewInteger()
- mxmlNewOpaque() @@ -2091,8 +1796,12 @@ Ty Coon, President of Vice
- mxmlSaveFd()
- mxmlSaveFile()
- mxmlSaveString() -
- mxmlSetCDATA() -
- mxmlSetCustom() +
- mxmlSetCDATA() + + Mini-XML 2.3 +
- mxmlSetCustom() + + Mini-XML 2.1
- mxmlSetCustomHandlers()
- mxmlSetElement() @@ -2107,8 +1816,7 @@ Ty Coon, President of Vice
mxmlAdd()
-+
mxmlAdd()
Description
Add a node to a tree. Adds the specified node to the parent. If the child argument is not NULL, puts the new node before or after the @@ -2127,10 +1835,10 @@ mxmlAdd( mxml_node_t * node);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| parent | Parent node |
| where | Where to add, MXML_ADD_BEFORE or @@ -2139,12 +1847,12 @@ mxmlAdd( MXML_ADD_TO_PARENT |
| node | Node to add |
Returns
Nothing.
-mxmlDelete()
-+
mxmlDelete()
Description
Delete a node and all of its children. If the specified node has a parent, this function first removes the node from its parent using the @@ -2156,19 +1864,19 @@ mxmlDelete( mxml_node_t * node);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Node to delete |
Returns
Nothing.
-mxmlElementGetAttr()
-+
mxmlElementGetAttr()
Description
Get an attribute. This function returns NULL if the node is not an element or the named attribute does not exist.
@@ -2180,20 +1888,20 @@ mxmlElementGetAttr( const char * name);Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Element node |
| name | Name of attribute |
Returns
Attribute value or NULL
-mxmlElementSetAttr()
-+
mxmlElementSetAttr()
Description
Set an attribute. If the named attribute already exists, the value of the attribute is replaced by the new string value. The string value is @@ -2208,44 +1916,36 @@ mxmlElementSetAttr( const char * value);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Element node |
| name | Name of attribute |
| value | Attribute value |
Returns
Nothing.
-mxmlEntityAddCallback()
-+
+mxmlEntityAddCallback()
Description
Add a callback to convert entities to Unicode.
Syntax
int -mxmlEntityAddCallback( - int (*cb)(const char *name)); +mxmlEntityAddCallback(void);
Arguments
- -| Name | Description |
|---|---|
| (*cb)(const char *name) | Callback function to - add |
None.
Returns
0 on success, -1 on failure
-mxmlEntityGetName()
-+
mxmlEntityGetName()
Description
Get the name that corresponds to the character value. If val does not need to be represented by a named entity, NULL is returned.
@@ -2256,19 +1956,19 @@ mxmlEntityGetName( int val);Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| val | Character value |
Returns
Entity name or NULL
-mxmlEntityGetValue()
-+
mxmlEntityGetValue()
Description
Get the character corresponding to a named entity. The entity name can also be a numeric constant. -1 is returned if the name is not @@ -2280,42 +1980,34 @@ mxmlEntityGetValue( const char * name);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| name | Entity name |
Returns
Character value or -1 on error
-mxmlEntityRemoveCallback()
-+
+mxmlEntityRemoveCallback()
Description
Remove a callback.
Syntax
void -mxmlEntityRemoveCallback( - int (*cb)(const char *name)); +mxmlEntityRemoveCallback(void);
Arguments
- -| Name | Description |
|---|---|
| (*cb)(const char *name) | Callback function to - remove |
None.
Returns
Nothing.
-mxmlFindElement()
-+
mxmlFindElement()
Description
Find the named element. The search is constrained by the name, attribute name, and value; any NULL names or values are treated as @@ -2338,10 +2030,10 @@ mxmlFindElement( int descend);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Current node |
| top | Top node |
| descend | Descend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST |
Returns
Element node or NULL
-mxmlIndexDelete()
-+
mxmlIndexDelete()
Description
Delete an index.
Syntax
@@ -2366,19 +2058,19 @@ mxmlIndexDelete( mxml_index_t * ind);Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| ind | Index to delete |
Returns
Nothing.
-mxmlIndexEnum()
-+
mxmlIndexEnum()
Description
Return the next node in the index. Nodes are returned in the sorted order of the index.
@@ -2389,19 +2081,19 @@ mxmlIndexEnum( mxml_index_t * ind);Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| ind | Index to enumerate |
Returns
Next node or NULL if there is none
-mxmlIndexFind()
-+
mxmlIndexFind()
Description
Find the next matching node. You should call mxmlIndexReset() prior to using this function for the first time with a particular set of @@ -2416,21 +2108,21 @@ mxmlIndexFind( const char * value);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| ind | Index to search |
| element | Element name to find, if any |
| value | Attribute value, if any |
Returns
Node or NULL if none found
-mxmlIndexNew()
-+
mxmlIndexNew()
Description
Create a new index. The index will contain all nodes that contain the named element and/or attribute. If both "element" and "attr" are NULL, @@ -2446,21 +2138,21 @@ mxmlIndexNew( const char * attr);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | XML node tree |
| element | Element to index or NULL for all |
| attr | Attribute to index or NULL for none |
Returns
New index
-mxmlIndexReset()
-+
mxmlIndexReset()
Description
Reset the enumeration/find pointer in the index and return the first node in the index. This function should be called prior to using @@ -2472,19 +2164,19 @@ mxmlIndexReset( mxml_index_t * ind);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| ind | Index to reset |
Returns
First node or NULL if there is none
-mxmlLoadFd()
-+
mxmlLoadFd()
Description
Load a file descriptor into an XML node tree. The nodes in the specified file are added to the specified top node. If no top node is @@ -2500,26 +2192,23 @@ mxmlIndexReset( mxml_node_t * mxmlLoadFd( mxml_node_t * top, - int fd, - mxml_type_t (*cb)(mxml_node_t *node)); + int fd);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| top | Top node |
| fd | File descriptor to read from |
| (*cb)(mxml_node_t *node) | Callback function or - MXML_NO_CALLBACK |
Returns
First node or NULL if the file could not be read.
-mxmlLoadFile()
-+
mxmlLoadFile()
Description
Load a file into an XML node tree. The nodes in the specified file are added to the specified top node. If no top node is provided, the @@ -2535,26 +2224,23 @@ mxmlLoadFd( mxml_node_t * mxmlLoadFile( mxml_node_t * top, - FILE * fp, - mxml_type_t (*cb)(mxml_node_t *node)); + FILE * fp);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| top | Top node |
| fp | File to read from |
| (*cb)(mxml_node_t *node) | Callback function or - MXML_NO_CALLBACK |
Returns
First node or NULL if the file could not be read.
-mxmlLoadString()
-+
mxmlLoadString()
Description
Load a string into an XML node tree. The nodes in the specified string are added to the specified top node. If no top node is provided, @@ -2570,26 +2256,25 @@ mxmlLoadFile( mxml_node_t * mxmlLoadString( mxml_node_t * top, - const char * s, - mxml_type_t (*cb)(mxml_node_t *node)); + const char * s);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| top | Top node |
| s | String to load |
| (*cb)(mxml_node_t *node) | Callback function or - MXML_NO_CALLBACK |
Returns
First node or NULL if the string has errors.
-mxmlNewCDATA()
-+
+ + Mini-XML 2.3 mxmlNewCDATA()
Description
Create a new CDATA node. The new CDATA node is added to the end of the specified parent's child list. The constant MXML_NO_PARENT can be @@ -2604,20 +2289,22 @@ mxmlNewCDATA( const char * data);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| parent | Parent node or MXML_NO_PARENT |
| data | Data string |
Returns
New node
-mxmlNewCustom()
-+
+ + Mini-XML 2.1 mxmlNewCustom()
Description
Create a new custom data node. The new custom node is added to the end of the specified parent's child list. The constant MXML_NO_PARENT @@ -2629,26 +2316,23 @@ mxmlNewCDATA( mxml_node_t * mxmlNewCustom( mxml_node_t * parent, - void * data, - void (*destroy)(void *)); + void * data);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| parent | Parent node or MXML_NO_PARENT |
| data | Pointer to data |
| (*destroy)(void *) | Function to destroy data | -
Returns
New node
-mxmlNewElement()
-+
mxmlNewElement()
Description
Create a new element node. The new element node is added to the end of the specified parent's child list. The constant MXML_NO_PARENT can @@ -2661,20 +2345,20 @@ mxmlNewElement( const char * name);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| parent | Parent node or MXML_NO_PARENT |
| name | Name of element |
Returns
New node
-mxmlNewInteger()
-+
mxmlNewInteger()
Description
Create a new integer node. The new integer node is added to the end of the specified parent's child list. The constant MXML_NO_PARENT can @@ -2687,20 +2371,20 @@ mxmlNewInteger( int integer);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| parent | Parent node or MXML_NO_PARENT |
| integer | Integer value |
Returns
New node
-mxmlNewOpaque()
-+
mxmlNewOpaque()
Description
Create a new opaque string. The new opaque node is added to the end of the specified parent's child list. The constant MXML_NO_PARENT can @@ -2714,20 +2398,20 @@ mxmlNewOpaque( const char * opaque);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| parent | Parent node or MXML_NO_PARENT |
| opaque | Opaque string |
Returns
New node
-mxmlNewReal()
-+
mxmlNewReal()
Description
Create a new real number node. The new real number node is added to the end of the specified parent's child list. The constant @@ -2741,20 +2425,20 @@ mxmlNewReal( double real);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| parent | Parent node or MXML_NO_PARENT |
| real | Real number value |
Returns
New node
-mxmlNewText()
-+
mxmlNewText()
Description
Create a new text fragment node. The new text node is added to the end of the specified parent's child list. The constant MXML_NO_PARENT @@ -2771,22 +2455,22 @@ mxmlNewText( const char * string);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| parent | Parent node or MXML_NO_PARENT |
| whitespace | 1 = leading whitespace, 0 = no whitespace |
| string | String |
Returns
New node
-mxmlNewTextf()
-+
mxmlNewTextf()
Description
Create a new formatted text fragment node. The new text node is added to the end of the specified parent's child list. The constant @@ -2804,10 +2488,10 @@ mxmlNewTextf( ...);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| parent | Parent node or MXML_NO_PARENT |
| whitespace | 1 = leading whitespace, 0 = no @@ -2815,12 +2499,12 @@ mxmlNewTextf( |
| format | Printf-style frmat string |
| ... | Additional args as needed |
Returns
New node
-mxmlRemove()
-+
mxmlRemove()
Description
Remove a node from its parent. Does not free memory used by the node - use mxmlDelete() for that. This function does nothing if the node has @@ -2832,19 +2516,20 @@ mxmlRemove( mxml_node_t * node);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Node to remove |
Returns
Nothing.
-mxmlSaveAllocString()
-+
mxmlSaveAllocString() +
Description
Save an XML node tree to an allocated string. This function returns a pointer to a string containing the textual representation of the XML @@ -2859,25 +2544,22 @@ mxmlRemove(
char * mxmlSaveAllocString( - mxml_node_t * node, - const char * (*cb)(mxml_node_t *node, int ws)); + mxml_node_t * node);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Node to write |
| (*cb)(mxml_node_t *node, int ws) | Whitespace - callback or MXML_NO_CALLBACK |
Returns
Allocated string or NULL
-mxmlSaveFd()
-+
mxmlSaveFd()
Description
Save an XML tree to a file descriptor. The callback argument specifies a function that returns a whitespace string or NULL before @@ -2889,26 +2571,23 @@ mxmlSaveAllocString( int mxmlSaveFd( mxml_node_t * node, - int fd, - const char * (*cb)(mxml_node_t *node, int ws)); + int fd);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Node to write |
| fd | File descriptor to write to |
| (*cb)(mxml_node_t *node, int ws) | Whitespace - callback or MXML_NO_CALLBACK |
Returns
0 on success, -1 on error.
-mxmlSaveFile()
-+
mxmlSaveFile()
Description
Save an XML tree to a file. The callback argument specifies a function that returns a whitespace string or NULL before and after each @@ -2920,26 +2599,23 @@ mxmlSaveFd( int mxmlSaveFile( mxml_node_t * node, - FILE * fp, - const char * (*cb)(mxml_node_t *node, int ws)); + FILE * fp);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Node to write |
| fp | File to write to |
| (*cb)(mxml_node_t *node, int ws) | Whitespace - callback or MXML_NO_CALLBACK |
Returns
0 on success, -1 on error.
-mxmlSaveString()
-+
mxmlSaveString()
Description
Save an XML node tree to a string. This function returns the total number of bytes that would be required for the string but only copies @@ -2954,27 +2630,26 @@ int mxmlSaveString( mxml_node_t * node, char * buffer, - int bufsize, - const char * (*cb)(mxml_node_t *node, int ws)); + int bufsize);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Node to write |
| buffer | String buffer |
| bufsize | Size of string buffer |
| (*cb)(mxml_node_t *node, int ws) | Whitespace - callback or MXML_NO_CALLBACK |
Returns
Size of string
-mxmlSetCDATA()
-+
+ + Mini-XML 2.3 mxmlSetCDATA()
Description
Set the element name of a CDATA node. The node is not changed if it is not a CDATA element node.
@@ -2986,20 +2661,22 @@ mxmlSetCDATA( const char * data);Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Node to set |
| data | New data string |
Returns
0 on success, -1 on failure
-mxmlSetCustom()
-+
+ + Mini-XML 2.1 mxmlSetCustom()
Description
Set the data and destructor of a custom data node. The node is not changed if it is not a custom node.
@@ -3008,25 +2685,24 @@ mxmlSetCDATA( int mxmlSetCustom( mxml_node_t * node, - void * data, - void (*destroy)(void *)); + void * data);Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Node to set |
| data | New data pointer |
| (*destroy)(void *) | New destructor function |
Returns
0 on success, -1 on failure
-mxmlSetCustomHandlers()
-+
+mxmlSetCustomHandlers()
Description
Set the handling functions for custom data. The load function accepts a node pointer and a data string and must return 0 on success and @@ -3036,24 +2712,24 @@ mxmlSetCustom(
void mxmlSetCustomHandlers( - mxml_custom_load_cb_t load, - mxml_custom_save_cb_t save); + mxml_custom_load_cb_t load, + mxml_custom_save_cb_t save);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| load | Load function |
| save | Save function |
Returns
Nothing.
-mxmlSetElement()
-+
mxmlSetElement()
Description
Set the name of an element node. The node is not changed if it is not an element node.
@@ -3065,43 +2741,35 @@ mxmlSetElement( const char * name);Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Node to set |
| name | New name string |
Returns
0 on success, -1 on failure
-mxmlSetErrorCallback()
-+
mxmlSetErrorCallback() +
Description
Set the error message callback.
Syntax
void -mxmlSetErrorCallback( - void (*cb)(const char *)); +mxmlSetErrorCallback(void);
Arguments
- -| Name | Description |
|---|---|
| (*cb)(const char *) | Error callback function | -
None.
Returns
Nothing.
-mxmlSetInteger()
-+
mxmlSetInteger()
Description
Set the value of an integer node. The node is not changed if it is not an integer node.
@@ -3113,20 +2781,20 @@ mxmlSetInteger( int integer);Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Node to set |
| integer | Integer value |
Returns
0 on success, -1 on failure
-mxmlSetOpaque()
-+
mxmlSetOpaque()
Description
Set the value of an opaque node. The node is not changed if it is not an opaque node.
@@ -3138,20 +2806,20 @@ mxmlSetOpaque( const char * opaque);Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Node to set |
| opaque | Opaque string |
Returns
0 on success, -1 on failure
-mxmlSetReal()
-+
mxmlSetReal()
Description
Set the value of a real number node. The node is not changed if it is not a real number node.
@@ -3163,20 +2831,20 @@ mxmlSetReal( double real);Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Node to set |
| real | Real number value |
Returns
0 on success, -1 on failure
-mxmlSetText()
-+
mxmlSetText()
Description
Set the value of a text node. The node is not changed if it is not a text node.
@@ -3189,22 +2857,22 @@ mxmlSetText( const char * string);Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Node to set |
| whitespace | 1 = leading whitespace, 0 = no whitespace |
| string | String |
Returns
0 on success, -1 on failure
-mxmlSetTextf()
-+
mxmlSetTextf()
Description
Set the value of a text node to a formatted string. The node is not changed if it is not a text node.
@@ -3218,10 +2886,10 @@ mxmlSetTextf( ...);Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Node to set |
| whitespace | 1 = leading whitespace, 0 = no @@ -3229,12 +2897,12 @@ mxmlSetTextf( |
| format | Printf-style format string |
| ... | Additional arguments as needed |
Returns
0 on success, -1 on failure
-mxmlWalkNext()
-+
mxmlWalkNext()
Description
Walk to the next logical node in the tree. The descend argument controls whether the first child is considered to be the next node. The @@ -3248,22 +2916,22 @@ mxmlWalkNext( int descend);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Current node |
| top | Top node |
| descend | Descend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST |
Returns
Next node or NULL
-mxmlWalkPrev()
-+
mxmlWalkPrev()
Description
Walk to the previous logical node in the tree. The descend argument controls whether the previous node's last child is considered to be the @@ -3278,35 +2946,37 @@ mxmlWalkPrev( int descend);
Arguments
- +| Name | Description |
|---|---|
| Name | Description |
| node | Current node |
| top | Top node |
| descend | Descend into tree - MXML_DESCEND, MXML_NO_DESCEND, or MXML_DESCEND_FIRST |
Returns
Previous node or NULL
-Structures
+Structures
- mxml_attr_s -
- mxml_custom_s +
- mxml_custom_s + + Mini-XML 2.1 +
- mxml_element_s
- mxml_index_s
- mxml_node_s
- mxml_text_s -
- mxml_value_s
mxml_attr_s
-+
mxml_attr_s
Description
-An XML element attribute value.
+Data types...
Definition
struct mxml_attr_s @@ -3316,18 +2986,18 @@ struct mxml_attr_s };
Members
- -| Name | Description |
|---|
| Name | Description |
|---|---|
| name | Attribute name |
| value | Attribute value |
mxml_custom_s
-+
+ + Mini-XML 2.1 mxml_custom_s
Description
An XML custom value.
Definition
@@ -3338,17 +3008,38 @@ struct mxml_custom_s };Members
- -| Name | Description |
|---|
| Name | Description |
|---|---|
| data | Pointer to (allocated) custom data |
mxml_index_s
-+
mxml_element_s
+Description
+An XML element value.
+Definition
+
+struct mxml_element_s
+{
+ mxml_attr_t * attrs;
+ char * name;
+ int num_attrs;
+};
+
+Members
+| Name | Description |
|---|---|
| attrs | Attributes |
| name | Name of element |
| num_attrs | Number of attributes |
mxml_index_s
Description
An XML node index.
Definition
@@ -3363,10 +3054,9 @@ struct mxml_index_s };Members
- -| Name | Description |
|---|
| Name | Description |
|---|---|
| alloc_nodes | Allocated nodes in index |
| attr | Attribute used for indexing or NULL |
| nodes | Node array |
| num_nodes | Number of nodes in index |
mxml_node_s
-+
mxml_node_s
Description
An XML node.
Definition
@@ -3394,10 +3083,9 @@ struct mxml_node_s };Members
- -| Name | Description |
|---|
| Name | Description |
|---|---|
| child | First child node |
| last_child | Last child node |
| type | Node type |
| value | Node value |
mxml_text_s
-+
mxml_text_s
Description
An XML text value.
Definition
@@ -3422,45 +3109,23 @@ struct mxml_text_s };Members
- -| Name | Description |
|---|
| Name | Description |
|---|---|
| string | Fragment string |
| whitespace | Leading whitespace? |
mxml_value_s
--
Description
-An XML element value.
-Definition
-
-struct mxml_value_s
-{
- mxml_attr_t * attrs;
- char * name;
- int num_attrs;
-};
-
-Members
- -| Name | Description |
|---|---|
| attrs | Attributes |
| name | Name of element |
| num_attrs | Number of attributes |
Types
+Types
- mxml_attr_t -
- mxml_custom_t +
- mxml_custom_load_cb_t +
- mxml_custom_save_cb_t +
- mxml_custom_t + + Mini-XML 2.1
- mxml_element_t
- mxml_index_t
- mxml_node_t @@ -3469,18 +3134,38 @@ struct mxml_value_s
mxml_attr_t
-+
mxml_attr_t
Description
-An XML element attribute value.
+Data types...
Definition
typedef struct mxml_attr_s mxml_attr_t;-
mxml_custom_t
-+
mxml_custom_load_cb_t +
+Description
+Custom data load callback function
+Definition
++typedef int (*mxml_custom_load_cb_t)(mxml_node_t *, const char *); ++ + +
mxml_custom_save_cb_t +
+Description
+Custom data save callback function
+Definition
++typedef char * (*mxml_custom_save_cb_t)(mxml_node_t *); ++ + +
+ + Mini-XML 2.1 mxml_custom_t
Description
An XML custom value.
Definition
@@ -3489,18 +3174,16 @@ typedef struct mxml_custom_s mxml_custom_t; -mxml_element_t
-+
mxml_element_t
Description
An XML element value.
Definition
-typedef struct mxml_value_s mxml_element_t; +typedef struct mxml_element_s mxml_element_t;-
mxml_index_t
-+
mxml_index_t
Description
An XML node index.
Definition
@@ -3509,8 +3192,7 @@ typedef struct mxml_index_s mxml_index_t; -mxml_node_t
-+
mxml_node_t
Description
An XML node.
Definition
@@ -3519,8 +3201,7 @@ typedef struct mxml_node_s mxml_node_t; -mxml_text_t
-+
mxml_text_t
Description
An XML text value.
Definition
@@ -3529,8 +3210,7 @@ typedef struct mxml_text_s mxml_text_t; -mxml_value_t
-+
mxml_value_t
Description
An XML node value.
Definition
@@ -3539,14 +3219,13 @@ typedef union mxml_value_u mxml_value_t; -Unions
+Unions
-mxml_value_u
-+
mxml_value_u
Description
An XML node value.
Definition
@@ -3562,17 +3241,18 @@ union mxml_value_u };Members
- -| Name | Description |
|---|
| Name | Description |
|---|---|
| custom | Custom data |
| custom + + Mini-XML 2.1 | Custom data |
| element | Element |
| integer | Integer number |
| opaque | Opaque string |
| real | Real number |
| text | Text fragment |
4 - Using the mxmldoc -Utility
- -This chapter describes how to use the mxmldoc(1) -utility that comes with Mini-XML to automatically generate -documentation for your programs.
- -The Basics
- -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.
- -Code Documentation Conventions
- -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.
- -Functions and Methods
- -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.
- -Variables and Class/Structure/Union Members
- -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 */ -- -
Types
- -Each type must have a comment block immediately before the -typedef, as follows:
- -- /* - * This type is for foobar options. - */ - typedef int this_type_t; -- - -
Classes, Structures, and Unions
- -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);
- }
- };
-
-
-Enumerations
- -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 */
- };
-
-
-
-XML Schema
- -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.2 documentation schema for mxmldoc output. - Copyright 2003-2005 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> -- |
mxmldoc(1)
+Name
+mxmldoc - mini-xml documentation generator +Synopsis
+mxmldoc +[ --intro +introfile.html +] [ --section +section +] [ --title +title +] [ +filename.xml +] [ +source file(s) +] > +filename.html +Description
+mxmldoc scans the specified C and C++ source files to +produce an XML representation of globally accessible classes, +constants, enumerations, functions, structures, typedefs, +unions, and variables. The XML file is updated as necessary and +a HTML representation of the XML file is written to the standard +output. If no source files are specified then the current XML +file is converted to HTML on the standard output. +In general, any C or C++ source code is handled by +mxmldoc, however it was specifically written to handle +code with documentation that is formatted according to the CUPS +Configuration Management Plan which is available at +"http://www.cups.org/documentation.php". +
Options
+-
+
- --intro introfile.html + +
- Inserts the specified file at the top of the output documentation. + +
- --section section + +
- Sets the section/keywords in the output documentation. + +
- --title title + +
- Sets the title of the output documentation. + +