/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page xml-changes-qt6.html
    \title Changes to Qt XML
    \ingroup changes-qt-5-to-6
    \brief Migrate Qt XML to Qt 6.

    Qt 6 is a result of the conscious effort to make the framework more
    efficient and easy to use.

    We try to maintain binary and source compatibility for all the public
    APIs in each release. But some changes were inevitable in an effort to
    make Qt a better framework.

    In this topic we summarize those changes in Qt XML, and provide
    guidance to handle them.

    \section1 Simple API for XML (SAX) parser
    All \b SAX classes have been removed from Qt XML. 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

    As \b SAX classes have been removed from Qt XML, QDomDocument
    has been re-implemented using QXmlStreamReader.
    This causes a few behavioral changes:

    \list
        \li Attribute values will be normalized. For example,
        \c{<tag attr=" a \n b " />} is equivalent to \c{<tag attr="a b"/>}.
        \li Identical qualified attribute names are no longer allowed. This
        means attributes of an element must have unique names.
        \li Undeclared namespace prefixes are no longer allowed.
    \endlist

    If you use QDomDocument and rely on any of these, you must 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 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
*/
