[grilo] Added an overview section to documentation.

[Iago Toral Quiroga <itoral src gnome org>]

commit daf099ad22db45c666fd270b1735093207b55429
Author: Iago Toral Quiroga <itoral igalia com>
Date:   Mon Apr 5 16:26:25 2010 +0200

    Added an overview section to documentation.

 doc/reference/grilo-docs.sgml |   12 ++---
 doc/reference/overview.xml    |   98 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 103 insertions(+), 7 deletions(-)
---
diff --git a/doc/reference/grilo-docs.sgml b/doc/reference/grilo-docs.sgml
index 6c27863..5fded23 100644
--- a/doc/reference/grilo-docs.sgml
+++ b/doc/reference/grilo-docs.sgml
@@ -9,17 +9,15 @@
     <title>Grilo Reference Manual</title>
     <releaseinfo>
       The latest version of this software can be found on-line at
-      <ulink role="online-location" url="http://gitorious.org/grilo";>http://gitorious.org/grilo</ulink>.
+      <ulink role="online-location" url="http://git.gnome.org/browse/grilo";>http://git.gnome.org/browse/grilo</ulink>
+      and 
+      <ulink role="online-location" url="http://git.gnome.org/browse/grilo-plugins";>http://git.gnome.org/browse/grilo-plugins</ulink>.
     </releaseinfo>
   </bookinfo>
 
   <preface>
-    <title>Introduction</title>
-    <para>Grilo is a development framework for accessing on-line multimedia
-      contents such as streaming audio/video, pictures, etc..</para>
-    <para>It will retrieve all the available meta-data associated to the
-      multimedia resource.</para>
-    <para>It's licensed as LGPL</para>
+    <title>Overview</title>
+    <xi:include href="overview.xml"/>
   </preface>
 
   <reference>
diff --git a/doc/reference/overview.xml b/doc/reference/overview.xml
new file mode 100644
index 0000000..be9f6fb
--- /dev/null
+++ b/doc/reference/overview.xml
@@ -0,0 +1,98 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+
+<section id="overview">
+
+<para>
+Modern media player applications enable users to consume content
+from various service providers, both local and on-line: Youtube,
+Jamendo, Flickr, SHOUTCast, UPnP are a few examples of this trend.
+</para>
+
+
+<para>
+Creating powerful applications that are capable of integrating all
+these services is a time consuming task that requires to invest
+a lot of effort not only in coding but also in learning about all
+these services and the particularities of each one.
+</para>
+
+
+<para>
+Unfortunately, applications that already implement support for
+some of these services do so in a way that is application-specific,
+disabling the possibility to reuse this code directly in other
+projects. This means that other applications out there have to do all
+that work again if they want to integrate the same services.
+</para>
+
+<para>
+In this context, the target of Grilo is to provide application
+developers with a framework where they can work together in the
+creation of application-independent plugins for managing media content
+that can be reused directly by applications. This model adds a number
+of important benefits:
+</para>
+
+<para><emphasis>Less work on the application side.</emphasis>
+All the plugin development happens in the framework and application
+developers can focus on making good user interfaces. It is the
+same with GStreamer if you think about it, application developers
+do not have to write decoders to playback content any more, they
+get the decoders from GStreamer (the framework) and that eases a
+lot application development. Well, this is the same idea, but applied
+to media browsing and discovery instead of media playback.
+</para>
+
+<para>
+<emphasis>Code reuse.</emphasis>
+There are many media player applications allowing users
+to access contents from various services. This is nice, but all this
+is done at the application level, which usually means that all that
+code cannot be directly reused in other projects. Because of that
+there are developers writing application specific plugins for all
+these services in various applications (Totem, Rhythmbox, Amarok,
+etc), replicating code that cannot be reused directly in other
+applications. If the plugins were developed on the framework side, all
+these developers could share efforts and write support for these
+services only once in the framework, making them available for all
+the applications using the framework for free. Every one wins.
+</para>
+
+<para>
+<emphasis>Quick learning curve.</emphasis>
+If you want to write a media player with support for various
+media content providers, you would have to learn how to deal with
+each one of them independently: want to add Youtube videos? go and
+learn about Youtube data API, want to add music from Jamendo? go and
+learn about how Jamendo allows you to do that, want to provide access
+to your local media? Go and learn how Tracker APIs work for example,
+want to access UPnP servers? then go and learn about using GUPnP,
+and so forth. This is a lot to learn, and even more code to implement.
+The framework approach would ease all this, one would have to learn
+only one API (the framework API) and that would enable application
+developers to access all these services through the framework plugins.
+</para>
+
+<para>
+Application developers will find in Grilo a framework they can use
+to gain access to a variety of media resources exposed by different
+services, all that using a single API that abstracts the differences and
+particularities of each one, easing remarkably the development of
+modern players.
+</para>
+
+<para>
+Platform developers will find in Grilo a framework where they can
+cooperate in the development of plugins for managing media content
+from various services.
+</para>
+
+<para>
+Grilo is lincesed under the GNU Lesser General Public License (LGPL).
+</para>
+
+</section>