Everybody loves docs - add docs for musicbrainz plugin.

Original commit message from CVS:
* docs/plugins/Makefile.am:
* docs/plugins/gst-plugins-bad-plugins-docs.sgml:
* docs/plugins/gst-plugins-bad-plugins-sections.txt:
* docs/plugins/gst-plugins-bad-plugins.hierarchy:
* docs/plugins/inspect/plugin-musicbrainz.xml:
* ext/musicbrainz/gsttrm.c:
* ext/musicbrainz/gsttrm.h:
Everybody loves docs - add docs for musicbrainz plugin.

ChangeLog

@@ -1,3 +1,14 @@
+2006-05-03  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* docs/plugins/Makefile.am:
+	* docs/plugins/gst-plugins-bad-plugins-docs.sgml:
+	* docs/plugins/gst-plugins-bad-plugins-sections.txt:
+	* docs/plugins/gst-plugins-bad-plugins.hierarchy:
+	* docs/plugins/inspect/plugin-musicbrainz.xml:
+	* ext/musicbrainz/gsttrm.c:
+	* ext/musicbrainz/gsttrm.h:
+	  Everybody loves docs - add docs for musicbrainz plugin.
+
 2006-05-03  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* ext/Makefile.am:

docs/plugins/Makefile.am

@@ -86,7 +86,8 @@ EXAMPLE_CFILES = \
         $(top_srcdir)/ext/directfb/dfb-example.c
 
 EXTRA_HFILES = \
-	$(top_srcdir)/ext/directfb/dfbvideosink.h
+	$(top_srcdir)/ext/directfb/dfbvideosink.h \
+	$(top_srcdir)/ext/musicbrainz/gsttrm.h
 
 # Images to copy into HTML directory.
 HTML_IMAGES =

docs/plugins/gst-plugins-bad-plugins-docs.sgml

@@ -14,6 +14,7 @@
     <title>gst-plugins-bad Elements</title>
 
     <xi:include href="xml/element-dfbvideosink.xml" />
+    <xi:include href="xml/element-trm.xml" />
   </chapter>
 
   <chapter>
@@ -27,6 +28,7 @@
     <xi:include href="xml/plugin-glimagesink.xml" />
     <xi:include href="xml/plugin-gsm.xml" />
     <xi:include href="xml/plugin-modplug.xml" />
+    <xi:include href="xml/plugin-musicbrainz.xml" />
     <xi:include href="xml/plugin-neon.xml" />
     <xi:include href="xml/plugin-qtdemux.xml" />
     <xi:include href="xml/plugin-sdlvideosink.xml" />

docs/plugins/gst-plugins-bad-plugins-sections.txt

@@ -5,3 +5,11 @@ GstDfbVideoSink
 <SUBSECTION Standard>
 GstDfbVideoSinkClass
 </SECTION>
+
+<SECTION>
+<FILE>element-trm</FILE>
+GstTRM
+<TITLE>trm</TITLE>
+<SUBSECTION Standard>
+GstTRMClass
+</SECTION>

docs/plugins/gst-plugins-bad-plugins.hierarchy

@@ -12,6 +12,7 @@ GObject
       GstBaseSink
         GstVideoSink
           GstDfbVideoSink
+      GstTRM
     GstPlugin
     GstRegistry
     GstPadTemplate

docs/plugins/inspect/plugin-musicbrainz.xml

@@ -0,0 +1,20 @@
+<plugin>
+  <name>musicbrainz</name>
+  <description>A TRM signature producer based on libmusicbrainz</description>
+  <filename>../../ext/musicbrainz/.libs/libgsttrm.so</filename>
+  <basename>libgsttrm.so</basename>
+  <version>0.10.2.1</version>
+  <license>LGPL</license>
+  <source>gst-plugins-bad</source>
+  <package>GStreamer Bad Plug-ins CVS/prerelease</package>
+  <origin>Unknown package origin</origin>
+  <elements>
+    <element>
+      <name>trm</name>
+      <longname>MusicBrainz TRM generator</longname>
+      <class>Filter/Analyzer/Audio</class>
+      <description>Compute MusicBrainz TRM Id using libmusicbrainz</description>
+      <author>Jeremy Simon &lt;jsimon13@yahoo.fr&gt;</author>
+    </element>
+  </elements>
+</plugin>

ext/musicbrainz/gsttrm.c

@@ -18,6 +18,42 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-trm
+ *
+ * <refsect2>
+ * <para>
+ * GstTRM computes <ulink url="http://www.musicbrainz.org/">MusicBrainz</ulink>
+ * TRM identifiers for audio streams using libmusicbrainz.
+ * </para>
+ * <para>
+ * A TRM identifier is something like an 'acoustic fingerprint', the aim is
+ * to uniquely identify the same song regardless of which source it comes from
+ * or which audio format the stream is in.
+ * </para>
+ * <para>
+ * The TRM element will collect about 30 seconds of audio and let
+ * libmusicbrainz calculate a preliminary audio signature from that. That audio
+ * signature will then be sent over the internet to a musicbrainz.org server
+ * which will calculate the TRM for that signature.
+ * </para>
+ * <para>
+ * The TRM element will post a tag message with a #GST_TAG_MUSICBRAINZ_TRMID
+ * tag on the bus once the TRM has been calculated (and also send a tag event
+ * with that information downstream).
+ * </para>
+ * <title>Example pipeline</title>
+ * <para>
+ * Here is a test pipeline to test the TRM element:
+ * <programlisting>
+ * gst-launch -m filesrc location=somefile.ogg ! decodebin ! audioconvert ! trm ! fakesink
+ * </programlisting>
+ * this should (among many other things) print the tag message with the TRM ID.
+ * </para>
+ * </refsect2>
+ */
+
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

ext/musicbrainz/gsttrm.h

@@ -38,9 +38,17 @@ G_BEGIN_DECLS
 typedef struct _GstTRM GstTRM;
 typedef struct _GstTRMClass GstTRMClass;
 
+/**
+ *  GstTRM
+ *
+ *  GStreamer TRM element. This structure is opaque (private).
+ *
+ **/
+
 struct _GstTRM {
   GstElement element;
 
+  /*< private >*/
   GstPad   *sinkpad;
   GstPad   *srcpad;