tree.c doc/* Elaborate in documentation discussion of xmlNewChild and
Tue Dec 16 20:40:40 MST 2003 John Fleck <jfleck@inkstain.net>
* tree.c
* doc/*
Elaborate in documentation discussion of xmlNewChild
and xmlNewTextChild. Thanks to Steve Lenti for pointing
out the usefulness of a more explicit explanation of the
reserved character escaping issue.
diff --git a/tree.c b/tree.c
index 56b47c6..3d01025 100644
--- a/tree.c
+++ b/tree.c
@@ -2351,7 +2351,11 @@
* Creation of a new child element, added at the end of @parent children list.
* @ns and @content parameters are optional (NULL). If @content is non NULL,
* a child TEXT node will be created containing the string @content.
- * NOTE: Use xmlNewChild() if entity support for @content is needed.
+ * NOTE: Use xmlNewChild() if @content will contain entities that need to be
+ * preserved. Use this function, xmlNewTextChild(), if you need to ensure that
+ * reserved XML chars that might appear in @content, such as the ampersand,
+ * greater-than or less-than signs, are automatically replaced by their XML
+ * escaped entity representations.
*
* Returns a pointer to the new node object.
*/
@@ -2722,10 +2726,9 @@
* Creation of a new child element, added at the end of @parent children list.
* @ns and @content parameters are optional (NULL). If @content is non NULL,
* a child list containing the TEXTs and ENTITY_REFs node will be created.
- * NOTE: @content is supposed to be a piece of XML CDATA, so it allow entities
- * references, but XML special chars need to be escaped first by using
- * xmlEncodeEntitiesReentrant(). Use xmlNewTextChild() if entities
- * support is not needed.
+ * NOTE: @content is supposed to be a piece of XML CDATA, so it allows entity
+ * references. XML special chars must be escaped first by using
+ * xmlEncodeEntitiesReentrant(), or xmlNewTextChild() should be used.
*
* Returns a pointer to the new node object.
*/