[cairo] Rethinking cairo's build system

[Damon Chaplin]

On Sat, 2006-06-24 at 19:53 +0200, Carl Worth wrote:
> On Sat, 24 Jun 2006 18:43:16 +0100, Damon Chaplin wrote:
> > > 
> > > 4) Building the docs takes too long, (or perhaps it just needs to be
> > >    moved to "make doc" instead of "make)
> > 
> > Or you can use './configure --disable-gtk-doc' to skip building the
> > documentation.
> 
> But configure is slow, so I wouldn't want to have to go through it
> again (twice!) just to be able to build the docs and then turn them
> off again. So a separate make target is definitely what I want here.

OK. I've added a separate 'docs' target you can use in the documentation
directory, even if '--disable-gtk-doc' has been used.


> > > 6) Building the docs modifies (!) a bunch of files under version
> > >    control. This is worse than annoying.
> > 
> > It updates the template files, but should only do that if needed.
> > Is it updating anything else under version control?
> 
> It's just template files that I've seen. But there a couple problems
> here:
> 
> 	1) It generates output with trailing whitespace

Why is trailing whitespace a problem?


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

It also helps if people only commit docs if they have worked on them.


> > It is now possible to write all the gtk-doc documentation in the source
> > code, and not place the template files under version control. That might
> > help you a bit. (goocanvas does that.) If you want help with that, let
> > me know. (You just need to add an empty tmpl/dummy.sgml file to avoid
> > issues with make.)
> 
> That sounds like the perfect thing. And I would love help with that.

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

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.

Damon

-------------- next part --------------
A non-text attachment was scrubbed...
Name: cairo-docs.c
Type: text/x-csrc
Size: 9304 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20060630/afffb8f9/cairo-docs-0001.c