17 files changed, 763 insertions, 263 deletions
diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc
index 401cf16..7416341 100644
--- a/doc/src/declarative/animation.qdoc
+++ b/doc/src/declarative/animation.qdoc
@@ -29,134 +29,301 @@
 \page qdeclarativeanimation.html
 \title QML Animation
 
-Animation in QML is done by animating properties of objects. Properties of type
-real, int, color, rect, point, size, and vector3d can all be animated.
 
-QML supports three main forms of animation: basic property animation,
-transitions, and property behaviors.
+In QML, animations are created by applying animation objects to object property
+values to gradually change them over time. Animation objects are created from
+the built-in set of animation elements, which can be used to animate various
+types of property values. In addition, animation objects can be applied in
+different ways depending on the context in which they are required.
+
+To create an animation, use an appropriate animation element for the type of
+the property that is to be animated, and apply the animation depending on the
+type of behavior that is required. This page describes the \l {Types of
+Animations} that can be created and the \l {Animation Elements} that are used
+to create these animations.
+
+
+\section1 Types of Animations
+
+An animation is created in different ways depending on the context in which it
+is required. Suppose a \l Rectangle's movement - that is, changes in its \c x
+or \c y property values - should be animated. The semantics of the animation
+differ depending on whether you want to create:
+
+\list
+\o An animation that moves the \l Rectangle as soon as it is created, to a
+known position
+\o An animation that only triggers when the \l Rectangle is moved by external
+sources - for example, when the mouse is clicked, animate the movement to the
+mouse position
+\o An animation that triggers when a particular signal is received
+\o A standalone animation that is not bound to the \l Rectangle's movement, but
+instead can be started and stopped from script as required
+\o An animation that only triggers during \l{QML States}{state changes}
+\endlist
+
+To support these different types of animation methods, QML provides several
+methods for defining an animation. These are:
+
+\list
+\o Creating an \l{Animations as Property Value Sources}{animation using
+property value sources}, to immediately animate a specific property
+\o Using \l{Behavioral Animations}{behavioral animations}, which are triggered
+when a property changes value
+\o \l{Animations in a Signal Handler}{Within a signal handler}, to be triggered
+when a signal is received
+\o As a \l{Standalone Animation}{standalone animation}, that can be
+started/stopped from script and can be rebound to different objects
+\o Using \l{Transitions}{transitions}, to provide animations between \l{QML
+States}{state changes}
+\endlist
+
+These methods are demonstrated below. Notice these examples use
+PropertyAnimation, which is one of several QML elements that can be used to
+create an animation. See the \l {Animation Elements} section further below for 
+details.
 
-\tableofcontents
 
-\section1 Basic Property Animation
 
-The simplest form of animation is a \l PropertyAnimation, which can animate all of the property
-types listed above. If the property you are animating is a number or color, you can alternatively use
-NumberAnimation or ColorAnimation. These elements don't add any additional functionality,
-but will help enforce type correctness and are slightly more efficient.
+\section2 Animations as Property Value Sources
+
+An animation is applied as a \l{QDeclarativePropertyValueSource}{property value
+source} using the \e Animation \bold on \e Property syntax. Here is a \l
+Rectangle whose movement is animated using this method:
+
+\snippet doc/src/snippets/declarative/animation-propertyvaluesource.qml 0
+	
+This applies a PropertyAnimation to the \l Rectangle's \c x and \c y properties
+to animate from their current values (i.e. zero) to 50, over 1000 milliseconds.
+The animation starts as soon as the \l Rectangle is loaded. To animate from
+specific values rather than the current \c x and \c y values, set the
+PropertyAnimation's \l {PropertyAnimation::}{from} property.
+
+Specifying an animation as a property value source is useful for animating a
+property to a particular value as soon as the object is loaded.
+
+
+\section2 Behavioral Animations
+
+Often an animation should be applied whenever a particular property value
+changes. In these cases, a \l Behavior can be used to specify a default
+animation for a property change. Here is an example:
+
+\snippet doc/src/snippets/declarative/animation-behavioral.qml 0
 
-A property animation can be specified as a value source using the \e Animation \bold on \e property syntax. This is especially useful
-for repeating animations.
+This \l Rectangle has \l Behavior objects applied to its \c x and \c y
+properties. Whenever these properties change (in this case, when the mouse is
+clicked within the parent \l Item), the PropertyAnimation objects defined
+within the behaviors will be applied to these properties, thus animating the \l
+Rectangle's movement to its new position. Unlike the method of \l {Animations
+as Property Value Sources}{defining an animation as a property value source},
+which creates a one-time animation that animates a property to a known value, a
+behavioral animation is an animation that is triggered \e {in response to} a
+value change.
 
-The following example creates a bouncing effect:
-\snippet doc/src/snippets/declarative/animation.qml property-anim-1
+Any changes to these properties will trigger their animations. If \c x or \c y
+were bound to other properties, and those properties changed, the animation
+would be triggered. The \l{Behavior::}{enabled} property can be used to force a
+\l Behavior to only apply under certain circumstances.
 
-\image propanim.gif
+Notice that unlike for property value source animations, the
+PropertyAnimation's \l {PropertyAnimation::}{from} and \l
+{PropertyAnimation::}{to} properties do not need to be defined because these
+values are already provided, respectively, by the \l Rectangle's current values
+and the new values set in the \c onClicked handler. If these properties were
+defined anyway, they would override the default values.
+
+See the \l {declarative/animation/behaviors}{Behaviors example} for a
+demonstration of behavioral animations.
+
+
+\section2 Animations in a Signal Handler
+
+An animation can be created within a signal handler to be triggered when the
+signal is received. For example:
+    
+\snippet doc/src/snippets/declarative/animation-signalhandler.qml 0
+
+The PropertyAnimation is triggered when the MouseArea is clicked, animating the
+\c x and \c y properties to a value of 50 over 1000 milliseconds. Since the
+animation is not bound to a particular object or property, it must define the
+\l {PropertyAnimation::}{target} and \l {PropertyAnimation::}{property} (or \l
+{PropertyAnimation::}{targets} and \l{PropertyAnimation::}{properties}) values.
+The \l {PropertyAnimation::}{to} property is also required to specify the new
+\c x and \c y values.
+
+
+\section2 Standalone Animations
+
+Animations can also be created as ordinary QML objects that are not bound to
+any particular objects and properties. An example:
+
+\snippet doc/src/snippets/declarative/animation-standalone.qml 0
+
+A standalone animation is not running by default and must be started explicitly
+using the \l {Animation::}{running} property or \l {Animation::}{start()} and
+\l {Animation::}{stop()} methods. Since the animation is not bound to a
+particular object or property, it must define the \l
+{PropertyAnimation::}{target} and \l {PropertyAnimation::}{property} (or \l
+{PropertyAnimation::}{targets} and \l{PropertyAnimation::}{properties}) values.
+The \l {PropertyAnimation::}{to} property is also required to specify the new
+\c x and \c y values. (The \l {PropertyAnimation::}{from} value can optionally
+be provided.)
+
+Standalone animations are useful when an animation is not targeted towards a
+single object property and the animation should be explicitly started and
+stopped.
+
+
+\section2 Transitions
 
-When you assign an animation as a value source, you do not need to specify \c property
-or \c target values; they are automatically selected for you. You do, however, need to specify a \c to value.
-An animation specified as a value source will be \c running by default.
+Transitions are used to describe the animations to be applied when a \l {QML
+States}{state change} occurs. To create a transition, define a \l Transition
+object and add it to an item's \l {Item::}{transitions} property. An example:
 
-For example, here is a rectangle that uses a \l NumberAnimation value source to animate the movement
-from its current position to an \c x value of 50. The animation starts immediately, and only the \c to 
-property is required:
+\snippet doc/src/snippets/declarative/animation-transitions.qml 0
 
-\snippet doc/src/snippets/declarative/animation.qml property-anim-2
+When the \l Rectangle changes to the \e moved state, its \c x and \c y property
+values are changed by the PropertyChanges object, and the PropertyAnimation
+defined within the \l Transition is triggered on these properties. The
+animation will not be applied at any time other than during the state change.
 
-A property animation can also be specified as a resource that is manipulated from script.
+Notice the example does not set any \l {PropertyAnimation::}{from} and \l
+{PropertyAnimation::}{to} values for the PropertyAnimation. As a convenience,
+these properties are automatically set to the values of \c x and \c y before
+and after the state change, respectively. However, they can be explicitly set
+if these values should be overrided.
 
-\snippet doc/src/snippets/declarative/animation.qml property-anim-3
+Also notice the PropertyAnimation does not need to specify a \l
+{PropertyAnimation::}{target} object; any \c x or \c y value of any object that
+has changed during the state change will be animated. However, the target can
+be set if the animation should be restricted to certain objects.
 
-As can be seen, when an animation is used like this (as opposed to as a value source) you will need
-to explicitly set the \c target and \c property to animate.  This also the only case where
-an animation needs to be started explictly by either setting the \c running property to
-true or calling the \c start() method.
+The top-level animations in a \l Transition are run in parallel. To run them
+one after the other, use a SequentialAnimation, as shown below in \l {Grouping
+Animations}.
 
-Animations can be joined into a group using SequentialAnimation and ParallelAnimation.
+See the \l Transition documentation for more information.
 
-See the \l {declarative/animation/basics}{Animation basics example} for a demonstration of creating and combining multiple animations in QML.
 
-\target state-transitions
-\section1 Transitions
+\section1 Animation Elements
 
-\l Transition elements describe the animations to perform when \l{qmlstates}{state} changes occur. A transition
-can only be triggered by a state change.
+To create an animation, choose from one of the built-in QML animation elements.
+While the above examples are demonstrated using PropertyAnimation, they could
+have used other elements depending on the type of the property to be animated
+and whether a single or multiple animations are required.
 
-For example, a \l Transition could describe how an item moves from its initial position to its new position:
+All animation elements inherit from the \l Animation element. It is not
+possible to create \l Animation objects; instead, this element provides the
+essential properties and methods for animation elements. For example, it allows
+animations to be started and stopped through the \l {Animation::}{running}
+property and the \l{Animation::}{start()} and \l{Animation::}{stop()} methods.
+It can also define the number of \l {Animation::}{loops} for an animation.
 
-\snippet doc/src/snippets/declarative/animation.qml transitions-1
 
-As can be seen, transitions make use of the same basic animation classes introduced above.
-In the above example we have specified that we want to animate the \c x and \c y properties, but have not
-specified the objects to animate or the \c to values. By default these values are supplied by the framework;
-the animation will animate any \c targets whose \c x and \c y have changed, and the \c to values will be those
-defined in the end state. You can always supply explicit values to override these implicit values when needed.
+\section2 Property Animation Elements
 
-\snippet doc/src/snippets/declarative/animation.qml transitions-2
+PropertyAnimation is the most basic animation element for animating a property.
+It can be used to animate \c real, \c int, \c color, \c rect, \c point, \c size, and
+\c vector3d properties. It is inherited by NumberAnimation, ColorAnimation,
+RotationAnimation and Vector3dAnimation: NumberAnimation provides a more 
+efficient implementation for animating \c real and \c int properties, and 
+Vector3dAnimation does the same for \c vector3d properties.  ColorAnimation 
+and RotationAnimation provide more specific attributes for animating color 
+and rotation changes. 
 
-QML transitions have selectors to determine which state changes a transition should apply to.
-The following transition will only be triggered when we enter into the \c "details" state.
-(The "*" value is a wildcard value that specifies the transition should be applied when changing
-from \e any state to the "details" state.)
+A ColorAnimation allows color values for the \l {ColorAnimation::}{from} 
+and \l {ColorAnimation::}{to} properties. The
+following animates the rectangle's \l {Rectangle::color} property:
 
-\code
-Transition {
-    from: "*"
-    to: "details"
-    ...
-}
-\endcode
+\snippet doc/src/snippets/declarative/animation-elements.qml color
 
-Transitions can happen in parallel, in sequence, or in any combination of the two. By default, the top-level
-animations in a transition will happen in parallel. The following example shows a rather complex transition
-making use of both sequential and parallel animations:
+RotationAnimation allows a rotation's direction to be specified. The following
+animates the rectangle's \l {Item::rotation} property:
 
-\snippet doc/src/snippets/declarative/animation.qml transitions-3
+\snippet doc/src/snippets/declarative/animation-elements.qml rotation
 
+In addition, the following specialized animation elements are available:
 
-See \l {declarative/animation/states}{States and Transitions example} for a simple example of how transitions can be applied.
+\list
+\o SmoothedAnimation: a specialized NumberAnimation that provides smooth 
+changes in animation when the target value changes
+\o SpringAnimation: provides a spring-like animation with specialized 
+attributes such as \l {SpringAnimation::}{mass}, 
+\l{SpringAnimation::}{damping} and \l{SpringAnimation::}{epsilon}
+\o ParentAnimation: used for animating a parent change (see ParentChange)
+\o AnchorAnimation: used for animating an anchor change (see AnchorChanges)
+\endlist
 
+See their respective documentation pages for more details.
 
-\section1 Property Behaviors
 
-A property \l {Behavior}{behavior} specifies a default animation to run whenever the property's value changes, regardless
-of what caused the change. The \c enabled property can be used to force a \l Behavior
-to only apply under certain circumstances.
+\section3 Easing
+
+Any PropertyAnimation-based animations can specify \l
+{PropertyAnimation::easing.type}{easing attributes} to control the
+easing curve applied when a property value is animated. These control the
+effect of the animation on the property value, to provide visual effects like
+bounce, acceleration and deceleration.
+
+For example, this modified version of an \l {Animations as Property Value
+Sources}{earlier example} uses \c Easing.OutBounce to create a bouncing effect
+when the animation reaches its target value:
+
+\snippet doc/src/snippets/declarative/animation-easing.qml 0
+
+The \l{declarative/animation/easing}{easing example} visually demonstrates each
+of the different easing types.
+
+\section2 Grouping Animations
+
+Multiple animations can be combined into a single animation using one of the
+animation group elements: ParallelAnimation or SequentialAnimation. As their
+names suggest, animations in a ParallelAnimation are run at the same time,
+while animations in a SequentialAnimation are run one after the other.
+
+To run multiple animations, define the animations within an animation group.
+The following example creates a SequentialAnimation that runs three animations
+one after the other: a NumberAnimation, a PauseAnimation and another
+NumberAnimation. The SequentialAnimation is applied as a \l{Animations as
+Property Value Sources}{property value source animation} on the image's \c y
+property, so that the animation starts as soon as the image is loaded, moving
+the image up and down:
+
+\snippet doc/src/snippets/declarative/animation-groups.qml 0
+\image propanim.gif
+
+Since the SequentialAnimation is applied to the \c y property, the individual
+animations within the group are automatically applied to the \c y property as
+well; it is not required to set their \l{PropertyAnimation::}{properties}
+values to a particular property.
 
-In the following snippet, we specify that we want the \c x position of \c redRect to be animated
-whenever it changes. The animation will last 300 milliseconds and use an \l{PropertyAnimation::easing.type}{Easing.InOutQuad} easing curve.
+Animation groups can be nested. Here is a rather complex animation making use
+of both sequential and parallel animations:
 
-\snippet doc/src/snippets/declarative/animation.qml behavior
+\snippet doc/src/snippets/declarative/animation-groups.qml 1
 
-Like using an animation as a value source, when used in a \l Behavior and animation does not need to specify
-a \c target or \c property.
+Once individual animations are placed into a SequentialAnimation or
+ParallelAnimation, they can no longer be started and stopped independently. The
+sequential or parallel animation must be started and stopped as a group.
 
-To trigger this behavior, we could enter a state that changes \c x:
+See the \l {declarative/animation/basics}{Animation basics example} for a
+demonstration of creating and combining multiple animations in QML.
 
-\qml
-State {
-    name: "myState"
-    PropertyChanges {
-        target: redRect
-        x: 200
-        ...
-    }
-}
-\endqml
 
-Or, update \c x from a script:
 
-\qml
-MouseArea {
-    ....
-    onClicked: redRect.x = 24;
-}
-\endqml
+\section2 Other Animation Elements
 
-If \c x were bound to another property, triggering the binding would also trigger the behavior.
+In addition, QML provides several other elements useful for animation:
 
-If a state change has a transition animation matching a property with a \l Behavior, the transition animation
-will override the \l Behavior for that state change.
+\list
+\o PauseAnimation: enables pauses during animations
+\o ScriptAction: allows JavaScript to be executed during an animation, and can
+be used together with StateChangeScript to reused existing scripts
+\o PropertyAction: changes a property \e immediately during an animation,
+without animating the property change
+\endlist
 
-The \l {declarative/animation/behaviors}{Behaviors example} shows how behaviors can be used to provide animations.
+See their respective documentation pages for more details.
 
 */
diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc
index 217e372..ce35f26 100644
--- a/doc/src/declarative/declarativeui.qdoc
+++ b/doc/src/declarative/declarativeui.qdoc
@@ -27,7 +27,7 @@
 
 /*!
 \title Qt Quick
-\page declarativeui.html
+\page qtquick.html
 
 \brief Qt Quick provides a declarative framework for building highly
 dynamic, custom user interfaces.
@@ -41,11 +41,10 @@ and netbooks. Qt Quick consists of the QtDeclarative C++ module, QML, and
 the integration of both of these into the Qt Creator IDE. Using the QtDeclarative
 C++ module, you can load and interact with QML files from your Qt application.
 
-QML is an extension to \l
-{http://www.ecma-international.org/publications/standards/Ecma-262.htm}
-{JavaScript}, that provides a mechanism to declaratively build an
-object tree of \l {QML Elements}{QML elements}.  QML improves the
-integration between JavaScript and Qt's existing QObject based type
+QML provides mechanisms to declaratively build an object tree using
+\l {QML Elements}{QML elements}. QML improves the integration between 
+\l {http://www.ecma-international.org/publications/standards/Ecma-262.htm}{JavaScript}
+and Qt's existing QObject based type
 system, adds support for automatic \l {Property Binding}{property
 bindings} and provides \l {Network Transparency}{network transparency}
 at the language level.
@@ -87,11 +86,11 @@ application or to build completely new applications.  QML is fully \l
 \o \l {qdeclarativemodules.html}{Modules}
 \o \l {Extending types from QML}
 \o \l {qdeclarativedynamicobjects.html}{Dynamic Object Creation}
-\o \l {qmlruntime.html}{The Qt Declarative Runtime}
 \endlist
 
 \section1 Using QML with C++
 \list
+\o \l {qmlruntime.html}{The Qt Declarative Runtime}
 \o \l {Using QML in C++ Applications}
 \o \l {Integrating QML with existing Qt UI code}
 \o \l {Tutorial: Writing QML extensions with C++}
diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc
index 300799c..997f601 100644
--- a/doc/src/declarative/dynamicobjects.qdoc
+++ b/doc/src/declarative/dynamicobjects.qdoc
@@ -148,17 +148,47 @@ lots of dynamically created items, however, you may receive a worthwhile
 performance benefit if unused items are deleted.
 
 Note that you should never manually delete items that were dynamically created
-by QML elements (such as \l Loader and \l Repeater). Also, you should generally avoid deleting
+by QML elements (such as \l Loader and \l Repeater). Also, you should avoid deleting
 items that you did not dynamically create yourself.
 
 Items can be deleted using the \c destroy() method. This method has an optional
 argument (which defaults to 0) that specifies the approximate delay in milliseconds
-before the object is to be destroyed. This allows you to wait until the completion of
-an animation or transition. An example:
+before the object is to be destroyed. 
 
-\snippet doc/src/snippets/declarative/dynamicObjects.qml 0
+Here is an example. The \c application.qml creates five instances of the \c SelfDestroyingRect.qml
+component. Each instance runs a NumberAnimation, and when the animation has finished, calls
+\c destroy() on its root item to destroy itself:
+
+\table
+\row
+\o \c application.qml
+\o \c SelfDestroyingRect.qml
+
+\row
+\o \snippet doc/src/snippets/declarative/dynamicObjects-destroy.qml 0
+\o \snippet doc/src/snippets/declarative/SelfDestroyingRect.qml 0
+
+\endtable
+
+Alternatively, the \c application.qml could have destroyed the created object
+by calling \c object.destroy().
+
+Notice that if a \c SelfDestroyingRect instance was created statically like this:
+
+\qml
+Item {
+    SelfDestroyingRect { ... }
+}
+\endqml
+
+This would result in an error, since items can only be dynamically 
+destroyed if they were dynamically created.
+
+Objects created with \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()}
+can similarly be destroyed using \c destroy():
+
+\snippet doc/src/snippets/declarative/createQmlObject.qml 0
+\snippet doc/src/snippets/declarative/createQmlObject.qml destroy
 
-Here, \c Rectangle objects are destroyed one second after they are created, which is long
-enough for the \c NumberAnimation to be played before the object is destroyed.
 */
 
diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc
index c2930b3..c008404 100644
--- a/doc/src/declarative/elements.qdoc
+++ b/doc/src/declarative/elements.qdoc
@@ -114,6 +114,7 @@ The following table lists the QML elements provided by the \l {QtDeclarative}{Qt
 \row \o \l {Component} \o Encapsulate QML items as a component
 \row \o \l {Timer} \o Provides timed triggers 
 \row \o \l {QML:QtObject} {QtObject} \o Basic element containing only the objectName property
+\row \o \l {QML:Qt} {Qt} \o The QML global Qt object provides useful enums and functions from Qt.
 \row \o \l {WorkerScript} \o Enables the use of threads in QML
 \row \o \l {Loader} \o Controls the loading of items or components
 \row \o \l {Repeater} \o Uses a model to create multiples of components
diff --git a/doc/src/declarative/example-slideswitch.qdoc b/doc/src/declarative/example-slideswitch.qdoc
index f056892..1a40f14 100644
--- a/doc/src/declarative/example-slideswitch.qdoc
+++ b/doc/src/declarative/example-slideswitch.qdoc
@@ -115,7 +115,7 @@ For more information on scripts see \l{Integrating JavaScript}.
 At this point, when the switch toggles between the two states the knob will instantly change its \c x position between 1 and 78.
 In order for the the knob to move smoothly we add a transition that will animate the \c x property with an easing curve for a duration of 200ms.
 
-For more information on transitions see \l{state-transitions}{QML Transitions}.
+For more information on transitions see \l{qdeclarativeanimation.html#transitions}{QML Transitions}.
 
 \section1 Usage
 The switch can be used in a QML file, like this:
diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc
index 39da323..9929cfe 100644
--- a/doc/src/declarative/examples.qdoc
+++ b/doc/src/declarative/examples.qdoc
@@ -203,6 +203,11 @@ The examples can be found in Qt's \c examples/declarative directory.
 \o \l{declarative/threading/workerscript}{WorkerScript}
 \endlist
 
+\section2 Screen orientation
+\list
+\o \l{declarative/screenorientation}{Example}
+\endlist
+
 \section2 SQL Local Storage
 \list
 \o \l{declarative/sqllocalstorage}{Example}
diff --git a/doc/src/declarative/extending-tutorial.qdoc b/doc/src/declarative/extending-tutorial.qdoc
index bc849b0..d128d0f 100644
--- a/doc/src/declarative/extending-tutorial.qdoc
+++ b/doc/src/declarative/extending-tutorial.qdoc
@@ -421,7 +421,7 @@ To create a plugin library, we need:
 \list
 \o A plugin class that registers our QML types
 \o A project file that describes the plugin 
-\o A "qmldir" file that tells the QML engine to load the plugin
+\o A \l{Writing a qmldir file}{qmldir} file that tells the QML engine to load the plugin
 \endlist
 
 First, we create a plugin class named \c ChartsPlugin. It subclasses QDeclarativeExtensionPlugin
@@ -441,8 +441,8 @@ and specifies with DESTDIR that library files should be built into a "lib" subdi
 
 \quotefile declarative/tutorials/extending/chapter6-plugins/chapter6-plugins.pro
 
-Finally, we add a \c qmldir file that is automatically parsed by the QML engine.
-Here, we specify that a plugin named "chapter6-plugin" (the name
+Finally, we add a \l{Writing a qmldir file}{qmldir} file that is automatically parsed by the QML engine.
+In this file, we specify that a plugin named "chapter6-plugin" (the name
 of the example project) can be found in the "lib" subdirectory:
 
 \quotefile declarative/tutorials/extending/chapter6-plugins/qmldir
diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc
index e3ca963..56ea165 100644
--- a/doc/src/declarative/focus.qdoc
+++ b/doc/src/declarative/focus.qdoc
@@ -266,7 +266,7 @@ When a QML item explicitly relinquishes focus (by setting its
 does not automatically select another element to receive focus.  That is, it
 is possible for there to be no currently \e {active focus}.
 
-See the {declarative/keyinteraction/focus}{Keyboard Focus example} for a 
+See the \l{declarative/keyinteraction/focus}{Keyboard Focus example} for a 
 demonstration of moving keyboard focus between multiple areas using FocusScope
 elements.
 
diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc
index 938222a..467b7d0 100644
--- a/doc/src/declarative/modules.qdoc
+++ b/doc/src/declarative/modules.qdoc
@@ -30,152 +30,285 @@
 \title Modules
 \section1 QML Modules
 
-A \bold {QML module} is a collection of QML types. They allow you to organize your QML content
-into independent units. Modules have an optional versioning mechanism that allows for independent
+
+A module is a set of QML content files that can be imported as a unit into a QML 
+application. Modules can be used to organize QML content into independent units,
+and they can use a versioning mechanism that allows for independent 
 upgradability of the modules.
 
-There are two types of modules:
-location modules (defined by a URL),
-and
-installed modules (defined by a URI).
+While QML component files within the same directory are automatically accessible
+within the global namespace, components defined elsewhere must be imported 
+explicitly using the \c import statement to import them as modules. For 
+example, an \c import statement is required to use:
+
+\list
+\o A component defined in another QML file that is not in the same directory
+\o A component defined in a QML file located on a remote server
+\o A \l{QDeclarativeExtensionPlugin}{QML C++ plugin} library (unless the plugin is installed in the same directory)
+\o A JavaScript file (note this must be imported using \l {#namespaces}{named imports})
+\endlist
+
+An \c import statement includes the module name, and possibly a version number.
+This can be seen in the snippet commonly found at the top of QML files:
+
+\qml
+    import Qt 4.7
+\endqml
+    
+This imports version 4.7 of the "Qt" module into the global namespace. (The QML 
+library itself must be imported to use any of the \l {QML Elements}, as they
+are not included in the global namespace by default.)
+
+The \c Qt module is an \e installed module; it is found in the 
+\l{The QML import path}{import path}. There are two types of QML modules: 
+location modules (defined by a URL) and installed modules (defined by a URI).
+
+
+\section1 Location Modules
+
+Location modules can reside on the local filesystem or a network resource,
+and are referred to by a quoted location URL that specifies the filesystem
+or network URL. They allow any directory with QML content to be imported
+as a module, whether the directory is on the local filesystem or a remote
+server.
+
+For example, a QML project may have a separate directory for a set of
+custom UI components. These components can be accessed by importing the
+directory using a relative or absolute path, like this:
+
+\table
+\row
+\o Directory structure
+\o Contents of application.qml
+
+\row
+\o
+\code
+MyQMLProject
+    |- MyComponents
+        |- Slider.qml
+        |- CheckBox.qml       
+    |- Main    
+        |- application.qml
+\endcode
+
+\o
+\code
+import "../MyComponents"
+
+Slider { ... }
+CheckBox { ... }
+\endcode
+
+\endtable
 
-Location modules types are defined in QML files and \l{QDeclarativeExtensionPlugin}{QML C++ plugins}
-in a directory refered to directly by
-the location URL, either on the local filesystem, or as a network resource. The URL that locates them
-can be relative, in which case they actual URL is resolved by the QML file containing the import.
-When importing a location module, a quoted URL is used:
+Similarly, if the directory resided on a network source, it could
+be imported like this:
 
 \code
-import "https://qml.nokia.com/qml/example" 1.0
-import "https://qml.nokia.com/qml/example" as NokiaExample
-import "mymodule" 1.0
-import "mymodule"
+    import "https://qml.nokia.com/qml/qmlcomponents"
+    import "https://qml.nokia.com/qml/qmlcomponents" 1.0
 \endcode
 
-Installed modules can \e only be on the local file system or in application C++ code. Again they
-are defined in QML files and \l{QDeclarativeExtensionPlugin}{QML C++ plugins} in a directory,
-but the directory is indirectly referred to by the URI. The mapping to actual content is either
-by application C++ code registering a C++ type to a module URI (see \l{Extending QML in C++}),
-or in the referenced subdirectory of a path on the import path (see below).
-When importing a location module, an un-quoted URI is used:
+Remote location modules must have a \l{Writing a qmldir file}{qmldir file} in the
+same directory to specify which QML files should be made available. See the
+\l {#qmldirexample}{example} below. The qmldir file is optional for modules on 
+the local filesystem.
+
+
+
+\section1 Installed modules
+
+
+Installed modules are modules that are installed on the
+local filesystem within the QML import path, or modules defined in C++ 
+application code. When importing an installed module, an un-quoted URI is 
+used, with a mandatory version number:
 
 \code
-import com.nokia.qml.mymodule 1.0
-import com.nokia.qml.mymodule as MyModule
+    import Qt 4.7
+    import com.nokia.qml.mymodule 1.0
 \endcode
 
+Installed modules that are installed into the import path or created
+as a \l{QDeclarativeExtensionPlugin}{QML C++ plugin} must define a 
+\l{Writing a qmldir file}{qmldir file}.
+
+
+\section2 The QML import path
 
-For either type of module, a \c qmldir file in the module directory defines the content of the module. This file is
-optional for location modules, but only for local filesystem content or a single remote content with a namespace.
-The second exception is explained in more detail in the section below on Namespaces.
+The QML engine will search the import path for a requested installed module.
+The default import path includes:
 
-\section2 The Import Path
+\list
+\o The directory of the current file
+\o The location specified by QLibraryInfo::ImportsPath 
+\o Paths specified by the \c QML_IMPORT_PATH environment variable
+\endlist
 
-Installed modules are searched for on the import path.
-The \c -I option to the \l {QML Viewer} adds paths to the import path.
+The import path can be queried using QDeclarativeEngine::importPathList() and modified using QDeclarativeEngine::addImportPath().
 
-From C++, the path is available via \l QDeclarativeEngine::importPathList() and can be prepended to
-using \l QDeclarativeEngine::addImportPath().
+When running the \l {QML Viewer}, use the \c -I option to add paths to the import path.
 
-\section2 The \c qmldir File
 
-Installed QML modules and remote content without a namespace 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:
+\section2 Creating installed modules in C++
+
+C++ applications can dynamically define installed modules using 
+qmlRegisterType(). 
+
+For \l{QDeclarativeExtensionPlugin}{QML C++ plugins}, the 
+module URI is automatically passed to QDeclarativeExtensionPlugin::registerTypes().
+The QDeclarativeExtensionPlugin documentation shows how to use this URI
+to call qmlRegisterType() to enable the plugin library to be built as
+an installed module. Once the plugin is built and installed, the module is importable
+in QML, like this:
+
+\code
+import com.nokia.TimeExample 1.0
+\endcode
+
+A \l{QDeclarativeExtensionPlugin}{QML C++ plugin} also requires a 
+\l{Writing a qmldir file}{qmldir file} to make it available to the
+QML engine.
+
+
+
+\target namespaces
+\section1 Namespaces: Using Named Imports
+
+By default, when a module is imported, its contents are imported into the global namespace. You may choose to import the module into another namespace, either to allow identically-named types to be referenced, or purely for readability.
+
+To import a module into a specific namespace, use the \e as keyword:
+
+\qml
+    import Qt 4.7 as QtLibrary
+    import "../MyComponents" as MyComponents
+    import com.nokia.qml.mymodule 1.0 as MyModule
+\endqml
+
+Types from these modules can then only be used when qualified by the namespace:
+
+\qml
+    QtLibrary.Rectangle { ... }
+    
+    MyComponents.Slider { ... }
+    
+    MyModule.SomeComponent { ... }
+\endqml
+
+Multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace:
+
+\qml
+    import Qt 4.7 as Nokia
+    import Ovi 1.0 as Nokia
+\endqml
+
+\section2 JavaScript files
+
+JavaScript files must always be imported with a named import:
+
+\qml
+    import "somescript.js" as MyScript
+    
+    Item {
+        //...
+        Component.onCompleted: MyScript.doSomething()
+    }
+\endqml
+
+
+
+\section1 Writing a qmldir file
+
+A \c qmldir file is a metadata file for a module that maps all type names in 
+the module to versioned QML files. It is required for installed modules, and 
+location modules that are loaded from a network source.
+
+It is defined by a plain text file named "qmldir" that contains one or more lines of the form:
 
 \code
 # <Comment>
 <TypeName> [<InitialVersion>] <File>
-internal <Name> <File>
+internal <TypeName> <File>
 plugin <Name> [<Path>]
 \endcode
 
-# <Comment> lines are ignored, and can be used for comments.
+\bold {# <Commment>} lines are used for comments. They are ignored by the QML engine.
 
-<TypeName> <InitialVersion> <File> lines are used to add QML files as types.
-<TypeName> is the type being made available; the optional <InitialVersion> is a version
-number like \c 4.0; <File> is the (relative)
-file name of the QML file defining the type. 
+\bold {<TypeName> [<InitialVersion>] <File>} lines are used to add QML files as types.
+<TypeName> is the type being made available, the optional <InitialVersion> is a version
+number, and <File> is the (relative) file name of the QML file defining the type. 
 
 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, but
 if the module is imported from a remote location, those files must nevertheless be listed in
 the \c qmldir file. Types which you do not wish to export to users of your module
-may be marked with the \c internal keyword: \c internal <TypeName> <File>.
+may be marked with the \c internal keyword: \bold {internal <TypeName> <File>}.
 
 The same type can be provided by different files in different versions, in which
 case later versions (eg. 1.2) must precede earlier versions (eg. 1.0),
 since the \e first name-version match is used and a request for a version of a type
 can be fulfilled by one defined in an earlier version of the module. If a user attempts
 to import a version earlier than the earliest provided or later than the latest provided,
-an error results, but if the user imports a version within the range of versions provided,
-even if no type is specific to that version, no error results.
+the import produces a runtime error, but if the user imports a version within the range of versions provided,
+even if no type is specific to that version, no error will occur.
 
 A single module, in all versions, may only be provided in a single directory (and a single \c qmldir file).
 If multiple are provided, only the first in the search path will be used (regardless of whether other versions
 are provided by directories later in the search path).
 
-Installed and remote files without a namespace \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
 provide those identifiers.
 
-\c plugin <Name> [<Path>] lines are used to add \l{QDeclarativeExtensionPlugin}{QML C++ plugins}
-to the module. 
-
-<Name> is the name of the library.  It is usually not 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. 
-By default the engine searches for the plugin library in the directory containing the \c qmldir
-file.  The \c -P option to the \l {QML Viewer} adds paths to the 
-plugin search path. 
-From C++, the path is available via \l QDeclarativeEngine::pluginPathList() and can be prepended to
-using \l QDeclarativeEngine::addPluginPath().
+\bold {plugin <Name> [<Path>]} lines are used to add \l{QDeclarativeExtensionPlugin}{QML C++ plugins} to the module. <Name> is the name of the library.  It is usually not the same as the file name
+of the plugin binary, which is platform dependent; e.g. the library \c MyAppTypes would produce
+\c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows. 
 
 <Path> is an optional argument specifying either an absolute path to the directory containing the
 plugin file, or a relative path from the directory containing the \c qmldir file to the directory 
-containing the plugin file.
-
+containing the plugin file. By default the engine searches for the plugin library in the directory that contains the \c qmldir
+file. The plugin search path can be queried with QDeclarativeEngine::pluginPathList() and modified using QDeclarativeEngine::addPluginPath(). When running the \l {QML Viewer}, use the \c -P option to add paths to the plugin search path.
 
-\section2 Namespaces - Named Imports
 
-When importing content it by default imports types into the global namespace.
-You may choose to import the module into another namespace, either to allow identically-named
-types to be referenced, or purely for readability.
+\target qmldirexample
+\section2 Example
 
-To import a module into a namespace:
+If the components in the \c MyComponents directory from the 
+\l{Location Modules}{earlier example} were to be made available as a network resource,
+the directory would need to contain a \c qmldir file similar to this:
 
 \code
-import Qt 4.7 as TheQtLibrary
+ComponentA 1.0 ComponentA.qml
+ComponentB 1.0 ComponentB.qml
 \endcode
 
-Types from the Qt 4.7 module may then be used, but only by qualifying them with the namespace:
+The \c MyComponents directory could then be imported as a module using: 
 
 \code
-TheQtLibrary.Rectangle { ... }
+import "http://the-server-name.com/MyComponents"
+
+Slider { ... }
+CheckBox { ... }
 \endcode
 
-Multiple modules can be imported into the same namespace in the same way that multiple
-modules can be imported into the global namespace:
+with an optional "1.0" version specification. Notice the import fails if
+a later version is used, as the \c qmldir file specifies that these elements
+are only available in the 1.0 version.
 
-\code
-import Qt 4.7 as Nokia
-import Ovi 1.0 as Nokia
-\endcode
 
-While import statements are needed 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
-the start of 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. This is the last location searched for types - so if you
-happen to have a "Text.qml" file, or "text.qml" on case-insensitive file systems, it will not override
-the one from Qt if you import Qt.
+For examples of \c qmldir files for plugins, see the 
+\l {declarative/cppextensions/plugins}{Plugins} example and 
+\l {Tutorial: Writing QML extensions with C++}.
 
-*/
 
-/*
+\section1 Debugging
+
+The \c QML_IMPORT_TRACE environment variable can be useful for debugging
+when there are problems with finding and loading modules. See 
+\l{Debugging module imports} for more information.
 
-Original requirement is QT-558.
 
 */
+/
diff --git a/doc/src/declarative/pics/anatomy-component.png b/doc/src/declarative/pics/anatomy-component.png
index 70ed983..6125b00 100644
--- a/doc/src/declarative/pics/anatomy-component.png
+++ b/doc/src/declarative/pics/anatomy-component.png
diff --git a/doc/src/declarative/qdeclarativedocument.qdoc b/doc/src/declarative/qdeclarativedocument.qdoc
index a2ed205..068297a 100644
--- a/doc/src/declarative/qdeclarativedocument.qdoc
+++ b/doc/src/declarative/qdeclarativedocument.qdoc
@@ -73,51 +73,61 @@ document - such as \c Rectangle and \c ListView - including those made within an
 import statements.  QML does not import any modules by default, so at least one \c import
 statement must be present or no elements will be available!
 
+Each \c id value in a QML document must be unique within that document. They
+do not need to be unique across different documents as id values are
+resolved according to the document scope.
+
+
+\section1 Documents as Component Definitions
+
 A QML document defines a single, top-level \l {QDeclarativeComponent}{QML component}.  A QML component 
 is a template that is interpreted by the QML runtime to create an object with some predefined 
 behaviour.  As it is a template, a single QML component can be "run" multiple times to 
 produce several objects, each of which are said to be \e instances of the component.  
 
 Once created, instances are not dependent on the component that created them, so they can 
-operate on independent data.  Here is an example of a simple "Button" component that is 
-instantiated four times, each with a different value for its \c text property.
+operate on independent data.  Here is an example of a simple "Button" component (defined
+in a \c Button.qml file) that is instantiated four times by \c application.qml.
+Each instance is created with a different value for its \c text property:
 
-\raw HTML
-<table><tr><td>
-\endraw
-\code
+\table
+\row
+\o Button.qml
+\o application.qml
+
+\row
+\o \snippet doc/src/snippets/declarative/qmldocuments.qml 0
+\o 
+\qml
 import Qt 4.7
 
-BorderImage {
-    property alias text: textElement.text
-    width: 100; height: 30; source: "images/toolbutton.sci"
-
-    Text {
-        id: textElement
-        anchors.centerIn: parent
-        font.pointSize: 20
-        style: Text.Raised
-        color: "white"
-    }
+Column {
+    spacing: 10
+
+    Button { text: "Apple" }
+    Button { text: "Orange" }
+    Button { text: "Pear" }
+    Button { text: "Grape" }
 }
-\endcode
-\raw HTML
-</td> <td>
-\endraw
+\endqml
+
 \image anatomy-component.png
-\raw HTML
-</td> </tr> </table>
-\endraw
+
+\endtable
 
 Any snippet of QML code can become a component, just by placing it in the file "<Name>.qml"
-where <Name> is the new element name, and begins with an uppercase letter.  Note that
+where <Name> is the new element name, and begins with an \bold uppercase letter.  Note that
 the case of all characters in the <Name> are significant on some filesystems, notably
 UNIX filesystems.  It is recommended that the case of the filename matches the case of
 the component name in QML exactly, regardless of the platform the QML will be deployed to.
 
-These QML files automatically become available as new QML element types
+These QML component files automatically become available as new QML element types
 to other QML components and applications in the same directory.
 
+
+
+\section1 Inline Components
+
 In addition to the top-level component that all QML documents define, and any reusable
 components placed in separate files, documents may also 
 include \e inline components.  Inline components are declared using the 
diff --git a/doc/src/declarative/qdeclarativei18n.qdoc b/doc/src/declarative/qdeclarativei18n.qdoc
index b6e6c6e..70a3587 100644
--- a/doc/src/declarative/qdeclarativei18n.qdoc
+++ b/doc/src/declarative/qdeclarativei18n.qdoc
@@ -80,5 +80,5 @@ qmlviewer -translation hello.qm hello.qml
 \endcode
 
 
-You can see a complete example and source code in the {declarative/i18n}{QML Internationalization example}.
+You can see a complete example and source code in the \l{declarative/i18n}{QML Internationalization example}.
 */
diff --git a/doc/src/declarative/qdeclarativeintro.qdoc b/doc/src/declarative/qdeclarativeintro.qdoc
index 75055d8..fa42f59 100644
--- a/doc/src/declarative/qdeclarativeintro.qdoc
+++ b/doc/src/declarative/qdeclarativeintro.qdoc
@@ -87,6 +87,10 @@ Rectangle { width: 100; height: 100 }
 When multiple property/value pairs are specified on a single line, they
 must be separated by a semicolon.
 
+The \c import statement imports the \c Qt \l{QML Modules}{module}, which contains all of the
+standard \l {QML Elements}. Without this import statement, the \l Rectangle
+and \l Image elements would not be available.
+
 \section1 Expressions
 
 In addition to assigning values to properties, you can also assign
@@ -181,7 +185,8 @@ Item {
 
 \section3 The \c id property
 
-Each object can be given a special unique property called an \e id. Assigning an id enables the object
+Each object can be given a special unique property called an \e id. No other object within the
+same \l{QML Documents}{QML document} can have the same \c id value. Assigning an id enables the object
 to be referred to by other objects and scripts.
 
 The first Rectangle element below has an \e id, "myRect". The second Rectange element defines its
diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc
index 6461925..274040a 100644
--- a/doc/src/declarative/qdeclarativestates.qdoc
+++ b/doc/src/declarative/qdeclarativestates.qdoc
@@ -32,57 +32,197 @@
 
 \section1 Overview
 
-QML states typically describe user interface configurations, including:
-\list
-\o What UI elements are present
-\o The properties of those elements (including how they behave)
-\o What actions are available
-\endlist
-
-A state can also be thought of as a set of batched changes from a default configuration.
-
-Examples of states in modern UI:
-\list
-\o An Address Book application with a 'View Contact' state and an 'Edit Contact' State. In the first state the contact information presented is read-only (using labels), and in the second it is editable (using editors).
-\o A button with a pressed and unpressed state. When pressed the text moves slightly down and to the right, and the button has a slightly darker appearance.
-\endlist
-
-\section1 States in QML
+User interfaces are designed to present different interface configurations in
+different scenarios, or to modify their appearances in response to user
+interaction. Often, there are a set of changes that are made concurrently, such
+that the interface could be seen to be internally changing from one \e state to
+another. 
+
+This applies generally to interface elements regardless of their complexity. 
+A photo viewer may initially present images in a grid, and when an image is
+clicked, change to a "detailed" state where the individual image is expanded
+and the interface is changed to present new options for image editing. On the
+other end of the scale, when a simple button is pressed, it may change to a
+"pressed" state in which its color and position is modified to give a pressed
+appearance.
+
+In QML, any object can change between different \e states to apply sets of
+changes that modify the properties of relevant items. Each \e state could 
+present a different configuration that could, for example:
 
-In QML:
 \list
-\o Any object can use states.
-\o There is a default state. The default state can be explicitly set.
-\o A state can affect the properties of other objects, not just the object owning the state (and not just that object's children).
+\o Show some UI elements and hide others
+\o Present different available actions to the user
+\o Start, stop or pause animations
+\o Execute some script required in the new state
+\o Change a property value for a particular item
+\o Show a different view or "screen"
 \endlist
 
-To define a state for an item, add a \l State element to the \l{Item::states}{states} property. To
-change the current state of an \l Item, set the \l{Item::state}{state} property to the name
-of the required state.
+Changes between states can be animated using \l {Transitions}{transitions}, as
+discussed further below.
 
-Here is an example of using states. In the default state \c myRect is positioned at 0,0. In the 'moved' state it is positioned at 50,50. Clicking within the mouse area changes the state from the default state to the 'moved' state, thus moving the rectangle.
+All \l {Item}-based objects have a \e {default state}, and can specify additional
+states by adding new \l State objects to the item's \l {Item::}{states}
+property. Each state has a \e name that is unique for all states within that
+item; the default state's name is an empty string. To change the current state
+of an item, set the \l {Item::}{state} property to the name of the state.
 
-\snippet doc/src/snippets/declarative/states.qml 0
-\snippet doc/src/snippets/declarative/states.qml 1
+Non-Item objects can use states through the StateGroup element.
 
-State changes can be animated using \l{state-transitions}{Transitions}.
 
-For example, adding this code to the above \c Item element animates the transition to the "moved" state:
+\section1 Creating states
 
-\snippet doc/src/snippets/declarative/states.qml transitions
+To create a state, add a \l State object to the item's \l {Item::}{states} property,
+which holds a list of states for that item.
 
-See \l{state-transitions}{Transitions} for more information.
+Following is an example. Here, the \l Rectangle is initially placed in the
+default (0, 0) position. It has defined an additional state named "moved", in
+which a PropertyChanges object repositions the rectangle to (50, 50). Clicking
+within the MouseArea changes the state to the "moved" state, thus moving the \l
+Rectangle.
 
+\snippet doc/src/snippets/declarative/states.qml 0
+ 
+The \l State item defines all the changes to be made in the new state. It
+could specify additional properties to be changed, or create additional 
+PropertyChanges for other objects. It can also modify the properties of other 
+objects, not just the object that owns the state. For example:
+
+\qml
+Rectangle {
+    ...
+    states: [
+        State {
+            name: "moved"
+            PropertyChanges { target: myRect; x: 50; y: 50; color: "blue" }
+            PropertyChanges { target: someOtherItem; width: 1000 }            
+        }
+    ]
+}
+\endqml
+
+As a convenience, if an item only has one state, its \l {Item::}{states} 
+property can be defined as a single \l State, without the square-brace list
+syntax:
+
+\qml
+Item {
+    ...
+    states: State {
+        ...
+    }
+}
+\endqml
+
+A \l State is not limited to performing modifications on property values. It 
+can also:
 
-Other things you can do in a state change:
 \list
-\o Override signal handlers with PropertyChanges
-\o Change an item's visual parent with ParentChange
-\o Change an item's anchors with AnchorChanges
-\o Run some script with StateChangeScript
+\o Run some script using StateChangeScript
+\o Override an existing signal handler for an object using PropertyChanges
+\o Re-parent an \l Item using ParentChanges
+\o Modify anchor values using AnchorChanges
 \endlist
 
-
-The {declarative/animation/states}{States and Transitions example} demonstrates how to declare a basic set of states and then apply animated transitions between them.
+The \l {declarative/animation/states}{States and Transitions example} 
+demonstrates how to declare a basic set of states and apply animated 
+transitions between them.
+
+
+\section1 The default state
+
+Of course, the \l Rectangle in the example above could have simply been moved
+by setting its position to (50, 50) in the mouse area's \c onClicked handler.
+However, aside from enabling batched property changes, one of the features of
+QML states is the ability of an item to revert to its \e {default state}.
+The default state contains all of an item's initial property values before 
+they were modified in a state change.
+
+For example, suppose the \l Rectangle should move to (50,50) when the mouse is
+pressed, and then move back to its original position when the mouse is 
+released. This can be achieved by using the \l {State::}{when} property,
+like this:
+
+\qml 
+Rectangle {
+    ...
+
+    MouseArea {
+        id: mouseArea
+        anchors.fill: parent
+    }
+
+    states: State {
+        name: "moved"; when: mouseArea.pressed
+        ...
+    }
+}
+\endqml 
+
+The \l {State::}{when} property is set to an expression that evaluates to
+\c true when the item should be set to that state. When the mouse is pressed,
+the state is changed to \e moved. When it is released, the item reverts to its
+\e default state, which defines all of the item's original property values.
+
+Alternatively, an item can be explicitly set to its default state by setting its
+\l {Item::}{state} property to an empty string (""). For example, instead of
+using the \l {State::}{when} property, the above code could be changed to:
+
+\qml 
+Rectangle {
+    ...
+
+    MouseArea {
+        anchors.fill: parent
+        onPressed: myRect.state = 'moved';
+        onReleased: myRect.state = '';
+    }
+
+    states: State {
+        name: "moved"
+        ...
+    }
+}
+\endqml 
+
+Obviously it makes sense to use the \l {State::}{when} property when possible
+as it provides a simpler (and a better, more declarative) solution than 
+assigning the state from signal handlers.
+
+
+\section1 Animating state changes
+
+
+State changes can be easily animated through \l {Transitions}{transitions}. A
+\l Transition defines the animations that should be applied when an item
+changes from one state to another.
+
+If the above example was modified to include the following \l Transition, the
+movement of the \l Rectangle would be animated:
+
+\qml
+Rectangle {
+    ...
+
+    MouseArea { ... }
+
+    states: [
+       ...
+    ]
+     
+    transitions: [
+        Transition {
+            NumberAnimation { properties: "x,y"; duration: 500 }
+        }
+    ]
+ }
+\endqml  
+
+This \l Transition defines that if any \c x or \c y properties have changed
+during a state change within this item, their values should be animated over 500
+millliseconds.
+
+See the \l Transitions documentation for more information.
 
 */
diff --git a/doc/src/declarative/qmlviewer.qdoc b/doc/src/declarative/qmlviewer.qdoc
index 5efc0ce..41c4c80 100644
--- a/doc/src/declarative/qmlviewer.qdoc
+++ b/doc/src/declarative/qmlviewer.qdoc
@@ -197,10 +197,10 @@ Rectangle {
 \o \c runtime.orientation
 
 \o This property indicates the current orientation of the QML Viewer. On the
-N900 platform, this property automatically updates to reflect the device's 
-actual orientation; on other platforms, this indicates the orientation currently
-selected in the QML Viewer's \e {Settings -> Properties} menu. The
-\c orientation value can be one of the following:
+N900 platform and most S60 5.0-based or newer Symbian devices, this property 
+automatically updates to reflect the device's actual orientation; on other platforms, 
+this indicates the orientation currently selected in the QML Viewer's 
+\e {Settings -> Properties} menu. The \c orientation value can be one of the following:
 
 \list
 \o \c Orientation.Portrait
diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc
index fb50286..b4f4c83 100644
--- a/doc/src/declarative/qtdeclarative.qdoc
+++ b/doc/src/declarative/qtdeclarative.qdoc
@@ -48,7 +48,7 @@
   \endcode
 
   For more information on the Qt Declarative module, see the
-  \l{declarativeui.html}{Qt Quick} documentation.
+  \l{Qt Quick} documentation.
 */
 
 
@@ -70,13 +70,23 @@
 
   Returns the QML type id.
 
-  Example: Register the C++ class \c MinehuntGame as the QML type
-  named \c Game for version 0.1 in the import library \c MinehuntCore:
+  For example, this registers a C++ class \c MySliderItem as a QML type
+  named \c Slider for version 1.0 of a \l{QML Modules}{module} called
+  "com.mycompany.qmlcomponents":
 
   \code
-  qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game");
+  qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider");
   \endcode
 
+  Once this is registered, the type can be used in QML by importing the 
+  specified module name and version number:
+
+  \qml
+  imoprt com.mycompany.qmlcomponents 1.0
+
+  Slider { ... }
+  \endqml
+
   Note that it's perfectly reasonable for a library to register types to older versions
   than the actual version of the library. Indeed, it is normal for the new library to allow
   QML written to previous versions to continue to work, even if more advanced versions of
diff --git a/doc/src/declarative/tutorial.qdoc b/doc/src/declarative/tutorial.qdoc
index 7a97eb1..f913d44 100644
--- a/doc/src/declarative/tutorial.qdoc
+++ b/doc/src/declarative/tutorial.qdoc
@@ -222,5 +222,5 @@ This is equivalent to writing the two transitions separately.
 The \l ParallelAnimation element makes sure that the two types of animations (number and color) start at the same time.
 We could also run them one after the other by using \l SequentialAnimation instead.
 
-For more details on states and transitions, see \l {QML States} and the {declarative/animation/states}{states and transitions example}.
+For more details on states and transitions, see \l {QML States} and the \l{declarative/animation/states}{states and transitions example}.
 */