Re: Feedback about Yelp

[Shaun McCance <shaunm gnome org>]

Hi Luis,

Thanks for your feedback.

On Sun, 2009-11-15 at 13:37 -0500, Luis Felipe López Acevedo wrote:
> Hello all.
> 
> I'm using GNOME 2.22.1 on gNewSense 2.3 and I'd like to give some
> feedback about Yelp.
> 
> 1. I don't like that when you search for something you get results from
> all help documents in the help system. I'd prefer to get results from
> the document or manual I'm reading. For example, if I'm reading Ekiga's
> manual I'd like to get results related to Ekiga only and not Gedit. In
> my opinion, the current behavior would be good as an option, not as the
> only way to search.

Searching within the current document will be the default
behavior in Yelp 3.0.

> 2. I don't like that the style of the documents depends on the colors of
> the desktop theme. With dark themes, the documentation looks really bad.

The style has to depend on the current theme.  People who
use dark themes for accessibility reasons may find it very
difficult to read white-on-black.  The problem is that the
colors got screwed up somewhere in the last few releases.
I'll be working on generating colors that are suitable for
all themes for 3.0.

> 3. I'd like the content and the contents bar to the right to have
> independent scrolling. The reason for this is that when you write a
> DocBook document that uses images with widths different to the
> recommended in GNOME-STYLE[1], and these images are at the same level of
> the navigation bar to the right, this bar will overlap the image.

I'm thinking of moving the contents back into a separate
sidebar for 3.0.  That's how it used to be, but we changed
it to try to de-emphasize the linear structure and make it
feel more topic-oriented.

We're now doing topic-oriented help in Mallard, leaving
DocBook for documents which really are linear books and
articles.  So I don't see much point in treating DocBook
as something it's not anymore.

> I'd also like to ask if the start page that you see when you open Yelp
> is writen in DocBook and where can I find it. I was trying to use the
> "set" element in DocBook hoping to get something similar but didn't get
> what I wanted.

The start page is currently generated inside Yelp.  It
scans your system for all installed documentation and
generated a set of TOC pages.

In 3.0, the start page will be the index page of the
Desktop Help, which will replace the User Guide.  This
will be a Mallard document, and downstream distributors
will be able to plug into it in the same ways they can
plug into other Mallard documents.

If you're interested in what we're doing or would like
to help out, you could join us on IRC.  We're on the
#docs channel on irc.gnome.org.  There's instructions
here:

http://live.gnome.org/DocumentationProject/Contact

Thanks,
Shaun