Ladies and gentlemen, please welcome the User Experience Technology Manager for Mac OS X, John Galenzi. Seems like I've been in this hall all day. All right, well, welcome to session 145, Apple Help. Apple's really embracing a lot of open standards for Mac OS X, and Help 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 APIs that exist, as well as helping you author the HTML Help, figuring out what to do specifically to make it really nice. And I just want to encourage you as developers to deliver really good help.

It's very important from a user experience point of view, and users-- if you look at the statistics of 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 deliver really comprehensive help and interactive help is 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. JOHN WOLFF: You're welcome. Here's your switcher. 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 authoring help systems for your products? All right, just one more.

How many of you are responsible for implementing help systems, that is, getting your applications to talk to your help? Okay, 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.

It worked pretty well. People look at you kind of funny because 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 yell, get out of my way, don't take it personally. It has nothing to do with your driving record. It's just a habit. Well, unless you drive a blue minivan with Utah plates, then I owe you an apology.

Anyway, so let's get started. Apple Help. There's a lot of information to cover, but let's start by going back in time just a little bit to System 7.5. At that point, the help system for the Macintosh was Apple Guide. Nice 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 and advanced users, but it really wasn't designed for them. It was also expensive and hard to produce. So with System 8.5, Apple introduced Apple Help, which is what we're going to talk about today. The system is much more flexible and a lot easier to author for.

And we're going to give you all the details, kind of 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 Apple Help? Well, if you're an author, you'll be pleased to hear that it's very easy to create. It uses standard HTML 3.2. You can use any off-the-shelf authoring tool you like. Dreamweaver, GoLive, BBEdit, SimpleText, even something on another platform.

If you're an implementer, it's equally easy to implement. We have a nice set of APIs, very simple yet flexible. And I'm really proud to announce today, really pleased to announce today, that Apple Help is the help system for Mac OS X. If you deploy an Apple Help, you can use your help across Carbon, Cocoa, and classic environments. One help 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 Help. Talk about its features and give a little demonstration. We'll also talk about how to create an Apple Help book. You'll see that that's very easy to do. Then we'll cover the Apple Help APIs, which are how you get your application talking to the help system.

And as a bonus, we have free Ginsu knives for everyone. Oh, I'm kidding. Of course. Of course I'm kidding. What we have is something much better, the HTMLRenderingLibrary. This is a piece of code that you can use in your application to display HTML data. And the fan club for the rendering library is present.

The Help Viewer. So as I said, the Help Viewer is the heart of the Apple Help system. What it is, it's a lightweight HTML display application. It renders standard HTML 3.2 without forms, JavaScripts, or plugins, but it does display 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, stills, 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 help systems to make some really unique help. And you can use all of that in the Help Viewer.

So you might be thinking, if this is the first you've heard of Apple Help, you might be wondering, well, gee, Gordon, if it's HTML-based and it can display movies, why don't I just use a web browser? Well, you could, but you shouldn't. Apple Help is the help platform for Mac OS X. Your users will be expecting your help to appear there. Additionally, web browsers are these big monster applications, lots of UI, lots of memory. The 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, we've incorporated some Sherlock technology to allow you to search all of your help really quick. It returns a nice relevance-ranked list of results for your users. We've also extended HTML to allow you to launch AppleScript 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 the help viewer environment. So that's the high-level view, but it's time to take a look at it, because, you know, pictures speak louder than words. So to help me out with the demo, I want to introduce Jessica Kahn. Jessica is the lead engineer for Apple Help. Welcome.

So Jessica's 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 Viewer. It's rendering HTML nicely. It's a native Mac OS application. It's been carbonized, so it has the Aqua appearance. You see some lists that you can click on. You see a graphic there that's being displayed by QuickTime. And across the top of the screen is our interface, our very simple interface for accessing searching.

You can type in a word there, and word or phrase will get some results. Why don't we look for something on-- oh, Firewire. So Help Viewer 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 has a QuickTime movie embedded on it, and it began to play when the page was opened. As I said, we don't use the QuickTime plugin, but we do respect all of the embed parameters you'd expect in HTML. So this one was set to autoplay. 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.

And again, we've searched through all of Mac Help and found the most relevant information. Why don't we go into one of those? And we want to show you another feature of Apple Help, which is the AppleScript automations. Now, this page is talking about the Preferences application, because that's how you set your internet preferences on Mac OS X.

And that blue button is an image map, and that has an href that launches an AppleScript. Why don't we go ahead and check that out? So when Jessica clicks that, it runs the AppleScript, which opens Preferences application for the user. It's a very simple example of using AppleScript to automate tasks for the users.

The Help Center is a list of Apple Help books that are installed on the system and those that are available for the particular user that Jessica has logged in on. In this case, you see we have Mac Help and QuickTime Help are 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've just added this. Why don't we check that out? This is on DP4, the CD you all got. And this is the complete documentation you need to develop on Mac OS X. Our TechPubs group has done a great job of converting their stuff over. They're continuing to work on it and improve it. And why don't we just take a quick look and browse through here. And of course, because this is an Apple Help format, it's completely searchable, whatever you want to find. Why don't we go back? Yeah. Sure.

Let's check out QuickTime Help. This is kind of a special book. Now, this is the Mac OS 9 book. It's from Mac OS 9, QuickTime Help. We've copied it over to Mac OS X. Works fine. That's fully supported. But this is an interesting example, because there is very little of this book that actually exists on 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 viewer is going to retrieve that page for us from the internet.

Once the internet wakes up. There we go. Great. So what you saw happening there was URL access was coming to the front. It's not displaying as progress bar for us right now, and we decided to leave that in because we know you're a skeptical crowd and otherwise it would just seem like there was a delay or you wouldn't be able to tell what was really happening.

But that page has been pulled from one of Apple's internet servers across the internet and brought down for the user. So that's one of the new features we've added. It was added to Mac OS 9 and it's something we're going to talk about a little bit later, some more. Why don't we go back to the Help Center.

and check out Mac Help again. And let's look for something to do with sound. What I want to show is how the Help Viewer searches 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 installed 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 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 book's installed in the Help Center, we'd be searching your book too.

Thanks, Jeff. So that's the Help Viewer. What do you think? If we go back to the slides, I want to talk a little bit more about some of those features you saw. The first one is integrating Internet-based content. The QuickTime Help book was an example of this. This is something new that we've added and it's a really powerful feature. It's something that Apple is going to be taking great advantage of in Mac OS X. Mac OS X is a great Internet client and as such is going to have partially-based Internet help.

and your help is wrong and nobody has even seen it yet. It's really a bummer.

You know, so my wife, I got to tell you, so my wife tells me that the reason I'm losing my hair is that I'm getting older, but I swear it's last-minute changes. If I could just get, like, Workman's Comp to pay for Rogaine, I'd be all set. 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 makes sure they can get the latest help all within the help viewer environment.

So let's talk about how this works. Now the help viewer always looks for content locally. That is, that's where it loads its files. 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 application's help folder. It finds the page it's looking for, so it opens it. But what if the page isn't there? Well, next, the help viewer will look in the help cache. The help cache contains help files that were recently downloaded from the internet.

If the page the help viewer is looking for is in the help cache, then it loads it from there. If it's not in the help cache, then it asks URL access to go to a remote internet mirror, retrieve the pages looking for, URL access brings that page and puts it in the help cache from which the help viewer loads it.

So what's happening behind the scenes is the help viewer is pre-appending the location it's looking for at each stage. Again, in the local situation, it's looking for my app help/page.html. It doesn't find it there. It pre-appends the location of the help cache, still looking for page.html. If it doesn't find it there, then it turns it into a URL and pre-appends the location where you said your internet content is stored. You tell us where the internet content is stored when you index the files, and we're going to cover that.

And that's what it passes off to URL access for it to retrieve for us. Now once a page is put in the help cache, it stays there for three days. This allows users to go back and look at it again, right, because they just looked at it. They might want to go back and review it. And they 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 files, 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's internet-based content. There's 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. And we're going to cover the first three in depth. We're going to talk about AppleScript 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 Lookup, which is also something new that we've added.

But I want to talk for a second here about the dynamic table of contents, because this is kind of a hidden feature, but it's unique and you might need it. So in the demo, there was the Help Center. And the Help Center contained three items-- Mac Help, QuickTime Help, and the Developer Center. Those items appeared in the 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 plug-ins 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 help for the things they've chosen to install. That's kind of what it does. If you want the details on how it works, that's all covered in the SDK, which we'll tell you about at the end.

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, as I think you've already realized, it's a great resource for you all. If you have questions about developing for Mac OS X, go there, type in your search term, browse around, get the information you need.

But secondly, it's important to note, because Apple is now using the Help Viewer and 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 in this format. We're solidly behind this, and we want you to join us in this effort.

So let's talk about AppleScript 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 have to be done frequently by users, automate them. It 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. You go to href, as you see on the bottom of the slide, which is a standard HTML link, but you give it a special URL, which is help colon run script. And you give it the path to your AppleScript, which has to be on the local hard disk. You can't run an AppleScript that's on the internet. And you can pass a parameter if you want to.

For example, in MacHelp we use this. We pass parameters for applications to open. We have one script that does it, and we just give it the parameters. That reduces the number of scripts we have and eliminates some testing for us. So AppleScript automations are a good thing to add to your help. It just makes your help a lot more interactive and usable.

Search results. Apple Help is all about searching. We've got a great search engine courtesy of Sherlock. You can type in a word, a phrase, a sentence, whatever you'd like. It 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 in 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 misspellings, just to make sure that people can get the results they're looking for.

In Mac Help, for example, when we're talking about QuickTime, we always keyword 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 noindex tag. This is robots equals noindex, common tag, and this will tell our search index to skip that page and not include it 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 can 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 Lookup. 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 it in the demo because we didn't want to make the demo too long, but it's really easy to explain.

Anchor is a standard HTML tag. You embed it in your HTML and you give a name for that anchor, such as foo. From within your application, say from a help button in a dialog, using our APIs, you tell the help viewer to open the page that contains the anchor foo. The application doesn't have to know what page that occurs on.

The help viewer 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. This is a new feature. I think you'll find it really handy.

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 help system is and how easy it is to use, but this is where the proof is in the pudding, so to speak. You could literally go from HTML to Apple Help in five minutes. We've worked 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 can 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 Help 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 is standard HTML. It isn'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 in some other help system. This meta tag is called Apple Title. And the contents of the meta tag is the name of your book. In this example, myapp.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 APIs.

That's all you have to do, is add that one tag to one page. The next step is to index it. We give you a drag-and-drop indexing tool. You take your folder of HTML, you drop it on the indexing tool, it quickly goes through and scans all of the content, pays attention to keywords, Apple abstracts, no index, and everything else it needs to look at. And it creates a search index file, which is a small file that 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 Lookup to provide contextual help, then you need to turn on a checkbox. But it's really as easy as that.

The next thing to do is to store your help. On Mac OS X, your application's help is stored within your applications bundle. You take your help folder, you put it in there with the rest of your other resources. If you have localized resources, that's great. You can have localized 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, heaven forbid, even throw it away, and they throw away the app and the help it wants. Nice feature. And on Mac OS X, 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 help center that's targeted to exactly what you can use. This is a cool feature.

So on the authoring side of things, you're done. You started with HTML, hopefully added some AppleScript enhancements, some keywords to make sure people can find their content, maybe decided some of it was going to be internet-based. And it's as simple as that. The next step is to get your application to open the Help Viewer at the appropriate time with the right content.

And to cover how to do that, it's not me, it's Miller time for me, I want to reintroduce The person responsible for bringing Apple Help to Mac OS X and the lead engineer for Apple Help, Jessica Kahn. Jessica? 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 going to be covering a little bit about some new help URLs that have been introduced in the Mac OS X 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 HTMLRenderingLib briefly, which is the underlying rendering technology for the help viewer, and you can use that in your application as well.

So here we are on 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 Apple Help, I want to see you adopt it because I want Mac OS X, in particular, to be awesome.

And part of Mac OS X 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 help content, but to make sure that they know how to get to that help content. And I think that if we're consistent with bringing them help content through the help 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 help solutions. Please consider not porting those custom help solutions. We've got a really easy solution for you, and I'm going to explain how easy it is now.

Okay, so first things first, as your application launches, you're going to want a help menu. And the way you get that help menu in Mac OS X is a little different than it has been in the past. But it's easy. For Carbon and Cocoa applications, we'll 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 help system, we understand that you need it to be customizable. In the simplest case, you've got one book of help content, and you just need a help menu with one item in it, 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.plist. I'm not sure if all of you know what an Info.plist is. Perhaps if you saw 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 a way on Mac OS X 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 CFBundle 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 been used in examples earlier today, inside of my Sketch.app 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 Praj, I could have a Sketch help.

And in my German, El Praj, 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 plist, you just have CFBundle help book folder with the corresponding key of Sketch help.

With that plist entry, 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 picks that item, we would go out and find the entry page for your help content.

That entry page is what Gordon discussed earlier where you put the meta tag for the Apple title. And for, I would guess, 98% of applications, this is about all you need to do to provide content for your users, particularly if you're using the help viewer since that content is going to be multifaceted as you want it to be with movies, AppleScript, and very searchable.

Alright, but there are some applications out there, I'll admit, that have very complicated help menus 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 with the 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 help content for your application, let's say you've got an app and it needs help and then you've got plug-ins and they need separate help for some reason, you can still use the CFBundle help book.

Book folder key in your P list, but instead of putting one string as your value, you can put an array of strings as your value. Each string will be the name of the folder for the different book. Once you do that, things 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 last thing.

If that is the route that you go, there's an API. It's one of the new Apple Help APIs, and it's called AHRegisterHelpBook. You need to call that if you have more than one help book, and you need to call it for each book. What it does is it places your book in the help center.

So you think, so what if my book's in the Help Center? I can get to it from my Help menu. That's all I need. Well, you lose out on a lot of the features of the Help 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 Help 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 help book and it's stored within your app bundle, again, your Info.plist should contain the key, CFBundle help book folder, and the string of the folder name that your help is stored in within your app bundle.

So we talked briefly about one of the Apple Help APIs, the Register Book API, but there are a number of others that help you customize either your help menu or if you have help buttons within your application. Their shipping is a help framework, which will be part of the Carbon umbrella, but it's not yet in DP4.

It will also be available in CarbonLib, so you can ship an application for CarbonLib running on 9.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 Cocoa apps. By nature of the fact that it's just a C API, you can link to the help framework and use these APIs.

So what are they? Well, the first one is registering a help book. And again, that puts your help book into the help center. Next, there are APIs that cause HelpViewer to open to a particular location. These are going to be the most common APIs that you're probably going to want to use. They are ah-go-to-main-toc, ah-go-to-page, and ah-lookup-anchor. And we'll discuss them in detail in a slide or two. And finally, there's an API for performing a search programmatically, and that's ah-search.

So examples. And at this point, I want to note that these examples work in DP4. So I want you to take your CD home and try start hooking up your help stuff. 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 ahgo2mainTOC. And you specify a constant there of which TOC you want. A TOC is a table of contents. And a main TOC would specify either the help center or the developer center that you saw in Gordon's demo earlier. So specify K-A-H-T-O-C type user to go to the Help Center or K-A-H-T-O-C type developer to go to the Developer Center.

All right, to go to the main page of your application's help book, which is probably the most common thing that you're going to want to do, you call ah-go-to-page. The first parameter there is a CFString representing the name of your book. 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 APIs that you see that we're requesting a book ID, the book ID is the Apple title.

So turn that into a CFString, 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 it's null. You don't ever have to. to supply an anchor to us in the AH GoToPage routine.

Finally, you can go to any HTML file on the disk and make sure that it opens in Help Viewer. You can also do that with the AH GoToPage. You see here that we use sort of a mix and match of the different parameters. They're optional and you can kind of combine them to make cool things happen. Here the book name is null because this file might have nothing to do with your book. You're specifying a file:URL that is the full path to the file on disk.

Here we have no anchor specified, but you could have an anchor specified. 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. Foo would be your anchor there.

The next type of help APIs are lookups and searches. Lookups 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 when 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 help 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 ahlookup anchor with the CFString of my book ID, again the Apple title, and a CFString of the anchor that I'm looking for. And provided that I've indexed my content for anchor lookup, Help Viewer takes care of figuring out what file that anchor's in and scrolling to the appropriate place in the file.

You can also perform a search of the help content either of your book only or of the entire help content installed on the system. Here you see ahsearch with a CFString 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 app, but you'd probably also find help about how to find files using Sherlock. The next one limits the search to just your book. And there you just specify the book ID, again the Apple title, and then the search string.

Okay, just to make sure that you guys understand this stuff, the anchor stuff without a demo is a little bit hard to get. 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 lookup. They called up help on a particular Carbon API, and it launched Help Viewer 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, and the HTML there again is the a name equals anchor. And then Help Viewer, when an anchor lookup was performed for get folder name, would open this page and scroll to that anchor.

So we have talked about the APIs, 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? They're for use from within your content to make that content more dynamic. They exploit the very same features of the help viewer as the APIs 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 help viewer to a specific location, they perform a search, and they run an AppleScript.

The first that we're going to talk about, open the help viewer to a particular location. First is the help go to help center. That is equivalent to the AH go to main TOC API. So here you specify help go to help center equals user to go to the help center and help go to help center developer to go to the developer center. 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 help 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 AH 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 link to that using a regular file colon URL to my main page? Why use the silly Help 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 Help 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. And that can be very useful. Next is the Help Anchor URL. Obviously, probably this is analogous to the Anchor lookup.

Again, I keep thinking with these APIs, when I was 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 until the very last second. So this is useful not when you're worrying about breaking your app, but it's useful when you're worried about breaking your other help content.

If you have a very complicated book, you might have 300 HTML files. If you have a complicated app and you've got a lot of help. So what if at 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 colon URL with an anchor appended, this will prevent mistakes like that.

And finally, this one's, 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 APIs. There's a help:fullpathtofile URL. So you're thinking, why on earth would I want to use this instead of a file:? 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 has set up your internet preferences properly for help:viewer to be the help: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 help:viewer that you would never want opened in Internet Explorer. For instance, something that might have run script URLs that launch Apple scripts. Thank you.

Finally, performing a search and running an AppleScript. You can put URLs for searches inside of your content. That's a help:search. 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:search, but it is a search from within content, so it'll get you thinking on why you might want to do this.

Look into the Mac Help book on your DP4 CD and you'll see that list of quick clicks. You'll notice when you click on them that that initiates a search for a particular term. Check that out and it'll get you thinking on why you might want to use these URLs. Then Gordon did a very good job of explaining what running an AppleScript is good for.

I'm just going to give a slightly more specific example for formatting purposes. You see that it's help:runScript=HELP. Then a path to your script, which is relative to your book's 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 APIs and we're done talking about the URLs. 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. 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 help viewer. On 10, it's shipped as the HTML rendering framework, which is a part of the Carbon umbrella in DP4. On Mac OS 9, it's still available as a non-carbon shared library, but it will also be available in CarbonLib.

What exactly is this thing 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 pane 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 Help 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 is a table within a table, it's got a font specified, it's got a colored table cell. It does some pretty interesting stuff.

Yeah, well, give me the details. Well, so it does HTML 3.2, which includes lists, frames, tables, images in 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 4.0. 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 4.0, it might be malformed HTML, it might be anything. That's not what it's great at. It's great at content that you design for it. You've seen it be great at rendering help content. It's also really good at item descriptions or item summaries. I'll show you in a demo in a minute, we use it in software update.

And you can also use it for advertisements. As I mentioned, you can have an about box, renders HTML, and 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 the rendering 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 DP4 inside of the system demos folder, I believe. 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. What have we here? It's found an update to Mac OS X. You guys think I could do that? Install Mac OS X right on here using software update? Well, let's see what it says about Mac OS X. This pane here is the rendering library. And you know, it's simpler than the help viewer content. That's because I am just not a web designer.

So what does this say? Let's see, Mac OS X has some great features, including a new version of the already excellent HTML rendering library. Did you guys know that? Before you update, consider a visit to the Apple Store to purchase a G4 and a cinema display, making X all the more enjoyable.

Don't I wish I had one? All right, 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. He's 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 and use it.

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 Help APIs is a little lacking, but we're working on it. We're working real hard. So for now, check out the System Library Framework's Help Framework.

You'll see the header there. You can get going. And I'll give you an email address to send questions to. For other general Apple Help information, including a link to the SDK that Gordon mentioned, that has a lot of interesting content authoring tips and lessons and neat 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/macos/help.html . And that's a good jumping off point for lots of information. And then for specific information on the HTMLRenderingLibrary, there's sample code. And I know that's a long URL, so I'll try to dawdle and make sure that you guys have time to copy it down. That's developer.apple.com/samplecode/Ssample_C ode/HumanInterfaceToolbox.htm.

And then there's also a PDF with documentation on each of the individual HTML rendering APIs and how to use them. And, well, I've been reading out all the other URLs. So developer.apple.com/techpubs.html. Mac OS 8. PDF. HTML_renderinglib.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.

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 AppleHelpComments. 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 content authors, and you can discuss with each other what you're doing, get answers. I'm not sure if it's monitored by Apple or not. Maybe Gordon would answer that question when he comes up here later. You can find that from lists.apple.com.

Finally, you can always communicate with John Galenzi. He is the User Experience Technology Manager, and he handles developer relations for our technology. That's galenzi, spelled G-E-L-E-Y-N-S-E, at apple.com. And with my giving his email address, I'll invite him back on stage, and he's going to take us through the roadmap and Q&A.

Thanks, Jessica. So let's just talk about the roadmap 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 APIs 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 sub-track, and it relates to you delivering really consistent and really rich user experience in your applications on 10. And, of course, the ever-famous or infamous Aqua Feedback Forum, which we're looking forward to your participation in.