[gst-devel] [PATCH] documentation patches
Cameron Hutchison
camh+gst at xdna.net
Fri Aug 30 00:58:05 CEST 2002
As a newbie to gstreamer, I've been working my way through the manual.
Whenever I've found something that is incorrect or somewhere where it
could be enhanced, I've made changes.
I've decided to stop after chapter 6 (plugins) so I can get some
feedback, in case I'm going in the wrong direction. Someone please tell
me I'm doing things right (or wrong) so I can continue.
The changes in the patch are:
* Added some links to other sites where appropriate (glib, other gtk
stuff)
* Misc speeling fixes
* Misc grammar/typo fixes
* Added some text marked with FIXME where more info should be added.
At least, this was info that I wanted to know as I read the
tutorial.
* Added spaces between words. eg "elementfactory" -> "element factory".
This may be controversial, but since the words are not tagged with
<classname> or any other tag, I expect them to be english. As such,
there should be a space between the words. If the precise classname
is needed, then it should be used properly (eg.
<classname>GstElementFactory</classname>).
* Added markup for various bits that look like they should have it
(class names, function names, filenames, etc)
(NOTE: I'm a newbie to docbook to so I may have missed some
opportunities for markup or got some wrong. I'm using the docbook
guide at http://docbook.org/tdg/en/html/docbook.html)
* Added a bit more explanatory text before code examples so that the
particular function being described in the example is referenced in
the main text (using <function> tags) which may help in generating
indexes (dont know if this really helps but it makes sense to me).
I've got more I want to do (this is getting out of control - I just
started to fix some typos :-):
* Add <example> tags to all the examples
* Thats all for now :-)
* Add more explanatory text before examples (same as last element in
the list above, but do it more consistently)
* Make callback functions consistently use gpointer for the data
parameter. Even though direct pointers are allowed (eg.
GstElement *), I've opted to make all usage consistent and safe. I
feel that this is best for a tutorial.
It looks like this has turned into a "getting to know docbook" exercise,
which is fine, since that's been on my todo list for a while too (as
well as "get to know gstreamer").
-------------- next part --------------
Index: gstreamer/docs/manual/elements.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/elements.xml,v
retrieving revision 1.4
diff -u -u -r1.4 elements.xml
--- gstreamer/docs/manual/elements.xml 24 Jul 2002 19:46:42 -0000 1.4
+++ gstreamer/docs/manual/elements.xml 30 Aug 2002 07:53:21 -0000
@@ -8,9 +8,9 @@
<sect1 id="sec-elements-design">
<title>What is a GstElement</title>
<para>
- The GstElement is the basic building block for the media pipeline. All the
- different components you are going to use are derived from this GstElement.
- This means that a lot of functions you are going to use operate on this object.
+ <classname>GstElement</classname> is the basic building block for the media pipeline. All the
+ different components you are going to use are derived from <classname>GstElement</classname>.
+ This means that a lot of functions you are going to use operate on objects of this class.
</para>
<para> Elements, from the perspective of GStreamer, are viewed as "black boxes" with a number of
different aspects. One of these aspects is the presence of "pads", or connection points. This
@@ -38,7 +38,7 @@
<para>
Source elements do not accept data, they only generate data. You can see
this in the figure because it only has a src pad. A src pad can only
- generate buffers.
+ generate data.
</para>
</sect2>
@@ -50,7 +50,7 @@
would fall into this category.
</para>
<para>
- Elements are not constrained as to the number of pads they migh have; for example, a video
+ Elements are not constrained as to the number of pads they might have; for example, a video
mixer might have two input pads (the images of the two different video streams) and one
output pad.
</para>
@@ -78,8 +78,8 @@
</figure>
<para>
The above figure shows the visualisation of a filter element with more than one output pad.
- An example of such a filter is the AVI splitter (demuxer). This element will parse the input
- data and extracts the audio and video data. Most of these filters dynamically send out a
+ An example of such a filter is the AVI splitter (demultiplexer). This element will parse the input
+ data and extract the audio and video data. Most of these filters dynamically send out a
signal when a new pad is created so that the application programmer can connect an arbitrary
element to the newly created pad.
</para>
@@ -89,7 +89,7 @@
<title>Sink elements</title>
<para>
Sink elements are terminal points in a media pipeline. They accept data but do not produce
- anything. Disk writing, soundcard playback, and video output woul all be implemented by sink
+ anything. Disk writing, soundcard playback, and video output would all be implemented by sink
elements.
</para>
<figure float="1" id="sec-element-sinkimg">
@@ -105,8 +105,9 @@
<sect1 id="sec-elements-create">
<title>Creating a GstElement</title>
<para>
- GstElements are created from factories. To create an element, one has to get
- access the a <classname>GstElementFactory</classname> using a unique factoryname.
+ A <classname>GstElement</classname> object is created from a factory. To create an element,
+ you have to get access a <classname>GstElementFactory</classname> object using a unique
+ factory name.
</para>
<para>
The following code example is used to get a factory that can be used to create the
@@ -118,7 +119,7 @@
factory = gst_element_factory_find ("mad");
</programlisting>
<para>
- Once you have the handle to the elementfactory, you can create a real element with
+ Once you have the handle to the element factory, you can create a real element with
the following code fragment:
</para>
<programlisting>
@@ -127,13 +128,13 @@
element = gst_element_factory_create (factory, "decoder");
</programlisting>
<para>
- gst_element_factory_create () will use the elementfactory to create an element with the given
+ <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 lookup the element in a
- bin, for example. You can pass NULL as the name argument to get a unique, default name.
+ 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 elementfactory named "mad". This convenient function is
+ an element, named "decoder" from the element factory named "mad". This convenient function is
most widely used to create an element.
</para>
<programlisting>
@@ -155,16 +156,19 @@
<sect1 id="sec-elements-properties">
<title>GstElement properties</title>
<para>
- A GstElement can have several properties which are implemented using standard
- GObject properties. The usual GObject methods to query, set and get property values
- and GParamSpecs are therefore supported.
+ A <classname>GstElement</classname> can have several properties which are implemented
+ using standard <classname>GObject</classname> properties. The usual
+ <classname>GObject</classname> methods to query, set and get property values
+ and <classname>GParamSpecs</classname> are therefore supported.
</para>
<para>
- Every GstElement inherits at least one property of its parent GstObject, the "name"
- property. This is the name you provide to gst_element_factory_make() or
- gst_element_factory_create(). You can get and set this property using the
- gst_object_set_name() and gst_object_get_name() or use the GObject property
- mechanism as shown below.
+ Every <classname>GstElement</classname> inherits at least one property of its
+ parent <classname>GstObject</classname>, the "name" property. This is the name
+ you provide to the functions <function>gst_element_factory_make</function> or
+ <function>gst_element_factory_create</function>. You can get and set this property
+ using the functions <function>gst_object_set_name</function> and
+ <function>gst_object_get_name</function> or use the <classname>GObject</classname>
+ property mechanism as shown below.
</para>
<programlisting>
GstElement *element;
@@ -182,20 +186,22 @@
Most plugins provide additional properties to provide more information
about their configuration or to configure the element.
<command>gst-inspect</command> is a useful tool to query the properties
- of a perticular element, it will also use property introspection to give
+ of a particular element. It will also use property introspection to give
a short explanation about the function of the property and about the
parameter types and ranges it supports.
</para>
<para>
- For more information about GObject properties we recommend to read the GObject
- manual.
+ For more information about <classname>GObject</classname> properties we recommend you read the
+ <ulink url="http://developer.gnome.org/doc/API/2.0/gobject/index.html" type="http">
+ GObject manual</ulink>.
</para>
</sect1>
<sect1 id="sec-elements-signals">
<title>GstElement signals</title>
<para>
- A GstElement also provides various GObject signals that can be used as a flexible
+ A <classname>GstElement</classname> also provides various
+ <classname>GObject</classname> signals that can be used as a flexible
callback mechanism.
</para>
</sect1>
Index: gstreamer/docs/manual/goals.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/goals.xml,v
retrieving revision 1.3
diff -u -u -r1.3 goals.xml
--- gstreamer/docs/manual/goals.xml 24 Jul 2002 19:46:42 -0000 1.3
+++ gstreamer/docs/manual/goals.xml 30 Aug 2002 07:53:21 -0000
@@ -8,10 +8,10 @@
<sect1 id="sec-goals-design">
<title>The design goals</title>
<para>
- We descibe what we try to achieve with GStreamer.
+ We describe what we try to achieve with GStreamer.
</para>
<sect2 id="sec-goals-clean">
- <title>Clean and powerfull</title>
+ <title>Clean and powerful</title>
<para>
GStreamer wants to provide a clean interface to:
</para>
@@ -19,7 +19,7 @@
<listitem>
<para>
The application programmer who wants to build a media pipeline.
- The programmer can use an extensive set of powerfull tools to create
+ The programmer can use an extensive set of powerful tools to create
media pipelines without writing a single line of code. Performing
complex media manipulations becomes very easy.
</para>
@@ -69,8 +69,8 @@
have any header files installed for the plugins.
</para>
<para>
- Special care has been taking into making the plugin completely self
- contained. All relevant aspects of plugins can be queried at run-time.
+ Special care has been taken to make plugins completely self contained.
+ All relevant aspects of plugins can be queried at run-time.
</para>
</sect2>
@@ -115,7 +115,7 @@
</listitem>
<listitem>
<para>
- Allowing HW acceleration by the use of specialized plugins.
+ Allowing hardware acceleration by the use of specialized plugins.
</para>
</listitem>
<listitem>
@@ -138,7 +138,8 @@
<para>
GStreamer also wants to be an easy framework where codec developers
can experiment with different algorithms, speeding up the development
- of open and free multimedia codecs like tarking and vorbis.
+ of open and free multimedia codecs like <ulink url="http://www.xiph.org/ogg/index.html"
+ type="http">tarkin and vorbis</ulink>.
</para>
<para>
</para>
Index: gstreamer/docs/manual/gstreamer-manual.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/gstreamer-manual.xml,v
retrieving revision 1.4
diff -u -u -r1.4 gstreamer-manual.xml
--- gstreamer/docs/manual/gstreamer-manual.xml 7 Apr 2002 23:32:11 -0000 1.4
+++ gstreamer/docs/manual/gstreamer-manual.xml 30 Aug 2002 07:53:21 -0000
@@ -94,10 +94,13 @@
<xref linkend="overview"/> gives you an overview of <application>GStreamer</application>
design goals. <xref linkend="basic-concepts"/> rapidly covers the basics of
<application>GStreamer</application> programming. In <xref linkend="build-app"/> we will move
- on to the examples. Since <application>GStreamer</application> uses GLib 2.0, the reader is
- assumed to understand the basics of the GObject object model. For a gentle introduction to
- this system, you may wish to read the <emphasis>GTK+ Tutorial</emphasis> or Eric Harlow's
- book <emphasis>Developing Linux Applications with GTK+ and GDK</emphasis>.
+ on to the examples. Since <application>GStreamer</application> uses <ulink url="
+ http://developer.gnome.org/arch/gtk/glib.html" type="http">GLib 2.0</ulink>, the reader is
+ assumed to understand the basics of the <ulink url="http://developer.gnome.org/doc/API/2.0/gobject/index.html"
+ type="http">GObject object model</ulink>. For a gentle introduction to
+ this system, you may wish to read the <emphasis><ulink url="http://www.gtk.org/tutorial/"
+ type="http">GTK+ Tutorial</ulink></emphasis> or Eric Harlow's book
+ <emphasis>Developing Linux Applications with GTK+ and GDK</emphasis>.
</para>
</partintro>
@@ -114,7 +117,7 @@
<part id="basic-concepts"><title>Basic concepts</title>
<partintro>
<para>
- We will first describe the basics of the <application>GStreamer</application> programming by
+ We will first describe the basics of <application>GStreamer</application> programming by
introducing the different objects needed to create a media pipeline.
</para>
<para>
Index: gstreamer/docs/manual/init.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/init.xml,v
retrieving revision 1.3
diff -u -u -r1.3 init.xml
--- gstreamer/docs/manual/init.xml 24 Jul 2002 19:46:42 -0000 1.3
+++ gstreamer/docs/manual/init.xml 30 Aug 2002 07:53:21 -0000
@@ -2,12 +2,13 @@
<title>Initializing <application>GStreamer</application></title>
<para>
When writing a <application>GStreamer</application> application, you can
- simply include gst/gst.h to get access to the library functions.
+ 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
- gst_init () has to be performed from the main app. this call will perform
- first initialisation and will parse the GStreamer specific command line
+ <function>gst_init</function> has to be called from the main app. This call will perform
+ first initialization and will parse the GStreamer specific command line
options.
</para>
<para>
@@ -28,17 +29,29 @@
}
</programlisting>
<para>
- It is also possible to call the gst_init method with two NULL arguments.
+ FIXME: What options does gst_init look for and what do they do???
+ </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
+ parsed by <application>GStreamer</application>.
</para>
<para>
- Use the GST_VERSION_MAJOR, GST_VERSION_MINOR and GST_VERSION_MICRO macros to
- get the <application>GStreamer</application> version you are building against or
- use gst_version() to get the version you are linked against.
+ 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.
</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 code fragment:
+ You can also 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>
<programlisting>
int
Index: gstreamer/docs/manual/intro.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/intro.xml,v
retrieving revision 1.4
diff -u -u -r1.4 intro.xml
--- gstreamer/docs/manual/intro.xml 24 Jul 2002 19:46:42 -0000 1.4
+++ gstreamer/docs/manual/intro.xml 30 Aug 2002 07:53:21 -0000
@@ -24,7 +24,7 @@
<para>
One of the the most obvious uses of GStreamer is using it to build a media player.
GStreamer already includes components for building a media player that can support a
- very wide variety of formats including mp3, Ogg Vorbis, Mpeg1, Mpeg2, Avi, Quicktime, mod
+ very wide variety of formats including mp3, Ogg Vorbis, MPEG1, MPEG2, AVI, Quicktime, mod
and so on.
GStreamer, however, is much more than just another media player. Its
main advantages are that the pluggable components can be mixed and matched into
Index: gstreamer/docs/manual/motivation.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/motivation.xml,v
retrieving revision 1.4
diff -u -u -r1.4 motivation.xml
--- gstreamer/docs/manual/motivation.xml 24 Jul 2002 19:46:42 -0000 1.4
+++ gstreamer/docs/manual/motivation.xml 30 Aug 2002 07:53:21 -0000
@@ -83,7 +83,8 @@
</para>
<para>
No provisions have been made for emerging technologies such as
- the GNOME object embedding using Bonobo.
+ the <ulink url="http://developer.gnome.org/arch/component/bonobo.html"
+ type="http">GNOME object embedding using Bonobo</ulink>.
</para>
<para>
The GStreamer cores does not use network transparent technologies at the
Index: gstreamer/docs/manual/plugins.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/plugins.xml,v
retrieving revision 1.3
diff -u -u -r1.3 plugins.xml
--- gstreamer/docs/manual/plugins.xml 9 Jul 2002 18:43:13 -0000 1.3
+++ gstreamer/docs/manual/plugins.xml 30 Aug 2002 07:53:21 -0000
@@ -1,5 +1,8 @@
<chapter id="cha-plugins">
- <title>What are Plugins</title>
+ <title>Plugins</title>
+ <para>
+ FIXME: Type definitions should be introduced before this chapter
+ </para>
<para>
A plugin is a shared library that contains at least one of the following items:
</para>
@@ -7,17 +10,17 @@
<itemizedlist>
<listitem>
<para>
- one or more elementfactories
+ one or more element factories
</para>
</listitem>
<listitem>
<para>
- one or more typedefinitions
+ one or more type definitions
</para>
</listitem>
<listitem>
<para>
- one or more autopluggers
+ one or more auto-pluggers
</para>
</listitem>
<listitem>
@@ -27,12 +30,12 @@
</listitem>
</itemizedlist>
<para>
- The plugins have one simple method: plugin_init () where all the elementfactories are
- created and the typedefinitions are registered.
+ All plugins have one main function, <function>plugin_init</function>, that creates all the
+ element factories and registers all the type definitions contained in the plugin.
</para>
<para>
- the plugins are maintained in the plugin system. Optionally, the typedefinitions and
- the elementfactories can be saved into an XML representation so that the plugin system
+ The plugins are maintained in the plugin system. Optionally, the type definitions and
+ the element factories can be saved into an XML representation so that the plugin system
does not have to load all available plugins in order to know their definition.
</para>
@@ -40,6 +43,8 @@
The basic plugin structure has the following fields:
</para>
<programlisting>
+typedef struct _GstPlugin GstPlugin;
+
struct _GstPlugin {
gchar *name; /* name of the plugin */
gchar *longname; /* long name of plugin */
@@ -57,7 +62,8 @@
</programlisting>
<para>
- You can query a GList of available plugins with:
+ You can query a <classname>GList</classname> of available plugins with the function
+ <function>gst_plugin_get_list</function> as this example shows:
</para>
<programlisting>
GList *plugins;
Index: gstreamer/docs/manual/threads.xml
===================================================================
RCS file: /cvsroot/gstreamer/gstreamer/docs/manual/threads.xml,v
retrieving revision 1.5
diff -u -u -r1.5 threads.xml
--- gstreamer/docs/manual/threads.xml 9 Jul 2002 18:43:13 -0000 1.5
+++ gstreamer/docs/manual/threads.xml 30 Aug 2002 07:53:22 -0000
@@ -81,7 +81,7 @@
/* eos will be called when the src element has an end of stream */
void
-eos (GstSrc *src, gpointer data)
+eos (GstElement *src, gpointer data)
{
GstThread *thread = GST_THREAD (data);
g_print ("have eos, quitting\n");
More information about the gstreamer-devel
mailing list