docs: Add a Richer README.md file

Add features, communication & contribution, build information,
and usage of Geoclue.

Fixes #108

1 files changed, 63 insertions, 5 deletions

diff --git a/README.md b/README.md
index edf7456..a1e4361 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,74 @@
 Geoclue: The Geoinformation Service
 ===================================
 
-Geoclue is a D-Bus geoinformation service. The goal of the Geoclue project is to
-make creating location-aware applications as simple as possible.
+Geoclue is a D-Bus geoinformation service. The goal of the Geoclue project
+is to make creating location-aware applications as simple as possible.
 
 Geoclue is Free Software, licensed under GNU GPLv2+.
 
-# Troubleshooting and known limitations
+Geoclue comprises the following functionalities : 
+- WiFi-based geolocation (accuracy: in meters)
+- GPS(A) receivers (accuracy: in centimeters)
+- GPS of other devices on the local network, e.g smartphones (accuracy: 
+  in centimeters)
+- 3G modems (accuracy: in kilometers, unless modem has GPS)
+- GeoIP (accuracy: city-level)
 
-  * Geoclue requires glib >= 2.44.0, which is not available on Ubuntu 14.04.
+WiFi-based geolocation makes use of 
+[Mozilla Location Service](https://wiki.mozilla.org/CloudServices/Location). 
 
+If geoclue is unable to find you, you can easily fix that by installing 
+and running a 
+[simple app](https://wiki.mozilla.org/CloudServices/Location#Contributing) on 
+your phone. For using phone GPS, you'll need to install the latest version of 
+[GeoclueShare app](https://github.com/ankitstarski/GeoclueShare/releases)
+on your phone (currently, this is supported only on Android devices).
+
+Geoclue was also used for (reverse-)geocoding but that functionality has 
+been dropped in favour of the 
+[geocode-glib library](http://ftp.gnome.org/pub/GNOME/sources/geocode-glib/).
+
+# History
+Geoclue was started during the GNOME Summit 2006 in Boston. At least 
+Keith Preston and Tuomas Kuosmanen can be blamed. There was a total rewrite 
+after version 0.9. 
+
+Use tag "0.9" (as in git checkout 0.9) if you need the old code.
+
+There was yet another rewrite that we call geoclue2. The first version to 
+introduce the re-write was version 1.99.
+
+# Communication and Contribution
+
+- Discussions take place on the 
+[mailing list](http://lists.freedesktop.org/mailman/listinfo/geoclue).
+- The IRC chat for geoclue is on __#gnome-maps__ at irc.gimp.org .
+- Issues are tracked on 
+[Gitlab](https://gitlab.freedesktop.org/geoclue/geoclue/issues).
+
+# Get Source Code
+The source code is available as a tar-ball and in a Git repository.
+
+For latest release tarballs, use the `Download` option of Gitlab on the 
+[tag of your choice](https://gitlab.freedesktop.org/geoclue/geoclue/tags/).
+
+Older (than 2.4.13) releases are available 
+[here](http://www.freedesktop.org/software/geoclue/releases/2.4/).
+
+Git repository for Geoclue: https://gitlab.freedesktop.org/geoclue/geoclue
+  
 # Building Geoclue
 
-Refer to [Hacking.md](HACKING.md)
+The guidelines for building geoclue have been documented 
+[here](https://gitlab.freedesktop.org/geoclue/geoclue/blob/master/HACKING.md). 
 
+# Using Geoclue in an application
+ 
+- __D-Bus API__: The documentation for using geoclue with D-Bus API is 
+[here](http://www.freedesktop.org/software/geoclue/docs/).
+- __Libgeoclue API documentation__:  The documentation is available 
+[here](https://www.freedesktop.org/software/geoclue/docs/libgeoclue/).
+- __C user application__: 
+[Here](https://gitlab.freedesktop.org/geoclue/geoclue/blob/master/demo/where-am-i.c)
+is an example showing a C application that uses 
+geoclue to locate its user. 
\ No newline at end of file