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" à la 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 _______________________________________________ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list