Re: xmldocs.make and friends

[Malcolm Tredinnick <malcolm commsecure com au>]

On Wed, Sep 11, 2002 at 06:51:32AM -0600, John Fleck wrote:
> On Sat, 2002-09-07 at 20:51, Jody Goldberg wrote:
> > My first thought was to have something akin to intltool.  However, I
> > suspect that a low tech approach may be simpler.   Have a module
> > that contains
> >     - a copy of the xmldocs.make file
> >     - pkgconfig info with a pointer to the installed copy of xmldocs.make
> > Then application can cut-n-paste some pkgconfig magic to find and
> > include the common copy of the xmldocs.make file.
> > 
> > It avoids making major changes to the current infrastructure, and
> > does not suffer from the problems associated with the dreaded
> > 'macros' dir approach.
> > 
> 
> This sounds like the simplest approach, but y'all need to explain stuff
> better for me. How does "pkgconfig" work? Where would the installed copy
> of xmldocs.make (and omf.make) go? gnome-common? Or do we still need to
> create our own module to handle this? And will this approach still be
> subject to the backwards compatibility problem Malcolm alluded to
> earlier?

At the risk of putting words into Jody's mouth, I think I can explain
what he's thinking here...

We make a package called, for sake of argument, gnome-docs-common. This
is required to be installed by anybody building from source tarballs
(not just from CVS). This package will install the xmldocs.make and
omf.make files along with the pkgconfig stuff required to find it for
other packages.

When another package is being built and it wants to include the makefile
fragments for building the documentation, it needs to know where they
are installed on the builder's system. So it asks pkg-config for this
information. Normally pkg-config is used to extract the required C
header include paths and library paths for linking, etc, but you can
store arbitrary configuration data in there. Each application that
supplies information via pkg-config just installs a foo.pc file in
$prefix/lib/pkgconfig/.

To clear up some confusion that appears to be creeping in: this is
different from gnome-common. The gnome-common module is only required by
people building from CVS (i.e. those who have to run autoconf, aclocal
and automake). It is _not_ required for building from tarballs, whereas
the pkg-config solution that I think Jody is proposing is required in
the latter case.

Also, I think we are pretty much doomed with respect to backwards
compatibility, but I have probably talked myself down from that ledge.
It's just not as big a problem as I was thinking it might be.

As soon as we have any kind of common code that is being used in builds,
we are going to have to think hard before breaking it in a
backwards-compatible sense. However, this is no greater responsibility
than any other core package has. Also, all this really means is that we
do not go around randomly requiring people to change the Makefile.am
file that lives in their documentation directories. This is the file
that currently says something like

	figs =
	docname = foo
	lang = en_AU
	omffile = foo-en_AU.omf
	entities =
	include $(top_srcdir)/xmldocs.make
	dist-hook: app-dist-hook

so it's not going to be too much of a challenge not to require changes,
since it really only contains the most basic of information. The "magic"
that happens inside xmldocs.make we can mess around with as much as we
like without imposing upon the other maintainers.

> The other issue we need to address is finding a hacker to implement
> whatever we come up with. I'll work closely with whoever, but I'm not
> comfortable/competent doing this kind of stuff myself.

I started to knock this together this evening and it nearly works. I
think we probably need a new module for it, since it's something that
will need to be packaged up and distributed and it needs to be built
very early in the build hierarchy (so gnome-desktop, where our common
docs are, is not appropriate). My proposal is 'gnome-doc-common' or
'gnome-doc-tools'. It needs to start with 'gnome-', since it's an
installable package, so we need to put it in the GNOME "namespace".
Ultimately, we could think about moving gnome-desktop/desktop-docs into
this package as well, but that's for another day.

If nobody can come up with a better name or shoot holes in this
proposal, I will commit stuff to CVS in about 24 hours. Then we can
fine-tune it from there.

Malcolm