More work on GHelp API

[Shaun McCance <shaunm gnome org>]

Hi all,

I posted about the GHelp API I'm working on back in April:

http://mail.gnome.org/archives/gtk-devel-list/2011-April/msg00141.html

I started working on this again. I've got all my work on gitorious,
so I don't have to pass tons of patches around.

https://gitorious.org/ghelp

To test this out:

* Build and install the ghelp branch of my glib repository.
* Build and install the master branch of my gnomehelp repository.
* Copy the .page files in gnomehelp/gnome-help into
  ~/.local/share/gnome/help/gnome-help/C/
* Build the ghelp branch of my gtk repository.

In the gtk repository, run tests/testhelpbutton like so:

./tests/testhelpbutton ghelp:gnome-help

Put any valid tag name the text entry and watch what the button
and menu do. Try "mouse" or "a11y" as tags, or "index" as a tag
that only has one page. Or grep for '<tag' in the page files.

I'd like input on this API:

https://gitorious.org/ghelp/glib/blobs/ghelp/gio/ghelp.h
https://gitorious.org/ghelp/glib/blobs/ghelp/gio/ghelpactiongroup.h

Right now, GHelp is an interface with methods the query the source.
These return GHelpActionGroup instances. These are GActionGroups,
but they also have a title associated with each action.

I have three different ideas on how the API could be different:

1) Leave everything as it is, but make GHelp be a GHelpActionGroup.
That would provide a way to ask for all pages/actions.

2) Remove GHelpActionGroup and make GHelp be a derived interface
of GActionGroup. The query functions would return GHelp instances.
You'd then be able to chain an indefinite number of list_for_tags
and search calls. While powerful, I don't know that it's needed,
and it adds complexity to implementations.

3) Remove GHelpActionGroup and make GHelp be a derived interface
of GActionGroup, but make list_for_tags and search just return
gchar**. That is, the GHelp object is the only GActionGroup you
use, and the select functions just return a filtered list of the
possible actions. I'm liking this idea.

Also, I realize that the search entry in the menu is pretty crappy
at the moment. It sort of works, but it does a lot wrong. This is
not something GtkMenu was designed for, and it will take a log of
work to get it right. It could be punted, though. The tag-based
help querying alone is still cool.

Comments?

--
Shaun