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.8 6.5
Change-Id: I630e0e73bc8e4b6f145cb1e771a0a6fec54543cf
Reviewed-by: Safiyyah Moosa <safiyyah.moosa@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
(cherry picked from commit d2258328e39ab8695e8034fe85cec7a18884f6d2)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
This commit is contained in:
Magdalena Stojek 2025-03-26 07:34:01 +01:00 committed by Qt Cherry-pick Bot
parent 013793a783
commit 64fd9edb2c
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
inserted into a document anywhere but on the first line.
Do not use this function to create an xml declaration, since although it
has the same syntax as a processing instruction, it isn't, and might not
be treated by QDom as such.
\note Do not use this function to create an XML declaration. Although the
XML declaration shares the same syntax as a processing instruction, it
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()
and set with setData(). The processing instruction's target is