[gst-devel] application development manual

[Ronald S. Bultje]

Hi,

I just sort-of finished the plugin writer's guide (see #125890 for
pending issues, it's good enough as it is). Given the amount of, well,
"newbie questions" that we get on how to do this or that, I thought I'd
revive the application development manual too. I'll shortly discuss what
it contains now and what I think it should contain.

First, I'd like to start with a general idea on our docs. I think Stefan
also had some ideas on it, so let's work something out. We currently
have three basic types of docs: application development manual (ADM),
plugin writer's guide (PWG) and the API references. Some time ago,
Stefan suggested to split the PWG/ADM up in three parts: 1) intro to
GStreamer, 2) plugins 3) applications. I'm not sure if this is a good
idea. The PWG and ADM should both be readable without requiring the
other to be read. A general introduction is useful, though. I think we
should put that on http://gstreamer.freedesktop.org/documentation/, or
(if it turns out to get large) be the first item in the list of
available documents. "Tell what GStreamer is ..." (maybe mention the
pad/element/link concept) "... and tell when you should read the ADM,
PWG and API refs." Furthermore, Stefan suggested to make the API refs
linked in the ADM/PWG. I'm not sure how easy that is (from a technical
perspective), but I like that idea. Anyway, I'd like to keep the PWG and
ADM around as they are and add a general introduction on our docs
frontpage, that's enough.

No on to what's in the ADM now: the first chapter is introduction, the
second chapter explains basic concepts (elements, plugins, pads, links,
bins, buffers, states). It's very conceptual and not really targetted at
application development yet. Chapter 3 discusses the same things again,
this time from an application perspective (with small pieces of example
code). Chapter 4 contains first application examples. Chapter 5 is on
advanced concepts, such as threads, scheduling, clocks, autoplugging and
dparams. Chapter 6 discusses XML and chapter 7 contains non-core related
topics such as GNOME, Win32, gstplay and other stuff such as gst-launch,
debugging (in plugins!) and so on.

So, what should we do with it (imo)? Here's some ideas:

* chapter 2, 3 and the first half of 4 should be merged and used as a
first introduction to application-related concepts in GStreamer.
Basically, it will explain how to build a mp3 player (this should
obviously be ogg/vorbis, btw) and so on. It will discuss "low-level"
details such as pads, buffers, elements and plugins. In the end of this
chapter, people will be able to write a small media-related application.
This chapter can still be very player-centric, since that's easiest to
explain. We should, however, stress that playback is not all we can do.
Stuff that should be added here is querying (for position/length).

* the second half of chapter 4 (on types) and 5 should be merged in an
'advanced' part. This part will explain concepts in GStreamer that you
don't necessarily need to build applications, but that are useful to
understand if you go deeper into application-building. Threads, queues,
clocks and so on are *concepts* in applications, you don't actually use
them too much really. We should add parts on interfaces and tags.

* Chapter 6 can be kept, but maybe as a subchapter in 'higher
interfaces'. The previous chapters will be "low-level" interfaces to
GStreamer. In this chapter, we should discuss higher interfaces such as
playbin (gstplay? spider?), xml, GNOME (/KDE/Win32) application
integration, maybe gnome-media's audio encoding profiles, and so on.
Basically, in the preface, we should refer to this chapter for those of
us that "just want to build a working media player without going through
this whole mess". Maybe we should even move it to before the advanced
topics, to prevent confusing readers. We can link to things such as
interfaces, dparams or such things (in advanced) because people will ask
questions. Maybe we should even provide full-blown code for Qt/Gtk
widgets that embed XOverlay. People will ask for this at some point, and
we have good & simple widgets available already.

* the appendices can be kept, but really need some clean-ups. The win32
chapter includes full discussions on how to *build* Gstreamer on win32,
which totally doesn't belong there. That should move somewhere else. For
other archs/oses, we mention this information in our release notes, we
should link to such a page (which is then hosted somewhere else on our
website) in our release notes as well. It does *not* belong in the ADM.
The plugin debugging stuff should move to the PWG (wrong as well).

Comments? Like it?

Ronald

-- 
Ronald S. Bultje <rbultje at ronald.bitfreak.net>