[Xapian-discuss] Perl XS bindings, postlist_begin

[Olly Betts]

On Wed, Jun 02, 2004 at 10:33:06AM +0100, James Aylett wrote:
> On Tue, Jun 01, 2004 at 07:17:33PM +0100, Olly Betts wrote:
> 
> > 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.

It's probably not a huge amount of work.  But it's very wide ranging and
quite invasive - I'd imagine almost it would touch the majority of files.

At present I've a number of unchecked in patches (mostly quartz
reworking in progress), so this isn't a good time to be changing lots
from my point of view.

So perhaps for 0.9?

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

Even if the comments are all useful, the "comments on docs" style will
inherently lack coherency compared to being able to add content to the
page itself.

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

I was looking at MoinMoin earlier, as someone else suggested it to me.

The diff support looks ideal for how I envision this working, which is
that a (human) editor would periodically sweep through the wiki and fold
most additions into the base documents.  Then we probably reset the wiki
to new base documents (or perhaps the editor just cleans up any problems
and then copies the wiki to the base docs).

The base documents being what goes in the release tarball (so the editor
would try to do this shortly before a release, and perhaps at other
times to avoid a huge pile of changes building up).

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

That'd be cool (and mailman - nudge).

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

And it shouldn't be hard to seed those from the doxygen docs.

Cheers,
    Olly