mirror of
https://github.com/michaelrsweet/mxml.git
synced 2025-02-20 17:35:30 +00:00
Documentation updates.
Add --section option.
This commit is contained in:
Michael R Sweet
parent
2e7bc89ddd
commit
cc5890089d
6
CHANGES
6
CHANGES
@ -1,4 +1,4 @@
|
|||||||
CHANGES - 11/30/2005
|
CHANGES - 12/02/2005
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
CHANGES IN Mini-XML 2.3
|
CHANGES IN Mini-XML 2.3
|
||||||
@ -11,8 +11,8 @@ CHANGES IN Mini-XML 2.3
|
|||||||
"@private@", and "@since version@" comments.
|
"@private@", and "@since version@" comments.
|
||||||
- Fixed function and enumeraion type bugs in mxmldoc.
|
- Fixed function and enumeraion type bugs in mxmldoc.
|
||||||
- Fixed XML schema for mxmldoc.
|
- Fixed XML schema for mxmldoc.
|
||||||
- The mxmldoc program now supports --title and --intro
|
- The mxmldoc program now supports --intro, --section,
|
||||||
options.
|
and --title options.
|
||||||
- The mxmlLoad*() functions could leak a node on an error
|
- The mxmlLoad*() functions could leak a node on an error
|
||||||
(STR #27)
|
(STR #27)
|
||||||
- The mxml_vsnprintf() function could get in an infinite
|
- The mxml_vsnprintf() function could get in an infinite
|
||||||
|
|||||||
@ -1,6 +1,6 @@
|
|||||||
<html>
|
<html>
|
||||||
<head>
|
<head>
|
||||||
<title>Mini-XML Programmers Manual, Version 2.2.3</title>
|
<title>Mini-XML Programmers Manual, Version 2.3</title>
|
||||||
<meta name='copyright' content='Copyright 2003-2005'/>
|
<meta name='copyright' content='Copyright 2003-2005'/>
|
||||||
<meta name='author' content='Michael Sweet'/>
|
<meta name='author' content='Michael Sweet'/>
|
||||||
<meta name='keywords' content='XML, C, C++, library'/>
|
<meta name='keywords' content='XML, C, C++, library'/>
|
||||||
@ -9,7 +9,7 @@
|
|||||||
|
|
||||||
<h1 align='right'><a name='INTRO'>Introduction</a></h1>
|
<h1 align='right'><a name='INTRO'>Introduction</a></h1>
|
||||||
|
|
||||||
<p>This programmers manual describes Mini-XML version 2.2.3, a
|
<p>This programmers manual describes Mini-XML version 2.3, a
|
||||||
small XML parsing library that you can use to read and write XML
|
small XML parsing library that you can use to read and write XML
|
||||||
and XML-like data files in your application without requiring
|
and XML-like data files in your application without requiring
|
||||||
large non-standard libraries. Mini-XML only requires an ANSI C
|
large non-standard libraries. Mini-XML only requires an ANSI C
|
||||||
|
|||||||
1204
doc/mxml.html
1204
doc/mxml.html
File diff suppressed because it is too large
Load Diff
12
doc/mxml.man
12
doc/mxml.man
@ -15,7 +15,7 @@
|
|||||||
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||||
.\" GNU General Public License for more details.
|
.\" GNU General Public License for more details.
|
||||||
.\"
|
.\"
|
||||||
.TH mxml 3 "mini-XML" "25 February 2005" "Michael Sweet"
|
.TH mxml 3 "mini-XML" "2 December 2005" "Michael Sweet"
|
||||||
.SH NAME
|
.SH NAME
|
||||||
mxml \- mini-xml library
|
mxml \- mini-xml library
|
||||||
.SH INCLUDE FILE
|
.SH INCLUDE FILE
|
||||||
@ -31,9 +31,7 @@ most vendors' ANSI C compilers) and a "make" program.
|
|||||||
.PP
|
.PP
|
||||||
Mini-XML provides the following functionality:
|
Mini-XML provides the following functionality:
|
||||||
.IP \(bu 4
|
.IP \(bu 4
|
||||||
Reading and writing of UTF-8 encoded XML files.
|
Reading of UTF-8 and UTF-16 and writing of UTF-8 encoded XML files and strings.
|
||||||
.IP \(bu 4
|
|
||||||
Reading and writing of UTF-8 encoded XML strings.
|
|
||||||
.IP \(bu 4
|
.IP \(bu 4
|
||||||
Data is stored in a linked-list tree structure,
|
Data is stored in a linked-list tree structure,
|
||||||
preserving the XML data hierarchy.
|
preserving the XML data hierarchy.
|
||||||
@ -44,7 +42,7 @@ values with no preset limits, just available memory.
|
|||||||
Supports integer, real, opaque ("cdata"), and text data types in
|
Supports integer, real, opaque ("cdata"), and text data types in
|
||||||
"leaf" nodes.
|
"leaf" nodes.
|
||||||
.IP \(bu 4
|
.IP \(bu 4
|
||||||
Functions for creating and managing trees of data.
|
Functions for creating, indexing, and managing trees of data.
|
||||||
.IP \(bu 4
|
.IP \(bu 4
|
||||||
"Find" and "walk" functions for easily locating and navigating
|
"Find" and "walk" functions for easily locating and navigating
|
||||||
trees of data.
|
trees of data.
|
||||||
@ -53,9 +51,7 @@ Mini-XML doesn't do validation or other types of processing
|
|||||||
on the data based upon schema files or other sources of
|
on the data based upon schema files or other sources of
|
||||||
definition information, nor does it support character
|
definition information, nor does it support character
|
||||||
entities other than those required by the XML
|
entities other than those required by the XML
|
||||||
specification. Also, since Mini-XML does not support the
|
specification.
|
||||||
UTF-16 encoding, it is technically not a conforming XML
|
|
||||||
consumer/client.
|
|
||||||
.SH USING MINI-XML
|
.SH USING MINI-XML
|
||||||
Mini-XML provides a single header file which you include:
|
Mini-XML provides a single header file which you include:
|
||||||
.nf
|
.nf
|
||||||
|
|||||||
432
doc/mxmldoc.html
432
doc/mxmldoc.html
@ -1,378 +1,66 @@
|
|||||||
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
|
||||||
<html>
|
<html>
|
||||||
|
<!-- SECTION: Man Pages -->
|
||||||
|
<head>
|
||||||
|
<style type='text/css'><!--
|
||||||
|
h1, h2, h3, p { font-family: sans-serif; text-align: justify; }
|
||||||
|
tt, pre a:link, pre a:visited, tt a:link, tt a:visited { font-weight: bold; color: #7f0000; }
|
||||||
|
pre { font-weight: bold; color: #7f0000; margin-left: 2em; }
|
||||||
|
h1.title, h2.title, h3.title { border-bottom: solid 2px #000000; }
|
||||||
|
--></style>
|
||||||
|
<title>mxmldoc</title>
|
||||||
|
</head>
|
||||||
<body>
|
<body>
|
||||||
|
|
||||||
<h1 align='right'><a name='MXMLDOC'>4 - Using the mxmldoc
|
|
||||||
Utility</a></h1>
|
|
||||||
|
|
||||||
<p>This chapter describes how to use the <tt>mxmldoc(1)</tt>
|
|
||||||
utility that comes with Mini-XML to automatically generate
|
|
||||||
documentation for your programs.</p>
|
|
||||||
|
|
||||||
<h2>The Basics</h2>
|
|
||||||
|
|
||||||
<p>The <tt>mxmldoc</tt> 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 <tt>mxmldoc</tt> can
|
|
||||||
extract the necessary descriptive text.</p>
|
|
||||||
|
|
||||||
<p>The <tt>mxmldoc</tt> 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, <tt>mxmldoc</tt> writes XHTML documentation to the
|
|
||||||
standard output, which can be redirected to the file using the
|
|
||||||
<kbd>>filename</kbd> syntax:</p>
|
|
||||||
|
|
||||||
<pre>
|
|
||||||
<kbd>mxmldoc myfile.xml >myfile.html ENTER</kbd>
|
|
||||||
<kbd>mxmldoc myfile.xml file1.c file2.cxx file3.h >myfile.html ENTER</kbd>
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<p>If no source files are provided on the command-line, the
|
|
||||||
current contents of the XML file are converted to XHTML.</p>
|
|
||||||
|
|
||||||
<h2>Code Documentation Conventions</h2>
|
|
||||||
|
|
||||||
<p>As noted previously, source code must be commented properly
|
|
||||||
for <tt>mxmldoc</tt> to generate correct documentation for the
|
|
||||||
code. Single line comments can use the C++ <tt>//</tt> comment
|
|
||||||
sequence, however all multi-line comments must use the C <tt>/*
|
|
||||||
... */</tt> comment sequence.</p>
|
|
||||||
|
|
||||||
<h3>Functions and Methods</h3>
|
|
||||||
|
|
||||||
<p>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:</p>
|
|
||||||
|
|
||||||
<pre>
|
|
||||||
/*
|
|
||||||
* '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);
|
|
||||||
}
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<p>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.</p>
|
|
||||||
|
|
||||||
<h3>Variables and Class/Structure/Union Members</h3>
|
|
||||||
|
|
||||||
<p>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:</p>
|
|
||||||
|
|
||||||
<pre>
|
|
||||||
int this_variable; /* The current state of this */
|
|
||||||
int that_variable; /* The current state of that */
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<h3>Types</h3>
|
|
||||||
|
|
||||||
<p>Each type must have a comment block immediately before the
|
|
||||||
typedef, as follows:</p>
|
|
||||||
|
|
||||||
<pre>
|
|
||||||
/*
|
|
||||||
* This type is for foobar options.
|
|
||||||
*/
|
|
||||||
typedef int this_type_t;
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<!-- NEED 5in -->
|
|
||||||
<h3>Classes, Structures, and Unions</h3>
|
|
||||||
|
|
||||||
<p>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:</p>
|
|
||||||
|
|
||||||
<pre>
|
|
||||||
/*
|
|
||||||
* 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);
|
|
||||||
}
|
|
||||||
};
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<h3>Enumerations</h3>
|
|
||||||
|
|
||||||
<p>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:</p>
|
|
||||||
|
|
||||||
<pre>
|
|
||||||
/*
|
|
||||||
* Enumeration of media trays.
|
|
||||||
*/
|
|
||||||
enum this_enum_e
|
|
||||||
{
|
|
||||||
THIS_TRAY, /* This tray */
|
|
||||||
THAT_TRAY /* That tray */
|
|
||||||
};
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<!-- NEW PAGE -->
|
<!-- NEW PAGE -->
|
||||||
<h2>XML Schema</h2>
|
<h2 class='title'><a name='mxmldoc.1'>mxmldoc(1)</a></h2>
|
||||||
|
<h3 _hd_omit_toc>Name</h3>
|
||||||
<p>Listing 4-1 shows the XML schema file <var>mxmldoc.xsd</var>
|
mxmldoc - mini-xml documentation generator
|
||||||
which is included with Mini-XML. This schema file can be used to
|
<h3 _hd_omit_toc>Synopsis</h3>
|
||||||
convert the XML files produced by <tt>mxmldoc</tt> into other
|
<b>mxmldoc
|
||||||
formats.</p>
|
</b>[ --intro
|
||||||
|
<i>introfile.html
|
||||||
<center><table border='1' width='80%' bgcolor='#cccccc' cellpadding='5' cellspacing='0'>
|
</i>] [ --section
|
||||||
<caption align='bottom'><i>Listing 4-1, XML Schema File "mxmldoc.xsd"</i></caption>
|
<i>section
|
||||||
<tr><td>
|
</i>] [ --title
|
||||||
<pre>
|
<i>title
|
||||||
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
|
</i>] [
|
||||||
<xsd:annotation>
|
<i>filename.xml
|
||||||
<xsd:documentation xml:lang="en">
|
</i>] [
|
||||||
Mini-XML 2.2 documentation schema for mxmldoc output.
|
<i>source file(s)
|
||||||
Copyright 2003-2005 by Michael Sweet.
|
</i>] >
|
||||||
|
<i>filename.html
|
||||||
This program is free software; you can redistribute it and/or
|
</i><h3 _hd_omit_toc>Description</h3>
|
||||||
modify it under the terms of the GNU Library General Public
|
<i>mxmldoc</i> scans the specified C and C++ source files to
|
||||||
License as published by the Free Software Foundation; either
|
produce an XML representation of globally accessible classes,
|
||||||
version 2, or (at your option) any later version.
|
constants, enumerations, functions, structures, typedefs,
|
||||||
|
unions, and variables. The XML file is updated as necessary and
|
||||||
This program is distributed in the hope that it will be useful,
|
a HTML representation of the XML file is written to the standard
|
||||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
output. If no source files are specified then the current XML
|
||||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
file is converted to HTML on the standard output.
|
||||||
GNU General Public License for more details.
|
<p>In general, any C or C++ source code is handled by
|
||||||
</xsd:documentation>
|
<i>mxmldoc</i>, however it was specifically written to handle
|
||||||
</xsd:annotation>
|
code with documentation that is formatted according to the CUPS
|
||||||
|
Configuration Management Plan which is available at
|
||||||
<!-- basic element definitions -->
|
"http://www.cups.org/documentation.php".
|
||||||
<xsd:element name="argument" type="argumentType"/>
|
<h3 _hd_omit_toc>Options</h3>
|
||||||
<xsd:element name="class" type="classType"/>
|
<dl>
|
||||||
<xsd:element name="constant" type="constantType"/>
|
<dt>--intro introfile.html
|
||||||
<xsd:element name="description" type="xsd:string"/>
|
</dt>
|
||||||
<xsd:element name="enumeration" type="enumerationType"/>
|
<dd>Inserts the specified file at the top of the output documentation.
|
||||||
<xsd:element name="function" type="functionType"/>
|
</dd>
|
||||||
<xsd:element name="mxmldoc" type="mxmldocType"/>
|
<dt>--section section
|
||||||
<xsd:element name="namespace" type="namespaceType"/>
|
</dt>
|
||||||
<xsd:element name="returnvalue" type="returnvalueType"/>
|
<dd>Sets the section/keywords in the output documentation.
|
||||||
<xsd:element name="seealso" type="identifierList"/>
|
</dd>
|
||||||
<xsd:element name="struct" type="structType"/>
|
<dt>--title title
|
||||||
<xsd:element name="typedef" type="typedefType"/>
|
</dt>
|
||||||
<xsd:element name="type" type="xsd:string"/>
|
<dd>Sets the title of the output documentation.
|
||||||
<xsd:element name="union" type="unionType"/>
|
</dd>
|
||||||
<xsd:element name="variable" type="variableType"/>
|
</dl>
|
||||||
|
<h3 _hd_omit_toc>See Also</h3>
|
||||||
<!-- descriptions of complex elements -->
|
mxml(3), Mini-XML Programmers Manual, http://www.easysw.com/~mike/mxml/
|
||||||
<xsd:complexType name="argumentType">
|
<h3 _hd_omit_toc>Copyright</h3>
|
||||||
<xsd:sequence>
|
Copyright 2003-2005 by Michael Sweet.
|
||||||
<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"/>
|
|
||||||
</pre>
|
|
||||||
</td></tr>
|
|
||||||
</table></center>
|
|
||||||
<!-- NEW PAGE -->
|
|
||||||
<center><table border='1' width='80%' bgcolor='#cccccc' cellpadding='5' cellspacing='0'>
|
|
||||||
<caption align='bottom'><i>Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)</i></caption>
|
|
||||||
<tr><td>
|
|
||||||
<pre>
|
|
||||||
<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"/>
|
|
||||||
</pre>
|
|
||||||
</td></tr>
|
|
||||||
</table></center>
|
|
||||||
<!-- NEW PAGE -->
|
|
||||||
<center><table border='1' width='80%' bgcolor='#cccccc' cellpadding='5' cellspacing='0'>
|
|
||||||
<caption align='bottom'><i>Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)</i></caption>
|
|
||||||
<tr><td>
|
|
||||||
<pre>
|
|
||||||
<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>
|
|
||||||
</pre>
|
|
||||||
</td></tr>
|
|
||||||
</table></center>
|
|
||||||
<!-- NEW PAGE -->
|
|
||||||
<center><table border='1' width='80%' bgcolor='#cccccc' cellpadding='5' cellspacing='0'>
|
|
||||||
<caption align='bottom'><i>Listing 4-1, XML Schema File "mxmldoc.xsd" (con't)</i></caption>
|
|
||||||
<tr><td>
|
|
||||||
<pre>
|
|
||||||
</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>
|
|
||||||
</pre>
|
|
||||||
</td></tr>
|
|
||||||
</table></center>
|
|
||||||
|
|
||||||
</body>
|
</body>
|
||||||
</html>
|
</html>
|
||||||
|
|||||||
@ -15,13 +15,15 @@
|
|||||||
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||||
.\" GNU General Public License for more details.
|
.\" GNU General Public License for more details.
|
||||||
.\"
|
.\"
|
||||||
.TH mxmldoc 1 "mini-XML" "21 September 2005" "Michael Sweet"
|
.TH mxmldoc 1 "mini-XML" "2 December 2005" "Michael Sweet"
|
||||||
.SH NAME
|
.SH NAME
|
||||||
mxmldoc \- mini-xml documentation generator
|
mxmldoc \- mini-xml documentation generator
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
.B mxmldoc
|
.B mxmldoc
|
||||||
[ --intro
|
[ --intro
|
||||||
.I introfile.html
|
.I introfile.html
|
||||||
|
] [ --section
|
||||||
|
.I section
|
||||||
] [ --title
|
] [ --title
|
||||||
.I title
|
.I title
|
||||||
] [
|
] [
|
||||||
@ -50,6 +52,10 @@ Configuration Management Plan which is available at
|
|||||||
.br
|
.br
|
||||||
Inserts the specified file at the top of the output documentation.
|
Inserts the specified file at the top of the output documentation.
|
||||||
.TP 5
|
.TP 5
|
||||||
|
\--section section
|
||||||
|
.br
|
||||||
|
Sets the section/keywords in the output documentation.
|
||||||
|
.TP 5
|
||||||
\--title title
|
\--title title
|
||||||
.br
|
.br
|
||||||
Sets the title of the output documentation.
|
Sets the title of the output documentation.
|
||||||
|
|||||||
@ -21,8 +21,8 @@
|
|||||||
|
|
||||||
<li>Fixed XML schema for mxmldoc.</li>
|
<li>Fixed XML schema for mxmldoc.</li>
|
||||||
|
|
||||||
<li>The mxmldoc program now supports --title and --intro
|
<li>The mxmldoc program now supports --intro, --section,
|
||||||
options.</li>
|
and --title options.</li>
|
||||||
|
|
||||||
<li>The mxmlLoad*() functions could leak a node on an
|
<li>The mxmlLoad*() functions could leak a node on an
|
||||||
error (STR #27)</li>
|
error (STR #27)</li>
|
||||||
|
|||||||
90
mxmldoc.c
90
mxmldoc.c
@ -150,7 +150,8 @@ static void update_comment(mxml_node_t *parent,
|
|||||||
mxml_node_t *comment);
|
mxml_node_t *comment);
|
||||||
static void usage(const char *option);
|
static void usage(const char *option);
|
||||||
static void write_description(mxml_node_t *description);
|
static void write_description(mxml_node_t *description);
|
||||||
static void write_documentation(const char *title,
|
static void write_documentation(const char *section,
|
||||||
|
const char *title,
|
||||||
const char *intro,
|
const char *intro,
|
||||||
mxml_node_t *doc);
|
mxml_node_t *doc);
|
||||||
static void write_element(mxml_node_t *doc, mxml_node_t *element);
|
static void write_element(mxml_node_t *doc, mxml_node_t *element);
|
||||||
@ -171,6 +172,7 @@ main(int argc, /* I - Number of command-line args */
|
|||||||
FILE *fp; /* File to read */
|
FILE *fp; /* File to read */
|
||||||
mxml_node_t *doc; /* XML documentation tree */
|
mxml_node_t *doc; /* XML documentation tree */
|
||||||
mxml_node_t *mxmldoc; /* mxmldoc node */
|
mxml_node_t *mxmldoc; /* mxmldoc node */
|
||||||
|
const char *section; /* Section/keywords of documentation */
|
||||||
const char *title; /* Title of documentation */
|
const char *title; /* Title of documentation */
|
||||||
const char *introfile; /* Introduction file */
|
const char *introfile; /* Introduction file */
|
||||||
const char *xmlfile; /* XML file */
|
const char *xmlfile; /* XML file */
|
||||||
@ -181,6 +183,7 @@ main(int argc, /* I - Number of command-line args */
|
|||||||
* Check arguments...
|
* Check arguments...
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
section = NULL;
|
||||||
title = NULL;
|
title = NULL;
|
||||||
introfile = NULL;
|
introfile = NULL;
|
||||||
xmlfile = NULL;
|
xmlfile = NULL;
|
||||||
@ -189,19 +192,7 @@ main(int argc, /* I - Number of command-line args */
|
|||||||
mxmldoc = NULL;
|
mxmldoc = NULL;
|
||||||
|
|
||||||
for (i = 1; i < argc; i ++)
|
for (i = 1; i < argc; i ++)
|
||||||
if (!strcmp(argv[i], "--title") && !title)
|
if (!strcmp(argv[i], "--intro") && !introfile)
|
||||||
{
|
|
||||||
/*
|
|
||||||
* Set title...
|
|
||||||
*/
|
|
||||||
|
|
||||||
i ++;
|
|
||||||
if (i < argc)
|
|
||||||
title = argv[i];
|
|
||||||
else
|
|
||||||
usage(NULL);
|
|
||||||
}
|
|
||||||
else if (!strcmp(argv[i], "--intro") && !introfile)
|
|
||||||
{
|
{
|
||||||
/*
|
/*
|
||||||
* Set intro file...
|
* Set intro file...
|
||||||
@ -213,6 +204,30 @@ main(int argc, /* I - Number of command-line args */
|
|||||||
else
|
else
|
||||||
usage(NULL);
|
usage(NULL);
|
||||||
}
|
}
|
||||||
|
else if (!strcmp(argv[i], "--section") && !section)
|
||||||
|
{
|
||||||
|
/*
|
||||||
|
* Set section/keywords...
|
||||||
|
*/
|
||||||
|
|
||||||
|
i ++;
|
||||||
|
if (i < argc)
|
||||||
|
section = argv[i];
|
||||||
|
else
|
||||||
|
usage(NULL);
|
||||||
|
}
|
||||||
|
else if (!strcmp(argv[i], "--title") && !title)
|
||||||
|
{
|
||||||
|
/*
|
||||||
|
* Set title...
|
||||||
|
*/
|
||||||
|
|
||||||
|
i ++;
|
||||||
|
if (i < argc)
|
||||||
|
title = argv[i];
|
||||||
|
else
|
||||||
|
usage(NULL);
|
||||||
|
}
|
||||||
else if (argv[i][0] == '-')
|
else if (argv[i][0] == '-')
|
||||||
{
|
{
|
||||||
/*
|
/*
|
||||||
@ -343,7 +358,8 @@ main(int argc, /* I - Number of command-line args */
|
|||||||
* Write HTML documentation...
|
* Write HTML documentation...
|
||||||
*/
|
*/
|
||||||
|
|
||||||
write_documentation(title ? title : "Documentation", introfile, mxmldoc);
|
write_documentation(section, title ? title : "Documentation", introfile,
|
||||||
|
mxmldoc);
|
||||||
|
|
||||||
/*
|
/*
|
||||||
* Delete the tree and return...
|
* Delete the tree and return...
|
||||||
@ -2174,6 +2190,7 @@ write_description(
|
|||||||
|
|
||||||
static void
|
static void
|
||||||
write_documentation(
|
write_documentation(
|
||||||
|
const char *section, /* I - Section */
|
||||||
const char *title, /* I - Title */
|
const char *title, /* I - Title */
|
||||||
const char *introfile, /* I - Intro file */
|
const char *introfile, /* I - Intro file */
|
||||||
mxml_node_t *doc) /* I - XML documentation */
|
mxml_node_t *doc) /* I - XML documentation */
|
||||||
@ -2204,24 +2221,31 @@ write_documentation(
|
|||||||
* Standard header...
|
* Standard header...
|
||||||
*/
|
*/
|
||||||
|
|
||||||
printf("<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.0 Transitional//EN\" "
|
puts("<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.0 Transitional//EN\" "
|
||||||
"\"http://www.w3.org/TR/REC-html40/loose.dtd\">\n"
|
"\"http://www.w3.org/TR/REC-html40/loose.dtd\">\n"
|
||||||
"<html>\n"
|
"<html>");
|
||||||
"<head>\n"
|
|
||||||
"\t<title>%s</title>\n"
|
if (section)
|
||||||
"\t<meta name='creator' content='" MXML_VERSION "'>\n"
|
printf("<!-- SECTION: %s -->\n", section);
|
||||||
"\t<style type='text/css'><!--\n"
|
|
||||||
"\th1, h2, h3, p { font-family: sans-serif; text-align: justify; }\n"
|
printf("<head>\n"
|
||||||
"\ttt, pre a:link, pre a:visited, tt a:link, tt a:visited { font-weight: bold; color: #7f0000; }\n"
|
"\t<title>%s</title>\n", title);
|
||||||
"\tpre { font-weight: bold; color: #7f0000; margin-left: 2em; }\n"
|
if (section)
|
||||||
"\tspan.info { background: #000000; border: solid thin #000000; "
|
printf("\t<meta name='keywords' content='%s'>\n", section);
|
||||||
"color: #ffffff; font-size: 80%; font-style: italic; "
|
|
||||||
"font-weight: bold; white-space: nowrap; }\n"
|
puts("\t<meta name='creator' content='" MXML_VERSION "'>\n"
|
||||||
"\th3 span.info { float: right; font-size: 100%; }\n"
|
"\t<style type='text/css'><!--\n"
|
||||||
"\th1.title, h2.title, h3.title { border-bottom: solid 2px #000000; }\n"
|
"\th1, h2, h3, p { font-family: sans-serif; text-align: justify; }\n"
|
||||||
"\t--></style>\n"
|
"\ttt, pre a:link, pre a:visited, tt a:link, tt a:visited { font-weight: bold; color: #7f0000; }\n"
|
||||||
"</head>\n"
|
"\tpre { font-weight: bold; color: #7f0000; margin-left: 2em; }\n"
|
||||||
"<body>\n", title);
|
"\tspan.info { background: #000000; border: solid thin #000000; "
|
||||||
|
"color: #ffffff; font-size: 80%; font-style: italic; "
|
||||||
|
"font-weight: bold; white-space: nowrap; }\n"
|
||||||
|
"\th3 span.info { float: right; font-size: 100%; }\n"
|
||||||
|
"\th1.title, h2.title, h3.title { border-bottom: solid 2px #000000; }\n"
|
||||||
|
"\t--></style>\n"
|
||||||
|
"</head>\n"
|
||||||
|
"<body>");
|
||||||
|
|
||||||
/*
|
/*
|
||||||
* Intro...
|
* Intro...
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user