[cairo] internal cairo include syntax seems not flexible enough, backward-compatible fix proposal.

[Carl Worth]

On Sat, 2008-09-20 at 07:56 +0000, Fabien Costantini wrote:
> I was willing to include cairo include files using the cairo directory as follow:
>     #include <cairo/cairo.h>
> instead of
>     #include <cairo.h>
> 
> This way,  I don't need to add a specific include directory statement in makefiles like -I /usr/local/include/cairo ,
> provided that cairo is installed in common include directories.

Hi Fabien,

Thanks for raising this issue.

I wasn't aware that Behdad had changed our public header files to
include "cairo-features.h" instead of <cairo-features.h>, (since cairo
1.6) and I'd actually like to discuss that change here on the list
before we ship 1.8 with that change in place.

We've always documented that the way to use cairo is to put:

	#include <cairo.h>
	#include <cairo-[backend].h>

in your application code and then arrange for your compiler to find the
correct directory for those files. One can use pkg-config to help with
this process, but it's not a requirement.

I don't think we did the <cairo-features.h> thing specifically to
*prevent* anyone from putting <cairo/cairo.h> into their application.
But I'm also not sure if we want to encourage that either.

Here are some problems with application code using <cairo/cairo.h>:

1. It's ugly. Worse than being more typing---it's a name with redundant
components in it, and that's just not pleasant.

2. It's different. If some people use <cairo.h> and others use
<cairo/cairo.h> then there's potential confusion. If people share code
casually, (without corresponding build scripts), then the code might not
work from one evironment to the next. Not nice. Users might see the
other form and wonder if they're doing something "wrong". Again, more
confusion and an isse better to just avoid.

3. It breaks our standard build instructions. The documented approach is
to use pkg-config to get the correct build flags. But if pkg-config is
giving you -I/some/prefix/cairo and you use <cairo/cairo.h> then you
won't get the header you want from /some/prefix/cairo, but could
silently get an incorrect one from /usr/include/cairo. That's very bad.

So we definitely want to teach people to just use <cairo.h>. And if we
already have an (accidental) means in place in all previous releases
that enforces this, why should we change it?

Behdad, I'm of a mind to revert the change before 1.8.

Other thoughts?

-Carl