Re: [xml] [PATCH] Doc: do not mislead towards "infeasible" scenario wrt. xmlBufNodeDump
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ý > --- > > 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?'/> > > >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 > */ > -- > 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
Re: [xml] [PATCH] Doc: do not mislead towards "infeasible" scenario wrt. xmlBufNodeDump
On 11/07/19 20:00 +0200, Jan Pokorný wrote: > 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...) Also submitted as a merge request for more persistent tracking and possible discussion: https://gitlab.gnome.org/GNOME/libxml2/merge_requests/30 (As an aside, RelaxNG seems not to be in shape when any advanced grammar constructs are present, i.e., not just a matter of performance but rather the correctness of validation: https://gitlab.gnome.org/GNOME/libxml2/merge_requests/31) -- Jan (Poki) pgp9LlzhAzzYC.pgp Description: PGP signature ___ xml mailing list, project page http://xmlsoft.org/ xml@gnome.org https://mail.gnome.org/mailman/listinfo/xml
[xml] [PATCH] 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ý --- 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?'/> 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 */ -- 2.22.0 ___ xml mailing list, project page http://xmlsoft.org/ xml@gnome.org https://mail.gnome.org/mailman/listinfo/xml
