1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clarify QDomProcessingInstruction docs regarding XML declaration

Browse Source 
The documentation now explicitly explains that the XML declaration is
not a processing instruction according to the XML 1.0 Specification and
the W3C DOM Level 1/2 Core specifications. It advises against using
createProcessingInstruction() to insert an XML declaration and
recommends QXmlStreamWriter.
This clarification aims to reduce confusion caused by the similar syntax
of processing instructions and the XML declaration.

Fixes: QTBUG-21166
Pick-to: 6.9 6.8 6.5
Change-Id: I630e0e73bc8e4b6f145cb1e771a0a6fec54543cf
Reviewed-by: Safiyyah Moosa <safiyyah.moosa@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
This commit is contained in:
Magdalena Stojek 2025-03-26 07:34:01 +01:00
parent 56bfb02587
commit d2258328e3
1 changed files with 11 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
src/xml/dom/qdom.cpp
View File

@ -5703,9 +5703,17 @@ void QDomProcessingInstructionPrivate::save(QTextStream& s, int, int) const
not a processing instruction; among other differences, it cannot be not a processing instruction; among other differences, it cannot be
inserted into a document anywhere but on the first line. inserted into a document anywhere but on the first line.
Do not use this function to create an xml declaration, since although it \note Do not use this function to create an XML declaration. Although the
has the same syntax as a processing instruction, it isn't, and might not XML declaration shares the same syntax as a processing instruction, it
be treated by QDom as such. is not one. According to the
\l{https://www.w3.org/TR/xml/#sec-prolog-dtd}{XML 1.0 Specification} and the
\l{https://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-1590626202}{W3C DOM Structure Model},
the XML declaration is part of the document prolog and not part of the
DOM tree - meaning it should not be represented as a DOM node and cannot be
created or inserted via the DOM API.
If you need to generate a well-formed XML document that includes an XML
declaration, use QXmlStreamWriter, which provides proper support for
writing the declaration through \l {QXmlStreamWriter::}{writeStartDocument}.
The content of the processing instruction is retrieved with data() The content of the processing instruction is retrieved with data()
and set with setData(). The processing instruction's target is and set with setData(). The processing instruction's target is