Long live Qt 4.5!

1 files changed, 893 insertions, 0 deletions

diff --git a/doc/src/qtxmlpatterns.qdoc b/doc/src/qtxmlpatterns.qdoc
new file mode 100644
index 0000000..cb260fc
--- /dev/null
+++ b/doc/src/qtxmlpatterns.qdoc
@@ -0,0 +1,893 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \module QtXmlPatterns
+    \title QtXmlPatterns Module
+    \since 4.4
+    \contentspage Qt's Modules
+    \previouspage QtXml
+    \nextpage Phonon Module
+    \ingroup modules
+    \ingroup scripting
+
+    \keyword Patternist
+
+    \brief An overview of Qt's support for using XQuery and XPath in
+    Qt programs.
+
+    \tableofcontents
+
+    \section1 Introduction
+
+    XQuery is a language for traversing XML documents to select and
+    aggregate items of interest and to transform them for output as
+    XML or some other format. XPath is the \e{element selection} part
+    of XQuery.
+
+    The QtXmlPatterns module supports using
+    \l{http://www.w3.org/TR/xquery} {XQuery 1.0} and
+    \l{http://www.w3.org/TR/xpath20} {XPath 2.0} in Qt applications,
+    for querying XML data \e{and} for querying
+    \l{QAbstractXmlNodeModel} {non-XML data that can be modeled to
+    look like XML}. The QtXmlPatterns module is included in the \l{Qt
+    Full Framework Edition}, and the \l{Open Source Versions of Qt}.
+    Readers who are not familiar with the XQuery/XPath language can read
+    \l {A Short Path to XQuery} for a brief introduction.
+
+    \section1 Advantages of using QtXmlPatterns and XQuery
+
+    The XQuery/XPath language simplifies data searching and
+    transformation tasks by eliminating the need for doing a lot of
+    C++ or Java procedural programming for each new query task. Here
+    is an XQuery that constructs a bibliography of the contents of a
+    library:
+
+    \target qtxmlpatterns_example_query
+    \quotefile snippets/patternist/introductionExample.xq
+
+    First, the query opens a \c{<bibliography>} element in the
+    output. The
+    \l{xquery-introduction.html#using-path-expressions-to-match-select-items}
+    {embedded path expression} then loads the XML document describing
+    the contents of the library (\c{library.xml}) and begins the
+    search. For each \c{<book>} element it finds, where the publisher
+    was Addison-Wesley and the publication year was after 1991, it
+    creates a new \c{<book>} element in the output as a child of the
+    open \c{<bibliography>} element. Each new \c{<book>} element gets
+    the book's title as its contents and the book's publication year
+    as an attribute. Finally, the \c{<bibliography>} element is
+    closed.
+
+    The advantages of using QtXmlPatterns and XQuery in your Qt
+    programs are summarized as follows:
+
+    \list
+
+    \o \bold{Ease of development}: All the C++ programming required to
+       perform data query tasks can be replaced by a simple XQuery
+       like the example above.
+
+    \o \bold{Comprehensive functionality}: The
+       \l{http://www.w3.org/TR/xquery/#id-expressions} {expression
+       syntax} and rich set of
+       \l{http://www.w3.org/TR/xpath-functions} {functions and
+       operators} provided by XQuery are sufficient for performing any
+       data searching, selecting, and sorting tasks.
+
+    \o \bold{Conformance to standards}: Conformance to all applicable
+       XML and XQuery standards ensures that QtXmlPatterns can always
+       process XML documents generated by other conformant
+       applications, and that XML documents created with QtXmlPatterns
+       can be processed by other conformant applications.
+
+    \o \bold{Maximal flexibility} The QtXmlPatterns module can be used
+       to query XML data \e{and} non-XML data that can be
+       \l{QAbstractXmlNodeModel} {modeled to look like XML}.
+
+    \endlist
+
+    \section1 Using the QtXmlPatterns module
+
+    There are two ways QtXmlPatterns can be used to evaluate queries.
+    You can run the query engine in your Qt application using the
+    QtXmlPatterns C++ API, or you can run the query engine from the
+    command line using Qt's \c{xmlpatterns} command line utility.
+
+    \section2 Running the query engine from your Qt application
+
+    To access the QtXmlPatterns C++ API from your Qt application,
+    include the QtXmlPatterns classes at compile time:
+
+    \snippet doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc 0
+
+    Link the compiled application with the QtXmlPatterns module by
+    adding the following line to the
+    \l{qmake-project-files.html#declaring-qt-libraries} {QT line} in
+    your qmake \c{.pro} file:
+
+    \snippet doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc 1
+
+    If we save the example XQuery shown above in a text file (e.g.
+    \c{myquery.xq}), we can run it from a Qt application using a
+    standard QtXmlPatterns code sequence:
+
+    \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 3
+
+    First construct a QFile for the text file containing the XQuery
+    (\c{myquery.xq}). Then create an instance of QXmlQuery and call
+    its \l{QXmlQuery::}{setQuery()} function to load and parse the
+    XQuery file. Then create an \l{QXmlSerializer} {XML serializer} to
+    output the query's result set as unformatted XML. Finally, call
+    the \l{QXmlQuery::}{evaluateTo()} function to evaluate the query
+    and serialize the results as XML.
+
+    \note If you compile Qt yourself, the QtXmlPatterns module will
+    \e{not} be built if exceptions are disabled, or if you compile Qt
+    with a compiler that doesn't support member templates, e.g., MSVC
+    6.
+
+    See the QXmlQuery documentation for more information about the
+    QtXmlPatterns C++ API.
+
+    \section2 Running the query engine from the command line utility
+
+    \e xmlpatterns is a command line utility for running XQueries.  It
+    expects the name of a file containing the XQuery text.
+
+    \snippet doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc 2
+
+    The XQuery in \c{myQuery.xq} will be evaluated and its output
+    written to \c stdout. Pass the \c -help switch to get the list of
+    input flags and their meanings.
+
+    xmlpatterns can be used in scripting. However, the descriptions
+    and messages it outputs were not meant to be parsed and may be
+    changed in future releases of Qt.
+
+    \target QtXDM
+    \section1 The XQuery Data Model
+
+    XQuery represents data items as \e{atomic values} or \e{nodes}. An
+    atomic value is a value in the domain of one of the
+    \l{http://www.w3.org/TR/xmlschema-2/#built-in-datatypes} {built-in
+    datatypes} defined in \l{http://www.w3.org/TR/xmlschema-2} {Part
+    2} of the W3C XML Schema. A node is normally an XML element or
+    attribute, but when non-XML data is \l{QAbstractXmlNodeModel}
+    {modeled to look like XML}, a node can also represent a non-XML
+    data items.
+
+    When you run an XQuery using the C++ API in a Qt application, you
+    will often want to bind program variables to $variables in the
+    XQuery. After the query is evaluated, you will want to interpret
+    the sequence of data items in the result set.
+
+    \section2 Binding program variables to XQuery variables
+
+    When you want to run a parameterized XQuery from your Qt
+    application, you will need to \l{QXmlQuery::bindVariable()} {bind
+    variables} in your program to $name variables in your XQuery.
+
+    Suppose you want to parameterize the bibliography XQuery in the
+    example above. You could define variables for the catalog that
+    contains the library (\c{$file}), the publisher name
+    (\c{$publisher}), and the year of publication (\c{$year}):
+
+    \target qtxmlpatterns_example_query2
+    \quotefile snippets/patternist/introExample2.xq
+
+    Modify the QtXmlPatterns code to use one of the \l{QXmlQuery::}
+    {bindVariable()} functions to bind a program variable to each
+    XQuery $variable:
+
+    \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 4
+
+    Each program variable is passed to QtXmlPatterns as a QVariant of
+    the type of the C++ variable or constant from which it is
+    constructed. Note that QtXmlPatterns assumes that the type of the
+    QVariant in the bindVariable() call is the correct type, so the
+    $variable it is bound to must be used in the XQuery accordingly.
+    The following table shows how QVariant types are mapped to XQuery
+    $variable types:
+
+    \table
+
+    \header
+        \o QVariant type
+        \o XQuery $variable type
+
+    \row
+        \o QVariant::LongLong
+        \o \c xs:integer
+
+    \row
+        \o QVariant::Int
+        \o \c xs:integer
+
+    \row
+        \o QVariant::UInt
+        \o \c xs:nonNegativeInteger
+
+    \row
+        \o QVariant::ULongLong
+        \o \c xs:unsignedLong
+
+    \row
+        \o QVariant::String
+        \o \c xs:string
+
+    \row
+        \o QVariant::Double
+        \o \c xs:double
+
+    \row
+        \o QVariant::Bool
+        \o \c xs:boolean
+
+    \row
+        \o QVariant::Double
+        \o \c xs:decimal
+
+    \row
+        \o QVariant::ByteArray
+        \o \c xs:base64Binary
+
+    \row
+        \o QVariant::StringList
+        \o \c xs:string*
+
+    \row
+        \o QVariant::Url
+        \o \c xs:string
+
+    \row
+        \o QVariant::Date
+        \o \c xs:date.
+
+    \row
+        \o QVariant::DateTime
+        \o \c xs:dateTime
+
+    \row
+        \o QVariant::Time.
+        \o \c xs:time. (see \l{Binding To Time}{Binding To
+        QVariant::Time} below)
+
+    \row
+        \o QVariantList
+        \o (see \l{Binding To QVariantList}{Binding To QVariantList}
+           below)
+
+    \endtable
+
+    A type not shown in the table is not supported and will cause
+    undefined XQuery behavior or a $variable binding error, depending
+    on the context in the XQuery where the variable is used.
+
+    \target Binding To Time
+    \section3 Binding To QVariant::Time
+
+    Because the instance of QTime used in QVariant::Time does not
+    include a zone offset, an instance of QVariant::Time should not be
+    bound to an XQuery variable of type \c xs:time, unless the QTime is
+    UTC. When binding a non-UTC QTime to an XQuery variable, it should
+    first be passed as a string, or converted to a QDateTime with an arbitrary
+    date, and then bound to an XQuery variable of type \c xs:dateTime.
+
+    \target Binding To QVariantList
+    \section3 Binding To QVariantList
+
+    A QVariantList can be bound to an XQuery $variable. All the
+    \l{QVariant}s in the list must be of the same atomic type, and the
+    $variable the variant list is bound to must be of that same atomic
+    type. If the QVariants in the list are not all of the same atomic
+    type, the XQuery behavior is undefined.
+
+    \section2 Interpreting XQuery results
+
+    When the results of an XQuery are returned in a sequence of \l
+    {QXmlResultItems} {result items}, atomic values in the sequence
+    are treated as instances of QVariant. Suppose that instead of
+    serializing the results of the XQuery as XML, we process the
+    results programatically. Modify the standard QtXmlPatterns code
+    sequence to call the overload of QXmlQuery::evaluateTo() that
+    populates a sequence of \l {QXmlResultItems} {result items} with
+    the XQuery results:
+
+    \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 5
+
+    Iterate through the \l {QXmlResultItems} {result items} and test
+    each QXmlItem to see if it is an atomic value or a node. If it is
+    an atomic value, convert it to a QVariant with \l {QXmlItem::}
+    {toAtomicValue()} and switch on its \l {QVariant::type()} {variant
+    type} to handle all the atomic values your XQuery might return.
+    The following table shows the QVariant type to expect for each
+    atomic value type (or QXmlName):
+
+    \table
+
+    \header
+        \o XQuery result item type
+        \o QVariant type returned
+
+    \row
+        \o \c xs:QName
+        \o QXmlName (see \l{Handling QXmlNames}{Handling QXmlNames}
+        below)
+
+    \row
+        \o \c xs:integer
+        \o QVariant::LongLong
+
+    \row
+        \o \c xs:string
+        \o QVariant::String
+
+    \row
+        \o \c xs:string*
+        \o QVariant::StringList
+
+    \row
+        \o \c xs:double
+        \o QVariant::Double
+
+    \row
+        \o \c xs:float
+        \o QVariant::Double
+
+    \row
+        \o \c xs:boolean
+        \o QVariant::Bool
+
+    \row
+        \o \c xs:decimal
+        \o QVariant::Double
+
+    \row
+        \o \c xs:hexBinary
+        \o QVariant::ByteArray
+
+    \row
+        \o \c xs:base64Binary
+        \o QVariant::ByteArray
+
+    \row
+        \o \c xs:gYear
+        \o QVariant::DateTime
+
+    \row
+        \o \c xs:gYearMonth
+        \o QVariant::DateTime
+
+    \row
+        \o \c xs:gMonthDay
+        \o QVariant::DateTime
+
+    \row
+        \o \c xs:gDay
+        \o QVariant::DateTime
+
+    \row
+        \o \c xs:gMonth
+        \o QVariant::DateTime
+
+    \row
+        \o \c xs:anyURI
+        \o QVariant::Url
+
+    \row
+        \o \c xs:untypedAtomic
+        \o QVariant::String
+
+    \row
+        \o \c xs:ENTITY
+        \o QVariant::String
+
+    \row
+        \o \c xs:date
+        \o QVariant::DateTime
+
+    \row
+        \o \c xs:dateTime
+        \o QVariant::DateTime
+
+    \row
+        \o \c xs:time
+        \o (see \l{xstime-not-mapped}{No mapping for xs:time} below)
+
+    \endtable
+
+    \target Handling QXmlNames
+    \section3 Handling QXmlNames
+
+    If your XQuery can return atomic value items of type \c{xs:QName},
+    they will appear in your QXmlResultItems as instances of QXmlName.
+    Since the QVariant class does not support the QXmlName class
+    directly, extracting them from QXmlResultItems requires a bit of
+    slight-of-hand using the \l{QMetaType} {Qt metatype system}. We
+    must modify our example to use a couple of template functions, a
+    friend of QMetaType (qMetaTypeId<T>()) and a friend of QVariant
+    (qVariantValue<T>()):
+
+    \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 6
+
+    To access the strings in a QXmlName returned by an
+    \l{QXmlQuery::evaluateTo()} {XQuery evaluation}, the QXmlName must
+    be accessed with the \l{QXmlNamePool} {name pool} from the
+    instance of QXmlQuery that was used for the evaluation.
+
+    \target xstime-not-mapped
+    \section3 No mapping for xs:time
+
+    An instance of \c xs:time can't be represented correctly as an
+    instance of QVariant::Time, unless the \c xs:time is a UTC time.
+    This is because xs:time has a zone offset (0 for UTC) in addition
+    to the time value, which the QTime in QVariant::Time does not
+    have. This means that if an XQuery tries to return an atomic value
+    of type \c xs:time, an invalid QVariant will be returned. A query
+    can return an atomic value of type xs:time by either converting it
+    to an \c xs:dateTime with an arbitrary date, or to an \c xs:string.
+
+    \section1 Using XQuery with Non-XML Data
+
+    Although the XQuery language was designed for querying XML, with
+    QtXmlPatterns one can use XQuery for querying any data that can
+    be modeled to look like XML. Non-XML data is modeled to look like
+    XML by loading it into a custom subclass of QAbstractXmlNodeModel,
+    where it is then presented to the QtXmlPatterns XQuery engine via
+    the same API the XQuery engine uses for querying XML.
+
+    When QtXmlPatterns loads and queries XML files and produces XML
+    output, it can always load the XML data into its default XML node
+    model, where it can be traversed efficiently. The XQuery below
+    traverses the product orders found in the XML file \e myOrders.xml
+    to find all the skin care product orders and output them ordered
+    by shipping date.
+
+    \quotefile snippets/patternist/introAcneRemover.xq
+
+    QtXmlPatterns can be used out of the box to perform this
+    query, provided \e myOrders.xml actually contains well-formed XML. It
+    can be loaded directly into the default XML node model and
+    traversed. But suppose we want QtXmlPatterns to perform queries on
+    the hierarchical structure of the local file system. The default
+    XML node model in QtXmlPatterns is not suitable for navigating the
+    file system, because there is no XML file to load that contains a
+    description of it. Such an XML file, if it existed, might look
+    something like this:
+
+    \quotefile snippets/patternist/introFileHierarchy.xml
+
+    The \l{File System Example}{File System Example} does exactly this.
+
+    There is no such file to load into the default XML node model, but
+    one can write a subclass of QAbstractXmlNodeModel to represent the
+    file system. This custom XML node model, once populated with all
+    the directory and file descriptors obtained directly from the
+    system, presents the complete file system hierarchy to the query
+    engine via the same API used by the default XML node model to
+    present the contents of an XML file. In other words, once the
+    custom XML node model is populated, it presents the file system to
+    the query engine as if a description of it had been loaded into
+    the default XML node model from an XML file like the one shown
+    above.
+
+    Now we can write an XQuery to find all the XML files and parse
+    them to find the ones that don't contain well-formed XML.
+
+    \quotefromfile snippets/patternist/introNavigateFS.xq
+    \skipto <html>
+    \printuntil
+
+    Without QtXmlPatterns, there is no simple way to solve this kind
+    of problem. You might do it by writing a C++ program to traverse
+    the file system, sniff out all the XML files, and submit each one
+    to an XML parser to test that it contains valid XML. The C++ code
+    required to write that program will probably be more complex than
+    the C++ code required to subclass QAbstractXmlNodeModel, but even
+    if the two are comparable, your custom C++ program can be used
+    only for that one task, while your custom XML node model can be
+    used by any XQuery that must navigate the file system.
+
+    The general approach to using XQuery to perform queries on non-XML
+    data has been a three step process. In the first step, the data is
+    loaded into a non-XML data model. In the second step, the non-XML
+    data model is serialized as XML and output to XML (text) files. In
+    the final step, an XML tool loads the XML files into a second, XML
+    data model, where the XQueries can be performed.  The development
+    cost of implementing this process is often high, and the three
+    step system that results is inefficient because the two data
+    models must be built and maintained separately.
+
+    With QtXmlPatterns, subclassing QAbstractXmlNodeModel eliminates
+    the transformation required to convert the non-XML data model to
+    the XML data model, because there is only ever one data model
+    required. The non-XML data model presents the non-XML data to the
+    query engine via the XML data model API. Also, since the query
+    engine uses the API to access the QAbstractXmlNodeModel, the data
+    model subclass can construct the elements, attributes and other
+    data on demand, responding to the query's specific requests.  This
+    can greatly improve efficiency, because it means the entire model
+    might not have to be built. For example, in the file system model
+    above, it is not necessary to build an instance for a whole
+    XML file representing the whole file system. Instead nodes are
+    created on demand, which also likely is a small subset of the file
+    system.
+
+    Examples of other places where XQuery could be used in
+    QtXmlPatterns to query non-XML data:
+
+    \list
+
+        \o The internal representation for word processor documents
+
+        \o The set of dependencies for a software build system
+
+        \o The hierarchy (or graph) that links a set of HTML documents
+        from a web crawler
+
+        \o The images and meta-data in an image collection
+
+        \o The set of D-Bus interfaces available in a system
+
+        \o A QObject hierarchy, as seen in the \l{QObject XML Model
+        Example} {QObject XML Model example}.
+
+    \endlist
+
+    See the QAbstractXmlNodeModel documentation for information about
+    how to implement custom XML node models.
+
+    \section1 More on using QtXmlPatterns with non-XML Data
+
+    Subclassing QAbstractXmlNodeModel to let the query engine access
+    non-XML data by the same API it uses for XML is the feature that
+    enables QtXmlPatterns to query non-XML data with XQuery. It allows
+    XQuery to be used as a mapping layer between different non-XML
+    node models or between a non-XML node model and the built-in XML
+    node model. Once the subclass(es) of QAbstractXmlNodeModel have
+    been written, XQuery can be used to select a set of elements from
+    one node model, transform the selected elements, and then write
+    them out, either as XML using QXmlQuery::evaluateTo() and QXmlSerializer,
+    or as some other format using a subclass of QAbstractXmlReceiver.
+
+    Consider a word processor application that must import and export
+    data in several different formats. Rather than writing a lot of
+    C++ code to convert each input format to an intermediate form, and
+    more C++ code to convert the intermediate form back to each
+    output format, one can implement a solution based on QtXmlPatterns
+    that uses simple XQueries to transform each XML or non-XML format
+    (e.g. MathFormula.xml below) to the intermediate form (e.g. the
+    DocumentRepresentation node model class below), and more simple
+    XQueries to transform the intermediate form back to each XML or
+    non-XML format.
+
+    \image patternist-wordProcessor.png
+
+    Because CSV files are not XML, a subclass of QAbstractXmlNodeModel
+    is used to present the CSV data to the XQuery engine as if it were
+    XML. What are not shown are the subclasses of QAbstractXmlReceiver
+    that would then send the selected elements into the
+    DocumentRepresentation node model, and the subclasses of
+    QAbstractXmlNodeModel that would ultimately write the output files
+    in each format.
+
+    \section1 Security Considerations
+
+    \section2 Code Injection
+
+    XQuery is vulnerable to
+    \l{http://en.wikipedia.org/wiki/Code_injection} {code injection
+    attacks} in the same way as the SQL language. If an XQuery is
+    constructed by concatenating strings, and the strings come from
+    user input, the constructed XQuery could be malevolent. The best
+    way to prevent code injection attacks is to not construct XQueries
+    from user-written strings, but only accept user data input using
+    QVariant and variable bindings. See QXmlQuery::bindVariable().
+
+    The articles
+    \l{http://www.ibm.com/developerworks/xml/library/x-xpathinjection.html}
+    {Avoid the dangers of XPath injection}, by Robi Sen and
+    \l{http://www.packetstormsecurity.org/papers/bypass/Blind_XPath_Injection_20040518.pdf}
+    {Blind XPath Injection}, by Amit Klein, discuss the XQuery code
+    injection problem in more detail.
+
+    \section2 Denial of Service Attacks
+
+    Applications using QtXmlPatterns are subject to the same
+    limitations of software as other systems. Generally, these can not
+    be checked. This means QtXmlPatterns does not prevent rogue
+    queries from consuming too many resources. For example, a query
+    could take too much time to execute or try to transfer too much
+    data. A query could also do too much recursion, which could crash
+    the system.  XQueries can do these things accidentally, but they
+    can also be done as deliberate denial of service attacks.
+
+    \section1 Features and Conformance
+
+    \section2 XQuery 1.0
+
+    QtXmlPatterns aims at being a
+    \l{http://www.w3.org/TR/xquery/#id-xquery-conformance} {conformant
+    XQuery processor}. It adheres to
+    \l{http://www.w3.org/TR/xquery/#id-minimal-conformance} {Minimal
+    Conformance} and supports the
+    \l{http://www.w3.org/TR/xquery/#id-serialization-feature}
+    {Serialization Feature} and the
+    \l{http://www.w3.org/TR/xquery/#id-full-axis-feature} {Full Axis
+    Feature}. QtXmlPatterns currently passes 97% of the tests in the
+    \l{http://www.w3.org/XML/Query/test-suite} {XML Query Test Suite}.
+    Areas where conformance may be questionable and where behavior may
+    be changed in future releases include:
+
+    \list
+
+    \o Some corner cases involving namespaces and element constructors
+       are incorrect.
+
+    \o XPath is a subset of XQuery and the implementation of
+       QtXmlPatterns uses XPath 2.0 with XQuery 1.0.
+
+    \endlist
+
+    The specifications discusses conformance further:
+    \l{http://www.w3.org/TR/xquery/}{XQuery 1.0: An XML Query
+    Language}.  W3C's XQuery testing effort can be of interest as
+    well, \l{http://www.w3.org/XML/Query/test-suite/}{XML Query Test
+    Suite}.
+
+    Currently \c fn:collection() does not access any data set, and
+    there is no API for providing data through the collection. As a
+    result, evaluating \c fn:collection() returns the empty
+    sequence. We intend to provide functionality for this in a future
+    release of Qt.
+
+    Only queries encoded in UTF-8 are supported.
+
+    \section2 XSLT 2.0
+
+    Partial support for XSLT was introduced in Qt 4.5. Future
+    releases of QtXmlPatterns will aim to support these XSLT
+    features:
+
+    \list
+        \o Basic XSLT 2.0 processor
+        \o Serialization feature
+        \o Backwards Compatibility feature
+    \endlist
+
+    For details, see \l{http://www.w3.org/TR/xslt20/#conformance}{XSL
+    Transformations (XSLT) Version 2.0, 21 Conformance}.
+
+    \note In this release, XSLT support is considered experimental.
+
+    Unsupported or partially supported XSLT features are documented
+    in the following table. The implementation of XSLT in Qt 4.5 can
+    be seen as XSLT 1.0 but with the data model of XPath 2.0 and
+    XSLT 2.0, and using the using the functionality of XPath 2.0 and
+    its accompanying function library. When QtXmlPatterns encounters
+    an unsupported or partially support feature, it will either report
+    a syntax error or silently continue, unless otherwise noted in the
+    table.
+
+    The implementation currently passes 42% of W3C's XSLT test suite,
+    which focus on features introduced in XSLT 2.0.
+
+    \table
+    \header
+        \o XSL Feature
+        \o Support Status
+    \row
+        \o \c xsl:key and \c fn:key()
+        \o not supported
+    \row
+        \o \c xsl:include
+        \o not supported
+    \row
+        \o \c xsl:import
+        \o not supported
+    \row
+        \o \c xsl:copy
+
+        \o The \c copy-namespaces and \c inherit-namespaces attributes
+           have no effect. For copied comments, attributes and
+           processing instructions, the copy has the same node
+           identity as the original.
+
+    \row
+        \o \c xsl:copy-of
+        \o The \c copy-namespaces attribute has no effect.
+    \row
+        \o \c fn:format-number()
+        \o not supported
+    \row
+        \o \c xsl:message
+        \o not supported
+    \row
+        \o \c xsl:use-when
+        \o not supported
+    \row
+        \o \c Tunnel Parameters
+        \o not supported
+    \row
+        \o \c xsl:attribute-set
+        \o not supported
+    \row
+        \o \c xsl:decimal-format
+        \o not supported
+    \row
+        \o \c xsl:fallback
+        \o not supported
+    \row
+        \o \c xsl:apply-imports
+        \o not supported
+    \row
+        \o \c xsl:character-map
+        \o not supported
+    \row
+        \o \c xsl:number
+        \o not supported
+    \row
+        \o \c xsl:namespace-alias
+        \o not supported
+    \row
+        \o \c xsl:output
+        \o not supported
+    \row
+        \o \c xsl:output-character
+        \o not supported
+    \row
+        \o \c xsl:preserve-space
+        \o not supported
+    \row
+        \o \c xsl:result-document
+        \o not supported
+    \row
+        \o Patterns
+        \o Complex patterns or patterns with predicates have issues.
+    \row
+        \o \c 2.0 Compatibility Mode
+
+        \o Stylesheets are interpreted as XSLT 2.0 stylesheets, even
+           if the \c version attribute is in the XSLT source is
+           1.0. In other words, the version attribute is ignored.
+
+    \row
+        \o Grouping
+
+        \o \c fn:current-group(), \c fn:grouping-key() and \c
+           xsl:for-each-group.
+
+    \row
+        \o Regexp elements
+        \o \c xsl:analyze-string, \c xsl:matching-substring,
+           \c xsl:non-matching-substring, and \c fn:regex-group()
+    \row
+        \o Date & Time formatting
+        \o \c fn:format-dateTime(), \c fn:format-date() and fn:format-time().
+
+    \row
+        \o XPath Conformance
+        \o Since XPath is a subset of XSLT, its issues are in affect too.
+    \endtable
+
+    The QtXmlPatterns implementation of the XPath Data Model does not
+    include entities (due to QXmlStreamReader not reporting them).
+    This means that functions \c unparsed-entity-uri() and \c
+    unparsed-entity-public-id() always return negatively.
+
+    \section2 XPath 2.0
+
+    Since XPath 2.0 is a subset of XQuery 1.0, XPath 2.0 is
+    supported. Areas where conformance may be questionable and,
+    consequently, where behavior may be changed in future releases
+    include:
+
+    \list
+    \o Regular expression support is currently not conformant
+       but follows Qt's QRegExp standard syntax.
+
+    \o Operators for \c xs:time, \c xs:date, and \c xs:dateTime
+       are incomplete.
+
+    \o Formatting of very large or very small \c xs:double, \c
+       xs:float, and \c xs:decimal values may be incorrect.
+    \endlist
+
+    \section2 xml:id
+
+    Processing of XML files supports \c xml:id. This allows elements
+    that have an attribute named \c xml:id to be looked up efficiently
+    with the \c fn:id() function. See
+    \l{http://www.w3.org/TR/xml-id/}{xml:id Version 1.0} for details.
+
+    \section2 Resource Loading
+
+    When QtXmlPatterns loads an XML resource, e.g., using the
+    \c fn:doc() function, the following schemes are supported:
+
+    \table
+    \header
+        \o Scheme Name
+        \o Description
+    \row
+        \o \c file
+        \o Local files.
+    \row
+        \o \c data
+
+        \o The bytes are encoded in the URI itself. e.g., \c
+           data:application/xml,%3Ce%2F%3E is \c <e/>.
+
+    \row
+        \o \c ftp
+        \o Resources retrieved via FTP.
+    \row
+        \o \c http
+        \o Resources retrieved via HTTP.
+    \row
+        \o \c https
+        \o Resources retrieved via HTTPS. This will succeed if no SSL
+           errors are encountered.
+    \row
+        \o \c qrc
+        \o Qt Resource files. Expressing it as an empty scheme, :/...,
+           is not supported.
+
+    \endtable
+
+    \section2 XML
+
+    XML 1.0 and XML Namespaces 1.0 are supported, as opposed to the
+    1.1 versions. When a strings is passed to a query as a QString,
+    the characters must be XML 1.0 characters. Otherwise, the behavior
+    is undefined. This is not checked.
+
+    URIs are first passed to QAbstractUriResolver. Check
+    QXmlQuery::setUriResolver() for possible rewrites.
+
+*/
+
+/*!
+    \namespace QPatternist
+    \brief The QPatternist namespace contains classes and functions required by the QtXmlPatterns module.
+    \internal
+*/