Doc: Add Qt6 XML porting guide

Fixes: QTBUG-88026
Change-Id: I5f23e3ba984b7aaa326b713a03101797298c44d7
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
Reviewed-by: Sona Kurazyan <sona.kurazyan@qt.io>

1 files changed, 71 insertions, 1 deletions

diff --git a/src/xml/doc/src/qt6-changes.qdoc b/src/xml/doc/src/qt6-changes.qdoc
index 62e26a304e..365cce0d9a 100644
--- a/src/xml/doc/src/qt6-changes.qdoc
+++ b/src/xml/doc/src/qt6-changes.qdoc
@@ -41,6 +41,76 @@
     In this topic we summarize those changes in Qt XML, and provide
     guidance to handle them.
 
-    \section1 ADD STUFF HERE
+    \section1 Simple API for XML (SAX) parser
 
+    \section2 QXmlStreamReader
+
+    In Qt6, all \c SAX classes have been removed from Qt XML, please use
+    QXmlStreamReader for reading XML files. Here are some simple steps to
+    port your current code to QXmlStreamReader:
+
+    \oldcode
+        QFile *file = new QFile(...);
+        QXmlInputSource *source = new QXmlInputSource(file);
+
+        Handler *handler = new Handler;
+
+        QXmlSimpleReader xmlReader;
+        xmlReader.setErrorHandler(handler);
+        xmlReader.setContentHandler(handler);
+
+        if (xmlReader.parse(source)) {
+            ... // do processing
+        } else {
+            ... // do error handling
+        }
+    \newcode
+        QFile file = ...;
+        QXmlStreamReader reader(&file);
+
+        while (!reader.atEnd()) {
+            reader.readNext();
+            ... // do processing
+        }
+        if (reader.hasError()) {
+            ... // do error handling
+        }
+    \endcode
+
+    \section2  QDom and QDomDocument
+
+    In Qt6, \c SAX classes have been removed and therefore QDomDocument
+    cannot use them anymore. That's why it has been re-implemented using
+    the QXmlStreamReader. This brings a few behavioral changes:
+
+    \list
+        \li Attribute values will be normalized. For example
+        \c{<tag attr=" a \n b " />} will be equivalent to \c{<tag attr="a b"/>}.
+        \li Identical qualified attribute names won't be allowed anymore, i.e.
+        attributes of an element must have unique names.
+        \li Undeclared namespace prefixes won't be allowed anymore.
+    \endlist
+
+    If you are using QDomDocument and relying on any of these, please update
+    your code and XML documents accordingly.
+
+    \section2 Qt Core5 compatibility library
+
+    If your application or library cannot be ported right now, the \l
+    QXmlSimpleReader and related classes do still exist in Qt5Compat to keep
+    old code-bases working. If you want to use those SAX classes further, you
+    need to link against the new Qt5Compat module and add this line to your \l
+    qmake \c .pro file:
+
+    \code
+        QT += core5compat
+    \endcode
+
+    In case you already ported your application or library to the
+    \l {Build with CMake}{cmake} build system, add the following to your
+    \c CMakeList.txt:
+    \code
+        PUBLIC_LIBRARIES
+            Qt::Core5Compat
+    \endcode
 */