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