Squashed commit of the changes from the mobile-examples repository

(4.7-generated-declarative branch).

2 files changed, 180 insertions, 61 deletions

diff --git a/tools/qdoc3/doc/corefeatures.qdoc b/tools/qdoc3/doc/corefeatures.qdoc
new file mode 100644
index 0000000..ee579cf
--- /dev/null
+++ b/tools/qdoc3/doc/corefeatures.qdoc
@@ -0,0 +1,35 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Free Documentation License
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page corefeatures.html
+    \title Core Features
+
+    \input examples/signalandslots.qdocinc
+    \input examples/objectmodel.qdocinc
+    \input examples/layoutmanagement.qdocinc
+*/
diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc
index 0e4055b..da0646e 100644
--- a/tools/qdoc3/doc/qdoc-manual.qdoc
+++ b/tools/qdoc3/doc/qdoc-manual.qdoc
@@ -66,6 +66,7 @@
           \o \l {Compatibility Issues}
           \o \l {qt.qdocconf}
           \o \l {minimum.qdocconf}
+          \o \l {Generating DITA XML Output}
         \endlist
     \endlist
 
@@ -3999,20 +4000,11 @@
 
     Here are links to the \c .qdocinc files used above:
     \l{signalandslots.qdocinc}, \l{objectmodel.qdocinc},
-    \l{layoutmanagement.qdocinc}. QDoc renders this page as:
-
-            \quotation
-                \raw HTML
-                <h1>Core Features</h1>
-                \endraw
-
-                \input examples/signalandslots.qdocinc
-                \input examples/objectmodel.qdocinc
-                \input examples/layoutmanagement.qdocinc
-            \endquotation
+    \l{layoutmanagement.qdocinc}. QDoc renders this page 
+    \l{corefeatures.html} {as shown here}.
 
     \target 2-argument-form}
-    \section2 \\include filename snippet-identifier
+    \section2 \\include filename snippet-identifier \span {class="newStuff"} {(new)}
 
     It is kind of a pain to make a separate \c .qdocinc file for every
     QDoc include snippet you want to use in multiple places in the
@@ -4046,48 +4038,77 @@
     sent to the QDoc input stream. You can even nest these snippets,
     although it's not clear why you would want to do that.
 
-    \target meta-command
+    \target meta-command 
     \section1 \\meta 
 
-    The \\meta command is the QDoc equivalent to the HTML
-    \c meta tag.
-
-    The command accepts two arguments: The first argument (the
-    following word) is equivalent to the HTML meta tag's \e name
-    variable, and the second argument (the rest of the line) is
-    equivalent to the tag's \e contents variable.
-
-           \code
-           / *!
-               \meta author Summerfield
-
-               \section1 Automatic Dialogs
-
-               \abstract
-                   This article shows how to maintain sets of
-                   "attributes" (QVariant values), and how to allow
-                   users to view and edit them using dialogs that are
-                   created dynamically based on the attributes and
-                   their types.
-               \endabstract
-
-               The Attributes class described in this article holds a
-               set of QVariants, and can create a dialog to present
-               the QVariants to the user in an appropriate way.
+    The \\meta command is mainly used for including metadata in DITA
+    XML files. It is also used when generating HTML output for specifying
+    the \e maintainer(s) of a C++ class.
 
-               ...
-           * /
-           \endcode
+    The command has two arguments: The first argument is the name of the
+    metadata attribute you wish to set, and the second argument is the 
+    value for the attribute. Each argument should be enclosed in curly
+    brackets, as shown in this example:
 
-    QDoc renders this as:
+    \code
+    / *!
+        \class QWidget
+        \brief The QWidget class is the base class of all user interface objects.
+
+        \ingroup basicwidgets
+
+        \meta {technology} {User Interface}
+        \meta {platform} {OS X 10.6}
+        \meta {platform} {Symbian}
+        \meta {platform} {MeeGo}
+        \meta {audience} {user}
+        \meta {audience} {programmer}
+        \meta {audience} {designer}
+    * /
+    \endcode
 
-           \code
-           <head>
-                ...
-                <meta name="author" content="Summerfield" />
-                ...
-           </head>
-           \endcode
+    When running QDoc to generate HTML, the example above will have no
+    effect on the generated output, but if you run QDoc to generate
+    DITA XML, the example will generate the following:
+
+    \code
+    <?xml version="1.0" encoding="UTF-8"?>
+    <!DOCTYPE cxxClass PUBLIC "-//NOKIA//DTD DITA C++ API Class Reference Type v0.6.0//EN" "dtd/cxxClass.dtd">
+    <!--qwidget.cpp-->
+    <cxxClass id="id-9a14268e-6b09-4eee-b940-21a00a0961df">
+       <apiName>QWidget</apiName>
+       <shortdesc>the QWidget class is the base class of all user interface objects.</shortdesc>
+       <prolog>
+           <author>Qt Development Frameworks</author>
+           <publisher>Nokia</publisher>
+           <copyright>
+               <copyryear year="2011"/>
+               <copyrholder>Nokia</copyrholder>
+           </copyright>
+           <permissions view="all"/>
+           <metadata>
+               <audience type="designer"/>
+               <audience type="programmer"/>
+               <audience type="user"/>
+               <category>Class reference</category>
+               <prodinfo>
+                   <prodname>Qt Reference Documentation</prodname>
+                   <vrmlist>
+                       <vrm version="4" release="7" modification="3"/>
+                   </vrmlist>
+                   <component>QtGui</component>
+               </prodinfo>
+               <othermeta name="platform" content="MeeGo"/>
+               <othermeta name="platform" content="Symbian"/>
+               <othermeta name="platform" content="OS X 10.6"/>
+               <othermeta name="technology" content="User Interface"/>
+           </metadata>
+       </prolog>
+    \endcode
+
+    In the example output, several values have been set using defualt
+    values obtained from the QDoc configuration file. See \l
+    {Generating DITA XML Output} for details.
 
     \target omit-command
     \section1 \\omit 
@@ -6932,7 +6953,7 @@
     \page 21-1-minimum-qdocconf.html
     \previouspage qt.qdocconf
     \contentspage Table of Contents
-    \nextpage Table of Contents
+    \nextpage Generating DITA XML Output
 
     \title minimum.qdocconf
 
@@ -6951,6 +6972,65 @@
 */
 
 /*!
+    \page 21-3-qt-dita-xml-output.html
+    \previouspage minimum.qdocconf
+    \contentspage Table of Contents
+    \nextpage Table of Contents
+
+    \title Generating DITA XML Output
+
+    QDoc can generate \l {http://dita.xml.org} {DITA XML output}. 
+
+    In your confifiguration file, set your \c {outputformats} variable
+    to \c {DITAXML}, and send the output to an appropriate directory:
+
+    \code
+    outputdir                  = $QTDIR/doc/ditaxml
+    outputformats              = DITAXML
+    \endcode
+
+    And include these macros in your configuration file to prevent
+    QDoc from doing some escaping that doesn't validate in XML:
+
+    \code
+    macro.aacute.DITAXML       = "&aacute;"
+    macro.Aring.DITAXML        = "&Aring;"
+    macro.aring.DITAXML        = "&aring;"
+    macro.Auml.DITAXML         = "&Auml;"
+    macro.br.DITAXML           = " "
+    macro.BR.DITAXML           = " "
+    macro.copyright.DITAXML    = "&copy;"
+    macro.eacute.DITAXML       = "&eacute;"
+    macro.hr.DITAXML           = " "
+    macro.iacute.DITAXML       = "&iacute;"
+    macro.oslash.DITAXML       = "&oslash;"
+    macro.ouml.DITAXML         = "&ouml;"
+    macro.raisedaster.DITAXML  = "<sup>*</sup>"
+    macro.rarrow.DITAXML       = "&rarr;"
+    macro.reg.DITAXML          = "<sup>&reg;</sup>"
+    macro.uuml.DITAXML         = "&uuml;"
+    macro.mdash.DITAXML        = "&mdash;"
+    macro.emptyspan.DITAXML    = " "
+    \endcode
+
+    You can also set default values for some of the tags in the DITA
+    \c {<prolog>} and \c {<metadata>} elements:
+
+    \code
+    dita.metadata.default.author      = Qt Development Frameworks
+    dita.metadata.default.permissions = all
+    dita.metadata.default.publisher   = Nokia
+    dita.metadata.default.copyryear = 2011
+    dita.metadata.default.copyrholder = Nokia
+    dita.metadata.default.audience = programmer
+    \endcode
+
+    See the \l {12-0-qdoc-commands-miscellaneous.html#meta-command}
+    {\\meta} command for more details on DITA metadata.
+
+*/
+
+/*!
     \page 22-qdoc-configuration-generalvariables.html
     \previouspage The QDoc Configuration File
     \contentspage Table of Contents
@@ -6981,7 +7061,7 @@
     information see the \l {Compatibility Issues} {compatibility
     section}.
 
-    See also \l {macro-command} {macro}.
+    See also \l {macro-variable} {macro}.
 
     \target codeindent-variable
     \section1 codeindent 
@@ -7480,23 +7560,27 @@
     \target macro-variable
     \section1 macro 
 
-    The \c macro variable can be used to create your own QDoc
-    commands.
+    The \c macro variable is used to create your own simple QDoc
+    commands. The syntax is \tt {macro.\e{command} = \e{definition}},
+    where the definition is written using QDoc syntax.
 
-    The general syntax is \tt {macro.\e{command} =
-    "\e{definition}}". The definition can be described using QDoc
-    syntax. In addition it is possible to provide an HTML definition
-    by appending .HTML to the variable.
-
-    For example in \l qt.qdocconf:
+    A macro variable can be restricted for use in one type of output
+    generation. By appending \c {.HTML} to the macro name, for
+    example, the macro is only used when generating HTML output. By
+    appending \c {.DITAXML} to the macro name, the macro is only used
+    when generating DITA XML.
 
     \code
         macro.gui              = "\\bold"
         macro.raisedaster.HTML = "<sup>*</sup>"
     \endcode
 
-    makes sure that the \\gui command renders its argument using a
-    bold font, and that \\raisedaster renders a '*'.
+    The first macro defines the \\gui command to render its argument
+    using a bold font. The second macro defines the \\raisedaster
+    command to render a superscript asterisk, but only when generating
+    HTML.
+
+    See also \l {alias-variable} {alias}.
 
     \target naturallanguage-variable
     \section1 naturallanguage