Documentation of gtk-doc

[Malcolm Tredinnick <malcolm commsecure com au>]

I notice in the GNOME 2 release committe minutes that somebody brought
up the point of providing assistance to others on, amongst other things,
gtk-doc.

One of my current "it would be nice to do" items is to write some better
gtk-doc documentation than currently exists (basically some kind of
HOWTO). However, since I'm probably not going to get to that for a week
or so, if anybody wants to pick up the challenge, here are some notes on
what curerntly exists and what I think needs to be done. I'm assuming
the person writing this documentation has either some experience in
documenting APIs with gtk-doc or has read the gtk-doc-list archives back
to about January (it's a low volume list, so not too hard). The
following is just in "raw brain dump" format, since I'm lazy. 

	- There is already some documentation in gtk-doc/help/manual/C.
	  However, it is nearly a year old and much has changed in that
	  time.
	
	- The setup required needs to made simple (a checklist?).
	  Generally, if you can already run jade or jw on gnome-docs,
	  then gtk-doc setup is basically done.
	
	- Documentation intended for those starting to document is in
	  gtk-doc/doc. Most items of relevance are mentioned in there,
	  but they could be made more obvious and ordered for people
	  just starting out.
	
	- gtk-doc will now (as of a few months ago) scan header files,
	  so structures and enums can be documented inline, rather than
	  having to go in the template files.
	
	- The documentation in gtk-doc/doc really talks about
	  documenting for glib/gtk-1.2 based APIs. For 1.3 (soon-to-be
	  2.0) APIs, any reference to gtkdoc-scanobj should be replaced
	  with gtkdoc-scangobj. However, except for apps that create
	  their own widgets, it will not be necessary for either of
	  these to be run.
	
	- Running gtk-doc requires an X-server, since it needs, in some
	  cases, to compile a small gtk+ program and run gtk_init(). The
	  nightly runs on d.g.o use Xvfb to satisfy this requirement.
	
	- The output is DocBook-sgml, then converted via jade and then
	  post-processed to make links to external documents work.
	  Making it produce Docbook-xml with correct links and all is a
	  bit tricky. See the exchange between DV and owen in this
	  thread

	http://mail.gnome.org/archives/gtk-doc-list/2001-June/msg00001.html

	  if you are interested, but for documentation purposes, it is
	  probably just worth pointing out that this is the situation.
	
	- There are bugs in gtk-doc. It is a bunch of special cases
	  grouped together and when new cases are found, they are added
	  (especially to the parsing code). This is because it was built
	  for a specific purpose and then is growing as required. The
	  gtk-doc list seems friendly, so people wanting to use gtk-doc
	  should visit their (and read the archives, since questions
	  have come up before, surprisingly enough!).

My plan would be to take the skeleton of a manual that currently exists.
Update it. Merge in the information from the gtk-doc/doc directory and
include some of the common problems that come up on the mailing list,
along with some of the "behind the curtains stuff" I mentioned above
(why not XML, why gtk-doc is not perfect, etc).

As I said, there's pretty much no way I'm going to get to this in the
next week or two, so if somebody wants to run with it, feel free to use
the above (or to ignore it at will). However, if you do start working on
it, please let me know so that I don't accidently duplicate effort.

Cheers,
Malcolm

-- 
42.7 percent of all statistics are made up on the spot.