AIR
/
mxml
mirror of https://github.com/michaelrsweet/mxml.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
pull/227/head
Michael R Sweet 6 years ago
parent 911f74e0d0
commit e19d38b5a7
No known key found for this signature in database
GPG Key ID: 999559A027815955
9 changed files with 1240 additions and 1263 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 4
      README.md
  2. 28
      doc/basics.html
  3. 41
      doc/install.html
  4. 420
      doc/mxml.html
  5. 24
      doc/mxml.man
  6. BIN
      doc/mxml.pdf
  7. 20
      doc/mxmldoc.html
  8. 32
      doc/reference.html

4
README.md
Unescape View File

@ -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);

28
doc/basics.html
Unescape View File

@ -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
data nodes in the document contain whitespace-separated text
values. Other standard callbacks include
the <tt>MXML_OPAQUE_CALLBACK</tt> constant which specifies that all
data nodes in the document contain opaque string values with whitespace
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>.</p>
<tt>MXML_REAL_CALLBACK</tt>, and
<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 -->

41
doc/install.html
Unescape View File

@ -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>

420
doc/mxml.html
View File

File diff suppressed because it is too large Load Diff

24
doc/mxml.man
Unescape View File

@ -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

BIN
doc/mxml.pdf
View File

Binary file not shown.

20
doc/mxmldoc.html
Unescape View File

@ -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"
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>

32
doc/reference.html
Unescape View File

@ -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">

Write Preview
Loading…
Cancel
Save