docs: Add overview and architecture document and cleanup docs more.

common

@@ -1 +1 @@
-Subproject commit 0702fe19e974bc4461b5cfeb5db0e80de00a84d3
+Subproject commit 792d198f3f694e5475d1467b5ae9371a23baf7a3

docs/libs/Makefile.am

@@ -85,7 +85,7 @@ EXTRA_HFILES = \
 HTML_IMAGES =
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
-content_files =
+content_files = architecture.xml
 
 # Other files to distribute.
 extra_files =

docs/libs/architecture.xml

@@ -0,0 +1,128 @@
+<?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 % version-entities SYSTEM "version.entities">
+	  %version-entities;
+	  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+	  ]>
+<refentry id="ges-architecture" revision="25 mar 2009">
+  <refmeta>
+    <refentrytitle>Overview and architecture</refentrytitle>
+    <manvolnum>1</manvolnum>
+    <refmiscinfo>GStreamer Editing Services</refmiscinfo>
+  </refmeta>
+
+  <!-- <refnamediv> -->
+  <!-- <refname>Overview</refname> -->
+  <!-- <refpurpose> -->
+  <!-- Goals of the GStreamer Editing Services. -->
+  <!-- </refpurpose> -->
+  <!-- </refnamediv> -->
+
+  <refsect1>
+    <title>Goals of GStreamer Editing Services</title>
+    
+    <para>
+      The GStreamer multimedia framework and the accompanying GNonLin set
+      of plugins for non-linear editing offer all the building blocks for:
+      <itemizedlist>
+	<listitem>
+	  Decoding and encoding to a wide variety of formats, through
+	  all the available GStreamer plugins.
+	</listitem>
+	<listitem>
+	  Easily choosing segments of streams and arranging them through
+	  time through the GNonLin set of plugins.
+	</listitem>
+      </itemizedlist>
+    </para>
+
+    <para>
+      But all those building blocks only offer stream-level access,
+      which results in developers who want to write non-linear editors
+      to write a consequent amount of code to get to the level of
+      <emphasis>non-linear editing</emphasis> notions which are closer
+      and more meaningful for the end-user (and therefore the
+      application).
+    </para>
+
+    <para>
+      The GStreamer Editing Services <remark>(hereafter GES)</remark>
+      aims to fill the gap between GStreamer/GNonLin and the
+      application developer by offering a series of classes to
+      simplify the creation of many kind of editing-related
+      applications. 
+    </para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Architecture</title>
+
+    <refsect2>
+      <title>Timeline and TimelinePipeline</title>
+
+      <para>
+	The most top-level object encapsulating every other object is
+	the <link linkend="GESTimeline">GESTimeline</link>. It is the
+	central object for any editing project. 
+      </para>
+
+      <para>
+	The <classname>GESTimeline</classname> is
+	a <classname>GstElement</classname>. It can therefore be used in
+	any GStreamer pipeline like any other object.
+      </para>
+
+      <para>
+	The GESTimeline can contain two types of objects:
+	<itemizedlist>
+	  <listitem>
+	    <emphasis>Layers</emphasis> - Corresponds to the user-visible
+	    layout of non-overlapping objects. A minimalistic would
+	    only have one layer. A more complex editing application
+	    could use as many as needed.
+	  </listitem>
+	  <listitem>
+	    <emphasis>Tracks</emphasis> - Corresponds to the output
+	    stream formats. A typical GESTimeline would have a audio
+	    track and a video track. A audio editor would only require
+	    one single audio Track.
+	  </listitem>
+	</itemizedlist>
+      </para>
+
+      <para>
+	FIXME : INSERT DIAGRAM
+      </para>
+
+      <para>
+	In order to reduce even more the amount of GStreamer
+	interaction the application developer has to deal with , a
+	convenience GstPipeline has been made available specifically
+	for Timelines
+	:  <link linkend="GESTimelinePipeline">GESTimelinePipeline</link>.
+      </para>
+    </refsect2>
+
+
+    <refsect2>
+      <title>Timeline layers</title>
+
+      <para>
+	The layers are the end-user visible part of GES.
+      </para>
+    </refsect2>
+
+    <refsect2>
+      <title>Timeline Tracks</title>
+
+      <para>
+	The tracks are the GStreamer-level components of a
+	Timeline. They are a 1-to-1 relationship to the output
+	streams. 
+      </para>
+    </refsect2>
+  </refsect1>
+
+</refentry>

docs/libs/ges-docs.sgml

@@ -27,21 +27,22 @@ applications.
 platform as well as Windows. It is released under the GNU Library General Public License
 (GNU LGPL).
     </para>
-  <xi:include href="xml/ges.xml"/>
+  <xi:include href="architecture.xml"/>
+  <xi:include href="xml/ges-common.xml"/>
   </chapter>
 
   <chapter>
     <title>Base Classes</title>
-    <xi:include href="xml/ges-track.xml"/>
-    <xi:include href="xml/ges-track-object.xml"/>
-    <xi:include href="xml/ges-track-source.xml"/>
-    <xi:include href="xml/ges-track-filesource.xml"/>
     <xi:include href="xml/ges-timeline.xml"/>
     <xi:include href="xml/ges-timeline-layer.xml"/>
     <xi:include href="xml/ges-timeline-object.xml"/>
     <xi:include href="xml/ges-timeline-source.xml"/>
     <xi:include href="xml/ges-timeline-filesource.xml"/>
     <xi:include href="xml/ges-timeline-transition.xml"/>
+    <xi:include href="xml/ges-track.xml"/>
+    <xi:include href="xml/ges-track-object.xml"/>
+    <xi:include href="xml/ges-track-source.xml"/>
+    <xi:include href="xml/ges-track-filesource.xml"/>
   </chapter>
 
   <chapter>

docs/libs/ges-sections.txt

@@ -1,8 +1,8 @@
 <INCLUDE>ges/ges.h</INCLUDE>
 
 <SECTION>
-<FILE>ges</FILE>
+<FILE>ges-common</FILE>
-<TITLE>GStreamer Editing Services</TITLE>
+<TITLE>Initialization</TITLE>
 ges_init
 </SECTION>
 

docs/libs/ges.types

@@ -1,3 +1,6 @@
+#include <gst/gst.h>
+#include <ges/ges.h>
+
 ges_track_get_type
 ges_track_type_get_type
 ges_track_object_get_type

ges/ges.c

@@ -23,7 +23,7 @@
 GST_DEBUG_CATEGORY (ges_debug);
 
 /**
- * SECTION:ges
+ * SECTION:ges-common
  * @short_description: Initialization.
  */