Help system (was Re: Undelivered Mail Returned to Sender)

[Malcolm Tredinnick <malcolm commsecure com au>]

This seems like a very nice proposal. Nice and meaty on the details.
Which raises two questions in my mind...

On Fri, Aug 31, 2001 at 08:40:49PM -0400, Jonathan Blandford wrote:
[...]
> There are 3 proposed API calls for libgnome:
> 
> gboolean gnome_help_display         (GnomeProgram  *program,
>                                      char          *doc_name,
>                                      char          *link_id,
>                                      GError       **error);
> gboolean gnome_help_display_desktop (GnomeProgram  *program,
>                                      char          *doc_name,
>                                      char          *link_id,
>                                      GError       **error);
> gboolean gnome_help_display_uri     (char          *help_uri,
>                                      GError       **error);
> 
> The first two calls basically construct the appropriate URI, and then
> call gnome_help_display_uri [3].  The difference between the first two
> calls is that the first is used to display the help for the user
> documentation, while the second is intended to show installed help that
> comes with GNOME (such as the glossary).  One assumption made here is
> that this desktop documentation is installed with the same prefix as the
> gnome libraries and help-browser.

Question 1:
-----------
Could gnome_help_display_desktop first checked an environment variable
(say GNOME_DOCS) for the location of the docs and then default to the
main prefix? My thinking here is that this would make it easier to
develop new versions of the system documentation without having to
reinstall various major packages (would could lead to all sorts of
exciting breakages).

I'm not sure if this is a necessary idea for gnome_help_display or not.
If it existed, you would check the env variable first and then the
DATADIR. But rebuilding a single package into a different directory and
running it from there is not as painful as rebuilding gnome-core or
libgnome*, for example.

Question 2:
-----------
Seeing the word 'glossary' twigged my memory: does anybody have any
creative ideas on how to handle a glossary section in a flexible
fashion? We have a glossary of common GNOME terms. Different
applications may also want a glossary of terms specific to their domain.
It is not feasible to put all these terms in the main glossary (it would
become enormous and everytime a package was released, the main glossary
would need to be updated or would stagnat).

Currently, there needs to be two glossaries available from an
application's help pages because of this situation. Is there any clever
way to treat glossaries specially and somehow merge them? I've been
thinking about this on and off and my brain is too limited to come up
with something that isn't really awkward. Am I wanting too much
uniformity (most likely)?

Cheers,
Malcolm

-- 
Why be difficult when, with a little bit of effort, you could be impossible.