Add an initial attempt at docs on the new runtime and imports.

3 files changed, 161 insertions, 61 deletions

diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc
index ca4c5da..69a8216 100644
--- a/doc/src/declarative/declarativeui.qdoc
+++ b/doc/src/declarative/declarativeui.qdoc
@@ -94,6 +94,7 @@ completely new applications.  QML is fully \l {Extending QML in C++}{extensible
 \o \l {qdeclarativefocus.html}{Keyboard Focus}
 \o \l {Extending types from QML}
 \o \l {Dynamic Object Creation}
+\o \l {qmlruntime.html}{The Qt Declarative Runtime}
 \endlist
 
 \section1 Reference:
diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc
index 53de32c..f90e23b 100644
--- a/doc/src/declarative/modules.qdoc
+++ b/doc/src/declarative/modules.qdoc
@@ -42,14 +42,79 @@
 /*!
 \page qdeclarativemodules.html
 \title Modules
+\section1 QML Modules.
+QUERY: Is a directory with no qmldir really a module? Assumed NO.
 
-A \bold module is a collection of QML types.
+A \bold module is a collection of QML types. These types can be defined in QML, or in C++
+through a QDeclarativeExtensionPlugin. They can then be collected into a directory to comprise
+a module.
+
+Additionally a module can also be a collection of types which was compiled into your application, see \l{Extending QML in C++}.
+
+While a directory containing types can be used to organize QML components, QML modules also contain a \c qmldir file.
+This file provides a manifest of all types available in the module,
+and allows versioned imports (among other things). A directory containing only QML files or plugins behaves similarly
+to a module, but a QML module requires a \c qmldir file (unless it is written in C++ and compiled into your application).
+
+\section2 The \c qmldir File
+
+QML modules containing installed files and remote content require a file \c qmldir which specifies the
+mapping from all type names to versioned QML files. It is a list of lines of the form:
+
+\code
+# <Comment>
+<TypeName> <InitialVersion> <File>
+plugin <Name> [<Path>]
+\endcode
+
+# <Comment> lines are ignored, and can be used for comments.
+
+<TypeName> <InitialVersion> <File> lines are used to add QML files as types.
+<TypeName> is the type being made available; <InitialVersion> is a version
+number like \c 4.0; <File> is the (relative)
+file name of the QML file defining the type. 
+
+plugin <Name> [<Path>] lines are used to add plugins (QDeclarativeExtensionPlugin subclasses
+written in C++) to the module. The line starts with the keyword 'plugin'; <Name> is the
+name of the library; <Path> is an optional argument specifying the full path to the directory
+containing the plugin file, if it is omitted then the directory is assumed to be the same as
+the directory of the qmldir file. Note that <Name> is not usually the same as the file name
+of the plugin binary, which is platform dependent e.g. the library MyAppTypes would produce a libMyAppTypes.so on linux and MyAppTypes.dll on windows. 
+
+The same type can be provided by different files in different versions, in which
+case later earlier versions (eg. 1.2) must precede earlier versions (eg. 1.0),
+since the \e first name-version match is used.
+
+Installed files do not need to import the module of which they are a part, as they can refer
+to the other QML files in the module as relative (local) files.
+If the module is imported from a remote location, those files must nevertheless be listed in
+the \c qmldir file. Internal files can be marked with the \c internal keyword, to ensure
+they are not visible outside the module:
+
+\code
+internal <TypeName> <File>
+\endcode
+
+Installed and remote files \e must be referred to by version information described above,
+local files \e may have it.
+
+The versioning system ensures that a given QML file will work regardless of the version
+of installed software, since a versioned import \e only imports types for that version,
+leaving other identifiers available, even if the actual installed version might otherwise
+use those identifiers.
+
+\section1 Importing Modules
 
 To use types from a module it must be imported using the \c import statement. Successive
 import statements override earlier import statements, however, since imports have version
 qualifiers, changes in modules do not alter the semantics of imports.
 
-\section1 Importing Types Defined in C++
+While it is possible to import some modules without specifying a version this is only advisable
+during prototyping, where version numbers mean very little. The rest of the time it is recommended that
+you take advantage of the versioning capabilities of the language.
+
+You can import a directory in the same way that you import a module, except that you cannot specify a version
+number. This will import all the types in that directory as QML files or as part of plugins.
 
 Types \link adding-types defined in C++\endlink can be from types your application defines, standard QML types,
 or types defined in plugins. To use any such types, you must import
@@ -90,7 +155,7 @@ Installed plugins and QML files can both contribute types to the same module.
 The specification of types to versions is given by a special file, \c qmldir which must
 exist in the module directory. The syntax is described below.
 
-The \c -L option to the \l {qmlviewer}{viewer} application also adds paths to the import path.
+The \c -L option to the \l {qmlviewer}{runtime} application also adds paths to the import path.
 
 
 \section2 Local QML Files
@@ -103,62 +168,31 @@ import "path"
 \endcode
 
 This allows all components defined in the directory \c path to be used in
-the component where this statement appears.
+the component where this statement appears. Because no version number is specified,
+all types in the directory will be imported.
 
-In this case, and only this case, it is not necessary for the module directory to include
+In this case, and only this case, it is not necessary for the directory to include
 a \c qmldir file, nor is it necessary to provide a version qualifier. The basis of this is
 that the files in the subdirectory are assumed to be packaged with the importer, and therefore
-they form a single versioned unit.
-
-
-\section2 Remote QML Files
-
-To import types defined in QML file at arbitrary network locations, a quoted absolute URL is used:
+they form a single versioned unit. It is however recommended that you add a qmldir file and create
+a QML module, as this provides additional options such as more flexible versioning. If the directory
+is a module then you can use a version qualifier, like below
 
 \code
-import "http://url/.../" 1.0
+import "path" 1.0
 \endcode
 
-This works the same as for relative directory imports, except that the target location \e must
-include a \c qmldir file, and a version qualifier must be given.
-
 
-\section2 The \c qmldir File
-
-Directories of installed files and remote content must include a file \c qmldir which specifies the
-mapping from all type names to versioned QML files. It is a list of lines of the form:
-
-\code
-# <Comment>
-<TypeName> <InitialVersion> <File>
-\endcode
-
-<TypeName> is the type being made available; <InitialVersion> is a version
-number like \c 4.0; <File> is the (relative)
-file name of the QML file defining the type.
-
-The same type can be provided by different files in different versions, in which
-case later earlier versions (eg. 1.2) must precede earlier versions (eg. 1.0),
-since the \e first name-version match is used.
+\section2 Remote QML Files
 
-Installed files do not need to import the module of which they are a part, as they can refer
-to the other QML files in the module as relative (local) files.
-If the module is imported from a remote location, those files must nevertheless be listed in
-the \c qmldir file. Internal files can be marked with the \c internal keyword, to ensure
-they are not visible outside the module:
+To import types defined in QML file at arbitrary network locations, a quoted absolute URL is used:
 
 \code
-internal <TypeName> <File>
+import "http://url/.../" 1.0
 \endcode
 
-Installed and remote files \e must be referred to by version information described above,
-local files \e may have it.
-
-The versioning system ensures that a given QML file will work regardless of the version
-of installed software, since a versioned import \e only imports types for that version,
-leaving other identifiers available, even if the actual installed version might otherwise
-use those identifiers.
-
+This works the same as for relative directory imports, except that the target location contain a QML module (\e must
+include a \c qmldir file), and a version qualifier must be given.
 
 \section1 Namespaces - Named Imports
 
@@ -185,6 +219,17 @@ modules can be imported into the global namespace:
 import Qt 4.6 as Nokia
 import Ovi 1.0 as Nokia
 \endcode
+
+There is one special module, called Qt, which contains all of the types that are part of
+Qt Declarative. While it still needs to be imported, this module can be used in all QML
+files.
+
+While import statements are need to make any types available in QML, the directory of the
+current file is implicitly loaded. This is the exact same as if you had added 'import "."' to
+every QML file. The effect of this is that you can automatically use Types defined in C++ plugins
+or QML files if they reside in the same directory.
+
+
 */
 
 /*
diff --git a/doc/src/declarative/qmlruntime.qdoc b/doc/src/declarative/qmlruntime.qdoc
index 6d3e109..710a030 100644
--- a/doc/src/declarative/qmlruntime.qdoc
+++ b/doc/src/declarative/qmlruntime.qdoc
@@ -41,32 +41,82 @@
 
 /*!
     \page qmlruntime.html
-    \title Qt Declarative UI Viewer (qmlviewer)
+    \title Qt Declarative UI Runtime
     \ingroup qttools
     \keyword qmlviewer
 
-    This page documents the \e{Declarative UI Viewer} for the Qt GUI
-    toolkit. The \c qmlviewer reads a declarative user interface definition
+    This page documents the \e{Declarative UI Runtime} for the Qt GUI
+    toolkit, and the \c qml executable which can be used to run apps
+    written for the runtime. The \c qml executable reads a declarative user interface definition
     (\c .qml) file and displays the user interface it describes.
 
-    qmlviewer is a development tool.  It is not intended to be
-    installed in a production environment.
+    QML is a runtime, as you can run plain qml files which pull in their required modules.
+    To run apps with the QML runtime, you can either start the runtime
+    from your on application (using a QDeclarativeView) or with the simple \c qml application.
+    The \c qml application can be
+    installed in a production environment, assuming that it is not already
+    present in the system. It is generally packaged alongside Qt.
 
-    \section1 Options
+    To deploy an application using the QML runtime, you have two options. You can either write your
+    own Qt application including a QDeclarative view and deploy it the same as
+    any other Qt application (not discussed further on this page). Alternatively you can write a main QML file for
+    your application, and run your application using the \c qml executable. If a qml file
+    is passed as an argument to the \c qml executable, it will automatically run it.
 
-    When run with the \c -help option, qmlviewer shows available options.
+    Deploying a QML application via the \c qml executable allows for QML only deployments, but can also
+    include custom C++ modules just as easily. Below is an example of how you might structure
+    a complex application deployed via the qml runtime, it is a listing of the files that would
+    be included in the deployment package.
 
-    \section1 Dummy Data
+    \code
+    MyApp.qml
+    MyAppCore/qmldir
+    MyAppCore/libMyAppCore.so
+    MyAppCore/MyAppCore.dll
+    MyAppCore/AnAppElement.qml
+    MyAppCore/AnotherElement.qml
+    MyAppCore/images/Logo.png
+    OtherModule/qmldir
+    OtherModule/OtherElement.qml
+    \endcode
+
+    Note that this example is for deploying the example to both windows and linux. You will still need to compile the C++
+    modules for each target platform, but you can deploy multiple versions of the modules across platforms with different naming conventions,
+    as the appropriate module file is chosen based on platform naming conventions. The C++ 
+    modules must contain a QDeclarativeExtentionPlugin subclass.
+
+    The application would be executed either with your own application, the command 'qml MyApp.qml' or by 
+    opening the qml file if your system has the \c qml executable registered as the handler for qml files. The MyApp.qml file would have access
+    to all of the deployed types using the import statements such as the following:
 
-    One use of qmlviewer is to allow QML files to be viewed stand-alone,
-    rather than being loaded from within a Qt program. Qt applications will
-    usually bind objects and properties into the execution context before
-    running the QML. To stand-in for such bindings, you can provide dummy
-    data: create a directory called "dummydata" in the same directory as
+    \code
+    import "MyAppCore"
+    import "OtherModule" 1.0 as Other
+    \endcode
+    
+    \section1 \c qml application functionality
+    The \c qml application implements some additional functionality to help it serve the role of a launcher
+    for myriad applications. If you implement your own launcher application, you may also wish to reimplement
+    some or all of this functionality. However, much of this functionality is intended to aid the prototyping of
+    qml applications and may not be necessary for a deployed application.
+
+    \section2 Options
+
+    When run with the \c -help option, qml shows available options.
+
+    \section2 Dummy Data
+
+    The secondary use of the qml runtime is to allow QML files to be viewed with
+    dummy data. This is useful when prototyping the UI, as the dummy data can
+    be later replaced with actual data and bindings from a C++ plugin. 
+    To provide dummy data: create a directory called "dummydata" in the same directory as
     the target QML file and create files there with the "qml" extension.
     All such files will be loaded as QML objects and bound to the root
     context as a property with the name of the file (without ".qml").
 
+    To replace this with real data, you simply bind the real object to 
+    the root context in C++.
+
     For example, if the Qt application has a "clock.time" property
     that is a qreal from 0 to 86400 representing the number of seconds since
     midnight, dummy data for this could be provided by \c dummydata/clock.qml:
@@ -76,9 +126,9 @@
     Any QML can be used in the dummy data files. You could even animate the
     fictional data!
 
-    \section1 Screen Orientation
+    \section2 Screen Orientation
 
-    A special piece of dummy data which is integrated into the viewer is
+    A special piece of dummy data which is integrated into the runtime is
     a simple orientation property. The orientation can be set via the
     settings menu in the application, or by pressing Ctrl+T to toggle it.
 
@@ -96,4 +146,8 @@
     }
 \endcode
 
+    This allows your application to respond to the orientation of the screen changing. The runtime
+    will automatically update this on some platforms (currently the N900 only) to match the physical
+    screen's orientation. On other plaforms orientation changes will only happen when explictly asked for.
+
 */