adding a section on gnome integration

Original commit message from CVS:
adding a section on gnome integration

docs/manual/appendix-gnome.xml

@@ -0,0 +1,74 @@
+<chapter id="cha-gnome">
+  <title>Gnome integration</title>
+  <para> 
+    GStreamer is fairly easy to integrate with Gnome applications.
+    GStreamer uses libxml 2.0, GLib 2.0 and popt, as do all other
+    Gnome applications.
+    There are however some basic issues you need to address in your Gnome
+    applications.
+  </para>
+ 
+  <sect1>
+    <title>Command line options</title>
+    <para>
+      Gnome applications call gnome_program_init () to parse command-line
+      options and initialize the necessary gnome modules.
+      GStreamer applications normally call gst_init (&amp;argc, &amp;argv) to
+      do the same for GStreamer.
+    </para>
+    <para>
+      Each of these two swallows the program options passed to the program,
+      so we need a different way to allow both Gnome and GStreamer to parse
+      the command-line options.  This is shown in the following example.
+    </para>  
+
+    <programlisting>
+/* example-begin gnome.c */
+#include &lt;gnome.h&gt;
+#include &lt;gst/gst.h&gt;
+
+int
+main (int argc, char **argv)
+{
+  struct poptOption options[] = {
+          { NULL, '\0', POPT_ARG_INCLUDE_TABLE, NULL, 0, "GStreamer", NULL },
+            POPT_TABLEEND
+        };
+  GnomeProgram *program;
+  poptContext context;
+  const gchar **argvn;
+
+  options[0].arg = (void *) gst_init_get_popt_table ();
+  if (! (program = gnome_program_init (PACKAGE, VERSION, LIBGNOMEUI_MODULE,
+                                       argc, argv,
+                                       GNOME_PARAM_POPT_TABLE, options,
+                                       NULL)))
+  g_error ("gnome_program_init failed");
+
+  g_object_get (program, "popt-context", &amp;context, NULL);
+  argvn = poptGetArgs (context);
+  if (!argvn) {
+    g_print ("Run this example with some arguments to see how it works.\n");
+    return 0;
+  }
+
+  while (*argvn) {
+    g_print ("argument: %s\n", *argvn);
+    ++argvn;
+  }
+
+  return 0;
+}
+/* example-end gnome.c */
+    </programlisting>
+    <para>
+      If you try out this program, you will see that when called with
+      --help, it will print out both GStreamer and Gnome help arguments.
+      All of the arguments that didn't belong to either end up in the
+      argvn pointer array.
+    </para>
+    <para>
+      FIXME: flesh this out more.  How do we get the GStreamer arguments
+      at the end ?
+  </sect1>
+</chapter>

docs/manual/appendix-integration.xml

@@ -0,0 +1,74 @@
+<chapter id="cha-gnome">
+  <title>Gnome integration</title>
+  <para> 
+    GStreamer is fairly easy to integrate with Gnome applications.
+    GStreamer uses libxml 2.0, GLib 2.0 and popt, as do all other
+    Gnome applications.
+    There are however some basic issues you need to address in your Gnome
+    applications.
+  </para>
+ 
+  <sect1>
+    <title>Command line options</title>
+    <para>
+      Gnome applications call gnome_program_init () to parse command-line
+      options and initialize the necessary gnome modules.
+      GStreamer applications normally call gst_init (&amp;argc, &amp;argv) to
+      do the same for GStreamer.
+    </para>
+    <para>
+      Each of these two swallows the program options passed to the program,
+      so we need a different way to allow both Gnome and GStreamer to parse
+      the command-line options.  This is shown in the following example.
+    </para>  
+
+    <programlisting>
+/* example-begin gnome.c */
+#include &lt;gnome.h&gt;
+#include &lt;gst/gst.h&gt;
+
+int
+main (int argc, char **argv)
+{
+  struct poptOption options[] = {
+          { NULL, '\0', POPT_ARG_INCLUDE_TABLE, NULL, 0, "GStreamer", NULL },
+            POPT_TABLEEND
+        };
+  GnomeProgram *program;
+  poptContext context;
+  const gchar **argvn;
+
+  options[0].arg = (void *) gst_init_get_popt_table ();
+  if (! (program = gnome_program_init (PACKAGE, VERSION, LIBGNOMEUI_MODULE,
+                                       argc, argv,
+                                       GNOME_PARAM_POPT_TABLE, options,
+                                       NULL)))
+  g_error ("gnome_program_init failed");
+
+  g_object_get (program, "popt-context", &amp;context, NULL);
+  argvn = poptGetArgs (context);
+  if (!argvn) {
+    g_print ("Run this example with some arguments to see how it works.\n");
+    return 0;
+  }
+
+  while (*argvn) {
+    g_print ("argument: %s\n", *argvn);
+    ++argvn;
+  }
+
+  return 0;
+}
+/* example-end gnome.c */
+    </programlisting>
+    <para>
+      If you try out this program, you will see that when called with
+      --help, it will print out both GStreamer and Gnome help arguments.
+      All of the arguments that didn't belong to either end up in the
+      argvn pointer array.
+    </para>
+    <para>
+      FIXME: flesh this out more.  How do we get the GStreamer arguments
+      at the end ?
+  </sect1>
+</chapter>

docs/manual/gnome.xml

@@ -0,0 +1,74 @@
+<chapter id="cha-gnome">
+  <title>Gnome integration</title>
+  <para> 
+    GStreamer is fairly easy to integrate with Gnome applications.
+    GStreamer uses libxml 2.0, GLib 2.0 and popt, as do all other
+    Gnome applications.
+    There are however some basic issues you need to address in your Gnome
+    applications.
+  </para>
+ 
+  <sect1>
+    <title>Command line options</title>
+    <para>
+      Gnome applications call gnome_program_init () to parse command-line
+      options and initialize the necessary gnome modules.
+      GStreamer applications normally call gst_init (&amp;argc, &amp;argv) to
+      do the same for GStreamer.
+    </para>
+    <para>
+      Each of these two swallows the program options passed to the program,
+      so we need a different way to allow both Gnome and GStreamer to parse
+      the command-line options.  This is shown in the following example.
+    </para>  
+
+    <programlisting>
+/* example-begin gnome.c */
+#include &lt;gnome.h&gt;
+#include &lt;gst/gst.h&gt;
+
+int
+main (int argc, char **argv)
+{
+  struct poptOption options[] = {
+          { NULL, '\0', POPT_ARG_INCLUDE_TABLE, NULL, 0, "GStreamer", NULL },
+            POPT_TABLEEND
+        };
+  GnomeProgram *program;
+  poptContext context;
+  const gchar **argvn;
+
+  options[0].arg = (void *) gst_init_get_popt_table ();
+  if (! (program = gnome_program_init (PACKAGE, VERSION, LIBGNOMEUI_MODULE,
+                                       argc, argv,
+                                       GNOME_PARAM_POPT_TABLE, options,
+                                       NULL)))
+  g_error ("gnome_program_init failed");
+
+  g_object_get (program, "popt-context", &amp;context, NULL);
+  argvn = poptGetArgs (context);
+  if (!argvn) {
+    g_print ("Run this example with some arguments to see how it works.\n");
+    return 0;
+  }
+
+  while (*argvn) {
+    g_print ("argument: %s\n", *argvn);
+    ++argvn;
+  }
+
+  return 0;
+}
+/* example-end gnome.c */
+    </programlisting>
+    <para>
+      If you try out this program, you will see that when called with
+      --help, it will print out both GStreamer and Gnome help arguments.
+      All of the arguments that didn't belong to either end up in the
+      argvn pointer array.
+    </para>
+    <para>
+      FIXME: flesh this out more.  How do we get the GStreamer arguments
+      at the end ?
+  </sect1>
+</chapter>

docs/manual/gstreamer-manual.xml

@@ -36,6 +36,7 @@
 <!ENTITY DEBUGGING SYSTEM "debugging.xml">
 <!ENTITY PROGRAMS SYSTEM "programs.xml">
 <!ENTITY COMPONENTS SYSTEM "components.xml">
+<!ENTITY GNOME SYSTEM "gnome.xml">
 <!ENTITY QUOTES SYSTEM "quotes.xml">
 ]>
 
@@ -242,6 +243,8 @@
 
       &COMPONENTS;
 
+      &GNOME;
+
       &QUOTES;
 
   </part>