[Xapian-discuss] Perl XS bindings, postlist_begin

[James Aylett]

On Tue, Jun 01, 2004 at 07:17:33PM +0100, Olly Betts wrote:

> > Also, I haven't delved into the use of set_error_handler in PHP 4.
> > There are no exceptions yet, so errors which aren't return codes are
> > awkward to handle.
> 
> We've discussed this before, and longer term we'll probably move to an
> error code strategy for the library, with in-lined wrappers which
> convert these to exceptions for developers who prefer an exception
> error model.  You could think of this as offering C++-with-exceptions
> bindings to a C++-without-exceptions library.

We should think about when to do this. I can support direct exceptions
properly in Python, but it's a pain because I'll have to directly call
internal creation mechanisms in the bindings, which is why I haven't
done it yet. Checking return codes would allow me to define my own
exception hierarchy in Python (which would have the added bonus of
inheriting from the right thing).

OTOH, you can get by in most languages, so we can survive (with an
appropriate policy in PHP) for a while.
 
> > Just had a thought... One way to improve documentation without much
> > effort would be to have user comments on the online docs, like the PHP
> > and MySQL websites.  If each Xapian function was separately
> > commentable website, then people using it would add explanations and
> > suggestions.
> 
> But the downside is that the comments often seem to be confused, just
> plain wrong, or questions (usually without corresponding answers).  I've
> rarely found the comments on the PHP docs useful, for example.

Ditto mysql. The problem is that you need someone to act as editor for
any contributed commentary, or it gets out of date - and inaccurate,
as (forgive the bluntness) stupid people have a habit of trampling
their misunderstandings into a system that others are trying to rely
on for solid documentation. Bits of the PHP docs are useless because
of this.

Of course, we don't have any stupid people using Xapian at the moment,
so maybe we'll be more fortunate than other projects :-)
 
> Perhaps we should just put up a wiki, preloaded with the documentation,
> and see how it develops.  Can anyone suggest a suitable wiki?  One with
> good support for change management would be good I guess...

I use MoinMoin, and love it. The latest version has very nice
arbitrary diff support (most wikis don't seem to have this, and it's
critical).

You can do clever things with authentication, so we can have
superusers with special permissions (and lock certain pages to them,
for instance).

The latest versions of pages are stored as text, so we can write
additional tools on top of it easily enough, as well. I can find some
time to update the MoinMoin install on ixion, and probably set up a
Wiki fairly quickly.

The structure should probably mirror the classes and namespaces, so we
have:

Xapian/WritableDatabase/add_document

and so on. (MoinMoin supports hierarchies of pages, with automatic
linking back up a level.)

J

-- 
/--------------------------------------------------------------------------\
  James Aylett                                                  xapian.org
  james@tartarus.org                               uncertaintydivision.org