From 81958b6e94bce3b51effd1fa145daceab173b7a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Pokorn=C3=BD?= Date: Thu, 11 Jul 2019 19:24:11 +0200 Subject: [PATCH] Doc: do not mislead towards "infeasible" scenario wrt. xmlBufNodeDump MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit At least when merely public API is to be leveraged, one cannot use xmlBufCreate function that would otherwise be a clear fit, and relying on some invariants wrt. how some other struct fields will get initialized along the construction/filling such parent struct and (ab)using that instead does not appear clever, either. Hence, instruct people what's the Right Thing for the moment, that is, make them use xmlNodeDumpOutput instead (together with likewise public xmlAllocOutputBuffer). Going forward, it's questionable what do with xmlBuf* family of functions that are once public, since they, for any practical purpose, cannot be used by the library clients (that's how I've run into this). Signed-off-by: Jan Pokorný --- doc/devhelp/libxml2-tree.html | 2 +- doc/libxml2-api.xml | 2 +- doc/libxml2-refs.xml | 6 +++--- xmlsave.c | 4 ++-- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/devhelp/libxml2-tree.html b/doc/devhelp/libxml2-tree.html index 44e1e03a..03e57f97 100644 --- a/doc/devhelp/libxml2-tree.html +++ b/doc/devhelp/libxml2-tree.html @@ -1401,7 +1401,7 @@ The content of this structure is not made public by the API.
buffer:a buffer
cur:the node being read
Returns:0 in case of success and -1 in case of error.

xmlNodeDump ()

int	xmlNodeDump			(xmlBufferPtr buf, 
					 xmlDocPtr doc, 
					 xmlNodePtr cur, 
					 int level, 
					 int format)

-

Dump an XML node, recursive behaviour,children are printed too. Note that @format = 1 provide node indenting only if xmlIndentTreeOutput = 1 or xmlKeepBlanksDefault(0) was called Since this is using xmlBuffer structures it is limited to 2GB and somehow deprecated, use xmlBufNodeDump() instead.

+

Dump an XML node, recursive behaviour,children are printed too. Note that @format = 1 provide node indenting only if xmlIndentTreeOutput = 1 or xmlKeepBlanksDefault(0) was called. Since this is using xmlBuffer structures it is limited to 2GB and somehow deprecated, use xmlNodeDumpOutput() instead.

buf:the XML buffer output
doc:the document
cur:the current node
level:the imbrication level for indenting
format:is formatting allowed
Returns:the number of bytes written to the buffer or -1 in case of error

xmlNodeDumpOutput ()

void	xmlNodeDumpOutput		(xmlOutputBufferPtr buf, 
					 xmlDocPtr doc, 
					 xmlNodePtr cur, 
					 int level, 
					 int format, 
					 const char * encoding)

diff --git a/doc/libxml2-api.xml b/doc/libxml2-api.xml
index 9cf6c72e..ccba52f2 100644
--- a/doc/libxml2-api.xml
+++ b/doc/libxml2-api.xml
@@ -11778,7 +11778,7 @@ Could we use @subtypes for this?'/>
     
     
       defined(LIBXML_OUTPUT_ENABLED)
-      Dump an XML node, recursive behaviour,children are printed too. Note that @format = 1 provide node indenting only if xmlIndentTreeOutput = 1 or xmlKeepBlanksDefault(0) was called Since this is using xmlBuffer structures it is limited to 2GB and somehow deprecated, use xmlBufNodeDump() instead.
+      Dump an XML node, recursive behaviour,children are printed too. Note that @format = 1 provide node indenting only if xmlIndentTreeOutput = 1 or xmlKeepBlanksDefault(0) was called. Since this is using xmlBuffer structures it is limited to 2GB and somehow deprecated, use xmlNodeDumpOutput() instead.
       
       
       
diff --git a/doc/libxml2-refs.xml b/doc/libxml2-refs.xml
index 3fe0876f..3109bac4 100644
--- a/doc/libxml2-refs.xml
+++ b/doc/libxml2-refs.xml
@@ -31120,9 +31120,6 @@
         
           
         
-        
-          
-        
         
           
         
@@ -31493,6 +31490,9 @@
           
           
         
+        
+          
+        
         
           
         
diff --git a/xmlsave.c b/xmlsave.c
index f7173ebb..bf805330 100644
--- a/xmlsave.c
+++ b/xmlsave.c
@@ -2186,9 +2186,9 @@ xmlAttrSerializeTxtContent(xmlBufferPtr buf, xmlDocPtr doc,
  *
  * Dump an XML node, recursive behaviour,children are printed too.
  * Note that @format = 1 provide node indenting only if xmlIndentTreeOutput = 1
- * or xmlKeepBlanksDefault(0) was called
+ * or xmlKeepBlanksDefault(0) was called.
  * Since this is using xmlBuffer structures it is limited to 2GB and somehow
- * deprecated, use xmlBufNodeDump() instead.
+ * deprecated, use xmlNodeDumpOutput() instead.
  *
  * Returns the number of bytes written to the buffer or -1 in case of error
  */