Re: gtk_show_help and gtk_show_url

[Matthew Paul Thomas <mpt myrealbox com>]

On Oct 26, 2007, at 10:14 AM, Shaun McCance wrote:
> On Thu, 2007-10-25 at 17:36 -0700, Matthew Paul Thomas wrote:
> ...
> > 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.

So I guess the answer is "in practice". ;-) I've seen the "The Uniform 
Resource Identifier ’file://some.long.and.scary.url’ is invalid or does 
not point to an actual file" alert several times in Gnome, and I expect 
it to become more frequent as programs use context-sensitive help more 
often and that help becomes more extensive and frequently edited.

> Note that:
>
> - gnome-doc-utils contains a little-used utility that generates a 
> header file with symbols for each page.

That's good, but I think error recovery baked in to the API will 
inevitably be more robust than error recovery that relies on the use of 
a particular authoring tool ...

> - 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.

... or error recovery that relies on authors remembering to do optional 
things.

> - 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.

Right, I'm not claiming a search string would fix all problems with 
broken IDs, just two of them: (1) the relevant file has been renamed, 
and (2) the relevant help has been merged into another file.

> * 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.

That's an interesting problem, but search results would be more useful 
more often than an error message, regardless of whether that error 
message was localized. (Namely, search results would be more useful 
whenever the topic being searched for contained untranslated words, 
such as proper nouns.)

One approach would be to put (a more human-friendly version of) the 
localized error message at the beginning of the search results. "That 
topic wasn’t found. Try these suggestions:"

> * 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.
> ...

I agree -- we've seen this in HTML with <img alt=. This case would be 
different, though, in that people wouldn't be any *worse* off with 
search text of "" than they were with the error alert (especially if a 
brief explanation was prepended to the search results as I described 
above). Meanwhile, some authors would have been prompted into providing 
useful search strings when they wouldn't have otherwise, making help 
more reliable on average than if the parameter was optional.

Cheers
--
Matthew Paul Thomas
http://mpt.net.nz/