Add support for generating Xcode documentation sets.

Fix a few Clang-detected issues.
2024-11-24 11:25:30 +00:00 · 2008-11-28 10:56:50 +00:00 · 2008-11-28 10:56:50 +00:00 · 59e1bbbb7a
commit 59e1bbbb7a
parent 95c3d05239
12 changed files with 1478 additions and 149 deletions
--- a/6
+++ b/6
@ -1,8 +1,10 @@
-CHANGES - 2008-10-26
+CHANGES - 2008-11-28
 --------------------

-CHANGES IN Mini-XML 2.5.1
+CHANGES IN Mini-XML 2.6

+	- The mxmldoc program now supports generating Xcode documentation
+	  sets.
 	- mxmlNewXML() now adds encoding="utf-8" in the ?xml directive
 	  to avoid problems with non-conformant XML parsers that assume
 	  something other than UTF-8 as the default encoding.
--- a/Makefile.in
+++ b/Makefile.in
@ -116,6 +116,17 @@ distclean:	clean
 	$(RM) Makefile config.h
 	$(RM) -r autom4te*.cache
 	$(RM) *.bck *.bak
+	$(RM) -r clang
+
+
+#
+# Run the clang.llvm.org static code analysis tool on the C sources.
+#
+
+.PHONY: clang
+clang:
+	$(RM) -r clang
+	scan-build -k -V -o `pwd`/clang $(MAKE) $(MFLAGS) CC=ccc-analyzer clean all


 #
@ -326,6 +337,13 @@ testmxml.o:	mxml.h
 mxml.xml:	mxmldoc-static mxml.h $(PUBLIBOBJS:.o=.c)
 	$(RM) mxml.xml
 	./mxmldoc-static --header doc/reference.heading mxml.xml mxml.h $(PUBLIBOBJS:.o=.c) >doc/reference.html
+	if test "x`uname`" = xDarwin; then \
+		./mxmldoc-static --docset ~/Library/Developer/Shared/Documentation/DocSets/org.minixml.docset \
+			--docversion @VERSION@ --feedname minixml.org \
+			--feedurl http://www.minixml.org/documentation.atom \
+			--header doc/docset.header --intro doc/docset.intro \
+			--css doc/docset.css mxml.xml; \
+	fi

 valgrind:	mxmldoc-static
 	$(RM) valgrind.xml
--- a/2
+++ b/2
@ -1717,7 +1717,7 @@ ac_compiler_gnu=$ac_cv_c_compiler_gnu
 ac_config_headers="$ac_config_headers config.h"


-VERSION=2.5
+VERSION=2.6

 cat >>confdefs.h <<_ACEOF
 #define MXML_VERSION "Mini-XML v$VERSION"
--- a/configure.in
+++ b/configure.in
@ -23,7 +23,7 @@ dnl Set the name of the config header file...
 AC_CONFIG_HEADER(config.h)

 dnl Version number...
-VERSION=2.5
+VERSION=2.6
 AC_SUBST(VERSION)
 AC_DEFINE_UNQUOTED(MXML_VERSION, "Mini-XML v$VERSION")

--- a/doc/docset.css
+++ b/doc/docset.css
@ -0,0 +1,114 @@
+body {
+  background: white;
+  color: black;
+  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
+}
+
+h1, h2, h3, h4, h5, h6, p, td, th {
+  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
+}
+
+kbd {
+  color: #006600;
+  font-family: monaco, courier, monospace;
+  font-weight: bold;
+}
+
+pre {
+  font-family: monaco, courier, monospace;
+}
+
+pre.example {
+  background: white;
+  border: dotted thin #999999;
+  margin-left: 36pt;
+  padding: 10px;
+}
+
+pre.example em {
+  color: #3f0000;
+  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
+}
+
+div.summary table {
+  border: solid thin #999999;
+  border-collapse: collapse;
+  border-spacing: 0;
+  margin: 10px;
+  width: 33%;
+}
+
+div.summary table td, div.summary table th {
+  background: white;
+  border: solid thin #999999;
+  border-spacing: 0;
+  padding: 5px;
+  text-align: left;
+  vertical-align: top;
+}
+
+div.summary table thead th {
+  background: #f0f0f0;
+}
+
+div.body h1 {
+  margin: 0;
+}
+div.body h2 {
+  margin-top: 1.5em;
+}
+div.body h3, div.body h4, div.body h5 {
+  margin-bottom: 0.5em;
+  margin-top: 1.5em;
+}
+.class, .enumeration, .function, .struct, .typedef, .union {
+  border-bottom: solid thin #999999;
+  margin-bottom: 0;
+  margin-top: 2em;
+}
+.description {
+  margin-top: 0.5em;
+}
+code, p.code, pre, ul.code li {
+  font-family: monaco, courier, monospace;
+  font-size: 90%;
+}
+ul.code, ul.contents, ul.subcontents {
+  list-style-type: none;
+  margin: 0;
+  padding-left: 0;
+}
+ul.code li {
+  margin: 0;
+}
+ul.contents > li {
+  margin-top: 1em;
+}
+ul.contents li ul.code, ul.contents li ul.subcontents {
+  padding-left: 2em;
+}
+div.body dl {
+  margin-left: 0;
+  margin-top: 0;
+}
+div.body dt {
+  font-style: italic;
+  margin-left: 0;
+  margin-top: 0;
+}
+div.body dd {
+  margin-bottom: 0.5em;
+}
+span.info {
+  background: black;
+  border: thin solid black;
+  color: white;
+  font-size: 80%;
+  font-style: italic;
+  font-weight: bold;
+  white-space: nowrap;
+}
+h2 span.info, h3 span.info, h4 span.info {
+  float: right;
+  font-size: 100%;
+}
--- a/doc/docset.header
+++ b/doc/docset.header
@ -0,0 +1,16 @@
+<h1>Mini-XML API Reference</h1>
+
+<div class='summary'><table summary='General Information'>
+<thead>
+<tr>
+	<th>Header</th>
+	<th>mxml.h</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+	<th>Library</th>
+	<td>-lmxml</td>
+</tr>
+</tbody>
+</table></div>
--- a/doc/docset.intro
+++ b/doc/docset.intro
@ -0,0 +1,155 @@
+<h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2>
+
+<p>Mini-XML is a small XML parsing library that you can use to read 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.</p>
+
+<p>Mini-XML provides the following functionality:</p>
+
+<ul>
+
+	<li>Reading of UTF-8 and UTF-16 and writing of UTF-8 encoded XML files
+	and strings.</li>
+
+	<li>Data is stored in a linked-list tree structure, preserving the XML
+	data hierarchy.</li>
+
+	<li>Supports arbitrary element names, attributes, and attribute values
+	with no preset limits, just available memory.</li>
+
+	<li>Supports integer, real, opaque ("cdata"), and text data types in
+	"leaf" nodes.</li>
+
+	<li>Functions for creating, indexing, and managing trees of data.</li>
+
+	<li>"Find" and "walk" functions for easily locating and navigating trees
+	of data.</li>
+
+</ul>
+
+<p>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.</p>
+
+<h2 class='title'><a name='USING'>Using Mini-XML</a></h2>
+
+<p>Mini-XML provides a single header file which you include:</p>
+
+<pre class='example'>
+#include &lt;mxml.h&gt;
+</pre>
+
+<p>Nodes are defined by the "<a href='#mxml_node_s'>mxml_node_t</a>" 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
+"<a href='#mxmlNewElement'>mxmlNewElement()</a>",
+"<a href='#mxmlNewInteger'>mxmlNewInteger()</a>",
+"<a href='#mxmlNewOpaque'>mxmlNewOpaque()</a>",
+"<a href='#mxmlNewReal'>mxmlNewReal()</a>", and
+"<a href='#mxmlNewText'>mxmlNewText()</a>" functions. Only elements can have
+child nodes, and the top node must be an element, usually "?xml".</p>
+
+<p>You load an XML file using the "mxmlLoadFile()" function:</p>
+
+<pre class='example'>
+FILE *fp;
+mxml_node_t *tree;
+
+fp = fopen("filename.xml", "r");
+tree = mxmlLoadFile(NULL, fp, MXML_NO_CALLBACK);
+fclose(fp);
+</pre>
+
+<p>Similarly, you save an XML file using the
+"<a href='#mxmlSaveFile'>mxmlSaveFile()</a>" function:
+
+<pre class='example'>
+FILE *fp;
+mxml_node_t *tree;
+
+fp = fopen("filename.xml", "w");
+mxmlSaveFile(tree, fp, MXML_NO_CALLBACK);
+fclose(fp);
+</pre>
+
+<p>The "<a href='#mxmlLoadString'>mxmlLoadString()</a>",
+"<a href='#mxmlSaveAllocString'>mxmlSaveAllocString()</a>", and
+"<a href='#mxmlSaveString'>mxmlSaveString()</a>" functions load XML node trees
+from and save XML node trees to strings:</p>
+
+<pre class='example'>
+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);
+</pre>
+
+<p>You can find a named element/node using the
+"<a href='#mxmlFindElement'>mxmlFindElement()</a>" function:</p>
+
+<pre class='example'>
+mxml_node_t *node = mxmlFindElement(tree, tree, "name",
+				    "attr", "value",
+				    MXML_DESCEND);
+</pre>
+
+<p>The "name", "attr", and "value" arguments can be passed as
+<code>NULL</code> to act as wildcards, e.g.:</p>
+
+<pre class='example'>
+/* 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);
+</pre>
+
+<p>You can also iterate with the same function:</p>
+
+<pre class='example'>
+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 ...
+}
+</pre>
+
+<p>Finally, once you are done with the XML data, use the
+"<a href='#mxmlDelete'>mxmlDelete()</a>" function to recursively free the
+memory that is used for a particular node or the entire tree:</p>
+
+<pre class='example'>
+mxmlDelete(tree);
+</pre>
--- a/doc/mxmldoc.html
+++ b/doc/mxmldoc.html
@ -67,6 +67,22 @@ create a man page instead of HTML documentation, for example:</p>
        &gt;filename.man ENTER</kbd>
 </pre>

+<p>The <tt>--docset directory.docset</tt> option tells <tt>mxmldoc</tt> to
+create an Xcode documentation set containing the HTML documentation, for
+example:</p>
+
+<pre>
+    <kbd>mxmldoc --docset ~/Library/Developer/Shared/Documentation/DocSets/foo.docset \
+    	*.h *.c foo.xml ENTER</kbd>
+</pre>
+
+<blockquote><b>Note:</b>
+
+<p>Xcode documentation sets can only be built on Mac OS X with Xcode 3.0 or
+higher installed.</p>
+
+</blockquote>
+

 <h2>Commenting Your Code</h2>

--- a/doc/mxmldoc.man
+++ b/doc/mxmldoc.man
@ -15,7 +15,7 @@
 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 .\" GNU General Public License for more details.
 .\"
-.TH mxmldoc 1 "Mini-XML" "26 January 2008" "Michael Sweet"
+.TH mxmldoc 1 "Mini-XML" "28 November 2008" "Michael Sweet"
 .SH NAME
 mxmldoc \- mini-xml documentation generator
 .SH SYNOPSIS
@ -45,6 +45,31 @@ mxmldoc \- mini-xml documentation generator
 .I filename.html
 .br
 .B mxmldoc
+[ \-\-docset
+.I directory.docset
+] [ \-\-docversion
+.I version
+] [ \-\-feedname
+.I name
+] [ \-\-feedurl
+.I url
+] [ \-\-footer
+.I footerfile
+] [ \-\-header
+.I headerfile
+] [ \-\-intro
+.I introfile
+] [ \-\-section
+.I section
+] [ \-\-title
+.I title
+] [
+.I filename.xml
+] [
+.I source file(s)
+]
+.br
+.B mxmldoc
 [ \-\-footer
 .I footerfile
 ] [ \-\-framed
@ -64,15 +89,15 @@ mxmldoc \- mini-xml documentation generator
 ]
 .br
 .B mxmldoc
-\-\-man
-.I manpage
 [ \-\-footer
 .I footerfile
 ] [ \-\-header
 .I headerfile
 ] [ \-\-intro
 .I introfile
-] [ \-\-section
+] \-\-man
+.I manpage
+[ \-\-section
 .I section
 ] [ \-\-title
 .I title
@ -101,13 +126,31 @@ documentation that is formatted according to the CUPS Developer
 Guide which is available at "http://www.cups.org/documentation.php".
 .SH OPTIONS
 .TP 5
+\-\-docset directory.docset
+.br
+Creates an Xcode documentation set in the specified directory.
+.TP 5
+\-\-docversion version
+.br
+Specifies the version number for the Xcode documentation set.
+.TP 5
+\-\-feedname name
+.br
+Specifies the Xcode documentation set feed name, typically the project or
+company name.
+.TP 5
+\-\-feedurl url
+.br
+Specifies the Xcode documentation set feed URL which must point to an ATOM file
+linking to updates.
+.TP 5
 \-\-footer footerfile
 .br
 Inserts the specified file at the bottom of the output documentation.
 .TP 5
 \-\-framed basename
 .br
-Created HTML documentation using frames - one for the table-of-contents and
+Creates HTML documentation using frames - one for the table-of-contents and
 one for the body.
 .TP 5
 \-\-header headerfile
--- a/doc/reference.html
+++ b/doc/reference.html
@ -2,7 +2,7 @@
 <html>
 <head>
 <title>Documentation</title>
-<meta name="creator" content="Mini-XML v2.5">
+<meta name="creator" content="Mini-XML v2.6">
 <style type="text/css"><!--
 body, p, h1, h2, h3, h4 {
  font-family: lucida grande, geneva, helvetica, arial, sans-serif;
@ -142,7 +142,6 @@ hspace="10" width="100" height="100" alt="C"></a>Library
 Reference</h1>

 <h2 class="title">Contents</h2>
-<ul class="contents">
 <li><a href="#FUNCTIONS">Functions</a><ul class="code">
 <li><a href="#mxmlAdd" title="Add a node to a tree.">mxmlAdd</a></li>
 <li><a href="#mxmlDelete" title="Delete a node and all of its children.">mxmlDelete</a></li>
@ -199,7 +198,7 @@ using a SAX callback.">mxmlSAXLoadString</a></li>
 <li><a href="#mxmlSetWrapMargin" title="Set the the wrap margin when saving XML data.">mxmlSetWrapMargin</a></li>
 <li><a href="#mxmlWalkNext" title="Walk to the next logical node in the tree.">mxmlWalkNext</a></li>
 <li><a href="#mxmlWalkPrev" title="Walk to the previous logical node in the tree.">mxmlWalkPrev</a></li>
-</ul>
+</ul></li>
 <li><a href="#TYPES">Data Types</a><ul class="code">
 	<li><a href="#mxml_attr_t" title="An XML element attribute value.">mxml_attr_t</a></li>
 	<li><a href="#mxml_custom_destroy_cb_t" title="Custom data destructor">mxml_custom_destroy_cb_t</a></li>
--- a/mxmldoc.c
+++ b/mxmldoc.c
--- a/testmxml.c
+++ b/testmxml.c
@ -452,8 +452,7 @@ main(int  argc,				/* I - Number of command-line args */
      return (1);
    }

-    if ((node = mxmlFindElement(node, tree, "choice", NULL, NULL,
-                                MXML_NO_DESCEND)) == NULL)
+    if (!mxmlFindElement(node, tree, "choice", NULL, NULL, MXML_NO_DESCEND))
    {
      fputs("Unable to find second <choice> element in XML tree!\n", stderr);
      mxmlDelete(tree);
@ -539,7 +538,7 @@ main(int  argc,				/* I - Number of command-line args */
  memset(event_counts, 0, sizeof(event_counts));

  if (argv[1][0] == '<')
-    tree = mxmlSAXLoadString(NULL, argv[1], type_cb, sax_cb, NULL);
+    mxmlSAXLoadString(NULL, argv[1], type_cb, sax_cb, NULL);
  else if ((fp = fopen(argv[1], "rb")) == NULL)
  {
    perror(argv[1]);
@ -551,7 +550,7 @@ main(int  argc,				/* I - Number of command-line args */
    * Read the file...
    */

-    tree = mxmlSAXLoadFile(NULL, fp, type_cb, sax_cb, NULL);
+    mxmlSAXLoadFile(NULL, fp, type_cb, sax_cb, NULL);

    fclose(fp);
  }