docs/manual/advanced-dparams.xml: describe controller

Original commit message from CVS:
* docs/manual/advanced-dparams.xml:
describe controller
* docs/manual/advanced-position.xml:
* docs/manual/basics-init.xml:
* docs/manual/manual.xml:
* docs/manual/titlepage.xml:
* docs/pwg/pwg.xml:
* docs/pwg/titlepage.xml:
cleanup xml (more to come)
* libs/gst/controller/gstcontroller.c:
fix typo

9 files changed, 278 insertions, 341 deletions

diff --git a/ChangeLog b/ChangeLog
index ba4507c53f..e701debbd6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2006-01-30  Stefan Kost  <ensonic@users.sf.net>
+
+	* docs/manual/advanced-dparams.xml:
+          describe controller
+	* docs/manual/advanced-position.xml:
+	* docs/manual/basics-init.xml:
+	* docs/manual/manual.xml:
+	* docs/manual/titlepage.xml:
+	* docs/pwg/pwg.xml:
+	* docs/pwg/titlepage.xml:
+          cleanup xml (more to come)
+	* libs/gst/controller/gstcontroller.c:
+          fix typo
+
 2006-01-30  Sebastien Moutte  <sebastien@moutte.net>
 	
 	* win32/vs6/grammar.dsp:
diff --git a/docs/manual/advanced-dparams.xml b/docs/manual/advanced-dparams.xml
index 577b02172b..fc88098144 100644
--- a/docs/manual/advanced-dparams.xml
+++ b/docs/manual/advanced-dparams.xml
@@ -1,198 +1,81 @@
 <chapter id="chapter-dparams">
-  <title>Dynamic Parameters</title>
+  <title>Dynamic Controllable Parameters</title>
   
   <sect1 id="section-dparams-getting-started">
     <title>Getting Started</title>
     <para>
-      The Dynamic Parameters subsystem is contained within the
+    The controller subsystem offers a lightweight way to adjust gobject
+    properties over stream-time.
+    It works by using time-stamped value pairs that are queued for
+    element-properties.
+    At run-time the elements continously pull values changes for the
+    current stream-time.
+    </para>
+    <para>
+      This subsystem is contained within the
       <filename>gstcontrol</filename> library.
-
       You need to include the header in your application's source file:
     </para>
     <programlisting>
 ...
 #include &lt;gst/gst.h&gt;
-#include &lt;gst/control/control.h&gt;
+#include &lt;gst/controller/gstcontroller.h&gt;
 ...
     </programlisting>
     <para>
-      Your application should link to the shared library <filename>gstcontrol</filename>.
+      Your application should link to the shared library <filename>gstreamer-controller</filename>.
     </para>
     <para>
-      The <filename>gstcontrol</filename> library needs to be initialized
+      The <filename>gstreamer-controller</filename> library needs to be initialized
       when your application is run.  This can be done after the the GStreamer
       library has been initialized.
     </para>
     <programlisting>
   ...
   gst_init(&amp;argc,&amp;argv);
-  gst_control_init(&amp;argc,&amp;argv);
+  gst_controller_init(&amp;argc,&amp;argv);
   ...
     </programlisting>
   </sect1>
-
-  <sect1 id="section-dparams-creating">
-    <title>Creating and Attaching Dynamic Parameters</title>
-    <para>
-      Once you have created your elements you can create and attach dparams to them.
-      First you need to get the element's dparams manager. If you know exactly what kind of element
-      you have, you may be able to get the dparams manager directly. However if this is not possible, 
-      you can get the dparams manager by calling <filename>gst_dpman_get_manager</filename>.
-    </para>
+  
+  <sect1 id="section-dparams-parameters">
+    <title>Setting up parameters</title>
     <para>
-      Once you have the dparams manager, you must set the mode that the manager will run in.
-      There is currently only one mode implemented called <filename>"synchronous"</filename> - this is used for real-time
-      applications where the dparam value cannot be known ahead of time (such as a slider in a GUI).
-      The mode is called <filename>"synchronous"</filename> because the dparams are polled by the element for changes before
-      each buffer is processed.  Another yet-to-be-implemented mode is <filename>"asynchronous"</filename>.  This is used when
-      parameter changes are known ahead of time - such as with a timelined editor.  The mode is called 
-      <filename>"asynchronous"</filename> because parameter changes may happen in the middle of a buffer being processed.
+      It makes not sense for all GObject parameter to be real-time controlled.
+      Therefore the first step is to mark controllable parameters.
     </para>
     <programlisting>
-  GstElement *audiotestsrc;
-  GstDParamManager *dpman;
-  ...
-  audiotestsrc = gst_element_factory_make("audiotestsrc", NULL);
-  ...
-  dpman = gst_dpman_get_manager (audiotestsrc);
-  gst_dpman_set_mode(dpman, "synchronous");
+  controller = g_object_control_properties(object, "prop1", "prop2",...);
     </programlisting>
     <para>
-      If you don't know the names of the required dparams for your element you can call 
-      <filename>gst_dpman_list_dparam_specs(dpman)</filename> to get a NULL terminated array of param specs.
-      This array should be freed after use.  You can find the name of the required dparam by calling
-      <filename>g_param_spec_get_name</filename> on each param spec in the array. In our example, 
-      <filename>"volume"</filename> will be the name of our required dparam.
-    </para>
-    <para>
-      Each type of dparam currently has its own <filename>new</filename> function. This may eventually
-      be replaced by a factory method for creating new instances.  A default dparam instance can be created
-      with the <filename>gst_dparam_new</filename> function. Once it is created it can be attached to a 
-      required dparam in the element.
+      Next we can select an interpolation mode. This mode controls how inbetween
+      values are determined.
+      The controller subsystem can e.g. fill gaps by smoothing parameter changes.
+      Each controllable GObject property can be
+      interpolated differently.      
     </para>
     <programlisting>
-  GstDParam *volume;
-  ...
-  volume = gst_dparam_new(G_TYPE_DOUBLE);
-  if (gst_dpman_attach_dparam (dpman, "volume", volume)){
-    /* the dparam was successfully attached */
-    ...
-  }
+  gst_controller_set_interpolation_mode(controller,"prop1",mode);
     </programlisting>
-  </sect1>
-
-  <sect1 id="section-dparams-changing">
-    <title>Changing Dynamic Parameter Values</title>
     <para>
-      All interaction with dparams to actually set the dparam value is done through simple GObject properties.
-      There is a property value for each type that dparams supports - these currently being 
-      <filename>"value_double"</filename>, <filename>"value_float"</filename>, <filename>"value_int"</filename> and <filename>"value_int64"</filename>.
-      To set the value of a dparam, simply set the property which matches the type of your dparam instance.
+      Finally one needs to set control points. These are time-stamped GValues.
+      The values become active when the timestamp is reached. They still stay
+      in the list. If e.g. the pipeline runs a loop (using a segmented seek),
+      the control-curve gets repeated as well. 
     </para>
     <programlisting>
-#define ZERO(mem) memset(&amp;mem, 0, sizeof(mem))
-...
-
-  gdouble set_to_value;
-  GstDParam *volume;
-  GValue set_val;
-  ZERO(set_val);
-  g_value_init(&amp;set_val, G_TYPE_DOUBLE);
-  ...
-  g_value_set_double(&amp;set_val, set_to_value);
-  g_object_set_property(G_OBJECT(volume), "value_double", &amp;set_val);
-    </programlisting>
-    <para>Or if you create an actual GValue instance:</para>
-    <programlisting>
-  gdouble set_to_value;
-  GstDParam *volume;
-  GValue *set_val;
-  set_val = g_new0(GValue,1);
-  g_value_init(set_val, G_TYPE_DOUBLE);
-  ...
-  g_value_set_double(set_val, set_to_value);
-  g_object_set_property(G_OBJECT(volume), "value_double", set_val);
+  gst_controller_set (controller, "prop1" ,0 * GST_SECOND, value1);
+  gst_controller_set (controller, "prop1" ,1 * GST_SECOND, value2);
     </programlisting>
-
-  </sect1>
-
-  <sect1 id="section-dparams-types">
-    <title>Different Types of Dynamic Parameter</title>
     <para>
-      There are currently only two implementations of dparams so far.  They are both for real-time use so 
-      should be run in the <filename>"synchronous"</filename> mode.
+      The controller subsystem has a builtin live-mode. Even though a parameter
+      has timestamped control-values assigned one can change the GObject
+      property through <function>g_object_set()</function>.
+      This is highly useful when binding the GObject properties to GUI widgets.
+      When the user adjusts the value with the widget, one can set the GOBject
+      property and this remains active until the next timestamped value overrides.
+      This also works with smoothed parameters.  
     </para>
-    <sect2>
-      <title>GstDParam - the base dparam type</title>
-      <para>
-        All dparam implementations will subclass from this type.  It provides a basic implementation which simply 
-        propagates any value changes as soon as it can.  
-        A new instance can be created with the function <filename>GstDParam* gst_dparam_new (GType type)</filename>.
-        It has the following object properties:
-      </para>
-      <itemizedlist>
-        <listitem><para><filename>"value_double"</filename>
-          - the property to set and get if it is a double dparam
-        </para></listitem>
-        <listitem><para><filename>"value_float"</filename>
-          - the property to set and get if it is a float dparam
-        </para></listitem>
-        <listitem><para><filename>"value_int"</filename>
-          - the property to set and get if it is an integer dparam
-        </para></listitem>
-        <listitem><para><filename>"value_int64"</filename>
-          - the property to set and get if it is a 64 bit integer dparam
-        </para></listitem>
-        <listitem><para><filename>"is_log"</filename>
-          - readonly boolean which is TRUE if the param should be displayed on a log scale
-        </para></listitem>
-        <listitem><para><filename>"is_rate"</filename>
-          - readonly boolean which is TRUE if the value is a proportion of the sample rate.  
-          For example with a sample rate of 44100, 0.5 would be 22050 Hz and 0.25 would be 11025 Hz.
-        </para></listitem>
-      </itemizedlist>
-    </sect2>
-    <sect2>
-      <title>GstDParamSmooth - smoothing real-time dparam</title>
-      <para>
-        Some parameter changes can create audible artifacts if they change too rapidly.  The GstDParamSmooth
-        implementation can greatly reduce these artifacts by limiting the rate at which the value can change.
-        This is currently only supported for double and float dparams - the other types fall back to the default implementation.
-        A new instance can be created with the function <filename>GstDParam* gst_dpsmooth_new (GType type)</filename>.
-        It has the following object properties:
-      </para>
-      <itemizedlist>
-        <listitem><para><filename>"update_period"</filename>
-          - an int64 value specifying the number nanoseconds between updates. This will be ignored in 
-          <filename>"synchronous"</filename> mode since the buffer size dictates the update period.
-        </para></listitem>
-        <listitem><para><filename>"slope_time"</filename>
-          - an int64 value specifying the time period to use in the maximum slope calculation
-        </para></listitem>
-        <listitem><para><filename>"slope_delta_double"</filename>
-          - a double specifying the amount a double value can change in the given slope_time.
-        </para></listitem>
-        <listitem><para><filename>"slope_delta_float"</filename>
-          - a float specifying the amount a float value can change in the given slope_time.
-        </para></listitem>
-      </itemizedlist>
-      <para>
-        Audible artifacts may not be completely eliminated by using this dparam. The only way to eliminate
-        artifacts such as "zipper noise" would be for the element to implement its required dparams using the 
-        array method. This would allow dparams to change parameters at the sample rate which should eliminate
-        any artifacts.
-      </para>
-      
-    </sect2>
-    <sect2>
-      <title>Timelined dparams</title>
-      <para>
-        A yet-to-be-implemented subclass of GstDParam will add an API which allows the creation and manipulation
-        of points on a timeline. This subclass will also provide a dparam implementation which uses linear
-        interpolation between these points to find the dparam value at any given time. Further subclasses can 
-        extend this functionality to implement more exotic interpolation algorithms such as splines.
-      </para>
-    </sect2>
   </sect1>
   
 </chapter>
diff --git a/docs/manual/advanced-position.xml b/docs/manual/advanced-position.xml
index f072840e68..7bab808c8e 100644
--- a/docs/manual/advanced-position.xml
+++ b/docs/manual/advanced-position.xml
@@ -39,7 +39,8 @@
       source itself.
     </para>
 
-    <programlisting><!-- example-begin query.c a -->
+    <programlisting>
+<!-- example-begin query.c a -->
 #include &lt;gst/gst.h&gt;
 <!-- example-end query.c a -->
 <!-- example-begin query.c b --><!--
@@ -71,7 +72,8 @@ my_bus_message_cb (GstBus     *bus,
       break;
   }
 }
---><!-- example-end query.c b -->
+-->
+<!-- example-end query.c b -->
 <!-- example-begin query.c c -->
 static gboolean
 cb_print_position (GstElement *pipeline)
diff --git a/docs/manual/basics-init.xml b/docs/manual/basics-init.xml
index 2d048a9ec9..125cbca055 100644
--- a/docs/manual/basics-init.xml
+++ b/docs/manual/basics-init.xml
@@ -20,7 +20,9 @@
       A typical program &EXAFOOT; would have code to initialize
       &GStreamer; that looks like this:
     </para>
-    <programlisting>
+    <example id="ex-init-c">
+      <title>Initializing GStreamer</title>
+      <programlisting>
 <!-- example-begin init.c -->
 #include &lt;gst/gst.h&gt;
 
@@ -39,7 +41,8 @@ main (int   argc,
   return 0;
 }
 <!-- example-end init.c -->
-    </programlisting>
+      </programlisting>
+    </example>
     <para>
       Use the <symbol>GST_VERSION_MAJOR</symbol>,
       <symbol>GST_VERSION_MINOR</symbol> and <symbol>GST_VERSION_MICRO</symbol>
@@ -62,7 +65,9 @@ main (int   argc,
       You can also use a GOption table to initialize your own parameters as
       shown in the next example:
     </para>
-    <programlisting>
+    <example id="ex-goption-c">
+      <title>Initialisation using the GOption interface</title>
+      <programlisting>
 <!-- example-begin goption.c -->
 #include &lt;gst/gst.h&gt;
 
@@ -96,7 +101,8 @@ main (int   argc,
   return 0;
 }
 <!-- example-end goption.c -->
-    </programlisting>
+      </programlisting>
+    </example>
     <para>
       As shown in this fragment, you can use a <ulink
       url="http://developer.gnome.org/doc/API/2.0/glib/glib-Commandline-option-parser.html"
diff --git a/docs/manual/manual.xml b/docs/manual/manual.xml
index 1fc7e500cb..aba084981b 100644
--- a/docs/manual/manual.xml
+++ b/docs/manual/manual.xml
@@ -18,102 +18,50 @@
 </footnote>
 ">
 
+<!ENTITY TITLEPAGE            SYSTEM "titlepage.xml">
+
 <!-- Part 1: Overview -->
-<!ENTITY INTRO SYSTEM "intro-preface.xml">
-<!ENTITY MOTIVATION SYSTEM "intro-motivation.xml">
-<!ENTITY CONCEPTS SYSTEM "intro-basics.xml">
+<!ENTITY INTRO                SYSTEM "intro-preface.xml">
+<!ENTITY MOTIVATION           SYSTEM "intro-motivation.xml">
+<!ENTITY CONCEPTS             SYSTEM "intro-basics.xml">
 
 <!-- Part 2: Basic Concepts -->
-<!ENTITY INIT SYSTEM "basics-init.xml">
-<!ENTITY ELEMENTS SYSTEM "basics-elements.xml">
-<!ENTITY BINS SYSTEM "basics-bins.xml">
-<!ENTITY BUS SYSTEM "basics-bus.xml">
-<!ENTITY PADS SYSTEM "basics-pads.xml">
-<!ENTITY DATA SYSTEM "basics-data.xml">
-<!ENTITY HELLOWORLD SYSTEM "basics-helloworld.xml">
+<!ENTITY INIT                 SYSTEM "basics-init.xml">
+<!ENTITY ELEMENTS             SYSTEM "basics-elements.xml">
+<!ENTITY BINS                 SYSTEM "basics-bins.xml">
+<!ENTITY BUS                  SYSTEM "basics-bus.xml">
+<!ENTITY PADS                 SYSTEM "basics-pads.xml">
+<!ENTITY DATA                 SYSTEM "basics-data.xml">
+<!ENTITY HELLOWORLD           SYSTEM "basics-helloworld.xml">
 
 <!-- Part 3: Advanced Concepts -->
-<!ENTITY QUERYEVENTS SYSTEM "advanced-position.xml">
-<!ENTITY METADATA SYSTEM "advanced-metadata.xml">
-<!ENTITY INTERFACES SYSTEM "advanced-interfaces.xml">
-<!ENTITY CLOCKS SYSTEM "advanced-clocks.xml">
-<!ENTITY DPARAMS SYSTEM "advanced-dparams.xml">
-<!ENTITY THREADS SYSTEM "advanced-threads.xml">
-<!ENTITY AUTOPLUGGING SYSTEM "advanced-autoplugging.xml">
-<!ENTITY DATAACCESS SYSTEM "advanced-dataaccess.xml">
+<!ENTITY QUERYEVENTS          SYSTEM "advanced-position.xml">
+<!ENTITY METADATA             SYSTEM "advanced-metadata.xml">
+<!ENTITY INTERFACES           SYSTEM "advanced-interfaces.xml">
+<!ENTITY CLOCKS               SYSTEM "advanced-clocks.xml">
+<!ENTITY DPARAMS              SYSTEM "advanced-dparams.xml">
+<!ENTITY THREADS              SYSTEM "advanced-threads.xml">
+<!ENTITY AUTOPLUGGING         SYSTEM "advanced-autoplugging.xml">
+<!ENTITY DATAACCESS           SYSTEM "advanced-dataaccess.xml">
 
 <!-- Part 4: Higher-level interfaces -->
-<!ENTITY XML SYSTEM "highlevel-xml.xml">
-<!ENTITY COMPONENTS SYSTEM "highlevel-components.xml">
+<!ENTITY XML                  SYSTEM "highlevel-xml.xml">
+<!ENTITY COMPONENTS           SYSTEM "highlevel-components.xml">
 
 <!-- Appendices -->
-<!ENTITY CHECKLIST SYSTEM "appendix-checklist.xml">
-<!ENTITY PORTING SYSTEM "appendix-porting.xml">
-<!ENTITY INTEGRATION SYSTEM "appendix-integration.xml">
-<!ENTITY LICENSING SYSTEM "appendix-licensing.xml">
-<!ENTITY WIN32 SYSTEM "appendix-win32.xml">
-<!ENTITY QUOTES SYSTEM "appendix-quotes.xml">
+<!ENTITY CHECKLIST            SYSTEM "appendix-checklist.xml">
+<!ENTITY PORTING              SYSTEM "appendix-porting.xml">
+<!ENTITY INTEGRATION          SYSTEM "appendix-integration.xml">
+<!ENTITY LICENSING            SYSTEM "appendix-licensing.xml">
+<!ENTITY WIN32                SYSTEM "appendix-win32.xml">
+<!ENTITY QUOTES               SYSTEM "appendix-quotes.xml">
 
 <!ENTITY GStreamer    "<application>GStreamer</application>">
 ]>
 
 <book id="index">
-  <bookinfo>
-    
-    <authorgroup>
-      <author>
-	<firstname>Wim</firstname>
-	<surname>Taymans</surname>
-	<authorblurb>
-	  <para>
-	    <email>wim.taymans@chello.be</email>
-	  </para>
-	</authorblurb>
-      </author>
-      <author>
-	<firstname>Steve</firstname>
-	<surname>Baker</surname>
-	<authorblurb>
-	  <para>
-	    <email>stevebaker_org@yahoo.co.uk</email>
-	  </para>
-	</authorblurb>
-      </author>
-      <author>
-	<firstname>Andy</firstname>
-	<surname>Wingo</surname>
-	<authorblurb>
-	  <para>
-	    <email>wingo@pobox.com</email>
-	  </para>
-	</authorblurb>
-      </author>
-      <author>
-        <firstname>Ronald</firstname>
-        <othername>S.</othername>
-        <surname>Bultje</surname>
-        <authorblurb>
-          <para>
-            <email>rbultje@ronald.bitfreak.net</email>
-          </para>
-        </authorblurb>
-      </author>
-    </authorgroup>
-
-    <legalnotice id="misc-legalnotice">
-      <para>
-	This material may be distributed only subject to the terms and
-        conditions set forth in the Open Publication License, v1.0 or later (the
-        latest version is presently available at <ulink url="
-        http://www.opencontent.org/opl.shtml"
-        type="http">http://www.opencontent.org/opl.shtml</ulink>).
-      </para>
-    </legalnotice>
-
-    <title>&GStreamer; Application Development Manual (&GST_VERSION;)</title>
-
-  </bookinfo>
-      
+  &TITLEPAGE;
+  
 <!-- ############# Introduction & Overview - part ############### -->
 
   <part id="part-overview">
@@ -261,35 +209,35 @@
       </para>
     </partintro>
 
-<!--
-Idea:
-* Debugging and error handling
-   - 'error' signal in pipelines
-   - checking return values and how to handle them
-   - using signals for pipeline states
-   - gst-debug
-   - programs
-* Desktop integration
-   - Linux/UNIX
-      . {x,xv}imagesink
-      . {oss,alsa}sink
-      . {v4l,v4l2,oss,alsa}src
-   - GNOME
-      . GConf ({video,audio}{src,sink})
-      . gnomevfssrc, gnomevfssink
-      . popt
-      . app examples (RB, Totem, gnome-media, ...)
-   - KDE
-      . kiosrc
-      . app examples (JuK, AmaroK)
-      . ask Scott/Mark
-   - Mac OS X
-      . native video/audio sink
-   - Windows
-      . build etc.
-* Quotes from devs
-   - table please...
--->
+    <!--
+    Idea:
+    * Debugging and error handling
+     - 'error' signal in pipelines
+     - checking return values and how to handle them
+     - using signals for pipeline states
+     - gst-debug
+     - programs
+    * Desktop integration
+     - Linux/UNIX
+	. {x,xv}imagesink
+	. {oss,alsa}sink
+	. {v4l,v4l2,oss,alsa}src
+     - GNOME
+	. GConf ({video,audio}{src,sink})
+	. gnomevfssrc, gnomevfssink
+	. popt
+	. app examples (RB, Totem, gnome-media, ...)
+     - KDE
+	. kiosrc
+	. app examples (JuK, AmaroK)
+	. ask Scott/Mark
+     - Mac OS X
+	. native video/audio sink
+     - Windows
+	. build etc.
+    * Quotes from devs
+     - table please...
+    -->
 
     &CHECKLIST;
     &PORTING;
diff --git a/docs/manual/titlepage.xml b/docs/manual/titlepage.xml
new file mode 100644
index 0000000000..3883384a4e
--- /dev/null
+++ b/docs/manual/titlepage.xml
@@ -0,0 +1,69 @@
+<bookinfo>
+  
+  <authorgroup>
+    <author>
+      <firstname>Wim</firstname>
+      <surname>Taymans</surname>
+      <authorblurb>
+	<para>
+	  <email>wim.taymans@chello.be</email>
+	</para>
+      </authorblurb>
+    </author>
+    
+    <author>
+      <firstname>Steve</firstname>
+      <surname>Baker</surname>
+      <authorblurb>
+	<para>
+	  <email>stevebaker_org@yahoo.co.uk</email>
+	</para>
+      </authorblurb>
+    </author>
+    
+    <author>
+      <firstname>Andy</firstname>
+      <surname>Wingo</surname>
+      <authorblurb>
+	<para>
+	  <email>wingo@pobox.com</email>
+	</para>
+      </authorblurb>
+    </author>
+    
+    <author>
+      <firstname>Ronald</firstname>
+      <othername>S.</othername>
+      <surname>Bultje</surname>
+      <authorblurb>
+	<para>
+	  <email>rbultje@ronald.bitfreak.net</email>
+	</para>
+      </authorblurb>
+    </author>
+
+    <author>
+      <firstname>Stefan</firstname>
+      <surname>Kost</surname>
+      <authorblurb>
+	<para>
+	  <email>ensonic@users.sf.net</email>
+	</para>
+      </authorblurb>
+    </author>
+  </authorgroup>
+
+  <legalnotice id="misc-legalnotice">
+    <para>
+      This material may be distributed only subject to the terms and
+      conditions set forth in the Open Publication License, v1.0 or later (the
+      latest version is presently available at <ulink url="
+      http://www.opencontent.org/opl.shtml"
+      type="http">http://www.opencontent.org/opl.shtml</ulink>).
+    </para>
+  </legalnotice>
+
+  <title>&GStreamer; Application Development Manual (&GST_VERSION;)</title>
+
+</bookinfo>
+
diff --git a/docs/pwg/pwg.xml b/docs/pwg/pwg.xml
index 8674170f3c..dccfbe097a 100644
--- a/docs/pwg/pwg.xml
+++ b/docs/pwg/pwg.xml
@@ -8,9 +8,11 @@
 
 <!ENTITY TITLEPAGE            SYSTEM "titlepage.xml">
 
+<!-- Part 1: Introduction -->
 <!ENTITY INTRO_PREFACE        SYSTEM "intro-preface.xml">
 <!ENTITY INTRO_BASICS         SYSTEM "intro-basics.xml">
 
+<!-- Part 2: Building a Plugin -->
 <!ENTITY BUILDING_BOILER      SYSTEM "building-boiler.xml">
 <!ENTITY BUILDING_DEBUG       SYSTEM "building-debug.xml">
 <!ENTITY BUILDING_PADS        SYSTEM "building-pads.xml">
@@ -20,6 +22,7 @@
 <!ENTITY BUILDING_SIGNALS     SYSTEM "building-signals.xml">
 <!ENTITY BUILDING_TESTAPP     SYSTEM "building-testapp.xml">
 
+<!-- Part 3: Advanced Filter Concepts -->
 <!ENTITY ADVANCED_NEGOTIATION SYSTEM "advanced-negotiation.xml">
 <!ENTITY ADVANCED_SCHEDULING  SYSTEM "advanced-scheduling.xml">
 <!ENTITY ADVANCED_TYPES       SYSTEM "advanced-types.xml">
@@ -31,11 +34,13 @@
 <!ENTITY ADVANCED_TAGGING     SYSTEM "advanced-tagging.xml">
 <!ENTITY ADVANCED_EVENTS      SYSTEM "advanced-events.xml">
 
+<!-- Part 4: Creating special element types -->
 <!ENTITY OTHER_BASE           SYSTEM "other-base.xml">
 <!ENTITY OTHER_ONETON         SYSTEM "other-oneton.xml">
 <!ENTITY OTHER_NTOONE         SYSTEM "other-ntoone.xml">
 <!ENTITY OTHER_MANAGER        SYSTEM "other-manager.xml">
 
+<!-- Appendices -->
 <!ENTITY APPENDIX_CHECKLIST   SYSTEM "appendix-checklist.xml">
 <!ENTITY APPENDIX_PORTING     SYSTEM "appendix-porting.xml">
 <!ENTITY APPENDIX_LICENSING   SYSTEM "appendix-licensing.xml">
@@ -49,7 +54,7 @@
 <book id="index">
   &TITLEPAGE;
 
-  <!-- ############# part ############### -->
+  <!-- ############# Introduction - part ############### -->
 
   <part id="part-introduction" xreflabel="Introduction">
     <title>Introduction</title>
@@ -78,7 +83,7 @@
     &INTRO_BASICS;
   </part>
 
-  <!-- ############ part ############# -->
+  <!-- ############ Building a Plugin - part ############# -->
 
   <part id="part-building" xreflabel="Building a Plugin">
     <title>Building a Plugin</title>
@@ -118,7 +123,7 @@
     &BUILDING_TESTAPP;
   </part>
 
-  <!-- ############ part ############# -->
+  <!-- ############ Advanced Filter Concepts - part ############# -->
 
   <part id="part-advanced" xreflabel="Advanced Filter Concepts">
     <title>Advanced Filter Concepts</title>
@@ -148,7 +153,7 @@
 
   </part>
 
-  <!-- ############ part ############# -->
+  <!-- ############ Creating special element types - part ############# -->
 
   <part id="part-other" xreflabel="Creating special element types">
     <title>Creating special element types</title>
@@ -173,7 +178,7 @@
     &OTHER_MANAGER;
   </part>
 
-  <!-- ############ part ############# -->
+  <!-- ############ Appendices - part ############# -->
 
   <part id="part-appendix" xreflabel="Appendices">
     <title>Appendices</title>
diff --git a/docs/pwg/titlepage.xml b/docs/pwg/titlepage.xml
index 680ede057b..dabdf54894 100644
--- a/docs/pwg/titlepage.xml
+++ b/docs/pwg/titlepage.xml
@@ -1,69 +1,79 @@
-  <bookinfo>
+<bookinfo>
 
-    <authorgroup>
-      <author>
-	<firstname>Richard</firstname>
-	<othername>John</othername>
-	<surname>Boulton</surname>
-	<authorblurb>
-	  <para>
-	    <email>richard-gst@tartarus.org</email>
-	  </para>
-	</authorblurb>
-      </author>
+  <authorgroup>
+    <author>
+      <firstname>Richard</firstname>
+      <othername>John</othername>
+      <surname>Boulton</surname>
+      <authorblurb>
+	<para>
+	  <email>richard-gst@tartarus.org</email>
+	</para>
+      </authorblurb>
+    </author>
 
-      <author>
-	<firstname>Erik</firstname>
-	<surname>Walthinsen</surname>
-	<authorblurb>
-	  <para>
-	    <email>omega@temple-baptist.com</email>
-	  </para>
-	</authorblurb>
-      </author>
+    <author>
+      <firstname>Erik</firstname>
+      <surname>Walthinsen</surname>
+      <authorblurb>
+	<para>
+	  <email>omega@temple-baptist.com</email>
+	</para>
+      </authorblurb>
+    </author>
 
-      <author>
-	<firstname>Steve</firstname>
-	<surname>Baker</surname>
-	<authorblurb>
-	  <para>
-	    <email>stevebaker_org@yahoo.co.uk</email>
-	  </para>
-	</authorblurb>
-      </author>
+    <author>
+      <firstname>Steve</firstname>
+      <surname>Baker</surname>
+      <authorblurb>
+	<para>
+	  <email>stevebaker_org@yahoo.co.uk</email>
+	</para>
+      </authorblurb>
+    </author>
 
-      <author>
-	<firstname>Leif</firstname>
-	<surname>Johnson</surname>
-	<authorblurb>
-	  <para>
-	    <email>leif@ambient.2y.net</email>
-	  </para>
-	</authorblurb>
-      </author>
+    <author>
+      <firstname>Leif</firstname>
+      <surname>Johnson</surname>
+      <authorblurb>
+	<para>
+	  <email>leif@ambient.2y.net</email>
+	</para>
+      </authorblurb>
+    </author>
 
-      <author>
-        <firstname>Ronald</firstname>
-        <othername>S.</othername>
-        <surname>Bultje</surname>
-        <authorblurb>
-          <para>
-            <email>rbultje@ronald.bitfreak.net</email>
-          </para>
-        </authorblurb>
-      </author>
-    </authorgroup>
+    <author>
+      <firstname>Ronald</firstname>
+      <othername>S.</othername>
+      <surname>Bultje</surname>
+      <authorblurb>
+	<para>
+	  <email>rbultje@ronald.bitfreak.net</email>
+	</para>
+      </authorblurb>
+    </author>
 
-    <legalnotice id="misc-legalnotice">
-      <para>
-	This material may be distributed only subject to the terms and
-	conditions set forth in the Open Publication License, v1.0 or later (the
-	latest version is presently available at <ulink
-	url="http://www.opencontent.org/openpub/"
-	type="http">http://www.opencontent.org/openpub/</ulink>).
-      </para>
-    </legalnotice>
+    <author>
+      <firstname>Stefan</firstname>
+      <surname>Kost</surname>
+      <authorblurb>
+	<para>
+	  <email>ensonic@users.sf.net</email>
+	</para>
+      </authorblurb>
+    </author>
+  </authorgroup>
 
-    <title>&GStreamer; Plugin Writer's Guide (&GST_VERSION;)</title>
+  <legalnotice id="misc-legalnotice">
+    <para>
+      This material may be distributed only subject to the terms and
+      conditions set forth in the Open Publication License, v1.0 or later (the
+      latest version is presently available at <ulink
+      url="http://www.opencontent.org/openpub/"
+      type="http">http://www.opencontent.org/openpub/</ulink>).
+    </para>
+  </legalnotice>
 
-  </bookinfo>
+  <title>&GStreamer; Plugin Writer's Guide (&GST_VERSION;)</title>
+
+</bookinfo>
diff --git a/libs/gst/controller/gstcontroller.c b/libs/gst/controller/gstcontroller.c
index 377823fa6b..c70991cbae 100644
--- a/libs/gst/controller/gstcontroller.c
+++ b/libs/gst/controller/gstcontroller.c
@@ -25,8 +25,8 @@
  * @short_description: dynamic parameter control subsystem
  *
  * The controller subsystem offers a lightweight way to adjust gobject
- * properties over stream-time. It works by using time-stampled value pairs that
- * are queued for element-properties. At run-time the elements continously pulls
+ * properties over stream-time. It works by using time-stamped value pairs that
+ * are queued for element-properties. At run-time the elements continously pull
  * values changes for the current stream-time.
  *
  * What needs to be changed in a #GstElement?