From e796fe4caf3744c757db71581d31369f9f97d30f Mon Sep 17 00:00:00 2001
From: Michael R Sweet <michael.r.sweet@gmail.com>
Date: Mon, 2 Jul 2018 18:56:43 -0400
Subject: [PATCH] Add a Note: for all of the text/opaque string support (Issue
 #190)

---
 mxml-file.c | 18 ++++++++++++++++++
 mxml-get.c  |  8 +++++++-
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/mxml-file.c b/mxml-file.c
index cc79279..1f46892 100644
--- a/mxml-file.c
+++ b/mxml-file.c
@@ -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@,
  * @code MXML_REAL_CALLBACK@, and @code MXML_TEXT_CALLBACK@ are defined for
  * 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. */
@@ -142,6 +148,12 @@ mxmlLoadFd(mxml_node_t    *top,		/* I - Top node */
  * The constants @code MXML_INTEGER_CALLBACK@, @code MXML_OPAQUE_CALLBACK@,
  * @code MXML_REAL_CALLBACK@, and @code MXML_TEXT_CALLBACK@ are defined for
  * 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. */
@@ -167,6 +179,12 @@ mxmlLoadFile(mxml_node_t    *top,	/* I - Top node */
  * The constants @code MXML_INTEGER_CALLBACK@, @code MXML_OPAQUE_CALLBACK@,
  * @code MXML_REAL_CALLBACK@, and @code MXML_TEXT_CALLBACK@ are defined for
  * 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. */
diff --git a/mxml-get.c b/mxml-get.c
index abe2da5..b791979 100644
--- a/mxml-get.c
+++ b/mxml-get.c
@@ -1,7 +1,7 @@
 /*
  * 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
  * property of Michael R Sweet and are protected by Federal copyright
@@ -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.
  * 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@
  */