Re: xmldocs.make and friends

[Malcolm Tredinnick <malcolm commsecure com au>]

On Fri, Sep 06, 2002 at 11:38:21AM +0800, James Henstridge wrote:
[...]
> The current practice of include'ing the desired rules seems sound, the 
> problem to solve is to only have to maintain the file in a single 
> location.  In the past, we have used a number of different methods for this.
> 
> For instance, with the dreaded "macros" directory, we used cvs includes, 
> which has its own problems.  The main one was that of branching.  People 
> would branch their module, and end up branching the macros directory as 
> well.  This meant that they would effectively stop seeing updates to the 
> macros, because the people maintaining the macros wouldn't merge changes 
> to their branches.  So this solution would leave us with the same 
> problems in some cases.  Just take a look at the "cvs status -v" output 
> for some files in the macros directory to see how much of a problem this 
> could be (about 200 branches so far ...).

Couldn't agree more!

> 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. 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.

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.

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. :-(

Malcolm