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

Add a Note: for all of the text/opaque string support (Issue #190)

parent 0b896710
...@@ -106,6 +106,12 @@ static int mxml_write_ws(mxml_node_t *node, void *p, ...@@ -106,6 +106,12 @@ static int mxml_write_ws(mxml_node_t *node, void *p,
* The constants @code MXML_INTEGER_CALLBACK@, @code MXML_OPAQUE_CALLBACK@, * The constants @code MXML_INTEGER_CALLBACK@, @code MXML_OPAQUE_CALLBACK@,
* @code MXML_REAL_CALLBACK@, and @code MXML_TEXT_CALLBACK@ are defined for * @code MXML_REAL_CALLBACK@, and @code MXML_TEXT_CALLBACK@ are defined for
* loading child (data) nodes of the specified type. * loading child (data) nodes of the specified type.
*
* Note: The most common programming error when using the Mini-XML library is
* to load an XML file using the @code MXML_TEXT_CALLBACK@, which returns inline
* text as a series of whitespace-delimited words, instead of using the
* @code MXML_OPAQUE_CALLBACK@ which returns the inline text as a single string
* (including whitespace).
*/ */
mxml_node_t * /* O - First node or @code NULL@ if the file could not be read. */ mxml_node_t * /* O - First node or @code NULL@ if the file could not be read. */
...@@ -142,6 +148,12 @@ mxmlLoadFd(mxml_node_t *top, /* I - Top node */ ...@@ -142,6 +148,12 @@ mxmlLoadFd(mxml_node_t *top, /* I - Top node */
* The constants @code MXML_INTEGER_CALLBACK@, @code MXML_OPAQUE_CALLBACK@, * The constants @code MXML_INTEGER_CALLBACK@, @code MXML_OPAQUE_CALLBACK@,
* @code MXML_REAL_CALLBACK@, and @code MXML_TEXT_CALLBACK@ are defined for * @code MXML_REAL_CALLBACK@, and @code MXML_TEXT_CALLBACK@ are defined for
* loading child (data) nodes of the specified type. * loading child (data) nodes of the specified type.
*
* Note: The most common programming error when using the Mini-XML library is
* to load an XML file using the @code MXML_TEXT_CALLBACK@, which returns inline
* text as a series of whitespace-delimited words, instead of using the
* @code MXML_OPAQUE_CALLBACK@ which returns the inline text as a single string
* (including whitespace).
*/ */
mxml_node_t * /* O - First node or @code NULL@ if the file could not be read. */ mxml_node_t * /* O - First node or @code NULL@ if the file could not be read. */
...@@ -167,6 +179,12 @@ mxmlLoadFile(mxml_node_t *top, /* I - Top node */ ...@@ -167,6 +179,12 @@ mxmlLoadFile(mxml_node_t *top, /* I - Top node */
* The constants @code MXML_INTEGER_CALLBACK@, @code MXML_OPAQUE_CALLBACK@, * The constants @code MXML_INTEGER_CALLBACK@, @code MXML_OPAQUE_CALLBACK@,
* @code MXML_REAL_CALLBACK@, and @code MXML_TEXT_CALLBACK@ are defined for * @code MXML_REAL_CALLBACK@, and @code MXML_TEXT_CALLBACK@ are defined for
* loading child (data) nodes of the specified type. * loading child (data) nodes of the specified type.
*
* Note: The most common programming error when using the Mini-XML library is
* to load an XML file using the @code MXML_TEXT_CALLBACK@, which returns inline
* text as a series of whitespace-delimited words, instead of using the
* @code MXML_OPAQUE_CALLBACK@ which returns the inline text as a single string
* (including whitespace).
*/ */
mxml_node_t * /* O - First node or @code NULL@ if the string has errors. */ mxml_node_t * /* O - First node or @code NULL@ if the string has errors. */
......
/* /*
* Node get functions for Mini-XML, a small XML file parsing library. * Node get functions for Mini-XML, a small XML file parsing library.
* *
* Copyright 2014-2017 by Michael R Sweet. * Copyright 2014-2018 by Michael R Sweet.
* *
* These coded instructions, statements, and computer programs are the * These coded instructions, statements, and computer programs are the
* property of Michael R Sweet and are protected by Federal copyright * property of Michael R Sweet and are protected by Federal copyright
...@@ -346,6 +346,12 @@ mxmlGetReal(mxml_node_t *node) /* I - Node to get */ ...@@ -346,6 +346,12 @@ mxmlGetReal(mxml_node_t *node) /* I - Node to get */
* @code NULL@ is returned if the node (or its first child) is not a text node. * @code NULL@ is returned if the node (or its first child) is not a text node.
* The "whitespace" argument can be @code NULL@. * The "whitespace" argument can be @code NULL@.
* *
* 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@ nodes.
* If you want the entire string between elements in the XML file, you MUST read
* the XML file with @code MXML_OPAQUE@ nodes and get the resulting strings
* using the @link mxmlGetOpaque@ function instead.
*
* @since Mini-XML 2.7@ * @since Mini-XML 2.7@
*/ */
......
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