*** Bug 123747 has been marked as a duplicate of this bug. ***

do s/GNOME/GObject/g, where GObject may be something else depending on
context. We don't want to anger KDE guys, now do we? ;)

<Gelmir> A filter is an important type of element that processes a
stream of data. Producers and consumers of data are called source and
sink elements, respectively. Bin elements contain other elements. One
type of bin is responsible for scheduling the elements that they
contain so that data flows smoothly. Another type of bin, called
autoplugger elements, automatically add other elements to the bin and
link them together so that they act as a filter betw
<Gelmir> een two arbitary stream types.

I'm being told that this sounds extremely vague to a newcomer.

Oh, and dave told me the bufferpool story is outdated, too.

And section-preface-reading.html should point to Matthieu's GObject
doc on http://www.le-hacker.org/papers/gobject/index.html

bufferpool stuff is rewritten.

IMO, a filter is restricted to elements that always have the same caps
on both source and sink pads.  Thus, demuxers, decoders, and
colorspace are not filters, which is not clear from the current
description.  I prefer to use the term 'converters' for
format-changing elements (like colorspace, audioscale, videoscale, or
audioconvert).

Erik used to use the term 'filter' for everything that wasn't a source
or a sink, which I think is incorrect.

Elements can be divided into several categories by their function and
by how they work:
- Filters are the elements that do most of the work one would consider
"processing media". They take some input data (by so called _sink
pads_, described in next chapter), manipulate it in some way, and
produce some output, pushing it through _source pads_. Filter elements
are for example codecs, visualisation elements, or sample rate converters.
- Source and sink elements are producers and consumers of data,
respectively. Example of source may be filesrc element that allows to
read data from file on disk.
- Another type of elements are _managing elements_, such as bins,
threads and pipelines themselves that can contain other elements.
Although it may not seem obvious, they are also subclassed from
GstElement and as such are first class elements.
- Special, and very useful type of bin is _autoplugger_, ie. bin that
can perform arbitrary manipulation on data types, by managing its
child elements accordingly. This way you can request specific
*transformation* instead of linking specific elements, and thus avoid
having to hardcode some required elements in your application.

Will that do? Apart from David having just commited definition of
'filter' that obviously conflicts with what's written above ;)

In the "Constructing the boiler plate/GstElementDetails" section, I'd
change the sentence "The element details are registered with the
plugin during _base_init ()." to explicitly say that this _base_init
() function is the GObject _base_init () function, not something
specific to GStreamer.

The "Constructing the Boilerplate/GstStaticPadTemplate" pad template
section lacks an example of using gst_pad_new_from_template () in an
_init function.
The current _base_init example defines static pad templates as local
variables, I suppose they should be static globals so that they can be
used both in _init and in _base_init. 
Maybe what I'm saying doesn't make much sense, but anyway this section
needs a bit of clarification since I had to look at an existing
plug-in to find out what I should do with gst_pad_new_from_template ;)
Maybe it could also be mentioned that the gchar *name argument to
gst_pad_new_from_template may seem redundant with the name passed when
initializing the static pad template, but that it's useful with other
pad types.

Looks like my 2 previous complaints are addressed in the PWG, but the
explanations come in later sections.

(I apologize for the spam on this bug)
There is a small typo in "The chain function" section:
lineair => linear in the second sentence.
I didn't see any mention of loop functions, maybe they should be
mentioned when chain functions are first introduced, with the
differences between both being described, and with a comment that
chain functions are recommended and loop functions are reserved for
more advanced stuff ?

Once again, I should have read a bit more before my last comment, loop
functions are mentioned ;)

This should be my last comment, mainly abotu some typos

"What are states?"
Mangaging filter state => Managing filter state

"Signals"
Make it explicit that this is abotu GObject signals, and not Posix
signals or something else

"Building a Test Application"
Ususally => Usually (in the 2nd sentence)

"How a loopfunc works"
ascynronous => asynchronous
different display timestamp then the data => ... than the data

"The Bytestream Object"
 that receive of pull full buffers of a random size => this sentence
seems a bit awkward, I had to read it a second time and slowly to
understand it ;)
ususally  => usually
comment: when I used bytestream, I had perf issues (100% cpu) when
calling gst_bytestream_peek_data too often with small byte count. This
should probably be mentioned (and if this is considered as a bug, I'll
be glad to file it separately ;)

"Types and Properties"
neccessary => necessary

"Tagging (Metadata and Streaminfo)"
butthey => but they
rathen => rather

The section "The Bytestream Object" should mention that you need to
have something like 
if (!gst_library_load ("gstbytestream")) {
		return FALSE;
	}
in your plugin_init function, and it could also tell which file need
to be included to get the bytestream functions.

The pluginstamp.sh script which is mentioned in Building a
filter/Using the Project Stamp no longer seems to exist
The CVSROOT in Getting the GStreamer Plugin Templates is wrong, it
should be 
:pserver:anoncvs@cvs.freedesktop.org:/cvs/gstreamer
instead of 
:pserver:anonymous@cvs.freedesktop.org:/home/cvs/gstreamer

http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/section-types-typefind.html

The code there is wrong, it misses several brackets.

*** Bug 138972 has been marked as a duplicate of this bug. ***

I fixed everything mentioned above as far as I could. Currently, the following
chapters are still pending:

* All appendices. Do we want to remove them?
* The sections on N-to-N elements and autopluggers. Both can be useful, but we
shouldn't go too deeply into them. These topics are hard. The section on N-to-1
elements currently uses _pad_select(), which it shouldn't. The section on muxers
suggests to use explicit caps, it probably shouldn't do this.
* navigation interface is empty.
* 

OK, so I accidently pressed enter...

* navigation events
* the preface has a lot of stuff marked as fixme that is finished. We should
remove the fixmes.
* preface mentions chapters on writing a scheduler. Ehm... right.

That's all... We're almost there.

OK, so the preface is updated now. See above for the rest (#18/#19).

Last notes on stuff that's missing:

* querying, converting and so on isn't mentioned anywhere except in the other-
chapters. They should be discussed in general before that.
* elements without dynamically loadable plugins.

We should probably have a blurb about why glib mainloop integration in a plugin
is a bad idea somewhere too.

*** Bug 165604 has been marked as a duplicate of this bug. ***

See Stefan's comments in bug #165604 about order of presenting different kinds
of dataflow functions. Of course this is a bit different in 0.9.

Christian: stuff that isn't a good idea should not go in the PWG. Stuff that
*is* a good idea should. Else we'll be discussing everything in the whole world
as not-a-good-idea. If it happens, it's a bug and we'll fix it in that plugin.
No need to mention it here.

status update for 0.9:

done:
* N-to-N/autoplug removed, since it doesn't do anything... Pointless anyway.
(re: #18)
* scheduling is explained in detail in the advanced-scheduling.xml doc (re: Andy)

Still todo:
* navigation interface/events... (#18/#19)
* query/event handling discussion isn't all too good. (#21)
* we need to discuss metadata/tags (both read and write) and the URI interface, too

I'm closing this.  Clearly we're not interested in using a TRACKER bug for this.