fixes/improvements for new QML right-to-left docs

Clarify some of the docs and fix some broken doc links.

8 files changed, 89 insertions, 64 deletions

diff --git a/doc/src/declarative/pics/layoutmirroring.png b/doc/src/declarative/pics/layoutmirroring.png
new file mode 100644
index 0000000..df90ac4
--- /dev/null
+++ b/doc/src/declarative/pics/layoutmirroring.png
diff --git a/doc/src/declarative/righttoleft.qdoc b/doc/src/declarative/righttoleft.qdoc
index 710855d..7db6136 100644
--- a/doc/src/declarative/righttoleft.qdoc
+++ b/doc/src/declarative/righttoleft.qdoc
@@ -27,7 +27,6 @@
 
 /*!
 \page qml-righttoleft.html
-\target righttoleft
 \title QML Right-to-left User Interfaces
 
 \section1 Overview
@@ -39,104 +38,114 @@ is properly aligned to the right, and horizontally ordered content in views, lis
 correctly from the right to left.
 
 In right-to-left language speaking cultures, people naturally scan and read graphic elements and text
-from the right to left. General rule of thumb is that the content like photos, videos, maps is not
-mirrored, but positioning of the content is, like application layouts and the flow of visual elements.
-Common use cases include photos shown in chronological order should flow right-to-left, the
-low end range of the horizontal sliders should be located at the right side of the slider, and the
-text lines should should be aligned to the right side of the available area. The location of visual
-elements should not be mirrored when the position is related to a content, for example when a
+from the right to left. The general rule of thumb is that content (like photos, videos and maps) is not
+mirrored, but positioning of the content (like application layouts and the flow of visual elements) is
+mirrored. For example, photos shown in chronological order should flow from right to left, the
+low end range of the horizontal sliders should be located at the right side of the slider, and
+text lines should should be aligned to the right side of the available text area. The location of visual
+elements should not be mirrored when the position is related to a content; for example, when a
 position marker is shown to indicate a location on a map. Also, there are some special cases you may
-need to take into account where the right-to-left language speakers are used to the left-to-right
+need to take into account where right-to-left language speakers are used to left-to-right
 positioning, for example when using number dialers in phones and media play, pause, rewind and
 forward buttons in music players.
 
 \section1 Text Alignment
 
-Applies to \l Text, \l TextInput and \l TextEdit.
+(This applies to the \l Text, \l TextInput and \l TextEdit elements.)
 
-When the horizontal alignment of the text item is not explicitly set, the text element will be
+When the horizontal alignment of a text item is not explicitly set, the text element is
 automatically aligned to the natural reading direction of the text. By default left-to-right text
 like English is aligned to the left side of the text area, and right-to-left text like Arabic is
 aligned to the right side of the text area. The alignment of a text element with empty text takes
-it's alignment cue from \l QApplication::keyboardInputDirection(), which is based on the active
-system locale. Explicitly setting property \c horizontalAlignment for the text will override any
-implicit locale-based alignment. Enabling layout mirroring using attached property
-\l LayoutMirroring causes any explicit left and right horizontal alignments to be mirrored.
-Note that \c horizontalAlignment property itself will remain unchanged. The effective alignment of
-the text element that takes the mirroring into account can be read from the
+its alignment cue from \l QApplication::keyboardInputDirection(), which is based on the active
+system locale.
+
+This default locale-based alignment can be overriden by setting the \c horizontalAlignment
+property for the text element, or by enabling layout mirroring using the \l LayoutMirroring attached
+property, which causes any explicit left and right horizontal alignments to be mirrored.
+Note that when \l LayoutMirroring is set, the \c horizontalAlignment property value remains unchanged;
+the effective alignment of the text element that takes the mirroring into account can be read from the
 \c effectiveHorizontalAlignment property.
 
 \snippet doc/src/snippets/declarative/righttoleft.qml 0
 
 \section1 Layout direction of positioners and views
 
-Applies to \l Row, \l Grid, \l Flow, \l ListView and \l GridView
+(This applies to the \l Row, \l Grid, \l Flow, \l ListView and \l GridView elements.)
 
-From Qt Quick 1.1 onwards horizontal positioners and model views have gained a \c layoutDirection
+From Qt Quick 1.1 onwards, elements used for horizontal positioning and model views have gained a \c layoutDirection
 property for controlling the horizontal direction of the layouts. Setting \c layoutDirection to
 \c Qt.RightToLeft causes items to be laid out from the right to left. By default Qt Quick follows
 the left-to-right layout direction.
 
-Enabling application layout mirroring using attached property \c LayoutMirroring causes the effective
-\c layoutDirection of positioners and views to be mirrored. Note that actual value of \c layoutDirection
-property will remain unchanged. The effective layout direction of positioners and views that takes the mirroring into account can be read from the \c effectiveLayoutDirection property.
+The horizontal layout direction can also be reversed through the \l LayoutMirroring attached property.
+This causes the effective \c layoutDirection of positioners and views to be mirrored. Note the actual value
+of the \c layoutDirection property will remain unchanged; the effective layout direction of positioners and
+views that takes the mirroring into account can be read from the \c effectiveLayoutDirection property.
 
 \snippet doc/src/snippets/declarative/righttoleft.qml 1
 
 \section1 Layout mirroring
 
-Attached property \l LayoutMirroring is provided as a convenience for easily implementing right-to-left
+The attached property \l LayoutMirroring is provided as a convenience for easily implementing right-to-left
 support for existing left-to-right Qt Quick applications. It mirrors the behavior of \l {anchor-layout}
 {Item anchors}, the layout direction of \l{Using QML Positioner and Repeater Items}{positioners} and
-model views and the explicit text alignment of QML text elements.
+model views, and the explicit text alignment of QML text elements.
 
-You can enable layout mirroring for a particular Item
+You can enable layout mirroring for a particular \l Item:
 
 \snippet doc/src/snippets/declarative/righttoleft.qml 2
 
-or make all children elements also inherit the layout direction
+Or set all child elements to also inherit the layout direction:
 
 \snippet doc/src/snippets/declarative/righttoleft.qml 3
 
-Mirroring does not change the return value of the layout direction and horizontal alignment properties.
-Separate read-only property \c effectiveLayoutDirection can be used to query the effective layout
-direction of positioners and model views that takes the mirroring into account. Similarly \c Text,
-\c TextInput and \c TextEdit elements have gained read-only property \c effectiveHorizontalAlignment
-for querying what is the effective visual alignment of text.
-
-\c LayoutMirroring doesn't alter application layouts and animations done by using the \l x coordinate
-directly. Adding right-to-left support to those layouts requires some code changes to your application,
-especially in views that rely on both the anchors and x coordinate-based positioning.
+Applying mirroring in this manner does not change the actual value of the relevant anchor,
+\c layoutDirection or \c horizontalAlignment properties. The separate read-only property
+\c effectiveLayoutDirection can be used to query the effective layout
+direction of positioners and model views that takes the mirroring into account. Similarly the \l Text,
+\l TextInput and \l TextEdit elements have gained the read-only property \c effectiveHorizontalAlignment
+for querying the effective visual alignment of text. For anchors, the read only
+\l {Item::anchors}{anchors.mirrored} property reflects whether anchors have been mirrored.
+
+Note that application layouts and animations that are defined using \l {Item::}{x} property values (as
+opposed to anchors or positioner elements) are not affected by the \l LayoutMirroring attached property.
+Therefore, adding right-to-left support to these types of layouts may require some code changes to your application,
+especially in views that rely on both the anchors and x coordinate-based positioning. Here is one way to use
+the \l LayoutMirroring attached property to apply mirroring to an item that is positioned using \l {Item::}{x}
+coordinates:
 
 \snippet doc/src/snippets/declarative/righttoleft.qml 4
 
-Not all the layouts should be mirrored. There are cases where the visual element is positioned to
-the right side of the screen for better one-handed use, because most people are right-handed, and not
-because of the reading direction. In the case that a child element needs to be unaffected by the mirroring, set the \c LayoutMirroring.enabled property for that element to false. Qt Quick is designed
-for developing animated, fluid user interfaces. When mirroring your application, remember to test that
-the animations and transitions continue to work as expected. If you don't have resources to add
+Not all layouts should necessarily be mirrored. There are cases where a visual element is positioned to
+the right side of the screen for improved one-handed use, because most people are right-handed, and not
+because of the reading direction. In the case that a child element should not be affected by mirroring,
+set the \l {LayoutMirroring::enabled}{LayoutMirroring.enabled} property for that element to false.
+
+Qt Quick is designed for developing animated, fluid user interfaces. When mirroring your application, remember to test that
+the animations and transitions continue to work as expected. If you do not have the resources to add
 right-to-left support for your application, it may be better to just keep the application layouts left
 aligned and just make sure that text is translated and aligned properly.
 
 \section1 Mirroring icons
 
-Applies to \l Image, \l BorderImage, \l AnimatedImage
+(This applies to \l Image, \l BorderImage and \l AnimatedImage elements.)
 
-Most images don't need mirroring, but some directional icons should be mirrored. You can mirror the
-painting of these icons with a dedicated \l mirror property introduced in Qt Quick 1.1.
+Most images do not need to be mirrored, but some directional icons, such as arrows, may need to be mirrored.
+The painting of these icons can be mirrored with a dedicated \c mirror property introduced in Qt Quick 1.1:
 
 \snippet doc/src/snippets/declarative/righttoleft.qml 5
 
 \section1 Default layout direction
 
-Property \l Qt.application.layoutDirection can be used to query the active layout direction of the
+The \l {QML:Qt::application}{Qt.application.layoutDirection} property can be used to query the active layout direction of the
 application. It is based on QApplication::layoutDirection(), which most commonly determines the layout
 direction from the active language translation file.
 
 To define the layout direction for a particular locale, declare the dedicated string literal
 \c QT_LAYOUT_DIRECTION in context \c QApplication as either "LTR" or "RTL".
 
-You can do this by first introducing line
+You can do this by first introducing this line
 
 \code
 QT_TRANSLATE_NOOP("QApplication", "QT_LAYOUT_DIRECTION");
@@ -148,7 +157,7 @@ somewhere in your QML source code and calling \c lupdate to generate the transla
 lupdate myapp.qml -ts myapp.ts
 \endcode
 
-This will append following declaration to the translation file, where you can fill either "LTR" or
+This will append the following declaration to the translation file, where you can fill in either "LTR" or
 "RTL" as the translation for the locale.
 
 \code
@@ -163,20 +172,20 @@ This will append following declaration to the translation file, where you can fi
 \endcode
 
 You can test that the layout direction works as expected by running your Qt Quick application with
-the compiled translation file.
+the compiled translation file:
 
 \code
 qmlviewer myapp.qml -translation myapp.qm
 \endcode
 
 You can test your application in right-to-left layout direction simply by executing qmlviewer with a
-command-line parameter "-reverse".
+command-line parameter "-reverse":
 
 \code
 qmlviewer myapp.qml -reverse
 \endcode
 
-Layout direction can also be set from C++ by calling static function \l QApplication::setLayoutDirection().
+The layout direction can also be set from C++ by calling the static function \l QApplication::setLayoutDirection():
 
 \code
 QApplication app(argc, argv);
diff --git a/doc/src/declarative/whatsnew.qdoc b/doc/src/declarative/whatsnew.qdoc
index 8d975c7..6eb1548 100644
--- a/doc/src/declarative/whatsnew.qdoc
+++ b/doc/src/declarative/whatsnew.qdoc
@@ -37,7 +37,7 @@ QtQuick 1.1 is a minor feature update.  \e {import QtQuick 1.1} to use the new f
 
 PinchArea provides support for the common two finger pinch gesture.
 
-\section2 LayoutMirroring
+\section2 LayoutMirroring attached property
 
 \l {LayoutMirroring}{Layout mirroring} is useful when you need to support both left-to-right and right-to-left layout versions of your application that target different language areas.
 
diff --git a/doc/src/examples/qml-examples.qdoc b/doc/src/examples/qml-examples.qdoc
index 8f34a9f..3439b09 100644
--- a/doc/src/examples/qml-examples.qdoc
+++ b/doc/src/examples/qml-examples.qdoc
@@ -278,6 +278,8 @@
     of the text and by the layout mirrroring. Click on the gray buttons
     shown at the bottom of the example to toggle between different
     horizontal alignment options.
+
+    \sa {QML Right-to-left User Interfaces}
 */
 
 /*!
@@ -290,6 +292,8 @@
     to toggle the layout direction of the shown elements.
 
     \image qml-righttoleft-layoutdirection-example.png
+
+    \sa {QML Right-to-left User Interfaces}
 */
 
 
@@ -303,6 +307,8 @@
     layout mirroring.
 
     \image qml-righttoleft-layoutmirroring-example.png
+
+    \sa {QML Right-to-left User Interfaces}
 */
 
 /*!
diff --git a/doc/src/images/qml-righttoleft-layoutdirection-example.png b/doc/src/images/qml-righttoleft-layoutdirection-example.png
index e8dd85c..381ecd7 100644
--- a/doc/src/images/qml-righttoleft-layoutdirection-example.png
+++ b/doc/src/images/qml-righttoleft-layoutdirection-example.png
diff --git a/doc/src/images/qml-righttoleft-layoutmirroring-example.png b/doc/src/images/qml-righttoleft-layoutmirroring-example.png
index 2fa82ac..992c876 100644
--- a/doc/src/images/qml-righttoleft-layoutmirroring-example.png
+++ b/doc/src/images/qml-righttoleft-layoutmirroring-example.png
diff --git a/doc/src/snippets/declarative/layoutmirroring.qml b/doc/src/snippets/declarative/layoutmirroring.qml
index 23eecd6..617f39d 100644
--- a/doc/src/snippets/declarative/layoutmirroring.qml
+++ b/doc/src/snippets/declarative/layoutmirroring.qml
@@ -43,18 +43,25 @@ import QtQuick 1.1
 Rectangle {
     LayoutMirroring.enabled: true
     LayoutMirroring.childrenInherit: true
-    width: 240; height: 50
+
+    width: 300; height: 50
+    color: "yellow"
+    border.width: 1
+
     Row {
         anchors { left: parent.left; margins: 5 }
         y: 5; spacing: 5
+
         Repeater {
             model: 5
+
             Rectangle {
                 color: "red"
-                opacity: (5-index) / 5
+                opacity: (5 - index) / 5
                 width: 40; height: 40
+
                 Text {
-                    text: index+1
+                    text: index + 1
                     anchors.centerIn: parent
                 }
             }
diff --git a/doc/src/snippets/declarative/righttoleft.qml b/doc/src/snippets/declarative/righttoleft.qml
index 5d34f50..c2e504a 100644
--- a/doc/src/snippets/declarative/righttoleft.qml
+++ b/doc/src/snippets/declarative/righttoleft.qml
@@ -44,13 +44,13 @@ import "righttoleft"
 Column {
     width: 200
 //![0]
-// aligned to the left
+// automatically aligned to the left
 Text {
     text: "Phone"
     width: 200
 }
 
-// aligned to the right
+// automatically aligned to the right
 Text {
     text: "خامل"
     width: 200
@@ -73,20 +73,20 @@ Text {
 //![0]
 
 //![1]
-// by default positions child items from the left to right
+// by default child items are positioned from left to right
 Row {
     Child {}
     Child {}
 }
 
-// positions child items from the right to left
+// position child items from right to left
 Row {
     layoutDirection: Qt.RightToLeft
     Child {}
     Child {}
 }
 
-// positions child items from the left to right
+// position child items from left to right
 Row {
     LayoutMirroring.enabled: true
     layoutDirection: Qt.RightToLeft
@@ -97,12 +97,13 @@ Row {
 
 //![2]
 Item {
-    // anchor left becomes right
     height: 50; width: 150
+
     LayoutMirroring.enabled: true
-    anchors.left: parent.left
+    anchors.left: parent.left   // anchor left becomes right
+
     Row {
-        // flows from the left to right
+        // items flow from left to right (as per default)
         Child {}
         Child {}
         Child {}
@@ -112,13 +113,15 @@ Item {
 
 //![3]
 Item {
-    // anchor left becomes right
     height: 50; width: 150
+
     LayoutMirroring.enabled: true
     LayoutMirroring.childrenInherit: true
-    anchors.left: parent.left
+    anchors.left: parent.left   // anchor left becomes right
+
     Row {
-        // flows from the right to left
+        // setting childrenInherit in the parent causes these
+        // items to flow from right to left instead
         Child {}
         Child {}
         Child {}
@@ -143,4 +146,4 @@ Image {
     mirror: true
 }
 //![5]
-}
\ No newline at end of file
+}