Update documentation for mxmldoc changes and use MXML_OPAQUE_CALLBACK for example (Issue #190)

README.md

@@ -82,7 +82,7 @@ You load an XML file using the `mxmlLoadFile()` function:
     mxml_node_t *tree;
 
     fp = fopen("filename.xml", "r");
-    tree = mxmlLoadFile(NULL, fp, MXML_NO_CALLBACK);
+    tree = mxmlLoadFile(NULL, fp, MXML_OPAQUE_CALLBACK);
     fclose(fp);
 
 Similarly, you save an XML file using the `mxmlSaveFile()` function:
@@ -102,7 +102,7 @@ functions load XML node trees from and save XML node trees to strings:
     mxml_node_t *tree;
 
     ...
-    tree = mxmlLoadString(NULL, buffer, MXML_NO_CALLBACK);
+    tree = mxmlLoadString(NULL, buffer, MXML_OPAQUE_CALLBACK);
 
     ...
     mxmlSaveString(tree, buffer, sizeof(buffer), MXML_NO_CALLBACK);

doc/basics.html

@@ -154,22 +154,22 @@ first and last child nodes for the element, respectively.</p>
 <a href="#mxmlGetInteger"><tt>mxmlGetInteger</tt></a> function retrieves the
 integer value for a node.</p>
 
-<h3>Opaque Nodes</h3>
+<h3>Opaque String Nodes</h3>
 
-<p>Opaque (<tt>MXML_OPAQUE</tt>) nodes are created using the
+<p>Opaque string (<tt>MXML_OPAQUE</tt>) nodes are created using the
 <a href="#mxmlNewOpaque"><tt>mxmlNewOpaque</tt></a> function. The
 <a href="#mxmlGetOpaque"><tt>mxmlGetOpaque</tt></a> function retrieves the
 opaque string pointer for a node. Opaque nodes are like string nodes but
 preserve all whitespace between nodes.</p>
 
-<h3>Text Nodes</h3>
+<h3>Text String Nodes</h3>
 
-<p>Text (<tt>MXML_TEXT</tt>) nodes are created using the
+<p>Text string (<tt>MXML_TEXT</tt>) nodes are created using the
 <a href="#mxmlNewText"><tt>mxmlNewText</tt></a> and
 <a href="#mxmlNewTextf"><tt>mxmlNewTextf</tt></a> functions. Each text node
-consists of a text string and (leading) whitespace value - the
+consists of a single word string and (leading) whitespace value - the
 <a href="#mxmlGetText"><tt>mxmlGetText</tt></a> function retrieves the
-text string pointer and whitespace value for a node.</p>
+string pointer and whitespace value for a node.</p>
 
 <!-- NEED 12 -->
 <h3>Processing Instruction Nodes</h3>
@@ -292,7 +292,7 @@ function:</p>
 
 fp = fopen("filename.xml", "r");
 tree = mxmlLoadFile(NULL, fp,
-                        MXML_TEXT_CALLBACK);
+                    MXML_OPAQUE_CALLBACK);
 fclose(fp);
 </pre>
 
@@ -313,12 +313,12 @@ the value type of the immediate children for a new element node:
 <tt>MXML_INTEGER</tt>, <tt>MXML_OPAQUE</tt>, <tt>MXML_REAL</tt>,
 or <tt>MXML_TEXT</tt>. Load callbacks are described in detail in
 <a href='#LOAD_CALLBACKS'>Chapter 3</a>. The example code uses
-the <tt>MXML_TEXT_CALLBACK</tt> constant which specifies that all
+the <tt>MXML_OPAQUE_CALLBACK</tt> constant which specifies that all
-data nodes in the document contain whitespace-separated text
+data nodes in the document contain opaque string values with whitespace
-values. Other standard callbacks include
+preserved. Other standard callbacks include
 <tt>MXML_IGNORE_CALLBACK</tt>, <tt>MXML_INTEGER_CALLBACK</tt>,
-<tt>MXML_OPAQUE_CALLBACK</tt>, and
+<tt>MXML_REAL_CALLBACK</tt>, and
-<tt>MXML_REAL_CALLBACK</tt>.</p>
+<tt>MXML_TEXT_CALLBACK</tt>.</p>
 
 <p>The <a href='#mxmlLoadString'><tt>mxmlLoadString</tt></a>
 function loads XML node trees from a string:</p>
@@ -330,7 +330,7 @@ function loads XML node trees from a string:</p>
 
 ...
 tree = mxmlLoadString(NULL, buffer,
-                          MXML_TEXT_CALLBACK);
+                      MXML_OPAQUE_CALLBACK);
 </pre>
 
 <p>The first and third arguments are the same as used for
@@ -488,7 +488,7 @@ e.g.:</p>
    to a URL */
 node = mxmlFindElement(tree, tree, "a",
                        "href",
-                           "http://www.easysw.com/",
+                       "http://www.example.com/",
                        MXML_DESCEND);
 </pre>
 <!-- NEED 5 -->

doc/install.html

@@ -73,46 +73,5 @@ directories:</p>
 </pre>
 
 
-<h2>Creating Mini-XML Packages</h2>
-
-<p>Mini-XML includes two files that can be used to create binary
-packages. The first file is <var>mxml.spec</var> which is used
-by the <tt>rpmbuild(8)</tt> software to create Red Hat Package
-Manager ("RPM") packages which are commonly used on Linux. Since
-<tt>rpmbuild</tt> wants to compile the software on its own, you
-can provide it with the Mini-XML tar file to build the
-package:</p>
-
-<pre>
-    <kbd>rpmbuild -ta mxml-<i>version</i>.tar.gz ENTER</kbd>
-</pre>
-
-<p>The second file is <var>mxml.list</var> which is used by the
-<tt>epm(1)</tt> program to create software packages in a variety
-of formats. The <tt>epm</tt> program is available from the
-following URL:</p>
-
-<pre>
-    <a href="http://www.epmhome.org/">http://www.epmhome.org/</a>
-</pre>
-
-<p>Use the <tt>make</tt> command with the <kbd>epm</kbd> target
-to create portable and native packages for your system:</p>
-
-<pre>
-    <kbd>make epm ENTER</kbd>
-</pre>
-
-<p>The packages are stored in a subdirectory named
-<var>dist</var> for your convenience. The portable packages
-utilize scripts and tar files to install the software on the
-target system. After extracting the package archive, use the
-<var>mxml.install</var> script to install the software.</p>
-
-<p>The native packages will be in the local OS's native format:
-RPM for Red Hat Linux, DPKG for Debian Linux, PKG for Solaris,
-and so forth. Use the corresponding commands to install the
-native packages.</p>
-
 </body>
 </html>

doc/mxml.man

@@ -578,6 +578,12 @@ const char * mxmlGetText (
 .PP
 \fBNULL\fR is returned if the node (or its first child) is not a text node.
 The "whitespace" argument can be \fBNULL\fR.
+.PP
+Note: Text nodes consist of whitespace-delimited words. You will only get
+single words of text when reading an XML file with \fBMXML_TEXT\fR nodes.
+If you want the entire string between elements in the XML file, you MUST read
+the XML file with \fBMXML_OPAQUE\fR nodes and get the resulting strings
+using the \fImxmlGetOpaque\fR function instead.
 
 
 .SS mxmlGetType
@@ -693,6 +699,12 @@ function returns the value type that should be used for child nodes.
 The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR,
 \fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for
 loading child (data) nodes of the specified type.
+.PP
+Note: The most common programming error when using the Mini-XML library is
+to load an XML file using the \fBMXML_TEXT_CALLBACK\fR, which returns inline
+text as a series of whitespace-delimited words, instead of using the
+\fBMXML_OPAQUE_CALLBACK\fR which returns the inline text as a single string
+(including whitespace).
 .SS mxmlLoadFile
 Load a file into an XML node tree.
 .PP
@@ -711,6 +723,12 @@ function returns the value type that should be used for child nodes.
 The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR,
 \fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for
 loading child (data) nodes of the specified type.
+.PP
+Note: The most common programming error when using the Mini-XML library is
+to load an XML file using the \fBMXML_TEXT_CALLBACK\fR, which returns inline
+text as a series of whitespace-delimited words, instead of using the
+\fBMXML_OPAQUE_CALLBACK\fR which returns the inline text as a single string
+(including whitespace).
 .SS mxmlLoadString
 Load a string into an XML node tree.
 .PP
@@ -729,6 +747,12 @@ function returns the value type that should be used for child nodes.
 The constants \fBMXML_INTEGER_CALLBACK\fR, \fBMXML_OPAQUE_CALLBACK\fR,
 \fBMXML_REAL_CALLBACK\fR, and \fBMXML_TEXT_CALLBACK\fR are defined for
 loading child (data) nodes of the specified type.
+.PP
+Note: The most common programming error when using the Mini-XML library is
+to load an XML file using the \fBMXML_TEXT_CALLBACK\fR, which returns inline
+text as a series of whitespace-delimited words, instead of using the
+\fBMXML_OPAQUE_CALLBACK\fR which returns the inline text as a single string
+(including whitespace).
 .SS mxmlNewCDATA
 Create a new CDATA node.
 .PP

doc/mxmldoc.html

@@ -75,20 +75,6 @@ create an EPUB book containing the HTML documentation, for example:</p>
 </pre>
 
 
-<h3>Creating Xcode Documentation Sets</h3>
-
-<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 foo.docset *.h *.c foo.xml ENTER</kbd>
-</pre>
-
-<p>Xcode documentation sets can only be built on macOS with Xcode 3.0 or
-higher installed.</p>
-
-
 <h2>Commenting Your Code</h2>
 
 <p>As noted previously, <tt>mxmldoc</tt> looks for in-line comments
@@ -159,9 +145,9 @@ following special <tt>@name ...@</tt> directive strings:</p>
 	discourage its use</li>
 
 	<li><tt>@exclude format[,...,format]@</tt> - excludes the item from the
-	documentation in the specified formats: "all" for all formats, "docset"
+	documentation in the specified formats: "all" for all formats, "epub"
-	for Xcode documentation sets, "epub" for EPUB books, "html" for HTML
+	for EPUB books, "html" for HTML output, and "man" for man page
-	output, and "man" for man page output</li>
+	output</li>
 
 	<li><tt>@private@</tt> - flags the item as private so it
 	will not be included in the documentation</li>

doc/reference.html

@@ -703,7 +703,13 @@ const char *mxmlGetText(<a href="#mxml_node_t">mxml_node_t</a> *node, int *white
         <p class="description">Text string or <code>NULL</code></p>
 <h4 class="discussion">Discussion</h4>
         <p class="discussion"><code>NULL</code> is returned if the node (or its first child) is not a text node.
-The &quot;whitespace&quot; argument can be <code>NULL</code>.
+The &quot;whitespace&quot; argument can be <code>NULL</code>.<br>
+<br>
+Note: Text nodes consist of whitespace-delimited words. You will only get
+single words of text when reading an XML file with <code>MXML_TEXT</code> nodes.
+If you want the entire string between elements in the XML file, you MUST read
+the XML file with <code>MXML_OPAQUE</code> nodes and get the resulting strings
+using the <a href="#mxmlGetOpaque"><code>mxmlGetOpaque</code></a> function instead.
 
 </p>
 <h3 class="function"><span class="info">&#160;Mini-XML 2.7&#160;</span><a id="mxmlGetType">mxmlGetType</a></h3>
@@ -845,7 +851,13 @@ single parent node like &lt;?xml&gt; for the entire file. The callback
 function returns the value type that should be used for child nodes.
 The constants <code>MXML_INTEGER_CALLBACK</code>, <code>MXML_OPAQUE_CALLBACK</code>,
 <code>MXML_REAL_CALLBACK</code>, and <code>MXML_TEXT_CALLBACK</code> are defined for
-loading child (data) nodes of the specified type.</p>
+loading child (data) nodes of the specified type.<br>
+<br>
+Note: The most common programming error when using the Mini-XML library is
+to load an XML file using the <code>MXML_TEXT_CALLBACK</code>, which returns inline
+text as a series of whitespace-delimited words, instead of using the
+<code>MXML_OPAQUE_CALLBACK</code> which returns the inline text as a single string
+(including whitespace).</p>
 <h3 class="function"><a id="mxmlLoadFile">mxmlLoadFile</a></h3>
         <p class="description">Load a file into an XML node tree.</p>
 <p class="code">
@@ -868,7 +880,13 @@ single parent node like &lt;?xml&gt; for the entire file. The callback
 function returns the value type that should be used for child nodes.
 The constants <code>MXML_INTEGER_CALLBACK</code>, <code>MXML_OPAQUE_CALLBACK</code>,
 <code>MXML_REAL_CALLBACK</code>, and <code>MXML_TEXT_CALLBACK</code> are defined for
-loading child (data) nodes of the specified type.</p>
+loading child (data) nodes of the specified type.<br>
+<br>
+Note: The most common programming error when using the Mini-XML library is
+to load an XML file using the <code>MXML_TEXT_CALLBACK</code>, which returns inline
+text as a series of whitespace-delimited words, instead of using the
+<code>MXML_OPAQUE_CALLBACK</code> which returns the inline text as a single string
+(including whitespace).</p>
 <h3 class="function"><a id="mxmlLoadString">mxmlLoadString</a></h3>
         <p class="description">Load a string into an XML node tree.</p>
 <p class="code">
@@ -891,7 +909,13 @@ single parent node like &lt;?xml&gt; for the entire string. The callback
 function returns the value type that should be used for child nodes.
 The constants <code>MXML_INTEGER_CALLBACK</code>, <code>MXML_OPAQUE_CALLBACK</code>,
 <code>MXML_REAL_CALLBACK</code>, and <code>MXML_TEXT_CALLBACK</code> are defined for
-loading child (data) nodes of the specified type.</p>
+loading child (data) nodes of the specified type.<br>
+<br>
+Note: The most common programming error when using the Mini-XML library is
+to load an XML file using the <code>MXML_TEXT_CALLBACK</code>, which returns inline
+text as a series of whitespace-delimited words, instead of using the
+<code>MXML_OPAQUE_CALLBACK</code> which returns the inline text as a single string
+(including whitespace).</p>
 <h3 class="function"><span class="info">&#160;Mini-XML 2.3&#160;</span><a id="mxmlNewCDATA">mxmlNewCDATA</a></h3>
         <p class="description">Create a new CDATA node.</p>
 <p class="code">