pecl-gen'd cairo wrapper - how to name, where to put ...

ROLLBACK TRANSACTION; BEGIN TRANSACTION;

* why PECL?

  Originally i didn't consider releasing anything at all
  but simply considered it as one of my real-life tests
  for pecl-gen. There was no plan to do a full wrapper.

  Things only changed in August this year while visiting
  a user group meeting in another town. I don't remember
  how the topic came up but when i mentioned tht "i've
  started something like this a while ago" people went
  like "oh, yes? let me see! we've *so* been waiting for
  this ...".

  So i took the extra mile to wrap up the remaining 90%
  of the cairo api during my spare time the following
  two weeks, also fixing a lot of small pecl-gen issues
  and adding some minor missing features on the way,
  finally setting up

    http://cairo-wrapper.php-baustelle.de/

  as its project site and publishing it on the "php-baustelle"
  channel.

  But then requests like "why don't yo move this to PECL?",
  "*when* will you move this to PECL?", "we would like to
  integrate support for this into ... but can't unless it
  is in PECL".

  I finally gave in on this during the Frankfurt conference,
  and the feedback i got on my own PECL inclusion questions
  was more or less "go aheat, just commit, why bother?" ...
  yes i should have known better ...

  Anyway, i myself don't care much about this being in PECL
  or not, it's others that do and from now on i'd like to
  ask these to speak up for themselves on this.

* how to name the beast?

  To be honest, i'm not happy with the 'cairo' name either,
  i picked the original name 'cairo_wrapper' to reflect that
  it is exactly that: an almost 1:1 wrapper around the cairo
  C API whereever possible.

  One of the reasons for this was obviously ease of wrapping.
  Another one was that once the actual functionality is there
  it is way easier to try out different ideas on how to create
  a more PHPish interface in user land code first before rolling
  the interfaces into an actual extension.

  The only reason *for* naming it 'cairo' was that all the
  functions are prefixed with "cairo_..." as the names are 1:1
  mappings of the C API, too.

  With function names already as long as

    cairo_ps_surface_dsc_begin_page_setup()

  or

    cairo_svg_surface_restrict_to_version()

  i was not looking forward to make these even longer by changing
  the prefix to "cairo_wrapper_". Although now thinking of it
  "cairo_api_" might work out as a compromise?

* where to maintain the source?

  I've put the generated code into PECL CVS but thingking about it
  again this might not make that much sense. All this is generated
  out of a single XML spec file and any changes to the actual code
  and project files would either have to be rolled back into the
  spec file or the generator code, else it would fork away from
  the generator stuff which doesn't seem like a good idea as of now.

  The XML spec file (soon to be converted into a master XML file
  that includes smaller XML chunks to make the beast more maintainable)
  is in a subversion repository on php-baustelle.de, mirroring it
  to PECL CVS might not be that clever (double effort, danger of
  divergent changes) so maybe just having the release packages
  available on PECL might be a better idea here?

* how to handle the documentation?

  This is a more general question that might not only affect this
  extension: where to put/maintain PECL extension documentation?

  The current pecl-gen approach is: bundle the docbook source with
  the extension, but in a way that the files can easily be copied
  over to the php manual source tree if needed. It doesn't cover
  translations yet though.

  What it *does* cover is creating a standalone HTML or PDF manual
  using the "docbook tools" package. For now it requires that you
  set the PHPDOC environment variable to your local copy of the
  phpdoc repository, in an ideal world this should be a "configure"
  job.

  + source and docs are bundled in one place
  + documentation material covering just this extension can
    easily be created

  - current karma system would prevent doc guys and translators
    to access the docbook stuff

/* running out of power now, don't expect me to comment on any
   replies for a while, maybe not even before monday ... */

COMMIT TRANSACTION;

--
Hartmut Holzgraefe, Senior Support Engineer                            .
MySQL AB, www.mysql.com