More documentation changes, a couple configure.in and Makefile.am fixes.

Original commit message from CVS:
More documentation changes, a couple configure.in and Makefile.am fixes.

configure.in

@@ -188,20 +188,20 @@ esac],
 AC_ARG_ENABLE(debug,
 [  --enable-debug               spews lots of useless info at runtime],
 [case "${enableval}" in
-  yes) use_debug=yes ;;
+  yes) USE_DEBUG=yes ;;
-  no)  use_debug=no ;;
+  no)  USE_DEBUG=no ;;
   *) AC_MSG_ERROR(bad value ${enableval} for --enable-debug) ;;
 esac], 
-[use_debug=no]) dnl Default value
+[USE_DEBUG=no]) dnl Default value
 
 AC_ARG_ENABLE(profiling,
 [  --enable-profiling           adds -pg to compiler commandline, for profiling],
 [case "${enableval}" in
-  yes) use_profiling=yes ;;
+  yes) USE_PROFILING=yes ;;
-  no)  use_profiling=no ;;
+  no)  UES_PROFILING=no ;;
   *) AC_MSG_ERROR(bad value ${enableval} for --enable-profiling) ;;
 esac], 
-[use_profiling=no]) dnl Default value
+[USE_PROFILING=no]) dnl Default value
 
 
 dnl ################################################

docs/Makefile.am

@@ -1,3 +1,7 @@
-SUBDIRS = gst
+if HAVE_GTK_DOC
+  SUBDIRS += gst manual
+endif
+
+DIST_SUBDIRS = gst manual
 
 #EXTRA_DIST = random slides

docs/gst/Makefile.am

@@ -39,11 +39,32 @@ tmpl_sources =				\
 	tmpl/gstxml.sgml		\
 	tmpl/plugin.sgml
 
+gstreamer_docdir = $(HTML_DIR)
+gstreamer_doc_DATA =		\
+	gstreamer.html		\
+	gstreamer.hierarchy	\
+	gstreamer.types		\
+	gstreamer-decl.txt	\
+	gstreamer-sections.txt
+
 SCANOBJS_FILES =		\
 	$(DOC_MODULE).signals	\
 	$(DOC_MODULE).hierarchy	\
 	$(DOC_MODULE).args
 
+if HAVE_GTK_DOC
+gstreamer.html: html/book1.html
+	-cd $(srcdir) && cp html/book1.html gstreamer.html
+else
+gstreamer.html:
+endif
+
+html/book1.html: sgml/gstreamer-doc.bottom
+	$(MAKE) html
+
+sgml/gstreamer-doc.bottom: $(tmpl_sources)
+	$(MAKE) sgml
+
 scanobj:
 	env CC="$(LIBTOOL) --mode=link $(CC)" CFLAGS="$(CFLAGS)" LDFLAGS="$(LDFLAGS)" \
 		gtkdoc-scanobj --module=$(DOC_MODULE) \
@@ -63,15 +84,34 @@ html:
 	-cd html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
 
 clean-local:
-	rm -f *~ *.bak *.hierarchy *.signals *.args *-unused.txt
+	rm -f *~ *.bak *.signals *-unused.txt
 
 maintainer-clean-local: clean
 	rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt 
 
 install-data-local:
-	install -d -m 0755 $(TARGET_DIR)
+	$(mkinstalldirs) $(DESTDIR)$(TARGET_DIR)
-	install -m 0644 html/*.html $(TARGET_DIR)
+	(installfiles=`echo $(srcdir)/html/*.html`; \
-	install -m 0644 html/index.sgml $(TARGET_DIR)
+	if test "$$installfiles" = '$(srcdir)/html/*.html'; \
-	gtkdoc-fixxref --module=$(DOC_MODULE) --html-dir=$(HTML_DIR)
+	then echo '-- Nothing to install' ; \
+	else \
+	  for i in $$installfiles; do \
+	    echo '-- Installing '$$i ; \
+	    $(INSTALL_DATA) $$i $(DESTDIR)$(TARGET_DIR); \
+	  done; \
+	  echo '-- Installing $(srcdir)/html/index.sgml' ; \
+	  $(INSTALL_DATA) $(srcdir)/html/index.sgml $(DESTDIR)$(TARGET_DIR); \
+	  echo '-- Fixing Crossreferences' ; \
+	  gtkdoc-fixxref --module=$(DOC_MODULE) --html-dir=$(HTML_DIR)|| true; \
+	fi)
+
+dist-hook:
+	mkdir $(distdir)/html
+	mkdir $(distdir)/sgml
+	mkdir $(distdir)/tmpl
+	-cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html
+	-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
+	-cp $(srcdir)/sgml/*.sgml $(distdir)/sgml
+	-cp $(srcdir)/sgml/*.bottom $(srcdir)/sgml/*.top $(distdir)/sgml
 
 .PHONY : html sgml templates scan

docs/gst/gstreamer-decl.txt

@@ -501,10 +501,10 @@ struct GstElementDetails {
 <STRUCT>
 <NAME>GstElementFactory</NAME>
 struct GstElementFactory {
-  gchar *name;
+  gchar *name;			/* name of element */
-  GtkType type;
+  GtkType type;			/* unique GtkType of element */
 
-  GstElementDetails *details;
+  GstElementDetails *details;	/* pointer to details struct */
 };
 </STRUCT>
 <FUNCTION>

docs/gst/gstreamer-sections.txt

@@ -25,6 +25,49 @@ GST_OBJECT_CLASS
 GST_IS_OBJECT_CLASS
 </SECTION>
 
+<SECTION>
+<FILE>gstelement</FILE>
+GstElement
+GstElementState
+GST_STATE
+GST_STATE_IS_SET
+GST_STATE_SET
+GST_STATE_UNSET
+GstElementDetails
+GstElementFactory
+GstElementLoopFunction
+<TITLE>GstElement</TITLE>
+gst_element_new
+gst_element_set_loop_function
+gst_element_set_name
+gst_element_get_name
+gst_element_set_manager
+gst_element_get_manager
+gst_element_add_pad
+gst_element_add_ghost_pad
+gst_element_get_pad
+gst_element_get_pad_list
+gst_element_connect
+gst_element_set_state
+gst_element_error
+gst_element_change_state
+gst_element_destroy
+gst_element_save_thyself
+gst_elementfactory_new
+gst_elementfactory_register
+gst_elementfactory_find
+gst_elementfactory_get_list
+gst_elementfactory_create
+gst_elementfactory_make
+gst_element_loopfunc_wrapper
+<SUBSECTION Standard>
+gst_element_get_type
+GST_TYPE_ELEMENT
+GST_IS_ELEMENT
+GST_ELEMENT_CLASS
+GST_IS_ELEMENT_CLASS
+</SECTION>
+
 <SECTION>
 <FILE>gstbin</FILE>
 GST_BIN
@@ -90,49 +133,6 @@ GST_CONNECTION_CLASS
 GST_IS_CONNECTION_CLASS
 </SECTION>
 
-<SECTION>
-<FILE>gstelement</FILE>
-GstElementState
-GST_STATE
-GST_STATE_IS_SET
-GST_STATE_SET
-GST_STATE_UNSET
-GST_ELEMENT
-GstElementDetails
-GstElementFactory
-GstElementLoopFunction
-<TITLE>GstElement</TITLE>
-gst_element_new
-gst_element_set_loop_function
-gst_element_set_name
-gst_element_get_name
-gst_element_set_manager
-gst_element_get_manager
-gst_element_add_pad
-gst_element_add_ghost_pad
-gst_element_get_pad
-gst_element_get_pad_list
-gst_element_connect
-gst_element_set_state
-gst_element_error
-gst_element_change_state
-gst_element_destroy
-gst_element_save_thyself
-gst_elementfactory_new
-gst_elementfactory_register
-gst_elementfactory_find
-gst_elementfactory_get_list
-gst_elementfactory_create
-gst_elementfactory_make
-gst_element_loopfunc_wrapper
-<SUBSECTION Standard>
-GST_TYPE_ELEMENT
-GST_IS_ELEMENT
-gst_element_get_type
-GST_ELEMENT_CLASS
-GST_IS_ELEMENT_CLASS
-</SECTION>
-
 <SECTION>
 <FILE>gstfilter</FILE>
 GST_FILTER
@@ -199,15 +199,15 @@ GST_IS_PAD_CLASS
 
 <SECTION>
 <FILE>gstpipeline</FILE>
-GST_PIPELINE
+GstPipeline
 <TITLE>GstPipeline</TITLE>
 gst_pipeline_new
 gst_pipeline_destroy
 gst_pipeline_iterate
 <SUBSECTION Standard>
+gst_pipeline_get_type
 GST_TYPE_PIPELINE
 GST_IS_PIPELINE
-gst_pipeline_get_type
 GST_PIPELINE_CLASS
 GST_IS_PIPELINE_CLASS
 </SECTION>

docs/gst/tmpl/gstelement.sgml

@@ -28,11 +28,18 @@ simpler to connect pads of two elements together.
 
 </para>
 
-<!-- ##### ENUM GstElementState ##### -->
+<!-- ##### STRUCT GstElement ##### -->
 <para>
 
 </para>
 
+
+<!-- ##### ENUM GstElementState ##### -->
+<para>
+This enum defines the standard states an element may be in.  GST_STATE_MAX
+is the highest bit that can be set, and is used internally.
+</para>
+
 @GST_STATE_COMPLETE: 
 @GST_STATE_RUNNING: 
 @GST_STATE_DISCOVERY: 
@@ -43,50 +50,43 @@ simpler to connect pads of two elements together.
 
 <!-- ##### MACRO GST_STATE ##### -->
 <para>
-
+This macro returns the entire state of the element.
 </para>
 
-@obj: 
+@obj: Element to return state for.
 
 
 <!-- ##### MACRO GST_STATE_IS_SET ##### -->
 <para>
-
+This macro checks to see if the given state is set.
 </para>
 
-@obj: 
+@obj: Element to check for state.
-@flag: 
+@flag: State to check for, must be a single bit in guint32.
 
 
 <!-- ##### MACRO GST_STATE_SET ##### -->
 <para>
-
+This macro sets the given state on the element.
 </para>
 
-@obj: 
+@obj: Element to set state of.
-@flag: 
+@flag: State to set, can be any number of bits in guint32.
 
 
 <!-- ##### MACRO GST_STATE_UNSET ##### -->
 <para>
-
+This macro unsets the given state on the element.
 </para>
 
-@obj: 
+@obj: Element to unset state of.
-@flag: 
+@flag: State to unset, can be any number of bits in guint32.
-
-
-<!-- ##### MACRO GST_ELEMENT ##### -->
-<para>
-
-</para>
-
-@obj: 
 
 
 <!-- ##### STRUCT GstElementDetails ##### -->
 <para>
-
+This struct is used to define public information about the element.  It
+describes the element, mostly for the benefit of editors.
 </para>
 
 @longname: 
@@ -98,7 +98,9 @@ simpler to connect pads of two elements together.
 
 <!-- ##### STRUCT GstElementFactory ##### -->
 <para>
-
+This factory is used when registering the element, and contains the name
+of the element, the GtkType value for it, as well as a pointer to the
+GstElementDetails struct for the element.
 </para>
 
 @name: 
@@ -107,10 +109,12 @@ simpler to connect pads of two elements together.
 
 <!-- ##### USER_FUNCTION GstElementLoopFunction ##### -->
 <para>
-
+This function type is used to specify a loop function for the element.  It
+is passed the element in question, and is expect to return only in error
+circumstances.
 </para>
 
-@element: 
+@element: The element in question.
 
 
 <!-- ##### FUNCTION gst_element_new ##### -->
@@ -320,16 +324,6 @@ simpler to connect pads of two elements together.
 @Returns: 
 
 
-<!-- ##### FUNCTION gst_element_loopfunc_wrapper ##### -->
-<para>
-
-</para>
-
-@argc: 
-@argv: 
-@Returns: 
-
-
 <!-- ##### SIGNAL GstElement::state-change ##### -->
 <para>
 

docs/gst/tmpl/gstpipeline.sgml

@@ -2,25 +2,28 @@
 GstPipeline
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Top-level bin with scheduling and pipeline management functionality.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+In almost all cases, you'll want to use a GstPipeline when creating a
+filter graph.  The GstPipeline will manage all the scheduling issues,
+including threading, as well as provide simple interfaces to common
+functions, like 'Play'.
 </para>
 
+<para>FIXME: this is entirely blue-sky</para>
+
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
 </para>
 
-<!-- ##### MACRO GST_PIPELINE ##### -->
+<!-- ##### STRUCT GstPipeline ##### -->
 <para>
 
 </para>
 
-@obj: 
-
 
 <!-- ##### FUNCTION gst_pipeline_new ##### -->
 <para>

gst/gst.c

@@ -26,8 +26,8 @@ extern gint _gst_trace_on;
  * @argc: pointer to application's argc
  * @argv: pointer to application's argv
  *
- * Initializes the GStreamer system, setting up internal lists and loading
+ * Initializes the GStreamer library, setting up internal path lists,
- * standard plugins.
+ * registering built-in elements, and loading standard plugins.
  */
 void gst_init(int *argc,char **argv[]) {
   GstTrace *gst_trace;

gst/gstelement.c

@@ -110,7 +110,7 @@ static void gst_element_init(GstElement *element) {
 /**
  * gst_element_new:
  *
- * Create a new element.
+ * Create a new element.  Should never be used, as it does no good.
  *
  * Returns: new element
  */
@@ -256,6 +256,14 @@ void gst_element_connect(GstElement *src,gchar *srcpadname,
   }
 }
 
+/**
+ * gst_element_error:
+ * @element: Element with the error
+ * @error: String describing the error
+ *
+ * This function is used internally by elements to signal an error
+ * condition.  It results in the "error" signal.
+ */
 void gst_element_error(GstElement *element,gchar *error) {
   g_error("error in element '%s': %s\n",element->name,error);
 
@@ -484,10 +492,26 @@ xmlNodePtr gst_element_save_thyself(GstElement *element,xmlNodePtr parent) {
   return self;
 }
 
+/**
+ * gst_element_set_manager:
+ * @element: Element to set manager of.
+ * @manager: Element to be the manager.
+ *
+ * Sets the manager of the element.  For internal use only, unless you're
+ * writing a new bin subclass.
+ */
 void gst_element_set_manager(GstElement *element,GstElement *manager) {
   element->manager = manager;
 }
 
+/**
+ * gst_element_get_manager:
+ * @element: Element to get manager of.
+ *
+ * Returns the manager of the element.
+ *
+ * Returns: Element's manager
+ */
 GstElement *gst_element_get_manager(GstElement *element) {
   return element->manager;
 }
@@ -498,6 +522,15 @@ int gst_element_loopfunc_wrapper(int argc,char **argv) {
   element->loopfunc(element);
 }
 
+/**
+ * gst_element_set_loop_function:
+ * @element: Element to set loop function of.
+ * @loop: Pointer to loop function.
+ *
+ * This sets the loop function for the element.  The function pointed to
+ * can deviate from the GstElementLoopFunction definition in type of
+ * pointer only.
+ */
 void gst_element_set_loop_function(GstElement *element,
                                    GstElementLoopFunction loop) {
   element->loopfunc = loop;

gst/gstelement.h

@@ -128,10 +128,10 @@ struct _GstElementDetails {
 };
 
 struct _GstElementFactory {
-  gchar *name;
+  gchar *name;			/* name of element */
-  GtkType type;
+  GtkType type;			/* unique GtkType of element */
 
-  GstElementDetails *details;
+  GstElementDetails *details;	/* pointer to details struct */
 };
 
 

gst/gstobject.c

@@ -88,7 +88,7 @@ static void gst_object_init(GstObject *object) {
 /**
  * gst_object_new:
  *
- * Create a new object with
+ * Create a new, empty object.  Not very useful, should never be used.
  *
  * Returns: new object
  */
@@ -150,6 +150,12 @@ void gst_object_unparent(GstObject *object) {
   gst_object_unref(object);
 }
 
+/**
+ * gst_object_ref:
+ * @object: GstObject to reference
+ *
+ * Increments the refence count on the object.
+ */
 #ifndef gst_object_ref
 void gst_object_ref (GstObject *object) {
   g_return_if_fail(object != NULL);
@@ -167,6 +173,13 @@ void gst_object_ref (GstObject *object) {
 }
 #endif /* gst_object_ref */
 
+/**
+ * gst_object_unref:
+ * @object: GstObject to unreference
+ *
+ * Decrements the refence count on the object.  If reference count hits
+ * zero, destroy the object.
+ */
 #ifndef gst_object_unref
 void gst_object_unref (GstObject *object) {
   int reftest;
@@ -209,6 +222,14 @@ void gst_object_unref (GstObject *object) {
 }
 #endif /* gst_object_unref */
 
+/**
+ * gst_object_sink:
+ * @object: GstObject to sink
+ *
+ * Removes floating reference on an object.  Any newly created object has
+ * a refcount of 1 and is FLOATING.  This function should be used when
+ * creating a new object to symbolically 'take ownership of' the object.
+ */
 #ifndef gst_object_sink
 void gst_object_sink(GstObject *object) {
   g_return_if_fail(object != NULL);

gst/gstpipeline.c

@@ -87,6 +87,15 @@ gst_pipeline_class_init(GstPipelineClass *klass) {
 static void gst_pipeline_init(GstPipeline *pipeline) {
 }
 
+
+/**
+ * gst_pipeline_new:
+ * @name: name of new pipeline
+ *
+ * Create a new pipeline with the given name.
+ *
+ * Returns: newly created GstPipeline
+ */
 GstPipeline *gst_pipeline_new(guchar *name) {
   GstPipeline *pipeline;
 
@@ -128,6 +137,12 @@ static gboolean gst_pipeline_change_state(GstElement *element,
 }
 
 
+/**
+ * gst_pipeline_iterate:
+ * @pipeline: GstPipeline to iterate
+ *
+ * Cause the pipeline's contents to be run through one full 'iteration'.
+ */
 void gst_pipeline_iterate(GstPipeline *pipeline) {
   g_return_if_fail(pipeline != NULL);
   g_return_if_fail(GST_IS_PIPELINE(pipeline));