Re: gtk_show_help and gtk_show_url

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.

Matthew Paul Thomas

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]