Commit e19d38b5 authored by Michael R Sweet's avatar Michael R Sweet

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

parent 911f74e0
......@@ -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);
......
This diff is collapsed.
This diff is collapsed.
......@@ -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>
This diff is collapsed.
......@@ -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
......
No preview for this file type
......@@ -26,7 +26,7 @@ header files in the current directory and produce a HTML
documentation file called <var>filename.html</var>:</p>
<pre>
<kbd>mxmldoc *.h *.c &gt;filename.html ENTER</kbd>
<kbd>mxmldoc *.h *.c &gt;filename.html ENTER</kbd>
</pre>
<p>You can also specify an XML file to create which contains all of
......@@ -35,21 +35,21 @@ command creates an XML file called <var>filename.xml</var> in
addition to the HTML file:</p>
<pre>
<kbd>mxmldoc filename.xml *.h *.c &gt;filename.html ENTER</kbd>
<kbd>mxmldoc filename.xml *.h *.c &gt;filename.html ENTER</kbd>
</pre>
<p>The <tt>--no-output</tt> option disables the normal HTML
output:</p>
<pre>
<kbd>mxmldoc --no-output filename.xml *.h *.c ENTER</kbd>
<kbd>mxmldoc --no-output filename.xml *.h *.c ENTER</kbd>
</pre>
<p>You can then run <tt>mxmldoc</tt> again with the XML file alone
to generate the HTML documentation:</p>
<pre>
<kbd>mxmldoc filename.xml &gt;filename.html ENTER</kbd>
<kbd>mxmldoc filename.xml &gt;filename.html ENTER</kbd>
</pre>
<h3>Creating Man Pages</h3>
......@@ -58,11 +58,11 @@ to generate the HTML documentation:</p>
create a man page instead of HTML documentation, for example:</p>
<pre>
<kbd>mxmldoc --man filename filename.xml \
&gt;filename.man ENTER</kbd>
<kbd>mxmldoc --man filename filename.xml \
&gt;filename.man ENTER</kbd>
<kbd>mxmldoc --man filename *.h *.c \
&gt;filename.man ENTER</kbd>
<kbd>mxmldoc --man filename *.h *.c \
&gt;filename.man ENTER</kbd>
</pre>
<h3>Creating EPUB Books</h3>
......@@ -71,24 +71,10 @@ create a man page instead of HTML documentation, for example:</p>
create an EPUB book containing the HTML documentation, for example:</p>
<pre>
<kbd>mxmldoc --epub foo.epub *.h *.c foo.xml ENTER</kbd>
<kbd>mxmldoc --epub foo.epub *.h *.c foo.xml ENTER</kbd>
</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
......@@ -107,47 +93,47 @@ example, the following code excerpt defines a key/value structure
and a function that creates a new instance of that structure:</p>
<pre>
/* A key/value pair. This is used with the
dictionary structure. */
struct keyval
{
char *key; /* Key string */
char *val; /* Value string */
};
/* Create a new key/value pair. */
struct keyval * /* New key/value pair */
new_keyval(
const char *key, /* Key string */
const char *val) /* Value string */
{
...
}
/* A key/value pair. This is used with the
dictionary structure. */
struct keyval
{
char *key; /* Key string */
char *val; /* Value string */
};
/* Create a new key/value pair. */
struct keyval * /* New key/value pair */
new_keyval(
const char *key, /* Key string */
const char *val) /* Value string */
{
...
}
</pre>
<p><tt>Mxmldoc</tt> also knows to remove extra asterisks (*) from
the comment string, so the comment string:</p>
<pre>
/*
* Compute the value of PI.
*
* The function connects to an Internet server
* that streams audio of mathematical monks
* chanting the first 100 digits of PI.
*/
/*
* Compute the value of PI.
*
* The function connects to an Internet server
* that streams audio of mathematical monks
* chanting the first 100 digits of PI.
*/
</pre>
<p>will be shown as:</p>
<pre>
Compute the value of PI.
Compute the value of PI.
The function connects to an Internet server
that streams audio of mathematical monks
chanting the first 100 digits of PI.
The function connects to an Internet server
that streams audio of mathematical monks
chanting the first 100 digits of PI.
</pre>
<p><a name="ATDIRECTIVES">Comments</a> can also include the
......@@ -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"
for Xcode documentation sets, "epub" for EPUB books, "html" for HTML
output, and "man" for man page output</li>
documentation in the specified formats: "all" for all formats, "epub"
for EPUB books, "html" for HTML output, and "man" for man page
output</li>
<li><tt>@private@</tt> - flags the item as private so it
will not be included in the documentation</li>
......@@ -183,9 +169,9 @@ and introduction text for the generated documentation. The
documentation. The title string is usually put in quotes:</p>
<pre>
<kbd>mxmldoc filename.xml \
--title "My Famous Documentation" \
&gt;filename.html ENTER</kbd>
<kbd>mxmldoc filename.xml \
--title "My Famous Documentation" \
&gt;filename.html ENTER</kbd>
</pre>
<p>The <tt>--section name</tt> option specifies the section for
......@@ -193,7 +179,7 @@ the documentation. For HTML documentation, the name is placed in
a HTML comment such as:</p>
<pre>
&lt;!-- SECTION: name -->
&lt;!-- SECTION: name -->
</pre>
<p>For man pages, the section name is usually just a number ("3"),
......@@ -201,7 +187,7 @@ or a number followed by a vendor name ("3acme"). The section name is
used in the <tt>.TH</tt> directive in the man page:</p>
<pre>
.TH mylibrary 3acme "My Title" ...
.TH mylibrary 3acme "My Title" ...
</pre>
<p>The default section name for man page output is "3". There is no
......
......@@ -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">
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment