WWDC2001 Session 137

Transcript

Kind: captions Language: en so my name is Tony Childress I'm director of tech pubs at Apple and what we're gonna 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 gonna do is we're gonna actually demo a range of content and how you access that we also have a surprise guest and I'm gonna save the guest until after the demo as added incentive to get to guys to you know recover from last night and stick around and hear what he has to say we were trying to provide documentation every way you like it and and based on feedback that we got from last year's WWDC and our feedback sessions we know that you want to have the material locally you know on your 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 gonna do we're gonna go through a couple of developer scenarios and these are generally applicable on how you would use the documentation to do do a task so we're gonna go through cocoa app development particularly using project builder and sort of hard core carbon porting and 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 which we're going to hold off till later so to do that I'm gonna I'm gonna introduce a couple of our writing managers here at Apple and I hope that they have recovered and sufficiently the first fella he's manages our cocoa and developer tools documentation his name is Matt Ralston and the second guy he manages our carbon and core technologies and that's Tony Francis we're gonna 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 you were at WWDC last year fair number okay 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 piece bits and pieces so it's available from fat brain 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's 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 for those of you porting your existing classic Mac applications you should get this book the brand new version of the Aqua 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 a hundred thousand copies of this book so we know you're paying attention this book has been updated now its final and it includes information 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 a hard copy version from fat brain comm and it'll be they'll have it to you in a couple of weeks or so if you order today alright 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 10 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 10 is got a lot of great features to it there's a lot of neat things there but performance is you know not 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 10 and to help you out with that we've got a book called inside Mac OS 10 performance I think we could come up with better names for some of these books Tony will work on that too anyways this is also available from fat brain on the website on the CD that you got with your WWC 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 Rowley I have a question for the audience how many of you made it to party last night that's a lot of fun you guys should come back more often that was a crazy how well the view 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 you hope you already got it at the O'Reilly booth here at the conference or you bought a copy from developer Depot while you're here a number of Apple riders with a lot of help from Apple engineering prepared this book because many of you requested in an introductory carbon programming guide so their system overview there is uh aqua human face 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 tech pubs also write about the down and dirty lowdown 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 huh how many of you are planning to start a carbon project in the near future yeah okay great well hopefully this will be of a 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 os10 developer tool 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 10 by the way Apple is planning to release periodic updates of the Mac OS 10 developer tool CD with updated documentation to register developers the developer tools CD that you got here at the conference's 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 10 development the developer Help Center is displayed by to help you application the help viewer is the built-in Mac os10 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 from 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 roller let's follow that link here you'll find the books the tools and the techno TARTA khals 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 porta guide is an essential resource for those of you bringing your Mac applications forward to 10 this book offers a cookbook list of changes to make your code carbon compliant it 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 tools 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 many of you have told us that you prefer to read hardcopy documentation at least part of the time in addition to setting the carbon porting guide to your printer you can also take it on disk to a reproduction service like a Kinkos 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 fat brain comm the carbon porting 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 the Mac os10 performance directly from the developer Help Center well let's return to the help viewer application where the carbon pouring tools 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 fat brain comm well as the carbon porting guide explains an essential first step and carbonizing application is to analyze it with the carbon data tool returning the help viewer will show you that we've provided a link to carbon data from this page the tool itself is not included on the CD you use in conjunction with the Apple developer website because we want to make sure that you always get the latest and greatest sporting information when you use carbon data 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'll veterans may remember is an old old sample application the DTS wrote years and years ago and the writer of the carbon porting guide used it as an example for reporting when the writer received his carbon compatibility report for traffic light he saw that among other unsupported functions the application was calling the old window manager function close window the carbon compatibility report noted the closed windows not supported because carbon applications don't allocate their own memory for windows the report noted that disposed window should be used in the place of close window if you receive this information your applications carbon compatibility report you'll probably want to look at the documentation for both close window and dispose window if you want to find the documentation for an API just ask for it last ask help viewer Raleigh 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 appeared in the compatibility report for traffic light these notes include the prescription to use disposed a window let's take a look at the documentation for disposed window we can also you look at the disposal window documentation help viewer but currently to help you or doesn't support multiple browser windows it would be really nice to be able to have a window open for both closing window and disposal window to compare the two so until help viewers 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 Raleigh and I will show you how when you installed the developer tool CD you get any 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 dot HTML let's open this file if this page looks remarkably similar the one displayed by help viewer that's because Internet Explorer is using the very same HTML source that helped viewer uses we can find a suppose 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 I like finding information this way it's 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 disposal window our window manager calls so to expedite our indexing tasks right now we'll index just human interface toolbox documentation by dragging its folder on to Sherlock and then Sherlock I'm 10 automatically indexes this for us after clicking the check box for this folder we're ready to search its contents Broly take a look at 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 the top of the list let's take a look at the documentation for disposal window we find that by dragging the result onto the ie icon and the doc we get a separate window and now we have two windows open so we can compare the two calls we you know send them a 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 suppose a window for closing window 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 that 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 so 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 is that developer.apple.com slash tech pub slash well just go to developer.apple.com and navigate your way down to our to our website this page looks very similar 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 well he's been sick recently he's been sick oh he could've been a minute sound allowed the fun he just looks on over he's never 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 last jump over the Mac os10 developer doc homepage what's more and then can I love it 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 if you will 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 some come by 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 go to the if you're not a registered developer and 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 Raleigh manages that effort so now he'll guide you through a few more of our documentation access features with your needs in mind thanks Tony 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 a search right we've got Sherlock 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 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 Justin carbon or Justin cocoa or just in QuickTime or whatever area of the documentation you're most interested in okay so how many of you are working on a cocoa application okay few of you how many of you are just learning cocoa okay a 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 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 okay 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 the center of your universe as you're developing because we have documentation on the hard drive that ships with Mac OS 10 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 want to 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 the quickly we've got you know 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 more complete for now that your best bet when learning specific things you know 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 the reference pages themselves the the actual spec sheets ok 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 with a new environment so to help out there we actually ship a whole bunch of example source code so we go into the finder go look in again the developer folder there's an examples directory underneath it and in there you'll find several different folders for different parts of the system app kit is the basic cocoa stuff the the well app kit is the user interface portion of cocoa Foundation 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 foundations the place to look if you're interested in some of the GUI widgets app kit is the place that has examples there are a whole bunch of really interesting examples some of them very very complete sketch for example as 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 so we go and double click on rulers PB proj it goes ahead and opens up in project builder and from here you can use project builders 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 a 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 is this you know what 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 main bundle equals NS bundle main bundle so first of all what what exactly is NS bundle let's see if there's documentation on that so you go to the find menu and you see there's this nice menu items said find selected definition go ahead and select that it does a fine 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 NS bundle but for now let's look at the main NS bundle class so we see we've got the header file and s bundle dot H and right next to it there's this little book I 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 NS bundle reference sheet in help your and you can go through and read you know all the different documentation that's available there okay let's go back to project builder mmm-hmm now let's say that I'm interested in one specific method on NS bundle so here we're calling NS bundle 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 CF bundle get main bundle which is sort of interesting but for now let's take a look at the NS bundle 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 you're searching in project builder API look up documentation available on your local disk on the website from 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 Tony great so to summarize you got to get a hold of these key titles okay if you're new to the ten platform and get oriented with a system overview book it's been updated get the Aqua hIgG 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 and you can tell it's coming here so I hope you're as pleased as I am and as Apple isn't and as we all are that O'Reilly has decided to move into the Macintosh developer market you know Oh Riley is probably the most well respected publisher of developer books in the universe you know they're they're incredibly strong in in open source and java and unix where there's a lot of interest around mac OS 10 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 [Applause] good morning my name is troy mana I'm an executive editor at O'Reilly 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 os10 and a little bit of how we edit books and also about the cirali Apple Agreement and some of the products we're creating many of you may know Riley associates is and where information we deliver information technology when 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 conference's division and a good example of that is the open source convention that we're hosting in July this year for websites there's a Riley comm and we also have a Riley Nick network where we have a Mac dev Center which is a collection of all sorts of information and articles on Mac os10 which you can find at a rally Netcom slash Mac we even have a new product called Safari which is a subscription-based service for online or Riley books for more information on any of this you can go to the riley book booth over in the internet cafe if you haven't been there already so first of all you know what are we five interest with OS 10 of course the coupling of the the stability of UNIX with the beauty of aquas is very compelling and we're also very interested in the open source nature of the Darwin kernel O'Reilly 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 os10 developers you know the way we work at a toilet 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 a group of authors even involved in some levels the book going through production and marketing and work with product marketing managers so what is the Riley Apple agreement all about basically we're in delivering a new series of Mac OS 10 developer books these books are reviewed by Apple engineers and also recommended by Apple Developer connection so any books in this series will have the ADC logo which if you've seen I'm sure you've seen the cocoa or carbon books you see the the logo on the front the spine and back cover and you know I actually edited these two books and it was a pleasure for me working with Apple who actually authored these two books we 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 and 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 gonna be a great resource for you guys you know out there you're gonna be able to go into a bookstore now and not have to look for a Mac book on the shelf right you know we're now gonna have Mac books on the shelf in the bookstore along with all the windows stuff so I hope you got one of your books here and and this is gonna be a great great thing for you guys okay a little bit about staying up to date and and Rowling and Tony 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 doc we put it up there regularly it's it's a hassle to do that so so like Tony says join the free ad c-- 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 just join The Selecter premier programs you know get get yourself in a position so you can be eligible for seeding programs where we do pre-release documentation that gets out to you guys earlier you know then the final stuff that gets published so that's a good way to so we're working on more content fixing some bugs in the in the material and and working to improve the local access and I'd like to say a little bit about that Tony and Raleigh demoed the Apple help center which is our viewing mechanism on 10:00 now for for viewing developer documentation it's not yet feature complete for features that developers would want to 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 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 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 two 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 1 way to give us feedback then we also have a feedback link on the website which is where we get a lot a lot of comments from you folks so please keep them coming and then a roadmap there's 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 header doc tool for creating documentation and I think this is actually a problem we brought her interest then 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 gonna find that the Darwin site is a good resource for you for technical material as well so you know you might think about caching caching this session it's coming right up you