Getting the Facts: Where to Find Documentation

Distributions of Linux, including Red Hat Linux, typically do not come with hardcopy reference manuals. However, its online documentation has always been one of Linux's strengths. The manual (or man) and info pages have been available via the man and info utilities since early releases of the operating system. Both the GNOME and KDE desktops provide graphical Help Centers. Not surprisingly, with the growth of Linux and the Internet, the sources of documentation have expanded as well. This section discusses some of the places you can look for information on Linux in general and Red Hat Linux in particular.

The KDE Help Center

Display the KDE Help Center by clicking Main menu: Help. If the Help Center displays a window that asks whether you want to create a search index, click Create. The Help Center then displays the Build Search Index window. Put a check mark in each of the boxes in the Search Scope column of this window and click Build Index. The window that appears shows the progress being made in building the index. When it is complete, click Close.

The Help Center window contains two vertical sections separated by a thin bar with hatchmarks on it. (See Figure 4-17 on page 100 for an example of a bar with similar marks.) Click the hatchmarks and drag the bar left or right to adjust the sizes of the two sections of the window.

The left side of the Help Center window contains three tabs: Contents, Glossary, and Search Options. Click the Contents tab to display a list of the Help Center contents on the left. This list includes the KDE FAQ, the KDE User's Manual, Linux (UNIX) man pages, GNU info pages, KDE Control Center modules, and more. Click an item on this list to display a list of subitems available for further exploration. Click a subitem to display that item on the right. Figure 4-20 shows the Help Center, Contents tab, displaying information on the Control Center Modules Font Installer.

Figure 4-20. The KDE Help Center

Clicking the Glossary tab displays definitions of words related to Linux sorted either alphabetically or by topic. When you click the Search Options tab and select one or more items from the Scope column, you can enter a word to search for in the small text box just above the tabs. Click Search to display the results of the search in the right portion of the window. Figure 4-21 shows the result of a search of the Linux (called UNIX in this window) manual pages for the word uptime.

Figure 4-21. Result of a search for uptime in the KDE Help Center

GNOME Help

To display the GNOME Help window (Figure 4-22), select System: Help (RHEL uses Applications: Help) from the panel at the top of the screen. Click topics in this window until GNOME displays the information you are looking for. Click Command Line Help to display man and info pages.

Figure 4-22. The GNOME Help window

man: Displays the System Manual

In addition to the KDE Help Center and GNOME Help, the character-based man (manual) utility displays pages (man pages) from the system documentation. This documentation is helpful 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 with Linux. Because the descriptions in the system documentation are often terse, they are most helpful if you already understand the basic functions of the utility.

Because man is a character-based utility, you need to open a terminal emulator window (page 93) to run it. You can also log in on a virtual terminal (page 113) and run the utility from there.

To find out more about a utility, give the command man, followed by the name of the utility. Figure 4-23 shows man displaying information about itself, after the user entered a man man command.

Figure 4-23. The man utility displaying information about itself

less (pager)

The man utility automatically sends its output through a pagerusually less (page 128), which displays a file one screen at a time. When you access a manual page in this manner, 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 less commands. Pressing q (quit) stops less and causes the shell to display a prompt. You can search for topics covered by man pages by using the apropos utility (page 145).

Based on the FHS (Filesystem Hierarchy Standard, page 176), the Linux 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

10. New

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.

Tip: You can use Konqueror to view man and info pages

You can view man and info pages by entering, for example, man:cat or info:cat in Konqueror's location bar (Figure 4-13, page 96) or in the Run Command box (page 96). The KDE Help Center also offers direct access to these pages as UNIX manual pages. GNOME Help refers to them as Command Line Help.

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

$ man write

To see the man page for the write system call from section 2, enter

$ man 2 write

The preceding command instructs man to look only in section 2 for the man page. Use the a option (see the adjacent tip) to view all man pages for a given subject (press q to move to the next man page). For example, give the command man a write to view all man pages for write.

Tip: Options

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

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: Displays Information About Utilities

The character-based info utility is a menu-based hypertext system developed by the GNU project (page 2) and distributed with Red Hat Linux. The info utility includes a tutorial on itself (go to www.gnu.org/software/texinfo/manual/info or give the command info info) and documentation on many Linux shells, utilities, and programs developed by the GNU project. Figure 4-24 shows the screen that info displays when you give the command info.

Figure 4-24. The first screen that info displays

Because the information on this screen is drawn from an editable file, your display may differ from those shown in this section. When you see the initial info screen, you can press any of the following keys or key combinations:

• h to go through an interactive tutorial on info

• ? to list info commands

• SPACE to scroll through the menu of items for which information is available

• m followed by the name of the menu you want to display or a SPACE to display a list of menus

• q or CONTROL-C 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. (On some systems you need to press ESCAPE and then x to duplicate the function of META-x.)

Tip: You may find pinfo easier to use than info

The pinfo utility is similar to info but is more intuitive if you are not familiar with the emacs editor. This utility runs in a textual environment, as does info. When it is available, pinfo uses color to make its interface easier to use.

After giving the command info, press the SPACE bar a few times to scroll through the display. Figure 4-25 shows the entry for sleep. The asterisk at the left end of the line means that this entry is a menu item. Following the asterisk is the name of the menu item, a colon, the name of the package (in parentheses) that the menu item belongs to, other information, and a description of the item on the right. In most cases the package name corresponds to the name of the rpm package (page 487) that contains the item. Figure 4-25 shows that the sleep utility is part of the coreutils package.

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

Each menu item is a 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. To display information on sleep, for example, you can give the command m sleep, followed by RETURN. When you type m (for menu), the cursor moves to the bottom line of the screen and displays Menu item:. Typing sleep displays sleep on that line, and pressing RETURN displays information about the menu item you have chosen.

Figure 4-26 shows the top node of information on sleep. 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 (Figure 4-24).

Figure 4-26. The info page on the sleep utility

As you read through this book and learn about new utilities, you can use man or info to find out more about the 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). you can also use a browser to display the documentation at www.tldp.org, fedora.redhat.com/docs, fedoraproject.org/wiki/Docs, or www.redhat.com and then print the desired information from the browser.

The help Option

Another tool you can use in a textual environment is the help option. Most GNU utilities provide a help option that displays information about the utility. Non-GNU utilities may use a h or help option to display Help information.

$ cat --help Usage: cat [OPTION] [FILE]... Concatenate FILE(s), or standard input, to standard output.   -A, --show-all           equivalent to -vET   -b, --number-nonblank    number nonblank output lines   -e                       equivalent to -vE   -E, --show-ends          display $ at end of each line ...

If the information that help displays runs off the screen, send the output through the less pager (page 104) using a pipe (page 52):

$ ls --help | less

HOWTOs: Finding Out How Things Work

A HOWTO document explains in detail how to do something related to Linuxfrom setting up a specialized piece of hardware to performing a system administration task to setting up specific networking software. Mini-HOWTOs offer shorter explanations. As with Linux software, one person or a few people generally are responsible for a HOWTO document, but many people may contribute to it.

The Linux Documentation Project (LDP, page 110) site houses most HOWTO and mini-HOWTO documents. Use a browser to go to www.tldp.org, click HOWTOs, and pick the index you want to use to find a HOWTO or mini-HOWTO. You can also use the LDP search feature on its home page to find HOWTOs and more.

Getting Help with the System

KDE and GNOME provide similar Help facilities. Each provides tooltips (page 86), a context-sensitive Help system, and the Help systems discussed on pages 102 and 103.

Finding Help Locally

The /usr/src/linux/Documentation (present only if you installed the kernel source code as explained in Chapter 15) and /usr/share/doc directories often contain more detailed and different information about a utility than man or info provides. Frequently this information is meant for people who will be compiling and modifying the utility, not just using it. These directories hold thousands of files, each containing information on a separate topic.

Using the Internet to Get Help

The Internet provides many helpful sites related to Linux. Aside from 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, or its Linux-specific version at www.google.com/linux). Enclose the error message within double quotation marks to improve the quality of the results. The search will likely yield a post concerning your problem and suggestions about how to solve it. See Figure 4-27 on the next page.

Figure 4-27. Google reporting on an error message

The Red Hat Web site

The Red Hat and Fedora Web sites are rich sources of information. The following list identifies of some locations that may be of interest:

• Manuals for Red Hat Linux through Red Hat Linux 9 and RHEL are available at www.redhat.com/docs.

• Various types of support documents and support are available at www.redhat.com/apps/support.

• You can query the Red Hat Knowledgebase (requires free registration) at kbase.redhat.com.

• FEDORA documentation is available at fedora.redhat.com/docs, and fedoraproject.org (click Documentation).

• RHEL+FEDORA The home pages (www.redhat.com, fedora.redhat.com, and fedoraproject.org), have a wealth of information.

• RHEL+FEDORA support forums are online discussions about any Red Hatrelated issues that people want to raise. One forum is dedicated to new users; others to Apache, the X Window System, and so on. Go to www.redhat.com/mailman/listinfo to browse the lists. Another site that has similar, useful information is fedoraforum.org.

• FEDORA information is available at fedoranews.org.

• RHEL hardware help is available from the Red Hat hardware catalog at hardware.redhat.com. The hardware that FEDORA supports is mostly a superset of that supported by RHEL.

GNU

GNU manuals are available at www.gnu.org/manual. In addition, you can visit 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.

The Linux Documentation Project

The Linux Documentation Project (www.tldp.org), which has been around for almost as long as Linux, houses a complete collection of guides, HOWTOs, FAQs, man pages, and Linux magazines. The home page is available in English, Portuguese, Spanish, Italian, Korean, and French. It is easy to use and supports local text searches. It also provides a complete set of links (Figure 4-28) that you can use to find almost anything you want that is related to Linux (click Links in the Search box or go to www.tldp.org/links). The links page includes sections on general information, events, getting started, user groups, mailing lists, and newsgroups, with each section containing many subsections.

Figure 4-28. The Linux Documentation Project home page