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

@@ -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/>

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'/>

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>

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
  */