Re: Initial work on a help API

[Shaun McCance <shaunm gnome org>]

On Wed, 2011-05-18 at 11:29 +0200, Rodrigo Moya wrote:
> On Thu, 2011-04-21 at 16:16 -0400, Shaun McCance wrote:
> > Hi all,
> > 
> > I had a project called Squawk I was working on last year.
> > I chatted a bit with Ryan Lortie about it at the recent
> > help hackfest, and decided to work on it again, but this
> > time directly in GLib and GTK+.
> > 
> > The basic idea is that GLib has a help provider API that
> > knows about your application's help. It knows more than
> > just that the help exists. It actually knows about all
> > the topics in your help, their URIs, titles, tags, etc.
> > 
> > Then there's a set of GTK+ widgets that consume this.
> > If you want to make a help button in a dialog, instead
> > of just making a button and attaching a static URI to
> > it, you'd make a help button and give it a tag. Then
> > it's up to help authors to tag topics for that button.
> > 
> > Then do menus the same way. We can kill off the crappy
> > Help->Contents item, and have the Help menu display
> > whatever topics help authors feel are worth promoting
> > to the menu. You can change widget tags at run-time to
> > make them reflect UI state or what the user is doing.
> > 
> I was looking at reducing the number of patches some Ubuntu packages
> carry over, and one of them (in several packages) is about
> launchpad-integration, which adds several items to the Help menu ("Get
> Help online", "Translate this application" and "Report a problem"), so I
> was thinking on writing some GtkHelpMenu widget or something similar
> that does this automatically.
> 
> Would that be helpful for upstream GTK? I guess it could do what the
> launchpad integration thing does (pointing to GNOME bugzilla and
> translations pages, of course, so that Ubuntu would just have to patch
> that to point to Launchpad) plus what your code does.
> 
> So, what do GTK maintainers think about it?

So a GtkHelpMenu is part of what I'm proposing here, though
it's not in the current patch. I've got that code started on
my machine. GtkHelpMenu would use the GHelp API, just like
GtkHelpButton.

My plan for GtkHelpMenu was to have it automatically populated
with entries based on tag, exactly like GtkHelpButton, but also
show statically-added entries (e.g. Help->About). It would have
a search entry at the top. Typing will replace the menu items
with any matching topics in the document.

So what you're asking for is something in between. It's not the
managed topics, because those come from the help file. And it's
not the static items, because those are what you have to deal
with patching right now.

Options:
1) GHelp has a function like g_help_get_static_entries, and you
just patch the help provider (or we even provide a way for our
help provider to load data, and you install some data files).
2) You just patch GTK+ to insert fixed items between the topics
and the statically-added items.

In either case, if you don't want to patch applications, then
this code has to be able to figure out the correct LP URLs, or
if there's even a project in LP for the application. (Think of
third-party, possibly proprietary, applications using the API.)

With some GApplication work, we could get applications to read
something from their .desktop file. Then it could be explicit,
e.g. X-Launchpad-ID=.... You'd still have to patch applications,
but with a one-line patch to a data file instead.

Thoughts?

--
Shaun