Split QtLocation into QtPositioning and QtLocation

QtPositioning is not dependent on any gui component and mostly
covers everything around the retrieval of position information.

QtLocation covers place, map and navigation APIs.

Several documentation issues were fixed during the process.

Change-Id: I98e2a53065549a2fc43f93a75b4f65b5bc884c92
Reviewed-by: Alex Blasche <alexander.blasche@digia.com>

10 files changed, 943 insertions, 0 deletions

diff --git a/src/positioning/doc/src/cpp-position.qdoc b/src/positioning/doc/src/cpp-position.qdoc
new file mode 100644
index 00000000..75c2e30e
--- /dev/null
+++ b/src/positioning/doc/src/cpp-position.qdoc
@@ -0,0 +1,191 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page location-positioning-cpp.html
+
+\title Positioning (C++)
+
+\brief The Location Positioning API enables location positioning by means of
+GPS or an NMEA data source.
+
+\section1 Positioning
+
+The Positioning component of the Qt Location API is about the geographical position, size
+and address of some place. Positioning contains a QGeoCoordinate class, containing latitude, longitude and altitude in meters. QGeoLocation contains a QGeoCoordinate plus address
+and size information (a bounding box) so that positions can be more than mathematical points.
+Movement into or out of the defined bounding box areas can be monitored. The API
+also allows the developer to control the source of the positional information
+as well.
+
+Location data involves a precisely specified position on the Earth's
+surface \unicode {0x2014} as provided by a latitude-longitude coordinate
+\unicode {0x2014} along with associated data, such as:
+
+    \list
+    \li The date and time at which the position was reported
+    \li The velocity of the device that reported the position
+    \li The altitude of the reported position (height above sea level)
+    \li The bearing of the device in degrees, relative to true north
+    \endlist
+
+This data can be extracted through a variety of methods. One of the most
+well known methods of positioning is GPS (Global Positioning System), a
+publicly available system that uses radiowave signals received from
+Earth-orbiting satellites to calculate the precise position and time of
+the receiver. Another popular method is 'Cell Identifier Positioning', which uses
+the cell identifier of the cell site that is currently serving the receiving
+device to calculate its approximate location. These and other positioning
+methods can all be used with the Location API; the only requirement for a
+location data source within the API is that it provides a
+latitude-longitude coordinate with a date/time value, with the option of
+providing the other attributes listed above.
+
+
+Location data sources are created by subclassing QGeoPositionInfoSource and
+providing QGeoPositionInfo objects through the
+QGeoPositionInfoSource::positionUpdated() signal. Clients that require
+location data can connect to the
+\l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal and
+call \l{QGeoPositionInfoSource::startUpdates()}{startUpdates()} or
+\l{QGeoPositionInfoSource::requestUpdate()}{requestUpdate()} to trigger the
+distribution of location data. The location data distribution can be stopped by
+calling the \l {QGeoPositionInfoSource::stopUpdates()}{stopUpdates()} function.
+
+A default position source may be available on some platforms. Call
+QGeoPositionInfoSource::createDefaultSource() to create an instance of the default
+position source; the method returns 0 if no default source is available for
+the platform.
+
+If a problem occurs with access to the information source then an
+\l {QGeoPositionInfoSource::error()}{error()} signal is emitted.
+
+The QGeoAreaMonitor class enables client applications to be notified when
+the receiving device has moved in or out of a particular area, as specified
+by a coordinate and radius. If the platform provides built-in support for
+area monitoring, QGeoAreaMonitor::createDefaultMonitor() returns an instance of
+the default area monitor.
+
+Satellite information can also be distributed through the
+QGeoSatelliteInfoSource class. Call QGeoSatelliteInfoSource::createDefaultSource() to
+create an instance of the default satellite data source for the platform,
+if one is available. Alternatively, clients can subclass it to provide a
+custom satellite data source.
+
+
+
+\section2 Requesting Location Data from Data Sources
+
+To receive data from a source, connect to its
+\l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal,
+then call either \l{QGeoPositionInfoSource::startUpdates()}{startUpdates()}
+or \l{QGeoPositionInfoSource::requestUpdate()}{requestUpdate()} to begin.
+
+Here is an example of a client that receives data from the default location
+data source, as returned by QGeoPositionInfoSource::createDefaultSource():
+
+\code
+class MyClass : public QObject
+{
+    Q_OBJECT
+public:
+    MyClass(QObject *parent = 0)
+        : QObject(parent)
+    {
+        QGeoPositionInfoSource *source = QGeoPositionInfoSource::createDefaultSource(this);
+        if (source) {
+            connect(source, SIGNAL(positionUpdated(QGeoPositionInfo)),
+                    this, SLOT(positionUpdated(QGeoPositionInfo)));
+            source->startUpdates();
+        }
+    }
+
+private slots:
+    void positionUpdated(const QGeoPositionInfo &info)
+    {
+        qDebug() << "Position updated:" << info;
+    }
+};
+
+\endcode
+
+\section2 Controlling Aspects of Data Sources
+
+The QGeoPositionInfoSource::setUpdateInterval() method can be used to
+control the rate at which position updates are received. For example, if
+the client application only requires updates once every 30 seconds, it can
+call \c setUpdateInterval(30000). (If no update interval is set, or
+\l {QGeoPositionInfoSource::}{setUpdateInterval()} is called with a value of 0, the source uses a default
+interval or some other internal logic to determine when updates should be
+provided.)
+
+QGeoPositionInfoSource::setPreferredPositioningMethods() enables client
+applications to request that a certain type of positioning method be used.
+For example, if the application prefers to use only satellite positioning,
+which offers fairly precise outdoor positioning but can be a heavy user of
+power resources, it can call this method with the
+QGeoPositionInfoSource::SatellitePositioningMethods value. However, this
+method should only be used in specialized client applications; in most
+cases, the default positioning methods should not be changed, as a source
+may internally use a variety of positioning methods that can be useful to
+the application.
+
+\section2 NMEA Data
+
+\l {http://en.wikipedia.org/wiki/NMEA_0183}{NMEA} is a common text-based
+protocol for specifying navigational data. For convenience, the
+QNmeaPositionInfoSource is provided to enable client applications to read
+and distribute NMEA data in either real-time mode (for example, when
+streaming from a GPS device) or simulation mode (for example, when reading
+from a NMEA log file). In simulation mode, the source will emit updates
+according to the time stamp of each NMEA sentence to produce a "replay"
+of the recorded data.
+
+Generally, the capabilities provided by the default position source as
+returned by QGeoPositionInfoSource::createDefaultSource(), along with the
+QNmeaPositionInfoSource class, are sufficient for retrieving location
+data. However, in some cases developers may wish to write their own custom
+location data source.
+
+The \l {Log File Position Source (C++)} example demonstrates how to subclass QGeoPositionInfoSource
+to create a custom positioning source.
+
+
+\section1 Examples
+
+\section3 \b{Flickr Example}
+
+The \l{Flickr QML}{Flickr Example} uses the Location to download thumbnail
+images from Flickr relevant to the current location.
+
+
+
+\section1 Positioning Classes
+
+\annotatedlist QtPositioning-positioning
+
+*/
diff --git a/src/positioning/doc/src/cpp-qml-positioning.qdoc b/src/positioning/doc/src/cpp-qml-positioning.qdoc
new file mode 100644
index 00000000..4ccd8510
--- /dev/null
+++ b/src/positioning/doc/src/cpp-qml-positioning.qdoc
@@ -0,0 +1,55 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page positioning-cpp-qml.html
+\title Interfaces between C++ and QML Code in Qt Positioning
+
+\brief Some of the providing QtPositioning QML types providing interfaces to access and modify properties in C++.
+
+\section2 Address - QGeoAddress
+\target geoaddress
+The \l {QtPositioning5::Address::address} {Address.address} property is used to provide an interface between C++ and QML code.  First a pointer to a
+Address object must be obtained from C++, then use the \l {QObject::property()}{property()} and
+\l {QObject::setProperty()}{setProperty()} functions to get and set the \c address property.
+The following gets the QGeoAddress representing this object from C++:
+\snippet cpp/cppqml.cpp Address get
+The following sets the properties of this object based on a QGeoAddress object from C++:
+\snippet cpp/cppqml.cpp Address set
+
+
+\section2 Location - QGeoLocation
+\target location
+The \l {Location::location} {Location.location} property is used to provide an interface between C++ and QML code.  First a pointer to a
+Location object must be obtained from C++, then use the \l {QObject::property()}{property()} and
+\l {QObject::setProperty()}{setProperty()} functions to get and set the \c location property.
+The following gets the QGeoLocation representing this object from C++:
+\snippet cpp/cppqml.cpp Location get
+The following sets the properties of this object based on a QGeoLocation object from C++:
+\snippet cpp/cppqml.cpp Location set
+
+*/
diff --git a/src/positioning/doc/src/examples/declarative-flickr.qdoc b/src/positioning/doc/src/examples/declarative-flickr.qdoc
new file mode 100644
index 00000000..c68797b0
--- /dev/null
+++ b/src/positioning/doc/src/examples/declarative-flickr.qdoc
@@ -0,0 +1,85 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example declarative/flickr
+    \title Flickr (QML)
+    \ingroup qtpositioning-examples
+
+    \brief The Flickr example shows how to use the user's current position to
+           fetch local content from a web service.
+
+    This is a small example, illustrating one of the very core parts of the
+    Qt Positioning API: the ability to retrieve and use the user's current
+    geographic position.
+
+    Key QML types shown in this example:
+    \list
+        \li \l{QtPositioning5::PositionSource}{PositionSource}
+        \li \l{XmlListModel}{XmlListModel}
+    \endlist
+
+    \image  qml-flickr-1.jpg
+
+    \section2 Retrieving the Current Position
+
+    Retrieving the user's current position is achieved using the PositionSource
+    type. In this example, we instantiate the PositionSource as part of the
+    GeoTab component (the floating "window" describing current position and
+    status).
+
+    \snippet flickr/flickrmobile/GeoTab.qml possrc
+
+    When the "Locate and update" button is pressed, we first interrogate the
+    PositionSource to check if it has an available backend for positioning
+    data. If it does not, we fall back to using a pre-recorded NMEA log
+    for demonstration. We then instruct the PositionSource to update.
+
+    \snippet flickr/flickrmobile/GeoTab.qml locatebutton-top
+    \snippet flickr/flickrmobile/GeoTab.qml locatebutton-clicked
+
+    To share the new position data with the rest of the application, we use
+    properties that we have created on the GeoTab component:
+
+    \snippet flickr/flickrmobile/GeoTab.qml props
+
+    \section2 Using the Current Position
+
+    The longitude and latitude values retrieved here are eventually set on
+    in properties on the RestModel component. The RestModel is an XmlListModel,
+    which retrieves XML data from a URL and creates a data model by performing
+    XPath queries on it.
+
+    In this case, it retrieves data from the Flickr REST API online, based on
+    our current position
+
+    \snippet flickr/flickrcommon/RestModel.qml restmodel
+
+    This model data is then shown in a variety of Qt Quick views to produce
+    the example application.
+
+*/
diff --git a/src/positioning/doc/src/examples/logfilepositionsource.qdoc b/src/positioning/doc/src/examples/logfilepositionsource.qdoc
new file mode 100644
index 00000000..f69c1dd1
--- /dev/null
+++ b/src/positioning/doc/src/examples/logfilepositionsource.qdoc
@@ -0,0 +1,87 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\example logfilepositionsource
+\title Log File Position Source (C++)
+\ingroup qtpositioning-examples
+
+\brief The Logfile Position Source shows how to create and work with a custom NMEA position source,
+       for platforms without GPS.
+
+The data is read from a file which has positional data in NMEA format. The resulting time and
+position information is then displayed to the screen as simple text in date/time and
+latitude/longitude format.
+
+This example class reads position data from a text file, \e log.txt. The file specifies position
+data using a simple text format: it contains one position update per line, where each line contains
+a date/time, a latitude and a longitude, separated by spaces. The date/time is in ISO 8601 format
+and the latitude and longitude are in degrees decimal format. Here is an excerpt from \e log.txt:
+
+\code
+2009-08-24T22:25:01 -27.576082 153.092415
+2009-08-24T22:25:02 -27.576223 153.092530
+2009-08-24T22:25:03 -27.576364 153.092648
+\endcode
+
+The class reads this data and distributes it via the
+\l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal.
+
+Here is the definition of the \c LogFilePositionSource class:
+
+\quotefromfile logfilepositionsource/logfilepositionsource.h
+\skipto class LogFilePositionSource
+\printuntil };
+
+The main methods overrided by the subclass are:
+
+\list
+    \li \l{QGeoPositionInfoSource::startUpdates()}{startUpdates()}: called by client applications
+        to start regular position updates.
+    \li \l{QGeoPositionInfoSource::stopUpdates()}{stopUpdates()}: called by client applications to
+        stop regular position updates.
+    \li \l{QGeoPositionInfoSource::requestUpdate()}{requestUpdate()}: called by client applications
+        to request a single update, with a specified timeout.
+\endlist
+
+When a position update is available, the subclass emits the
+\l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal.
+
+Here are the key methods in the class implementation:
+
+\quotefromfile logfilepositionsource/logfilepositionsource.cpp
+\skipto LogFilePositionSource::LogFilePositionSource
+\printuntil /^\}/
+\skipto LogFilePositionSource::startUpdates
+\printuntil /^\}/
+\skipto LogFilePositionSource::stopUpdates
+\printuntil /^\}/
+\skipto LogFilePositionSource::requestUpdate
+\printuntil /^\}/
+\printuntil LogFilePositionSource::readNextPosition
+\printuntil /^\}/
+*/
diff --git a/src/positioning/doc/src/examples/qtpositioning-examples.qdoc b/src/positioning/doc/src/examples/qtpositioning-examples.qdoc
new file mode 100644
index 00000000..ac1d79ec
--- /dev/null
+++ b/src/positioning/doc/src/examples/qtpositioning-examples.qdoc
@@ -0,0 +1,38 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \group qtpositioning-examples
+    \title Qt Positioning Examples
+    \brief Examples for the Qt Positioning module
+    \ingroup all-examples
+    \ingroup qtpositioning
+
+    These are the Qt Positioning examples.
+
+*/
+
diff --git a/src/positioning/doc/src/examples/weatherinfo.qdoc b/src/positioning/doc/src/examples/weatherinfo.qdoc
new file mode 100644
index 00000000..0c98cc04
--- /dev/null
+++ b/src/positioning/doc/src/examples/weatherinfo.qdoc
@@ -0,0 +1,109 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example weatherinfo
+    \title Weather Info (C++/QML)
+
+    \brief The Weather Info example shows how to use the user's current position
+           to retrieve local content from a web service in a C++ plugin for QML.
+
+    \ingroup qtpositioning-examples
+
+    Key Qt Positioning classes used in this example:
+
+    \list
+    \li \l{QGeoPositionInfo}
+    \li \l{QGeoPositionInfoSource}
+    \endlist
+
+    \image ../images/example-weatherinfo.png
+
+    The key part of this example is the application's data model, contained
+    in the WeatherData and AppModel classes. WeatherData represents the weather
+    information taken from the HTTP service. It is a simple data class, but we
+    give it Q_PROPERTies to expose it nicely to QML, later.
+
+    \snippet weatherinfo/appmodel.h 0
+    \snippet weatherinfo/appmodel.h 1
+
+    AppModel models the state of the entire application. At startup, the
+    application first begins by waiting for network connectivity. We do
+    this using the QNetworkConfigurationManager and QNetworkSession family
+    of C++ APIs.
+
+    \snippet weatherinfo/appmodel.cpp 0
+    \snippet weatherinfo/appmodel.cpp 1
+
+    Once the network session is open, we proceed to get the platform's
+    default position source using QGeoPositionInfo::createDefaultSource()
+
+    \snippet weatherinfo/appmodel.cpp 2
+
+    If no default source is available, we take a static position and fetch
+    weather for that. If, however, we do have a position source, we connect
+    its positionUpdated() signal to a slot on the AppModel and call
+    startUpdates(), which begins regular updates of device position.
+
+    When a position update is received, we use the longitude and latitude
+    of the returned coordinate to retrieve the current "city" name for use
+    in the weather lookup.
+
+    \snippet weatherinfo/appmodel.cpp 3
+
+    To inform the UI about this process, the cityChanged() signal is emitted
+    when a new city is used, and the weatherChanged() signal whenever a
+    weather update occurs.
+
+    \snippet weatherinfo/appmodel.h 2
+    \snippet weatherinfo/appmodel.h 3
+    \snippet weatherinfo/appmodel.h 4
+
+    We use a QQmlListProperty for the weather forecast information,
+    which contains the next 4 days of forecast weather. This makes it
+    easy to access from QML.
+
+    To expose these to the QML UI layer, we use the qmlRegisterType()
+    function. We call this once for each type we wish to register, before
+    loading the actual QML file.
+
+    \snippet weatherinfo/main.cpp 0
+    \snippet weatherinfo/main.cpp 1
+
+    Finally, in the actual QML, we instantiate the AppModel.
+
+    \snippet weatherinfo/weatherinfo.qml 0
+    \snippet weatherinfo/weatherinfo.qml 1
+    \snippet weatherinfo/weatherinfo.qml 2
+
+    Once instantiated like this, we can use its properties elsewhere in the
+    QML document:
+
+    \snippet weatherinfo/weatherinfo.qml 3
+    \snippet weatherinfo/weatherinfo.qml 4
+
+*/
diff --git a/src/positioning/doc/src/qml-position.qdoc b/src/positioning/doc/src/qml-position.qdoc
new file mode 100644
index 00000000..850bdd35
--- /dev/null
+++ b/src/positioning/doc/src/qml-position.qdoc
@@ -0,0 +1,107 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page location-positioning-qml.html
+
+\title Positioning (QML)
+
+\brief The Location Positioning API enables location positioning by means of
+GPS or an NMEA data source.
+
+\section1 Location Positioning
+
+Location data involves a precisely specified position on the Earth's
+surface \unicode {0x2014} as provided by a latitude-longitude coordinate
+\unicode {0x2014} along with associated data, such as:
+
+    \list
+    \li The date and time at which the position was reported
+    \li The velocity of the device that reported the position
+    \li The altitude of the reported position (height above sea level)
+    \li The bearing of the device in degrees, relative to true north
+    \endlist
+
+For more information see
+\l {http://en.wikipedia.org/wiki/Geographic_coordinate}{Geographic Coordinate}.
+
+This data can be extracted through a variety of methods. One of the most
+well known methods of positioning is GPS (Global Positioning System), a
+publicly available system that uses radiowave signals received from
+Earth-orbiting satellites to calculate the precise position and time of
+the receiver. Another popular method is 'Cell Identifier Positioning', which uses
+the cell identifier of the cell site that is currently serving the receiving
+device to calculate its approximate location. These and other positioning
+methods can all be used with the Location API; the only requirement for a
+location data source within the API is that it provides a
+latitude-longitude coordinate with a date/time value, with the option of
+providing the other attributes listed above.
+
+\section2 Coordinate
+
+The \l {coordinate} is a basic unit of geographical information. The
+\l {coordinate} type has attributes to hold the \c {latitude},
+\c longitude and \c altitude.
+
+\section2 Position
+
+The three dimensional position of an object such as a mobile device can be specified by giving
+the latitude, longitude and altitude.  That is the values held in the
+l\ {coordinate} type.  Additionally for computation of future
+positions we would like to know if the object is moving, what \l {Position::speed}{speed} it is
+doing and what is the \l {Position::timestamp}{timestamp} of the last position data.  Position
+therefore includes values for the \l {Position::coordinate}{coordinate},
+\l {Position::speed}{speed} and a \l {Position::timestamp}{timestamp}.  \l Position also takes
+responsibility for validation of sensible values for these properties.  These are exposed as
+the \l {Position::latitudeValid}{latitudeValid}, \l {Position::longitudeValid}{longitudeValid},
+\l {Position::altitudeValid}{altitudeValid}, \l {Position::speedValid}{speedValid},
+\l {Position::horizontalAccuracyValid}{horizontalAccuracyValid}, and
+\l {Position::verticalAccuracyValid}{verticalAccuracyValid} properties.
+
+
+\section2 PositionSource
+
+We have a Position type, a \l {coordinate} type but where does the data come from?
+Also it is a good idea to be able to indicate alternative sources.
+Perhaps instead of directly picking up GPS satellites it might be desirable to do
+some testing using a datafile.
+
+The \l PositionSource type provides the developer with control,
+within the limits allowed by the platform, of the source of the
+geographical data. Apart from tradtional sources such as GPS and cell data the positional data can be
+sourced from a logfile which is in NMEA format.
+
+\l {http://en.wikipedia.org/wiki/NMEA}{NMEA} is a common text-based protocol for specifying navigational data. For convenience, the \l {PositionSource::nmeaSource}{nmeaSource} property is provided to enable QML applications to read NMEA data from a log file, the source will emit updates according to the time stamp of each NMEA sentence to produce a "replay" of the recorded data.
+
+
+
+\section2 \b{Flickr Example}
+
+The \l{Flickr (QML)}{Flickr Example} uses the Location to download thumbnail
+images from Flickr relevant to the current location.
+
+*/
diff --git a/src/positioning/doc/src/qtpositioning-plugins.qdoc b/src/positioning/doc/src/qtpositioning-plugins.qdoc
new file mode 100644
index 00000000..1ed1be1a
--- /dev/null
+++ b/src/positioning/doc/src/qtpositioning-plugins.qdoc
@@ -0,0 +1,82 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qtpositioning-plugins.html
+\title Qt Positioning service plugins
+\brief Implementing Qt Positioning plugins
+
+Qt Positioning provides the majority of its functionality through plugins. This
+document outlines how to develop a new position plugin.
+
+\section1 Plugin description
+
+Each plugin is described by a json file. The json describes the plugins capabilities and
+version. Below is an example of a json file used by the postionpoll plugin:
+
+\quotefile ../../../plugins/position/positionpoll/plugin.json
+
+The entries have the following meaning:
+
+\table
+    \header
+        \li Key
+        \li Description
+    \row
+        \li Keys
+        \li The unique name/key of the plugin. Each position plugin must have a unique name.
+    \row
+        \li Provider
+        \li The provider name of the services. Multiple plugins may have the same name.
+            In such cases the Version string will be used to further distinguish the plugins.
+    \row
+        \li Position
+        \li Set to \c true if the plugin implements a \l QGeoPositionInfoSource.
+    \row
+        \li Satellite
+        \li Set to \c true if the plugin implements a \l QGeoSatelliteInfoSource.
+    \row
+        \li Monitor
+        \li Set to \c true if the plugin implements a \l QGeoAreaMonitor.
+    \row
+        \li Priority
+        \li The plugin priority. If multiple plugins have the same provider name, the plugin
+            with the higest priority will be used.
+\endtable
+
+\section1 Implementing Plugins
+
+A plugin implementer needs to subclass \l QGeoPositionInfoSourceFactory and override one or more of
+its functions. If a plugin does not support a specific feature the function should return 0 or
+utilize the default implementation.
+
+\list
+    \li \l QGeoPositionInfoSourceFactory::areaMonitor()
+    \li \l QGeoPositionInfoSourceFactory::positionInfoSource()
+    \li \l QGeoPositionInfoSourceFactory::satelliteInfoSource()
+\endlist
+*/
diff --git a/src/positioning/doc/src/qtpositioning-qml.qdoc b/src/positioning/doc/src/qtpositioning-qml.qdoc
new file mode 100644
index 00000000..ba35cb89
--- /dev/null
+++ b/src/positioning/doc/src/qtpositioning-qml.qdoc
@@ -0,0 +1,65 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \qmlmodule QtPositioning 5.0
+    \title Qt Positioning QML Types
+    \ingroup qmlmodules
+    \brief Provides QML types for position information
+
+\section1 Overview
+
+The identifying string for this module is \e QtPositioning. To use include the following import
+statement in the QML file.
+
+\snippet doc_src_qtpositioning.qml import
+
+\section2 Positioning QML Concepts
+
+Position information can come from a variety of sources including satellites,
+wifi, text files and so on. The position is described by the latitude,
+the longitude, and the altitude in meters. For more information see
+\l {http://en.wikipedia.org/wiki/Geographic_coordinate}{Geographic Coordinate}.
+
+The QML position is stored in a \l {coordinate} which contains the
+latitude, longitude and altitude of the device.  The \l {QtPositioning5::Location}{Location} contains
+this \l {coordinate} and adds an address, it also has a bounding box which
+defines the recommended viewing region when displaying the location.
+
+Now that the device has a position, with regular updates the API can determine
+the speed and heading of the device. It can also define a box or a circle that can
+produce a notification when the device either leaves or enters that region.
+
+More detailed information retrieving the current position can be found under
+{Positioning (QML)}{Location Positioning via QML}
+
+\section1 Basic Types
+
+\annotatedlist qml-QtPositioning5-basictypes
+
+\section1 Alphabetical Listing of all QML Types
+*/
diff --git a/src/positioning/doc/src/qtpositioning.qdoc b/src/positioning/doc/src/qtpositioning.qdoc
new file mode 100644
index 00000000..95b3fecc
--- /dev/null
+++ b/src/positioning/doc/src/qtpositioning.qdoc
@@ -0,0 +1,124 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+
+
+
+/*!
+    \module QtPositioning
+    \title Qt Positioning C++ Classes
+    \ingroup modules
+    \qtvariable location
+
+    \brief The Positioning module provides positioning information via QML and C++ interfaces.
+
+    To load the Qt Positioning module, add the following statement to your .qml files
+
+    \code
+        import QtPositioning 5.0
+    \endcode
+
+    For C++ projects include the header appropriate for the current use case,
+    for example applications using routes may use
+
+    \code #include <QGeoCoordinate> \endcode
+
+    The .pro file should have the \e positioning keyword added
+
+    \code QT += positioning \endcode
+
+
+    See more in the \l{Qt Positioning}{Qt Positioning Overview}.
+
+*/
+
+
+
+/*!
+\page qtpositioning-index.html
+\title Qt Positioning
+\brief The Qt Positioning API provides positioning information via QML and C++ interfaces.
+\ingroup technology-apis
+
+The Qt Positioning API provides positioning information via QML and C++ interfaces.
+
+\section1 Overview
+
+The Qt Positioning API gives developers the ability to determine a position by
+using a variety of possible sources, including satellite, or wifi, or text file,
+and so on. That information can then be used to for example determine a position
+on a map. In addition satellite information can be retrieved and area based monitoring
+can be performed.
+
+\section1 Getting Started
+
+To load the Qt Positioning module, add the following statement to your .qml files
+
+\code
+    import QtPositioning 5.0
+\endcode
+
+For C++ projects include the header appropriate for the current use case,
+for example applications using routes may use
+
+\code #include <QGeoCoordinate> \endcode
+
+The .pro file should have the \e positioning keyword added
+
+\code QT += positioning \endcode
+
+\section1 Related information
+\section2 Overview
+
+Positioning includes all the functionality necessary to find and work with geographic
+coordinates. It can use a variety of external sources of information, including GPS. This
+provides us with a coordinate and altitude for the device with additional features
+such as speed and direction. This provides the fundamental location information used in the API.
+
+\section2 References
+\table
+\row
+    \li Positioning introduction:
+    \li \l{Positioning (QML)}{for QML}
+    \li \l{Positioning (C++)}{for C++}
+\row
+    \li API references:
+    \li \l {Qt Positioning QML Types}{for QML}
+    \li \l {Qt Positioning C++ Classes}{for C++}
+\row
+    \li Position plugins:
+    \li \l {Qt Positioning service plugins}
+\endtable
+
+\section2 Examples
+
+\list
+    \li \l {Flickr (QML)}
+    \li \l {Log File Position Source (C++)}
+    \li \l {Weather Info (C++/QML)}
+\endlist
+*/