Re: yelp patches

[Brent Smith <gnome nextreality net>]

Christopher James Lahey wrote:
> I've been working on adding some features to yelp and wish to work on
> getting them upstreamed.
>
> Included are 4 yelp patches.
>
> The first, yelp-helpuri.patch, enables yelp to recognize help: uris as
> used by KDE.  It will also find things in some gnome directories (with
> the same behavior as the patch I added to khelpcenter for SuSE a while
> back.)  I've written up a standard, but it needs some discussion.  This
> could go in as is to match with KDE.

This seems like a good idea, but how does it compare to the current
ghelp uri?

> The second, yelp-libmenu.patch, causes yelp to use the menu system to
> generate its table of contents instead of using scrollkeeper.  This will
> allow us to get rid of the installtime hit from scrollkeeper as well as
> make the help menu match the Applications menu.  This is just reading
> from a .menu file, so we can have a help.menu file that includes
> applications.menu so we can include stuff not in the menus.

Right now I get two categories, Office and Sound & Video.  Office shows
acroread and Sound & Video shows k3b and totem.  Search doesn't work
and neither does the expand all categories at the top right.  Looks like
the patch still needs some work :-/

We have a way to currently match the categories in the menus, albeit it
isn't nearly as automated as what your patch achieves.  The
data/scrollkeeper.xml file maps scrollkeeper categories to different
categories which actually show up in the yelp TOC.  If we wanted to
match the TOC in yelp with the menus, this file could be modified (as
well as toc.xml).  Of course, this would require a little bit of hand
editting and translations to be performed.

> The third, yelp-printing.patch, adds printing support to yelp.  It will
> print either the page or the whole document.

I think this should definitely go in.  I don't have a printer so I'm
unable to test, but the dialog came up for me ;-)  This has been a
longstanding complaint against yelp.

> The fourth, yelp-toctree.patch, displays the table of contents as a tree
> on a single page instead of across multiple pages.

This is a cool idea.  The expansion works and shows the description for
each item, but like I said above there are only two categories and
entries for only totem, k3b, and Adobe Reader.

> Enjoy,
>    Chris

Thanks for hacking on yelp.  Maybe all Shaun's complaining on IRC helps.

I have been working on the man parser in my spare time.  The goal is to
be able to turn man page support on sometime in the near future ;-)

Also, I have a proof of concept patch for searching titles and keywords
in docbook files.  The patch is very hackish and in no way complete, but
if you are interested in taking a look let me know, and I can send you
the patch.  It does work, but it is slow and doesn't do full text search
(yet).

The other thing that I have been trying to do, although a bit
unsuccessfully, is to fix all the titles for the documentation in
scrollkeeper.  Basically this involves changing the bookinfo/title
element in the docbook file.  Updates to the abstract element in
the documentation are encouraged as well, as this currently shows
up below the doc title in the current TOC in yelp.
Details on the effort are here:

http://live.gnome.org/Yelp/ConsistentDocs

Patches have been applied for gnome-panel, but not much else yet.
It would probably help if someone on p.g.o. blogged about the effort
so we can get everyone to fix the documentation at the same time.
Although if we are going to generate the TOC from the menu, this
will become irrevelant.

--
Brent Smith <gnome nextreality net>
IRC: smitten (#docs)