Getting the Facts: Where to Find Documentation

Distributions of Mac OS X typically come with only a little hardcopy reference. However, online documentation has always been one of UNIX's strengths. The manual and info pages are available via the man and info utilities. With the growth of Mac OS X and the Internet, the sources of documentation have expanded. The following sections discuss some of the places you can look for information on various aspects of UNIX in general and Mac OS X in particular.

The Help Viewer

The Help Viewer is a graphical application that you run by clicking Help on the menu bar at the top of the screen. For graphical applications, it is the default help program. In general, the Help Viewer offers the documentation for application programs, not for utilities. This documentation often includes links to useful resources. For example, the help for Terminal includes links to Apple's Web site. These links point to documentation about the UNIX system and utilities.

System Documentation

With the Developer Tools package installed (page 478), the Xcode development environment (page 478) offers access to much of the system programming and UNIX command line documentation as well as provides a general-purpose software development environment.

man: Displaying the System Manual

The character-based man utility displays pages, known as man pages, from the system documentation. This documentation is useful when you know which utility you want to use but have forgotten exactly how to use it. You can also refer to the man pages to get more information about specific topics or to determine which features are available under Mac OS X. Because the descriptions in the system documentation are often terse, they are most helpful when you already understand basically what a utility does.

Because man is a character-based utility, you must run it from the command line. Nicely formatted versions of the man pages are available from within Xcode (page 478).

To find out more about a utility, give the command man, followed by the name of the utility. Figure 2-6 shows the command man who displaying information about the who utility.

Figure 2-6. The man utility displaying information about who

The command man man displays information on man. The man utility automatically sends the output through a pager, usually less (page 42), which allows you to view a file one screen at a time. When you access a manual page in this way, less displays a prompt (:) at the bottom of the screen after each screen of text and waits for you to request another screen by pressing the SPACE bar. Pressing h (help) displays a list of the less commands that you can use. Pressing q (quit) stops less and displays a shell prompt. You can search for topics covered by man pages by using the apropos utility (page 59, or give the command man apropos).

The Mac OS X system manual and the man pages are divided into ten sections. Each section describes related tools:

1. User Commands

2. System Calls

3. Subroutines

4. Devices

5. File Formats

6. Games

7. Miscellaneous

8. System Administration

9. Kernel Interfaces

N. Tcl/Tk commands

This layout closely mimics the way the set of UNIX manuals has always been divided. Unless you specify a manual section, man displays the earliest occurrence in the manual of the word you specify on the command line. Most users find the information they need in sections 1, 6, and 7; programmers and system administrators frequently need to consult the other sections. Some man pages are installed only with the Developer Tools package (page 478).

In some cases there are manual entries for different tools with the same name. For example, the following command displays the manual page for the write utility (page 63) from section 1 of the system manual:

$ man write 

To see the manual page for the write() system call from section 2, enter

$ man 2 write 

This command instructs man to look only in section 2 for the manual page. Use the a option (see the adjacent tip) to view all the man pages for a given subject (press q to move to the next section); use man a write to view all the man pages for write.

Tip: Options

An option modifies the way a utility or command works. Options are specified as one or more letters that are preceded by one or two hyphens (there are exceptions). The option appears following the name of the utility you are calling and a SPACE. Any other arguments (page 921) to the command follow the option and a SPACE. For more information refer to "Options" on page 115.

Tip: man and info display different information

The info utility displays more complete and up-to-date information on GNU utilities than does man. When a man page displays abbreviated information on a utility that is covered by info, the man page refers you to info. The man utility frequently displays the only information available on non-GNU utilities; when info displays information on non-GNU utilities, it is frequently a copy of the man page.

info: Displaying Information About Utilities

The character-based info utility is a menu-based hypertext system developed by the GNU Project and distributed with Mac OS X. As with man, you must run info from a terminal emulator window (page 24). The info utility includes a tutorial on itself (give the command info info or go to www.gnu.org/software/texinfo/manual/info) and documentation on many Mac OS X shells, utilities, and programs developed by the GNU Project (page 3). Figure 2-7 shows the screen that info displays when you give the command info.

Figure 2-7. The first screen that info displays

Because the information on this screen is drawn from an editable file, your display may differ. From the initial info screen you can press

• h to go through an interactive tutorial on info

• ? to list info commands

• SPACE to scroll through the menu of items you can get information on

• m, followed by the name of the menu item you want to access

• q to quit

The notation info uses to describe keyboard keys may not be familiar to you. The notation C-h is the same as CONTROL-H. Similarly M-x means hold down the META or ALT key and press x. Standard Mac keyboards do not have a META or ALT key. The "Activating the META key" tip explains how to set up the OPTION key to perform the same functions as the META key. For more information refer to "Keys: Notation and Use" on page 208.

Tip: Activating the META key

In the Terminal utility, you can make the OPTION (or ALT) key work as the META key. From the Terminal utility File menu, select Window Settings to display the Terminal Inspector window (Figure 2-8). This window provides a drop-down menu of properties that you can change. Select Keyboard, check the box labeled Use option key as meta key, and click Use Settings as Defaults. This procedure causes the OPTION key (on Mac keyboards) or the ALT key (on PC keyboards) to function as the META key while you are using the Terminal utility.

Figure 2-8. Terminal Inspector window

After giving the command info, press the SPACE bar a few times to scroll the display. Figure 2-9 (next page) shows the first screen that info displays. The asterisk at the left end of the line means that this entry is the beginning of a menu item. Following the asterisk is the name of the menu item, a colon, the name of the package (in parentheses) to which the menu item belongs, other information, and a description of the item (on the right).

Figure 2-9. The screen that info displays after you press the SPACE bar a few times

info menu items

Each menu item is an active link to the info page that describes the item. To jump to that page, move the cursor to the line containing the menu item and press RETURN. Alternatively you can type the name of the menu item in a menu command to view the information. For example, to display information on bash, give the command m bash followed by a RETURN. When you type m (for menu), the cursor moves to the bottom line of the screen and displays Menu item:. Typing bash displays bash on that line, and pressing RETURN displays the bash info page.

Figure 2-10 shows the top node of information on bash. A node is one group of information that you can scroll through with the SPACE bar. To display the next node, press n. Press p to display the previous node. You can always press d to display the initial menu, shown in Figure 2-7.

Figure 2-10. The info page on the bash utility

As you read this book and learn about new utilities, you may want to use man or info to find out more about those utilities. If you can print PostScript documents, you can print a manual page with the man utility using the t option (for example, man t cat | lpr prints information about the cat utility). The Linux Documentation Project (www.tldp.org) has a large collection of documentation on UNIX utilities, much of which is applicable to Mac OS X.

As with the man pages, much of the info documentation is available from within Xcode (page 478).

Using the Internet to Get Help

The Internet provides many helpful sites; see Appendix B for a list. Aside from visiting sites that carry various forms of documentation, you can enter an error message that you are having a problem with in a search engine such as Google (www.google.com). Enclose the error message within double quotation marks to improve the quality of the results. You will likely find a post concerning the problem and ways to solve it. See Figure 2-11.

Figure 2-11. Google reporting on an error message

The Apple Web site

The Apple Web site is a rich source of information. Following is a list of some locations that may be of interest:

• Manuals for Apple operating systems and products are available at www.info.apple.com/support/manuals.html.

• General support material is available at www.apple.com/support.

• Apple support forums are online discussions about any Apple-related issues. Forums are dedicated to specific applications or OS versions, specific Macintosh models, and so on. Go to discussions.info.apple.com to browse through the forums.

• Mailing lists are hosted by Apple; see lists.apple.com for a list of mailing lists.

• Even if you are not using Mac OS X Server, the documentation for Server has a lot of material on command line usage.

GNU

GNU makes many of its manuals available at www.gnu.org/manual. In addition, go to the GNU home page (www.gnu.org) for more documentation and other GNU resources. Many of the GNU pages and resources are available in a wide variety of languages. Mac OS X uses a number of GNU utilities, and many more are available for download.