Proposal: Replace scrollkeeper

[Don Scorgie <Don Scorgie org>]

Hi,

With the recent release of Rarian (new name for spoon) [1], I'd like to
propose replacing scrollkeeper with it and moving it to the external
dependencies moduleset.

Rarian is now on the "odd - unstable, even - stable" style release
cycle.  Ive just released 0.5.0.  My plan is to put only bug-fixes and
documentation into this branch, resulting in a stable 0.6.0 in good time
for GNOME 2.20.

Finally, you can get the 0.5.0 release from 
http://code.google.com/p/rarian/downloads/list

This might be a bit of a long email as I try and justify this.  The
short version is:

Rarian provides (almost) complete compatibility with scrollkeeper [2].
It works as a drop-in replacement in a fresh jhbuild install and I've
been using it in place of scrollkeeper in my normal install for several
weeks now without issue.

Right now, we're working on a redo of yelp's guts, fixing several
long-standing bugs and trying to prepare for Project Mallard.  This
seemed like a good opportunity to replace scrollkeeper, which causes us
(and packagers, and maintainers) hassle.  This rework now depends on
many new features available in Rarian to generate it's TOC.

Rarian reduces install time of applications that install documentation
and is quicker when run in yelp, getting the pages displayed quicker.

That's the short version.  The next part's the long version.  If I've
already complained to you about scrollkeeper, or you have no
objections / questions / don't really care, you can stop reading now.

For the rest of you...

The current situation:
A package installs an omf file and calls scrollkeeper-update.  This gets
added to the internal "database", which you've probably noticed when
installing something takes a little while.  The omf file describes the
location and contents of the documentation.

Yelp, when generating it's main page (the TOC), calls scrollkeeper
through the command line and receives a filename containing a copy of
the relevant list of omf files back.  We then read and parse this list
and extract the information.  Unfortunately, the index doesn't tell us
anything useful, except the location of the omf files.  We then open,
read and parse each omf in turn to generate all the nice titles and
descriptions.

The new situation with Rarian:
Rarian provides a library which handles parsing all the meta-data files
and returning the title / description.  Done.

Problems with scrollkeeper:
* It's unmaintained
* There are some outstanding bugs in it (we maintain 3 patches and apply
them during jhbuild)
* No facilities for fall-back languages
* Install time registration is a pain
* I'll stop there

Advantages of Rarian:
* Provides a library, instead of going through the command line
* Provides almost complete [2] compatibility with scrollkeeper
* Handles unknown / fallback languages gracefully
* (eventually) no install-time penalty
* It's maintained
* Allows distro language-packs much more easily

And now for the bad news:
* It's currently lacking documentation.  Fate, it seems, is not without
a sense of irony.
* It's largely untested.  I've been running it as a scrollkeeper
replacement however it hasn't been properly tested under different
conditions
* There's still a lot I'd like to do in it (in future branches)

In addition to the newness, Rarian provides a new meta-data format.
This is based on the (currently-being-worked-on) XDG help system spec.
However, for 2.20 I'm strongly advising AGAINST adopting this (as it is
liable to change as yet).  Instead, Rarian can function fine with
scrollkeeper omf files and piggy-backing on the scrollkeeper install
time registration system.

I'll also mention here I've had interest in using it from Ubuntu and
(some, maybe) from KDE.

So there you have it.  Anyone want to volunteer an opinion, question,
flame?
Don

[1]
http://mail.gnome.org/archives/gnome-announce-list/2007-June/msg00066.html
[2] The major missing part is the <sect1> titles from
scrollkeeper-get-extended-cl.  This isn't used though and seems
incompletely done in scrollkeeper.