new docs build setup

[John Fleck <jfleck inkstain net>]

Folks -

Malcolm has put together an improved docs build system that eliminates
the problem of maintaining mutliple xmldocs.make and omf.make files all
over GNOME cvs, pulling them from gnome-common at when you autogen a
package instead.

Malcolm's instructions cannot be improved upon. I quote:

****************
There is a README file in gnome-common/doc-build that gives a short
description of what is needed. I tested this with gnome-desktop (which
is reasonably correct under the old system, but not entirely up to
date). The changes I needed to make were:

(1) Remove sgmldocs.make, xmldocs.make (ultimately, these would be
removed from CVS as well). If a package has omf.make, that should be
removed as well, of course.

(2) Change autogen.sh. The line that invokes the standard
gnome-autogen.sh needed to be changed from

        USE_GNOME2_MACROS=1 . gnome-autogen.sh

to

        USE_GNOME2_MACROS=1 USE_COMMON_DOC_BUILD=yes . gnome-autogen.sh

(you could also put "export USE_COMMON_DOC_BUILD=yes" on an earlier
line, which may be neater).

(3) If I was putting this in CVS, I would add xmldocs.make and omf.make
to .cvsignore in the top-level directory. It would also be good to add
*.omf.out to the .cvsignore file in any directory containing and OMF
file (the *.omf.out files are a temporary by-product of the build
process. They are removed as part of 'make clean').

The only fiddly thing to be aware of is that all the Makefile.am files
in the documentation directories need to refer to
$(top_srcdir)/xmldocs.make, not some other location for xmldocs.make.
This is because that is where the gnome-doc-common script places them
(when run from autogen.sh). Some existing modules seem to have this
makefile fragment in other locations (like doc/ or help/). They will
need to be slightly edited.
******************

I've started adding a "2.4 build" column to the doctable so we can keep
track of this as we update the various packages.

Cheers,
John
-- 
John Fleck
jfleck inkstain net (h) jfleck abqjournal com (w)
http://www.inkstain.net http://www.abqjournal.com
http://www.gnome.org/learn/users-guide/latest/

"Not only isn't reality real - it's an illusion created by unreal people to
sell real people unnecesary cars." - Griffy