This article explains in detail how to utilize the extensive Help resources found in SUSE Linux, as well as how to use many standard commands. It is a actually a book chapter, entitled "Getting Help" from a new book called Linux Starter Kit: Everything you need to start using Linux today.. The book's author is Emmett Dulaney; its publisher is Sams Publishing. It consists of a full DVD version of SUSE Linux 10.1 and a Quick Start guide. The Linux Starter Kit is available at booksellers now.

Those who are new to the operating system often complain of the legions of commands that exist and how you must know when to use this one or that one and what options/parameters to use with it. The truth of the matter is that it is extremely rare to find a utility or feature that is not well documented in at least one location.

SUSE Linux has added to the inherent robustness of the help system by adding the SUSE Help Center directly to the KDE and GNOME desktop panels. Simply click on the icon of the lizard with a life preserver around it, and the Help Center opens.

Figure 6.1 Clicking the icon opens the SUSE Help Center.

Figure 6.2 The SUSE Help Center offers help for common problems.

You can use the search feature to find information, or click through the Contents or Glossary to find what you are looking for.

---

Note - In addition to the standard set, many vendors add their own documentation or utilities for simplifying the process of solving problems with their packages and applications.

---

From a command line/shell prompt, a number of methods are available for finding help on the operation of utilities. The most commonly used of these are

• man
• info
• –help
• Local Documentation

The following sections walk through these.

Using the man Utility

The man (as in manual) utility dates back to the early days of UNIX. Using whatever page utility is defined in the user's environmental variables for PAGER, it displays document files found beneath the subdirectories included in the MANPATH variable. The PAGER variable is usually equal to less on SUSE, but can also be equal to more. The MANPATH variable usually includes /usr/share/man, /usr/local/man, /usr/X11R6/man, and /opt/gnome/share/man, but can include others as well.

Although there are a number of directories beneath /usr/share/man, the main ones–and their purposes–include the directories listed in Table 6.1.

Table 6.1 Subdirectories of /usr/share/man

When you enter the command to display a manual page (man), these subdirectories are searched until the first match is found. For example, if you entered the following command:

man nice

The directories would be searched until the first match of a manual page describing nice is found. When the manual page is found, it is displayed using the utility specified by the PAGER variable. An example of the output follows (line numbering has been added to aid the discussion):

1.  NICE(1)          User Commands          NICE(1)
2.  NAME
3.  nice–run a program with modified scheduling priority
4.  SYNOPSIS
5.  nice [OPTION] [COMMAND[ARG]...]
6.  DESCRIPTION
7.  Run COMMAND with an adjusted scheduling priority. With no
8.  COMMAND, print the current scheduling priority. ADJUST is
a.  by default. Range goes from -20 (highest priority) to
9.  19 (lowest).
10.  -n, –adjustment=ADJUST
11.  increment priority by ADJUST first
12.  –help display this help and exit
13.  –version
14.  output version information and exit
15.  AUTHOR
16.  Written by David MacKenzie.
17.  REPORTING BUGS
18.  Report bugs to <bug-coreutils@gnu.org>.
19.  COPYRIGHT
20.  Copyright © 2004 Free Software Foundation, Inc.
21.  This is free software; see the source for copying condi–
22.  tions. There is NO warranty; not even for MERCHANTABILITY
23.  or FITNESS FOR A PARTICULAR PURPOSE.
24.  SEE ALSO
25.  The full documentation for nice is maintained as a Texinfo
26.  manual.  If the info and nice programs are properly
27.  installed at your site, the command
28.  info coreutils nice
29.  should give you access to the complete manual.
30.  nice 5.2.1         June 2004           NICE(1)

The nice utility is pretty straightforward and does not have an unlimited number of options, and thus makes it a good choice for dissecting as an example of the output available from man. Using the more or less utilities to display the page (whichever is defined by the PAGER variable), you can move through the documentation in a number of ways after the first screen appears, as shown in Table 6.2.

Table 6.2 Navigating with the more and less Utilities

Let's examine the actual display: Line 1 gives the name of the utility and the parentheses identify what subdirectory the documentation is coming from. In this case, the 1 indicates that it is a shell utility or user command that the documentation was found for and displayed. If there is documentation for other entities named "nice" as well, they will not be displayed, as the default action is to only display the first entity found.

To see whether there is more than one set of documentation on the system by the same name, you can use the whatis command:

$ whatis nice
nice (1)  - run a program with modified scheduling priority
nice (2)  - change process priority
nice (1p)  - invoke a utility with an altered nice value
nice (3p)  - change the nice value of a process
$

In this case, it turns out that there is another set of documentation for nice under man2 and more under 1p and 3p as well. The list displayed comes from a whatis database. To see the second set of documentation instead of the first, the command would be

man 2 nice

The value within the parentheses specifies the man section. This command specifies that you want the documentation for nice from the man2 directory (3 would be used for man3, 4 for man4, and so on).

Other lines of the manual file begin sections for Name, Synopsis, Description, and Options, respectively. Based on the complexity of the utility and other features, there can also be sections for See Also, Diagnostics, Files, Bugs, History, and Author sections.

The third line is a short synopsis in and of itself of what the utility does, and matches the line returned by the whatis utility. Other lines describe the options that can be used and go into more detail on the workings of each.

Various options that can be used with man (which could be ascertained with the command man man) include the following:

• -a to display all pages matching the text given and not quit after the first (matches are not found using the whatis database but by checking the subdirectories).
• -k to show all the manual pages with the same name (as found in the whatis database) and not stop after displaying the first. You can use -K to search the contents of the entire page.
• -M to specify the path to check (versus all subdirectories of /usr/man).
• -P to specify a different pager to use. The default in SLES 9 is less, but you can change this with this option. Whatever you specify here will override the setting that exists for the $PAGER variable.

Within Konqueror you can also use the help features through HTML links. To read the man page for nice, for example, enter this address:

man:nice

Click on the link to the man page you want to see and you can read the information within the browser.

Figure 6.3 You can access the same documentation through the browser available at the command line.

Getting Info

The info utility can be used to display documentation on the GNU utilities. The syntax is either

info

or

info { utility name} 

If info is called with no utility name following, it shows a main menu screen similar to the one shown here.

Figure 6.4 The opening of the info menu.

As the display states, you are really looking at the top (head) of a file named dir. This file contains a list of all the utilities for which the info command works, broken into sections (Miscellaneous, GNU file utilities, programming languages, and so on). Following each asterisk is the name of the item and within each set of parentheses is the text you would type to see the entry for that item. For example, to see the info for Bash, at the command line you would type

$ info bash

Within the menu, you can also press m to open a menu prompt, and then type the shortcut string ("bash" in this case). The first screen lists the commands to know to navigate within the tool (h, d, and so on) and their functions. The down arrow is used to scroll through the list one line at a time, and the Enter key selects that entry and shows you the information on it. The files are in hypertext format, so more often than not, making one selection will lead you to another menu.

To illustrate, you can use the down arrow to scroll through the list to this line:

* Gzip:(gzip).   The gzip command for compressing files.

Then when you press Enter, the menu of options specific to gzip will open.

Figure 6.5 The info display for the gzip utility.

From here, you would make your selection and choose to read the information relevant to what you are attempting to accomplish. Pressing q will quit, or pressing d will take you back to the main menu.

Other key combinations that work within info are summarized in Table 6.3. Just as files for the manual documentation reside beneath /usr/share/man, the files for the info utility reside beneath /usr/share/info.

---

Note - Notice the two empty colons following each choice on the gzip submenu. This means that you cannot type info followed by any shortcut text to arrive at that location. Very rarely is shortcut text available for use on anything but the main menu.

---

Table 6.3 Navigating Within info

Using --help

As was shown in the manual entry for nice, with many utilities and commands, you can follow the name of the utility with --help. This will provide very terse online help for the utility, showing syntax only, for example:

$ nice --help
Usage: nice [OPTION]... [COMMAND [ARG]...]
Run COMMAND with an adjusted scheduling priority.
With no COMMAND, print the current scheduling priority. ADJUST is 10
by default. Range goes from -20 (highest priority) to 19 (lowest).
 -ADJUST          increment priority by ADJUST first
 -n, --adjustment=ADJUST  same as -ADJUST
   --help        display this help and exit
   --version       output version information and exit
Report bugs to <bug-coreutils@gnu.org>
$

This is a much-abbreviated version of only some of the manual entry. Whether or not the help is there in this manner depends on the programmer creating the utility. Most of the newer (and GNU) utilities and commands do include the –help option, but it is far from a standard and rare with older utilities, and rarely available with applications.

Finding Local Documentation

Other locations where you can find documentation, such as whitepapers and release notes, locally include the subdirectories beneath /usr/share/doc. This directory contains a number of subdirectories, and the key ones for you to know are the following:

• manual–Contains the SLES administration manual–usually in both PDF and HTML formats.
• packages–The documentation for packages is located beneath subdirectories under here.
• release-notes–Contains HTML and RTF versions of the release notes.

Other local documentation that exists is depends on vendor applications installed. Always look under packages first to see if the information on them is located there. In many applications, you can press F1 to obtain help as well.

Finding Remote Resources

In addition to the resources available locally, numerous other resources are also available across the Internet. These resources can be divided into two categories: web sites and newsgroups. The former provide static information that may change daily or infrequently, but allow you to obtain information without providing any specific interaction. Newsgroups, on the other hand, consist of ongoing threads of communication between individuals who decide to participate. You can post a question specific to your situation in a newsgroup and (hopefully) have it answered by one or more knowledgeable individuals attempting to help. You would never use a newsgroup to post a common question to which the answer could easily be found elsewhere.

Table 6.4 lists sites that provide Linux or utility-oriented resources. As the Internet is a constantly changing entity, it is possible that in the future not all sites listed here will still exist, or that newer and better sites will come into being: Never underestimate the power of a good search engine in informing you of both.

Table 6.4 Internet Resources

Even though the site may be for a software vendor, or for a version of Linux other than what you are running, you should never dismiss checking the site. The simple reason for this is that many of the Linux sites post FAQs and help files for the operating system in general in addition to promoting their products.

The following newsgroups can be invaluable aids in solving specific problems you may be experiencing. The wonderful thing about newsgroups is that most of the time their names are self-explanatory, and this can prevent you from posting a question in the wrong location:

• comp.os.linux.advocacy
• comp.os.linux.announce.html
• comp.os.linux.answers
• comp.os.linux.development.apps
• comp.os.linux.development.system
• comp.os.linux.hardware
• comp.os.linux.misc
• comp.os.linux.networking
• comp.os.linux.setup
• comp.os.linux.x

There are also Linux mailing lists you can subscribe to in order to see email threads on particular topics. To subscribe, send a message to majordomo@vger.rutgers.edu with the topic "subscribe" and the name of the mailing list from the following list. Again, the names are self-explanatory:

• linux-admin
• linux-alpha
• linux-apps
• linux-c-programming
• linux-config
• linux-doc
• linux-kernel
• linux-laptop
• linx-newbie
• linux-sound
• linux-standards

© Copyright 2006 Pearson Education. All rights reserved.