Cleanup Plugin docs. Link to signals and properties. Fix sub-section titles. Drop mentining that all our example pipe...

Original commit message from CVS:
* docs/plugins/gst-plugins-base-plugins-docs.sgml:
* docs/plugins/gst-plugins-base-plugins-overrides.txt:
* docs/plugins/gst-plugins-base-plugins-sections.txt:
* docs/plugins/gst-plugins-base-plugins.args:
* docs/plugins/gst-plugins-base-plugins.hierarchy:
* docs/plugins/gst-plugins-base-plugins.interfaces:
* docs/plugins/gst-plugins-base-plugins.prerequisites:
* docs/plugins/gst-plugins-base-plugins.signals:
* docs/plugins/inspect/plugin-adder.xml:
* docs/plugins/inspect/plugin-alsa.xml:
* docs/plugins/inspect/plugin-audioconvert.xml:
* docs/plugins/inspect/plugin-audiorate.xml:
* docs/plugins/inspect/plugin-audioresample.xml:
* docs/plugins/inspect/plugin-audiotestsrc.xml:
* docs/plugins/inspect/plugin-cdparanoia.xml:
* docs/plugins/inspect/plugin-decodebin.xml:
* docs/plugins/inspect/plugin-ffmpegcolorspace.xml:
* docs/plugins/inspect/plugin-gdp.xml:
* docs/plugins/inspect/plugin-gnomevfs.xml:
* docs/plugins/inspect/plugin-libvisual.xml:
* docs/plugins/inspect/plugin-ogg.xml:
* docs/plugins/inspect/plugin-pango.xml:
* docs/plugins/inspect/plugin-playback.xml:
* docs/plugins/inspect/plugin-queue2.xml:
* docs/plugins/inspect/plugin-subparse.xml:
* docs/plugins/inspect/plugin-tcp.xml:
* docs/plugins/inspect/plugin-theora.xml:
* docs/plugins/inspect/plugin-typefindfunctions.xml:
* docs/plugins/inspect/plugin-uridecodebin.xml:
* docs/plugins/inspect/plugin-video4linux.xml:
* docs/plugins/inspect/plugin-videorate.xml:
* docs/plugins/inspect/plugin-videoscale.xml:
* docs/plugins/inspect/plugin-videotestsrc.xml:
* docs/plugins/inspect/plugin-volume.xml:
* docs/plugins/inspect/plugin-vorbis.xml:
* docs/plugins/inspect/plugin-ximagesink.xml:
* docs/plugins/inspect/plugin-xvimagesink.xml:
* ext/alsa/gstalsamixer.c:
* ext/alsa/gstalsasink.c:
* ext/alsa/gstalsasrc.c:
* ext/gio/gstgiosink.c:
* ext/gio/gstgiosrc.c:
* ext/gio/gstgiostreamsink.c:
* ext/gio/gstgiostreamsrc.c:
* ext/gnomevfs/gstgnomevfssink.c:
* ext/gnomevfs/gstgnomevfssrc.c:
* ext/ogg/gstoggdemux.c:
* ext/ogg/gstoggmux.c:
* ext/pango/gstclockoverlay.c:
* ext/pango/gsttextoverlay.c:
* ext/pango/gsttextrender.c:
* ext/pango/gsttimeoverlay.c:
* ext/theora/theoradec.c:
* ext/theora/theoraenc.c:
* ext/theora/theoraparse.c:
* ext/vorbis/vorbisdec.c:
* ext/vorbis/vorbisenc.c:
* ext/vorbis/vorbisparse.c:
* ext/vorbis/vorbistag.c:
* gst/adder/gstadder.c:
* gst/audioconvert/gstaudioconvert.c:
* gst/audioresample/gstaudioresample.c:
* gst/audiotestsrc/gstaudiotestsrc.c:
* gst/ffmpegcolorspace/gstffmpegcolorspace.c:
* gst/gdp/gstgdpdepay.c:
* gst/gdp/gstgdppay.c:
* gst/playback/gstdecodebin2.c:
* gst/playback/gstplaybin.c:
* gst/playback/gstplaybin2.c:
* gst/playback/gstqueue2.c:
* gst/playback/gsturidecodebin.c:
* gst/tcp/gstmultifdsink.c:
* gst/tcp/gsttcpserversink.c:
* gst/videorate/gstvideorate.c:
* gst/videoscale/gstvideoscale.c:
* gst/videotestsrc/gstvideotestsrc.c:
* gst/volume/gstvolume.c:
* sys/ximage/ximagesink.c:
* sys/xvimage/xvimagesink.c:
Cleanup Plugin docs. Link to signals and properties. Fix sub-section
titles. Drop mentining that all our example pipelines are "simple"
pipelines.

5 files changed, 64 insertions, 99 deletions

diff --git a/gst/videoscale/gstvideoscale.c b/gst/videoscale/gstvideoscale.c
index be6cb4ce..5813f70a 100644
--- a/gst/videoscale/gstvideoscale.c
+++ b/gst/videoscale/gstvideoscale.c
@@ -22,35 +22,27 @@
  * SECTION:element-videoscale
  * @see_also: videorate, ffmpegcolorspace
  *
- * <refsect2>
- * <para>
  * This element resizes video frames. By default the element will try to
  * negotiate to the same size on the source and sinkpad so that no scaling
  * is needed. It is therefore safe to insert this element in a pipeline to
  * get more robust behaviour without any cost if no scaling is needed.
- * </para>
- * <para>
+ *
  * This element supports a wide range of color spaces including various YUV and
  * RGB formats and is therefore generally able to operate anywhere in a
  * pipeline.
- * </para>
+ *
+ * <refsect2>
  * <title>Example pipelines</title>
- * <para>
- * <programlisting>
+ * |[
  * gst-launch -v filesrc location=videotestsrc.ogg ! oggdemux ! theoradec ! ffmpegcolorspace ! videoscale ! ximagesink
- * </programlisting>
- * Decode an Ogg/Theora and display the video using ximagesink. Since
+ * ]| Decode an Ogg/Theora and display the video using ximagesink. Since
  * ximagesink cannot perform scaling, the video scaling will be performed by
  * videoscale when you resize the video window.
  * To create the test Ogg/Theora file refer to the documentation of theoraenc.
- * </para>
- * <para>
- * <programlisting>
+ * |[
  * gst-launch -v filesrc location=videotestsrc.ogg ! oggdemux ! theoradec ! videoscale ! video/x-raw-yuv, width=50 ! xvimagesink
- * </programlisting>
- * Decode an Ogg/Theora and display the video using xvimagesink with a width of
- * 50.
- * </para>
+ * ]| Decode an Ogg/Theora and display the video using xvimagesink with a width
+ * of 50.
  * </refsect2>
  *
  * Last reviewed on 2006-03-02 (0.10.4)
diff --git a/gst/videotestsrc/gstvideotestsrc.c b/gst/videotestsrc/gstvideotestsrc.c
index 678d0e23..954c7c56 100644
--- a/gst/videotestsrc/gstvideotestsrc.c
+++ b/gst/videotestsrc/gstvideotestsrc.c
@@ -21,19 +21,15 @@
 /**
  * SECTION:element-videotestsrc
  *
- * <refsect2>
- * <para>
  * The videotestsrc element is used to produce test video data in a wide variaty
  * of formats. The video test data produced can be controlled with the "pattern"
  * property.
- * </para>
+ *
+ * <refsect2>
  * <title>Example launch line</title>
- * <para>
- * <programlisting>
+ * |[
  * gst-launch -v videotestsrc pattern=snow ! ximagesink
- * </programlisting>
- * Shows random noise in an X window.
- * </para>
+ * ]| Shows random noise in an X window.
  * </refsect2>
  */
 
diff --git a/gst/volume/gstvolume.c b/gst/volume/gstvolume.c
index c167f0fb..59e55f43 100644
--- a/gst/volume/gstvolume.c
+++ b/gst/volume/gstvolume.c
@@ -24,19 +24,15 @@
 /**
  * SECTION:element-volume
  *
- * <refsect2>
- * <para>
  * The volume element changes the volume of the audio data.
- * </para>
+ *
+ * <refsect2>
  * <title>Example launch line</title>
- * <para>
- * <programlisting>
+ * |[
  * gst-launch -v -m audiotestsrc ! volume volume=0.5 ! level ! fakesink silent=TRUE
- * </programlisting>
- * This pipeline shows that the level of audiotestsrc has been halved
+ * ]| This pipeline shows that the level of audiotestsrc has been halved
  * (peak values are around -6 dB and RMS around -9 dB) compared to
  * the same pipeline without the volume element.
- * </para>
  * </refsect2>
  */
 
diff --git a/sys/ximage/ximagesink.c b/sys/ximage/ximagesink.c
index 0b527028..0f530af4 100644
--- a/sys/ximage/ximagesink.c
+++ b/sys/ximage/ximagesink.c
@@ -20,14 +20,13 @@
 /**
  * SECTION:element-ximagesink
  *
- * <refsect2>
- * <para>
  * XImageSink renders video frames to a drawable (XWindow) on a local or remote
  * display. This element can receive a Window ID from the application through
  * the XOverlay interface and will then render video frames in this drawable.
  * If no Window ID was provided by the application, the element will create its
  * own internal window and render into it.
- * </para>
+ *
+ * <refsect2>
  * <title>Scaling</title>
  * <para>
  * As standard XImage rendering to a drawable is not scaled, XImageSink will use
@@ -37,12 +36,13 @@
  * or that an element generating the video frames can generate them with a 
  * different geometry. This mechanism is handled during buffer allocations, for
  * each allocation request the video sink will check the drawable geometry, look
- * at the
- * <link linkend="GstXImageSink--force-aspect-ratio">force-aspect-ratio</link>
- * property, calculate the geometry of desired video frames and then check that
- * the peer pad accept those new caps. If it does it will then allocate a buffer
- * in video memory with this new geometry and return it with the new caps.
+ * at the #GstXImageSink:force-aspect-ratio property, calculate the geometry of
+ * desired video frames and then check that the peer pad accept those new caps.
+ * If it does it will then allocate a buffer in video memory with this new
+ * geometry and return it with the new caps.
  * </para>
+ * </refsect2>
+ * <refsect2>
  * <title>Events</title>
  * <para>
  * XImageSink creates a thread to handle events coming from the drawable. There
@@ -55,11 +55,12 @@
  * paused, it will receive expose events from the drawable and draw the latest
  * frame with correct borders/aspect-ratio.
  * </para>
+ * </refsect2>
+ * <refsect2>
  * <title>Pixel aspect ratio</title>
  * <para>
  * When changing state to GST_STATE_READY, XImageSink will open a connection to
- * the display specified in the
- * <link linkend="GstXImageSink--display">display</link> property or the default
+ * the display specified in the #GstXImageSink:display property or the default
  * display if nothing specified. Once this connection is open it will inspect 
  * the display configuration including the physical display geometry and 
  * then calculate the pixel aspect ratio. When caps negotiation will occur, the
@@ -67,43 +68,34 @@
  * sure that incoming video frames will have the correct pixel aspect ratio for
  * this display. Sometimes the calculated pixel aspect ratio can be wrong, it is
  * then possible to enforce a specific pixel aspect ratio using the
- * <link linkend="GstXImageSink--pixel-aspect-ratio">pixel-aspect-ratio</link>
- * property.
+ * #GstXImageSink:pixel-aspect-ratio property.
  * </para>
+ * </refsect2>
+ * <refsect2>
  * <title>Examples</title>
- * <para>
- * Here is a simple pipeline to test reverse negotiation :
- * <programlisting>
+ * |[
  * gst-launch -v videotestsrc ! queue ! ximagesink
- * </programlisting>
- * When the test video signal appears you can resize the window and see that
- * scaled buffers of the desired size are going to arrive with a short delay.
- * This illustrates how buffers of desired size are allocated along the way.
- * If you take away the queue, scaling will happen almost immediately.
- * </para>
- * <para>
- * Here is a simple pipeline to test navigation events :
- * <programlisting>
+ * ]| A pipeline to test reverse negotiation. When the test video signal appears
+ * you can resize the window and see that scaled buffers of the desired size are
+ * going to arrive with a short delay. This illustrates how buffers of desired
+ * size are allocated along the way. If you take away the queue, scaling will
+ * happen almost immediately.
+ * |[
  * gst-launch -v videotestsrc ! navigationtest ! ffmpegcolorspace ! ximagesink
- * </programlisting>
+ * ]| A pipeline to test navigation events.
  * While moving the mouse pointer over the test signal you will see a black box
  * following the mouse pointer. If you press the mouse button somewhere on the 
  * video and release it somewhere else a green box will appear where you pressed
  * the button and a red one where you released it. (The navigationtest element
  * is part of gst-plugins-good.)
- * </para>
- * <para>
- * Here is a simple pipeline to test pixel aspect ratio :
- * <programlisting>
+ * |[
  * gst-launch -v videotestsrc ! video/x-raw-rgb, pixel-aspect-ratio=(fraction)4/3 ! videoscale ! ximagesink
- * </programlisting>
- * This is faking a 4/3 pixel aspect ratio caps on video frames produced by
+ * ]| This is faking a 4/3 pixel aspect ratio caps on video frames produced by
  * videotestsrc, in most cases the pixel aspect ratio of the display will be
  * 1/1. This means that videoscale will have to do the scaling to convert 
  * incoming frames to a size that will match the display pixel aspect ratio
  * (from 320x240 to 320x180 in this case). Note that you might have to escape 
  * some characters for your shell like '\(fraction\)'.
- * </para>
  * </refsect2>
  */
 
diff --git a/sys/xvimage/xvimagesink.c b/sys/xvimage/xvimagesink.c
index c9e7a3ce..966cb847 100644
--- a/sys/xvimage/xvimagesink.c
+++ b/sys/xvimage/xvimagesink.c
@@ -20,8 +20,6 @@
 /**
  * SECTION:element-xvimagesink
  *
- * <refsect2>
- * <para>
  * XvImageSink renders video frames to a drawable (XWindow) on a local display
  * using the XVideo extension. Rendering to a remote display is theorically
  * possible but i doubt that the XVideo extension is actually available when
@@ -29,17 +27,19 @@
  * application through the XOverlay interface and will then render video frames
  * in this drawable. If no Window ID was provided by the application, the
  * element will create its own internal window and render into it.
- * </para>
+ *
+ * <refsect2>
  * <title>Scaling</title>
  * <para>
  * The XVideo extension, when it's available, handles hardware accelerated
  * scaling of video frames. This means that the element will just accept
  * incoming video frames no matter their geometry and will then put them to the
- * drawable scaling them on the fly. Using the
- * <link linkend="GstXvImageSink--force-aspect-ratio">force-aspect-ratio</link>
+ * drawable scaling them on the fly. Using the #GstXvImageSink:force-aspect-ratio
  * property it is possible to enforce scaling with a constant aspect ratio,
  * which means drawing black borders around the video frame.
  * </para>
+ * </refsect2>
+ * <refsect2>
  * <title>Events</title>
  * <para>
  * XvImageSink creates a thread to handle events coming from the drawable. There
@@ -52,11 +52,12 @@
  * paused, it will receive expose events from the drawable and draw the latest
  * frame with correct borders/aspect-ratio.
  * </para>
+ * </refsect2>
+ * <refsect2>
  * <title>Pixel aspect ratio</title>
  * <para>
  * When changing state to GST_STATE_READY, XvImageSink will open a connection to
- * the display specified in the
- * <link linkend="GstXvImageSink--display">display</link> property or the
+ * the display specified in the #GstXvImageSink:display property or the
  * default display if nothing specified. Once this connection is open it will
  * inspect the display configuration including the physical display geometry and
  * then calculate the pixel aspect ratio. When receiving video frames with a
@@ -64,28 +65,24 @@
  * display the video frames correctly on display's pixel aspect ratio.
  * Sometimes the calculated pixel aspect ratio can be wrong, it is
  * then possible to enforce a specific pixel aspect ratio using the
- * <link linkend="GstXvImageSink--pixel-aspect-ratio">pixel-aspect-ratio</link>
- * property.
+ * #GstXvImageSink:pixel-aspect-ratio property.
  * </para>
+ * </refsect2>
+ * <refsect2>
  * <title>Examples</title>
- * <para>
- * Here is a simple pipeline to test hardware scaling :
- * <programlisting>
+ * |[
  * gst-launch -v videotestsrc ! xvimagesink
- * </programlisting>
+ * ]| A pipeline to test hardware scaling.
  * When the test video signal appears you can resize the window and see that
- * video frames are scaled through hardware (no extra CPU cost). You can try
- * again setting the force-aspect-ratio property to true and observe the borders
- * drawn around the scaled image respecting aspect ratio.
- * <programlisting>
+ * video frames are scaled through hardware (no extra CPU cost).
+ * |[
  * gst-launch -v videotestsrc ! xvimagesink force-aspect-ratio=true
- * </programlisting>
- * </para>
- * <para>
- * Here is a simple pipeline to test navigation events :
- * <programlisting>
+ * ]| Same pipeline with #GstXvImageSink:force-aspect-ratio property set to true
+ * You can observe the borders drawn around the scaled image respecting aspect
+ * ratio.
+ * |[
  * gst-launch -v videotestsrc ! navigationtest ! xvimagesink
- * </programlisting>
+ * ]| A pipeline to test navigation events.
  * While moving the mouse pointer over the test signal you will see a black box
  * following the mouse pointer. If you press the mouse button somewhere on the
  * video and release it somewhere else a green box will appear where you pressed
@@ -95,25 +92,17 @@
  * original video frame geometry so that the box can be drawn to the correct
  * position. This also handles borders correctly, limiting coordinates to the
  * image area
- * </para>
- * <para>
- * Here is a simple pipeline to test pixel aspect ratio :
- * <programlisting>
+ * |[
  * gst-launch -v videotestsrc ! video/x-raw-yuv, pixel-aspect-ratio=(fraction)4/3 ! xvimagesink
- * </programlisting>
- * This is faking a 4/3 pixel aspect ratio caps on video frames produced by
+ * ]| This is faking a 4/3 pixel aspect ratio caps on video frames produced by
  * videotestsrc, in most cases the pixel aspect ratio of the display will be
  * 1/1. This means that XvImageSink will have to do the scaling to convert
  * incoming frames to a size that will match the display pixel aspect ratio
  * (from 320x240 to 320x180 in this case). Note that you might have to escape
  * some characters for your shell like '\(fraction\)'.
- * </para>
- * <para>
- * Here is a test pipeline to test the colorbalance interface :
- * <programlisting>
+ * |[
  * gst-launch -v videotestsrc ! xvimagesink hue=100 saturation=-100 brightness=100
- * </programlisting>
- * </para>
+ * ]| Demonstrates how to use the colorbalance interface.
  * </refsect2>
  */