diff options
author | Arnab Datta <arnab.datta@nokia.com> | 2012-03-30 16:33:48 +0200 |
---|---|---|
committer | Qt by Nokia <qt-info@nokia.com> | 2012-04-13 13:08:08 +0200 |
commit | 08a3b2ea08480ef2f5b4ebc9d9a1442d45e1fa4c (patch) | |
tree | d6590c2e805d5d2600059ec3c8136b06e0f14880 /doc | |
parent | 0d6c28c5eb7046bbc011b060fdcab1f622ed9f9a (diff) | |
download | qtxmlpatterns-08a3b2ea08480ef2f5b4ebc9d9a1442d45e1fa4c.tar.gz |
Fixed all qdoc errors for this module (except those related to linking)
Change-Id: I36d07a02ec8dea6bc2d538f32b28b987635c32c1
Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/qt5.qdocconf | 6 | ||||
-rw-r--r-- | doc/src/examples/filetree.qdoc | 38 | ||||
-rw-r--r-- | doc/src/examples/globalVariables.qdoc | 20 | ||||
-rw-r--r-- | doc/src/examples/recipes.qdoc | 12 | ||||
-rw-r--r-- | doc/src/examples/schema.qdoc | 14 | ||||
-rw-r--r-- | doc/src/examples/trafficinfo.qdoc | 8 | ||||
-rw-r--r-- | doc/src/xml-processing/xml-patterns.qdoc | 20 | ||||
-rw-r--r-- | doc/src/xml-processing/xml-processing.qdoc | 16 | ||||
-rw-r--r-- | doc/src/xml-processing/xquery-introduction.qdoc | 126 |
9 files changed, 132 insertions, 128 deletions
diff --git a/doc/qt5.qdocconf b/doc/qt5.qdocconf index bd0fd67..e99c7c0 100644 --- a/doc/qt5.qdocconf +++ b/doc/qt5.qdocconf @@ -7,10 +7,14 @@ project = Qt Xml Patterns # Images should be placed in <rootdir>/dic/images and examples in # <rootdir>/examples. # Paths are relative to the location of this file. -exampledirs += ../doc/src +exampledirs += src \ + ../examples\ + src/snippets headerdirs += .. imagedirs += images sourcedirs += .. +excludedirs += ../tests/auto \ + ../tools # The following parameters are for creating a qhp file, the qhelpgenerator # program can convert the qhp file into a qch file which can be opened in diff --git a/doc/src/examples/filetree.qdoc b/doc/src/examples/filetree.qdoc index 82fdeaf..6a79e33 100644 --- a/doc/src/examples/filetree.qdoc +++ b/doc/src/examples/filetree.qdoc @@ -68,7 +68,7 @@ \c{main.cpp} (\c{Q_INIT_RESOURCE(queries);}). It lists the XQuery files (\c{.xq}) that can be selected in the combobox. - \quotefromfile examples/xmlpatterns/filetree/queries.qrc + \quotefromfile xmlpatterns/filetree/queries.qrc \printuntil To add your own queries to the example's combobox, store your @@ -103,12 +103,12 @@ QSimpleXmlNodeModel. When you implement your own custom node model, you must provide implementations for these callback functions: - \snippet examples/xmlpatterns/filetree/filetree.h 0 - \snippet examples/xmlpatterns/filetree/filetree.h 1 + \snippet xmlpatterns/filetree/filetree.h 0 + \snippet xmlpatterns/filetree/filetree.h 1 The \c{FileTree} class declares four data members: - \snippet examples/xmlpatterns/filetree/filetree.h 2 + \snippet xmlpatterns/filetree/filetree.h 2 The QVector \c{m_fileInfos} will contain the node model. Each QFileInfo in the vector will represent a file or a directory in the @@ -140,7 +140,7 @@ types: \target Node_Type - \snippet examples/xmlpatterns/filetree/filetree.h 4 + \snippet xmlpatterns/filetree/filetree.h 4 \c{Directory} and \c{File} will represent the XML element nodes for directories and files respectively, and the other enum values will @@ -149,7 +149,7 @@ initializes \c{m_names} with an appropriate QXmlName for each element and attribute type: - \snippet examples/xmlpatterns/filetree/filetree.cpp 2 + \snippet xmlpatterns/filetree/filetree.cpp 2 Note that the constructor does \e{not} pre-build the entire node model. Instead, the node model is built \e{incrementally} as the @@ -175,7 +175,7 @@ a QFileInfo, the class uses the private function \c{toNodeIndex()}: \target main toNodeIndex - \snippet examples/xmlpatterns/filetree/filetree.cpp 1 + \snippet xmlpatterns/filetree/filetree.cpp 1 It searches the \c{m_fileInfos} vector for a QFileInfo that matches \c{fileInfo}. If a match is found, its array index is passed to @@ -210,12 +210,12 @@ type directly from the QFileInfo: \target toNodeIndex of convenience - \snippet examples/xmlpatterns/filetree/filetree.cpp 0 + \snippet xmlpatterns/filetree/filetree.cpp 0 Note that the auxiliary vector \c{m_names} is accessed using the \l{Node_Type} {node type}, for example: - \snippet examples/xmlpatterns/filetree/filetree.cpp 3 + \snippet xmlpatterns/filetree/filetree.cpp 3 Most of the virtual functions in the callback interface are as simple as the ones described so far, but the callback function used @@ -252,7 +252,7 @@ each \l{QAbstractXmlNodeModel::SimpleAxis} {axis}. \target next node on axis - \snippet examples/xmlpatterns/filetree/filetree.cpp 4 + \snippet xmlpatterns/filetree/filetree.cpp 4 The first thing this function does is call \l{to file info} {toFileInfo()} to get the QFileInfo of the context node. The use of @@ -261,7 +261,7 @@ in \c{m_fileInfos}. \target to file info - \snippet examples/xmlpatterns/filetree/filetree.cpp 6 + \snippet xmlpatterns/filetree/filetree.cpp 6 The \l{QAbstractXmlNodeModel::Parent} {Parent} case looks up the context node's parent by constructing a QFileInfo from the context @@ -293,7 +293,7 @@ sibling to the node model, if it isn't in the model yet. \target nextSibling helper - \snippet examples/xmlpatterns/filetree/filetree.cpp 5 + \snippet xmlpatterns/filetree/filetree.cpp 5 \section2 The UI Class: MainWindow @@ -301,7 +301,7 @@ QMainWindow and the Ui_MainWindow base class generated by \l{Qt Designer Manual} {Qt Designer}. - \snippet examples/xmlpatterns/filetree/mainwindow.h 0 + \snippet xmlpatterns/filetree/mainwindow.h 0 It contains the custom node model (\c{m_fileTree}) and an instance of QXmlNodeModelIndex (\c{m_fileNode}) used for holding the node @@ -317,13 +317,13 @@ be loaded into the custom node model. Choosing a directory signals the \c{on_actionOpenDirectory_triggered()} slot: - \snippet examples/xmlpatterns/filetree/mainwindow.cpp 1 + \snippet xmlpatterns/filetree/mainwindow.cpp 1 The slot function simply calls the private function \c{loadDirectory()} with the path of the chosen directory: \target the standard code pattern - \snippet examples/xmlpatterns/filetree/mainwindow.cpp 4 + \snippet xmlpatterns/filetree/mainwindow.cpp 4 \c{loadDirectory()} demonstrates a standard code pattern for using Qt XML Patterns programatically. First it gets the node model index @@ -360,12 +360,12 @@ right. Choosing an XQuery signals the \c{on_queryBox_currentIndexChanged()} slot: - \snippet examples/xmlpatterns/filetree/mainwindow.cpp 2 + \snippet xmlpatterns/filetree/mainwindow.cpp 2 The slot function opens and loads the query file and then calls the private function \c{evaluateResult()} to run the query: - \snippet examples/xmlpatterns/filetree/mainwindow.cpp 3 + \snippet xmlpatterns/filetree/mainwindow.cpp 3 \c{evaluateResult()} is a second example of the same code pattern shown in \l{the standard code pattern} {loadDirectory()}. In this @@ -387,8 +387,8 @@ \c{FileTree} class, we can strip the running of \c{wholeTree.xq} out of \l{the standard code pattern} {MainWindow::loadDirectory()}: - \snippet examples/xmlpatterns/filetree/mainwindow.cpp 5 - \snippet examples/xmlpatterns/filetree/mainwindow.cpp 6 + \snippet xmlpatterns/filetree/mainwindow.cpp 5 + \snippet xmlpatterns/filetree/mainwindow.cpp 6 Note, however, that \c{FileTree} doesn't have the capability of deleting all or part of the node model. The node model, once built, diff --git a/doc/src/examples/globalVariables.qdoc b/doc/src/examples/globalVariables.qdoc index 3288128..b5ec61d 100644 --- a/doc/src/examples/globalVariables.qdoc +++ b/doc/src/examples/globalVariables.qdoc @@ -67,7 +67,7 @@ Consider the declarations in this hypothetical C++ application: - \snippet examples/xmlpatterns/xquery/globalVariables/globals.cpp 0 + \snippet xmlpatterns/xquery/globalVariables/globals.cpp 0 \section3 The XML description of the C++ application @@ -75,7 +75,7 @@ \l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML} produces this XML description: - \quotefromfile examples/xmlpatterns/xquery/globalVariables/globals.gccxml + \quotefromfile xmlpatterns/xquery/globalVariables/globals.gccxml \printuntil \section3 The XQuery for finding global variables @@ -84,7 +84,7 @@ description. Here is our XQuery source. We walk through it in \l{XQuery Code Walk-Through}. - \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq + \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq \printuntil \section3 Running the XQuery @@ -127,7 +127,7 @@ \c{examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq} It begins with two variable declarations that begin the XQuery: - \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq + \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq \skipto declare variable \printto (: @@ -148,7 +148,7 @@ instructions for displaying the text, and then the \c{<body>} element. - \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq + \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq \skipto <html xmlns \printuntil @@ -157,7 +157,7 @@ the two \c{return} clauses separated by the \e {comma operator} about halfway down: - \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq + \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq \skipto declare function local:report() \printuntil }; @@ -171,7 +171,7 @@ Here is the html generated for the \c{<body>} element. Compare it with the XQuery code above: - \quotefromfile examples/xmlpatterns/xquery/globalVariables/globals.html + \quotefromfile xmlpatterns/xquery/globalVariables/globals.html \skipto <body> \printuntil </body> @@ -180,21 +180,21 @@ returns true if the variable has a complex type. The variable can be mutable or const. - \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq + \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq \skipto declare function local:isComplexType \printuntil }; \c{isPrimitive()} returns true if the variable has a primitive type. The variable must be mutable. - \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq + \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq \skipto declare function local:isPrimitive \printuntil }; \c{location()} returns a text constructed from the variable's file and line number attributes. - \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq + \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq \skipto declare function local:location \printuntil }; diff --git a/doc/src/examples/recipes.qdoc b/doc/src/examples/recipes.qdoc index 745b747..c9c0e06 100644 --- a/doc/src/examples/recipes.qdoc +++ b/doc/src/examples/recipes.qdoc @@ -66,7 +66,7 @@ \c{main.cpp} (\c{Q_INIT_RESOURCE(recipes);}). It lists the XQuery files (\c{.xq}) that can be selected in the combobox. - \quotefromfile examples/xmlpatterns/recipes/recipes.qrc + \quotefromfile xmlpatterns/recipes/recipes.qrc \printuntil To add your own queries to the example's combobox, store your @@ -79,7 +79,7 @@ QApplication. Then it creates an instance of the UI class, shows it, and starts the Qt event loop: - \snippet examples/xmlpatterns/recipes/main.cpp 0 + \snippet xmlpatterns/recipes/main.cpp 0 \section2 The UI Class: QueryMainWindow @@ -87,7 +87,7 @@ QMainWindow and the class generated by \l{Qt Designer Manual} {Qt Designer}: - \snippet examples/xmlpatterns/recipes/querymainwindow.h 0 + \snippet xmlpatterns/recipes/querymainwindow.h 0 The constructor finds the window's \l{QComboBox} {combo box} child widget and connects its \l{QComboBox::currentIndexChanged()} @@ -97,7 +97,7 @@ viewer} . Finally, it finds the XQuery files (\c{.xq}) and adds each one to the \l{QComboBox} {combo box} menu. - \snippet examples/xmlpatterns/recipes/querymainwindow.cpp 0 + \snippet xmlpatterns/recipes/querymainwindow.cpp 0 The work is done in the \l{displayQuery() slot} {displayQuery()} slot and the \l{evaluate() function} {evaluate()} function it @@ -106,7 +106,7 @@ function} {evaluate()}. \target displayQuery() slot - \snippet examples/xmlpatterns/recipes/querymainwindow.cpp 1 + \snippet xmlpatterns/recipes/querymainwindow.cpp 1 \l{evaluate() function} {evaluate()} demonstrates the standard Qt XML Patterns usage pattern. First, an instance of QXmlQuery is @@ -124,7 +124,7 @@ called to ensure that the XQuery was correctly parsed. \target evaluate() function - \snippet examples/xmlpatterns/recipes/querymainwindow.cpp 2 + \snippet xmlpatterns/recipes/querymainwindow.cpp 2 If the XQuery is valid, an instance of QXmlFormatter is created to format the query result as XML into a QBuffer. To evaluate the diff --git a/doc/src/examples/schema.qdoc b/doc/src/examples/schema.qdoc index 9d56d6b..4086dd5 100644 --- a/doc/src/examples/schema.qdoc +++ b/doc/src/examples/schema.qdoc @@ -68,7 +68,7 @@ QApplication. Then it creates an instance of the mainwindow class, shows it, and starts the Qt event loop: - \snippet examples/xmlpatterns/schema/main.cpp 0 + \snippet xmlpatterns/schema/main.cpp 0 \section2 The UI Class: MainWindow @@ -76,7 +76,7 @@ QMainWindow and the class generated by \l{Qt Designer Manual} {Qt Designer}: - \snippet examples/xmlpatterns/schema/mainwindow.h 0 + \snippet xmlpatterns/schema/mainwindow.h 0 The constructor fills the schema and instance \l{QComboBox} selections with the predefined schemas and instances and connects their \l{QComboBox::currentIndexChanged()} {currentIndexChanged()} @@ -87,20 +87,20 @@ The call to \c{schemaSelected(0)} and \c{instanceSelected(0)} will trigger the validation of the initial Contact Schema example. - \snippet examples/xmlpatterns/schema/mainwindow.cpp 0 + \snippet xmlpatterns/schema/mainwindow.cpp 0 In the \c{schemaSelected()} slot the content of the instance \l{QComboBox} {selection} is adapted to the selected schema and the corresponding schema is loaded from the \l{The Qt Resource System} {resource file} and displayed in the schema \l{QTextBrowser} {viewer}. At the end of the method a revalidation is triggered. - \snippet examples/xmlpatterns/schema/mainwindow.cpp 1 + \snippet xmlpatterns/schema/mainwindow.cpp 1 In the \c{instanceSelected()} slot the selected instance is loaded from the \l{The Qt Resource System} {resource file} and loaded into the instance \l{QTextEdit} {editor} an the revalidation is triggered again. - \snippet examples/xmlpatterns/schema/mainwindow.cpp 2 + \snippet xmlpatterns/schema/mainwindow.cpp 2 The \c{validate()} slot does the actual work in this example. At first it stores the content of the schema \l{QTextBrowser} {viewer} and the @@ -109,7 +109,7 @@ \l{QAbstractMessageHandler} {QAbstractMessageHandler} and is a convenience class to store error messages from the XmlPatterns system. - \snippet examples/xmlpatterns/schema/mainwindow.cpp 4 + \snippet xmlpatterns/schema/mainwindow.cpp 4 After the \l{QXmlSchema} {QXmlSchema} is instanciated and the message handler set on it, the \l{QXmlSchema::load()} {load()} method is called with the schema data as argument. @@ -125,5 +125,5 @@ The rest of the code does only some fancy coloring and eyecandy. - \snippet examples/xmlpatterns/schema/mainwindow.cpp 3 + \snippet xmlpatterns/schema/mainwindow.cpp 3 */ diff --git a/doc/src/examples/trafficinfo.qdoc b/doc/src/examples/trafficinfo.qdoc index 6381a7e..59413fc 100644 --- a/doc/src/examples/trafficinfo.qdoc +++ b/doc/src/examples/trafficinfo.qdoc @@ -71,7 +71,7 @@ As a result we get the following document: - \quotefile examples/xmlpatterns/trafficinfo/time_example.wml + \quotefile xmlpatterns/trafficinfo/time_example.wml So for every departure we have a \c <a> tag that contains the time as a text element, and the following text element contains the line number @@ -82,7 +82,7 @@ that takes a station ID and date/time as input and returns the list of times and directions: - \snippet examples/xmlpatterns/trafficinfo/timequery.cpp 1 + \snippet xmlpatterns/trafficinfo/timequery.cpp 1 The first lines of this function synthesize the XQuery strings that fetch the document and extract the data. @@ -113,7 +113,7 @@ will return the following document: - \snippet examples/xmlpatterns/trafficinfo/station_example.wml 0 + \snippet xmlpatterns/trafficinfo/station_example.wml 0 The names of the available stations are listed as separate text elements and the station ID is part of the \c href attribute of the parent \c a @@ -121,7 +121,7 @@ the action of querying the stations that match the given name pattern with the following code: - \snippet examples/xmlpatterns/trafficinfo/stationquery.cpp 0 + \snippet xmlpatterns/trafficinfo/stationquery.cpp 0 Just as in the \c TimeQuery implementation, the first step is to synthesize the XQuery strings for selecting the station names and the diff --git a/doc/src/xml-processing/xml-patterns.qdoc b/doc/src/xml-processing/xml-patterns.qdoc index c608df0..b3817d3 100644 --- a/doc/src/xml-processing/xml-patterns.qdoc +++ b/doc/src/xml-processing/xml-patterns.qdoc @@ -64,7 +64,7 @@ library: \target qtxmlpatterns_example_query - \quotefile snippets/patternist/introductionExample.xq + \quotefile patternist/introductionExample.xq First, the query opens a \c{<bibliography>} element in the output. The @@ -120,7 +120,7 @@ \c{myquery.xq}), we can run it from a Qt application using a standard Qt XML Patterns code sequence: - \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 3 + \snippet 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 @@ -143,7 +143,7 @@ \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 + \snippet 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 @@ -182,13 +182,13 @@ (\c{$publisher}), and the year of publication (\c{$year}): \target qtxmlpatterns_example_query2 - \quotefile snippets/patternist/introExample2.xq + \quotefile patternist/introExample2.xq Modify the Qt XML Patterns 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 + \snippet code/src_xmlpatterns_api_qxmlquery.cpp 4 Each program variable is passed to Qt XML Patterns as a QVariant of the type of the C++ variable or constant from which it is @@ -302,7 +302,7 @@ populates a sequence of \l {QXmlResultItems} {result items} with the XQuery results: - \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 5 + \snippet 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 @@ -417,7 +417,7 @@ friend of QMetaType (qMetaTypeId<T>()) and a friend of QVariant (qvariant_cast<T>()): - \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 6 + \snippet 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 @@ -452,7 +452,7 @@ to find all the skin care product orders and output them ordered by shipping date. - \quotefile snippets/patternist/introAcneRemover.xq + \quotefile patternist/introAcneRemover.xq Qt XML Patterns can be used out of the box to perform this query, provided \e myOrders.xml actually contains well-formed XML. It @@ -464,7 +464,7 @@ description of it. Such an XML file, if it existed, might look something like this: - \quotefile snippets/patternist/introFileHierarchy.xml + \quotefile patternist/introFileHierarchy.xml The \l{File System Example}{File System Example} does exactly this. @@ -483,7 +483,7 @@ 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 + \quotefromfile patternist/introNavigateFS.xq \skipto <html> \printuntil diff --git a/doc/src/xml-processing/xml-processing.qdoc b/doc/src/xml-processing/xml-processing.qdoc index 2a8ec0b..89104d6 100644 --- a/doc/src/xml-processing/xml-processing.qdoc +++ b/doc/src/xml-processing/xml-processing.qdoc @@ -91,7 +91,7 @@ Consider the following example: - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 6 + \snippet code/doc_src_qtxml.qdoc 6 Here we find three different uses of the name \e title. If you wish to process this document you will encounter problems because each of the @@ -102,7 +102,7 @@ occurrence of \e title as the title of a book, i.e. to use the \e title element of a book namespace to distinguish it from, for example, the chapter title, e.g.: - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 7 + \snippet code/doc_src_qtxml.qdoc 7 \e book in this case is a \e prefix denoting the namespace. @@ -118,12 +118,12 @@ http://www.example.com/fnord/ the document's default XML namespace \e xmlns we write - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 8 + \snippet code/doc_src_qtxml.qdoc 8 To distinguish the \e http://www.example.com/fnord/book/ namespace from the default, we must supply it with a prefix: - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 9 + \snippet code/doc_src_qtxml.qdoc 9 A namespace that is declared like this can be applied to element and attribute names by prepending the appropriate prefix and a ":" @@ -144,7 +144,7 @@ within a \e chapter. Let's clarify this with an example: - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 10 + \snippet code/doc_src_qtxml.qdoc 10 Within the \e document element we have two namespaces declared. The default namespace \e http://www.example.com/fnord/ applies to the \e @@ -315,7 +315,7 @@ or an end tag, etc. To make it less abstract consider the following example: - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 3 + \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: @@ -400,7 +400,7 @@ and switched on or off using QXmlReader::setFeature(). Consider the example - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 4 + \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 @@ -445,7 +445,7 @@ \endlist Consider the following element: - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 5 + \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 diff --git a/doc/src/xml-processing/xquery-introduction.qdoc b/doc/src/xml-processing/xquery-introduction.qdoc index 524b46c..560100e 100644 --- a/doc/src/xml-processing/xquery-introduction.qdoc +++ b/doc/src/xml-processing/xquery-introduction.qdoc @@ -44,7 +44,7 @@ Where Java and C++ are \e{statement-based} languages, the XQuery language is \e{expression-based}. The simplest XQuery expression is an XML element constructor: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 20 +\snippet code/doc_src_qtxmlpatterns.qdoc 20 This \c{<recipe/>} element is an XQuery expression that forms a complete XQuery. In fact, this XQuery doesn't actually query @@ -56,7 +56,7 @@ An XQuery expression can also be enclosed in curly braces and embedded in another XQuery expression. This XQuery has a document expression embedded in a node expression: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 21 +\snippet code/doc_src_qtxmlpatterns.qdoc 21 It creates a new \c{<html>} element in the output and sets its \c{id} attribute to be the \c{id} attribute from an \c{<html>} element in the @@ -104,7 +104,7 @@ initial focus set. The document node will have one child node, and that child node will represent the document element. Consider the following XQuery: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 18 +\snippet code/doc_src_qtxmlpatterns.qdoc 18 The \c{doc()} function loads the \c{cookbook.xml} file and returns the document node. The document node then becomes the focus for the next @@ -119,7 +119,7 @@ Conceptually, evaluation of the steps of a path expression is similar to iterating through the same number of nested \e{for} loops. Consider the following XQuery, which builds on the previous one: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 19 +\snippet code/doc_src_qtxmlpatterns.qdoc 19 This XQuery is a single path expression composed of three steps. The first step creates the initial focus by calling the \c{doc()} @@ -159,7 +159,7 @@ implied. XQueries are normally written in this shorthand form, but they can also be written in the longhand form. If we rewrite the XQuery in the longhand form, it looks like this: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 22 +\snippet code/doc_src_qtxmlpatterns.qdoc 22 The two axis steps have been expanded. The first step (\c{//recipe}) has been rewritten as \c{/descendant-or-self::element(recipe)}, where @@ -343,7 +343,7 @@ The name tests are the \l{Node Tests} that have the \c{name} parameter. A name test must match the node \e name in addition to the node \e kind. We have already seen name tests used: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 19 +\snippet code/doc_src_qtxmlpatterns.qdoc 19 In this path expression, both \c{recipe} and \c{title} are name tests written in the shorthand form. XQuery resolves these names @@ -363,11 +363,11 @@ namespace(s) in an XQuery is a common cause of XQuery failures. Let's add a \e{default} namespace to \c{cookbook.xml} now. Change the \e{document element} in \c{cookbook.xml} from: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 23 +\snippet code/doc_src_qtxmlpatterns.qdoc 23 to... -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 24 +\snippet code/doc_src_qtxmlpatterns.qdoc 24 This is called a \e{default namespace} declaration because it doesn't include a namespace prefix. By including this default namespace @@ -390,17 +390,17 @@ can declare the namespace in the XQuery. We can give it a \e{namespace prefix} (e.g. \c{c} for cookbook) and prefix each name test with the namespace prefix: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 3 +\snippet code/doc_src_qtxmlpatterns.qdoc 3 Or we can declare the namespace to be the \e{default element namespace}, and then we can still run the original XQuery: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 4 +\snippet code/doc_src_qtxmlpatterns.qdoc 4 Both methods will work and produce the same output, all the \c{<title>} elements: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 5 +\snippet code/doc_src_qtxmlpatterns.qdoc 5 But note how the output is slightly different from the output we saw before we added the default namespace declaration to the cookbook file. @@ -423,7 +423,7 @@ attributes in the cookbook but select only the ones in the \c{xml} namespace, use the \c{xml:} namespace prefix but replace the \e{local name} (the attribute name) with the wildcard: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 7 +\snippet code/doc_src_qtxmlpatterns.qdoc 7 Oops! If you save this XQuery in \c{file.xq} and run it through \c{xmlpatterns}, it doesn't work. You get an error message instead, @@ -451,12 +451,12 @@ all regardless of their namespace, replace the namespace prefix with the wildcard and write \c{name} (the attribute name) as the local name: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 8 +\snippet code/doc_src_qtxmlpatterns.qdoc 8 To find and select all the attributes of the \e{document element} in the cookbook, replace the entire name test with the wildcard: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 9 +\snippet code/doc_src_qtxmlpatterns.qdoc 9 \section1 Using Predicates In Path Expressions @@ -469,14 +469,14 @@ filter, the node is included in the result set. The query below selects the recipe element that has the \c{<title>} element \c{"Hard-Boiled Eggs"}. -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 10 +\snippet code/doc_src_qtxmlpatterns.qdoc 10 The dot expression ('.') can be used in predicates and path expressions to refer to the current context node. The following query uses the dot expression to refer to the current \c{<method>} element. The query selects the empty \c{<method>} elements from the cookbook. -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 11 +\snippet code/doc_src_qtxmlpatterns.qdoc 11 Note that passing the dot expression to the \l{http://www.w3.org/TR/xpath-functions/#func-string-length} @@ -485,19 +485,19 @@ Note that passing the dot expression to the {string-length()} is called with no parameter, the context node is assumed: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 12 +\snippet code/doc_src_qtxmlpatterns.qdoc 12 Actually, selecting an empty \c{<method>} element might not be very useful by itself. It doesn't tell you which recipe has the empty method: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 31 +\snippet code/doc_src_qtxmlpatterns.qdoc 31 \target Empty Method Not Robust What you probably want to see instead are the \c{<recipe>} elements that have empty \c{<method>} elements: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 32 +\snippet code/doc_src_qtxmlpatterns.qdoc 32 The predicate uses the \l{http://www.w3.org/TR/xpath-functions/#func-string-length} @@ -509,7 +509,7 @@ text, the predicate evaluates to \c{false}, and the \c{<recipe>} element is discarded. The output is the entire recipe that has no instructions for preparation: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 33 +\snippet code/doc_src_qtxmlpatterns.qdoc 33 The astute reader will have noticed that this use of \c{string-length()} to find an empty element is unreliable. It works @@ -533,7 +533,7 @@ documents, the normal sequence is This query returns the second \c{<recipe>} element in the \c{cookbook.xml} file: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 13 +\snippet code/doc_src_qtxmlpatterns.qdoc 13 The other frequently used positional function is \l{http://www.w3.org/TR/xpath-functions/#func-last} {last()}, which @@ -542,11 +542,11 @@ another way, \l{http://www.w3.org/TR/xpath-functions/#func-last} {last()} returns the size of the focus set. This query returns the last recipe in the cookbook: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 16 +\snippet code/doc_src_qtxmlpatterns.qdoc 16 And this query returns the next to last \c{<recipe>}: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 17 +\snippet code/doc_src_qtxmlpatterns.qdoc 17 \section2 Boolean Predicates @@ -576,7 +576,7 @@ method element was written with both opening and closing tags and there was whitespace between the tags. Here is a more robust way that uses a different boolean predicate. -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 34 +\snippet code/doc_src_qtxmlpatterns.qdoc 34 This one uses the \l{http://www.w3.org/TR/xpath-functions/#func-empty} {empty()} and @@ -589,7 +589,7 @@ steps, but all the steps themselves are empty. That's still a case of a recipe with no instructions that won't be detected. There is a better way: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 35 +\snippet code/doc_src_qtxmlpatterns.qdoc 35 This version uses the \l{http://www.w3.org/TR/xpath-functions/#func-not} {not} and @@ -608,12 +608,12 @@ function in a comparison to inspect positions with conditional logic. The function returns the position index of the current context item in the sequence of items: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 14 +\snippet code/doc_src_qtxmlpatterns.qdoc 14 Note that the first position in the sequence is position 1, not 0. We can also select \e{all} the recipes after the first one: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 15 +\snippet code/doc_src_qtxmlpatterns.qdoc 15 \target Constructing Elements \section1 Constructing Elements @@ -634,14 +634,14 @@ the result set, we must create an XML element. We can do that using a \l{http://www.w3.org/TR/xquery/#id-orderby-return} {\e{return} clause} with an element constructor: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 25 +\snippet code/doc_src_qtxmlpatterns.qdoc 25 The \e{for} clause produces a sequence of attribute nodes from the result of the path expression. Each attribute node in the sequence is bound to the variable \c{$i}. The \e{return} clause then constructs a \c{<p>} element around the attribute node. Here is the output: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 28 +\snippet code/doc_src_qtxmlpatterns.qdoc 28 The output contains one \c{<p>} element for each \c{xml:id} attribute in the cookbook. Note that XQuery puts each attribute in the right @@ -653,27 +653,27 @@ The other two examples from the \l{Wildcards in Name Tests} {wildcard} section can be rewritten the same way. Here is the XQuery that selects all the \c{name} attributes, regardless of namespace: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 26 +\snippet code/doc_src_qtxmlpatterns.qdoc 26 And here is its output: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 29 +\snippet code/doc_src_qtxmlpatterns.qdoc 29 And here is the XQuery that selects all the attributes from the \e{document element}: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 27 +\snippet code/doc_src_qtxmlpatterns.qdoc 27 And here is its output: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 30 +\snippet code/doc_src_qtxmlpatterns.qdoc 30 \section2 Element Constructors are Expressions Because node constructors are expressions, they can be used in XQueries wherever expressions are allowed. -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 40 +\snippet code/doc_src_qtxmlpatterns.qdoc 40 If \c{cookbook.xml} is loaded without error, a \c{<oppskrift>} element (Norwegian word for recipe) is constructed for each \c{<recipe>} @@ -697,22 +697,22 @@ detailed specification. To construct an atomic value as element content, enclose an expression in curly braces and embed it in the element constructor: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 36 +\snippet code/doc_src_qtxmlpatterns.qdoc 36 Sending this XQuery through xmlpatterns produces: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 37 +\snippet code/doc_src_qtxmlpatterns.qdoc 37 To compute the value of an attribute, enclose the expression in curly braces and embed it in the attribute value: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 38 +\snippet code/doc_src_qtxmlpatterns.qdoc 38 Sending this XQuery through xmlpatterns produces: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 39 +\snippet code/doc_src_qtxmlpatterns.qdoc 39 -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 40 +\snippet code/doc_src_qtxmlpatterns.qdoc 40 If \c{cookbook.xml} is loaded without error, a \c{<oppskrift>} element (Norweigian word for recipe) is constructed for each \c{<recipe>} @@ -729,7 +729,7 @@ Copy the \c{cookbook.xml} to your current directory, save one of the cookbook XQuery examples in a \c{.xq} file (e.g., \c{file.xq}), and run the XQuery using Qt's command line utility: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 6 +\snippet code/doc_src_qtxmlpatterns.qdoc 6 \section1 Further Reading @@ -777,7 +777,7 @@ The most common cause of this bug is failure to declare one or more namespaces in your XQuery. Consider the following query for selecting all the examples in an XHTML document: -\quotefile snippets/patternist/simpleHTML.xq +\quotefile patternist/simpleHTML.xq It won't match anything because \c{index.html} is an XHTML file, and all XHTML files declare the default namespace @@ -788,19 +788,19 @@ But the actual expanded name is \c{{http://www.w3.org/1999/xhtml}html}. One possible fix is to declare the correct default namespace in the XQuery: -\quotefile snippets/patternist/simpleXHTML.xq +\quotefile patternist/simpleXHTML.xq Another common cause of this bug is to confuse the \e{document node} with the top element node. They are different. This query won't match anything: -\quotefile snippets/patternist/docPlainHTML.xq +\quotefile patternist/docPlainHTML.xq The \c{doc()} function returns the \e{document node}, not the top element node (\c{<html>}). Don't forget to match the top element node in the path expression: -\quotefile snippets/patternist/docPlainHTML2.xq +\quotefile patternist/docPlainHTML2.xq \section2 What if my input namespace is different from my output namespace? @@ -808,7 +808,7 @@ Just remember to declare both namespaces in your XQuery and use them properly. Consider the following query, which is meant to generate XHTML output from XML input: -\quotefile snippets/patternist/embedDataInXHTML.xq +\quotefile patternist/embedDataInXHTML.xq We want the \c{<html>}, \c{<body>}, and \c{<p>} nodes we create in the output to be in the standard XHTML namespace, so we declare the @@ -821,7 +821,7 @@ empty namespace. So we must declare that namespace too, with a namespace prefix, and then use the prefix with the node names in the path expression. This one will probably work better: -\quotefile snippets/patternist/embedDataInXHTML2.xq +\quotefile patternist/embedDataInXHTML2.xq \section2 Why doesn't my return clause work? @@ -830,7 +830,7 @@ Recall that XQuery is an \e{expression-based} language, not understanding XQuery expression precedence is very important. Consider the following query: -\quotefile snippets/patternist/forClause2.xq +\quotefile patternist/forClause2.xq It looks ok, but it isn't. It is supposed to be a FLWOR expression comprising a \e{for} clause and a \e{return} clause, but it isn't just @@ -848,7 +848,7 @@ FLWOR expression as its left operand. And, since the scope of variable scope error will be reported. Correct these problems by using parentheses. -\quotefile snippets/patternist/forClause.xq +\quotefile patternist/forClause.xq \section2 Why didn't my expression get evaluated? @@ -880,25 +880,25 @@ Either you put your predicate in the wrong place in your path expression, or you forgot to add some parentheses. Consider this input file \c{doc.txt}: -\quotefile snippets/patternist/doc.txt +\quotefile patternist/doc.txt Suppose you want the first \c{<span>} element of every \c{<p>} element. Apply a position filter (\c{[1]}) to the \c{/span} path step: -\quotefile snippets/patternist/filterOnStep.xq +\quotefile patternist/filterOnStep.xq Applying the \c{[1]} filter to the \c{/span} step returns the first \c{<span>} element of each \c{<p>} element: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 41 +\snippet code/doc_src_qtxmlpatterns.qdoc 41 \note: You can write the same query this way: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 44 +\snippet code/doc_src_qtxmlpatterns.qdoc 44 Or you can reduce it right down to this: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 45 +\snippet code/doc_src_qtxmlpatterns.qdoc 45 On the other hand, suppose you really want only one \c{<span>} element, the first one in the document (i.e., you only want the first @@ -907,17 +907,17 @@ more filtering. There are two ways you can do it. You can apply the \c{[1]} filter in the same place as above but enclose the path expression in parentheses: -\quotefile snippets/patternist/filterOnPath.xq +\quotefile patternist/filterOnPath.xq Or you can apply a second position filter (\c{[1]} again) to the \c{/p} path step: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 43 +\snippet code/doc_src_qtxmlpatterns.qdoc 43 Either way the query will return only the first \c{<span>} element in the document: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 42 +\snippet code/doc_src_qtxmlpatterns.qdoc 42 \section2 Why doesn't my FLWOR behave as expected? @@ -925,7 +925,7 @@ The quick answer is you probably expected your XQuery FLWOR to behave just like a C++ \e{for} loop. But they aren't the same. Consider a simple example: -\quotefile snippets/patternist/letOrderBy.xq +\quotefile patternist/letOrderBy.xq This query evaluates to \e{4 -4 -2 2 -8 8}. The \e{for} clause does set up a \e{for} loop style iteration, which does evaluate the rest of @@ -957,7 +957,7 @@ the variable on the left. In the example above, it binds (4 -4) to 8) on the third iteration. So the following query doesn't iterate through anything, and doesn't do any ordering: -\quotefile snippets/patternist/invalidLetOrderBy.xq +\quotefile patternist/invalidLetOrderBy.xq It binds the entire sequence (2, 3, 1) to \c{$i} one time only; the \e{order by} clause only has one thing to order and hence does @@ -974,7 +974,7 @@ order, because when appearing as operands to a path expression, there is no correct order. Consider the following query, which again uses the input file \c{doc.txt}: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 46 +\snippet code/doc_src_qtxmlpatterns.qdoc 46 The query finds all the \c{<p>} elements in the file. For each \c{<p>} element, it builds a \c{<p>} element in the output containing the @@ -982,16 +982,16 @@ concatenated contents of all the \c{<p>} element's child \c{<span>} elements. Running the query through \c{xmlpatterns} might produce the following output, which is not sorted in the expected order. -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 47 +\snippet code/doc_src_qtxmlpatterns.qdoc 47 You can use a \e{for} loop to ensure that the order of the result set corresponds to the order of the input sequence: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 48 +\snippet code/doc_src_qtxmlpatterns.qdoc 48 This version produces the same result set but in the expected order: -\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 49 +\snippet code/doc_src_qtxmlpatterns.qdoc 49 \section2 Why can't I use \c{true} and \c{false} in my XQuery? @@ -1002,5 +1002,5 @@ to use the builtin functions \c{true()} and \c{false()} wherever you want to use \c{true} and \c{false}. The other way is to invoke the boolean constructor: -\quotefile snippets/patternist/xsBooleanTrue.xq +\quotefile patternist/xsBooleanTrue.xq */ |