Documentation updates

Original commit message from CVS:
Documentation updates

8 files changed, 201 insertions, 23 deletions

diff --git a/docs/manual/basics-elements.xml b/docs/manual/basics-elements.xml
index f1592df89..f691847fe 100644
--- a/docs/manual/basics-elements.xml
+++ b/docs/manual/basics-elements.xml
@@ -142,13 +142,86 @@
  element = gst_element_factory_make ("mad", "decoder");
     </programlisting>
     <para> 
-      An element can be destroyed with:  FIXME talk about refcounting
+      When you don't need the element anymore, you need to unref it, as shown in the following
+      example. 
     </para> 
     <programlisting>
  GstElement *element;
 
   ...
- gst_element_destroy (element);
+ gst_element_unref (element);
     </programlisting>
   </sect1>
+  <sect1 id="sec-elements-properties">
+    <title>GstElement properties</title>
+    <para> 
+      A GstElement can have several properties which are implemented using standard
+      GObject properties. The usual GObject methods to query, set and get property values
+      and GParamSpecs are therefore supported.
+    </para> 
+    <para> 
+      Every GstElement inherits at least one property of its parent GstObject, the "name" 
+      property. This is the name you provide to gst_element_factory_make() or 
+      gst_element_factory_create(). You can get and set this property using the
+      gst_object_set_name() and gst_object_get_name() or use the GObject property 
+      mechanism as shown below.
+    </para> 
+    <programlisting>
+ GstElement *element;
+ GValue value = { 0, }; /* initialize the GValue for g_object_get() */
+
+ element = gst_element_factory_make ("mad", "decoder");
+ g_object_set (G_OBJECT (element), "name", "mydecoder", NULL);
+ ...
+
+ g_value_init (&amp;value, G_TYPE_STRING);
+ g_object_get_property (G_OBJECT (element), "name", &amp;value);
+ ...
+    </programlisting>
+    <para> 
+      Most plugins provide additional properties to provide more information
+      about their configuration or to configure the element. 
+      <command>gst-inspect</command> is a useful tool to query the properties
+      of a perticular element, it will also use property introspection to give
+      a short explanation about the function of the property and about the
+      parameter types and ranges it supports.
+    </para> 
+    <para> 
+      For more information about GObject properties we recommend to read the GObject
+      manual.
+    </para> 
+  </sect1>
+  
+  <sect1 id="sec-elements-signals">
+    <title>GstElement signals</title>
+    <para> 
+      A GstElement also provides various GObject signals that can be used as a flexible
+      callback mechanism.
+    </para> 
+  </sect1>
+  
+  <sect1 id="sec-elements-factories">
+    <title>More about GstElementFactory</title>
+    <para> 
+      We talk some more about the GstElementFactory object.
+    </para> 
+    
+    <sect2 id="sec-elements-factories-details">
+      <title>Getting information about an element using the factory details</title>
+      <para> 
+      </para> 
+    </sect2>
+    
+    <sect2 id="sec-elements-factories-padtemplates">
+      <title>Finding out what pads an element can contain</title>
+      <para> 
+      </para> 
+    </sect2>
+    
+    <sect2 id="sec-elements-factories-query">
+      <title>Different ways of querying the factories</title>
+      <para> 
+      </para> 
+    </sect2>
+  </sect1>
 </chapter>
diff --git a/docs/manual/elements.xml b/docs/manual/elements.xml
index f1592df89..f691847fe 100644
--- a/docs/manual/elements.xml
+++ b/docs/manual/elements.xml
@@ -142,13 +142,86 @@
  element = gst_element_factory_make ("mad", "decoder");
     </programlisting>
     <para> 
-      An element can be destroyed with:  FIXME talk about refcounting
+      When you don't need the element anymore, you need to unref it, as shown in the following
+      example. 
     </para> 
     <programlisting>
  GstElement *element;
 
   ...
- gst_element_destroy (element);
+ gst_element_unref (element);
     </programlisting>
   </sect1>
+  <sect1 id="sec-elements-properties">
+    <title>GstElement properties</title>
+    <para> 
+      A GstElement can have several properties which are implemented using standard
+      GObject properties. The usual GObject methods to query, set and get property values
+      and GParamSpecs are therefore supported.
+    </para> 
+    <para> 
+      Every GstElement inherits at least one property of its parent GstObject, the "name" 
+      property. This is the name you provide to gst_element_factory_make() or 
+      gst_element_factory_create(). You can get and set this property using the
+      gst_object_set_name() and gst_object_get_name() or use the GObject property 
+      mechanism as shown below.
+    </para> 
+    <programlisting>
+ GstElement *element;
+ GValue value = { 0, }; /* initialize the GValue for g_object_get() */
+
+ element = gst_element_factory_make ("mad", "decoder");
+ g_object_set (G_OBJECT (element), "name", "mydecoder", NULL);
+ ...
+
+ g_value_init (&amp;value, G_TYPE_STRING);
+ g_object_get_property (G_OBJECT (element), "name", &amp;value);
+ ...
+    </programlisting>
+    <para> 
+      Most plugins provide additional properties to provide more information
+      about their configuration or to configure the element. 
+      <command>gst-inspect</command> is a useful tool to query the properties
+      of a perticular element, it will also use property introspection to give
+      a short explanation about the function of the property and about the
+      parameter types and ranges it supports.
+    </para> 
+    <para> 
+      For more information about GObject properties we recommend to read the GObject
+      manual.
+    </para> 
+  </sect1>
+  
+  <sect1 id="sec-elements-signals">
+    <title>GstElement signals</title>
+    <para> 
+      A GstElement also provides various GObject signals that can be used as a flexible
+      callback mechanism.
+    </para> 
+  </sect1>
+  
+  <sect1 id="sec-elements-factories">
+    <title>More about GstElementFactory</title>
+    <para> 
+      We talk some more about the GstElementFactory object.
+    </para> 
+    
+    <sect2 id="sec-elements-factories-details">
+      <title>Getting information about an element using the factory details</title>
+      <para> 
+      </para> 
+    </sect2>
+    
+    <sect2 id="sec-elements-factories-padtemplates">
+      <title>Finding out what pads an element can contain</title>
+      <para> 
+      </para> 
+    </sect2>
+    
+    <sect2 id="sec-elements-factories-query">
+      <title>Different ways of querying the factories</title>
+      <para> 
+      </para> 
+    </sect2>
+  </sect1>
 </chapter>
diff --git a/docs/manual/goals.xml b/docs/manual/goals.xml
index f699face7..5d1fc2ba6 100644
--- a/docs/manual/goals.xml
+++ b/docs/manual/goals.xml
@@ -82,14 +82,15 @@
       <itemizedlist>
         <listitem>
 	  <para>
-	    Using GLib g_mem_chunk where possible to minimize dynamic memory
-	    allocation.
+	    Using GLib g_mem_chunk and fast non-blocking allocation algorithms 
+	    where possible to minimize dynamic memory allocation.
 	  </para>
         </listitem>
         <listitem>
 	  <para>
 	    Extremely light-weight connections between plugins. Data can travel
-	    the pipeline with minimal overhead.
+	    the pipeline with minimal overhead. Data passing between plugins only involves
+	    a pointer dereference in a typical pipeline.
 	  </para>
         </listitem>
         <listitem>
@@ -108,7 +109,8 @@
         <listitem>
 	  <para>
 	    The use of cothreads to minimize the threading overhead. Cothreads are a simple and fast
-	    user-space method for switching between subtasks.
+	    user-space method for switching between subtasks. Cothreads were measured  to
+	    consume as little as 600 cpu cycles.
 	  </para>
         </listitem>
         <listitem>
@@ -123,7 +125,24 @@
 	    used.
 	  </para>
         </listitem>
+        <listitem>
+	  <para>
+	    All critical data passing is free of locks and mutexes.
+	  </para>
+        </listitem>
       </itemizedlist>
     </sect2>
+
+    <sect2 id="sec-goals-testbed">
+      <title>Provide a framework for codec experimentation</title>
+      <para>
+        GStreamer also wants to be an easy framework where codec developers 
+	can experiment with different algorithms, speeding up the development
+	of open and free multimedia codecs like tarking and vorbis.
+      </para>
+      <para> 
+      </para> 
+    </sect2>
+
   </sect1>
 </chapter>
diff --git a/docs/manual/init.xml b/docs/manual/init.xml
index bae542d74..30b90e961 100644
--- a/docs/manual/init.xml
+++ b/docs/manual/init.xml
@@ -28,16 +28,17 @@ main (int argc, char *argv[])
 }
   </programlisting>
   <para>
-    It is also possible to call the gst_init method with two NULL argumants.
+    It is also possible to call the gst_init method with two NULL arguments.
   </para>
   <para> 
     Use the GST_VERSION_MAJOR, GST_VERSION_MINOR and GST_VERSION_MICRO macros to
-    get the <application>GStreamer</application> version you are building against.
+    get the <application>GStreamer</application> version you are building against or
+    use gst_version() to get the version you are linked against.
   </para>
   <sect1>
     <title>The popt interface</title>
     <para>
-      more info here
+      You can also use a popt table to initialize your own parameters as shown in the next code fragment:
     </para>
     <programlisting>
 int
diff --git a/docs/manual/intro-motivation.xml b/docs/manual/intro-motivation.xml
index 69ea414d9..df4635b3f 100644
--- a/docs/manual/intro-motivation.xml
+++ b/docs/manual/intro-motivation.xml
@@ -56,7 +56,9 @@
       <para> 
         Your typical media player might have a plugin for different media
         types. Two media players will typically implement their own plugin
-        mechanism so that the codecs cannot be easily exchanged. 
+        mechanism so that the codecs cannot be easily exchanged. The plugin system
+	of the typical media player is also very tailored to the specific needs
+	of the application.
       </para> 
       <para> 
         The lack of a unified plugin mechanism also seriously hinders the 
@@ -67,7 +69,8 @@
         While GStreamer also uses it own plugin system it offers a very rich
 	framework for the plugin developper and ensures the plugin can be used
 	in a wide range of applications, transparently interacting with other
-	plugins.
+	plugins. The Framework that GStreamer provides for the plugins is
+	flexible enough to host even the most demanding plugins.
       </para> 
     </sect2>
 
@@ -83,9 +86,10 @@
 	the GNOME object embedding using Bonobo.
       </para> 
       <para> 
-        While the GStreamer core does not use network transparent technologies
-	at the lowest level, it shouldn't be hard to create a wrapper around the
-	core components.
+        The GStreamer cores does not use network transparent technologies at the
+	lowest level as it only adds overhead for the local case. 
+	That said, it shouldn't be hard to create a wrapper around the
+	core components. 
       </para> 
     </sect2>
 
diff --git a/docs/manual/intro-preface.xml b/docs/manual/intro-preface.xml
index 687b5cec4..9deae187b 100644
--- a/docs/manual/intro-preface.xml
+++ b/docs/manual/intro-preface.xml
@@ -27,7 +27,8 @@
       very wide variety of formats including mp3, Ogg Vorbis, Mpeg1, Mpeg2, Avi, Quicktime, mod
       and so on. 
       GStreamer, however, is much more than just another media player. Its
-      main advantages are that the pluggable components also make it possible
+      main advantages are that the pluggable components can be mixed and matched into 
+      abitrary pipelines so that it's possible
       to write a full fledged video or audio editing application. 
     </para> 
 
@@ -48,6 +49,7 @@
     <para>
       This book is about GStreamer from a developer's point of view; it describes
       how to write a GStreamer application using the GStreamer libraries and tools.
+      For an explanation about writing plugins, we suggest the Plugin Writers Guide.
     </para> 
 
   </sect1>
diff --git a/docs/manual/intro.xml b/docs/manual/intro.xml
index 687b5cec4..9deae187b 100644
--- a/docs/manual/intro.xml
+++ b/docs/manual/intro.xml
@@ -27,7 +27,8 @@
       very wide variety of formats including mp3, Ogg Vorbis, Mpeg1, Mpeg2, Avi, Quicktime, mod
       and so on. 
       GStreamer, however, is much more than just another media player. Its
-      main advantages are that the pluggable components also make it possible
+      main advantages are that the pluggable components can be mixed and matched into 
+      abitrary pipelines so that it's possible
       to write a full fledged video or audio editing application. 
     </para> 
 
@@ -48,6 +49,7 @@
     <para>
       This book is about GStreamer from a developer's point of view; it describes
       how to write a GStreamer application using the GStreamer libraries and tools.
+      For an explanation about writing plugins, we suggest the Plugin Writers Guide.
     </para> 
 
   </sect1>
diff --git a/docs/manual/motivation.xml b/docs/manual/motivation.xml
index 69ea414d9..df4635b3f 100644
--- a/docs/manual/motivation.xml
+++ b/docs/manual/motivation.xml
@@ -56,7 +56,9 @@
       <para> 
         Your typical media player might have a plugin for different media
         types. Two media players will typically implement their own plugin
-        mechanism so that the codecs cannot be easily exchanged. 
+        mechanism so that the codecs cannot be easily exchanged. The plugin system
+	of the typical media player is also very tailored to the specific needs
+	of the application.
       </para> 
       <para> 
         The lack of a unified plugin mechanism also seriously hinders the 
@@ -67,7 +69,8 @@
         While GStreamer also uses it own plugin system it offers a very rich
 	framework for the plugin developper and ensures the plugin can be used
 	in a wide range of applications, transparently interacting with other
-	plugins.
+	plugins. The Framework that GStreamer provides for the plugins is
+	flexible enough to host even the most demanding plugins.
       </para> 
     </sect2>
 
@@ -83,9 +86,10 @@
 	the GNOME object embedding using Bonobo.
       </para> 
       <para> 
-        While the GStreamer core does not use network transparent technologies
-	at the lowest level, it shouldn't be hard to create a wrapper around the
-	core components.
+        The GStreamer cores does not use network transparent technologies at the
+	lowest level as it only adds overhead for the local case. 
+	That said, it shouldn't be hard to create a wrapper around the
+	core components. 
       </para> 
     </sect2>