summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid I. Lehn <dlehn@users.sourceforge.net>2003-06-26 08:48:52 +0000
committerDavid I. Lehn <dlehn@users.sourceforge.net>2003-06-26 08:48:52 +0000
commitbb16c7387501479a042b0927d6f881afd1019259 (patch)
tree880371ac028140975447c5612efdefd47f358065
parentddc2769c2d87ff92e3b407845c3783a4a135461a (diff)
kill docutils based docs (easy come, easy go) docbook based docs
Original commit message from CVS: kill docutils based docs (easy come, easy go) docbook based docs
-rw-r--r--AUTHORS40
-rw-r--r--ChangeLog10
-rw-r--r--NEWS11
-rw-r--r--README187
-rw-r--r--TODO28
-rw-r--r--configure.ac1
-rw-r--r--docs/.gitignore3
-rw-r--r--docs/HEAD.in13
-rw-r--r--docs/Makefile.am42
-rw-r--r--docs/common.xsl7
-rw-r--r--docs/docutils.conf9
-rw-r--r--docs/gst-python.css191
-rw-r--r--docs/gst-python.xml435
-rw-r--r--docs/html.xsl8
-rw-r--r--docs/pdf.xsl18
15 files changed, 503 insertions, 500 deletions
diff --git a/AUTHORS b/AUTHORS
index df15ca4..f42d485 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -1,39 +1 @@
-.. gst-python AUTHORS
-.. This file writen with docutils markup (http://docutils.sourceforge.net/)
-
-Contact
-=======
-
-Please feel free to contact the developers. They hang out on IRC_ and the
-mailing lists_.
-
-.. _IRC: http://gstreamer.net/dev/
-.. _lists: http://gstreamer.net/contact/lists.php
-
-Authors
-=======
-
-Maintainer
-----------
-
-* David I. Lehn <dlehn@users.sourceforge.net>
-
-Contributions
--------------
-
-Patches, suggestions, and other help:
-
-* Kenichi Sato <ksato@users.sourceforge.net>)
-
-Much of the framework for gst-python stolen from gtk and gconf bindings by:
-
-* James Henstridge <james@daa.com.au>
-* Johan Dahlin <jdahlin@telia.com>
-* Matt Wilson <msw@redhat.com>
-* and many more...
-
-GStreamer
----------
-
-And of course, none of this would be possible without the extreme hacker mojo
-of the whole GStreamer crew!
+The gst-python AUTHORS list is maintained at docs/gst-python.xml#authors.
diff --git a/ChangeLog b/ChangeLog
index 53c44f3..4a83fdc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2003-06-26 David I. Lehn <dlehn@users.sourceforge.net>
+
+ * configure.ac, AUTHORS, NEWS, README, TODO, docs/Makefile.am,
+ docs/HEAD.in docs/docutils.conf, docs/gst-python.css:
+ kill docutils based docs (easy come, easy go)
+
+ * AUTHORS, NEWS, README, TODO, docs/Makefile.am, docs/gst-python.xml,
+ docs/common.xsl, docs/html.xsl, docs/pdf.xsl, docs/gst-python.css:
+ docbook based docs
+
2003-06-25 David I. Lehn <dlehn@users.sourceforge.net>
* gstreamer/Makefile.am: fix up line continuations
diff --git a/NEWS b/NEWS
index 531887d..8d0b980 100644
--- a/NEWS
+++ b/NEWS
@@ -1,10 +1 @@
-.. gst-python NEWS
-.. This file writen with docutils markup (http://docutils.sourceforge.net/)
-
-News
-====
-
-2003-06-xx - 0.1.0 released
----------------------------
-
-* first release
+The gst-python NEWS is maintained at docs/gst-python.xml#news.
diff --git a/README b/README
index f18f192..81edc5f 100644
--- a/README
+++ b/README
@@ -1,186 +1 @@
-.. gst-python README
-.. This file writen with docutils markup (http://docutils.sourceforge.net/)
-
-About
-=====
-
-This is **gst-python**, the Python_ bindings for the GStreamer_ project. The
-bindings provide access to almost all of the GStreamer C API through an object
-oriented Python API.
-
-.. _Python: http://www.python.org/
-.. _GStreamer: http://www.gstreamer.net/
-
-
-Requirements
-============
-
-* Python_ 2.2
-* GStreamer_ 0.6.0
-* PyGTK_ 1.99.14
-
-.. _PyGTK: http://www.daa.com.au/~james/pygtk/
-
-
-Build/Install
-=============
-
-For build and install information please refer to the "``INSTALL``" file.
-Installation is optional, gst-python can be used from the build directory. The
-quick instructions: build and install PyGTK and GStreamer then build
-gst-python::
-
- $ ./configure && make
-
-
-Using
-=====
-
-You either need to install the package or add the root directory to your
-Python path::
-
- $ export PYTHONPATH=$PYTHONPATH:`pwd`
-
-Try running examples::
-
- $ cd examples/gstreamer/
- $ python cp.py <input file> <output file>
- $ cmp <input file> <output file>
- $ python vorbisplay.py <a vorbis file>
-
-
-Documentation
-=============
-
-General/API
------------
-
-The gst-python bindings are directly generated from the GStreamer headers.
-Look at the GStreamer documentation_ for general API and programming issues.
-In most cases the GStreamer classes and boxed types map directly to Python
-classes. The function-based methods also map onto Python object methods.
-
-.. _documentation: http://www.gstreamer.net/docs/
-
-
-Divergence From C API
----------------------
-
-Due to the nature of C and Python some of the GStreamer API is handled slightly
-different in Python than C. There are a few of the GStreamer C functions that
-are not yet provided in gst-python. These are mostly related to creating
-`Python Elements`_. A few others remain that return GList* or return values in
-their parameters. These have been wrapped as needed. Please file a bug_ if
-you need one of the unwrapped functions.
-
-API changes:
-
-* ``gst_props_entry_get_type`` is accessed through
- ``PropsEntry.get_props_type()``. This is due to the ``_get_type`` function
- extention being normally used for ``GType`` access and is inaccessable
- otherwise.
-
-* Special `Pipeline Iteration`_ support through the following functions:
-
- * ``add_iterate_bin(bin) -> id``: used to iterate a bin with a C idle loop
- callback instead of a Python callback.
- * ``remove_iterate_bin(id)``: used to remove the ``add_iterate_bin``
- idle loop callback id.
- * ``iterate_bin_all(bin)``: releases locks, calls ``gst_bin_iterate``
- until it returns 0, reacquires locks and completes
-
-* `Python Elements`_ support through the following horribly inefficient
- functions:
-
- * ``Buffer.get_data() -> string``: converts buffer data to a string and
- returns it.
- * ``Buffer.set_data(string)``: sets the buffer data from a string.
-
-
-Examples
---------
-
-The best documentation right now is the examples in
-"``./examples/gstreamer/``". Read them.
-
-
-Threads
--------
-
-Threading is a tricky subject for gst-python. There are a few lock you need to
-be aware of:
-
-* GIL
-
- The CPython interpreter is single threaded. Code execution in the
- interpreter is protected by a Global Interpreter Lock (GIL). This means that
- C code can run in other threads in parallel but only one thread will be
- running Python code at any one point. Most of this is handled internally by
- means of locking and unlocking the GIL at appropriate times. Callback code
- and other various code paths between Python and C *should* be setup to do
- proper GIL handling.
-
- However, it is possible that you may encounter a situation where proper
- locking is not done. This is most likely due to calling a wrapper function
- that follows a sequence like this:
-
- - Python -> wrapper function
- - wrapper function -> C GStreamer function
- - C GStreamer function -> side effect code
- - side effect code -> callback
- - callback -> tries to acquire Python GIL but it's already locked
- - deadlocked...
-
- This has been fixed for commonly called functions that have side effects
- which are likely to re-enter the interpreter. It just involves lock/unlock
- around the call to the C gst function. But doing it for every function could
- have performance issues and, more importantly, is not an automated process.
-
- Please file a bug_ if you have problems related to this and need other
- functions to be specially handled.
-
-* Gdk lock
-
- If you are using PyGTK you will have to deal with Gdk locking. Make sure
- you're holding the Gdk lock while executing Gdk/Gtk calls. See PyGTK
- documentation and FAQ list for more information.
-
-
-Pipeline Iteration
-------------------
-
-There are a number of ways to iterate pipelines. ./examples/gstreamer/bps.py
-is a small test program to measure the performance in buffers per second of
-these various techniques. Please see the example for how to use these
-techniques.
-
-* Bin.iterate() in Python from the gtk idle loop
-* gst_bin_iterate() in C from gtk idle loop
-* Bin.iterate() in a Python loop
-* gst_bin_iterate() in a C loop
-
-The method you chose depends on your application. The idle loop methods are
-slightly slower yet more flexible. Probably useful for interactive GUI
-applications.
-
-The basic loop methods are faster but probably more use for non-interactive
-applications. A variation on these loops would be to also check for a stop
-condition which may provide performance increase and some level of control.
-
-
-Python Elements
----------------
-
-It is possible to write Python subclasses of GstElement. This support is very
-primitive and likely to change. See "``./examples/gstreamer/rot13.py``" for an
-example.
-
-
-Bugs
-====
-
-*Please* submit gst-python bugs, patches, or suggestions to GNOME Bugzilla_,
-Product: GStreamer, Component: gst-python. Thank you.
-
-.. _Bugzilla: http://bugzilla.gnome.org/
-.. _bug: `Bugs`_
+The gst-python README is maintained in doc/gst-python.xml.
diff --git a/TODO b/TODO
index 88c4d32..8b6f2d1 100644
--- a/TODO
+++ b/TODO
@@ -1,27 +1 @@
-.. gst-python TODO
-.. This file writen with docutils markup (http://docutils.sourceforge.net/)
-
-TODO
-====
-
-- handle more of the functions that need manual wrapping code
-- add check that pygtk built with --enable-thread
-- improve Python gstreamer.Element creation
-
- - perhaps drop _set_foo_function() calls in favor of object methods
- - sane buffer handling with buffer type or Numeric?
-
-- docs
-
- - API ref
- - manual
- - tutorial
-
-- more examples
-- convert build system to distutils
-- wrap other GStreamer helper libs
-- add some standard widgets
-
- - gtk video widget (similar to widget gst-player is using)
-
-- testsuite
+The gst-python TODO list is maintained at docs/gst-python.xml#todo.
diff --git a/configure.ac b/configure.ac
index e1cb7fb..d8bc0bb 100644
--- a/configure.ac
+++ b/configure.ac
@@ -119,6 +119,5 @@ AC_OUTPUT([
examples/Makefile
examples/gstreamer/Makefile
docs/Makefile
- docs/HEAD
gst-python.spec
])
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..4c1e751
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,3 @@
+gst-python.html
+gst-python.txt
+gst-python.pdf
diff --git a/docs/HEAD.in b/docs/HEAD.in
deleted file mode 100644
index fb780c8..0000000
--- a/docs/HEAD.in
+++ /dev/null
@@ -1,13 +0,0 @@
-.. gst-python HEAD.in
-.. This file writen with docutils markup (http://docutils.sourceforge.net/)
-
-==========
-gst-python
-==========
-
-:Author: David I. Lehn
-:Contact: dlehn@users.sourceforge.net
-:Web site: http://www.gstreamer.net/bindings/python/
-:Version: @VERSION@
-
-.. contents::
diff --git a/docs/Makefile.am b/docs/Makefile.am
index da04cda..c0d9007 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -1,27 +1,21 @@
-EXTRA_DIST = HEAD.in docutils.conf gst-python.css
+XMLFILES = gst-python.xml
+XSLFILES = common.xsl html.xsl
+CSSFILES = gst-python.css
-DOCS = \
- $(srcdir)/HEAD \
- $(top_srcdir)/NEWS \
- $(top_srcdir)/README \
- $(top_srcdir)/TODO \
- $(top_srcdir)/AUTHORS
+DOCS = gst-python.txt gst-python.html
-gst-python.html: docutils.conf ${DOCS}
- @if [ ! $$DOCUTILSHOME ]; then \
- echo "ERROR: Please set \$$DOCUTILSHOME"; \
- exit 1; \
- fi
- @if [ ! -r $$DOCUTILSHOME/tools/html.py ]; then \
- echo "\$$DOCUTILSHOME/tools/html.py not found"; \
- exit 1; \
- fi
- rm -f gst-python.txt
- for doc in ${DOCS}; do \
- cat $$doc >> gst-python.txt; \
- printf "\n" >> gst-python.txt; \
- done
- PYTHONPATH=$$PYTHONPATH:$$DOCUTILSHOME $$DOCUTILSHOME/tools/html.py gst-python.txt gst-python.html
- lynx -dump -force_html gst-python.html > gst-python.out
+all: $(DOCS)
-CLEANFILES = gst-python.txt gst-python.html
+gst-python.txt: gst-python.xml
+ xmlto txt $<
+# cp gst-python.txt $(top_builddir)/../README
+
+gst-python.html: gst-python.xml common.xsl html.xsl
+ xmlto -m common.xsl -m html.xsl xhtml-nochunks $<
+
+gst-python.pdf: gst-python.xml common.xsl pdf.xsl
+ xmlto -m common.xsl -m pdf.xsl pdf $<
+
+CLEANFILES = $(DOCS)
+
+EXTRA_DIST = $(XMLFILES) $(XSLFILES) $(CSSFILES)
diff --git a/docs/common.xsl b/docs/common.xsl
new file mode 100644
index 0000000..8495981
--- /dev/null
+++ b/docs/common.xsl
@@ -0,0 +1,7 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version='1.0'>
+<xsl:param name="section.autolabel" select="1"/>
+<xsl:param name="section.label.includes.component.label" select="1"/>
+<xsl:param name="use.id.as.filename" select="1"/>
+</xsl:stylesheet>
diff --git a/docs/docutils.conf b/docs/docutils.conf
deleted file mode 100644
index 2f455f9..0000000
--- a/docs/docutils.conf
+++ /dev/null
@@ -1,9 +0,0 @@
-[options]
-
-# These entries affect all processing:
-source-link: 1
-datestamp: %Y-%m-%d %H:%M UTC
-generator: 1
-
-# These entries affect HTML output:
-stylesheet-path: gst-python.css
diff --git a/docs/gst-python.css b/docs/gst-python.css
index fe8dc8e..e69de29 100644
--- a/docs/gst-python.css
+++ b/docs/gst-python.css
@@ -1,191 +0,0 @@
-/*
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:date: $Date$
-:version: $Revision$
-:copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-*/
-
-.first {
- margin-top: 0 }
-
-.last {
- margin-bottom: 0 }
-
-a.toc-backref {
- text-decoration: none ;
- color: black }
-
-dd {
- margin-bottom: 0.5em }
-
-div.abstract {
- margin: 2em 5em }
-
-div.abstract p.topic-title {
- font-weight: bold ;
- text-align: center }
-
-div.attention, div.caution, div.danger, div.error, div.hint,
-div.important, div.note, div.tip, div.warning {
- margin: 2em ;
- border: medium outset ;
- padding: 1em }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
- color: red ;
- font-weight: bold ;
- font-family: sans-serif }
-
-div.hint p.admonition-title, div.important p.admonition-title,
-div.note p.admonition-title, div.tip p.admonition-title {
- font-weight: bold ;
- font-family: sans-serif }
-
-div.dedication {
- margin: 2em 5em ;
- text-align: center ;
- font-style: italic }
-
-div.dedication p.topic-title {
- font-weight: bold ;
- font-style: normal }
-
-div.figure {
- margin-left: 2em }
-
-div.footer, div.header {
- font-size: smaller }
-
-div.system-messages {
- margin: 5em }
-
-div.system-messages h1 {
- color: red }
-
-div.system-message {
- border: medium outset ;
- padding: 1em }
-
-div.system-message p.system-message-title {
- color: red ;
- font-weight: bold }
-
-div.topic {
- margin: 2em }
-
-h1.title {
- text-align: center }
-
-h2.subtitle {
- text-align: center }
-
-hr {
- width: 75% }
-
-ol.simple, ul.simple {
- margin-bottom: 1em }
-
-ol.arabic {
- list-style: decimal }
-
-ol.loweralpha {
- list-style: lower-alpha }
-
-ol.upperalpha {
- list-style: upper-alpha }
-
-ol.lowerroman {
- list-style: lower-roman }
-
-ol.upperroman {
- list-style: upper-roman }
-
-p.caption {
- font-style: italic }
-
-p.credits {
- font-style: italic ;
- font-size: smaller }
-
-p.label {
- white-space: nowrap }
-
-p.topic-title {
- font-weight: bold }
-
-pre.address {
- margin-bottom: 0 ;
- margin-top: 0 ;
- font-family: serif ;
- font-size: 100% }
-
-pre.line-block {
- font-family: serif ;
- font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
- margin-left: 2em ;
- margin-right: 2em ;
- background-color: #eeeeee }
-
-span.classifier {
- font-family: sans-serif ;
- font-style: oblique }
-
-span.classifier-delimiter {
- font-family: sans-serif ;
- font-weight: bold }
-
-span.interpreted {
- font-family: sans-serif }
-
-span.option {
- white-space: nowrap }
-
-span.option-argument {
- font-style: italic }
-
-span.pre {
- white-space: pre }
-
-span.problematic {
- color: red }
-
-table {
- margin-top: 0.5em ;
- margin-bottom: 0.5em }
-
-table.citation {
- border-left: solid thin gray ;
- padding-left: 0.5ex }
-
-table.docinfo {
- margin: 2em 4em }
-
-table.footnote {
- border-left: solid thin black ;
- padding-left: 0.5ex }
-
-td, th {
- padding-left: 0.5em ;
- padding-right: 0.5em ;
- vertical-align: top }
-
-th.docinfo-name, th.field-name {
- font-weight: bold ;
- text-align: left ;
- white-space: nowrap }
-
-h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
- font-size: 100% }
-
-tt {
- background-color: #eeeeee }
-
-ul.auto-toc {
- list-style-type: none }
diff --git a/docs/gst-python.xml b/docs/gst-python.xml
new file mode 100644
index 0000000..077a127
--- /dev/null
+++ b/docs/gst-python.xml
@@ -0,0 +1,435 @@
+<?xml version='1.0'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<article id="gst-python">
+<articleinfo>
+ <publisher><publishername>The GStreamer Development Team</publishername></publisher>
+ <pubdate>June ??, 2003</pubdate>
+ <copyright><year>2003</year><holder>David I. Lehn</holder></copyright>
+ <title><application>gst-python</application>: A Python Interface to GStreamer</title>
+ <titleabbrev>gst-python</titleabbrev>
+ <authorgroup>
+ <author>
+ <firstname>David</firstname>
+ <othername role="mi">I.</othername>
+ <surname>Lehn</surname>
+ <email>dlehn@users.sourceforge.net</email>
+ </author>
+ </authorgroup>
+ <abstract>
+ <para>Introductory information for the GStreamer Python bindings.</para>
+ <para><ulink url="http://www.gstreamer.net/bindings/python/"/></para>
+ </abstract>
+ <revhistory>
+ <revision>
+ <revnumber>0.1.0</revnumber>
+ <date>2003-06-??</date>
+ <authorinitials>dil</authorinitials>
+ <revremark>Initial version.</revremark>
+ </revision>
+ </revhistory>
+</articleinfo>
+
+<!--=====================================================================-->
+
+<section id="about">
+<title>About</title>
+<para>
+
+<application>gst-python</application>: the <ulink url="http://www.python.org/">Python</ulink> bindings for the <ulink url="http://www.gstreamer.net/">GStreamer</ulink> project. These bindings provide access to almost all of the GStreamer C API through an object oriented Python API.
+
+</para>
+</section>
+
+<!--=====================================================================-->
+
+<section id="news">
+<title>News</title>
+<para>
+<informaltable frame="all">
+<tgroup cols="3">
+<colspec align="center"/>
+<colspec align="center"/>
+<colspec align="left"/>
+<thead>
+ <row>
+ <entry>Date</entry>
+ <entry>Version</entry>
+ <entry>Notes</entry>
+ </row>
+</thead>
+<tbody>
+ <row>
+ <entry>2003-06-xx</entry>
+ <entry>0.1.0</entry>
+ <entry>first release</entry>
+ </row>
+</tbody>
+</tgroup>
+</informaltable>
+</para>
+</section>
+
+<!--=====================================================================-->
+
+<section id="installation">
+<title>Installation</title>
+
+<!--=================-->
+
+<section id="requirements">
+<title>Requirements</title>
+<itemizedlist>
+<listitem><para>
+Python 2.2 (<ulink url="http://www.python.org/"/>)
+</para></listitem>
+<listitem><para>
+GStreamer 0.6.x (<emphasis>except</emphasis> 0.6.1) (<ulink url="http://www.gstreamer.net/"/>)
+</para></listitem>
+<listitem><para>
+PyGTK 1.99.14 (<ulink url="http://www.daa.com.au/~james/pygtk/"/>)
+</para></listitem>
+</itemizedlist>
+</section>
+
+<!--=================-->
+
+<section id="building">
+<title>Building and Installation</title>
+
+<para>
+For build and install information please refer to the "INSTALL" file. Installation is optional, gst-python can be used from the build directory. The quick instructions: build and install PyGTK and GStreamer then build gst-python:
+</para>
+
+<para>
+<screen>
+ $ ./configure &amp;&amp; make
+</screen>
+</para>
+
+</section>
+
+<!--=================-->
+
+<section id="using">
+<title>Using</title>
+<para>
+You either need to install the package or add the root directory to your
+Python path:
+</para>
+
+<para>
+<screen>
+ $ export PYTHONPATH=$PYTHONPATH:`pwd`
+</screen>
+</para>
+
+<para>
+Try running examples:
+</para>
+
+<para>
+<screen>
+ $ cd examples/gstreamer/
+ $ python cp.py &lt;input file&gt; &lt;output file&gt;
+ $ cmp &lt;input file&gt; &lt;output file&gt;
+ $ python vorbisplay.py &lt;an Ogg Vorbis file&gt;
+</screen>
+</para>
+
+</section>
+
+<!--=================-->
+
+</section>
+
+<!--=====================================================================-->
+
+<section id="programming">
+<title>Programming</title>
+
+<!--=================-->
+
+<section id="general-api">
+<title>General API</title>
+<para>
+
+The gst-python bindings are directly generated from the GStreamer headers. Look at the GStreamer documentation at <ulink url="http://www.gstreamer.net/docs/"/> for general API and programming issues. In most cases the GStreamer classes and boxed types map directly to Python classes. The function-based GObject methods also map onto Python methods.
+
+</para>
+</section>
+
+<!--=================-->
+
+<section id="divergence-from-c-api">
+<title>Divergence From C API</title>
+
+<para>Due to the nature of C and Python some of the GStreamer API is handled
+slightly different in Python than C. There are a few of the GStreamer C
+functions that are not yet provided in gst-python. These are mostly related to
+creating <xref linkend="python-elements" endterm="python-elements.title"/>. A
+few others remain that return GList* or return values in their parameters.
+These have been wrapped as needed. Please file a <link
+linkend="bugs">bug</link> if you need one of the unwrapped functions.</para>
+
+<para>API changes:</para>
+
+<itemizedlist>
+
+ <listitem><para><function>gst_props_entry_get_type</function> is accessed
+ through <function>PropsEntry.get_props_type</function>(). This is due to the
+ <function>_get_type</function> function extention being normally used for
+ <function>GType</function> access and is inaccessable
+ otherwise.</para></listitem>
+
+ <listitem><para>Special <link linkend="pipeline-iteration">pipeline
+ iteration</link> support through the following functions:</para>
+
+ <itemizedlist>
+
+ <listitem><para><function>add_iterate_bin</function>(<parameter
+ class="function">bin</parameter>) -&gt; <returnvalue>id</returnvalue>: used
+ to iterate a bin with a C idle loop callback instead of a Python
+ callback.</para></listitem>
+
+ <listitem><para><function>remove_iterate_bin</function>(<parameter
+ class="function">id</parameter>): used to remove the
+ <function>add_iterate_bin</function> idle loop callback
+ id.</para></listitem>
+
+ <listitem><para><function>iterate_bin_all</function>(<parameter
+ class="function">bin</parameter>): releases locks, calls
+ <function>gst_bin_iterate</function> until it returns 0, reacquires locks
+ and completes</para></listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem><para><link linkend="python-elements">Python Elements</link> support through the following currently horribly inefficient functions:</para>
+
+ <itemizedlist>
+
+ <listitem><para><function>Buffer.get_data</function>() -&gt;
+ <returnvalue>string</returnvalue>: converts buffer data to a string and
+ returns it.</para></listitem>
+
+ <listitem><para><function>Buffer.set_data</function>(<parameter
+ class="function">string</parameter>): sets the buffer data from a
+ string.</para></listitem>
+
+ </itemizedlist>
+ </listitem>
+</itemizedlist>
+
+</section>
+
+<!--=================-->
+
+<section id="examples">
+<title>Examples</title>
+
+<para>The best documentation right now are the examples in <filename
+class="directory">./examples/gstreamer/</filename>. Read them.</para>
+
+</section>
+
+<!--=================-->
+
+<section id="threads">
+<title>Threads</title>
+
+<para>Threading is a tricky subject for gst-python. There are a few lock you
+need to be aware of:</para>
+
+<section id="gil">
+<title>GIL</title>
+
+<para>The CPython interpreter is single threaded. Code execution in the
+interpreter is protected by a Global Interpreter Lock (GIL). This means that C
+code can run in other threads in parallel but only one thread will be running
+Python code at any one point. Most of this is handled internally by means of
+locking and unlocking the GIL at appropriate times. Callback code and other
+various code paths between Python and C *should* be setup to do proper GIL
+handling.</para>
+
+<para>However, it is possible that you may encounter a situation where proper
+locking is not done. This is most likely due to calling a wrapper function
+that follows a sequence like this:</para>
+
+<orderedlist>
+<listitem><para>Python calls wrapper function</para></listitem>
+<listitem><para>wrapper function calls C GStreamer function</para></listitem>
+<listitem><para>C GStreamer function calls side effect code</para></listitem>
+<listitem><para>side effect code calls callback</para></listitem>
+<listitem><para>callback tries to acquire Python GIL but it's already locked</para></listitem>
+<listitem><para>deadlocked...</para></listitem>
+</orderedlist>
+
+<para>This has been fixed for commonly called functions that have side effects
+which are likely to re-enter the interpreter. It just involves lock/unlock
+around the call to the C gst function. But doing it for every function could
+have performance issues and, more importantly, is not an automated
+process.</para>
+
+<para>Please file a <link linkend="bugs">bug</link> if you have problems
+related to this and need other functions to be specially handled.</para>
+
+</section>
+
+<section id="gdk-lock">
+<title>Gdk Lock</title>
+
+<para>If you are using PyGTK you will have to deal with Gdk locking. Make sure
+you're holding the Gdk lock while executing Gdk/Gtk calls. See PyGTK
+documentation and FAQ list for more information.</para>
+
+</section>
+
+</section>
+
+<!--=================-->
+
+<section id="pipeline-iteration">
+<title>Pipeline Iteration</title>
+
+<para>There are a number of ways to iterate pipelines.
+<filename>./examples/gstreamer/bps.py</filename> is a small test program to
+measure the performance in buffers per second of these various techniques.
+Please see the example for how to use these techniques.</para>
+
+<itemizedlist>
+<listitem><para><function>Bin.iterate</function>() in Python from the gtk idle loop</para></listitem>
+<listitem><para><function>gst_bin_iterate</function>() in C from gtk idle loop</para></listitem>
+<listitem><para><function>Bin.iterate</function>() in a Python loop</para></listitem>
+<listitem><para><function>gst_bin_iterate</function>() in a C loop</para></listitem>
+</itemizedlist>
+
+<para>The method you chose depends on your application. The idle loop methods
+are slightly slower yet more flexible. Probably useful for interactive GUI
+applications.</para>
+
+<para>The basic loop methods are faster but probably more use for
+non-interactive applications. A variation on these loops would be to also
+check for a stop condition which may provide performance increase and some
+level of control.</para>
+
+</section>
+
+<!--=================-->
+
+<section id="python-elements">
+<title id="python-elements.title">Python Elements</title>
+
+<para> It is possible to write Python subclasses of GstElement. This support
+is very primitive and likely to change. See
+<filename>./examples/gstreamer/rot13.py</filename> for an example.</para>
+
+</section>
+
+<!--=================-->
+
+</section>
+
+<!--=====================================================================-->
+
+<section id="bugs">
+<title>Bugs</title>
+<para>
+<emphasis>Please</emphasis> submit gst-python bugs, patches, or suggestions to GNOME Bugzilla (<ulink url="http://bugzilla.gnome.org/"/>). Product: GStreamer, Component: gst-python. Or alternatively send a message to the gstreamer-devel list or the maintainer. Thank you.
+</para>
+</section>
+
+<!--=====================================================================-->
+
+<section id="todo">
+<title>TODO</title>
+<itemizedlist>
+<listitem><para>handle more of the functions that need manual wrapping code</para></listitem>
+<listitem><para>add check that pygtk built with <parameter class="command">--enable-thread</parameter></para></listitem>
+<listitem><para>improve Python gstreamer.Element creation</para>
+ <itemizedlist>
+ <listitem><para>perhaps drop <function>_set_foo_function</function>() calls in favor of object methods</para></listitem>
+ <listitem><para>sane buffer handling with buffer type or Numeric?</para></listitem>
+ </itemizedlist>
+</listitem>
+<listitem><para>docs</para>
+ <itemizedlist>
+ <listitem><para>API ref</para></listitem>
+ <listitem><para>manual</para></listitem>
+ <listitem><para>tutorial</para></listitem>
+ </itemizedlist>
+</listitem>
+<listitem><para>more examples</para></listitem>
+<listitem><para>convert build system to distutils</para></listitem>
+<listitem><para>wrap other GStreamer helper libs</para></listitem>
+<listitem><para>add some standard widgets</para>
+ <itemizedlist>
+ <listitem><para>gtk video widget (similar to widget gst-player is using)</para></listitem>
+ </itemizedlist>
+</listitem>
+<listitem><para>testsuite</para></listitem>
+</itemizedlist>
+</section>
+
+<!--=====================================================================-->
+
+<section id="authors">
+<title>Authors</title>
+
+<para>
+Please feel free to contact the developers. They hang out on IRC (<ulink url="http://gstreamer.net/dev/"/>) and the mailing lists (<ulink url="http://gstreamer.net/contact/lists.php"/>).
+</para>
+
+<!--=================-->
+
+<section id="maintainer">
+<title>Maintainer</title>
+
+<itemizedlist>
+<listitem><para>David I. Lehn <email>dlehn at users.sourceforge.net</email></para></listitem>
+</itemizedlist>
+</section>
+
+<!--=================-->
+
+<section id="contributions">
+<title>Contributions</title>
+<para>
+Patches, suggestions, and other help:
+</para>
+
+<itemizedlist>
+<listitem><para>Kenichi Sato <email>ksato at users.sourceforge.net</email></para></listitem>
+</itemizedlist>
+
+<para>
+Much of the framework for gst-python stolen from gtk and gconf bindings by:
+</para>
+
+<itemizedlist>
+<listitem><para>James Henstridge <email>james at daa.com.au</email></para></listitem>
+<listitem><para>Johan Dahlin <email>jdahlin at telia.com</email></para></listitem>
+<listitem><para>Matt Wilson <email>msw at redhat.com</email></para></listitem>
+<listitem><para>and many more...</para></listitem>
+</itemizedlist>
+
+</section>
+
+<!--=================-->
+
+<section id="gstreamer-team">
+<title>GStreamer Team</title>
+<para>
+And of course, none of this would be possible without the extreme hacker mojo
+of the whole GStreamer crew!
+</para>
+</section>
+
+<!--=================-->
+
+</section>
+
+<!--=====================================================================-->
+
+</article>
diff --git a/docs/html.xsl b/docs/html.xsl
new file mode 100644
index 0000000..ff36dd4
--- /dev/null
+++ b/docs/html.xsl
@@ -0,0 +1,8 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version='1.0'>
+
+<xsl:param name="html.stylesheet" select="'gst-python.css'"/>
+<xsl:param name="linenumbering.extension" select="1"/>
+
+</xsl:stylesheet>
diff --git a/docs/pdf.xsl b/docs/pdf.xsl
new file mode 100644
index 0000000..9f0bcc8
--- /dev/null
+++ b/docs/pdf.xsl
@@ -0,0 +1,18 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version='1.0'>
+
+<xsl:param name="body.margin.top">0.5in</xsl:param>
+
+<xsl:template name="is.graphic.extension">
+ <xsl:param name="ext"></xsl:param>
+ <xsl:if test="$ext = 'png'
+ or $ext = 'pdf'
+ or $ext = 'jpeg'
+ or $ext = 'gif'
+ or $ext = 'tif'
+ or $ext = 'tiff'
+ or $ext = 'bmp'">1</xsl:if>
+</xsl:template>
+
+</xsl:stylesheet>