(Resend) What's wrong with scrollkeeper

[Don Scorgie <DonScorgie Blueyonder co uk>]

Resend.  Might get there this time.  Just wanted to add my reasons for
hating scrollkeeper.

On Sun, 2006-07-09 at 17:03 -0500, Shaun McCance wrote: 
> On Sun, 2006-07-09 at 13:09 -0600, Chris Lyttle wrote:
> > Don Scorgie wrote:
> > > 4. Kill scrollkeeper using a blunt knife
> > >   
> > Ohhh, I think we need a lynching mob to kill scrollkeeper, a blunt
knife 
> > is too easy
> 
> Just to make sure I get everything right,
> here's an open question to everybody:
> 
> What's wrong with ScrollKeeper?
> 
> I can list probably a dozen things.  But
> I want everybody else's concerns.  I need
> to know the failures of the past to make
> sure we don't repeat them in the future.

As others have said.  

Plus: 

* The fact that in yelp, we have to access it through a command line
process.  It's dumb.  Make it a library and we can interact with it at
least.

* It dumps its output to a tmp file in /tmp which is never cleaned up
and (due to the brain-dead naming) can be attacked.  Don't know if
anyone would ever want to attack yelp, but its there as a possibility.
(/tmp/scrollkeeper-$USER/contents.{0,1,2,3,4} are not good names for tmp
files)

* The language thing.  It's been said before, but really.  This is the
biggest problem.  Any doc management system should be able to handle
docs in any language, whether it knows anything about the language at
compile time or not.  It should not fail silently when (failing to) add
a doc to its index at the very least.  It should be kicking and
screaming.

* There are hundreds of places in the code where possible off-by-one
errors happen.  Ubuntu has at least 3 patches to fix these errors and
compiling scrollkeeper from scratch (unpatched) on Ubuntu will seg fault
scrollkeeper when run, resulting in empty TOC's in Yelp.  At least for
me.

* The default install pretty much ignores $PREFIX for where to look for
it's index.  It really, really wants to look in /usr, no matter if its
installed in /home, /opt or anywhere else.  The default configuration is
to look for the index in /usr.  Really, really annoying when you build
jhbuild and discover no updated documentation because you forgot to edit
1 config file.

* 'I/O warning : failed to load external entity
"/var/lib/scrollkeeper/en_US/scrollkeeper_cl.xml"'.  Every time.
Despite this, it manages to produce a doc list.  If it doesn't affect
the thing I'm currently doing, don't tell me on screen.  I didn't ask
for a en_US list.  If you must, put it into a log-file somewhere.
Ironically, when adding a doc in an unsupported language (see above),
when I would really want an error, nothing appears!

* The content list returned is pretty much useless.  What do we drag out
of it?  A list of omf files, which then must be gone through to get any
relevant information.

* The content list contains a bundle of useless empty categories.
content-list != every category scrollkeeper has ever heard of.  It
should only return categories with something in them.  Or better yet,
only a list of docs with a tag inside their structure stating which
category they belong to.

*Using .omf, there is no way to prioritise docs in the list.  Ask
Joachim.  The user guides etc.: GNOME Desktop User Guide should be at
the top, then  Accessibility Guide then Sys admin guide.  To do this,
the title of the User Guide was changed to "Desktop User Guide" and the
other two kept a "GNOME" at the front.  Ubuntu put a special hack in to
prioritise they're docs on the front page.

* Development seems to have died.  Means no new features are expected.
No bug fixes are likely to happen.

Aaarrrghh.  Sorry.  Just a lot of built up frustration from dealing with
scrollkeeper.  At least 9 there, combined with what others said, I count
at least 14 things.  Hope your happy ;)

Anyway, that's enough venting for now.
Don