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

diff --git a/common b/common
index 0702fe1..792d198 160000 (submodule)
--- a/common
+++ b/common
@@ -1 +1 @@
-Subproject commit 0702fe19e974bc4461b5cfeb5db0e80de00a84d3
+Subproject commit 792d198f3f694e5475d1467b5ae9371a23baf7a3

diff --git a/docs/libs/Makefile.am b/docs/libs/Makefile.am
index 89e4f6d..fd060b2 100644 (file)
--- a/docs/libs/Makefile.am
+++ b/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 =

diff --git a/docs/libs/architecture.xml b/docs/libs/architecture.xml
new file mode 100644 (file)
index 0000000..41929eb
--- /dev/null
+++ b/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>

diff --git a/docs/libs/ges-docs.sgml b/docs/libs/ges-docs.sgml
index 014af1b..d4f30f9 100644 (file)
--- a/docs/libs/ges-docs.sgml
+++ b/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>

diff --git a/docs/libs/ges-sections.txt b/docs/libs/ges-sections.txt
index 5ff66c0..f45537f 100644 (file)
--- a/docs/libs/ges-sections.txt
+++ b/docs/libs/ges-sections.txt
@@ -1,8 +1,8 @@
 <INCLUDE>ges/ges.h</INCLUDE>
 
 <SECTION>
-<FILE>ges</FILE>
-<TITLE>GStreamer Editing Services</TITLE>
+<FILE>ges-common</FILE>
+<TITLE>Initialization</TITLE>
 ges_init
 </SECTION>
 

diff --git a/docs/libs/ges.types b/docs/libs/ges.types
index 8266618..b063037 100644 (file)
--- a/docs/libs/ges.types
+++ b/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

diff --git a/ges/ges.c b/ges/ges.c
index 524055b..438f885 100644 (file)
--- a/ges/ges.c
+++ b/ges/ges.c
@@ -23,7 +23,7 @@
 GST_DEBUG_CATEGORY (ges_debug);
 
 /**
- * SECTION:ges
+ * SECTION:ges-common
  * @short_description: Initialization.
  */