Makefile support for packages using gtk-doc

[James Henstridge <james daa com au>]

At the moment, setting up gtk-doc for a new package is fairly non 
trivial.  Setting up the Makefile is probably one of the more difficult 
parts of this process.

Most people end up copying the makefile from another package and editing 
a few variables at the top.  This problem with this is that when people 
find and fix bugs in their gtk-doc makefiles, the changes won't be 
propagated to other packages that copied the makefile.  It would be nice 
if there was only a single gtk-doc support makefile that everyone used, 
so that this wouldn't be a problem.

Newer versions of automake solve part of this problem with the "include" 
command (the behaviour of this command changed between 1.4 and 1.5 -- 
before it would be passed through for make to handle.  Now it is 
processed by automake itself).  A gtk-doc makefile might get reduced to 
something like this:
--- cut here ---
# require automake >= 1.5 for include support
AUTOMAKE_OPTIONS = 1.5

# info about this module
DOC_MODULE = libglade
DOC_MAIN_XML_FILE = libglade-docs.xml
DOC_SOURCE_DIR = ../glade
GTKDOC_CFLAGS = ...
GTKDOC_LIBS = ...
...
include $(srcdir)/gtk-doc.make
--- cut here ---

All the complicated automake rules would be confined to a separate file: 
gtk-doc.make.  To copy the gtk-doc.make file, maybe a "gtkdocize" script 
might be appropriate.  It could then be copied in when autogen.sh is run 
(it would need to be run before automake).  There are a number of 
situations that have occurred where this kind of setup would have helped:

   * switch over to the new html style.  many makefiles needed updating
     to install the navigation images with the rest of the documentation.
   * upgrading automake.  With automake >= 1.5, "make distcheck" uses a
     read only source directory.  Having a single gtk-doc.make would
     mean that there is only a single place to fix the problem.  At the
     moment, old gtk-doc makefiles are probably one of the things
     slowing down the switch to up to date automakes.

If we adopt something like this, it might be worth revisiting whether it 
is a good idea to provide a gtk-doc.m4 file.  A few reasons for 
providing one include:

   * don't have to worry about broken gtk-doc version checks in
     configure scripts.  This was one of the pros mentioned last time.
   * can provide consistent --enable-gtkdoc/--disable-gtkdoc configure
     script arguments.
   * the macro can make sure that all conditionals and makefile
     variables needed by the gtk-doc.make fragment are defined.

What do people think of this idea?  These additions would not break 
existing packages, but make it easier for new packages to adopt gtk-doc 
(and allow maintainers of existing packages to simplify the gtk-doc magic).

James.

--
Email: james daa com au
WWW:   http://www.daa.com.au/~james/