Small manual changes.

Original commit message from CVS:
Small manual changes.
Added a section about autoplugging.

docs/manual/Makefile.am

@@ -3,6 +3,7 @@ htmlname = index.html
 
 sgml_files = gstreamer-manual.sgml \
 	     advanced.sgml \
+	     autoplugging.sgml \
              bins.sgml \
              buffers.sgml \
              components.sgml \

docs/manual/autoplugging.sgml

@@ -0,0 +1,99 @@
+<chapter id="cha-autoplug">
+  <title>Autoplugging</title>
+  <para> 
+    <application>GStreamer</application> provides an API to automatically
+    construct complex pipelinebased on source and destination capabilities.
+    This feature is very usefull if you want to convert type X to type Y but
+    don't care about the plugins needed to accomplish this task. The 
+    autoplugger will consult the plugin repository, select and connect the
+    elements needed for the conversion.
+  </para>
+  <para> 
+    The autoplugger API is implemented in an abstract class. Autoplugger implementations
+    reside in plugins and are therefore optional and can be optimized for a specific
+    task.  Two types of autopluggers exist: renderer ones and non
+    renderer ones. the renderer autopluggers will not have any src pads while the
+    non renderer ones do. The renderer autopluggers are mainly used for media
+    playback while the non renderer ones are used for arbitrary format conversion.
+  </para>
+
+  <sect1>
+    <title>Using autoplugging</title>
+    <para> 
+      You first need to create a suitable autoplugger with gst_autoplugfactory_make().
+      The name of the autoplugger must be one of the registered autopluggers..
+    </para>
+    <para>
+      A list of all available autopluggers can be obtained with gst_autoplugfactory_get_list().
+    </para>
+    <para>
+      If the autoplugger supports the RENDERER API, use gst_autoplug_to_renderers() call to
+      create a bin that connectes the src caps to the specified render elements. You can
+      then add the bin to a pipeline and run it.
+
+      <programlisting>
+
+        GstAutoplug *autoplug;
+	GstElement  *element;
+	GstElement  *sink;
+
+	/* create a static autoplugger */
+	autoplug = gst_autoplugfactory_make ("staticrender");
+
+	/* create an osssink */
+	sink = gst_elementfactory_make ("osssink", "our_sink");
+
+	/* create an element that can play audio/mp3 through osssink */
+	element = gst_autoplug_to_renderers (autoplug,
+	                                     gst_caps_new (
+	                                       "sink_audio_caps",
+	                                       "audio/mp3",
+	                                       NULL
+	                                     ),
+	                                     sink,
+	                                     NULL);
+
+	/* add the element to a bin and connect the sink pad */
+	...
+      </programlisting>
+    </para>
+    <para>
+      If the autoplugger supports the CAPS API, use the gst_autoplug_to_caps() function to
+      connect the src caps to the destination caps. The created bin will have src and sink
+      pads compatible with the provided caps.
+
+      <programlisting>
+
+        GstAutoplug *autoplug;
+	GstElement  *element;
+
+	/* create a static autoplugger */
+	autoplug = gst_autoplugfactory_make ("static");
+
+	/* create an element that converts audio/mp3 to audio/raw */
+	element = gst_autoplug_to_caps (autoplug,
+	                                gst_caps_new (
+	                                  "sink_audio_caps",
+	                                  "audio/mp3",
+	                                  NULL
+	                                ),
+	                                gst_caps_new (
+	                                  "src_audio_caps",
+	                                  "audio/raw",
+	                                  NULL
+	                                ),
+	                                NULL);
+
+	/* add the element to a bin and connect the src/sink pads */
+	...
+      </programlisting>
+    </para>
+  </sect1>
+  <sect1>
+    <title>A complete autoplugging example</title>
+    <para>
+      We will create and explain how a complete media player can be built with the
+      autoplugger.
+    </para>
+  </sect1>
+</chapter>

docs/manual/bins.sgml

@@ -34,7 +34,7 @@
       <listitem>
         <para>
           A thread (<classname>GstThread</classname>). All the elements in the thread bin will 
-	  run in a separate thread. You will haver to use this bin if you carfully have to 
+	  run in a separate thread. You will have to use this bin if you carfully have to 
 	  synchronize audio and video for example. You will learn more about threads in.. <!-- FIXME -->
         </para>
       </listitem>

docs/manual/buffers.sgml

@@ -27,17 +27,6 @@
 	  will be used to destroy the buffer when no element is having a reference to it.
         </para>
       </listitem>
-      <listitem>
-        <para>
-          A list of metadata that describes the context of the buffers memory. In the case
-	  of audio data, for example, it would provide the samplerate, depth and channel
-	  count.
-        </para>
-        <para>
-	  GStreamer provides a registry where different metadata types can be registered
-	  so that everybody is talking about the same data.
-        </para>
-      </listitem>
     </itemizedlist>
   </para>
 
@@ -67,11 +56,4 @@
     situation.
   </para>
 
-  <para> 
-    Before an element can operate on the buffers memory, is has to check the metadata 
-    attached to it (if any).  An MPEG audio decoder has to ignore a buffer with video
-    metadata (in which case the pipeline is probably constructed by connecting the
-    wrong elements, anyway).
-  </para>
-
 </chapter>

docs/manual/elements.sgml

@@ -1,8 +1,8 @@
 <chapter id="cha-elements">
   <title>GstElement</title>
   <para> 
-    The most important object in GStreamer for the application programmer is
+    The most important object in <application>GStreamer</application> for the 
-    the GstElement object. 
+    application programmer is the <classname>GstElement</classname> object. 
   </para>
 
   <sect1 id="sec-elements-design">

docs/manual/gstreamer-manual.sgml

@@ -12,6 +12,7 @@
 
 <!ENTITY HELLOWORLD SYSTEM "helloworld.sgml">
 <!ENTITY FACTORIES SYSTEM "factories.sgml">
+<!ENTITY AUTOPLUGGING SYSTEM "autoplugging.sgml">
 <!ENTITY HELLOWORLD2 SYSTEM "helloworld2.sgml">
 
 <!ENTITY THREADS SYSTEM "threads.sgml">
@@ -130,6 +131,8 @@
 
       &FACTORIES;
 
+      &AUTOPLUGGING;
+
       &HELLOWORLD2;
   </part>
 

docs/manual/helloworld.sgml

@@ -19,17 +19,6 @@
       
 #include <gst/gst.h>
 
-gboolean playing;
-
-/* eos will be called when the src element has an end of stream */
-void 
-eos (GstSrc *src) 
-{
-  g_print ("have eos, quitting\n");
-
-  playing = FALSE;
-}
-
 int 
 main (int argc, char *argv[]) 
 {
@@ -48,8 +37,6 @@ main (int argc, char *argv[])
   /* create a disk reader */
   disksrc = gst_elementfactory_make ("disksrc", "disk_source");
   gtk_object_set (GTK_OBJECT (disksrc),"location", argv[1], NULL);
-  gtk_signal_connect (GTK_OBJECT (disksrc), "eos",
-                      GTK_SIGNAL_FUNC (eos), NULL);
 
   /* now it's time to get the parser */
   parse = gst_elementfactory_make ("mp3parse", "parse");
@@ -75,11 +62,7 @@ main (int argc, char *argv[])
   /* start playing */
   gst_element_set_state (bin, GST_STATE_PLAYING);
 
-  playing = TRUE;
+  while (gst_bin_iterate (GST_BIN (bin)));
-
-  while (playing) {
-    gst_bin_iterate (GST_BIN (bin));
-  }
 
   /* stop the bin */
   gst_element_set_state (bin, GST_STATE_NULL);
@@ -150,14 +133,7 @@ main (int argc, char *argv[])
   /* create a disk reader */
   disksrc = gst_elementfactory_make ("disksrc", "disk_source");
   gtk_object_set (GTK_OBJECT (disksrc),"location", argv[1], NULL);
-  gtk_signal_connect (GTK_OBJECT (disksrc), "eos",
-                      GTK_SIGNAL_FUNC (eos), NULL);
     </programlisting>
-    <para>
-      We also connected the eos signal to our function. When the
-      disk source has reached an end-of-stream, this function will be called.
-      We will use it to set a gboolean value to FALSE;
-    </para>
     <note>
       <para>
         You can check if the disksrc != NULL to verify the creation of the
@@ -165,20 +141,6 @@ main (int argc, char *argv[])
       </para>
     </note>
 
-    <programlisting>
-gboolean playing;
-...
-
-/* eos will be called when the src element has an end of stream */
-void 
-eos (GstSrc *src) 
-{
-  g_print ("have eos, quitting\n");
-
-  playing = FALSE;
-}
-    </programlisting>
-
     <para>
       We now create the MP3 decoder element. <application>GStreamer</application> requires you
       to put a parser in front of the decoder. This parser will
@@ -249,7 +211,6 @@ eos (GstSrc *src)
   /* start playing */
   gst_element_set_state (bin, GST_STATE_PLAYING);
 
-  playing = TRUE;
     </programlisting>
     <note>
       <para>
@@ -263,14 +224,12 @@ eos (GstSrc *src)
       call gst_bin_iterate() to execute one iteration of the bin. 
     </para>
     <programlisting>
-  while (playing) {
+  while (gst_bin_iterate (GST_BIN (bin)));
-    gst_bin_iterate (GST_BIN (bin));
-  }
     </programlisting>
     <para>
-      Remember that the variable playing will become false if the disk source
+      The gst_bin_iterate() function will return TRUE as long as something interesting
-      has reached an end-of-file. When that happens, the follwing code takes
+      happended inside the bin. When the end-of-file has been reached the _iterate 
-      care of the cleanup:
+      function will return FALSE and we can end the loop.
     </para>
     <programlisting>
   /* stop the bin */

docs/manual/pads.sgml

@@ -276,6 +276,21 @@ Pads:
 	    A list value: the property can take any value from a list.
           </para>
         </listitem>
+        <listitem>
+          <para>
+	    A float value: the property has this exact floating point value.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+	    A float range value: denotes a range of possible floating point values.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+	    A string value.
+          </para>
+        </listitem>
       </itemizedlist>
 
     </sect2>