Re: Apple's Help Viewer
Re: Apple's Help Viewer
- Subject: Re: Apple's Help Viewer
- From: David P Henderson <email@hidden>
- Date: Thu, 28 Apr 2005 18:08:33 -0400
On 28 Apr 2005, at 16:41, Jerry Krinock wrote:
I have used some very nice applications that open their help in the
default
web browser instead of Apple's Help Viewer. I'm working on a rewrite
of my
app and I think I am going to use the default web browser also.
Before I do
so, I'd like to ask if anyone knows of some benefits of Apple's Help
Viewer
which I have overlooked.
Thanks,
Jerry Krinock
Here is what I think:
WHY APPLE HELP VIEWER IS BAD FOR THE USER:
1. I believe it is confusing to new users (it was confusing to me)
when I
click "Help" in an application and a different application (Help
Viewer)
comes to the front. The user was not expecting this. On the other
hand,
when switching to the default web browser, users recognize it, know
what is
going on and how to use it.
This statement seems largely anecdotal and unsubstantiated which is not
to say that it was not your experience.
2. I have seen Help Viewer take 30 seconds or more to load on a G3.
I've seen [insert name of web browser here] take a significant amount
of time to launch YMMV. For me Help Viewer is quite responsive on my
iMac G3 (350), iBook (266) and Power Mac B&W (300), again YMMV. My
point is that this experience is also anecdotal. Any number of problems
may exist which cause poor performance in any application not limited
to just Help.
3. Help Viewer is buggy. For example, if the user already has Help
Viewer
open and was previously viewing Help from App A, then selects "Help"
in App
B, sometimes Help Viewer simply brings the window showing App A's help
to
the front, but does not load the Help for App B. I have seen this
happen
between other apps, not just mine, in 10.3.
Help Viewer does have certain limitations, one of which is that only
one help book/page/window can be open at a time. As to your other
complaint, I haven't seen this behavior.
4. Help Viewer is basically a light-weight web browser with many
features
removed, and some different commands. Sometimes it makes sense to use
a
smaller tool for a smaller job. But not when the bigger tool is
something
that all users have, usually already launched, and know how to use.
Help Viewer is not a light-weight web browser. It is rather an
application for viewing help files which are written in standard html.
Help Viewer in 10.3 (and possibly in later builds of 10.2 but not
certain about that) uses WebKit to render html pages. Additionally,
Help Viewer can run Applescripts, so if one's app is applescriptable,
one can write and run scripts which demonstrate the behavior about
which the user has questions.
WHY APPLE HELP VIEWER IS BAD FOR THE DEVELOPER:
1. When developing (editing and testing) Help for my application, you
have
to:
(a) Insert two cryptic entries in Info.plist
cryptic (krip'tik) adj. 1. Secret or hidden; occult. 2. Puzzling;
mystifying.
Given that the necessary entries are defined, discoverable and
explained, I can't agree with this statement. The information
pertaining to creating application help is logically located in the
developer documentation under the _User Experience_ topic in an
article, titled "Providing User Assistance With Apple Help," which can
be found in the documentation installed by the Xcode tools or on the
web at
<http://developer.apple.com/documentation/Carbon/Conceptual/
ProvidingUserAssitAppleHelp/index.html>.
For the record the two "cryptic" entries are:
CFBundleHelpBookFolder - this entry is the name of the folder in which
an application's help book is found.
CFBundleHelpBookName - this entry is the name of the application's help
book.
(b) Place all your html help files in the Resources
folder pointed to by one of the entries in (a)
Given that help files are resources, how is this requirement
unreasonable?
(c) Your "root" help must have a cryptic <meta NAME...> tag
in its head, and must have extension .html
Root as in title page. See above for definition of cryptic. How is the
meta tag cryptic? It is clearly defined and the only one required for
the application help to work correctly with Help Viewer. Also what file
extension should these files have?
The meta tag in question has a name value of "AppleTitle:" and a
content value which must be the same as the value of the plist
CFBundleHelpBookName entry, e.g.
<meta name="AppleTitle" content="My App Help">.
Again this information is documented at the URL given above.
2. If any of the pieces in the above chain are missing or
mis-spelled, you
don't get any error messages. It "just doesn't work".
I agree that this could work better.
3. Assuming that you've already got the launch path of your app for
other
purposes, opening help in the default browser takes one (1) line of
code:
It takes no code. If your help is in the standard location, and you
have used the "cryptic" plist entries correctly, launching your
application help requires nothing more than wiring your access points
(menu item, buttons, etc…) to -showHelp: under the Target/Action tab of
the Connection pane inspector panel.
Dave
--
Chaos Werks Design
"A lie can run around the world before the truth can get its boots on."
- Israel Zangwill (not Edward R. Murrow)
Attachment:
smime.p7s
Description: S/MIME cryptographic signature
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Cocoa-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden