[cairo] Rethinking cairo's build system

[Damon Chaplin]

On Tue, 2006-07-11 at 13:44 -0400, Behdad Esfahbod wrote:

> Thanks Damon.  Before getting your mail, I went on and hacked cairo's
> gtk-doc.make locally to add a 'doc' target that does about the same.
> Will switch to gtkdocize and your new feature.
> 
> So, you are changing gtk-doc to not build docs by default anymore?  That
> makes many people happy I'm sure.  But looking at your implementation
> versus mine, I've made both dist-hook and install-data-local to depend
> on html-build.stamp, but you only do for dist-hook.  I think someone
> enabling gtk-doc should get updated docs installed.  This has caused a
> minor glitch for cworth though: sudo make install leaves root-owned
> files in the tree.

I don't think gtk-doc built docs by default before. You had to use the
'--enable-gtk-doc' configure flag to build docs.

I just added a simple rule so you could still use 'make docs' to build
the docs even when '--enable-gtk-doc' wasn't used. It isn't perfect as
it doesn't care which version of gtk-doc is installed.

If someone wants to write a better version that supports something like
"--enable-gtk-doc=optional" that would be fine.


> > Why is trailing whitespace a problem?
> 
> Cause we've opted for the git commit hook that fails on committing text
> with trailing whitespace.  That's to help with "improved source
> quality" :-).

That's not a serious problem though. If I changed it now, all the
template files would get updated for little reason. A better solution
would be to skip the tmpl/ files in the git commit hook.


> > > 	2) Different versions of gtk-doc generate different template
> > >            results, (and often in fairly trivial ways, which makes the
> > >            change all the more annoying when they're under version
> > >            control).
> > 
> > Yes, unfortunately 2 minor bugs in the handling of template files turned
> > up recently, and the fixes tried to clean up the old errors, resulting
> > in minor changes.
> > 
> > If people use a recent gtk-doc that would help here (cvs would be best).
> 
> Can you make a release?

OK. I'll try to do one soon.


> > I've converted the existing section documentation to the inline versions
> > and attached it. You just need to place each part in the corresponding
> > file. (Or you could just put them in one .c file.)
> 
> Thanks!  Going to commit it soonish.  However, cworth and I couldn't
> quite figure out how this works, looking at goocanvas.  Does it scan
> source files for inline versions only if no template file is available?
> Cause we converted just one section into inline comments and gtk-doc
> didn't pick it up.

It scans both inline and template files at present.

Make sure you have gtk-doc from cvs. The older code was skipping section
names with "-" in them (e.g. "SECTION:cairo-font"), so most of the cairo
section docs didn't appear.

(I tried adding the section docs I attached last time to cairo.c and it
all worked fine for me.)


> > You can then remove all the tmpl/*.sgml files from version control
> > (so long as there is no other documentation in the tmpl/* files.)
> > But place a special tmpl/dummy.sgml file there to avoid a problem with
> > make and globs.
> > 
> > But you'll need gtk-doc from cvs to build the docs, as I just fixed
> > another bug with inline section docs.
> 
> Ok, then we really need a release before going on and do that, or, is
> the bug minor enough to ignore?

The section docs don't appear. That's all.

Damon