Merge branch '4.7' of scm.dev.nokia.troll.no:qt/qt-doc-staging into 4.7-integration

* '4.7' of scm.dev.nokia.troll.no:qt/qt-doc-staging: (45 commits)
  Removed mobile demos from the Symbian build in demos.pro
  Fixed demo subdirs for mobile examples.
  qdoc: Updates to the qdoc manual.
  Moved a couple of links into one list.
  Doc: Work on GettingStartedQt tutorial
  Added a link to the Debugging Techniques article.
  qdoc: Updates to the qdoc manual.
  qdoc: Added a way to exclude directories from receiving default metadata
  Edited the Tutorials and Examples pages. Renamed links in index.qdoc.
  Doc: Update to QStyledItemDelegate::displayText()
  qdoc: Added default values to config file for DITA
  Doc: Work on QAudioInput::start() functions.
  Avoided the use of hard-coded file names.
  Copied the declarative parser into qdoc3 to avoid dependency issues.
  qdoc: Don't wrap <image> in <fig> if in an <xref>
  Doc: Work on a11y docs
  qdoc: Added <copyright>, <copyryear>, and <copyrholder>.
  qdoc: Completed metadata handling.
  Doc: Small update to QImageReader/Writer::supportedImageFomrmats()
  Edited QtWebKit Guide qdoc and added external links.
  ...

4 files changed, 239 insertions, 190 deletions

diff --git a/doc/src/getting-started/demos.qdoc b/doc/src/getting-started/demos.qdoc
index 48a5fca..9366259 100644
--- a/doc/src/getting-started/demos.qdoc
+++ b/doc/src/getting-started/demos.qdoc
@@ -39,7 +39,7 @@
     \l{Qt Examples} and are used to highlight certain features of
     Qt.
 
-    \table 
+    \table
     \header
     \o {2,1} Getting an Overview
     \row
@@ -54,6 +54,17 @@
     If you are new to Qt, and want to start developing applications,
     you should probably start by going through the \l{Tutorials}.
 
+    \keyword qt-mobile-demos
+    \section1 Mobile Applications
+    These are demonstrations of some of the capabilities of \l{Qt Quick} and
+    \l{external: Qt Mobility Manual}{Mobility} to create feature rich mobile
+    applications.
+    \list
+    \o \l{Guitar Tuner Example}{Guitar Tuner} - a guitar tuner made with a QML frontend and a Mobility based backend
+    \o \l{Quick Hit Demo}{Quick Hit} - a game that uses multimedia and Qt Quick
+    \o \l{Qt Bubble Level Example}{Qt Bubble Level} - a game that utilizes hardware sensors for effects
+    \o \l{QCamera Example}{QCamera} - a camera application that accesses mobile contacts and networking
+    \endlist
     \section1 Painting
 
     \list
@@ -105,19 +116,19 @@
     \list
     \o \l{demos/mainwindow}{Main Window} shows Qt's extensive support for main window
        features, such as tool bars, dock windows, and menus.
-    \o \l{demos/macmainwindow}{Mac Main Window} shows how to create main window applications that has 
+    \o \l{demos/macmainwindow}{Mac Main Window} shows how to create main window applications that has
       the same appearance as other Mac OS X applications.
     \endlist
 
     \section1 Graphics View
 
     \list
-    \o \l{demos/chip}{40000 Chips} uses the \l{Graphics View Framework} to 
-       efficiently display a large number of individual graphical items on 
-       a scrolling canvas and highlighting features including rotation, 
+    \o \l{demos/chip}{40000 Chips} uses the \l{Graphics View Framework} to
+       efficiently display a large number of individual graphical items on
+       a scrolling canvas and highlighting features including rotation,
        zooming, level of detail control, and item selection.
-    \o \l{demos/embeddeddialogs}{Embedded Dialogs} showcases Qt 4.4's 
-       \e{Widgets on the Canvas} feature by embedding several 
+    \o \l{demos/embeddeddialogs}{Embedded Dialogs} showcases Qt 4.4's
+       \e{Widgets on the Canvas} feature by embedding several
        fully-functional dialogs in a scene.
     \o \l{demos/boxes}{Boxes} showcases Qt's OpenGL support and the
        integration with the \l{Graphics View Framework}.
diff --git a/doc/src/getting-started/examples.qdoc b/doc/src/getting-started/examples.qdoc
index 55d37d6..9a8fcaa 100644
--- a/doc/src/getting-started/examples.qdoc
+++ b/doc/src/getting-started/examples.qdoc
@@ -36,7 +36,8 @@
 
    You can run the examples from the \l{Examples and Demos Launcher}
    application (except see \l{QML Examples and Demos} {QML Examples}
-   for special instructions for running those examples).
+   for special instructions for running those examples). In addition,
+   Qt Creator can directly run these examples through the Welcome Page.
 
    The examples are listed below by functional area. Each example
    listed in a particular functional area is meant to illustrate how
@@ -56,8 +57,14 @@
    These examples are provided under the terms of the
    \l{New and Modified BSD Licenses}{Modified BSD License}.
 
+   \section1 Qt Quick Example Code
+   The \l{QML Examples and Demos} site has a dedicated page for QML examples.
 
-   \section1 Examples by Functional Area
+   \section1 Qt Mobility Example Code
+   The \l{external: Qt Mobility Examples}{Qt Mobility Examples} page lists
+   examples that show how the Qt Mobility APIs might be used.
+
+   \section1 Qt Examples by Module or Technology
 
    \generatelist{related}
 */
diff --git a/doc/src/getting-started/gettingstartedqt.qdoc b/doc/src/getting-started/gettingstartedqt.qdoc
index 2800be0..18f85f1 100644
--- a/doc/src/getting-started/gettingstartedqt.qdoc
+++ b/doc/src/getting-started/gettingstartedqt.qdoc
@@ -105,12 +105,13 @@
 
     This will leave an executable in the \c part1 directory (note that
     on Windows, you may have to use \c nmake instead of \c make. Also,
-    the executable will be placed in part1/debug or part1/release). \c
-    qmake is Qt's build tool, which takes a configuration file. \c
-    qmake generates this for us when given the \c{-project} argument.
-    Given the configuration file (suffixed .pro), \c qmake produces a
-    \c make file that will build the program for you. We will look
-    into writing our own \c .pro files later.
+    the executable will be placed in part1\\debug or part1\\release
+    (these directories are created when you run \c make). \c qmake is
+    Qt's build tool, which takes a configuration file. \c qmake
+    generates this for us when given the \c{-project} argument. Given
+    the configuration file (suffixed .pro), \c qmake produces a \c
+    make file that will build the program for you. We will look into
+    writing our own \c .pro files later.
 
     \section2 Learn More
 
@@ -245,28 +246,28 @@
     parameter types and invoke it.
 
     Line 13 declares the slot \c quit(). This is easy using the \c
-    slots macro. The \c quit() slot can now be connected to signals
-    with a matching signature (any signal that takes no parameters).
+    slots macro. The \c quit() slot can now be connected to signals.
+    We will do that later.
 
     Instead of setting up the GUI and connecting the slot in the \c
     main() function, we now use \c{Notepad}'s constructor. 
 
     \code
-        Notepad::Notepad()
-        {
-            textEdit = new QTextEdit;
-            quitButton = new QPushButton(tr("Quit"));
-
-            connect(quitButton, SIGNAL(clicked()), this, SLOT(quit()));
-
-            QVBoxLayout *layout = new QVBoxLayout;
-            layout->addWidget(textEdit);
-            layout->addWidget(quitButton);
-
-            setLayout(layout);
-
-            setWindowTitle(tr("Notepad"));
-        }
+20        Notepad::Notepad()
+21        {
+22            textEdit = new QTextEdit;
+23            quitButton = new QPushButton(tr("Quit"));
+24
+25            connect(quitButton, SIGNAL(clicked()), this, SLOT(quit()));
+26
+27            QVBoxLayout *layout = new QVBoxLayout;
+28            layout->addWidget(textEdit);
+29            layout->addWidget(quitButton);
+30
+31            setLayout(layout);
+32
+33            setWindowTitle(tr("Notepad"));
+34        }
     \endcode
 
     As you saw in the class definition, we use pointers to our \l
@@ -277,7 +278,9 @@
     visible strings. This function is necessary when you want to
     provide your application in more than one language (e.g.  English
     and Chinese). We will not go into details here, but you can follow
-    the \c {Qt Linguist} link from the learn more table.
+    the \c {Qt Linguist} link from the learn more table. We will not
+    look at the implementation of \c quit() slot and the \c main()
+    function, but you can check out the source code if you want to.
 
     \section2 Learn More
 
@@ -305,9 +308,9 @@
     using \c qmake's \c -project option.
 
     \code
-        HEADERS =  notepad.h
-        SOURCES =  notepad.cpp \
-                   main.cpp
+ 1        HEADERS =  notepad.h
+ 2        SOURCES =  notepad.cpp \
+ 3                   main.cpp
     \endcode
 
     The following shell commands build the example.
@@ -330,29 +333,29 @@
     Let us look at the new \c Notepad class definition.
 
     \code
-        #include <QtGui>
-
-        class Notepad : public QMainWindow
-        {
-            Q_OBJECT
-
-        public:
-            Notepad();
-
-        private slots:
-            void open();
-            void save();
-            void quit();
-
-        private:
-            QTextEdit *textEdit;
-
-            QAction *openAction;
-            QAction *saveAction;
-            QAction *exitAction;
-
-            QMenu *fileMenu;
-        };
+ 2        #include <QtGui>
+ 3 
+ 4        class Notepad : public QMainWindow
+ 5        {
+ 6            Q_OBJECT
+ 7 
+ 8        public:
+ 9            Notepad();
+10
+11        private slots:
+12            void open();
+13            void save();
+14            void quit();
+15
+16        private:
+17            QTextEdit *textEdit;
+18
+19            QAction *openAction;
+20            QAction *saveAction;
+21            QAction *exitAction;
+22
+23            QMenu *fileMenu;
+24        };
     \endcode
 
     We include two more slots that can save and open a document. We
@@ -369,27 +372,27 @@
     GUI.
 
     \code
-        Notepad::Notepad()
-        {
-            saveAction = new QAction(tr("&Open"), this);
-            saveAction = new QAction(tr("&Save"), this);
-            exitAction = new QAction(tr("E&xit"), this);
-
-            connect(openAction, SIGNAL(triggered()), this, SLOT(open()));
-            connect(saveAction, SIGNAL(triggered()), this, SLOT(save()));
-            connect(exitAction, SIGNAL(triggered()), qApp, SLOT(quit()));
-
-            fileMenu = menuBar()->addMenu(tr("&File"));
-            fileMenu->addAction(openAction);
-            fileMenu->addAction(saveAction);
-            fileMenu->addSeparator();
-            fileMenu->addAction(exitAction);
-
-            textEdit = new QTextEdit;
-            setCentralWidget(textEdit);
-
-            setWindowTitle(tr("Notepad"));
-        }
+25        Notepad::Notepad()
+26        {
+27            saveAction = new QAction(tr("&Open"), this);
+28            saveAction = new QAction(tr("&Save"), this);
+29            exitAction = new QAction(tr("E&xit"), this);
+30
+31            connect(openAction, SIGNAL(triggered()), this, SLOT(open()));
+32            connect(saveAction, SIGNAL(triggered()), this, SLOT(save()));
+33            connect(exitAction, SIGNAL(triggered()), qApp, SLOT(quit()));
+34
+35            fileMenu = menuBar()->addMenu(tr("&File"));
+36            fileMenu->addAction(openAction);
+37            fileMenu->addAction(saveAction);
+38            fileMenu->addSeparator();
+39            fileMenu->addAction(exitAction);
+40
+41            textEdit = new QTextEdit;
+42            setCentralWidget(textEdit);
+43
+44            setWindowTitle(tr("Notepad"));
+45        }
     \endcode
 
     \l{QAction}s are created with the text that should appear on the
@@ -426,28 +429,29 @@
     We will start with the \c open() slot:
 
     \code
-        QString fileName = QFileDialog::getOpenFileName(this, tr("Open File"), "",
-            tr("Text Files (*.txt);;C++ Files (*.cpp *.h)"));
-
-        if (fileName != "") {
-            QFile file(fileName);
-            if (!file.open(QIODevice::ReadOnly)) {
-                QMessageBox::critical(this, tr("Error"),
-                    tr("Could not open file"));
-                return; 
-            }
-            QString contents = file.readAll().constData();
-            textEdit->setPlainText(contents);
-            file.close();
-        }
+48    void Notepad::open()
+49    {
+50        QString fileName = QFileDialog::getOpenFileName(this, tr("Open File"), "",
+51            tr("Text Files (*.txt);;C++ Files (*.cpp *.h)"));
+52
+53        if (fileName != "") {
+54            QFile file(fileName);
+55            if (!file.open(QIODevice::ReadOnly)) {
+56                QMessageBox::critical(this, tr("Error"), tr("Could not open file"));
+57                return;
+58            }
+59            QTextStream in(&file);
+60            textEdit->setText(in.readAll());
+61            file.close();
+62        }
+63    }
     \endcode
 
     The first step is asking the user for the name of the file to
     open. Qt comes with QFileDialog, which is a dialog from which the
     user can select a file. The image above shows the dialog on
     Kubuntu. The static \l{QFileDialog::}{getOpenFileName()} function
-    displays a modal file dialog, and does not return until the user
-    has selected a file. It returns the file path of the file
+    displays a modal file dialog. It returns the file path of the file
     selected, or an empty string if the user canceled the dialog. 
 
     If we have a file name, we try to open the file with
@@ -458,38 +462,38 @@
     message (see the QMessageBox class description for further
     details).
 
-    Actually reading in the data is trivial using the
-    \l{QIODevice::}{readAll()} function, which returns all data in the
-    file in a QByteArray. The \l{QByteArray::}{constData()} returns all
-    data in the array as a const char*, which QString has a
-    constructor for. The contents can then be displayed in the text
+    Actually reading in the data is trivial using the QTextStream
+    class, which wraps the QFile object. The
+    \l{QTextStream::}{readAll()} function returns the contents of the
+    file as a QString. The contents can then be displayed in the text
     edit. We then \l{QIODevice::}{close()} the file to return the file
     descriptor back to the operating system.
 
     Now, let us move on to the the \c save() slot.
 
     \code
-        QString fileName = QFileDialog::getSaveFileName(this, tr("Save File"), "",
-            tr("Text Files (*.txt);;C++ Files (*.cpp *.h)"));
-
-        if (fileName != "") {
-            QFile file(fileName);
-            if (!file.open(QIODevice::WriteOnly)) {
-                // error message
-            } else {
-                QTextStream stream(&file);
-                stream << textEdit->toPlainText();
-                stream.flush();
-                file.close();
-            }
-        }
+65    void Notepad::save()
+66    {
+67        QString fileName = QFileDialog::getSaveFileName(this, tr("Save File"), "",
+68        tr("Text Files (*.txt);;C++ Files (*.cpp *.h)"));
+69
+70        if (fileName != "") {
+71            QFile file(fileName);
+72            if (!file.open(QIODevice::WriteOnly)) {
+73                // error message
+74            } else {
+75                QTextStream stream(&file);
+76                stream << textEdit->toPlainText();
+77                stream.flush();
+78                file.close();
+79            }
+80        }
+81    }
     \endcode
 
     When we write the contents of the text edit to the file, we use
-    the QTextStream class, which wraps the QFile object. The text
-    stream can write QStrings directly to the file; QFile only accepts
-    raw data (char*) with the \l{QIODevice::}{write()} functions of
-    QIODevice.
+    the QTextStream class again. QTextStream can also write
+    \l{QString}s to the file with the << operator.
 
     \section2 Learn More
 
diff --git a/doc/src/getting-started/tutorials.qdoc b/doc/src/getting-started/tutorials.qdoc
index 9fc6699..2849870 100644
--- a/doc/src/getting-started/tutorials.qdoc
+++ b/doc/src/getting-started/tutorials.qdoc
@@ -36,79 +36,106 @@
 
     \nextpage Qt Examples
 
-    A collection of tutorials and "walkthrough" guides are provided with Qt to
+    A collection of tutorials and \e walkthrough guides are provided with Qt to
     help new users get started with Qt development. These documents cover a
     range of topics, from basic use of widgets to step-by-step tutorials that
     show how an application is put together.
 
-    \table
-    \row
-    \o{2,1} \l{Widgets Tutorial}{\bold Widgets}
-    \o{2,1} \l{Address Book Tutorial}{\bold {Address Book}}
-    \row
-    \o \image widget-examples.png Widgets
-    \o
-    A beginner's guide to getting started with widgets and layouts to create
-    GUI applications.
-
-    \o \image addressbook-tutorial.png AddressBook
-    \o
-    A seven part guide to creating a fully-functioning address book
-    application. This tutorial is also available with
-    \l{Tutoriel "Carnet d'adresses"}{French explanation}.
-
-    \row
-    \o{2,1} \l{A Quick Start to Qt Designer}{\bold{Qt Designer}}
-    \o{2,1} \l{Qt Linguist Manual: Programmers#Tutorials}{\bold {Qt Linguist}}
-    \row
-    \o \image designer-examples.png
-    \o
-    A quick guide through \QD showing the basic steps to create a
-    form with this interactive tool.
-
-    \o \image linguist-examples.png QtLinguist
-    \o
-    A guided tour through the translations process, explaining the
-    tools provided for developers, translators and release managers.
-
-
-\row
-    \o{2,1} \l{modelview.html}{\bold{ModelView}}
-    \o{2,1} \l{thread-basics.html}{\bold {Threads}}
-    \row
-    \o \image treeview_sml.png ModelView
-    \o
-    This tutorial gives an introduction to ModelView programming using the Qt cross-platform framework
-
-    \o \image threads-examples.png Threads
-    \o
-    A short tutorial about thread concepts in general and basic Qt classes to handle threads.
-
-    \row
-    \o{2,1} \l{QML Tutorial}{\bold QML Tutorial}
-    \o{2,1} \l{QML Advanced Tutorial}{\bold SameGame}
-    \row
-    \o{2,1}
-    This tutorial provides a very basic introduction to QML.
-    \o \image qml-samegame-demo-small.png Samegame
-    \o
-    This tutorial walks through creating a complete application with QML,
-    in this case a simple game. It is recommended that you complete the basic QML
-    tutorial first.
-
-    \row
-    \o{2,1} \l{QTestLib Tutorial}{\bold QTestLib}
-    \o{2,1} \l{qmake Tutorial}{\bold qmake}
-    \row
-    \o{2,1}
-    This tutorial gives a short introduction to how to use some of the
-    features of Qt's unit-testing framework, QTestLib. It is divided into
-    four chapters.
-
-    \o{2,1}
-    This tutorial teaches you how to use \c qmake. We recommend that
-    you read the \l{qmake Manual}{qmake user guide} after completing
-    this tutorial.
-
-    \endtable
+    For demonstrations on how to use different Qt technologies, visit the
+    \l{Qt Examples} page.
+
+    \section1 Qt Creator Tutorial
+    Qt Creator is the development environment for Qt.
+    \list
+    \o \l{external: Qt Creator Manual}{Qt Creator Manual} - The manual contains
+    information on how to achieve development tasks
+    These are excerpts from the manual:
+        \list
+        \o \l{external: Creating Qt Projects in Creator}{Creating Qt Projects in Creator}
+        \o \l{external: Developing Qt Quick Applications with Creator}{Developing Qt Quick Applications with Creator}
+        \o \l{external: Building and Running Applications in Creator}{Building and Running Applications in Creator}
+        \o \l{external: Debugging Applications in Creator}{Debugging Applications in Creator}
+        \o \l{external: Publishing Applications to Ovi Store}{Publishing Applications to Ovi Store}
+        \endlist
+    \endlist
+
+    \section1 Qt Essentials
+    The basic concepts and technologies in Qt are introduced in these essential
+    tutorials.
+        \list
+        \o \l{Getting Started Programming with Qt}{Qt Text Editor} - A simple
+        tutorial detailing the creation of a basic Qt application
+        Introduces the use of slots and signals, file operations, and widgets.
+        \o \l{Address Book Tutorial}{Address Book} - A beginner's guide to
+        widgets, container classes, and layouts. This tutorial is also available
+        with
+        \l{Tutoriel "Carnet d'adresses"}{French version}.
+        \image addressbook-tutorial.png AddressBook
+        \o \l{modelview.html}{ModelView} - This tutorial gives an introduction to
+        ModelView programming using the Qt cross-platform framework
+        \o\l{thread-basics.html}{Threads} - A short tutorial about thread concepts
+        in general and basic Qt classes to handle threads
+        \endlist
+
+    \section1 Qt Quick Essentials
+    Qt Quick and QML features are covered in several tutorials, ranging from
+    easy introductions to advanced tutorials that mix QML with C++ and
+    JavaScript.
+        \list
+        \o \l{QML Tutorial}{Hello World} - A very simple QML example that
+        demonstrates the basic QML features
+        \o \l{Getting Started Programming with QML}{QML Text Editor} - An
+        intermediate QML tutorial that covers many QML features such as states,
+        plugins, and C++ development
+        \o \l{QML Advanced Tutorial}{SameGame} - A walkthrough of creating a
+        simple game using QML for the interface and JavaScript for the game
+        logic
+        \image qml-samegame-demo-small.png Samegame
+        \endlist
+
+    \section1 QtWebKit
+    \list
+    \o \l{QtWebKit Guide} - An introductory guide to the features of QtWebKit
+    and HTML5.
+        \list
+        \o \l{QtWebKit Guide - Level 3 CSS}{CSS Chapter} - Covers what is
+        possible with CSS3 and QtWebKit.
+        \o \l{Canvas Graphics}{HTML5 Canvas Chapter} - Covers the basics of
+        integrating the <canvas> element into web applications.
+        \o \l{QtWebKit Guide - Client Storage}{Client Storage Chapter} -
+        Describes the basics of storing information on the client side.
+        \endlist
+    \endlist
+
+    \section1 Qt Utilities
+    \list
+    \o \l{QTestLib Tutorial}{QTestLib} - This tutorial gives a short
+    introduction to how to use some of the features of Qt's unit-testing
+    framework, QTestLib. It is divided into four chapters.
+    \o \l{qmake Tutorial}{qmake} - This tutorial teaches you how to use \c
+    qmake. We recommend that you read the \l{qmake Manual}{qmake user guide}
+    after completing this tutorial.
+    \o \l{Qt Linguist Manual: Programmers#Tutorials}{Qt Linguist} - A guided
+    tour through the translations process, explaining the tools provided for
+    developers, translators and release managers.
+    \image linguist-examples.png QtLinguist
+    \endlist
+
+    \section1 Online Learning Materials
+    These online materials provide further tutorials and developer
+    presentations.
+
+    \note The videos presented in these sites are not supported by the
+    Qt Creator browser and must be viewed in a web browser.
+
+    \list
+    \o \l{Qt eLearning} - The Qt eLearning team provides training and Qt
+    certification. Many of their learning content are hosted online.
+        \list
+        \o \l{Qt eLearning Training Materials} - Additional training material
+        are available as videos, downloadable code, and PDF files.
+        \o \l{Qt Developer Days 2010} - The presentation slides and videos from
+        Qt Developer Days are available for viewing.
+        \endlist
+    \endlist
 */