docs/: add a chapter on running GStreamer.

Original commit message from CVS:

* docs/Makefile.am:
* docs/gst/Makefile.am:
* docs/gst/gstreamer-docs.sgml:
* docs/gst/running.xml:
* docs/version.entities.in:
add a chapter on running GStreamer.
document GST_DEBUG and GST_PLUGIN* env vars

diff --git a/ChangeLog b/ChangeLog
index a1b7049..1272ccb 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,24 @@
+2005-10-08  Thomas Vander Stichele  <thomas at apestaart dot org>
+
+       * docs/Makefile.am:
+       * docs/gst/Makefile.am:
+       * docs/gst/gstreamer-docs.sgml:
+       * docs/gst/running.xml:
+       * docs/version.entities.in:
+         add a chapter on running GStreamer.
+         document GST_DEBUG and GST_PLUGIN* env vars
+
+2005-10-08  Thomas Vander Stichele  <thomas at apestaart dot org>
+
+       * Makefile.am:
+         remove include dir
+       * configure.ac:
+         remove PLUGINS_BUILDDIR stuff
+       * gst/gst.c: (init_post):
+         reorder parsing of GST_PLUGIN_PATH and GST_PLUGIN_SYSTEM_PATH
+       * idiottest.mak:
+         remove, it was condescending and not needed
+
 2005-10-08  Wim Taymans  <wim@fluendo.com>
 
        * gst/base/gstbasesink.c: (gst_base_sink_preroll_queue_flush),

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 55b089a..521371f 100644 (file)
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -10,6 +10,8 @@ else
 SUBDIRS_DOCBOOK =
 endif
 
+BUILT_SOURCES = version.entities
+
 SUBDIRS = $(SUBDIRS_DOCBOOK) $(SUBDIRS_GTK_DOC)
 DIST_SUBDIRS = gst faq manual pwg libs xsl
 

diff --git a/docs/gst/Makefile.am b/docs/gst/Makefile.am
index 2ee7f7b..0aa8510 100644 (file)
--- a/docs/gst/Makefile.am
+++ b/docs/gst/Makefile.am
@@ -99,7 +99,7 @@ IGNORE_HFILES= \
 HTML_IMAGES =
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
-content_files =
+content_files = running.xml
 
 # Other files to distribute.
 extra_files =

diff --git a/docs/gst/gstreamer-docs.sgml b/docs/gst/gstreamer-docs.sgml
index 635d6ab..818e6c4 100644 (file)
--- a/docs/gst/gstreamer-docs.sgml
+++ b/docs/gst/gstreamer-docs.sgml
@@ -78,6 +78,8 @@
 <!-- generated by gtkdoc-mkdb, stupid name -->
 <!ENTITY gstreamer-tree-index SYSTEM "xml/tree_index.sgml">
 
+<!ENTITY gst-Running SYSTEM "running.xml">
+
 <!ENTITY hash "#">
 ]>
 <book id="index">
@@ -87,6 +89,26 @@
   </bookinfo>
 
   <chapter id="gstreamer">
+
+    <title>GStreamer Overview</title>
+    <para>
+GStreamer is a streaming media framework.
+It uses graphs of elements which operate on data.
+The functionality to process media is provided by plug-ins which provide
+features like elements, typefinding, and so on.
+This allows new functionality to be added simply by installing new plug-ins.
+    </para>
+
+    <para>
+GStreamer is cross-platform and works on most UNIX-like platforms as well as
+Windows.  It is released under the GNU Library General Public License
+(GNU LGPL).
+    </para>
+
+    &gst-Running;
+  </chapter>
+
+  <chapter id="libgstreamer">
     <title>GStreamer Core Library</title>
 
     <para>

diff --git a/docs/gst/running.xml b/docs/gst/running.xml
new file mode 100644 (file)
index 0000000..4ea923e
--- /dev/null
+++ b/docs/gst/running.xml
@@ -0,0 +1,172 @@
+<refentry id="gst-running" revision="08 Oct 2005">
+<refmeta>
+<refentrytitle>Running GStreamer Applications</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GStreamer Core</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Running GStreamer Applications</refname>
+<refpurpose>
+How to run and debug your GStreamer application
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Running and debugging GStreamer Applications</title>
+
+<refsect2>
+<title>Environment variables</title>
+
+<para> 
+GStreamer inspects a few of environment variables in addition to standard
+variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>. 
+</para>
+
+<formalpara id="GST_PLUGIN_SYSTEM_PATH">
+  <title><envar>GST_PLUGIN_SYSTEM_PATH</envar></title>
+
+  <para>
+
+This environment variable can be set to a colon-separated list of paths.
+If this variable is not set, GStreamer will fill in this list for you
+with
+<itemizedlist>
+  <listitem>
+    <para>
+plug-ins in the user's home directory.  These are stored in a directory called
+<filename>plugins</filename> inside the
+<filename>.gstreamer-&GST_MAJORMINOR;</filename> directory in the user's
+home directory.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+plug-ins installed system-wide.  On this system, they are stored in
+<filename>&GST_PLUGINS_DIR;</filename>.
+    </para>
+
+</listitem>
+</itemizedlist>
+   </para>
+
+    <para>
+GStreamer will scan these paths for GStreamer plug-ins.  These plug-ins will
+be loaded after the plug-ins in the GST_PLUGIN_PATH variable below.
+
+The paths are scanned in the given order.  This allows a user to override
+system-installed plug-ins with his own versions.
+   </para>
+
+    <para>
+Setting this variable to an empty string will cause GStreamer not to scan any
+system paths at all for plug-ins.  This can be useful if you're running
+uninstalled (for development purposes) or while running testsuites.
+   </para>
+
+</formalpara>
+
+<formalpara id="GST_PLUGIN_PATH">
+  <title><envar>GST_PLUGIN_PATH</envar></title>
+
+  <para>
+This environment variable can be set to a colon-separated list of paths.
+GStreamer will scan these paths for GStreamer plug-ins.  These plug-ins will
+be loaded in addition to, and before, the plug-ins in the system paths.
+  </para>
+
+</formalpara>
+
+<formalpara>
+  <title><envar>GST_DEBUG</envar></title>
+
+  <para>
+If GStreamer has been configured with <option>--enable-gst-debug=yes</option>,
+this variable can be set to a list of debug options, which cause GStreamer
+to print out different types of debugging information to stderr.
+  </para>
+  <para>
+The variable takes a comma-separated list of "category_name:level" pairs
+to set specific levels for the individual categories.
+The level value ranges from 0 (nothing) to 5 (LOG).
+    <variablelist>
+
+      <varlistentry>
+        <term>1 - <option>ERROR</option></term>
+        <listitem>
+<para>
+Logs all fatal errors.  These are errors that do not allow the core or elements
+to perform the requested action.  The application can still recover if
+programmed to handle the conditions that triggered the error.
+</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>2 - <option>WARNING</option></term>
+        <listitem>
+<para>
+Logs all warnings.  Typically these are non-fatal, but user-visible problems
+are expected to happen.
+</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>3 - <option>INFO</option></term>
+        <listitem>
+<para>
+Logs all informational messages.  These are typically used for events in
+the system that only happen once, or are important and rare enough to be
+logged at this level.
+</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>4 - <option>DEBUG</option></term>
+        <listitem>
+<para>
+Logs all debug messages.  These are general debug messages for events
+that happen only a limited number of times during an object's lifetime;
+these include setup, teardown, change of parameters, ...
+</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>5 - <option>LOG</option></term>
+        <listitem>
+<para>
+Logs all log messages.  These are messages for events
+that happen repeatedly during an object's lifetime;
+these include streaming and steady-state conditions.
+</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+ The category_name can contain "<option>*"</option> as a wildcard.
+  </para>
+
+  <para>
+For example, setting <envar>GST_DEBUG</envar> to
+<option>GST_AUTOPLUG:5,GST_ELEMENT_*:3</option>, will cause the
+<option>GST_AUTOPLUG</option> category to be logged at full
+<option>LOG</option> level, while all categories starting with
+<option>GST_ELEMENT_</option> will be logged at <option>INFO</option> level.
+  </para>
+
+  <para>
+To get all possible debug output, set
+<envar>GST_DEBUG</envar>
+to <option>*:5</option>
+  </para>
+
+</formalpara>
+
+</refsect2>
+
+</refsect1>
+
+</refentry>

diff --git a/docs/version.entities.in b/docs/version.entities.in
index 79a6898..17fdda6 100644 (file)
--- a/docs/version.entities.in
+++ b/docs/version.entities.in
@@ -1,2 +1,3 @@
 <!ENTITY GST_MAJORMINOR "@GST_MAJORMINOR@">
-<!ENTITY GST_VERSION "@VERSION@">
+<!ENTITY GST_VERSION "@GST_VERSION@">
+<!ENTITY GST_PLUGINS_DIR "@PLUGINS_DIR@">

diff --git a/idiottest.mak b/idiottest.mak
deleted file mode 100644 (file)
index 45c96ae..0000000
--- a/idiottest.mak
+++ /dev/null
@@ -1,15 +0,0 @@
-# Idiot test to stop the installing of versions with plugin builddir enabled
-install-exec-local:
-if PLUGINS_USE_BUILDDIR
-       @echo "*** ERROR: Cannot install:"
-       @echo "GStreamer was configured using the --enable-plugin-builddir option."
-       @echo
-       @echo "This option is for development purposes only: binaries built with"
-       @echo "it should be used with code in the build tree only.  To build an"
-       @echo "installable version, use ./configure without the --enable-plugin-builddir"
-       @echo "option.  Note that the autogen.sh script supplies the plugin builddir"
-       @echo "option automatically - it cannot be used to configure installable builds."
-       @echo
-       @/bin/false
-endif
-