[gst-devel] documentation

[Thomas Vander Stichele]

Hey people,

 I've commited a bunch of changes to the docbook documentation build
setup, because they were broken again and I was frustrated :)

I think I solved just about every issue I had with them, and everything
seems to work fine now.

If you're interested, here's where it stands now:
a) docs are in docbook-xml, 4.2
b) source images are either .png or .fig (we could add more later if
needed)
c) output formats are html, ps and pdf
d) configure checks for necessary tools
e) I renamed the base xml files, as well as the output files, to
"manual", "faq" and "pwg" respectively.
f) docs install in $datadir/doc/$(PACKAGE)-$(VERSION)/$(doc)

This was phase 1.  The next thing I want to do is fix the documentation
itself and update it.

Here are my plans:
a) only work on docs in HEAD (close docs in 0.6)
b) typofix the manual
c) make sure every code example used is a) built from seperate entities
(so we can reference them properly in the docs) and b) builds so it gets
kept in sync with the API
d) break up chapter II in two.  In the first of the two, I only want to
mention "theory", ie. no code at all.  In the second, we start with the
helloworld example, break it up as an introduction, then go through each
of the bits from chapter II again but with code explanation.
e) I want the examples that reference mp3 to change to Ogg/Vorbis (as a
way of promoting free formats)
f) Some of the code/docs need to move to the plugin writers guide.

I've already changed things around in my hardcopy of the manual, and if
nobody objects I'll start committing these changes to CVS HEAD soon.
Anyone have anything to add, questions, ... ?

Thomas

Dave/Dina : future TV today ! - http://davedina.apestaart.org/
<-*- thomas (dot) apestaart (dot) org -*->
Ik heb vannacht gedronken en gezien
Hoe jij van mij nooit krijgt wat je verdient
<-*- thomas (at) apestaart (dot) org -*->
URGent, best radio on the net - 24/7 ! - http://urgent.rug.ac.be/