---

Viewing Documentation

Technical documentation is an important part of the software development process. As you develop a Mac OS X software product with Xcode, you’re likely to use documentation to learn about the operating system and the technologies it supports, read about system frameworks, and look up individual API definitions.

Xcode includes its own documentation window, which you can use to view the technical documentation and other resources distributed as part of the ADC Reference Library. Xcode’s documentation window gives you several ways to find documentation: you can browse documentation by title and category, search for symbol names, or perform a full-text search for a word or phrase. In addition, Xcode gives you access to the latest documentation available from Apple with downloadable documentation updates.

This section describes the documentation window and the ADC Reference Library content that is distributed with the Xcode Tools. It shows you how to use the API lookup and full-text search features to find Reference Library information, and how to obtain documentation updates.

In this section:

Using the ADC Reference Library
Browsing ADC Reference Library Content
Searching for Documentation
Finding Documentation for Command-Line Tools
Working With Documentation Bookmarks
Obtaining Documentation Updates
Controlling the Appearance of the Documentation Viewer

Using the ADC Reference Library

Apple's ADC Reference Library is a complete collection of technical resources for developers, including documentation, sample code, release notes, technical notes, and technical Q&As. Xcode integrates this content into your development environment, letting you browse or search the ADC Reference Library from the documentation window.

Obtaining ADC Reference Library Content

The ADC Reference Library is available on Apple's developer website and as part of the Xcode Tools installation. You can automatically detect and download updates to the installed ADC Reference Library content through Xcode's documentation update mechanism, described in “Obtaining Documentation Updates,” or you can subscribe to the Developer Connection mailing to receive the entire ADC Reference Library on DVD each quarter. The Developer Connection mailing and Developer DVD Series are described further on the ADC website.

The Documentation package included with the Xcode Developer Tools installs a subset of the ADC Reference Library content on your local volume, at /Developer/ADC Reference Library. This content includes:

1. HTML versions of technical documentation, release notes, and API reference.

2. Category pages that let you browse documents by subject.

3. Full-text and symbol indexes that let you search all ADC Reference Library content.

This core documentation installation does not include PDF, sample code, technical notes, or technical Q&As. However, you can still access this content, referred to as “extended documentation,” from Xcode. You can also find additional sample code, in the form of sample Xcode projects, at /Developer/Examples on your local volume.

Extended Documentation Locations

When you click a documentation link or search result in the Xcode documentation window, Xcode first looks for that content at /Developer/ADC Reference Library. If it does not find the requested content there, Xcode then looks at the extended documentation locations defined in Xcode's documentation preferences. If Xcode cannot find the requested content after checking the extended locations, it notifies you that it was unable to locate the specified documentation.

Xcode's default extended documentation location points to the full ADC Reference Library on Apple's developer website. You can see where Xcode looks for additional documentation in Xcode's preferences, in the Extended Locations table. You can also add your own locations. For example, if you have the full ADC Reference Library content on DVD, you can add a new location specifying that Xcode look for additional content on that DVD volume.

To add an alternative location for locating extended documentation:

1. Open Xcode Preferences by choosing Xcode > Preferences or typing Command-comma. Open the Documentation pane.

2. Under Extended Locations, click the '+' button.

3. Navigate to the volume or folder where the documentation is located and select the ADC Reference Library folder.

4. Click Add or press Return to add the new location to the Extended Locations table. Xcode adds the new documentation location to the list and makes it active. Click Apply or OK to apply your changes.

Xcode looks for content at the extended locations in the order in which they appear in the table, looking at the top entry first. You can change the order of a location by dragging its entry to the appropriate spot in the table. For example, if you want Xcode to look at the DVD copy of the ADC Reference Library before going to the web, add the DVD as an extended location and drag that entry to the top of the list.

If you don't want Xcode to look for documentation at a location that appears in the Extended Locations table, you can either remove the entry from the list or disable the location. To remove a location from the list, select the entry for that location and click the '-' button. To disable a location, deselect the checkbox in the On column next to the location. You cannot remove the default Web location, although you can disable it.

Browsing ADC Reference Library Content

Xcode has its own built-in documentation viewer, shown below, which allows you to find documentation quickly and easily. To open the documentation window you can:

• Select an item from the Help menu.

• Option–double-click a symbol name in an editor.

• Click a book icon next to a symbol name in the class browser.

• Select text in an editor window and choose Help > Find Selected Text in API Reference or Help > Find Selected Text in Documentation.

• Control-click the selected text in an editor window and choose Find Selected Text in API Reference or Find Selected Text in Documentation from the contextual menu.

Reference Library content is organized by category; you can see these categories in the Search Groups list in the documentation window, shown in Figure 8-9. Many of these categories have additional subcategories, which you can see by clicking the turn-down arrow next to the category name. When you select a category or subcategory in the Search Groups list, Xcode displays its contents in the documentation pane. Selecting the top-level Reference Library group, or a group with additional subcategories, displays a navigation page such as the one below that shows you the categories in this group with a brief description. From there you can further narrow the subject matter to look for specific documents.

When you perform a full-text or API reference search in Xcode, Xcode searches only in documents in the currently selected group and any groups it might contain. To search all of the ADC Reference Library content, select the Reference Library group in the Search Groups list.

If you prefer to have more than one document open and visible at a time, the documentation window lets you open a document in the documentation window, in a separate Xcode window, or in your preferred browser.

• To open the current document in a separate Xcode window, Control-click in the content area of the document and choose Open Page in New Window or Open Frame in New Window.

• To open the current document in your preferred browser, Control-click in the content area of the document and choose Open Page in Browser.

When following links that appear in the documentation, you can choose to open those links in the documentation window, in a separate editor window, or in your preferred browser.

• To open a link in the documentation window, click the link.

• To open a link in a separate Xcode window, you can either Control-click the link and choose Open Link in New Window from the contextual menu or simply Command-click the link.

• To open a link in your preferred browser, Control-click the link and choose Open Link in Browser or simply Option-click the link.

You can also copy a link or an image to the clipboard by Control-clicking the link or image and choosing Copy Link from the contextual menu.

Searching for Documentation

When you know the term you're looking for, searching is often the fastest way to find documentation. Xcode's documentation window supports two search modes:

• API reference search. This lets you quickly search the available reference documents for a symbol name.

• Full-text search. This lets you search the available documentation for a word or phrase. Xcode's full-text search supports simple search term matches, as well as more complex queries using Boolean operators and wildcard searches.

The current selection in the Search Groups list determines the scope of both API-reference and full-text searches. For full-text searches, the selection in the Search Groups list determines the documentation set that Xcode searches. For example, if you search for the term “button” with the Cocoa category selected in the Search Groups list, Xcode returns only documents from the Cocoa category that contain the word “button.”

For API-Reference searches, the selection in the Search Group list determines the programming languages for which Xcode returns results. To search all available documentation, select Reference Library in the Search Groups list.

API Reference Search

When you are writing code, you often need to find documentation for a function, method, data type, or other symbol. Xcode's API reference search lets you quickly find the information you need.

To perform an API reference search in Xcode's documentation window, select API Search from the pull-down menu of the Search field and begin typing the name of the symbol. Xcode's API lookup supports type-ahead; as you type, the detail view displays all of the symbols whose names start with the string in the Search field, as shown in Figure 8-10. As a shortcut, you can also Option–double-click a symbol’s name in any Xcode editor window to open the documentation for that symbol in the documentation window.

The current selection in the Search Group list determines the programming languages for which Xcode returns results. For example, if you select “Reference Library,” Xcode returns all matching symbols, regardless of the type or language. If you select Carbon in the Search Groups list and perform an API lookup, Xcode returns only matching C and C++ symbols.

You can also specify additional language filters for Xcode's API-reference search by clicking the Configure Options button in the documentation window toolbar. In the dialog that Xcode displays, choose which languages Xcode includes in API-reference searches. To include a language in the API search, select the checkbox in the On column next to that language. If you don't want Xcode to return results for a particular language, deselect the checkbox next to that language. These filters are applied to all API-reference searches regardless of the current selection in the Search Groups list. By default, all of the languages are enabled. Xcode supports API lookup for C, C++, Java, and Objective-C.

To view the documentation associated with one of the symbols returned in a search, select its name from the table. The documentation is displayed in the pane below the table view.

Full-Text Search

Xcode's full-text search lets you search the installed documentation for a word or phrase. You can enter a simple search term, such as “button,” or create more advanced queries using Boolean operators and wildcard characters. Xcode's full-text search uses Apple's Search Kit technology, described in Search Kit Programming Guide

To perform a full-text search choose Full-Text Search from the pull-down menu in the Search field of the documentation window. Type your query and press Return. Xcode searches the installed documentation for the given term or terms and displays the results in the documentation window, as shown in Figure 8-11. The table view displays the relevance, location, page title, and document title for each page returned by the search. To view a page returned as a search result, select that page in the search results table. The scope of the search is determined by the selection in the Search Groups list.

By default, Xcode performs an exact-match search. That is, when you enter a search term, Xcode returns only those documents that contain the entire term. For example, searching for “button” returns documents containing the word “button,” but not documents containing only the word “buttons.” If you type a phrase, such as “bevel button,” Xcode returns those documents that contain both the word “bevel” and the word “button.”

As a shortcut, you can also search the installed documentation for text in an editor window. Select the text to search for and choose Help > Find Selected Text in Documentation. Xcode performs a full-text search and returns all documents containing that text.

You can further refine your search by combining search terms using Boolean operators, searching for required terms, or using a wildcard search. The following sections describe the various queries you can construct for searching the developer documentation.

Constructing Queries Using Boolean Operators

If you wish to further restrict the parameters of your search, you can combine search terms using Boolean operators. You can create arbitrarily complex queries to narrow your search to fit your particular criteria.

Xcode supports the following Boolean operators, listed in order of precedence from highest to lowest:

For example, to find documents about the font panel in Mac OS X, you want to find documents that contain the phrase “font panel.” Just to be safe, you also want to catch any documents that don't contain the exact phrase “font panel,” but do contain both search terms “font” and “panel.” You can do that with the following query:

"font panel" | (font & panel)

Required Terms Search

Simpler than a Boolean query, a required-terms search lets you search for terms that must or must not appear in documents returned as a search result. A required terms search uses the following operators:

For example, entering +window returns all documents containing the word “window,” similar to the behavior you get by simply entering “window” as a search term. However, if you enter +window -dialog, you will get all documents containing the word “window,” but NOT the word “dialog.”

Using Boolean operators to construct the previous query, you would write:

window & (!dialog)

Wildcard Search

If you are not sure exactly how a particular term appears in the documentation, you can use a wildcard search to include all variations of a search term in the search results. For example, if you are looking for all documentation about buttons in Mac OS X, you probably really want to see all documentation containing either the word “button” or the word “buttons.” Rather than have to specify each of these as separate terms, you can simply use the wildcard character to construct the following query, which returns all documents containing the word “button” or any word with the prefix “button.”

button*

You can use the wildcard character anywhere within a search string. Using a wildcard character at a location other than at the end of a search term may result in longer search times.

Finding Documentation for Command-Line Tools

To find documentation on a command-line tool, choose Help > Open man page. Use the “man page name” option to display documentation on a command-line tool. You can optionally specify a man page section; for example, access(5). Use the “search string” option to find commands that are related to a keyword.

Working With Documentation Bookmarks

The Xcode documentation window also supports bookmarks, to provide easy access to documentation that you use frequently. To view the available bookmarks in the documentation window, click the disclosure triangle next to the Bookmarks group in the Search Groups list of the documentation window. Xcode includes a default set of bookmarks, but you can delete any of these default bookmarks or create your own.

To add a bookmark, choose Find > Add to Bookmarks. This bookmarks the page currently open in the documentation window and adds the bookmark to the Bookmarks group. You can also add a bookmark by dragging the document proxy icon in the titlebar of the documentation window to the Bookmarks group in the Search Groups list.

To open a bookmarked location, select the bookmark in the Search Groups list. To rename a bookmark, Option-click the name of the bookmark in the Search Groups list and type the new name.

Obtaining Documentation Updates

In addition to the full ADC Reference Library content available with the Xcode Tools DVD and Developer DVD Series, Apple also provides downloadable packages of the documentation installed on your local computer at /Developer/ADC Reference Library. Xcode automatically detects these updates as they become available. Documentation updates are released more frequently than the full Xcode Tools package, so this is a quick and easy way to stay up-to-date with the latest technical information from Apple.

Checking for Updates

Xcode automatically checks for a documentation update the first time you launch Xcode after installing a new version of the Xcode tools. Any time you access the documentation after the initial check, Xcode checks for an update if the interval specified in Xcode's Documentation preferences has passed since the last check. By default, Xcode checks for updates on a weekly basis, but you can choose a different interval.

To change the interval at which Xcode checks for documentation updates:

1. Open the Documentation pane of Xcode Preferences.

2. Choose an interval from the “Check for documentation updates” pop-up menu that appears in the Updates settings group. You can choose to have Xcode check for updates on a daily, weekly, or monthly basis. Click Apply or OK to apply your changes.

If you don't want Xcode to automatically check for updates at all—for example, if you use Xcode on a computer that does not usually have an internet connection—deselect the checkbox next to the “Check for documentation updates” menu.

To check for a documentation update immediately, click the Check Now button. The “Last check” field shows the date and time at which Xcode last successfully checked for updated documentation.

Installing an Update

When it checks for a documentation update, Xcode compares the version of the documentation on Apple's server to the version installed on your computer. If the documentation on the server is newer, Xcode notifies you that updated documentation is available. To download the documentation package, click Download.

Xcode launches your default browser application to download the documentation package. When the download is complete, the disk image automatically mounts. Double-click the documentation package to launch the Installer. The installer updates the local installation of the ADC Reference Library at /Developer/ADC Reference Library.

If Xcode is running when the installation is successfully completed, Xcode notifies you that the documentation has been updated. Click OK to reload the Search Groups and ADC Reference Library entry page in the documentation window. Otherwise, Xcode loads the new documentation when it next launches.

Controlling the Appearance of the Documentation Viewer

You can change the minimum font size used for viewing documentation. To do so, open the Documentation pane of the Xcode Preferences window. To enforce a minimum font size for documents displayed in the documentation window:

1. Under Universal Access, select the “Never use font sizes smaller than” option.

2. Choose a font size from the corresponding pop-up menu.

You can temporarily change the font size used to display an HTML file—even if its font size is controlled by a CSS file—by choosing Format > Font > Bigger or Format > Font > Smaller.

---