diff --git a/docs/gst/gstreamer-docs.sgml b/docs/gst/gstreamer-docs.sgml
index ab9584e0e4..e13681fc43 100644
--- a/docs/gst/gstreamer-docs.sgml
+++ b/docs/gst/gstreamer-docs.sgml
@@ -162,6 +162,8 @@ with some more specialized elements.</para>
     &gstreamer-tree-index;
   </chapter>
 
+  <!-- this seems to be broken with current gtk-doc and the xml toolchain
   <index id="index"/>
+  -->
 
 </book>
diff --git a/docs/gst/tmpl/gst.sgml b/docs/gst/tmpl/gst.sgml
index c489172d9a..08add02b14 100644
--- a/docs/gst/tmpl/gst.sgml
+++ b/docs/gst/tmpl/gst.sgml
@@ -28,6 +28,8 @@ The <application>GStreamer</application> library should be initialized with gst_
 it can be used. You should pass a pointer to the main argc and argv variables so that GStreamer can 
 process its own command line options, as shown in the following example.
 
+<example>
+<title>Initializing the gstreamer libarary</title>
   <programlisting>
   int 
   main (int argc, char *argv[])
@@ -37,6 +39,7 @@ process its own command line options, as shown in the following example.
     ...
   }
   </programlisting>
+</example>
 </para>
 <para>
 It's allowed to pass two NULL pointers to gst_init() in case you don't want to pass the command
@@ -46,6 +49,8 @@ line args to GStreamer.
 <para>
 You can also use a popt table to initialize your own parameters as shown in the next code 
 fragment:
+<example>
+<title>Initializing own parameters when initializing gstreamer</title>
   <programlisting>
   static gboolean stats = FALSE;
   ...
@@ -65,6 +70,7 @@ fragment:
     ...
   }
   </programlisting>
+</example>
 </para>
 <para>
   Use gst_version() to query the library version at runtime or use the GST_VERSION_* macros
diff --git a/docs/gst/tmpl/gstbuffer.sgml b/docs/gst/tmpl/gstbuffer.sgml
index 1000d8a74c..34245560fa 100644
--- a/docs/gst/tmpl/gstbuffer.sgml
+++ b/docs/gst/tmpl/gstbuffer.sgml
@@ -17,7 +17,9 @@ Buffers are usually created with gst_buffer_new(). After a buffer has been
 created one will typically allocate memory for it and set the size of the 
 buffer data.  The following example creates a buffer that can hold a given
 video frame with a given width, height and bits per plane.
-<programlisting>
+<example>
+<title>Creating a buffer for a video frame</title>
+  <programlisting>
   GstBuffer *buffer;
   gint size, width, height, bpp;
 
@@ -29,7 +31,8 @@ video frame with a given width, height and bits per plane.
   GST_BUFFER_SIZE (buffer) = size;
   GST_BUFFER_DATA (buffer) = g_alloc (size);
   ...
-</programlisting>
+  </programlisting>
+</example>
 </para>
 <para>
 Alternatively, use gst_buffer_new_and_alloc() 
diff --git a/docs/gst/tmpl/gstevent.sgml b/docs/gst/tmpl/gstevent.sgml
index 8c82e1a6e6..c9e12a9009 100644
--- a/docs/gst/tmpl/gstevent.sgml
+++ b/docs/gst/tmpl/gstevent.sgml
@@ -162,10 +162,10 @@ The different types of seek events. When constructing a seek event a format,
 a seek method and optional flags are OR-ed together. The seek event is then
 inserted into the graph with #gst_pad_send_event() or #gst_element_send_event().
 
- <informalexample>
-  Following example illustrates how to insert a seek event (1 second in the stream)
-  in a pipeline.
- 
+Following example illustrates how to insert a seek event (1 second in the stream)
+in a pipeline.
+<example>
+<title>Insertion of a seek event into a pipeline</title>
   <programlisting>
   gboolean res;
   GstEvent *event;
@@ -181,7 +181,7 @@ inserted into the graph with #gst_pad_send_event() or #gst_element_send_event().
     g_warning ("seek failed");
   }
   </programlisting>
- </informalexample>
+</example>
 </para>
 
 @GST_SEEK_METHOD_CUR: Seek to an relative position