Re: gtk_show_help and gtk_show_url

[Shaun McCance <shaunm gnome org>]

On Thu, 2007-10-25 at 17:36 -0700, Matthew Paul Thomas wrote:
> Sorry to come in here wildly late, but ...
> 
> On Oct 8, 2007, at 8:34 AM, Shaun McCance wrote:
> >
> > - What sort of information does the Mac help system need?
> > ...
> 
> <http://urlx.org/apple.com/d50c3>
> 
> Help buttons in Mac OS X (in bundled software, at least) usually don't  
> open exact pages. Instead they open search results, in which the actual  
> page the developer was thinking of is the first or second result. This  
> is, I assume, because Apple are afraid of the software and the help  
> getting out of sync. If a Help button linked directly to a page that  
> had been renamed, or merged into another page, the help viewer would  
> have to return a nasty error "The help topic does not exist, contact  
> your application vendor for an updated Help file" �a Windows, and  
> people would be put off trying to using the help ever again.
> 
> I think that's a valid concern, but an annoying solution. I would  
> rather that any updated API for opening a help page in Gnome had two  
> compulsory parameters -- one for the page ID, and one for a fallback  
> search string if Yelp can't find the page. That way the page-not-found  
> error would only ever appear when debugging.

This is an interesting idea.  But it leaves me with
a few questions.

* Under what circumstances would the application and
the help files ever become out of sync?  We release
them in the same package, so they should (in theory)
always be in sync with each other.  Note that:

- gnome-doc-utils contains a little-used utility that
generates a header file with symbols for each page.
If you use these instead of raw strings, you avoid
typos or other problems with page IDs.  They would
cause a compiler error.

- Both DocBook and Mallard provide a means of putting
additional anchors on things.  So when you do some sort
of surgery on your document, you really ought to put an
auxiliary ID somewhere so that links don't break.

- In practice, I realize it's common for the help files
not to keep up with the application.  But this is not
the sort of thing that causes broken IDs.  Also, search
strings wouldn't help much, because in these cases, the
content just isn't there.

* A search string really should be translated if it's
pointing to translated help.  But if it's pointing to
English help, it shouldn't be translated, even if the
application is translated.

Currently, our application translations are much more
complete than our document translations.  So I'd be
worried that this would cause a different sort of
out-of-syncness: a German search string getting used
on an English document.

* In my experience, when you have compulsory parameters
that don't usually do anything, most people will just
do what they need to shut up the compiler.  So instead
of this:

gtk_help_show ("user-guide", "printer-configure", "anchor",
               "configure printer");

They'll do this:

gtk_help_show ("user-guide", "printer-configure", "anchor", "");

Alternately, they might write very unhelpful help strings,
because they're in a hurry to write real code, and don't
want to think about help stuff.

--
Shaun