[gst-devel] [PATCH] documentation patches

[Cameron H. <cam...@xd...>]

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").