From 2dcf1494c2ee724fd6e7994c3b360147bae050e1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tim-Philipp=20M=C3=BCller?= <tim@centricular.net>
Date: Mon, 6 Feb 2006 11:34:23 +0000
Subject: [PATCH] docs/plugins/: Add cdio plugin to docs.

Original commit message from CVS:
* docs/plugins/Makefile.am:
* docs/plugins/gst-plugins-good-plugins-docs.sgml:
* docs/plugins/gst-plugins-good-plugins-sections.txt:
* docs/plugins/inspect/plugin-cdio.xml:
Add cdio plugin to docs.
* ext/cdio/gstcdiocddasrc.c:
Add gtk-doc blurb.
* ext/cdio/gstcdio.c:
The plugin is called 'cdio' not 'cddio'.
---
 ext/cdio/gstcdio.c        |  2 +-
 ext/cdio/gstcdiocddasrc.c | 54 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/ext/cdio/gstcdio.c b/ext/cdio/gstcdio.c
index 869e789d9d..33547aef98 100644
--- a/ext/cdio/gstcdio.c
+++ b/ext/cdio/gstcdio.c
@@ -85,6 +85,6 @@ plugin_init (GstPlugin * plugin)
 
 GST_PLUGIN_DEFINE (GST_VERSION_MAJOR,
     GST_VERSION_MINOR,
-    "cddio",
+    "cdio",
     "Read audio from audio CDs",
     plugin_init, VERSION, "GPL", GST_PACKAGE_NAME, GST_PACKAGE_ORIGIN)
diff --git a/ext/cdio/gstcdiocddasrc.c b/ext/cdio/gstcdiocddasrc.c
index 0229732e08..ed0fef6768 100644
--- a/ext/cdio/gstcdiocddasrc.c
+++ b/ext/cdio/gstcdiocddasrc.c
@@ -17,6 +17,60 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-cdiocddasrc
+ * @short_description: Reads raw audio from an Audio CD
+ * @see_also: GstCdParanoiaSrc, GstCddaBaseSrc
+ *
+ * <refsect2>
+ * <para>
+ * cdiocddasrc reads and extracts raw audio from Audio CDs. It can operate
+ * in one of two modes:
+ * <itemizedlist>
+ *  <listitem><para>
+ *    treat each track as a separate stream, counting time from the start
+ *    of the track to the end of the track and posting EOS at the end of
+ *    a track, or
+ *  </para></listitem>
+ *  <listitem><para>
+ *    treat the entire disc as one stream, counting time from the start of
+ *    the first track to the end of the last track, posting EOS only at
+ *    the end of the last track.
+ *  </para></listitem>
+ * </itemizedlist>
+ * </para>
+ * <para>
+ * With a recent-enough version of libcdio, the element will extract
+ * CD-TEXT if this is supported by the CD-drive and CD-TEXT information
+ * is available on the CD. The information will be posted on the bus in
+ * form of a tag message.
+ * </para>
+ * <para>
+ * When opened, the element will also calculate a CDDB disc ID and a
+ * MusicBrainz disc ID, which applications can use to query online
+ * databases for artist/title information. These disc IDs will also be
+ * posted on the bus as part of the tag messages.
+ * </para>
+ * <para>
+ * cdiocddasrc supports the GstUriHandler interface, so applications can use
+ * playbin with cdda://&lt;track-number&gt; URIs for playback (they will have
+ * to connect to playbin's notify::source signal and set the device on the
+ * cd source in the notify callback if they want to set the device property).
+ * Applications should use seeks in "track" format to switch between different
+ * tracks of the same CD (passing a new cdda:// URI to playbin involves opening
+ * and closing the CD device, which is much slower).
+ * </para>
+ * <title>Example launch line</title>
+ * <para>
+ * <programlisting>
+ * gst-launch cdiocddasrc track=5 device=/dev/cdrom ! audioconvert ! vorbisenc ! oggmux ! filesink location=track5.ogg
+ * </programlisting>
+ * This pipeline extracts track 5 of the audio CD and encodes it into an
+ * Ogg/Vorbis file.
+ * </para>
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif