backed out the change of gst.h added some comment about building docs to README

Original commit message from CVS:
backed out the change of gst.h
added some comment about building docs to README

docs/README

@@ -29,7 +29,7 @@ OVERVIEW
     - in .fig
     - in .png (and maybe others)
 * We want to generate docs in HTML, PS and PDF
-* We want to use xmlto to generate these
+* We want to use xml to to generate these
 
 CONVENTIONS
 -----------
@@ -92,9 +92,17 @@ GTK-DOC NOTES
 
 * files under CVS control:
   - Makefile.am
-  - gstreamer-sections.txt, gstreamer.types.in, gstreamer-docs.sgml
+  - gstreamer-sections.txt
+    describes which symbols later appear on one api-doc page
+    configure which symbols are shown/invisible/private
+  - gstreamer.types
+    the types file lists all get_type() functions that register the GObject types
+  - gstreamer-docs.sgml
+    defines the overall structure of the api documentation
   - tmpl/
-  (FIXME: describe what each of these files do)
+    - only add the file to CVS if you have at least filled the short description
+      (filename corresponds to the <FILE> tag in the sections file)
+    - document as much as possible in the source (*.c files)
 
 * what to do when adding a new piece of API:
   - add both an entity and use the entity in gstreamer-docs.sgml
@@ -122,8 +130,8 @@ GTK-DOC NOTES
   - Warning: multiple "IDs" for constraint linkend: gst-tag-register.
     - check if gst_tag_register is listed more than once in -sections.txt
 
-WBSITE DOCUMENTATION
+WEBSITE DOCUMENTATION
-====================
+=====================
 
 Updating the online documentation is pretty simple.
 Make sure that you

docs/gst/gstreamer-docs.sgml

@@ -44,9 +44,6 @@
 <!ENTITY GstValue SYSTEM "xml/gstvalue.xml">
 <!ENTITY GstXML SYSTEM "xml/gstxml.xml">
 <!ENTITY GstQueue SYSTEM "xml/gstqueue.xml">
-<!-- these are elements without API docs
-...
--->
 
 <!ENTITY GstAggregator SYSTEM "xml/gstaggregator.xml">
 <!ENTITY GstFakeSrc SYSTEM "xml/gstfakesrc.xml">
@@ -101,9 +98,6 @@ with some more specialized elements.</para>
     &GstPluginFeature;
     &GstProbe;
     &GstQuery;
-<!-- no API docs
-...
--->
     &GstQueue;
     &GstRegistry;
     &GstRegistryPool;

docs/gst/gstreamer-sections.txt

@@ -1,6 +1,5 @@
 <SECTION>
 <FILE>gstbin</FILE>
-GST_BIN_CLASS
 GstBinFlags
 <TITLE>GstBin</TITLE>
 gst_bin_new
@@ -24,6 +23,7 @@ GST_BIN
 GST_IS_BIN
 GST_TYPE_BIN
 gst_bin_get_type
+GST_BIN_CLASS
 GST_IS_BIN_CLASS
 GST_BIN_GET_CLASS
 </SECTION>

docs/gst/gstreamer.types

@@ -1,4 +1,5 @@
 #include <gst/gst.h>
+#include <gst/gstqueue.h>
 
 gst_object_get_type
 gst_element_get_type
@@ -18,4 +19,3 @@ gst_index_get_type
 gst_index_factory_get_type
 gst_xml_get_type
 gst_queue_get_type
-gst_xml_registry_get_type

docs/gst/tmpl/gstbin.sgml

@@ -55,14 +55,6 @@ clock providers in the bin.
 
 </para>
 
-<!-- ##### MACRO GST_BIN_CLASS ##### -->
-<para>
-
-</para>
-
-@klass: 
-
-
 <!-- ##### ENUM GstBinFlags ##### -->
 <para>
 Flags for a bin.

docs/gst/tmpl/gstelement.sgml

@@ -124,6 +124,8 @@ and gst_element_set_clock().  You can wait for the clock to reach a given
 
 </para>
 
+@:
+
 @gstelement: the object which received the signal.
 
 <!-- ##### SIGNAL GstElement::pad-removed ##### -->

gst/gst.h

@@ -47,7 +47,6 @@
 #include <gst/gstpad.h>
 #include <gst/gstpipeline.h>
 #include <gst/gstplugin.h>
-#include <gst/gstqueue.h>
 #include <gst/gstscheduler.h>
 #include <gst/gststructure.h>
 #include <gst/gstsystemclock.h>
@@ -65,7 +64,6 @@
 #include <gst/gstparse.h>
 #include <gst/gstregistry.h>
 #include <gst/gstregistrypool.h>
-#include <gst/registries/gstxmlregistry.h>
 
 /* API compatibility stuff */
 #include <gst/gstcompat.h>