DOCUMENTATION SHORTCUTS A number of shortcuts are available for accessing the help window and for quickly looking up key terms. The global shortcuts are: SHORTCUT ACTION Option+Shift+Command+? Opens the help window Control+Shift+Command+? Opens the quick help window Shift+Command+? Activates the Help menu These three shortcuts are available almost universally in Xcode. The quick help window is described in the “ Quick Help ” section a little later in this chapter. The next few sections describe other kinds of documentation shortcuts and how to access them. Editing Shortcuts You will most likely want to consult the documentation for a particular function or method while editing code. With a symbol name selected in the text editor pane, you have the following menu command and shortcuts available to you: SHORTCUT ACTION Option+Shift+double - click Searches for symbol in documentation Option+double - click Opens quick help window for symbol Control/Right - click ➪ Find Text in Documentation Searches for selected text in documentation Help ➪ Find Documentation for Selected Text Same as Find Text in Documentation The two most useful shortcuts are the Option+Shift+double - click and Option+double - click gestures. These immediately select the word (symbol) underneath the cursor and search for its defi nition in either the help window or the quick help window (described in the next section). Quick Help The quick help window, shown in Figure 12 - 14, is a miniature help window that presents a succinct summary of a single API symbol. It operates in two modes: transient and persistent. FIGURE 12-14 Documentation Shortcuts ❘ 221 c12.indd 221c12.indd 221 1/21/10 3:31:03 PM1/21/10 3:31:03 PM Download at getcoolebook.com 222 ❘ CHAPTER 12 HELP AND DOCUMENTATION The quick help window has two action buttons, in addition to the standard title bar, resize, and close controls. The button with the little book jumps to the full API documentation for that symbol in the standard help window — equivalent to any of the other symbol search shortcuts mentioned in this section. If you have upgraded from an earlier version of Xcode, quick help replaces the Research Assistant. The “Persistent Quick Help” section described how to keep the quick help window open, where it acts very much like the Research Assistant did. The optional header button jumps to the defi nition of the symbol in the framework ’ s header ( .h ) fi le. This is equivalent to the Edit ➪ Find ➪ Jump to Defi nition (Command+double - click) shortcut. Transient Quick Help Quick help is intended to be just that: quick. When summoned from the editor using the Option+double - click shortcut, it appears immediately adjacent to the symbol in question. Pressing the Esc key, or clicking anywhere in the editor pane, dismisses the quick help window and returns you to your coding. Persistent Quick Help If you summon the quick help window and then move or resize it, or open it using the Help ➪ Quick Help (Control+Shift+Command+?) command, the quick help window becomes persistent; it will not automatically close when you return to editing. Instead, it acts more like an inspector palette, constantly updating its content based on the current text selection. If you fi nd yourself referring to the quick help window a lot, consider letting it be persistent. If you have limited screen real estate or, like me, only like to see it open when you need it, use the Option+double - click shortcut to open it on demand and press Esc to close it again. Documentation Shortcuts The help document browser responds to the following standard shortcuts, although — oddly — most are not associated with any of Xcode ’ s menus: SHORTCUT ACTION Command+[ Previous page in history Command+] Next page in history Command+F Find text, or fi nd next c12.indd 222c12.indd 222 1/21/10 3:31:04 PM1/21/10 3:31:04 PM Download at getcoolebook.com SHORTCUT ACTION Command+G Find next Shift+Command+G Find previous Command+D Add bookmark MAN PAGES UNIX man pages are another source of documentation that is loosely integrated with Xcode. The C functions (section 3) of the man pages are included in the API search index. Looking up or searching for a POSIX C function displays the man page for that function, but the man pages for shell commands (section 1), fi le formats (section 5), system utilities (section 8), along with third - party man pages are not indexed and cannot be found through the help window. To review any man page installed in your system, choose the Help ➪ Open man Page command, which presents the dialog shown in Figure 12 - 15. There is also a man . . . toolbar button that you can add to your help window ’ s toolbar. The man page name option invokes the man command with your search term and presents the resulting man page in the help window. The search string option invokes the apropos ( man - k ) command. This searches all of the short descriptions in the man page database for the given keywords and presents the results in the help window. Each result is linked to its man page, so review the search results and click the entries that interest you. CUSTOMIZING HELP The Documentation pane of the Xcode preferences, shown in Figure 12 - 16, allow you to customize three things: what documentation sets you subscribe to, what information is presented in the quick help window, and how small the documentation text fonts are allowed to be. FIGURE 12-15 Customizing Help ❘ 223 c12.indd 223c12.indd 223 1/21/10 3:31:09 PM1/21/10 3:31:09 PM Download at getcoolebook.com 224 ❘ CHAPTER 12 HELP AND DOCUMENTATION Managing Subscriptions Any or all of the documentation sets installed in /Developer/Documentation can be maintained through an RSS feed. Xcode can query these RSS feeds to determine if there are any updates to the documentation sets. If new documentation is available, Xcode will offer to (or will automatically) download the updated documentation and install it. Downloading documentation from Apple ’ s servers requires that you provide your developer connection account ID and password, as shown in Figure 12 - 17. This information will be saved for future updates. Installing new fi les in your /Developer folder also requires an administrator ’ s authorization. FIGURE 12-16 c12.indd 224c12.indd 224 1/21/10 3:31:10 PM1/21/10 3:31:10 PM Download at getcoolebook.com The Check For And Install Updates Automatically option instructs Xcode to periodically check for, and install, new documentation updates. If left unchecked, you will want to manually check for updates occasionally using the Check and Install Now button, preferably when you have a high - speed Internet connection — documentation updates can be quite large. In Figure 12 - 16, you can see that the iPhone OS 3.0 and Snow Leopard Library documentation sets are in the process of being downloaded. Be patient; even with a fast network pipe, large documentation sets can take an hour or more to download and install. If you ’ re wondering what the progress of the update is, check Xcode ’ s Activity window, as shown in Figure 12 - 18. A number of documentation sets have subscription feeds, but are disabled by default. In Figure 12 - 16, the original iPhone OS Library, Java Library, and some other sets are not installed. Click the Get button to download, install, and activate the RSS feed for that document set. If you ’ re curious about where the fi les for a particular document set are installed, the address of its RSS feed, and other information, click the small i (Info) button next to the set name. You cannot delete any of the preinstalled document sets from Apple, but you can install additional sets generated by you or a third party. The details of generating and installing your own Xcode - compatible documentation is amply described in the article “ Using Doxygen to Create Xcode Documentation Sets, ” which is part of the Xcode documentation set. FIGURE 12-17 FIGURE 12-18 Customizing Help ❘ 225 c12.indd 225c12.indd 225 1/21/10 3:31:10 PM1/21/10 3:31:10 PM Download at getcoolebook.com 226 ❘ CHAPTER 12 HELP AND DOCUMENTATION Customizing Quick Help To the right of the subscriptions is a panel where you can customize the content, and order, of information that is presented in the quick help window. Check the sections that you want to appear. Click and drag to change the order of those included. Limiting Font Size The only thing more frustrating than not fi nding what you ’ re looking for is fi nding it and then not being able to read it. Checking the Never Use Font Sizes Smaller Than option lets you establish a minimum font size for all text that appears in help windows. THE XCODE COMMUNITY This chapter has focused on the help and documentation resources accessible through the Xcode interface, but one of the most valuable resources for Xcode users is other Xcode users . In addition to supplementary developer information at Apple ’ s Developer Connection web site, you ’ ll also fi nd a variety of mailing list and discussion forums. You can see the complete list of the mailing lists at http://lists.apple.com/mailman/listinfo . Of particular interest is the Xcode - users mailing list. This list is populated by Xcode users from all over the world and is a phenomenal resource for solving problems with Xcode. I tapped the talented and helpful individuals of this list several times while writing this book. I would strongly urge you to join the Xcode - users list. As with many Internet discussion groups, members contribute their time and knowledge as a courtesy to others and to support the community of Xcode users. Many are professional software engineers with busy schedules and none of them are obligated to help you. Be respectful of their time and efforts by adhering to these guidelines: The list does not exist to solve your problems for you. Post questions only when you ’ ve read all the available documentation (which should include this book), searched the list archives for similar questions, and tried all of the solutions you can think of. Be clear, concise, complete, and courteous. Give something back. The list is a community of members helping members. If you know the answer to a question, or have a helpful suggestion, take the time to post it. You can ’ t expect others to help you if you never help anyone else. The list is not your personal soapbox. It ’ s not a forum for rants and personal opinions. If you want to provide feedback to the Xcode developers, use one of the feedback links on Apple ’ s website or fi le an enhancement request via the bug reporter (available to registered developers). In my experience, the Xcode development team is very open to suggestions that will improve Xcode. The list is not Apple support. If you need technical, sales, or developer support from Apple, contact the appropriate party through ADC. Apple engineers have been known to monitor and answer questions on the list, but they cannot provide you with any kind of offi cial sup- port through the list. ➤ ➤ ➤ ➤ ➤ c12.indd 226c12.indd 226 1/21/10 3:31:11 PM1/21/10 3:31:11 PM Download at getcoolebook.com SUMMARY Xcode includes a massive amount of documentation, and a variety of tools for working with it. You ’ ve seen how to search for keywords and symbols, and fi nd API documentation from within the class browser and directly from within your source code. You can even add you own documentation, if you need to. You may still not fi nd what you are looking for in the local documentation. Remember to avail yourself of the Apple Developer Connection web site ( http://developer.apple.com/ ). Apple ’ s online resources contain many more articles, documents, and sample code than could ever be downloaded and stored locally, and these resources are updated constantly. Summary ❘ 227 c12.indd 227c12.indd 227 1/21/10 3:31:11 PM1/21/10 3:31:11 PM Download at getcoolebook.com c12.indd 228c12.indd 228 1/21/10 3:31:11 PM1/21/10 3:31:11 PM Download at getcoolebook.com . ❘ 227 c12.indd 227c12.indd 227 1/21/10 3: 31:11 PM1/21/10 3: 31:11 PM Download at getcoolebook.com c12.indd 228c12.indd 228 1/21/10 3: 31:11 PM1/21/10 3: 31:11 PM Download at getcoolebook.com . documentation text fonts are allowed to be. FIGURE 12-15 Customizing Help ❘ 2 23 c12.indd 223c12.indd 2 23 1/21/10 3: 31:09 PM1/21/10 3: 31:09 PM Download at getcoolebook.com 224 ❘ CHAPTER 12 HELP AND DOCUMENTATION. persistent. FIGURE 12-14 Documentation Shortcuts ❘ 221 c12.indd 221c12.indd 221 1/21/10 3: 31: 03 PM1/21/10 3: 31: 03 PM Download at getcoolebook.com 222 ❘ CHAPTER 12 HELP AND DOCUMENTATION The quick