Re: [xml] [PATCH] Doc: do not mislead towards "infeasible" scenario wrt. xmlBufNodeDump

[Daniel Veillard <veillard redhat com>]

  ACK :-)


Daniel

On Thu, Jul 11, 2019 at 08:00:39PM +0200, Jan Pokorný via xml wrote:
> 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>
> ---
>
> Hello Daniel, Nick, and others,
>
> I've run into a source of frustration based on an unset advice
> in the documentation that I hope to remove with this change.
> Or did I overlook something?  Thanks for pulling otherwise!
>
> (Indeed, there could be substantially bigger cut, like possibly
> retargeting xmlBufCreate as public, etc. but no wonders if there's
> not much will for that once the status quo lasted so long...)
>
> -- Jan (Poki)
>
>  doc/libxml2-api.xml  | 2 +-
>  doc/libxml2-refs.xml | 6 +++---
>  xmlsave.c            | 4 ++--
>  3 files changed, 6 insertions(+), 6 deletions(-)
>
> 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
>   */
> -- 
> 2.22.0
>
> _______________________________________________
> xml mailing list, project page  http://xmlsoft.org/
> xml gnome org
> https://mail.gnome.org/mailman/listinfo/xml

-- 
Daniel Veillard      | Red Hat Developers Tools http://developer.redhat.com/
veillard redhat com  | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | virtualization library  http://libvirt.org/