[libxml2] Doc: do not mislead towards "infeasible" scenario wrt. xmlBufNodeDump

[Nick Wellnhofer <nwellnhof src gnome org>]

commit 81958b6e94bce3b51effd1fa145daceab173b7a0
Author: Jan Pokorný <jpokorny redhat com>
Date:   Thu Jul 11 19:24:11 2019 +0200

    Doc: do not mislead towards "infeasible" scenario wrt. xmlBufNodeDump
    
    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ý <jpokorny redhat com>

 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.
 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span 
class="term"><i><tt>buffer</tt></i>:</span></td><td>a buffer</td></tr><tr><td><span 
class="term"><i><tt>cur</tt></i>:</span></td><td>the node being read</td></tr><tr><td><span 
class="term"><i><tt>Returns</tt></i>:</span></td><td>0 in case of success and -1 in case of 
error.</td></tr></tbody></table></div></div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlNodeDump"/>xmlNodeDump ()</h3><pre 
class="programlisting">int  xmlNodeDump                     (<a 
href="libxml2-tree.html#xmlBufferPtr">xmlBufferPtr</a> buf, <br/>                                    <a 
href="libxml2-tree.html#xmlDocPtr">xmlDocPtr</a> doc, <br/>                                  <a 
href="libxml2-tree.html#xmlNodePtr">xmlNodePtr</a> cur, <br/>                                        int 
level, <br/>                                        int format)<br/>
-</pre><p>Dump an XML node, recursive behaviour,children are printed too. Note that @format = 1 provide node 
indenting only if <a href="libxml2-globals.html#xmlIndentTreeOutput">xmlIndentTreeOutput</a> = 1 or 
xmlKeepBlanksDefault(0) was called Since this is using <a href="libxml2-tree.html#xmlBuffer">xmlBuffer</a> 
structures it is limited to 2GB and somehow deprecated, use xmlBufNodeDump() instead.</p>
+</pre><p>Dump an XML node, recursive behaviour,children are printed too. Note that @format = 1 provide node 
indenting only if <a href="libxml2-globals.html#xmlIndentTreeOutput">xmlIndentTreeOutput</a> = 1 or 
xmlKeepBlanksDefault(0) was called. Since this is using <a href="libxml2-tree.html#xmlBuffer">xmlBuffer</a> 
structures it is limited to 2GB and somehow deprecated, use xmlNodeDumpOutput() instead.</p>
 <div class="variablelist"><table border="0"><col align="left"/><tbody><tr><td><span 
class="term"><i><tt>buf</tt></i>:</span></td><td>the XML buffer output</td></tr><tr><td><span 
class="term"><i><tt>doc</tt></i>:</span></td><td>the document</td></tr><tr><td><span 
class="term"><i><tt>cur</tt></i>:</span></td><td>the current node</td></tr><tr><td><span 
class="term"><i><tt>level</tt></i>:</span></td><td>the imbrication level for indenting</td></tr><tr><td><span 
class="term"><i><tt>format</tt></i>:</span></td><td>is formatting allowed</td></tr><tr><td><span 
class="term"><i><tt>Returns</tt></i>:</span></td><td>the number of bytes written to the buffer or -1 in case 
of error</td></tr></tbody></table></div></div>
         <hr/>
         <div class="refsect2" lang="en"><h3><a name="xmlNodeDumpOutput"/>xmlNodeDumpOutput ()</h3><pre 
class="programlisting">void     xmlNodeDumpOutput               (<a 
href="libxml2-tree.html#xmlOutputBufferPtr">xmlOutputBufferPtr</a> buf, <br/>                                 
       <a href="libxml2-tree.html#xmlDocPtr">xmlDocPtr</a> doc, <br/>                                  <a 
href="libxml2-tree.html#xmlNodePtr">xmlNodePtr</a> cur, <br/>                                        int 
level, <br/>                                        int format, <br/>                                       
const char * encoding)<br/>
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?'/>
     </function>
     <function name='xmlNodeDump' file='tree' module='xmlsave'>
       <cond>defined(LIBXML_OUTPUT_ENABLED)</cond>
-      <info>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.</info>
+      <info>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.</info>
       <return type='int' info='the number of bytes written to the buffer or -1 in case of error'/>
       <arg name='buf' type='xmlBufferPtr' info='the XML buffer output'/>
       <arg name='doc' type='xmlDocPtr' info='the document'/>
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 @@
         <word name='xmlAttributeTablePtr'>
           <ref name='xmlCopyAttributeTable'/>
         </word>
-        <word name='xmlBufNodeDump'>
-          <ref name='xmlNodeDump'/>
-        </word>
         <word name='xmlBufPtr'>
           <ref name='xmlBufGetNodeContent'/>
         </word>
@@ -31493,6 +31490,9 @@
           <ref name='xmlNewTextWriterPushParser'/>
           <ref name='xmlNewTextWriterTree'/>
         </word>
+        <word name='xmlNodeDumpOutput'>
+          <ref name='xmlNodeDump'/>
+        </word>
         <word name='xmlNodeListGetString'>
           <ref name='xmlNodeListGetRawString'/>
         </word>
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
  */