So, my name is Toni Childress. I'm Director of Tech Pubs at Apple. And what we're going to do today is show you how you can effectively use the documentation to do your job, okay, in the tasks that you do as developers. So, what we're going to do is we're going to actually demo a range of content and how you access that.

We also have a surprise guest, and I'm going to save the guest until after the demo as added incentive to get you guys to, you know, recover from last night and stick around and hear what he has to say. We're trying to provide documentation every way you like it. And based on feedback that we got from last year's WPBs, we know that you want to have the material locally, you know, on your hard disk. You want to have it integrated with your development environment.

When you go to the web, you want to have quick and easy searching. You know, you want to have printed books and so forth. So, we've been working really hard to put in place procedures to author and publish and deliver documentation so that I think that we can deliver it to you every way you like it.

And where we can't, we're partnering with third parties to be able to do it. So, here's what we're going to do. We're going to go through a couple of developer scenarios. And these are generally applicable on how you would use the documentation to do a task. So, we're going to go through Cocoa app development, particularly using Project Builder and sort of hardcore Carbon porting.

and here's what you'll learn. Key document titles. These are titles that everyone should have, you know, on your bookshelf or your virtual bookshelf. The easiest way to access them, using Project Builder to search API reference in particular, okay? And then our newest venue, which we're going to hold off until later.

So to do that, I'm going to introduce a couple of our writing managers here at Apple, and I hope that they have recovered sufficiently. The first fellow, he manages our Cocoa and Developer Tools documentation. His name is Matt Rollefsson. And the second guy, he manages our Carbon and Core Technologies, and that's Tony Francis.

So we're going to take you through a few developer scenarios, some typical ways you might access documentation. But before we do that, I want to talk a little bit about some key titles that we've come out in the past little while. So how many of you were at WWDC last year? see last year.

Fair number. So you all received, at that point, a preliminary version of the system overview book. So what do you think of that book? Helpful? Not helpful? Thumbs up, thumbs down, don't care? Who read it? Okay, at least people read it. Hopefully you found it helpful. In the time since then, we've come out with a revised version. It is no longer marked as preliminary. It is a good bit thicker than it used to be.

And it's got updated information about localization, booting, integration, and various other bits and pieces. So it's available from Fatbrain in this form. You can also get it on our website in HTML and PDF. And it's also available on your CD. So, Tony, I think you've got a book that people might be interested in. Sure. One thing that every application developer needs to consider, whether you're developing a Cocoa application, Java, or Carbon application, is the user interface for your application. So those of you with new applications, or those of you porting your existing classic Mac applications, you should get this book.

The brand new version of the AquaHuman Interface Guidelines became available in the middle of this week. We released an earlier version of this, a preliminary draft, in January, and a bunch of you downloaded 100,000 copies of this book, so we know you're paying attention. This book has been updated now, it's final, and it includes some additional information about creating icons, and there's a new chapter on user domain directories.

There's more information about localization and accessibility, and a lot of additional illustrations. You can find this book and download it for free at developer.apple.com or as you can see here, it's also available in hard copy version from fatbrain.com. And it'll be, they'll have it to you in a couple of weeks or so, if you order it today.

All right, I've got one more title I think you guys might be somewhat interested in. So how many of you have code running on Mac OS X right now? How many of you wish that that code would run faster? So one thing that we've heard from folks pretty consistently is that Mac OS X's got a lot of great features to it. There's a lot of neat things there, but performance is not as good as it could be and not as good as it needs to be.

Now there's some things that we can do to improve that, and we're working really hard on those. But there are also things that you can do to make your applications run as fast as possible on Mac OS. And to help you out with that, we've got a book called Inside Mac OS X Performance. Think we could come up with better names for some of these books, Toni? We'll work on that too.

Anyways, this is also available from Fatbrain on the website, on the CD that you got with your WWDC materials. So take a look at it. Use those tips. Make your code run great. And hopefully we will all have a lot of really spiffy applications for customers to go out and buy. Raleigh, I have a question for the audience.

How many of you made it to the party last night? Yeah, that was a lot of fun. You guys should come back more often. That was great. Of you all, how many of you are creating brand new Carbon applications? A few of you, huh? Then I hope you'll be sure to read the new Learning Carbon book from O'Reilly. I hope you already got it at the O'Reilly booth here at the conference, or you bought a copy from Developer Depot while you were here.

A number of Apple writers with a lot of help from Apple engineering prepared this book because many of you requested an introductory Carbon Programming Guide. So there's System Overview, there is AquaHuman Interface Guidelines, the Performance Book, Learning Carbon. These are some of the books that we've completed since we all met last year at WWDC.

Besides writing these high-level guides, we at TechPubs also write about the down and dirty, low down, delta singing API documentation that you need to get your job done. My writing group, in particular, has been busy documenting Carbon porting information. So how many of you out there are actively carbonizing your code? How many of you are planning to start a Carbon project in the near future? Okay, great. Well, hopefully this will be of particular interest to you. Raleigh and I will show you how to get the information you need to carbonize your application. First, let's take a look at what you got on your Mac OS X Developer Tools CD.

Here at the conference, many of you have told us that you want documentation local to your system. So we're supplying all of our developer documentation as part of the Developer Tools CD, distributed with every copy of Mac OS X. By the way, Apple is planning to release periodic updates of the Mac OS X Developer Tools CD with updated documentation to registered developers. The Developer Tools CD that you got here at the conference is the first installment of this update series.

When you install the packages on the Developer Tools CD, you get a bunch of great programming tools and the Developer Help Center. The Developer Help Center provides all of the documentation that Apple supplies for Mac OS X development. The Developer Help Center is displayed by the Help Viewer application. The Help Viewer is the built-in Mac OS X facility for displaying on-screen help. Let's take a look at the Carbon area.

From the Carbon Developer Documentation page, you gain access to over 20,000 pages of documentation for nearly 100 Carbon-compatible managers. As you can see, this page is organized by topic. We try to make all of our books available in both PDF and HTML. Now, we don't have all of our books in both formats yet, but we're getting there. Notice the Related Resources banner at the top of the page. Under this topic, there's a link to the Carbon Porting Tools and information. Rolle, let's follow that link.

Here you'll find the books, the tools, and the TechNote articles that are particularly valuable to your porting efforts. Let's take a closer look at the Carbon Porting Guide. Clicking the link for this particular title opens a PDF formatted version of the book. The Carbon Porting Guide is an essential resource for those of you bringing your Mac applications forward to X. This book offers a cookbook list of changes to make your code Carbon compliant and offers step-by-step explanations of how to port a sample application and offers an example of how to adopt the new Carbon event model.

The book is available on your developer tool CD for you to read online, but the main reason we make documents available in PDF format is so that you can print them. Many of you have told us that you prefer to read hard copy documentation, at least part of the time. In addition to sending the Carbon Porting Guide to your printer, you can also take it on disk to a reproduction service like a Kinko's and they'll print it for you.

So many of you have asked us to print the documentation for you. Well, we've made the selected documents available as bound books through fatbrain.com. The Carbon Reporting Guide is one of these titles. You can link to order forms for this and other important developer books, like the Human Interface Guidelines and Mac OS X Performance, directly from the Developer Help Center.

Well, let's return to the Help Viewer application, where the Carbon Porting Tools and Information page is displayed. Right here, you'll find a link to order that book from Fat Brain. Click here, and if you're connected to the internet, you'll go directly to the order page at fatbrain.com. Well, as the Carbon Reporting Guide explains, an essential first step in carbonizing an application is to analyze it with the Carbon Dator tool. Returning to the Help Viewer, we'll show you that we've provided a link to Carbon Dator from this page.

The tool itself is not included on the CD. You use it in conjunction with the Apple developer website because we want to make sure that you always get the latest and greatest porting information. When you use CarbonDater, it will produce an HTML Carbon compatibility report for your application. This customized document lists function calls and code usage from your application that you may need to change, along with suggestions about how to make those changes.

So here's an example of the first page of the Carbon Compatibility Report for Traffic Light. The Traffic Light application is used as a porting example in the porting guide. Traffic Light, some of you veterans may remember, is an old, old sample application that DTS wrote years and years ago. And the writer of the Carbon Porting Guide used it as an example for porting.

When the writer received his Carbon Compatibility Report for Traffic Light, he saw that among other unsupported functions, the application was calling the old WindowManager function "CloseWindow." The Carbon Compatibility Report noted that "CloseWindow" is not supported because Carbon applications don't allocate their own memory for Windows. The Report noted that "DisposeWindow" should be used in the place of "CloseWindow." If you receive this information in your application's Carbon Compatibility Report, you'll probably want to look at the documentation for both Close Window and Dispose Window.

If you want to find documentation for an API, just ask for it. Last ask help viewer, O'Reilly, for the documentation for closed window. The Help Viewer application returns a list of search hits, ranked by relevancy. This search facility works for the rest of the API documentation on your tool CD. Documentation for Cocoa, QuickTime, Core Technologies, and so forth.

Clicking the most relevant link takes us to the formal reference documentation for Close Window. You see that this function is tagged as unsupported in Carbon. As you scroll to the bottom of the page for Close Window, we see the Carbon porting notes. These notes also appear in the compatibility report for Traffic Light. These notes include the prescription to use Dispose Window. Let's take a look at the documentation for Dispose Window.

We can also look at the Dispose Window documentation in Help Viewer. But currently, Help Viewer doesn't support multiple browser windows. It would be really nice to be able to have a window open for both Close Window and Dispose Window to compare the two. So until Help Viewer supports multiple windows, most of us use a web browser when we're intensively studying API documentation like this. In case you're not already doing this, O'Reilly and I will show you how.

When you install the Developer Tools CD, you get a Developer folder. Inside that folder is a Documentation folder. There you'll find all the developer documentation that's in the Developer Help Center. Let's take a look at the Carbon folder. You'll see that it contains additional folders and a single HTML file, Carbon.html. Let's open this file.

If this page looks remarkably similar to the one displayed by Help Viewer, that's because Internet Explorer is using the very same HTML source that Help Viewer uses. We can find a exposed window by going to the function index under the site information banner at the top of the page and then navigating down to the relevant documentation.

But, forget it, Raleigh, finding information this way is kind of pokey. Browsers don't return the type of rapid search results that we saw help viewer return. Sherlock does, however. So let's quickly index a portion of the Carbon developer documentation and use Sherlock to find what we're looking for.

Raleigh and I happen to know that Close Window and Dispose Window are window manager calls. So to expedite our indexing task, right now we'll index just the Human Interface Toolbox documentation by dragging its folder onto Sherlock. And then Sherlock on 10 automatically indexes this for us. After clicking the checkbox for this folder, we're ready to search its contents. "Rolley, take a look at the close window." We've tagged these guys so that the API reference page automatically becomes the most relevant hit for you. So it's always at the top of the list. Let's take a look at the documentation for Dispose Window.

We find that by dragging the result onto the IE icon in the dock, we get a separate window. And now we have two windows open, so we can compare the two calls. We, uh... You need a cinema display so you can really see them next to each other.

We see that the functions are very similar. Both take the same window reference as a parameter. And so we can see that substituting disposeWindow for closeWindow will be a piece of cake. So now you know that we have tens of thousands of pages of Carbon documentation available for you on your system in an easily searchable form. And thousands of pages are also there that you can print. And if you don't want to print a document yourself, Fat Brain will gladly do it for you.

However, many of you also want the absolute latest documentation. Because while we're periodically updating the CD, many of you can't stand to use stale, two-month-old documentation. Well, it's our mission to give you documentation every way you want it. And if you want it timely, you'll be glad to know that we update our website just about daily.

Let's look at the Carbon Developer Documentation website then. It's at developer.apple.com/techpub/well, just go to developer.apple.com and navigate your way down to our website. This page looks very similar to the one that you saw in the developer center on your disk. That's because we basically take a snapshot of our website the day that we submit our content to the CD. But by the next day, we're already updating the website. Let's see what's new to this site.

Have you seen this, Raleigh? Raleigh's been sick all week. Not recently. He's been sick all week. He's been missing out on a lot of the fun. He just looks hungover. He's not really hungover. So if you look at new and updated documentation from the Carbon page, you'll see that we see a list of the documents that have been added and revised so far this month. Let's jump over to the Mac OS X Developer Doc home page.

and we'll look at the new Core Technologies page. We just added this in the middle of the week. From this page you'll find links to some Quartz 2D documentation. In particular we have a brand new document that's really nice. It's called Drawing with Quartz 2D. You'll also find documentation here, a bunch of printing documentation. And we'll also be adding some core audio and image capture documentation here soon.

So come back periodically and check out our site. Better yet, become a registered Apple developer and we'll tell you what's new. You'll receive a notification of new and updated documentation automatically through a weekly email newsletter. If you're not a registered developer, go to the ADC booth here in the Internet Cafe and join.

There's always the free online program that will get you this email newsletter to let you know what documentation is new. And, hey, it's free. You might as well join, huh? I hope this has given those of you starting your Carbon porting efforts some help on where and how to find the documentation you need. Plus, consider those of you interested in Cocoa documentation.

Rolle manages that effort, so now he'll guide you through a few more of our documentation access features with your needs in mind. Thanks, Toni. So one of the things that we didn't go over that you might find useful, especially when accessing the website, is that we've got-- Apple search, right? We've got Sherlock plugin. We've got plugins that you can download that will allow you to do custom Sherlock searches of the website, you know, getting relevant hits for the specific area that you're interested in.

So the search functionality is available on the website, but the default just searches all of the area. You can download these Sherlock plugins, which are--we've got links scattered at strategic areas on our site. And you can use those to search just in Carbon or just in Cocoa or just in QuickTime or whatever area of the documentation you're most interested in. Okay.

How many of you are working on a Cocoa application? Okay, a few of you. How many of you are just learning Cocoa? whole bunch. So, in order to help you sort of get your feet wet, I imagine you have already seen this book and picked a copy up.

We wrote this book to try and give people a good start and introduction to all of the different parts of Cocoa. A nice tutorial, really hands on introduction of how do I use this stuff? How do I get my head around it? So, we hope that you find that extremely useful as you're coming up to speed on Cocoa and then you'll start diving down into some more of the specific reference material that we've got.

So, Toni, let's take a look at Project Builder and see what Project Builder looks like. So Project Builder is the integrated development environment that's provided by Apple for your use. And as such, it's pretty much the center of your universe as you're developing. Because we have documentation on the hard drive that ships with Mac OS X, and because we write the IDE, we can take advantage of some integrations between the environment you're using to develop and the documentation. So if we just look in Project Builder, it's got a help menu. And it has links not only to online help about Project Builder itself, but also to the different technology areas that we might be interested in. So let's take a look first at Cocoa Help.

So when you click on Cocoa Help, Project Builder brings up Help Viewer, brings us to the Cocoa Documentation home page. You'll see that the Cocoa home page is designed very much like the Carbon home page and all of the other home pages that we have. This is not an accident. We want to make it as easy as possible for you to get oriented to the pages and understand where you are so you can access things quickly.

We've got site information, getting started, related resources, and then reference documentation, programming topics, what have you. So, down in the programming topics area, we have conceptual material that is related to the material in the API reference. Now you may find as you're looking through this documentation that it is not complete yet. We've been working on it.

We will continue to flesh it out and look for updates over the next several months that will be more and more complete. For now, your best bet when learning specific things, when trying to get a general idea of what's going on, is to check out this book for specifics. You can come here. You can also check out the reference pages themselves, the actual spec sheets. Okay. No.

So, documentation is great. Tutorial information helps you get up to speed. Documentation gives you an idea of what you need. But sometimes you've got a specific problem and the documentation doesn't directly tell you how to address that specific problem. It tells you how to do lots and lots of different things with a class, but it doesn't necessarily show you exactly what do I need to do in order to say animate a progress bar and just display it. So, for things like this, source code can often be your best friend. And examples are a really good way of seeing how to do very specific things.

and the rest of the Mac OS X development team. The Mac OS X Documentation is the underlying foundation, if you will, portion of Cocoa, where you have things like strings and Unicode support and collections, arrays, dictionaries, what have you. So, if you're interested in how that stuff works and seeing some examples, Foundation's the place to look. If you're interested in some of the GUI widgets, AppKit is the place that has examples. There are a whole bunch of really interesting examples, some of them very, very complete. Sketch, for example, is a demonstration.

Drawing application. And it's got a whole lot of information in it. For now, let's take a look at a somewhat more simple one, which is Rulers. We go and double click on rulers.pbproj. It goes ahead and opens up in Project Builder. And from here you can use Project Builder's normal browsing abilities to take a look through the source code.

So another integration between Project Builder and our documentation is API reference lookup. So Project Builder knows where the documentation is located and also what form it takes in your source code. So if you go ahead and index your project, Project Builder understands is this a class? Is this a method? What is this particular symbol? And it can then go and ask Help Viewer to display the documentation for that symbol, if it's available. So if we scroll down here, we see there's this interesting line, mainBundle equals NSBundle mainBundle.

So first of all, what exactly is NSBundle? Let's see if there's documentation on that. So you go to the Find menu, and you see there's this nice menu item that said Find Selected Definition. Go ahead and select that. It does a find for us, finds a whole bunch of different results, showing one of the interesting features of Objective-C, which is categories, where there are categories that come from different source files that actually extend NSBundle.

But for now, let's look at the main NSBundle. So we see we've got the header file, NSBundle.h, and right next to it, there's this little book icon. That book icon indicates that Project Builder knows that there's some help documentation available for this. So if we click on that icon, it brings up the NSBundle reference sheet in Help Viewer.

And you can go through and read all the different documentation that's available there. OK, let's go back to Project Builder. Now let's say that I'm interested in one specific method on NSBundle. So here we're calling NSBundle main bundle. I want to know what does that do. Again, I go, say, find selected definition. Comes back, tells me-- actually, with a couple of hits, there's a function, CFBundle get main bundle, which is sort of interesting. But for now, let's take a look at the NSBundle actual method. So again, we click on the book icon. It scrolls us directly to that method.

Alright. So, that's a quick overview of some of the ways that you can access our documentation. We've got reference material, we've got conceptual material, we have tutorials, and we've got searching in Help Viewer, searching in Project Builder, API Lookup, documentation available on your local disk, on the website, in hard copy from Frat Brain, and also now in hard copy from O'Reilly. So, hopefully we're getting the documentation to you, whichever way you want it, and it'll help you get your job done. Thanks very much, Toni.

Great. So, to summarize, you've got to get a hold of these key titles, okay? If you're new to the 10 platform, get oriented with the system overview book. It's been updated. Get the Aqua Hig. You know, get one of the new tutorials. You know, if you're into Carbon porting, I hope you started with a Carbon porting guide. You know, no matter what you're doing, you know, where you are in your development cycle, get the new performance book because that's really cool. You know, on the developer CD that we shipped in March, there was over 200 megabytes of material on it.

There's more than that on the CD that you got here at the conference, and there's even more on the website. As you can see, we're putting stuff up sort of weekly. So, there's lots of material out there for you. You can access a lot of different ways. Don't forget searching from Project Builder.

And lastly, I want to talk a little bit about O'Reilly, and you can tell what's coming here. So... I hope you're as pleased as I am. And as Apple is, and as we all are, that O'Reilly has decided to move into the Macintosh developer market. You know, O'Reilly is probably the most well-respected publisher of developer books.

In the universe, you know. They're incredibly strong in open source and Java and Unix, where there's a lot of interest around Mac OS X. So it's my very great pleasure to introduce Troy Mott. He's the executive editor at O'Reilly and Associates, and he's going to talk a little bit more about what it means to you guys to have them, you know, join the Mac developer community in the way of resources for you in the future and a little bit about our relationship with them. Okay, Troy.

Good morning. My name is Troy Mott. I'm an executive editor at O'Reilly and Associates. I'm here this morning to tell you a little bit about who we are, what we do, why we're interested in Mac OS X, and a little bit of how we edit books, and also about this O'Reilly-Apple agreement and some of the products we're creating.

As many of you may know, O'Reilly and Associates is where information, we deliver information technology, and we communicate expert knowledge through books, conferences, and websites. Our books, of course, most of them have the animals on the cover, and we've covered technologies such as Unix, Linux, Java, Perl, and many others.

We also have a conferences division, and a good example of that is the open source convention that we're hosting in July of this year. For our websites, there's O'Reilly.com, and we also have an O'Reilly Network, where we have a Mac Dev Center, which is a collection of all sorts of information and articles on Mac OS X, which you can find at O'ReillyNet.com slash Mac. We even have a new product called Safari, which is a subscription-based service for online O'Reilly books. For more information on any of this, you can go to the O'Reilly booth over in the Internet Cafe, if you haven't been there already.

So first of all, what do we find of interest with OS X? Of course, the coupling of the stability of Unix with the beauty of Aqua is very compelling. We're also very interested in the open source nature of the Darwin kernel. O'Reilly and Associates has published a lot of documentation to the open source community, and Tim O'Reilly is very involved in the different communities.

So our goal now is to deliver the same high level of content to Mac OS X developers. You know, the way we work editorially at O'Reilly is a little bit unique for the industry. Our editors are involved in all stages of the process from acquisitions to the developing of content, working closely with an author or group of authors. Even involved in some levels of the book going through production and marketing. We work with product marketing managers.

So, what is the O'Reilly-Apple Agreement all about? Basically, we're delivering a new series of Mac OS X developer books. These books are reviewed by Apple engineers and also recommended by Apple Developer Connection. So any books in this series have the ADC logo, which if you've seen, I'm sure you've seen the Cocoa or Carbon books, you see the logo on the front, the spine, and back cover.

I actually edited these two books and it was a pleasure for me working with Apple who actually authored these two books. The next book coming up in this series is titled Apple Script in a Nutshell by Bruce Perry and that will be released in a couple of weeks. I'm excited also about that title. I look forward to fielding any questions or hearing any comments in the Q&A session, part of the session, you know, following. And thank you very much for your time.

So, these are the two books that are available now. There's new books coming up. This is going to be a great resource for you guys, you know, out there. You're going to be able to go into a bookstore now and not have to look for a MacBook on the shelf, right? You know? We're now going to have MacBooks on the shelf in the bookstore along with all the Windows stuff. So I hope you got one of your books here. And this is going to be a great thing for you guys.

Okay, a little bit about staying up to date, and Raleigh and Toni talked about this. We're working like crazy on getting this content for the new operating system, but there's still stuff to do. So check the ADC website for new and updated documentation. We put it up there regularly. It's a hassle to do that, so like Toni says, join the free ADC news subscription thing, because that's where we list the titles that came out that week, and it's an easy way to know what's new.

And just join the selector premier programs. You know, get yourself in a position so you can be eligible for seating programs, where we do pre-release documentation that gets out to you guys earlier, you know, than the final stuff that gets published. So that's a good way, too. So we're working on more content, fixing some bugs in the material, and working to improve the local access. And I'd like to say a little bit about that.

Toni and Raleigh demoed the Apple Help Center, which is... our viewing mechanism on 10 now for viewing developer documentation. It's not yet feature complete for features that developers would want to use it, you know. So if you caught any of the Project Builder sessions, you know that we're working on integrating documentation viewing more closely into Project Builder itself. And, in fact, we have a demo running downstairs in the lab.

If you haven't checked it out, you should go down there and give us some feedback, where you can see some of the features that we're looking at to provide, you know, as far as viewing features, like the ability to bring up to Windows, a fine panel that lets you search down through a page, copy and paste, you know, man pages in HTML, that kind of stuff that's really tailored to a developer audience. So if you haven't checked out that demo and given us some feedback on those features, please do.

Okay, that's the lab, one way to give us feedback. Then we also have a feedback link on the website, which is where we get a lot of comments from you folks, so please keep them coming. And then a roadmap. There's a really interesting session coming up right after this one on the Darwin Documentation Project, contributing documentation to the Darwin Project using the HedrDoc tool for creating documentation. And I think this is actually of probably broader interest than you might think.

I really recommend that you go to it. For example, if you're doing driver development or I/O Kit or something like that, I think you're going to find that the Darwin site is a good resource for you for technical materials as well. So, you know, you might think about catching this session. It's coming right up.