Re: Yelp

[Shaun McCance <shaunm gnome org>]

On Mon, 2003-12-22 at 10:28, Laszlo Kovacs wrote:
> Hi Shaun,
> 
> After a long break away from gnome-doc-list I have spent some time 
> recently to see how online help is at the moment in Gnome. I have read 
> all your emails on gnome-doc-list in the last 12 months and the Shared 
> Documentation System thread on freedesktop.org.
> 
> Some of the docs guys here in Sun talked to me about some missing 
> features in Yelp and I wanted to find out which parts are you focusing 
> on at the moment and where/how could we join in to help.
> 
> A number of issues mentioned where the docs guys think Yelp could use 
> some work are:
> 
> - index keyword search: I know Scrollkeeper inside out so I know that it 
> supports index search if index markup is provided in the docs and I also 
> know that Yelp has support for this, but the 2.4.0 version I am using 
> does not display any index present in the docs
> 
> - search in documents: this is not supported at all, some kind of text 
> indexing facility that indexes all docs and provides search though Yelp 
> would be great

Searching is the killer feature that we're all waiting for.  There's a
lot of work that needs to be done to make it work well, and I've only
just begun working on it.

> - printing: it would be nice to be able to print docs viewed in Yelp

Yes, agreed.  So what I really want is a high-quality rendering of the
DocBook source, rather than just printing the HTML.  Proper rendering
for the screen is wholly different from proper rendering for the page. 
We can get much more beautiful prints if we start from DocBook and just
bypass HTML altogether.

That, again, is a fairly good amount of work.  What would really help is
a library to turn XSL-FO into PS/PDF.  The only decent one I know of is
FOP, but it's Java.

> - UI: it has been mentioned that the UI could use a facelift, it is not 
> very obvious for me what this means, but we could work on identifying 
> issues if it comes to it

I want to move away from a browser interface.  Currently, we have Back,
Forward, Previous, and Next.  This sort of thing happens all the time in
browsers like this, and it really confuses people.  I'd like to rethink
the Back/Forward thing and focus more on Yelp as a structured viewer for
structured documents, rather than a document browser.

> - tips: this could be part of Yelp or completely independent, it would 
> be useful to have the Tips window that a lot of other desktops have

If you mean context-sensitive help, like at the widget level, then this
is going to require some support in the toolkit.  I have some ideas on
this, but it's not really on the front burners right now.

> - bookmarks: would be nice to be able to store bookmarks to pages

I agree.  This isnt' all that hard, really.  I just didn't get a chance
to do it for 2.6.  There's been discussion of desktop-wide bookmarks,
and I'd want to do that if we get such a system.  But even without that,
it wouldn't be too much effort to work them directly into Yelp.

> What are your plans in these areas?
> 
> I know that the Shared Documentation System thread on freedesktop.org is 
> about making everybody's life simpler by getting rid of middlewares like 
> Scrollkeeper. Scrollkeeper provides some functionality that people will 
> need as build tools if Scrollkeeper is not present (like index and TOC 
> extraction from docs). It would be good to know how and when you plan to 
> move away from Scrollkeeper.

I don't know when.  I've been trying to write up a draft proposal, but I
keep getting sidetracked trying to fix Yelp bugs.  Hopefully I'll get a
chance to work on it and post it later this week.  Then it's a matter of
having discussions and hammering things out.  There's really no telling
how long that will take.  I'd love to have it in place for 2.8.

--
Shaun