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ý <jpoko...@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/ veill...@redhat.com | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ http://veillard.com/ | virtualization library http://libvirt.org/ _______________________________________________ xml mailing list, project page http://xmlsoft.org/ xml@gnome.org https://mail.gnome.org/mailman/listinfo/xml
