docs/: restructure so that common stuff is shown first

Original commit message from CVS:
* docs/Makefile.am:
* docs/manual/elements-api.xml:
restructure so that common stuff is shown first
* docs/manual/init-api.xml:
convert to examples
* docs/manual/manual.xml:
* docs/manuals.mak:
* docs/url.entities:
link to API on the website, possibly override later in build
* examples/manual/.cvsignore:
ignore more
* examples/manual/Makefile.am:
add more examples
* examples/manual/extract.pl:
error out on failure

7 files changed, 147 insertions, 150 deletions

diff --git a/docs/Makefile.am b/docs/Makefile.am
index cf9cfc4aa..ef24de6b8 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -18,7 +18,7 @@ DIST_SUBDIRS = gst faq manual pwg libs plugins xsl
 
 EXTRA_DIST = \
 	slides manuals.mak htmlinstall.mak upload.mak \
-	image-png image-pdf image-eps version.entities.in
+	image-png image-pdf image-eps url.entities version.entities.in
 
 upload:
 	@if test "x$(SUBDIRS_DOCS)" != x; then for a in $(SUBDIRS_DOCS); do cd $$a; make upload; cd ..; done; fi
diff --git a/docs/manual/basics-init.xml b/docs/manual/basics-init.xml
deleted file mode 100644
index 0b233fd38..000000000
--- a/docs/manual/basics-init.xml
+++ /dev/null
@@ -1,95 +0,0 @@
-<chapter id="chapter-initialisation">
-  <title>Initializing <application>GStreamer</application></title>
-  <para> 
-    When writing a <application>GStreamer</application> application, you can
-    simply include <filename class='headerfile'>gst/gst.h</filename> to get 
-    access to the library functions.
-  </para> 
-  <para> 
-    Before the <application>GStreamer</application> libraries can be used,
-    <function>gst_init</function> has to be called from the main application. 
-    This call will perform the necessary initialization of the library as
-    well as parse the GStreamer-specific command line options.
-  </para>
-  <para> 
-    A typical program would have code to initialize GStreamer that
-    looks like this:
-  </para>
-
-  <programlisting>
-/* example-begin init.c */
-
-#include &lt;gst/gst.h&gt;
-
-int
-main (int argc, char *argv[])
-{
-  guint major, minor, micro;
-
-  gst_init (&amp;argc, &amp;argv);
-
-  gst_version (&amp;major, &amp;minor, &amp;micro);
-  printf ("This program is linked against GStreamer %d.%d.%d\n",
-          major, minor, micro);
-
-  return 0;
-}
-/* example-end init.c */
-  </programlisting>
-  <para>
-    Use the <symbol>GST_VERSION_MAJOR</symbol>,
-    <symbol>GST_VERSION_MINOR</symbol> and <symbol>GST_VERSION_MICRO</symbol>
-    macros to get the <application>GStreamer</application> version you are
-    building against, or use the function <function>gst_version</function>
-    to get the version your application is linked against.
-<!--    FIXME: include an automatically generated list of these options. -->
-  </para>
-  <para>
-    It is also possible to call the <function>gst_init</function> function
-    with two <symbol>NULL</symbol> arguments, in which case no command line
-    options will be parsed by <application>GStreamer</application>.
-  </para>
-  <sect1>
-    <title>The popt interface</title>
-    <para>
-You can also use a popt table to initialize your own parameters as shown in the
-next example:
-    </para>
-    <programlisting>
-/* example-begin popt.c */
-
-#include &lt;gst/gst.h&gt;
-
-int
-main(int argc, char *argv[])
-{
-  gboolean silent = FALSE;
-  gchar *savefile = NULL;
-  struct poptOption options[] = {
-    {"silent",	's',  POPT_ARG_NONE|POPT_ARGFLAG_STRIP,   &amp;silent,   0,
-     "do not output status information", NULL},
-    {"output",	'o',  POPT_ARG_STRING|POPT_ARGFLAG_STRIP, &amp;savefile, 0,
-     "save xml representation of pipeline to FILE and exit", "FILE"},
-    POPT_TABLEEND
-  };
-
-  gst_init_with_popt_table (&amp;argc, &amp;argv, options);
-
-  printf ("Run me with --help to see the Application options appended.\n");
-
-  return 0;
-}
-/* example-end popt.c */
-    </programlisting>
-    <para>
-      As shown in this fragment, you can use a <ulink
-      url="http://developer.gnome.org/doc/guides/popt/"
-      type="http">popt</ulink> table to define your application-specific
-      command line options, and pass this table to the
-      function <function>gst_init_with_popt_table</function>. Your
-      application options will be parsed in addition to the standard
-      <application>GStreamer</application> options.
-    </para>
-  </sect1>
-
-</chapter>
diff --git a/docs/manual/elements-api.xml b/docs/manual/elements-api.xml
index b51d490fe..c9c80fe1f 100644
--- a/docs/manual/elements-api.xml
+++ b/docs/manual/elements-api.xml
@@ -2,66 +2,106 @@
   <title>Elements</title>
   <sect1 id="section-elements-create">
     <title>Creating a GstElement</title>
+    <para>
+The simplest way to create an element is to use
+<ulink type="http"
+       url="&URLAPI;GstElementFactory.html#gst-element-factory-make">
+<function>gst_element_factory_make</function>
+</ulink>.
+This function takes a factory name and an element name for the newly created
+element.
+ The name of the
+element is something you can use later on to look up the element in
+a bin, for example. You can pass <symbol>NULL</symbol> as the name
+argument to get a unique, default name.
+    </para>
+    <para>
+When you don't need the element anymore, you need to unref it using
+<ulink type="http"
+       url="&URLAPI;GstObject.html#gst-object-unref">
+<function>gst_object_unref</function></ulink>.
+This decreases the reference count for the element by 1.  An element has a
+refcount of 1 when it gets created.  An element gets destroyed completely
+when the refcount is decreased to 0.
+    </para>
+    <para>
+The following example &EXAFOOT; shows how to create an element named
+<emphasis>source</emphasis> from the element factory named
+<emphasis>fakesrc</emphasis>.  It checks if the creation succeeded.
+After checking, it unrefs the element.
+    </para>
+    <programlisting>
+<![CDATA[
+/* example-begin elementmake.c */
+
+#include <gst/gst.h>
+
+int
+main (int argc, char *argv[])
+{
+  GstElement *element;
+
+  gst_init (&argc, &argv);
+
+  element = gst_element_factory_make ("fakesrc", "source");
+
+  if (!element) {
+    g_error ("Could not create an element from 'fakesrc' factory.\n");
+  }
+
+  gst_object_unref (GST_OBJECT (element));
+
+  return 0;
+}
+
+/* example-end elementmake.c */
+]]>
+    </programlisting>
     <para> 
-      A <ulink type="http"
-      url="../../gstreamer/html/GstElement.html"><classname>GstElement</classname></ulink>
-      object is created from a factory.
-      To create an element, you have to get access to a
-      <ulink type="http" url="../../gstreamer/html/GstElementFactory.html">
-      <classname>GstElementFactory</classname></ulink> object using a unique
-      factory name.
+<function>gst_element_factory_make</function> is actually a shorthand
+for a combination of two functions.
+A
+<ulink type="http"
+       url="&URLAPI;GstElement.html"><classname>GstElement</classname></ulink>
+object is created from a factory.
+To create the element, you have to get access to a
+<ulink type="http" url="&URLAPI;GstElementFactory.html">
+<classname>GstElementFactory</classname></ulink>
+object using a unique factory name.
+This is done with
+<ulink type="http"
+       url="&URLAPI;GstElementFactory.html#gst-element-factory-find">
+<function>gst_element_factory_find</function></ulink>.
     </para> 
     <para> 
-      The following code example is used to get a factory that can be used 
-      to create the 'mad' element, an mp3 decoder.
+The following code fragment is used to get a factory that can be used 
+to create the <emphasis>fakesrc</emphasis> element, a fake data source.
     </para> 
     <programlisting>
  GstElementFactory *factory;
 
- factory = gst_element_factory_find ("mad");
+ factory = gst_element_factory_find ("fakesrc");
     </programlisting>
     <para> 
-      Once you have the handle to the element factory, you can create a 
-      real element with the following code fragment:
+Once you have the handle to the element factory, you can create a 
+real element with the following code fragment:
     </para> 
     <programlisting>
  GstElement *element;
 
- element = gst_element_factory_create (factory, "decoder");
+ element = gst_element_factory_create (factory, "source");
     </programlisting>
     <para>
-      <function>gst_element_factory_create</function> will use the element
-      factory to create an element with the given name. The name of the
-      element is something you can use later on to look up the element in
-      a bin, for example. You can pass <symbol>NULL</symbol> as the name
-      argument to get a unique, default name.
-    </para>
-    <para>
-      A simple shortcut exists for creating an element from a factory. The
-      following example creates an element named "decoder" from the element
-      factory named "mad". This convenience function is most widely used to
-      create an element.
+<ulink type="http"
+       url="&URLAPI;GstElementFactory.html#gst-element-factory-create">
+<function>gst_element_factory_create</function></ulink>
+will use the element factory to create an element with the given name.
     </para>
-    <programlisting>
- GstElement *element;
-
- element = gst_element_factory_make ("mad", "decoder");
-    </programlisting>
-    <para> 
-      When you don't need the element anymore, you need to unref it, as shown in the following
-      example. 
-    </para> 
-    <programlisting>
- GstElement *element;
-
-  ...
- gst_object_unref (GST_OBJECT (element));
-    </programlisting>
   </sect1>
   <sect1 id="section-elements-properties">
     <title>GstElement properties</title>
     <para> 
-      A <ulink type="http" url="../../gstreamer/html/GstElement.html">
+      A <ulink type="http" url="&URLAPI;GstElement.html">
       <classname>GstElement</classname></ulink> can have several properties
       which are implemented using standard <classname>GObject</classname>
       properties. The usual <classname>GObject</classname> methods to query,
@@ -69,7 +109,7 @@
       are therefore supported.
     </para> 
     <para> 
-      Every <ulink type="http" url="../../gstreamer/html/GstElementFactory.html">
+      Every <ulink type="http" url="&URLAPI;GstElementFactory.html">
       <classname>GstElement</classname></ulink> inherits at least
       one property of its parent <classname>GstObject</classname>:
       the "name" property. This is the name you provide to the
@@ -81,16 +121,31 @@
       <classname>GObject</classname> property mechanism as shown below.
     </para> 
     <programlisting>
- GstElement *element;
- GValue value = { 0, }; /* initialize the GValue for g_object_get() */
+<![CDATA[
+/* example-begin elementget.c */
+
+#include <gst/gst.h>
+
+int
+main (int argc, char *argv[])
+{
+  GstElement *element;
+  GValue value = { 0, }; /* initialize the GValue for g_object_get() */
+
+  gst_init (&argc, &argv);
+  element = gst_element_factory_make ("fakesrc", "source");
+  g_object_set (G_OBJECT (element), "name", "mysource", NULL);
+
+  g_value_init (&value, G_TYPE_STRING);
+  g_object_get_property (G_OBJECT (element), "name", &value);
+
+  g_print ("The name of the source is '%s'.\n", g_value_get_string (&value));
 
- element = gst_element_factory_make ("mad", "decoder");
- g_object_set (G_OBJECT (element), "name", "mydecoder", NULL);
- ...
+  return 0;
+}
 
- g_value_init (&amp;value, G_TYPE_STRING);
- g_object_get_property (G_OBJECT (element), "name", &amp;value);
- ...
+/* example-end elementget.c */
+]]>
     </programlisting>
     <para> 
       Most plugins provide additional properties to provide more information
@@ -113,7 +168,7 @@
   <sect1 id="section-elements-signals">
     <title>GstElement signals</title>
     <para> 
-      A <ulink type="http" url="../../gstreamer/html/GstElementFactory.html">
+      A <ulink type="http" url="&URLAPI;gstreamer/html/GstElementFactory.html">
       <classname>GstElement</classname></ulink> also provides various 
       <classname>GObject</classname> signals that can be used as a flexible
       callback mechanism.
diff --git a/docs/manual/init-api.xml b/docs/manual/init-api.xml
index 0b233fd38..054b7b519 100644
--- a/docs/manual/init-api.xml
+++ b/docs/manual/init-api.xml
@@ -12,14 +12,17 @@
     well as parse the GStreamer-specific command line options.
   </para>
   <para> 
-    A typical program would have code to initialize GStreamer that
+    A typical program
+    &EXAFOOT;
+    would have code to initialize GStreamer that
     looks like this:
   </para>
 
   <programlisting>
+<![CDATA[
 /* example-begin init.c */
 
-#include &lt;gst/gst.h&gt;
+#include <gst/gst.h>
 
 int
 main (int argc, char *argv[])
@@ -35,6 +38,7 @@ main (int argc, char *argv[])
   return 0;
 }
 /* example-end init.c */
+]]>
   </programlisting>
   <para>
     Use the <symbol>GST_VERSION_MAJOR</symbol>,
diff --git a/docs/manual/manual.xml b/docs/manual/manual.xml
index a2351956e..842710842 100644
--- a/docs/manual/manual.xml
+++ b/docs/manual/manual.xml
@@ -5,6 +5,18 @@
 %image-entities;
 <!ENTITY % version-entities SYSTEM "version.entities">
 %version-entities;
+<!ENTITY % url-entities SYSTEM "url.entities">
+%url-entities;
+
+<!ENTITY EXAFOOT "
+<footnote>
+<para>
+The code for this example is automatically extracted from
+the documentation and built under <filename>examples/manual</filename>
+in the GStreamer tarball.
+</para>
+</footnote>
+">
 
 <!-- Part 1: Overview -->
 <!ENTITY INTRO SYSTEM "intro.xml">
@@ -141,7 +153,8 @@
 
 <!-- ############ Basic concepts - part ############# -->
 
-  <part id="part-basic-concepts"><title>Basic Concepts</title>
+  <part id="part-basic-concepts">
+    <title>Basic Concepts</title>
     <partintro>
       <para> 
         We will first describe the basics of
@@ -170,7 +183,23 @@
   </part>
 
 <!-- ############ Basic API - part ############# -->
-  <part id="part-basic-api"><title>Basic API</title>
+  <part id="part-basic-api">
+    <title>Basic API</title>
+    <partintro>
+      <para> 
+This chapter will describe the basics of programming with GStreamer.
+Most of the concepts from the previous chapter will be illustrated with code
+fragments.
+     </para>
+      <para> 
+Most of the code examples in this manual are automatically extracted as part
+of the build process of the GStreamer tarball.  After building GStreamer from
+source, you will find the examples in <filename>examples/manual</filename>.
+Each example has a comment on the first line giving the name of the file
+it will be extracted as.
+     </para>
+     </partintro>
+
       &INIT-API;
 
       &ELEMENTS-API;
diff --git a/docs/manuals.mak b/docs/manuals.mak
index dd90317a8..272debcc5 100644
--- a/docs/manuals.mak
+++ b/docs/manuals.mak
@@ -85,6 +85,7 @@ $(BUILDDIR)/$(MAIN): $(XML) $(CSS) $(EXTRA_SOURCES)
 	@for a in $(XML); do cp $(srcdir)/$$a $(BUILDDIR); done
 	@for a in $(CSS); do cp $(srcdir)/$$a $(BUILDDIR); done
 	@cp ../version.entities $(BUILDDIR)
+	@cp ../url.entities $(BUILDDIR)
 
 html/index.html: $(BUILDDIR)/$(MAIN) $(PNG_BUILT) $(FIG_SRC)
 	@make check-local
diff --git a/docs/url.entities b/docs/url.entities
new file mode 100644
index 000000000..9bfb50e9e
--- /dev/null
+++ b/docs/url.entities
@@ -0,0 +1,3 @@
+<!-- These entities could be overridden for installed docs -->
+<!ENTITY URLAPI "http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/">
+