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

15 files changed, 503 insertions, 500 deletions

diff --git a/AUTHORS b/AUTHORS
index df15ca4114..f42d485f35 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 53c44f3dbf..4a83fdc257 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 531887db6c..8d0b980743 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 f18f192baf..81edc5fd5c 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 88c4d32ece..8b6f2d171a 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 e1cb7fb71c..d8bc0bb279 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 0000000000..4c1e7510ec
--- /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 fb780c8724..0000000000
--- 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 da04cda668..c0d90075d9 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 0000000000..84959814a8
--- /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 2f455f9f47..0000000000
--- 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 fe8dc8eace..e69de29bb2 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 0000000000..077a1275d8
--- /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 0000000000..ff36dd4dad
--- /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 0000000000..9f0bcc8280
--- /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>