CVS checkout and automatically building API reference documentation

[Patrick <pabos glypsube org>]

Hi.
In the hopes of obtaining a maintainable source of reference
documentation I've been looking at trying to build API reference
documentation using gtk-doc recently.

Having spent some time looking at websites with stale references and
unsuccessfully trying to build from scratch I have a few questions which
I would appreciate some help with if anyone feels so inclined. Not all
of the questions relate specifically to getting documentation to build.

I'll describe the steps I've taken below in fairly detailed steps since
it may be useful in pointing out what went wrong.

0. Clean RedHat 9 with latest RHN updates.
1. Create build environment:
	su -
	mkdir /build
	chown patrick:patrick /build
	exit
	cd /build
	vi setup.bash
		PATH=/build/bin:$PATH
		PREFIX=/build
		CVSROOT=':pserver:anonymous anoncvs gnome org:/cvs/gnome'
		export PREFIX
		export CVSROOT
	source setup.bash
	mkdir /build/tgz
	... download:
		autoconf-2.57.tar.bz2
		automake-1.7.3.tar.gz
		libtool-1.4.3.tar.gz
	...
	mkdir /build/src
	... install auto* tools
		./configure --prefix=/build
		make
		make install
	... checkout gtk-doc and build
		cd /build/src
		cvs -z3 checkout gtk-doc
		cd gtk-doc
		./configure --prefix=/build
		make
		make install
2. Try to build glib with documentation
	cd /build/src
	cvs -z3 checkout glib
	cd glib
	./configure --prefix=/build --enable-gtk-doc
	make
	make install
3. No documentation and no (obvious) errors.
	cd /build/src/glib
	ls docs/reference/glib
		... sgml files and txt files ...

	Makefile recursion exits docs/ directories immediately.

	/build/share/gtk-doc/html/glib is empty too (if thats even
	where it was supposed to go).


ADDITIONAL QUESTIONS
1. Is there a make target to build documentation? ie. can you build
documentation independently of building source?

2. If I wanted to be able to build documentation for older GNOME
releases as well what would change? (ie. is there a standard set of
auto* tools, gtk-doc version associated with GNOME 1.4, 2.0, 2.2?)
	I'd like to be able to script the creation
	of the build environment so that the documentation for any
	release can be built automatically.

	Also, any ideas on how point releases should be handled? I'm thinking
that the latest point release (ie. 2.0.6) would be the documentation for
that major release.

3. Once the documentation is built is there a way of generating XML
documentation (with some known published DTD/schema) instead of HTML?

4. Is documentation built in its own directory (ie.
docs/reference/glib/html) including resources such as pictures? That is,
can I grab everything within a single directory and be assured of having
taken the complete documentation.

5. Is there a tag/markup to indicate what version of the library a
function/structure/whatever was added?

6. Is there any provision for translating the API documentation?


Thanks for your time.


-- 
Patrick <pabos glypsube org>