Re: Minutes of Gnome 2 release team meeting (late): 2002-05-17

[Federico Mena Quintero <federico ximian com>]

On Fri, 2002-05-24 at 12:00, hobbit aloss ukuu org uk wrote:
>     * Help system
> 
>     Currently help works beautifully on some systems but on others
>     when you hit 'help', there is a long wait for the machine to 
>     find the right stylesheets because if it can't find them locally, 
>     it looks for them on the net. We need to get the right stylesheets 
>     onto people's boxes, It would be nice if all the distros did the
>     same thing and shipped the same versions of ones, but they don't. 
>     There are lots of caveats here: we do not want to mess up catalogues, 
>     we do not want to end up with unnecessary duplication, and we want 
>     to keep it all as described by various standards. Sander and Jody 
>     will try to track down the precise list of stylesheets and look at 
>     whether we need to ship it.

The basic problem is that Yelp tries to be too smart, but is rather dumb
at the same time.  Yes, the right thing to do is to fetch the
stylesheets from the net if you don't have them --- that's what the
document header's URL is for.  However, it should really tell you about
what it is going to do.

If Yelp can't find the DTD and/or stylesheets, it should pop up a dialog
telling you something like

	You do not have the DocBook/XML 4.1.2 DTD in /etc/xml/blahblah.
	The GNOME help browser can download the required information
	from the network to let you view FooApp's help.  However, the
	better solution is to get your system administrator to install
	the DTD for the whole system.  What would you like to do?

	[Cancel]    [Download]

If you hit Download, it would download the DTD (with a progress bar!)
and install it somewhere on your $HOME, and remember that it is there
for future access.

As a separate issue, here are some things that I've noted when fixing
some help-related bugs:

- Some apps don't pass the correct app_id to gnome_program_init().  This
has to be the same as the name of the directory where they install
help.  E.g. if they pass "foo" as their app_id, it means their help is
installed in $(datadir)/gnome/help/foo/[lang]/.

- Some apps are not passing GNOME_PROGRAM_APP_DATADIR and their DATADIR
correctly to gnome_program_init().  The easiest thing for apps to do is
to simply pass in GNOME_PROGRAM_STANDARD_PROPERTIES and put the
appropriate -D items in their Makefile.am.

- Many apps downright ignore the return value of gnome_help_display(). 
They should pay attention to it and display an error dialog with the
GError's message.  This is as simple as

	GError *error;

	error = NULL;
	gnome_help_display ("foo", NULL, &error);

	if (error) {
		GtkWidget *dialog;

		dialog = gtk_message_dialog_new (GTK_WINDOW (window),
						 0,
						 GTK_MESSAGE_ERROR,
						 GTK_BUTTONS_CLOSE,
						 _("Could not display help for FooApp.\n"
						   "%s"),
						 error->message);

		g_signal_connect_swapped (dialog, "response",
					  G_CALLBACK (gtk_widget_destroy),
					  dialog);
		gtk_widget_show (dialog);

		g_error_free (error);
	}

  Federico