2 files changed, 225 insertions, 13 deletions
diff --git a/doc/src/declarative/ecmascriptblocks.qdoc b/doc/src/declarative/ecmascriptblocks.qdoc
index 4dde19d..815c68c 100644
--- a/doc/src/declarative/ecmascriptblocks.qdoc
+++ b/doc/src/declarative/ecmascriptblocks.qdoc
@@ -43,17 +43,21 @@
 \page qmlecmascript.html
 \title ECMAScript Blocks
 
-QML encourages building UIs declaratively, using \l {Property Binding} and existing 
-\l {QML Elements}.  When imperative code is required to implementing more advanced 
-behavior, the \l Script element can be used to add ECMAScript code directly to a
-QML file, or to include an external ECMAScript file.
+QML encourages building UIs declaratively, using \l {Property Binding} and the 
+composition of existing \l {QML Elements}.  If imperative code is required to implement 
+more advanced behavior, the \l Script element can be used to add ECMAScript code directly 
+to a QML file, or to include an external ECMAScript file.
 
 The \l Script element is a QML language \e intrinsic.  It can be used anywhere in a
-QML file. \e except as the root element of a file or sub-component.  The included 
-ECMAScript is evaluated in a scope chain.  The \l {QML Scope} documentation covers
-the specifics of scoping in QML.  
+QML file, \e except as the root element of a file or sub-component, but cannot be 
+assigned to an object property or given an id.  The included ECMAScript is evaluated 
+in a scope chain.  The \l {QML Scope} documentation covers the specifics of scoping 
+in QML.  
 
-\section1 Inline ECMAScript
+\section1 Inline Script
+
+Small blocks of ECMAScript can be included directly inside a \l {QML Document} as
+the body of the \l Script element.
 
 \code
 Rectangle {
@@ -69,6 +73,141 @@ Rectangle {
 }
 \endcode
 
-\section1 Including a ECMAScript File
+Good programming practice dictates that only small script snippets should be written 
+inline.  QML prohibits the declaration of anything other than functions in an inline
+script block.  For example, the following script is illegal as an inline script block 
+as it declares the non-function variable \c lastResult.
+
+\code
+// Illegal inline code block
+var lastResult = 0
+function factorial(var a) {
+    a = Integer(a);
+    if (a <= 0) 
+        lastResult = 1;
+    else 
+        lastResult = a * factorial(a - 1);
+    return lastResult;
+}
+\endcode
+
+\section1 Including an External File
+
+To avoid cluttering the QML file, large script blocks should be in a separate file.
+The \l Script element's \c source property is used to load script from an external
+file.
+
+If the previous factorial code that was illegal as an inline script block was saved
+into a "factorial.js" file, it could be included like this.
+
+\code
+Rectangle {
+    Script { 
+        source: "factorial.js"
+    }
+}
+\endcode
+
+The \c source property may reference a relative file, or an absolute path.  In the
+case of a relative file, the location is resolved relative to the location of the
+\l {QML Document} that contains the \l Script element.  If the script file is not 
+accessible, an error will occur.  If the source is on a network resource, the
+enclosing QML document will remain in the \l {QmlComponent::status()}{waiting state}
+until the script has been retrieved.
+
+\section1 Running Script at Startup
+
+It is occasionally necessary to run a block of ECMAScript code at application (or
+component instance) "startup".  While it is tempting to just include the startup
+script as \e {global code} in an external script file, this can have sever limitations
+as the QML environment may not have been fully established.  For example, some objects 
+might not have been created or some \l {Property Binding}s may not have been run.
+\l {QML Script Restrictions} covers the exact limitations of global script code.
+
+The QML \l Component element provides an \e attached \c onCompleted property that
+can be used to trigger the execution of script code at startup after the
+QML environment has been completely established.
+
+The following QML code shows how to use the \c Component::onCompleted property.
+
+\code
+Rectangle {
+    Script {
+        function startupFunction() {
+            // ... startup code
+        }
+    }
+
+    Component.onCompleted: startupFunction();
+}
+\endcode
+
+Any element in a QML file - including nested elements and nested QML component 
+instances - can use this attached property.  If there is more than one script to
+execute at startup, they are run sequentially in an undefined order.
+
+\section1 QML Script Restrictions
+
+QML \l Script blocks contain standard ECMAScript code.  QML introduces the following
+restrictions.
+
+\list
+\o Script code cannot modify the global object.
+
+In QML, the global object is constant - existing properties cannot be modified or 
+deleted, and no new properties may be created.
+
+Most ECMAScript programs do not explicitly modify the global object.  However, 
+ECMAScript's automatic creation of undeclared variables is an implicit modification
+of the global object, and is prohibited in QML.
+
+Assuming that the \c a variable does not exist in the scope chain, the following code 
+is illegal in QML.
+
+\code
+// Illegal modification of undeclared variable
+a = 1;
+for (var ii = 1; ii < 10; ++ii) a = a * ii;
+print("Result: " + a);
+\endcode
+
+It can be trivially modified to this legal code.
+
+\code
+var a = 1;
+for (var ii = 1; ii < 10; ++ii) a = a * ii;
+print("Result: " + a);
+\endcode
+
+Any attempt to modify the global object - either implicitly or explicitly - will 
+cause an exception.  If uncaught, this will result in an warning being printed, 
+that includes the file and line number of the offending code.
+
+\o Global code is run in a reduced scope
+
+During startup, if a \l Script block includes an external file with "global"
+code, it is executed in a scope that contains only the external file itself and
+the global object.  That is, it will not have access to the QML objects and 
+properties it \l {QML Scope}{normally would}.
+
+Global code that only accesses script local variable is permitted.  This is an 
+example of valid global code.
+
+\code
+var colors = [ "red", "blue", "green", "orange", "purple" ];
+\endcode
+
+Global code that accesses QML objects will not run correctly.
+
+\code
+// Invalid global code - the "rootObject" variable is undefined
+var initialPosition = { rootObject.x, rootObject.y }
+\endcode
+
+This restriction exists as the QML environment is not yet fully established.  
+To run code after the environment setup has completed, refer to 
+\l {Running Script at Startup}.
+
+\endlist
 
 */
diff --git a/doc/src/declarative/network.qdoc b/doc/src/declarative/network.qdoc
index 3d75706..da4495f 100644
--- a/doc/src/declarative/network.qdoc
+++ b/doc/src/declarative/network.qdoc
@@ -43,11 +43,84 @@
 \page qmlnetwork.html
 \title Network Transparency
 
+QML supports network transparency by using URLs (rather than file names) for all
+references from a QML document to other content. Since a \i relative URL is the same
+as a relative file, development of QML on regular file systems remains simple.
+
+\section1 Accessing Network Reesources from QML
+
+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 \c{http://example.com/mystuff/test.qml}:
+
+\code
+Image {
+    source: "images/logo.png"
+}
+\endcode
+
+The \l Image source property will be assigned \c{http://example.com/mystuff/images/logo.png},
+but while the QML is being developed, in say \c C:\User\Fred\Documents\MyStuff\test.qml, it will be assigned
+\c C:\User\Fred\Documents\MyStuff\images\logo.png.
+
+Network transparency is supported throughout QML:
+
+\list
+\o Types - if the \c test.qml file above used "Hello { }", that would refer to \c http://example.com/mystuff/Hello.qml
+\o Scripts - the \c source property of \l Script is a URL
+\o Images - the \c source property of \l Image and similar types is a URL
+\o Fonts - the \c source property of FontLoader is a URL
+\o WebViews - the \c url property of WebView may be assigned a relative URL string
+\endlist
+
+Because of the declarative nature of QML and the asynchronous nature of network resources,
+objects which reference network resource generally change state as the network resource loads.
+For example, an Image with a network source will initially have
+a \c width and \c height of 0, a \c status of \c Loading, and a \c progress of 0.0.
+While the content loads, the \c progress will increase until
+the content is fully loaded from the network,
+at which point the \c width and \c height become the content size, the \c status becomes \c Ready, and the \c progress reaches 1.0.
+Applications can bind to these changing states to provide visual progress indicators where appropriate, or simply
+bind to the \c width and \c height as if the content was a local file, adapting as those bound values change.
+
+Note that when objects reference local files they immediately have the \c Ready status, but applications wishing
+to remain network transparent should not rely on this. Future versions of QML may also use asynchronous local file I/O
+to improve performance.
+
+\section1 Limitations
+
+The \c import statement only works network transparently if it has an "as" clause.
+
 \list
-\o Documents and script blocks can be fetched transparently over the network (blocking)
-\o Images, fonts can be fetched transparently over the network (non-blocking)
-\o Configuring the network access manager
-\o Relative URL resolution from ECMAScript/QML
+\o \c{import "dir"} only works on local file systems
+\o \c{import libraryUri} only works on local file systems
+\o \c{import "dir" as D} works network transparently
+\o \c{import libraryUrl as U} works network transparently
 \endlist
 
+\section1 Configuring the Network Access Manager
+
+All network access from QML is managed by a QNetworkAccessManager set on the QmlEngine which executes the QML.
+By default, this is an unmodified Qt QNetworkAccessManager. You may set a different manager using
+QmlEngine::setNetworkAccessManager() as appropriate for the policies of your application.
+For eample, the \l qmlviewer tool sets a new QNetworkAccessManager which
+trusts HTTP Expiry headers to avoid network cache checks, allows HTTP Pipelining, adds a persistent HTTP CookieJar,
+a simple disk cache, and supports proxy settings.
+
+\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
+    QmlView *canvas = new QmlView;
+    canvas->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.
+
 */