Getting the Facts: Where to Find Documentation

 < Day Day Up > 

Distributions of 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. With the growth of Linux 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 Linux.

The help Option

Most GNU utilities have a help option that displays information about the utility.

 $ 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 31) using a pipe:

 $ ls --help | less 

More information about pipes appears on page 52. Non-GNU utilities may use a h or help option to display help information.

Figure 2-1. The man utility displaying information about who
 WHO(1)                       User Commands                      WHO(1) NAME     who - show who is logged on SYNOPSIS     who [OPTION]... [ FILE | ARG1 ARG2 ] DESCRIPTION     -a, --all            same as -b -d --login -p -r -t -T -u     -b, --boot            time of last system boot     -d, --dead            print dead processes     -H, --heading            print line of column headings     -i, --idle            add idle time as HOURS:MINUTES, . or old (deprecated, use -u) 

man: Displays the System Manual

The 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 basically what a utility does.

To find out more about a utility, including the man utility itself, give the command man, followed by the name of the utility. Figure 2-1 shows the output of a man who command.

less (pager)

The command man man displays information about the man utility. The man utility automatically sends the output through a pager, usually less (page 45), which allows you to view a file one screen at a time. When you display 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 man and causes the shell to display a prompt. You can search for topics covered by man pages by using the apropos utility (page 62).

Manual sections

Based on the FHS (Filesystem Hierarchy Standard, page 86), 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. Local

  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 provide 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.

In some cases the manual contains entries for different tools with the same name. For example, the following command displays the manual page for the write utility (page 67) 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 

The preceding 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 (with some exceptions). The option appears following the name of the utility you are calling and a SPACE. Any other arguments (861) to the command follow the option and a SPACE. For more information refer to "Options" on page 109.


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 and distributed with Linux. 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 Linux shells, utilities, and programs developed by the GNU project (page 2). Figure 2-2 shows the screen that info displays when you give the command info.

Figure 2-2. The first screen that info displays


Because the information on this screen is drawn from an editable file, your display may differ. When you see 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 for which information is available

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

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

After giving the command info, press the SPACE bar a few times to scroll the display. Figure 2-3 shows the entry for sleep. 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, followed by 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.

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


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. To get information on sleep, for example, you give the command m sleep, 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 sleep displays sleep on that line, and pressing RETURN takes you to the menu item you have chosen.

Figure 2-4 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 get to the next node, press n. Press p to get to the previous node. You can always press d to display the initial menu (Figure 2-2).

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


As you read 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). Better yet, use a browser to look at the documentation at www.tldp.org and print the information from the browser.

HOWTOs: Finding Out How Things Work

A HOWTO document explains in detail how to do something related to Linux from 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, yet many people contribute to it.

The Linux Documentation Project (LDP, page 35) 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. Or use the LDP search feature on its home page to find HOWTOs and more.

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). Enclose the error message within double quotation marks to improve the quality of your results. You will likely find a post concerning your problem and how to solve it. See Figure 2-5.

Figure 2-5. Google reporting on an error message


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.

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 and is easy to use, supporting local text searches. It also has a complete set of links (Figure 2-6) that can help you 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, each containing many subsections.

Figure 2-6. The Linux Documentation Project home page


     < Day Day Up > 


    A Practical Guide to LinuxR Commands, Editors, and Shell Programming
    A Practical Guide to LinuxR Commands, Editors, and Shell Programming
    ISBN: 131478230
    EAN: N/A
    Year: 2005
    Pages: 213

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net