diff --git a/gst/replaygain/gstrganalysis.c b/gst/replaygain/gstrganalysis.c
index 613c087679..982c8a7f41 100644
--- a/gst/replaygain/gstrganalysis.c
+++ b/gst/replaygain/gstrganalysis.c
@@ -22,10 +22,8 @@
 
 /**
  * SECTION:element-rganalysis
- * @see_also: <link linkend="GstRgVolume">rgvolume</link>
+ * @see_also: #GstRgVolume
  *
- * <refsect2>
- * <para>
  * This element analyzes raw audio sample data in accordance with the proposed
  * <ulink url="http://replaygain.org">ReplayGain standard</ulink> for
  * calculating the ideal replay gain for music tracks and albums.  The element
@@ -35,8 +33,7 @@
  * posted on the message bus with a tag message.  The EOS event is forwarded as
  * normal afterwards.  Result tag lists at least contain the tags
  * #GST_TAG_TRACK_GAIN, #GST_TAG_TRACK_PEAK and #GST_TAG_REFERENCE_LEVEL.
- * </para>
- * <para>
+ * 
  * Because the generated metadata tags become available at the end of streams,
  * downstream muxer and encoder elements are normally unable to save them in
  * their output since they generally save metadata in the file header.
@@ -45,28 +42,27 @@
  * needed for <link linkend="GstRgAnalysis--num-tracks">album processing</link>
  * since the album gain and peak values need to be associated with all tracks of
  * an album, not just the last one.
- * </para>
+ * 
+ * <refsect2>
  * <title>Example launch lines</title>
- * <para>Analyze a simple test waveform:</para>
- * <programlisting>
+ * |[
  * gst-launch -t audiotestsrc wave=sine num-buffers=512 ! rganalysis ! fakesink
- * </programlisting>
- * <para>Analyze a given file:</para>
- * <programlisting>
- * gst-launch -t filesrc location="Some file.ogg" ! decodebin \
+ * ]| Analyze a simple test waveform
+ * |[
+ * gst-launch -t filesrc location=filename.ext ! decodebin \
  *     ! audioconvert ! audioresample ! rganalysis ! fakesink
- * </programlisting>
- * <para>Analyze the pink noise reference file:</para>
- * <programlisting>
+ * ]| Analyze a given file
+ * |[
  * gst-launch -t gnomevfssrc location=http://replaygain.hydrogenaudio.org/ref_pink.wav \
  *     ! wavparse ! rganalysis ! fakesink
- * </programlisting>
+ * ]| Analyze the pink noise reference file
  * <para>
  * The above launch line yields a result gain of +6 dB (instead of the expected
- * +0 dB).  This is not in error, refer to the <link
- * linkend="GstRgAnalysis--reference-level">reference-level</link> property
- * documentation for more information.
+ * +0 dB).  This is not in error, refer to the #GstRgAnalysis:reference-level
+ * property documentation for more information.
  * </para>
+ * </refsect2>
+ * <refsect2>
  * <title>Acknowledgements</title>
  * <para>
  * This element is based on code used in the <ulink
diff --git a/gst/replaygain/gstrglimiter.c b/gst/replaygain/gstrglimiter.c
index d474b26edb..43c7b01a94 100644
--- a/gst/replaygain/gstrglimiter.c
+++ b/gst/replaygain/gstrglimiter.c
@@ -22,22 +22,20 @@
 
 /**
  * SECTION:element-rglimiter
- * @see_also: <link linkend="GstRgVolume">rgvolume</link>
+ * @see_also: #GstRgVolume
  *
- * <refsect2>
- * <para>
  * This element applies signal compression/limiting to raw audio data.  It
  * performs strict hard limiting with soft-knee characteristics, using a
  * threshold of -6 dB.  This type of filter is mentioned in the proposed <ulink
  * url="http://replaygain.org">ReplayGain standard</ulink>.
- * </para>
+ * 
+ * <refsect2>
  * <title>Example launch line</title>
- * <para>Playback of a file:</para>
- * <programlisting>
- * gst-launch filesrc location="Filename.ext" ! decodebin ! audioconvert \
+ * |[
+ * gst-launch filesrc location=filename.ext ! decodebin ! audioconvert \
  *            ! rgvolume pre-amp=6.0 headroom=10.0 ! rglimiter \
  *            ! audioconvert ! audioresample ! alsasink
- * </programlisting>
+ * ]|Playback of a file
  * </refsect2>
  */
 
diff --git a/gst/replaygain/gstrgvolume.c b/gst/replaygain/gstrgvolume.c
index dbcfaf5d8f..41fe441d4c 100644
--- a/gst/replaygain/gstrgvolume.c
+++ b/gst/replaygain/gstrgvolume.c
@@ -22,11 +22,8 @@
 
 /**
  * SECTION:element-rgvolume
- * @see_also: <link linkend="GstRgLimiter">rglimiter</link>,
- *            <link linkend="GstRgAnalysis">rganalysis</link>
+ * @see_also: #GstRgLimiter, #GstRgAnalysis
  *
- * <refsect2>
- * <para>
  * This element applies volume changes to streams as lined out in the proposed
  * <ulink url="http://replaygain.org">ReplayGain standard</ulink>.  It
  * interprets the ReplayGain meta data tags and carries out the adjustment (by
@@ -41,21 +38,20 @@
  * The information carried by these tags must have been calculated beforehand by
  * performing the ReplayGain analysis.  This is implemented by the <link
  * linkend="GstRgAnalysis">rganalysis</link> element.
- * </para>
- * <para>
+ * 
  * The signal compression/limiting recommendations outlined in the proposed
  * standard are not implemented by this element.  This has to be handled by
  * separate elements because applications might want to have additional filters
  * between the volume adjustment and the limiting stage.  A basic limiter is
  * included with this plugin: The <link linkend="GstRgLimiter">rglimiter</link>
  * element applies -6 dB hard limiting as mentioned in the ReplayGain standard.
- * </para>
+ * 
+ * <refsect2>
  * <title>Example launch line</title>
- * <para>Playback of a file:</para>
- * <programlisting>
- * gst-launch filesrc location="Filename.ext" ! decodebin ! audioconvert \
+ * |[
+ * gst-launch filesrc location=filename.ext ! decodebin ! audioconvert \
  *     ! rgvolume ! audioconvert ! audioresample ! alsasink
- * </programlisting>
+ * ]| Playback of a file
  * </refsect2>
  */