Lập trình Wrox Professional Xcode 3 cho Mac OS part 27 pptx

12 Help and Documentation WHAT'S IN THIS CHAPTER? Browsing the Xcode, API, and developer documentation Searching for symbols, topics, and keywords Navigating help documentation Learning handy help shortcuts Using quick help to get fast answers Installing new documentation sets and keep them up to date Modern operating systems are staggering in their size and complexity. The sheer quantity of application program interfaces (APIs) available to a developer can be overwhelming at times. There are scores of frameworks and libraries, each consisting of literally thousands of classes, methods, functions, and constants. Often, just fi nding the correct method or constant can be your most diffi cult programming task. To help you navigate this jungle of symbols, Xcode provides integrated help and documentation. You can browse and search developer documentation. All of the major APIs are indexed, allowing you to call up the documentation for any symbol almost instantly. This chapter gives you an overview of what help resources are available, shows you how to navigate the documentation, and explores a number of different search techniques. A lot of the documentation features are nice to know but aren ’ t critical for day - to - day development. If you want just the essentials from this chapter, read the following sections: Navigating Documentation Searching Documentation Documentation Shortcuts ➤ ➤ ➤ ➤ ➤ ➤ ➤ ➤ ➤ c12.indd 207c12.indd 207 1/21/10 3:30:33 PM1/21/10 3:30:33 PM Download at getcoolebook.com 208 ❘ CHAPTER 12 HELP AND DOCUMENTATION The documentation provided with Xcode, along with additional material available through subscription, include: API Reference Documents Technology Guides Developer Articles Technical Notes and Q & As Release Notes Sample Code While programming, you ’ re most likely to be using the API reference documents. These are the documents that describe the details of each individual class, method, function, and constant. You ’ ll normally fi nd these by searching or using one of the documentation shortcuts. When you ’ re just getting started or learning a new technology, the guides and articles are the best place to begin. Find these by browsing the documentation sets. You can also browse the documentation sets for technical notes, release notes, and technical Q & As, but you ’ re more likely to fi nd them when searching or through a link from another article. Xcode used to include numerous sample projects as part of the Xcode tools installation. Now, those sample projects — and many more — have references in the documentation sets, but the actual project code must be downloaded. See the “ Sample Projects ” section later in this chapter. THE DOCUMENTATION WINDOW The main interface for all Xcode help is the Help and Documentation window, shown in Figure 12 - 1, which this chapter refers to simply as the help window . You have various ways of opening it, but the simplest is to choose the Help ➪ Developer Documentation (Command+Option+Shift+?) command. Most of the other commands in the Help menu — Help ➪ Xcode Help (Command+Shift+?), Help ➪ Xcode Quick Start, and Help ➪ Xcode Release Notes — all open the help window to some predetermined content; these are essentially built - in bookmarks. If you’ve used the help window in earlier versions of Xcode, you may fi nd the new one somewhat perplexing. It’s actually a substantial improvement and has a pleasantly simplifi ed interface. The help window, shown in Figure 12 - 1, has three basic parts. At the top is the help window ’ s toolbar. It contains some essential controls, so make sure it ’ s visible or your interactions with the help window will be extremely limited. The main pane that occupies most of the lower - right portion of the window is the documentation browser. It ’ s a WebKit view and acts much like any standard web browser. ➤ ➤ ➤ ➤ ➤ ➤ c12.indd 208c12.indd 208 1/21/10 3:30:36 PM1/21/10 3:30:36 PM Download at getcoolebook.com The search control bar underneath the toolbar, and the search results sidebar to the left, appear only when you are searching the documentation. The help window has two basic modes: browse only and search. When you enter any search term into the toolbar search fi eld, the search control bar and search results sidebar appear. Clear the search term and they disappear again. There ’ s a special search tool for looking up the “ man ” (manual) pages that are part of the BSD operating system. It has its own command and toolbar control (see Figure 12 - 2). Man page searches are described in the “ Man Pages ” section, later in this chapter. It ’ s possible to create more than one help window by opening a link in a new Xcode help window. See the section “ External Links ” to learn how. Browsing Documentation The easiest way to use the help window is as a browser. Like any browser, you need a place to start and Xcode provides several: Most of the Help menu items load preset documentation pages The “ Home ” page for each of the documentation sets Bookmarks Help ➪ Xcode Quick Start is a great place to start in general. For questions about Xcode itself, the Help menu provides direct links to Xcode ’ s documentation (Help ➪ Xcode Help), and the latest release notes (Help ➪ Xcode Release Notes). ➤ ➤ ➤ FIGURE 12 - 1 The Documentation Window ❘ 209 c12.indd 209c12.indd 209 1/21/10 3:30:47 PM1/21/10 3:30:47 PM Download at getcoolebook.com 210 ❘ CHAPTER 12 HELP AND DOCUMENTATION Each documentation set you install — see the “ Managing Subscriptions ” section later in this chapter — appears in the toolbar ’ s Home pop - up menu, as shown in Figure 12 - 2. FIGURE 12 - 2 If you want to explore the documentation of a particular operating system or technology, start at its home page. Over the years, most of the articles, technical notes, and other introductory material available from Apple ’ s developer web site has migrated into the Xcode documentation sets — in much the same form. Bookmarks are described later in the “ Bookmarks ” section. Navigating Help Documents As mentioned, the documentation browser is essentially a web page browser, so all of the standard elements (links, images, embedded video, scrolling) all work exactly as you would expect. The help window only adds two features to the browser: history and bookmarks. The back (Command+[) and forward (Command+]) history buttons are in the toolbar and act as you would expect them to. All other navigation is provided by the content of the documentation pages themselves — mostly via HTML and JavaScript. Thus, the organization and navigation of pages changes depending on the kind of documents at which you ’ re looking, and can evolve as the documentation content is updated. As of this writing, there are a couple of consistent themes. The document home pages or collection pages, as was shown in Figure 12 - 2, tend to list related documents and often have a table of contents on the left that let you jump to different sections. Some even have search, fi lter, and sorting features, like that shown in Figure 12 - 3. c12.indd 210c12.indd 210 1/21/10 3:30:47 PM1/21/10 3:30:47 PM Download at getcoolebook.com The API documentation, as shown in Figure 12 - 4, adds a number of navigation tools. The navigation bar across the top lets you toggle the table of contents for the group of documents. The table of contents contains links that jump to various sections and related documents. It often contains high - level section titles that can be individually expanded or collapsed. FIGURE 12 - 3 FIGURE 12 - 4 The Documentation Window ❘ 211 c12.indd 211c12.indd 211 1/21/10 3:30:48 PM1/21/10 3:30:48 PM Download at getcoolebook.com 212 ❘ CHAPTER 12 HELP AND DOCUMENTATION The pop - up navigation menu, also shown in Figure 12 - 4, lets you jump directly to various sections within the page and is organized very much like the functions menu in the text editor. Finally, the Previous and Next links at the upper - right link to the previous and next page within that document section; these are not history navigation buttons. When reading multi - page articles, use them to move sequentially through the material. Bookmarks Choose the Find ➪ Add to Bookmarks (Command+D) command, or choose the Add Bookmark For ‘ . . . ’ command from the Bookmarks toolbar control to create a bookmark to the current document. Figure 12 - 5 shows adding a bookmark to the File Manager Reference page. You can bookmark a page, but you can ’ t bookmark a particular anchor within a page. Bookmarks are added to the Bookmarks toolbar control and are independent of the Bookmarks smart group in your project. FIGURE 12-5 Choose a bookmark from the Bookmark menu to revisit that document. To manage your bookmarks, choose the Manage Bookmarks command in the Bookmarks toolbar control. In the bookmarks dialog box, shown in Figure 12 - 6, you can: Remove a bookmark with the - button. Add a bookmark to the current page with the + button. Reorder bookmarks by dragging. Rename a bookmark title by double - clicking. ➤ ➤ ➤ ➤ c12.indd 212c12.indd 212 1/21/10 3:30:48 PM1/21/10 3:30:48 PM Download at getcoolebook.com External Links Documentation pages may contain links to external sources (outside the /Developer/ Documentation folder). These include: Links to supplementary documents on Apple ’ s web site The PDF version of a document Feedback and bug reporting links Links to related standards (ISO, W3C, and so on) File archives (ZIP fi les, disk images, and so on) Multimedia (iTunes University, and so on) Most external links are handed off to your operating system and are handled according to your system preferences; an HTML link will most likely open in your default browser, a fi le link may download the fi le to your Downloads folder, a PDF link may download the document and open it using the Preview application, and a podcast may launch iTunes. A number of contextual commands are accessible by Control/Right - clicking a link or selection, as shown on the left in Figure 12 - 7, or anywhere else in a page, as shown on the right. ➤ ➤ ➤ ➤ ➤ ➤ FIGURE 12-6 The Documentation Window ❘ 213 c12.indd 213c12.indd 213 1/21/10 3:30:49 PM1/21/10 3:30:49 PM Download at getcoolebook.com 214 ❘ CHAPTER 12 HELP AND DOCUMENTATION These commands are: COMMAND ACTION Open Link Same as clicking the link Open Link in New Window Creates a second Xcode help window with the contents of the link Copy Link Copies the URL of the link to the clipboard Open Link in Browser Sends the URL of the link to your default browser Find Text in Documentation Enters the link or selected text as the search term (see the “ Searching Documentation ” section later in this chapter) Open Page in New Window Creates a second Xcode help window with the same content Open Page in Browser Sends the URL of the current page to your default browser The “ in New Window ” commands are the only way of creating multiple help windows. The original help window remains the principal help window for your project; shortcuts, for example, are always directed to the principal help window. Opening a link or page in your browser is a great way of keeping multiple documentation pages open at once. Modern browsers, with their tabs and workspace sets, can be much more effective at organizing, remembering, and managing multiple help documents than the simple Xcode help window. SAMPLE PROJECTS A special kind of external link is found in sample project pages. Recently, the Xcode developer tools suite has moved away from providing sample projects as part of the installation to providing links to sample projects in the documentation, going so far as to cross - reference each API with the example FIGURE 12-7 c12.indd 214c12.indd 214 1/21/10 3:30:50 PM1/21/10 3:30:50 PM Download at getcoolebook.com . ➤ ➤ ➤ ➤ ➤ ➤ ➤ ➤ ➤ c12.indd 207c12.indd 207 1/21/10 3: 30 :33 PM1/21/10 3: 30 :33 PM Download at getcoolebook.com 208 ❘ CHAPTER 12 HELP AND DOCUMENTATION The documentation provided with Xcode, along with additional material. on the right. ➤ ➤ ➤ ➤ ➤ ➤ FIGURE 12-6 The Documentation Window ❘ 2 13 c12.indd 213c12.indd 2 13 1/21/10 3: 30:49 PM1/21/10 3: 30:49 PM Download at getcoolebook.com 214 ❘ CHAPTER 12 HELP AND DOCUMENTATION. acts much like any standard web browser. ➤ ➤ ➤ ➤ ➤ ➤ c12.indd 208c12.indd 208 1/21/10 3: 30 :36 PM1/21/10 3: 30 :36 PM Download at getcoolebook.com The search control bar underneath the toolbar, and