Re: Yelp Help

[Shaun McCance <shaunm gnome org>]

On Tue, 2003-09-23 at 19:19, Rob Adams wrote:
> The gnome help system needs some serious loving.  It is absurd how long
> it takes to load even simple help documents in a Yelp window, especially
> considering the end result is simply a very basic-looking HTML document.

Agreed.

> Something as simple as the help document for the calculator takes
> several seconds to load, even discounting the extremely long time it
> takes the Yelp window to even appear.
> 
> Complex documents like the gnumeric yelp seem never to appear.  The CPU
> will churn forever, as far as I can tell.  I've never actually had the
> patience to wait for the document to load.  Presumably it's measured in
> tens of minutes.

On my machine, it takes about a minute.  But I have a fast machine. 
Your mileage may vary.  I did encourage the Gnumeric folks to ship
pregenerated HTML when it was apparent I couldn't get transformations
fast enough for 2.4.

> This requires some attention.  I see a couple of open bugs for yelp
> about speed-related issues, but nothing to address the core issues of
> why the heck is it so slow and what in the world is it doing?

This is getting attention.  Lots of it.  I work on this stuff every
single day.

> Apparently, yelp spends all this time doing XSLT transformations.  Why
> can these not be simply precompiled?  This would also allow us to also
> use fancier stylesheets.  In cases where this is not possible, yelp
> should be able to at least cache the documents resulting from the
> transformation.

What do you mean by "fancier stylesheets"?  Do you mean stylesheets that
produce output with more colors and lots of graphics?  First, that sort
of thing would hardly slow the transformation down, so it's not even an
issue with regards to speed.  Second, why do you want that stuff?  The
help documents should be simple and readable.  Using big colorful boxes
just distracts they eye and makes the document difficult to read.  It
also raises all sorts of accessibility concerns.

I am completely against having applications ship pretransformed HTML. 
If there's a bug in the transformation, you would have to upgrade each
program to get it fixed, rather than just upgrading Yelp.  Having the
DocBook around means that Yelp can generate things like indexes and
document outlines dynamically, allowing a sophisticated search system
and recommendations for related topics.  Having the DocBook around means
that Yelp could produce high-quality print renderings.

Let's move forward with 2.6, not backward.

> If for some reason none of this is possible, we need to rethink the way
> the help system works.  Because currently it is decidedly unhelpful.

Yes, "we" have been rethinking the way the help system works.  Where by
"we", I mean "I".  I've made posts to mailing lists before soliciting
people's ideas.  The posts mostly get no responses.  My impression is
that almost nobody is interested in actually working on a help viewer. 
It's just not a cool project.

If you've got ideas on how to do things, please contribute.

--
Shaun