WWDC2000 Session 145

Transcript

Kind: captions
Language: en
ladies and gentlemen please welcome the
user experience technology manager for
Mac os10 john de Lindsay seems like I've
been in this hall all day all right well
welcome to session 145 Apple help apples
really embracing a lot of open standards
for mac OS 10 and help is is no
different Apple help is quite clearly
going to be HTML based and this session
is talking about that both from a
developer engineering point of view how
to implement Apple help through ap is
that exists as well as helping you
author the HTML helps figuring out what
to do is disability to make it to make
it really nice and I just want to
encourage you as developers to deliver
really good help it's very important
from the user experience point of view
and users if you look at a cystic
statistics if who's buying Macintoshes
now stats that Steve showed in the
keynote in terms of imac buyers there's
a large percentage of users that are new
to computers new to the Macintosh and
your ability to live a really
comprehensive help and interactive help
is if key to their success in the
Macintosh and their enjoyment of their
machine so to talk about Apple help i'd
like to welcome on stage Gordon Meyer
who is part of the human interface team
at Apple thanks John thank you hello
everyone thanks for coming I'm wondering
how many of you were in this session on
Apple help last year could you raise
your hand for me ok great and how many
of you are responsible for writing and
you know authoring health systems for
your products all right just one more
how many of you are responsible for
implementing health systems that is
getting your application to talk to your
help ok great we have good information
for everyone before we begin I should
probably warn you about something though
I went to a public speaking class right
to prepare and they said that I should
practice this presentation while I was
doing other things so I decided to
practice it while I was driving my car
worked pretty well people look to kind
of funny
you're talking to yourself but there's a
side effect I didn't really anticipate
so if at any point I should stop and
suddenly ill get out of my way don't
take it personally and as I can do it
your driving record this is the habit
well it lets you drive a blue minivan
with you top place and I owe you an
apology anyway so let's get started
Apple's help there's a lot of
information to cover but let's start by
going back in time just a little bit to
system 75 at that point the health
system for the Macintosh with Apple
guide life little system small floating
panels took users through tasks step by
step by step worked great for novice
users wasn't so great for intermediate
advanced users but it really wasn't
designed for them it was also expensive
and hard to produce so with system 85
apple introduced apple health which is
we're going to talk about today the
system is much more flexible and a lot
easy to offer for and we're gonna give
you all the details kind of soup soup to
nuts of Apple help all the features how
to author it but let me cut to the
bottom line first because i'm kind of a
bottom-line person and i know some of
you are too so why should you adopt
appal help well if you're an author
you'll be pleased to hear that it's very
easy to create and use a standard HTML
3.2 you can use any off-the-shelf
authoring tool you like dreamweaver go
live ed at it simple text even something
on another platform if you're an
implementer is equally easy to implement
we have a nice set of AP is very simple
yes flexible and i'm really proud to
announce today really pleased to
announce today that apple health is the
health system for mac OS 10 if you
deploy an apple help you can use your
help across carbon cocoa and classic
environment one health system across
everything so that's the bottom line but
we're going to cover some other stuff as
I said we're going to talk about the
help viewer which is kind of the heart
of Apple he'll talk about its features
and give a little demonstration we'll
also talk about how to create an apple
help book you'll see it that's very
easily do then we'll cover the Apple
help api's which are how you get your
application talking to the
system and as a bonus we have free Ginsu
knives for everyone no I'm kidding of
course of course I'm kidding what we
have is something much better the HTML
rendering library this is a piece of
code that you could use in your
application to display HTML data and the
fan club from the rendering library is
pregnant the help viewer so as I said to
help you were as the heart of the apple
health system what it is it's a
lightweight HTML display application
render standard HTML 3.2 without forms
Java scripts or plugin but it does
display a QuickTime media we don't use
the quicktime plugin to do that we do it
natively and it can handle any kind of
QuickTime data you want to throw at it
movies still sound VR interactive
streaming I've been attending some of
the QuickTime sessions across the street
this week and there's a lot of great
things that can be implemented in health
systems to make some really unique help
and you can use all of that in the
health viewer so you might be thinking
is this is the first you've heard of
Apple help you might be wondering will
key Gordon if its HTML based and it can
display movies round-eyed issues a web
browser well you could but you shouldn't
apple health is the hell platform for
macula scan your users will be expecting
your help to appear there additionally
web browsers these big monster
applications lots of you I lots of
memory to help viewer is an optimized
application specifically for displaying
help and because we know that's how it's
going to be used we've added some unique
features to it to support that for
example it incorporated some Sherlock
technology to allow you to search all of
your help really quick returns a nice
relevance ranked list of results for
your users we've also extended HTML to
allow you to launch applescript app
Apple script automations so you can do
things automatically we'll talk about
that some more and with this version of
Apple help we have the ability to pull
help content from the internet that way
you can make sure users are getting the
latest information and you can continue
to develop and enhance your help and
still stay within to help your
environment so that's the high-level
view but it's time to take a look at it
goes you know pictures speak louder than
words so to help me out with a demo I
want to enter
used Jessica Khan jessica is a lead
engineer for Apple help okay well
jessica is going to drive while I talk
and this saves me from the potential
public embarrassment of having to point
click and talk all at the same time so
here you see the help you are rendering
HTML nicely it's a native mac OS
application has been carbonized so it
has the aqua appearance you see some
lists with that you can click on you see
graphic there it's being displayed by
quick time and across the top of the
screen is our interface are very simple
interface for access from searching you
can type in a word there and word or
phrase or get some results why don't we
look for something on Oh firewire will
help you or quickly searches all of Mac
help there's about 150 200 pages at this
point and finds the most relevant topics
based on what we typed in let's take a
look at one of those
so this particular page of the quicktime
movie embedded on it and they began to
play when the page was opened they said
we don't use the quicktime plugin but we
do respect all of the embed parameters
you'd expect an HTML so this one was set
to auto play you can also show the
controller or not show the controller
whatever it is you want to do let's look
now for something on internet settings
great and again we've searched through
all of Mac help it found the most
relevant information when we go into one
of those and we want to show you another
feature of apple health which is the
Apple script automations now this page
is talking about the Preferences
application because that's how you set
your internet preferences on Mac OS 10
and that blue button is an image map and
that has an href that launches an
applescript let me go ahead and check
that out so when Jessica clicks that it
runs the Apple script which opens
preferences application for the user
it's a very simple example of using
applescript to automate tasks of the
users let's go back to the health again
and why don't we check out the health
center now the health center is a list
of apple health books that are installed
on the system and those that are
available for the particular user that
jessica is logged in on in this case you
see we have mac help and quicktime help
or both available and when you convert
your book to Apple help format it'll
show up in this list too we've got
plenty of room for you at the bottom we
have something new it's called the
developer center we just added this one
we check that out this is on DP for the
CD you all got and this is a complete
documentation you need to develop on Mac
os10 our tech clubs group has done a
great job of converting their stuff over
there continuing to work on it and
improve it and why we just take a quick
look and browse through here and of
course because this is an apple help
format was completely searchable
whatever you want to find why don't we
go back yeah let's check out quicktime
help this is kind of a special book now
this is a de mac OS 9 book from its from
mac OS 9 quicktime help we've copied it
over to mac OS 10 works fine that's
fully supported but this is an
interesting example because there's very
little of this book that actually exists
from the hard disk most of it is on the
internet now we can search it we can
cruise through the table of contents a
little bit here but when we really want
to look at a page the help viewers going
to retrieve that page for us from the
internet
once the internet wakes up
there we go great so you thought
happening there was URL access was
coming to the front it's not displaying
its progress bar for us right now and we
decided to leave that in because we know
you're a skeptical crowd and otherwise
we just seemed like there was a delay or
wouldn't be able to tell it was really
happening but that page has been pulled
from one of the apples Internet servers
across the internet and brought down for
the user that's one of the new features
we've added it was added in Mac OS 9 and
something we're going to talk about a
little bit later some more why don't we
go back to the health center and check
out smack help again and let's look for
something to do with sound what I want
to show is how to help you were searched
his content so we're in Mac help and
we're looking for something to do with
sound and we found some various topics
related to that but of course quicktime
help is assault here too and we know
that that has content about playing
sound of course so we could go back to
quicktime help and search but it's much
easier to use this link at the bottom of
the page and it says search all help
when we do that we get hits from search
time and from quicktime and from mac
help all at the same time we've just
instantly searched all of the help
that's available in the help center and
when your books installed in the health
center we'd be searching your book too
thanks Jeff so that's the help viewer
what do you think okay we go back to the
slide I want to talk a little bit more
about some of those features you saw the
first one is integrating integrating
internet based content the QuickTime
help book was an example of this now
this is something new that we've added
and it's a really powerful feature if
something that Apple is going to be
taking great advantage of in Mac OS 10
mac OS 10 is a great internet client and
as such is going to have partially based
internet help now i don't really have to
tell you you guys are all developers but
you think about your development cycle
for a program right the programs under
development at some point the help team
comes in and starts writing content and
help team has to finish well maybe here
and this is where your application ships
right there's a gap of time here before
between the help freezing and the
application being done and things change
during that gap of time as much as we
wish they didn't write
teachers are removed because they're not
working right bugs are fixed you know
maybe somebody from marketing decides
that the find function should be named
after a fictional detective right it
could happen believe me and your help is
wrong and nobody has even seen it yet
it's really a bummer you know so my wife
I gotta tell you so my wife tells me
that the reason i am i'm losing my hair
is that i'm getting older I swear it's
last minute changes if I could just get
like workman's comp to pay for Rogaine
at the offset anyway so this is a great
feature it's good for you because you
can continue to develop and improve your
help over time after where you would
normally freeze it and even after the
product is shipped you can continue to
enhance it because your users
automatically get the latest content
from your server it's also good for
customers right in this internet age
people want the latest up-to-date
information that's why we go to the web
in the first place and this make sure
they can get the latest help all within
the help your environment so let's talk
about how this works and I hope viewer
always look for content locally that is
that's where it loads it's filed so how
do we get it to talk to the Internet
well you saw URL access that's part of
our trick but let's take a closer look
at how that works in the simplest
scenario the help viewer wants to open a
page it looks in your applications help
folder it finds the page is looking for
so it opens it but what if the page
isn't there well next the help viewer
will look in the help cash the help
cache contains help files that were
recently downloaded from the internet if
the page that help you was looking for
is in the help cash then it loads it
from there if it's not in the help cash
then it asks URL access to go to a
remote internet mirror retrieve the
pages looking for URL excess brings that
page and push the in the help cash from
which to help viewer loads it so what's
happening behind the scenes is the help
viewers pre appending the location is
looking for at each stage again in the
local situation is looking for my appt
help / page HTML it doesn't find it
there it Priya pins the location of the
help cash still looking for page dot
HTML if it doesn't find it there then it
it turns it into a URL and priya pans
the location where you said your
internet content is stored you tell us
where the internet content is stored
when you index the file and we're going
to cover that that's what it passes off
to you are Alexis for it to retrieve for
us now once the page is putting the help
cash it stays there for three days this
allows you to go back and look at it
again right cuz they just looked at it
they might want to go back and review it
and I don't have to go through this
retrieval process again but it doesn't
stick around so long that it becomes
stale again you specify the remote
location when you index the file so you
do need to know in advance before you
ship the product where your files are
going to be and you can't put everything
on the internet you have to have the
search index file locally because that's
where we know where the internet site is
and also it allows users to search the
content without having to connect to the
internet that's an important feature so
that internet based content there are
some other great features now we use
standard HTML lots of places but these
are things that you can add to your HTML
to enhance the user experience some
extensions we're going to cover the
first three in depth we're going to talk
about apple script automations how to
improve search results to make sure
users can find what they're looking for
and we're going to talk about anchor
looked up which is sub which is also
something new that we've added but I
want to talk for a sec I hear about the
dynamic table of content this is kind of
a hidden feature but it's it's unique
and you might need it so in the demo
there was the help center and the help
center contains three items Mac health
quicktime health in a developer center
those items appeared in a list because
the help viewer found them on the hard
disk and built that list automatically
so that same technique can be used
inside your help book to build your
table of contents now if you have a
product that has a lot of plugins or
optional pieces that users may or may
not install you can use the same feature
to build your table of contents
automatically making sure that users are
only seeing helps for the things they've
chosen to install that's kind of how
what it does if you want the details on
how it works it's all covered in the SDK
which will tell you about it again and
finally I want to talk about the
developer center now you saw it in the
demonstration
and I want to point out two important
things one is I think you've already
realize it's a great resource for you
all you have questions about developing
for Mac os10 go there type in your
search term browse around and get the
information you need but secondly it's
important to note because Apple is now
using to help viewer an apple help to
deliver all of its content all of our
end user based documentation is
delivered in this format and all of our
technical publications are delivered to
the floor mat we're solidly behind this
and we want you to join us in this
effort so let's talk about Apple script
automations those of you who are fans of
Apple guide this is a great way to
recover some of that interactivity and
do it for me type things it's also a
really good way to reduce kind of the
clutter that's in your documentation if
there are common steps that has to be
done frequently by users automate oh
okay gets people out of the help which
they really don't want to be in let's
face it and back into using your
application it's really easy to do eco
2h wrath as you see on the bottom of the
slide just a standard HTML link what you
give it a special URL which is helped
colon run scripts and you give it to
pass to your Apple script which has to
be on the local hard disk you can't run
an applescript it's on the internet and
you can pass a parameter if you want to
for example in Mac help we use this we
pass parameters for applications to open
we have one script that does it and we
just give it some parameters that
reduces the number of scripts we have
and eliminate some testing for us so
Apple script automations are a good
thing to add to your help it makes them
it just makes your help a lot more
interactive and usable search results
Apple help is all about searching I've
got a great search engine courtesy of
Sherlock you can type in a word affray
the sentence whatever you'd like and
automatically finds the most relevant
topics based on what you typed in but as
a Content author it's your
responsibility to test this and make
sure that people are getting the
information they need by typing and
words that you think they might use we
support standard HTML tags wherever
possible this is a great example of that
because we use the keyword tag which is
a standard meta tag and if you add this
to your pages you can use it to provide
synonyms and dispelling
to make sure that people can get the
results are looking for in Mac help for
example when we're talking about quick
time we always key word with the word
quick and the word time and that way if
somebody doesn't type in the product
name exactly right they're still going
to get the information they're looking
for you can also use the no index tag
this is robots equals no index common
tag and this will tell our search index
to skip that page and not included in
searching finally there's apple abstract
this is a tag we've added and the
contents of this meta tag can contain a
summary of your page if you provide an
apple abstract for a page and it shows
up in the search results the abstract
information shows up underneath the hit
that way people who decide if they want
to go view that page if it looks like it
has the information they're going to
need this is a great addition for
internet-based help because it helps
people decide whether or not they want
to connect and download that page next
is anchor look up this is a new feature
we've added since the last time we met
and talked about Apple help this is a
great way to provide contextual help now
we didn't include me the demo because we
don't know I'm going to make the demo
see long it's really easy to explain
anchors a standard HTML tag you embedded
in your HTML and he gives a name for
that anchor such as foo from within your
application say from a Help button in
the dialog using our API to tell the
help you were to open the page that
contains the anchor foo the application
doesn't have to know what page that
occurs on the help you or will see that
anchor find the right page and
automatically display it for the user
that way the content authors can
continue to modify the content move
stuff around as necessary without having
to deal with breaking things in the
application there's a new feature I
think you'll find it really handy
so authoring Apple help excuse me this
is where we get to the nitty-gritty now
you've heard me babble on for a few
minutes about how great the health
system is and how easy it is to use but
this is where the proof is in the
pudding so to speak you can literally go
from HTML to apple health in five
minutes it looks really hard to make
this as easy as possible now you need to
start with HTML remember we support HTML
3.2 you could use existing files you
create some new ones just author some
HTML once you've done that decide on
which page is going to be your start
page this is the page that appears when
you click your book name in the health
center it's also the page that appears
when somebody accesses your help menu to
that start page you add one meta tag a
meta tag a standard HTML it doesn't
displayed in the page so you can go
ahead and add this it won't affect the
page if you're reusing it in browsers on
the web or sitting some other helps us
book this meta tag is called Apple title
and the contents of the meta tag is the
name of your book in this example my
apps dot help this is the name that's
displayed in the help center and it also
becomes your book ID the book ID is used
in the API that's all you have to do is
add that one tag to one page the next
step is the indexer we give you a
drag-and-drop indexing tool you take
your folder of HTML you drop it on the x
and indexing tool they quickly goes
through and scans all of the content
pays attention to keywords Apple
abstracts and the windex and everything
else it needs to look at and it creates
the search index file which is a small
file it automatically puts it in the
right place within your help folder now
if you're going to use internet based
content this is where you tell us where
your remote mirror site is what the URL
is where we can go and download help if
we need to and if you're using anchor
look up to provide contextual help and
you need to turn on a checkbox but it's
really as easy of that as easy as that
the next thing to do is to store your
help now Mac os10 your applications help
is stored within your applications
bundle you take your help folder you put
it in there with the rest of your other
resources you have localized resources
that's great you can have a local life's
to help you put it inside there as well
this provides a drag-and-drop install of
your application and all the help files
people can move it around and you know
heaven forbid you can throw it away and
they throw away the app add the help it
was nice feature and i'm michael s 10
because we pay attention to file
permissions if somebody doesn't have
permission to launch your application
then they won't see your help and vice
versa this makes for a health center
that's targeted to exactly what you can
use the cool feature so on the authoring
side of things you are done right you
started with HTML hopefully added some
applescript enhancements some keywords
make sure people can find their content
may be decided some of it was going to
be internet-based it's as simple as that
the next step is to get your application
to open to help you or at the
appropriate time with the right content
and to cover how to do that does not
mean it's Miller time for me I want to
reintroduce the first one responsible
for bringing Apple help to Mac os10 and
the lead engineer for Apple help Jessica
Khan Africa
[Applause]
thanks Gordon okay well as Gordon said
I'm here primarily to talk to
application developers about how you can
provide Apple help from within your
application I'm also be going to be
covering a little bit about some new
health URLs that have been introduced in
the Mac os10 help viewer they're so new
in fact that Mac help hasn't necessarily
adopted them so it's better for me to
discuss them with you so that you get it
right and I'm also going to be
discussing the HTML rendering library
briefly which is the underlying
rendering technology for the health
viewer and you can use that in your
application as well so here we are in
the next slide but actually I'm going to
take a moment to well I was considering
bringing a soapbox and getting up on it
but then I thought I'll be nervous
enough that I'm going to fall down on
the stage or something ridiculous like
that so let's pretend i have a soapbox
and i'm going to get up as much as it's
personally gratifying for me to see you
adopt appal health I want to see you
adopt it because I want Mac os10 in
particular to be awesome and part of Mac
OS 10 being awesome is it being an easy
transition for our existing users the
way to make it easy for them is not only
to provide wonderful health content but
to make sure that they know how to get
to that health content and I think that
if we're consistent with bringing them
health content through the health viewer
they're going to have an easier time of
making this transition another thing
about this is that in the past we know
that you've had to do a number of
different things to provide help to your
users we've changed over the years and
some of you have custom health solutions
please consider not porting those custom
health solutions we've got a really easy
solution for you and I'm going to
explain how easy it is now ok so first
things first is your application
launches you're going to want to help
menu and the way you get that help menu
in Mac OS 10 is a little different than
it has been in the past but it's easy
for carbon and cocoa applications will
do all of the work for you as long as
you have a simple help system
but at the same time if you don't have a
simple health system we understand that
you need it to be customizable in the
simplest case you've got one book of
health content and you just need a help
menu with one night a minute and that
item will be your application name space
help all you need for that to appear
automatically in your application and in
fact for the menu item to be handled
automatically for you is a key in the
file known as your info key list I'm not
sure if all of you know what an
info.plist is perhaps if you saw the the
app packaging session earlier today or
one of the core foundation sessions you
may have heard a little bit about it but
it's basically away on Mac OS 10 for you
to give the system enough information
about your app that it can do a lot of
things for you so we have a special key
that we'd like you to put in your info
plist that key is the CF bundle help
book folder with that key you can put
one string as the value and that string
should be the name of the folder in
which your help content is stored so as
Gordon mentioned your help content
should be stored in a folder that's
inside of your application bundle so for
example if I have an application that is
called sketch that's that's been used in
examples earlier today inside of my
sketch that bundle and down into the
resources area of the bundle I'll have a
folder say it's called sketch space help
and that can be localized into multiple
different languages so in my English el
prof a sketch help and in my german el
proj i can have a sketch help and the
files inside of sketch help are
localized into the appropriate languages
but please remember as with any other
resource that you're localizing you do
not localize the name of the resource so
you have sketch help down in there and
in your pee list you just have CF bundle
health book folder with the
corresponding key of sketch help with
that p with sentry as you launch again
carbon or cocoa we make your help menu
we put the item in it and we handle that
item when the user picks it so I'm sure
you're wondering well what do you do
what if I don't want you to do that so
the thing that we do for you
automatically is that when the user
picked that item we would go out and
find
entry page for your health content that
entry page is what Gordon discussed
earlier where you put the meta tag for
the apple title and for I would guess
ninety-eight percent of applications
this is about all you need to do to
provide content for your users
particularly if you're using the health
viewer since that content is going to be
multifaceted as you want it to be with
movies Apple scripts and very searchable
all right but there are some
applications out there i'll admit that
have very complicated help menu
sometimes sometimes to my dismay if you
want to do that we're going to let you
we've heard that you need to be able to
do your own thing would help menu and
there are a couple different ways that
you can customize the first and easiest
one is if you need more than one book of
health content for your application
let's say you've got an app and it needs
help and then you've got plugins and
they need separate health for some
reason you can still use the CF mental
health book folder key in your pee list
but instead of putting one string as
your value you can put an array of
strings as your value and each string
will be the name of the folder for you
know the different book once you do that
then you get a little more complicated
and we can't handle things automatically
for you we will instantiate the help
menu for you at that point but it's your
responsibility to add menu items and
it's your responsibility to handle those
menu items when they're picked you can
even do one level further of
customization and of course no matter
what platform you're on if you know the
way to programmatically instantiate your
own help menu feel free if that's the
way you want to go but I hope that
you'll let us do the work for you one
more thing if that is the route that you
go there's an API it's one of the new
apple health api's and it's called aah
register help book you need to call that
if you have more than one health book
and you need to call it for each book
and what it does is it places your book
in the help center so you think so what
if my books in the help center I can get
through it for my help menu that's all I
need well you lose out on a lot of the
features of the health viewer if you
don't put your help in the Help Center
for instance it won't be searchable and
that's one of the key things about
health viewer
okay the example of the simplest case
and the case that we hope you'll adopt
since it'll be less error-prone for you
and you know great for our users because
it's simple if you have one health book
and it's stored within your app bundle
again your info pila should contain the
key CF bundle health book folder and the
strings of the folder name that your
help is stored in within your app bundle
okay so we talked briefly about one of
the Apple help API is the register book
API but there are a number of others
that help you customize either your help
menu or if you have helped button within
your application they're shipping as a
health framework which will be part of
the carbon umbrella but it's not yet in
DP for it will also be available in
carbon lib so you can ship an
application for carbon lib running on 9
dot whatever and also ship that same
binary to run on 10 and not have to
change the way you handle your help menu
and finally it's usable by Coco apps by
nature of the fact that it's just a capi
you can link to the health framework and
use these api so what are they well the
first one is registering a health book
and again that puts your help look into
the health center next there are api's
that cause help you were to open to a
particular location these are going to
be the most common api's that you're
probably going to want to use they ra h
go to main toc aah go to page and age
with a banker and we'll discuss them in
detail in a flight or two and finally
there's an API for performing a search
programmatically and that's a H search
okay so examples and at this point I
want to note that these examples work in
DP for so I want you to take your CD
home and try start hooking up your your
help stuff to the help menu stuff is not
yet implemented but you can still you
know make a test menu hook up those
items have buttons and hook them up okay
so the first one is H go to main toc and
you specify a constant fair of which toc
you want a TSE is a table of contents
and main toc would specify either the
health center or the developer center
that you saw in Gordon's demo earlier so
specified k h toc type you
to go to the health center or ka h toc
type developer to go to the developer
center all right to go to the main page
of your applications help book which is
probably the most common thing that
you're going to want to do you call h go
to page the first parameter there is a
CF string representing the name of your
books now it's a little confusing in
these slides I regret that the name of
your book is not the name of the book
folder the name of your book is the name
that you specified in the Apple title
tag so anywhere in these api is that you
see that we're requesting a book ID the
book ID is the apple title so turn that
into a CF string pass that to us the
next parameter is optional and here it's
set to null the parameter is a path so
you could conceivably pass us a book ID
and then a partial path into that book
and we would find that file for you here
it's null meaning that we want the main
page for the book and the third
parameter also optional is the anchor
parameter if you specified that we would
open to the anchor that you specified in
the page that you specified using the
other parameters here at snell you don't
ever have to supply an anchor to us in
the H go to page routine finally you can
go to any HTML file on the disk and make
sure that it opens and health viewer and
you can also do that with the age go to
page you see here that we use sort of a
mix and match of the different the
different parameters they're optional
and you can kind of combine them to make
cool things happen so here the books
name is null because this files might
have nothing to do with your book and
you're specifying a file in the URL that
is the full path to the file on disk and
here we have no anchor specified but you
could have an anchor specified and
actually let me take a moment to make
sure that you guys understand what we're
talking about when we say anchor I don't
think that we've had an example of it
the way it looks in HTML that's the tag
that starts with a and then space and
then name and equals foo so food would
be your anchor there the next type of
help api's are lookups and searches look
up actually take you to a place on disk
that's why they were listed that way a
couple slides back the lookups are what
Gordon discussed before and they're
especially helpful as he said for
content that changes
you don't want to break your app so what
you would do here is let's say I know
that I'm going to have a page on how to
print in my app but I don't know
necessarily that that page is going to
reside in a particular directory of my
health book I don't know what that file
name is going to be all I do is make
sure that in that file I have a name
equals printing and then I call AAA
choked up anchor with the CF string of
my book ID again the Apple title and a
CF string of the anchor that I'm looking
for and provided that I've indexed my
content for anchor look up healthier
takes care of figuring out what file
that anchors in and scrolling to the
appropriate place in the file you can
also perform a search of the health
content either of your book only or of
the entire help content installed on the
system here you see a church with the CF
string for find files that's searching
all of the help content for how to find
files so you might find how to find
files using your apps but you probably
also find helps about how to find files
using Sherlock the next one woman's the
search to just your book and there you
just specify the book ID again the Apple
title and then the search string ok just
to make sure that you guys understand
the stuff that the anchor stuff without
a demo is a little bit hard to get I
should know you may have seen a demo if
you went to the documentation session
yesterday they did a demo where project
builder was integrated with help viewer
and what they were doing there was an
anchor look up they called up help on a
particular carbon API and it launched
healthier and brought you to exactly
that api's documentation so this is sort
of a schematic of what that would be you
can see the arrow pointing inside of the
HTML file in the HTML there again is the
aam equals anchor and then help you were
when an anchor lookup was performed
forget folder name would open this page
and scroll to that anchor okay so we
have talked about the API and I hope
you're going to go and try them again
the examples that I gave you all work on
your CD and now I'm going to talk a
little bit about the URLs in depth some
of them again are very new but again all
of the examples i'm giving you are going
to work
so what are these URLs for their for use
from within your content to make that
content more dynamic they exploit the
very same features of the health viewer
as the api's do plus one additional one
that just doesn't make sense from an API
perspective so those features fall into
three categories again they open the
healthier to a specific location they
perform a search and they run an
applescript the first that we're going
to talk about opens the health viewer to
a particular location first is the help
go to help center that is equivalent to
the aah go to main toc api so here you
specify help go to help center equals
user to go to the health center and help
go to help center developer to go to the
developer center this is this might not
seem like much but it's actually a
really excellent feature because in the
past you couldn't have linked to the
help center from your help content you
would have to rely that the user knew
how to click that button on the toolbar
to take them back to the health center
why because you don't know where we're
writing the help center that's a
generated file so now you do have a way
to link to that and that can be really
helpful the next one is help open book
so this is analogous to some of the
variations of the aah go to page API
here the example you see is a help open
book with just the book ID specified
note here that the space in the book
name is escaped because this is a URL
and spaces really aren't valid the book
name again is the Apple title not the
folder name so what this would do is
bring you to the main page of your book
once again this is sort of an
interesting feature you're thinking well
why wouldn't I just linked to that using
a regular file call an URL to my main
page why is the silly health open book
thing well so there's a way that you can
generate your toc file for your book and
that's discussed in the SDK I don't
think Gordon went over it but it's an
interesting feature because this toc
would be generated the main page for
your book is generated once again you
suffer from the same situation with the
health center you don't know where we're
generating that file you couldn't
possibly link to it so this gives you a
way to do that
I can be very useful next is the help
anchor URL and obviously probably this
is analogous to be the anchor look up so
again I I keep thinking with these api's
when I'm thinking about this talk how am
I going to explain to them why these are
useful why these are more useful than
any of the standard HTML URLs that they
could use so this one was tricky but the
point is again that this is allowing you
to move your content around till the
very last second so this is useful not
in you know not when you're worrying
about breaking your app but it's useful
when you're worried about breaking your
other health content if you have a very
complicated but you might have 300 HTML
files if you have a complicated app and
you've got a lot of help so what is it
the last second somebody changes the
name of a file what are you going to do
what if you miss changing the links to
that file from elsewhere in your content
well this keeps you from having to worry
about that if you rather use this help
anchor URL instead of using a file call
and URL with an anchor appended this
will prevent mistakes like that and
finally this one I'll admit I'm on a
campaign to tell you why these are so
useful this last one is actually a
little silly and I'll admit it but it
fit in well because I had to implement
this functionality for the api's there's
a help colon full pass to file URL so
you're thinking why on earth would I
want to use this instead of a file and
well you know what I thought of a reason
I'm proud of myself I thought today it
took me forever to come up with it you
can actually use this as long as
internet config and set up your internet
preferences properly for help you were
to be the help colon handler if you put
this URL inside of content that for
instance might get opened in internet
explorer when a user clicks on this link
it will open the help viewer so you
might want to use this for files that
contain content very specific to the
health viewer that you would never want
opened an Internet Explorer for instance
something that might have run script
URLs that launched Apple scripts
finally performing a search and running
an applescript so you can script not
script I'm sorry you can put URLs for
searches inside of your content that's a
help cool in search and you can again as
with the API either limit that search to
your book or search all content
installed for an example of this which
is pretty neat they're not actually
using a help colon search but it is a
search from within content so it'll give
you they'll get you thinking on why you
might want to do this look into the mac
help book on your DD for CD and you'll
see that list of quick clicks and you'll
notice when you click on them that that
initiates a search for a particular term
so check that out no get you thinking on
why you might want to use these URLs and
then Gordon did a very good job of
explaining what running an applescript
is good for and I'm just going to give a
slightly more specific example for
formatting purposes so you see that it's
helpful and run script equals and then a
path to your script which is relative to
your books folder again it's a URL so
please escape spaces if you've got a
space in your book folder in its name
okay so we're done talking about the
api's and we're done talking about the
URL I'm going to take a moment just to
note that if you're left feeling like
wow she just bombarded me with a ton of
information I couldn't copy down the
examples anything like that we're going
to give you an email address that you
can send questions to and please do
don't feel like we don't want to hear
from you because I'm just desperate for
you to adopt this technology and I want
to make it as easy for you as possible
on that note let's talk about the
rendering library this is the underlying
technology that renders HTML in the
health viewer and on 10 it's shipped as
the HTML rendering framework which is a
part of the carbon umbrella in DP for a
mac OS 9 it's still available as a non
carbon shared library but it will also
be available in carbon lib so
what exactly is the sting and why would
I want to use it well you use it to
render HTML into any window in your
application an example of this might be
if you had an about box and you wanted
more dynamic looking about box content
you wanted a picture in there you wanted
a link to something out on the internet
you can use the rendering library and
have a pain inside of your about box
that renders HTML well so what exactly
does it do well it has the same
capabilities that you see for HTML
rendering in the health viewer so all
that stuff with movies and image maps
and it can play sounds it does some
really interesting things just in case
you forgot the recent demos I've got a
screenshot here that shows that it's got
a picture it's got the image map of that
button it's got I believe this page as a
table within a table it's got a font
specified it's got a colored table cell
it does have some pretty interesting
stuff yeah well give me the details well
so it does HTML 3.2 which includes lists
frames tables images and client-side
image maps and QuickTime embedding of
any quicktime content that you can throw
at us what doesn't it do now this is a
little controversial for some of you in
the audience it doesn't do HTML 40 it
doesn't do cascading style sheets and
basically it's not real good for
browsing the web use internet explorer
for that or another browser of your
choice so if it doesn't browse the web
why do I need it well it's really
lightweight we did it that way on
purpose it's fast it's ideal for
tailored content what I mean by this is
that you don't want to use it for
pulling web pages down when you haven't
you're not sure what's in there it might
be HTML 40 it might be malformed HTML it
it might be anything that's not what
it's great at it's great at content that
you designed for it you've seen it be
great at rendering health content it's
also really good at item descriptions or
item summaries and I'll show you in a
demo in a minute we use it in software
updates and you can also use it for
advertisements as I mentioned you can
have an about box renders HTML
and you know has a really cool-looking
ad for related products to the software
that you're already selling and at this
point I'm going to show you a demo of
their energy library
so here we are and we're going to launch
software update so for those of you
unfamiliar with software update it's
apple's mechanism for delivering updates
to the installed software and i believe
it shipped on mac OS 9 and you can
update your software on that with it and
it's shipping now in DP for inside of
the system demos folder I believe so it
wants me to click the update now button
to see what software is available I
think I'll do it looking for updates
let's hope the internet is being nice to
us Oh what have we here it's found an
update to Mac os10 you guys think I
could do that install mac OS 10 right on
here using software update we'll see
what it says about macro attend this
pain here is the rendering library I
know it's it's simpler than the
healthier content up because I am just
not a web designer but what is the same
let's see Mac os10 has some great
features including a new version of the
already excellent HTML rendering library
you guys know that before you update
consider a visit to the apple store to
purchase a g4 in a cinema display making
10 all the more enjoyable so when I wish
I had one alright so let's visit the
apple store maybe I'll buy myself a
cinema display while my boss isn't
looking oh wait he's looking keys right
there so check it out that's an example
of how you can bring people to your
website to purchase things so I hope
that you're going to go check it out
music
okay so I'm about done with my spiel but
I'll tell you where you can get more
information admittedly as i said the
documentation for the apple health api's
is a little little lacking but we're
working on it for working real hard so
for now check out the system library
frameworks help framework you'll see the
header dare you can get going and i'll
give you an email address to send
questions to four other general apple
health information including a link to
the sdk that Gordon mentioned that has a
lot of interesting content authoring
tips and lessons and meat stuff samples
also information on some of our legacy
technologies in case you need to figure
out how to transition away from them
visit developer apple com / mac OS flash
helped HTML that's a good jumping off
point for lots of information and then
for specific information on the HTML
rendering library their sample code and
I know that's a long URL so try the
doggle and make sure that you guys have
time to copy it down that's developer
apple com / sample code / capital s
sample underscore capital c code / human
interface toolbox with underscores and
capitals HTM and then there's also a PDF
with documentation on the each of the
individual HTML rendering api's and how
to use them and while I've been reading
out all the other you are el sol
developer.apple.com tech pubs mac OS 8
PDF HTML underscore rendering lib dot
PDF and you know these are long so if
you didn't make it just go to the
developer.apple.com site and get to the
documentation area and search it and
you'll find this stuff okay so how can
you communicate with us because we know
that you want to at least I want you to
you can email the engineering team
including myself at Apple help comments
that's capital a capital H capital C oh
why am I saying that i'm sorry i'm a
spaz email addresses are all lowercase
you guys know that at group apple com
apple help authoring discussion list
this is in particular for tech writers
or
authors and you can discuss with each
other what you're doing get answers I'm
not sure if it's monitored by opal or
not maybe Gordon would answer that
question when he comes up here later and
that's you can find that from list apple
com and finally you can always
communicate with John Glenn Z he is the
user experience technology manager and
he handles developer relations for our
technology and that's ghal NZ spelled
gele why NSE at apple com and with my
giving you his email address I'll invite
him back on stage and he's going to take
us through the roadmap and QA thanks
Jessica so let's talk about the road
back briefly many of these sessions have
passed but it's important to know that
they did talk about issues related to
aqua and user experience and AP is that
were talked about here packaging
bundling these sorts of things tomorrow
is a session on navigation services
which doesn't apply directly to Apple
help but it relates to the user
experience subtract and it relates to
you delivering you know really
consistent or really rich user
experience in your application on 10 and
of course the ever famous or infamous
aqua feedback forum which we're looking
forward to your participation in
you