Making sure an applet finds its help file

[Pierre Sarrazin <sarrazip sympatico ca>]

This is not a question, but a small report on a problem I had and
which I fixed.  Maybe this can be useful to others, and perhaps
the GNOME applet developer documentation could be augmented.

I am developing a GNOME 2 applet and my call to gnome_help_display()
failed:

    GError *error = NULL;
    if (!gnome_help_display(PACKAGE, NULL, &error))
	...

The PACKAGE macro is "myapplet".  The installation prefix is
/home/ps/ROOT/usr.  There is a myapplet.html file installed in
/home/ps/ROOT/usr/share/gnome/help/myapplet/C.  The LC_ALL
environment variable is defined to en_US.

I use these compilation flags, as seems to be recommended:

	-DPREFIX=\""$(prefix)"\" \
        -DSYSCONFDIR=\""$(sysconfdir)"\" \
        -DDATADIR=\""$(datadir)"\" \
        -DLIBDIR=\""$(libdir)"\"

In a GNOME _application_, one would call gnome_program_init()
like this:

    gnome_program_init(PACKAGE, VERSION, LIBGNOMEUI_MODULE, argc, argv,
                            GNOME_PROGRAM_STANDARD_PROPERTIES, NULL);

GNOME_PROGRAM_STANDARD_PROPERTIES is a macro that refers to the four
preceding macros.  That is how an application informs GNOME of the
directories where the help files are stored.  It is not clear to
me how an _applet_, however, tells GNOME about these directories.

I used strace to see where GNOME tried to find the help file.
Searching for 'gnome/help' in the traces gives this (lines shortened
for readability):

stat64("/home/ps/ROOT/usr/share/gnome/help/GNOME_myapplet/", 0xbfffcf60)
	= -1 ENOENT
stat64("/usr/share/gnome/help/", {st_mode=S_IFDIR|S_ISGID|0755,
access("/usr/share/gnome/help/en_US/myapplet.html.xml", F_OK) = -1 ENOENT
access("/usr/share/gnome/help/en_US/myapplet.html.docbook", F_OK) = -1 ENOENT
access("/usr/share/gnome/help/en_US/myapplet.html.sgml", F_OK) = -1 ENOENT
access("/usr/share/gnome/help/en_US/myapplet.html.html", F_OK) = -1 ENOENT
access("/usr/share/gnome/help/en_US/myapplet.html", F_OK) = -1 ENOENT
access("/usr/share/gnome/help/en/myapplet.html.xml", F_OK) = -1 ENOENT
access("/usr/share/gnome/help/en/myapplet.html.docbook", F_OK) = -1 ENOENT
access("/usr/share/gnome/help/en/myapplet.html.sgml", F_OK) = -1 ENOENT
access("/usr/share/gnome/help/en/myapplet.html.html", F_OK) = -1 ENOENT
access("/usr/share/gnome/help/en/myapplet.html", F_OK) = -1 ENOENT
access("/usr/share/gnome/help/C/myapplet.html.xml", F_OK) = -1 ENOENT
access("/usr/share/gnome/help/C/myapplet.html.docbook", F_OK) = -1 ENOENT
access("/usr/share/gnome/help/C/myapplet.html.sgml", F_OK) = -1 ENOENT
access("/usr/share/gnome/help/C/myapplet.html.html", F_OK) = -1 ENOENT
access("/usr/share/gnome/help/C/myapplet.html", F_OK) = -1 ENOENT

GNOME first attempted to go into a subdirectory called GNOME_myapplet,
which does not exist.  But if GNOME had instead attempted to open the
myapplet subdirectory of /home/ps/ROOT/usr/share/gnome/help instead,
it would have succeeded -- I proved this using a symbolic link.

I found that the "GNOME_" prefix came from the way I initialized
my applet:

PANEL_APPLET_BONOBO_FACTORY("OAFIID:GNOME_myapplet_Factory",
                             PANEL_TYPE_APPLET,
                             "GNOME_myapplet",
                             "0",
                             myapplet_fill,
                             NULL);

I simply replaced the "GNOME_myapplet" argument with the PACKAGE
macro, which is "myapplet", and then gnome_help_display() worked.
I had feared that this might break something else, but it did not.
(I don't remember why I put that "GNOME_" prefix there in the
first place -- I suppose it came from some examples I used when I
first learned to create a GNOME applet.  Since the applet developer
documentation was somewhat incomplete, I had to hack a bit.)

-- 
Pierre Sarrazin <sarrazip at sympatico dot ca>