Re: xmldocs.make and friends

[James Henstridge <james daa com au>]

Malcolm Tredinnick wrote:

> > The other way is to copy the files into the build tree as part of the 
> > autogen.sh process.  This would probably involve hackers needing to 
> > install a gnome-doc-tools package of some form, and having a script that 
> > would copy/symlink the files into the build tree, that could be called 
> > during autogen (I am guessing this is what Jody was suggesting).  This 
> > shouldn't suffer from any of the problems with the macros directory.
> >    
>
> We already need to have the gnome-common module installed, so finding
> some way to put it in there would be nice. In that case we need to copy
> the relevant files at autogen.sh time, rather than linking them.
I would prefer to see gnome-common die completely, but it might be the 
easiest way to do it.  The main issue with gnome-common is that it has 
always been a dumping ground with no clear maintainer.  If that is not a 
problem, then go ahead :)

> The
> reason for this is that gnome-common is not required to build from
> tarballs, only from CVS. So we need to make sure that 'make dist'
> includes the right file, not a link to it. The appropriate incantations
> here are not difficult.
"make dist" will tar up the file contents, rather than the symlink. 
This is how automake, gettextize and libtoolize work by default.

> Another advantage of including this in gnome-common is that we can
> write m4 macros when we need it to enable more flexibility in the docs
> build. Having an AC_BUILD_DOCS macro that allows some configuration
> could eventually be useful. Then we can say "the scrollkeeper stuff
> should go over here" (currently impossible without black magic) and
> similar things on the configure command line.
Don't put the AC_BUILD_DOCS macro into the gnome-common macros 
directory.  It should be installed in $(datadir)/aclocal like a normal 
macro.

> Having said all that, here's a big drawback that just occurred to me: it
> won't work. Basically, if we ever break backwards compatibility in the
> common xmldocs.make, we would need to tag gnome-common and say that
> version X of foo-docs requires version Y of gnome-common. This is going
> to be really icky when building older packages. Other solutions I can
> think of that don't involve branching gnome-common (or gnome-docs-common
> -- it's not tied to the location of the common script) are similarly
> awkward. James, do you have any bright ideas about how to get around
> this one? ... my brain is full and refuses to cooperate at the moment.
>
> Hmm .. so that was two good points and one show stopper. Probably a net
> minus. :-(
Well, if you branch a module, and need an older version of the 
gnome-doc-tools build files, you can do the same thing you would if you 
needed a particular libtool version: just check in the files it copies 
to your build dir, and don't call the gnome-doctoolize script (or 
whatever it gets called) in autogen.

That being said, you probably want to make the interface between the 
Makefile.am and xmldocs.make as small and well defined as possible. 
Possibly prefixing internal rules/variables with some value would help 
here, so it is obvious when people are going outside of the defined 
interface.

It would also be good to review where errors are being ignored, and work 
out which errors really should be treated as errors.

James.
(who is still working on getting the API doc tools to suck less)

--
Email: james daa com au              | Linux.conf.au   http://linux.conf.au/
WWW:   http://www.daa.com.au/~james/ | Jan 22-25   Perth, Western Australia.