Doc: review documentation 2D Renderer

Change-Id: Ic31014844066025a903b2d33f5780f4f8e046f72
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>

5 files changed, 60 insertions, 78 deletions

diff --git a/src/doc/config/qtquick2drenderer.qdocconf b/src/doc/config/qtquick2drenderer.qdocconf
index bf4791e6fd..e2f2e938f8 100644
--- a/src/doc/config/qtquick2drenderer.qdocconf
+++ b/src/doc/config/qtquick2drenderer.qdocconf
@@ -52,3 +52,6 @@ qhp.QtQuick2dRenderer.manual.type           = manual
 macro.RENDERER                    = "Qt Quick 2D Renderer"
 
 navigation.landingpage = "Qt Quick 2D Renderer"
+indexes = $QT_INSTALL_DOCS/qtgui/qtgui.index \
+          $QT_INSTALL_DOCS/qtquick/qtquick.index \
+          $QT_INSTALL_DOCS/qtgraphicaleffects/qtgraphicaleffects.index
diff --git a/src/doc/src/qtquick2drenderer-index.qdoc b/src/doc/src/qtquick2drenderer-index.qdoc
index b86b8dc9c2..b1c145f20e 100644
--- a/src/doc/src/qtquick2drenderer-index.qdoc
+++ b/src/doc/src/qtquick2drenderer-index.qdoc
@@ -25,10 +25,10 @@
 
     \RENDERER is an alternative renderer for Qt Quick 2 that uses the Raster
     paint engine to render the contents of the scene graph instead of OpenGL.
-    As a result of not using OpenGL to render the scene graph some features
+    As a result of not using OpenGL to render the scene graph, some features
     and optimizations are no longer available. Most Qt Quick 2 applications
     will run without modification though any attempts to use unsupported
-    features will be ignored. By using the \RENDERER is now possible to run Qt
+    features will be ignored. By using the \RENDERER it is now possible to run Qt
     Quick 2 applications on hardware and platforms that do not have OpenGL
     support.
 
diff --git a/src/doc/src/qtquick2drenderer-installation-guide.qdoc b/src/doc/src/qtquick2drenderer-installation-guide.qdoc
index 6dd2386f4d..1aff29eda2 100644
--- a/src/doc/src/qtquick2drenderer-installation-guide.qdoc
+++ b/src/doc/src/qtquick2drenderer-installation-guide.qdoc
@@ -18,62 +18,56 @@
 ****************************************************************************/
 
 /*!
-    \contentspage{index.html}{Qt Quick 2D Renderer}
     \page qtquick2drenderer-installation-guide.html
     \previouspage index.html
     \nextpage qtquick2drenderer-limitations.html
 
     \title Installation Guide
 
-    The building of \RENDERER is made complicated by the fact that Qt Quick 2
-    always requires OpenGL support regardless of whether is is being used or
+    The building of \RENDERER is complicated by the fact that Qt Quick 2
+    always requires OpenGL support regardless of whether it is being used or
     not. You will need to build Qt with support for OpenGL even if the target
-    system does not have support for using it. If you have a build of Qt that
-    already supports OpenGL you can skip to Building \RENDERER
+    system does not support it. If you have a Qt build that already supports
+    OpenGL, you can skip to \l {building-renderer}{Building \RENDERER}.
 
-    \target Providing the OpenGL Dependency
     \section1 Providing the OpenGL Dependency
 
-    The way that \RENDERER works is to render the Qt Quick 2 scene graph with
-    QPainter instead of using hardware acceleration via the OpenGL API.
+    \RENDERER works in such a way that it renders the Qt Quick 2 scene
+    graph with QPainter, instead of using hardware acceleration via the OpenGL API.
     However, Qt Quick 2 still assumes that OpenGL is always available. With
     \RENDERER we can avoid making OpenGL calls, but that does not change the
     fact that QtQuick 2 requires the OpenGL development headers to be available
     at build-time and will link against OpenGL libraries at run-time.
 
-    The solution to is to provide a dummy OpenGL library and development
-    headers to build Qt against. This way you can build Qt with virtual OpenGL
-    support and get access to the QtQuick 2 APIs. Provided you use a platform
-    plugin that does not make calls EGL or OpenGL commands, and you refrain
-    from using APIs that access OpenGL directly you should have no problems
-    using \RENDERER.
+    The solution is to provide a dummy OpenGL library and development
+    headers to build Qt against. In this way you can build Qt with virtual OpenGL
+    support and get access to the QtQuick 2 APIs. You should have no problems
+    using \RENDERER provided that you use a platform plugin that does not make calls to
+    EGL or OpenGL commands, and that you refrain from using APIs that access OpenGL directly.
 
-    \target How to use the OpenGL dummy libraries
-    \section1 How to use the OpenGL dummy libraries
+    \section1 How to use the OpenGL Dummy Libraries
 
     The OpenGL dummy libraries provide both headers and shared object files
     containing the symbols for both OpenGL and EGL. The headers get copied
-    into your INCLUDE path, and the shared object files gets copied into your LIB
+    into your INCLUDE path, and the shared object files get copied into your LIB
     path in both the sysroot, as well as in the target image distributed on the
     device. The library that is generated contains all the symbols needed to
     link an application as if you had support for OpenGL and EGL. It is important
     to make sure that you do not call any of these symbols in your application.
 
-    \target Prerequisites
     \section2 Prerequisites
 
-    You need to have three things:
+    Three elements are required:
     \list 1
-        \li Toolchain to cross compile code for your device
+        \li Toolchain to cross compile code for your device.
         \li Sysroot containing development headers and shared objects to link
-        against when building applications
-        \li Target image inteded to be deployed to your device.
+        against when building applications.
+        \li Target image intended to be deployed to your device.
     \endlist
 
-    \target How to build the OpenGL dummy libraries
-    \section2 How to build the OpengL dummy libraries
+    \section2 How to build the OpenGL Dummy Libraries
 
-    Setup your build environment by defining where your compiler and sysroot
+    Set up your build environment by defining where your compiler and sysroot
     are located:
     \badcode
     export CC=/opt/arm-toolchain/usr/bin/arm-linux-gnueabi-g++
@@ -84,9 +78,8 @@
     cd client-dummy
     ./build-gcc.sh
     \endcode
-    That should generate a two files: libEGL.so, libGLESv2.so
+    That should generate two files: \c libEGL.so, \c libGLESv2.so
 
-    \target Installation of Files
     \section2 Installation of Files
 
     Copy the include folder to the /usr/include folder in your sysroot.  This
@@ -94,19 +87,18 @@
     \badcode
     cp -r include/* ${SYSROOT}/usr/include/
     \endcode
-    Copy libEGL.so and libGLESv2.so to the /usr/lib folder in your sysroot:
+    Copy \c libEGL.so and \c libGLESv2.so to the /usr/lib folder in your sysroot:
     \badcode
     cp src/lib*.so ${SYSROOT}/usr/lib/
     \endcode
 
-    Copy the libEGL.so and libGLESv2.so libraries to the target device image as well.
+    Copy the \c libEGL.so and \c libGLESv2.so libraries to the target device image as well.
 
-    \target Building Qt
     \section1 Building Qt
 
-    When configuring Qt make sure to append -opengl es2 to your configure arguments.
+    When configuring Qt, make sure to append \c {-opengl es2} to your configure arguments.
 
-    \target Building \RENDERER
+    \target building-renderer
     \section1 Building \RENDERER
 
     Build \RENDERER like any other Qt module:
@@ -116,11 +108,10 @@
     make install
     \endcode
 
-    \target Deployment
     \section1 Deployment
 
-    Now when you deploy your Qt build to the device it will depend on the dummy
-    libs libEGL.so and libGLESv2.so, but as long as you are using the \RENDERER
+    Now, when you deploy your Qt build to the device, it will depend on the dummy
+    libs \c libEGL.so and \c libGLESv2.so, but as long as you are using the \RENDERER
     plugin you will be able to use Qt Quick 2 without actually making any
     OpenGL or EGL calls.
 
diff --git a/src/doc/src/qtquick2drenderer-limitations.qdoc b/src/doc/src/qtquick2drenderer-limitations.qdoc
index bdbc610733..3b1c84ce47 100644
--- a/src/doc/src/qtquick2drenderer-limitations.qdoc
+++ b/src/doc/src/qtquick2drenderer-limitations.qdoc
@@ -18,7 +18,6 @@
 ****************************************************************************/
 
 /*!
-    \contentspage{index.html}{Qt Quick 2D Renderer}
     \page qtquick2drenderer-limitations.html
     \previouspage qtquick2drenderer-installation-guide.html
     \nextpage qtquick2drenderer-performance.html
@@ -29,29 +28,25 @@
     out of available graphics hardware.  By not relying on OpenGL, \RENDERER
     presents certain limitations regarding the available features.
 
-    Since \RENDERER does not use OpenGL there are some features that can not be
+    Since \RENDERER does not use OpenGL, there are some features that cannot be
     supported.  The following are known limitations:
 
-    \target ShaderEffects
-    \section1 ShaderEffects
+    \section1 Shader Effects
     ShaderEffect components in QtQuick 2 can not be rendered with \RENDERER.
 
-    \target QtGraphicalEffects
-    \section1 QtGraphicalEffects
+    \section1 Qt Graphical Effects Module
     QtGraphicalEffects uses ShaderEffect items to render effects.  If you use a
-    graphical effect from QtGraphicalEffects the you should not hide the source
+    graphical effect from QtGraphicalEffects, then you should not hide the source
     item so that the original item can still be rendered.
 
-    \target Particles
-    \section1 Particles
+    \section1 Particle Effects
     It is not possible to render particle effects with \RENDERER. Whenever
-    possible, remove particles completely from the scene. Otherwise, even
-    though they are not visible with \RENDERER, a certain amount of processing
-    is done for them.
+    possible, remove particles completely from the scene. Otherwise they will still
+    require some processing, even though they are not visible with \RENDERER.
 
     \target Sprites
     \section1 Sprites
-    The Sprite item depends on OpenGL functions we dont have access to and will
+    The Sprite item depends on inaccessible OpenGL functions and will
     not be visible.
 
     \target Text
diff --git a/src/doc/src/qtquick2drenderer-performance.qdoc b/src/doc/src/qtquick2drenderer-performance.qdoc
index 3254c33e24..e6483881e9 100644
--- a/src/doc/src/qtquick2drenderer-performance.qdoc
+++ b/src/doc/src/qtquick2drenderer-performance.qdoc
@@ -24,61 +24,54 @@
 
     \title Performance Guide
 
-    Since \RENDERER does not use OpenGL we loose the ability to use many
+    Since \RENDERER does not use OpenGL, we lose the ability to use many
     optimizations that can improve rendering speed. To get the most out of
     \RENDERER there are some guidelines that should be followed.
 
-    \target 2D Hardware Acceleration
     \section1 2D Hardware Acceleration
 
     \RENDERER is designed to use operations that can be accelerated by 2D
-    acceleration hardware.  By using platform plugins that take advantage of
-    the QBlitter API (like DirectFB) is is possible to make use of such 2D
-    hardware acceleration.
+    acceleration hardware.  2D hardware acceleration uses platform plugins that take advantage of
+    the QBlitter API (like DirectFB).
 
-    \target Animation
     \section1 Animation
 
-    It is important to keep in mind the fact that with Qt Quick 2 every time
-    a node in the scene graph is marked dirty the entire window will need to be
-    rendered again. There is no partial update mechanimism that will only
-    update the regions of the window that are dirty. This means that any
-    animation that is running will be forcing a full repaint of the window and
-    with \RENDERER this can cause heavy CPU load.
+    It is important to keep in mind that with Qt Quick 2 the entire window will
+    need to be rendered every time a node in the scene graph is marked dirty.
+    There is no partial update mechanimism that will update only the dirty regions
+    of the window. This means that any animation that is running will be forcing
+    a full repaint of the window, and with \RENDERER this can cause a heavy CPU load.
 
-    \target Transforms
     \section1 Transforms
 
-    When rendering the scene graph with the OpenGL renderer transformations
-    come with no performance penality. This is not the case with \RENDERER.
-    Translation operations do not come with performance penalties but scaling
-    and rotation transformations should be avoided when possible.
+    Transformations come with no performance penalty when rendering the scene
+    graph with the OpenGL renderer. This is not the case with \RENDERER.
+    Translation operations do not come with performance penalties, but scaling
+    and rotation transformations should be avoided whenever possible.
 
-    \target Hidden Items
     \section1 Hidden Items
 
     \RENDERER will paint all items that are not hidden explicitly with either
-    the visibility property or an opacity of 0. Without OpenGL there is no
+    the visibility property or with an opacity of 0. Without OpenGL there is no
     depth buffer to check for items completely obscured by opaque items, so
-    everything will be painted even if it is unnecessary.
+    everything will be painted - even if it is unnecessary.
 
-    \target Pixel Fill Budget
     \section1 Pixel Fill Budget
 
-    When developing an application that will be using \RENDERER it is important
+    When developing an application that will be using \RENDERER, it is important
     to keep in mind your pixel fill budget, or the the amount of pixels you
     can push to the screen in the time needed for your target framerate.  For
-    example if your goal is to render your application at 60 frames per second
+    example, if your goal is to render your application at 60 frames per second,
     then you have about 16 milliseconds render to the framebuffer before
-    needing flush the pixels to screen.  Depending on your hardware's
-    performance you will only be able to handle a finite amount of pixel write
-    operations before the 16 milliseconds expires.  The interface you design
-    should take into consideration that each item that is added subtracts from
+    needing to flush the pixels to the screen.  Depending on your hardware's
+    performance, you will only be able to handle a finite amount of pixel write
+    operations before the 16 milliseconds expire.  The interface you design
+    should take into consideration that each added item subtracts from
     your pixel fill budget.
 
     \RENDERER uses the painters algorithm to paint each item in the scene
     back-to-front.  If you have an interface that stacks many items on top of
-    each other keep in mind that each layer is painted completely, not just the
+    each other, keep in mind that each layer is painted completely, not just the
     parts that are visible.  It can be very easy to waste your pixel fill
     budget with too many over-paints.