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

[Behdad Esfahbod]

Carl Worth wrote:
> We've always documented that the way to use cairo is to put:
> 
> 	#include <cairo.h>
> 	#include <cairo-[backend].h>

Sure, and we'd continue doing so.

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

Agreed.

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

Agreed.  I don't see that relevant to the discussion though.  No one is
encouraging that syntax.

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

We don't have that (accidental) means anymore.  So why change it?

If we decide to back the change out, there are other issues we have to
address.  For example, cairo build internally relies on the "" syntax.  All
source code in src/ except for cairo-version.c is tricked to include
src/cairo-version.h while the actual version file is the toplevel
cairo-version.h.  The benefit of this is that changing the cairo version
number does not force a full rebuild of the library, just the needed part
(cairo-version.c).

Now if cairo.h did #include <cairo-version.h> the above behavior would rely on
the -I orders, where as using the #include "cairo-version.h" syntax it's more
robust and more clear.  I honestly think the "" syntax is more appropriate
when one really means "include my sibling file".

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

I'm not a fan, and I don't see a reason really.

behdad

> Other thoughts?
> 
> -Carl
>