Doc: Remove deprecated API from XML processing overview

Pick-to: 5.15
Fixes: QTBUG-83873
Change-Id: I7fce8de11a9fb09a158f7ad5e32c0fcc323dbdf1
Reviewed-by: Sona Kurazyan <sona.kurazyan@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

1 files changed, 17 insertions, 243 deletions

diff --git a/src/xml/doc/src/xml-processing.qdoc b/src/xml/doc/src/xml-processing.qdoc
index 8ac279f8b6..226eeb196d 100644
--- a/src/xml/doc/src/xml-processing.qdoc
+++ b/src/xml/doc/src/xml-processing.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -29,7 +29,7 @@
     \group xml-tools
     \title XML Classes
 
-    \brief Classes that support XML, via, for example DOM and SAX.
+    \brief Classes that support XML.
 
     These classes are relevant to XML users.
 
@@ -42,10 +42,13 @@
 
     \brief An Overview of the XML processing facilities in Qt.
 
-    In addition to core XML support, classes for higher level querying
-    and manipulation of XML data are provided by the Qt XML Patterns
-    module. In the Qt SVG module, the QSvgRenderer and QSvgGenerator
-    classes can read and write a subset of SVG, an XML-based file
+    Qt provides two general-purpose sets of APIs to read and write well-formed
+    XML: \l{XML Streaming}{stream based} and
+    \l{Working with the DOM Tree}{DOM based}.
+
+    Qt also provides specific support for some XML dialects. For instance, the
+    Qt SVG module provides the QSvgRenderer and QSvgGenerator classes to read
+    and write a subset of SVG, an XML-based file
     format. Qt also provides helper functions that may be useful to
     those working with XML and XHTML: see Qt::escape() and
     Qt::convertFromPlainText().
@@ -56,7 +59,6 @@
     \li \l {Classes for XML Processing}
     \li \l {An Introduction to Namespaces}
     \li \l {XML Streaming}
-    \li \l {The SAX Interface}
     \li \l {Working with the DOM Tree}
     \endlist
 
@@ -202,7 +204,7 @@
     namespace prefix. In this case the local part and the qualified name
     are identical (i.e. \e chapter).
 
-    \sa {DOM Bookmarks Example}, {SAX Bookmarks Example}
+    \sa {DOM Bookmarks Example}
 */
 
 /*!
@@ -210,13 +212,12 @@
     \title XML Streaming
 
     \previouspage An Introduction to Namespaces
-    \nextpage The SAX Interface
+    \nextpage Working with the DOM Tree
 
-    Since version 4.3, Qt provides two new classes for reading and
-    writing XML: QXmlStreamReader and QXmlStreamWriter.
+    Qt provides two classes for reading and writing XML through a simple streaming
+    API:  QXmlStreamReader and QXmlStreamWriter.
 
-    The QXmlStreamReader and QXmlStreamWriter are two new classes provided
-    in Qt 4.3 and later. A stream reader reports an XML document as a stream
+    A stream reader reports an XML document as a stream
     of tokens. This differs from SAX as SAX applications provide handlers to
     receive XML events from the parser whereas the QXmlStreamReader drives the
     loop, pulling tokens from the reader when they are needed.
@@ -284,239 +285,11 @@
 */
 
 /*!
-    \page xml-sax.html
-    \title The SAX interface
-
-    \previouspage XML Streaming
-    \nextpage Working with the DOM Tree
-
-    SAX is an event-based standard interface for XML parsers.
-    The Qt interface follows the design of the SAX2 Java implementation.
-    Its naming scheme was adapted to fit the Qt naming conventions.
-    Details on SAX2 can be found at \l{http://www.saxproject.org}.
-
-    Support for SAX2 filters and the reader factory are under
-    development. The Qt implementation does not include the SAX1
-    compatibility classes present in the Java interface.
-
-    \section1 Introduction to SAX2
-
-    The SAX2 interface is an event-driven mechanism to provide the user with
-    document information. An "event" in this context means something
-    reported by the parser, for example, it has encountered a start tag,
-    or an end tag, etc.
-
-    To make it less abstract consider the following example:
-    \snippet code/doc_src_qtxml.qdoc 3
-
-    Whilst reading (a SAX2 parser is usually referred to as "reader")
-    the above document three events would be triggered:
-    \list 1
-    \li A start tag occurs (\c{<quote>}).
-    \li Character data (i.e. text) is found, "A quotation.".
-    \li An end tag is parsed (\c{</quote>}).
-    \endlist
-
-    Each time such an event occurs the parser reports it; you can set up
-    event handlers to respond to these events.
-
-    Whilst this is a fast and simple approach to read XML documents,
-    manipulation is difficult because data is not stored, simply handled
-    and discarded serially. The \l{Working with the DOM Tree}{DOM interface}
-    reads in and stores the whole document in a tree structure;
-    this takes more memory, but makes it easier to manipulate the
-    document's structure.
-
-    The Qt XML module provides an abstract class, \l QXmlReader, that
-    defines the interface for potential SAX2 readers. Qt includes a reader
-    implementation, \l QXmlSimpleReader, that is easy to adapt through
-    subclassing.
-
-    The reader reports parsing events through special handler classes:
-    \table
-    \header \li Handler class \li Description
-    \row \li \l QXmlContentHandler
-         \li Reports events related to the content of a document (e.g. the start tag
-            or characters).
-    \row \li \l QXmlDTDHandler
-         \li Reports events related to the DTD (e.g. notation declarations).
-    \row \li \l QXmlErrorHandler
-         \li Reports errors or warnings that occurred during parsing.
-    \row \li \l QXmlEntityResolver
-         \li Reports external entities during parsing and allows users to resolve
-            external entities themselves instead of leaving it to the reader.
-    \row \li \l QXmlDeclHandler
-         \li Reports further DTD related events (e.g. attribute declarations).
-    \row \li \l QXmlLexicalHandler
-         \li Reports events related to the lexical structure of the
-            document (the beginning of the DTD, comments etc.).
-    \endtable
-
-    These classes are abstract classes describing the interface. The \l
-    QXmlDefaultHandler class provides a "do nothing" default
-    implementation for all of them. Therefore users only need to overload
-    the QXmlDefaultHandler functions they are interested in.
-
-    To read input XML data a special class \l QXmlInputSource is used.
-
-    Apart from those already mentioned, the following SAX2 support classes
-    provide additional useful functionality:
-    \table
-    \header \li Class \li Description
-    \row \li \l QXmlAttributes
-         \li Used to pass attributes in a start element event.
-    \row \li \l QXmlLocator
-         \li Used to obtain the actual parsing position of an event.
-    \row \li \l QXmlNamespaceSupport
-         \li Used to implement namespace support for a reader. Note that
-            namespaces do not change the parsing behavior. They are only
-            reported through the handler.
-    \endtable
-
-    The \l{SAX Bookmarks Example} illustrates how to subclass
-    QXmlDefaultHandler to read an XML bookmark file (XBEL) and
-    how to generate XML by hand.
-
-    \section1 SAX2 Features
-
-    The behavior of an XML reader depends on its support for certain
-    optional features. For example, a reader may have the feature "report
-    attributes used for namespace declarations and prefixes along with
-    the local name of a tag". Like every other feature this has a unique
-    name represented by a URI: it is called
-    \e http://xml.org/sax/features/namespace-prefixes.
-
-    The Qt SAX2 implementation can report whether the reader has
-    particular functionality using the QXmlReader::hasFeature()
-    function. Available features can be tested with QXmlReader::feature(),
-    and switched on or off using QXmlReader::setFeature().
-
-    Consider the example
-    \snippet code/doc_src_qtxml.qdoc 4
-    A reader that does not support the \e
-    http://xml.org/sax/features/namespace-prefixes feature would report
-    the element name \e document but not its attributes \e xmlns:book and
-    \e xmlns with their values. A reader with the feature \e
-    http://xml.org/sax/features/namespace-prefixes reports the namespace
-    attributes if the \l{QXmlReader::feature()}{feature} is
-    switched on.
-
-    Other features include \e http://xml.org/sax/features/namespace
-    (namespace processing, implies \e
-    http://xml.org/sax/features/namespace-prefixes) and \e
-    http://xml.org/sax/features/validation (the ability to report
-    validation errors).
-
-    Whilst SAX2 leaves it to the user to define and implement whatever
-    features are required, support for \e
-    http://xml.org/sax/features/namespace (and thus \e
-    http://xml.org/sax/features/namespace-prefixes) is mandantory.
-    The \l QXmlSimpleReader implementation of \l QXmlReader,
-    supports them, and can do namespace processing.
-
-    \l QXmlSimpleReader is not validating, so it
-    does not support \e http://xml.org/sax/features/validation.
-
-    \section1 Namespace Support via Features
-
-    As we have seen in the previous section, we can configure the
-    behavior of the reader when it comes to namespace
-    processing. This is done by setting and unsetting the
-    \e http://xml.org/sax/features/namespaces and
-    \e http://xml.org/sax/features/namespace-prefixes features.
-
-    They influence the reporting behavior in the following way:
-    \list 1
-    \li Namespace prefixes and local parts of elements and attributes can
-    be reported.
-    \li The qualified names of elements and attributes are reported.
-    \li \l QXmlContentHandler::startPrefixMapping() and \l
-    QXmlContentHandler::endPrefixMapping() are called by the reader.
-    \li Attributes that declare namespaces (i.e. the attribute \e xmlns and
-    attributes starting with \e{xmlns:}) are reported.
-    \endlist
-
-    Consider the following element:
-    \snippet code/doc_src_qtxml.qdoc 5
-    With \e http://xml.org/sax/features/namespace-prefixes set to true
-    the reader will report four attributes; but with the \e
-    namespace-prefixes feature set to false only three, with the \e
-    xmlns:fnord attribute defining a namespace being "invisible" to the
-    reader.
-
-    The \e http://xml.org/sax/features/namespaces feature is responsible
-    for reporting local names, namespace prefixes and URIs. With \e
-    http://xml.org/sax/features/namespaces set to true the parser will
-    report \e title as the local name of the \e fnord:title attribute, \e
-    fnord being the namespace prefix and \e http://example.com/fnord/ as
-    the namespace URI. When \e http://xml.org/sax/features/namespaces is
-    false none of them are reported.
-
-    In the current implementation the Qt XML classes follow the definition
-    that the prefix \e xmlns itself isn't associated with any namespace at all
-    (see \l{http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-using}).
-    Therefore even with \e http://xml.org/sax/features/namespaces and
-    \e http://xml.org/sax/features/namespace-prefixes both set to true
-    the reader won't return either a local name, a namespace prefix or
-    a namespace URI for \e xmlns:fnord.
-
-    This might be changed in the future following the W3C suggestion
-    \l{http://www.w3.org/2000/xmlns/}
-    to associate \e xmlns with the namespace \e http://www.w3.org/2000/xmlns.
-
-    As the SAX2 standard suggests, \l QXmlSimpleReader defaults to having
-    \e http://xml.org/sax/features/namespaces set to true and
-    \e http://xml.org/sax/features/namespace-prefixes set to false.
-    When changing this behavior using \l QXmlSimpleReader::setFeature()
-    note that the combination of both features set to
-    false is illegal.
-
-    \section2 Summary
-
-    \l QXmlSimpleReader implements the following behavior:
-
-    \table
-    \header \li (namespaces, namespace-prefixes)
-            \li Namespace prefix and local part
-            \li Qualified names
-            \li Prefix mapping
-            \li xmlns attributes
-    \row \li (true, false) \li Yes \li Yes* \li Yes \li No
-    \row \li (true, true) \li Yes \li Yes \li Yes \li Yes
-    \row \li (false, true) \li No* \li Yes \li No* \li Yes
-    \row \li (false, false) \li {4,1} Illegal
-    \endtable
-
-    The behavior of the entries marked with an asterisk (*) is not specified by SAX.
-
-    \section1 Properties
-
-    Properties are a more general concept. They have a unique name,
-    represented as an URI, but their value is \c void*. Thus nearly
-    anything can be used as a property value. This concept involves some
-    danger, though: there is no means of ensuring type-safety; the user
-    must take care that they pass the right type. Properties are
-    useful if a reader supports special handler classes.
-
-    The URIs used for features and properties often look like URLs, e.g.
-    \c http://xml.org/sax/features/namespace. This does not mean that the
-    data required is at this address. It is simply a way of defining
-    unique names.
-
-    Anyone can define and use new SAX2 properties for their readers.
-    Property support is not mandatory.
-
-    To set or query properties the following functions are provided: \l
-    QXmlReader::setProperty(), \l QXmlReader::property() and \l
-    QXmlReader::hasProperty().
-*/
-
-/*!
     \page xml-dom.tml
     \title Working with the DOM Tree
     \target dom
 
-    \previouspage The SAX Interface
+    \previouspage XML Streaming
 
     DOM Level 2 is a W3C Recommendation for XML interfaces that maps the
     constituents of an XML document to a tree structure. The specification
@@ -527,7 +300,8 @@
 
     DOM provides an interface to access and change the content and
     structure of an XML file. It makes a hierarchical view of the document
-    (a tree view). Thus -- in contrast to the SAX2 interface -- an object
+    (a tree view). Thus -- in contrast to the streaming API provided
+    by QXmlStreamReader -- an object
     model of the document is resident in memory after parsing which makes
     manipulation easy.