Linux.com Article DB: The Linux Cookbook: Chapter 2, WHAT EVERY LINUX USER KNOWS

2.8 HELP FACILITIES

Linux systems come with a lot of help facilities, including compete manuals in etext form. In fact, the foremost trouble with Linux documentation isn't that there is not enough of it, but that you have to sift through the mounds of it, trying the find the precise information you're looking for!

I describe the help facilities in the following sections; their relative usefulness for the particular kind of information you're looking for is noted.

If you find that you need more help, don't panic--other options are available. They're described in Recipe 1.3 If you Need More Help, page 16.

2.8.1 FINDING THE RIGHT TOOL FOR THE JOB

When you know what a particular tool or application does, but you can't remember it's name, use apropos. This tool takes a keyword as an argument, and it outputs a list of installed software whose one-line descriptions contain that keyword. This is also useful for finding software on your system related to, say, "audio" or "sound" or "sort" or some other such general concept.

To output a list of programs that pertain to consoles, type:

$ apropos consoles "Ret"

 console (4) - console terminal and virtual consoles

 gpm (1) - a cut and paste utility and mouse server for virtual
consoles

 $

NOTE: The apropos tool only finds exact matches, so a search for the keyword 'console' might not list the programs that a search for the keyword 'consoles' would yield, and vice versa.

Another way to find tools by keyword is to search the system manual pages (see Recipe 2.8.4 Reading a Page from the System Manual, page 30). To do this, use man and give the text to search for as an argument to the '-k' option. This searches the short descriptions and manual page names for the given text, and outputs a list of those tools that match in the same format as the apropos tool.

To output a list of all tools whose pages in the system manual contain a reference to consoles, type: $ man -k consoles "Ret"
On Debian systems, yet another way to find installed software by keyword is to use dpkg, the Debian package tool. Use the '-l' option to list all of the installed packages, which are each out put on a line of their own with their package name and a brief description.

You can output a lit of packages that match a keyword by piping the output to grep. Use the '-i' option with grep to match keywords regardless of case (grep is discussed in Chapter 14 Searching Text, page 165).

Additionally, you can directly peruse the file /var/lib/dpkg/available; it lists all available packages and gives a description of them.
To list all of the packages on the system, type: $ dpkg -1 "Ret"
To list all of the packages whose name or description contains the text "edit," regardless of case, type: $ dpkg -1 | grep -i edit "Ret"
To peruse descriptions of the packages that are available, type: $ less /var/lib/dpkg/available "Ret"

2.8.2 LISTING A DESCRIPTION OF A PROGRAM

Use whatis to list a one-line description of a program. Give the name of the tool or application to list as an argument.

To get a description of the who tool, type:

$ whatis who "Ret"

NOTE: The watis tool gets its descriptions from the manual page of a given program; manual pages are described later in this section, in Recipe 2.8.4 Reading a Page from the System Manual, page 30.

2.8.3 LISTING THE USAGE OF A TOOL

Many tools have a long-style option, '--help', that outputs usage information about the tool, including the options and arguments the tool takes.

To list the possible options for whoami, type:

$ whoami --help "Ret"

 Usage: whoami [OPTION]...

 Print the user name associated with the current effective user
id.

 Same as id -un.



 --help display this help and exit

 --version output version information and exit

 Report bugs to sh-utils-bugs@gnu.ai.mit.edu

 $

This command outputs some usage information about the whoami tool, including a short description and a list of possible options.

NOTE: Not all tools take the '--help' option; some tools take a '-h' or '-?' option instead, which performs the same function.

2.8.4 READING A PAGE FROM THE SYSTEM MANUAL

In the olden days, the hardcopy reference manual that came with most Unix systems also existed electronically on the system itself; each software program that came with the system had its own manual page (often called a "man page") that described it. This is still true on Linux-based systems today, except they don't always come with a hardcopy manual.

Use the man tool to view a page in the system manual. As an argument to man, give the name of the program whose manual page you want to view (so to view the manual page for man, you would type man man).

To view the manual page for w, type:

$ man w "Ret"

This command displays the manual page for w:

W(1) Linux Programmer's Manual W(1) NAME w - Show who is logged on and what they are doing. SYNOPSIS w - [husfV] [user] DESCRIPTION w displays information about the users currently on the machine, and their processes. The header shos, in this order, the current time, how long the system has been running, how many users are currently logged on, and the system load averages for the past 1, 5, and 15 minutes. The following entries are displayed for each user: login name, the tty name, the remote host, login time, idle time, JCPU, PCPU, and the command line of their current process. The JCPU time is the time used by all processes attached Manual page w(1) line 1

Use the up and down arrow keys to move through the text. Type q to stop viewing the manual page and exit man. Since man uses less to display the text, you can use any of the less keyboard commands to peruse the manual page (see Recipe 9.1 Perusing Text, page 111).

Despite its name, a manual page does not always contain the complete documentation to a program, but it's more like a quick reference. It usually gives a short description of the program, and lists the options and arguments it takes; some manual pages also include an example or a list of related commands. (Sometimes, commands have very complete, extensive manual pages, but more often, their complete documentation is found either in other help files that come with it or in its Info documentation; these are subjects of the following two recipes.)

To prepare a man page for printing, see Recipe 25.3.4 Preparing a Man Page for Printing, page 278.

2.8.5 USING THE GNU INFO SYSTEM

The GNU Info System is an online hypertext reference system for documentation prepared in the Info format. This documentation tends to be more complete than a typical man page, and often, the Info documentation for a given software package will be an entire book or manual. All of the manuals published by the Free Software Foundation are released in Info format; these manuals contain the same text (sans illustrations) as the paper manuals that you can purchase directly from the Free Software Foundation.

There are different ways to peruse the Info documentation: you can use the standalone info tool, read Info files in the Emacs editor (see Recipe 10.2 Emacs, page 121), or use one of the other tools designed for this purpose. Additionally, tools exist for converting Info documentation to HTML that you can read in a Web browser (see Recipe 5.9 Browsing Files, page 81)

To read the Info manual for a tool or application with the info tool, give its name as an argument. With no arguments, info opens your system's Top Info menu, which lists all of the available manuals that are installed on the system.

To view all of the Info manuals on the system, type:

$ info "Ret"

This command starts info at the system's Top menu, which shows some of the info key commands and displays a list of available manuals:

File: dir, Node: Top, This is the top of the INFO tree This (the Directory node) gives a menu of major topics. Typing "q" exits, "?" lists all Info commands, "d" returns here, "h" gives a primer for first-timers, "mEmacs<return>" visits the Emacs manual, etc.

In Emacs, you can click mouse button 2 on a menu item or cross-reference to select it.

* Menu:
Texinfo documentation system
* Info: (info). Documentation browsing system.
* Texinfo: (texinfo). The GNU documentation format.
* install-info: (texinfo) Invoking install-info Updating info/dir entries
* texi2dvi: (texinfo) Format with texi2dvi. Printing text info documentation
*textindex: (texinfo)Format with text.textindex. Sorting Textinfo index fils.
*makeinfo: (texinfo)makeinfo Prefferred. Translate Texinfo source.
----Info: (dir) Top, 211 lines --Top--------------------------------------
Welcome to Info version 2,18. "C-h" for help, "m" for menue item

Use the arrow keys to move through each \page" of information, called an Info node. Nodes are the base unit of information in Info, and are arranged hierarchically : a manual's Top node will contain an Info menu containing links to its various chapters, and a chapter node will contain a menu with links for its sections, and so on. Links also appear as cross references in the text.

Links look the same in both menu items and cross-references: an asterisk (`*'), the name of the node it links to, and either one or two colon characters (`:'). To follow a link to the node it points to, move the cursor over any part of the node name in the link and press RET.

To run a tutorial that describes how to use info, type h. Type q at any time to stop reading the documentation and exit info.

To read Info documentation for a tool or application, give its name as an argument to info; if no Info manual exists for that tool, info displays the man page for that tool instead.

To read the Info documentation for the tar tool, type:

$ info tar RET

This command opens a copy of The GNU tar Manual in info.

To read the contents of a file written in Info format, give the name of the file to read with the `-f' option. This is useful for reading an Info file that you have obtained elsewhere, and is not in the /usr/info directory with the rest of the installed Info files. Info can automatically recognize and expand Info files that are compressed and have a `.gz' file name extension (see Recipe 8.5 Compressed Files, page 102).

To read`faq.info', an Info file in the current directory, type:

$ info -f faq.info RET

This command starts info and opens the Info file `faq.info', beginning at the top node in the file.

To read a specific node in an Info file, give the name of the node to use in quotes as an argument to the`-n' option.

To read `faq.info', an Info le in the current directory, beginning with the node Text, type:

$ info -n 'Text' -f faq.info RET

NOTE: You can also read Info documentation directly from the Emacs editor; you type C-h i from Emacs to start the Info reader, and then use the same commands as in the standalone info tool (see Recipe 10.2.1 Getting Acquainted with Emacs, page 121).

The Emacs \incremental" search command, C-s, also works in info; it's a very fast, efficient way to search for a word or phrase in an entire Info text (like this entire book); see Recipe 14.6.1 Searching Incrementally in Emacs, page 173.

2.8.6 Reading System Documentation and Help Files

Debian: ` doc-linux-text ' WWW: http://linuxdoc.org

The /usr/doc directory is for miscellaneous documentation: HOWTOs, FAQs, Debian-specific documentation files and documentation files that come with commands. (To learn more about files and directories, see Chapter 5 Files and Directories, page 65.) To peruse any of these files, use less, described in full in Recipe 9.1 Perusing Text, page 111.

When a software package is installed, any additional documentation files it might have beyond a manual page and Info manual are placed here, in a subdirectory with the name of that package. For example, additional documentation for the hostname package is in /usr/doc/hostname, and documentation for the passwd package is in /usr/doc/passwd.

Most packages have a file called `README', which usually contains relevant information. Often this file is compressed as `README.gz', in which caseyou can use zless instead of less.

The Linux Documentation Project (LDP) has overseen the creation of more than 100 "HOWTO" files, each of which covers a particular aspect of the installation or use of Linux-based systems.

The LDP HOWTOs are compressed text files stored in the /usr/doc/HOWTO directory; to view them, use zless. The file /usr/doc/HOWTO/HOWTO-Index.gz contains an annotated index of all the HOWTO documents installed on the system [FOOTNOTE: LDP documents are available in other formats as well, including HTML and DVI.].

Finally, the /usr/doc/FAQ directory contains a number of FAQ (\Frequently Asked Questions") files on various subjects, and the files that make up the Debian FAQ are in the /usr/doc/debian/FAQ directory. The Debian FAQ is available both in HTML format, which you can view in a Web browser (see Recipe 5.9 Browsing Files, page 81), and as a compressed text file, which you can view in zless.

To view the HTML version of the Debian FAQ in the lynx Web browser, type:
$ lynx /usr/doc/debian/FAQ/debian-faq.html RET
To view the compressed text version of the Debian FAQ inzless, type:
$ zless /usr/doc/debian/FAQ/debian-faq.txt.gz RET

NOTE: It's often very useful to use a Web browser to browse through the documentation files in these directories (see Recipe 5.9 Browsing Files, page 81.) On some systems, /usr/doc is superseded by the /usr/share/doc directory.

As a technology correspondent with Wired News/Reuters, MICHAEL STUTZ was one of the first journalists to write about Linux and the Open Source movement in the mainstream press. He has contributed to the GNU Project and the Linux Documentation Project, and created the Design Science License (DSL), a generalized "copyleft" license designed to fit any work.

Originally Published: Tuesday, 12 June 2001	Author: Michael Stutz
Published to: learn_articles_firststep/General	Page: 5/5 - [Printable]
The Linux Cookbook: Chapter 2, WHAT EVERY LINUX USER KNOWS Today's Learn article derived from Chapter Two of the soon to be published Linux Cookbook contains a ton of useful information for the new user. Learn all kinds of useful commands and short-cuts for basic system operation, and then join author Michael Stutz as he answers your questions live in Linux.com Live! Linux.com would like to thank publisher Bill Polluck of No Starch Press for the free use of this material.

	<< Page 5 of 5
2.8 HELP FACILITIES Linux systems come with a lot of help facilities, including compete manuals in etext form. In fact, the foremost trouble with Linux documentation isn't that there is not enough of it, but that you have to sift through the mounds of it, trying the find the precise information you're looking for! I describe the help facilities in the following sections; their relative usefulness for the particular kind of information you're looking for is noted. If you find that you need more help, don't panic--other options are available. They're described in Recipe 1.3 If you Need More Help, page 16. 2.8.1 FINDING THE RIGHT TOOL FOR THE JOB When you know what a particular tool or application does, but you can't remember it's name, use apropos. This tool takes a keyword as an argument, and it outputs a list of installed software whose one-line descriptions contain that keyword. This is also useful for finding software on your system related to, say, "audio" or "sound" or "sort" or some other such general concept. To output a list of programs that pertain to consoles, type: $ apropos consoles "Ret" console (4) - console terminal and virtual consoles gpm (1) - a cut and paste utility and mouse server for virtual consoles $ NOTE: The apropos tool only finds exact matches, so a search for the keyword 'console' might not list the programs that a search for the keyword 'consoles' would yield, and vice versa. Another way to find tools by keyword is to search the system manual pages (see Recipe 2.8.4 Reading a Page from the System Manual, page 30). To do this, use man and give the text to search for as an argument to the '-k' option. This searches the short descriptions and manual page names for the given text, and outputs a list of those tools that match in the same format as the apropos tool. To output a list of all tools whose pages in the system manual contain a reference to consoles, type: `$ man -k consoles "Ret"` On Debian systems, yet another way to find installed software by keyword is to use dpkg, the Debian package tool. Use the '-l' option to list all of the installed packages, which are each out put on a line of their own with their package name and a brief description. You can output a lit of packages that match a keyword by piping the output to grep. Use the '-i' option with grep to match keywords regardless of case (grep is discussed in Chapter 14 Searching Text, page 165). Additionally, you can directly peruse the file `/var/lib/dpkg/available`; it lists all available packages and gives a description of them. To list all of the packages on the system, type: `$ dpkg -1 "Ret"` To list all of the packages whose name or description contains the text "edit," regardless of case, type: `$ dpkg -1 \| grep -i edit "Ret"` To peruse descriptions of the packages that are available, type: `$ less /var/lib/dpkg/available "Ret"` 2.8.2 LISTING A DESCRIPTION OF A PROGRAM Use whatis to list a one-line description of a program. Give the name of the tool or application to list as an argument. To get a description of the who tool, type: `$ whatis who "Ret"` NOTE: The watis tool gets its descriptions from the manual page of a given program; manual pages are described later in this section, in Recipe 2.8.4 Reading a Page from the System Manual, page 30. 2.8.3 LISTING THE USAGE OF A TOOL Many tools have a long-style option, '--help', that outputs usage information about the tool, including the options and arguments the tool takes. To list the possible options for whoami, type: $ whoami --help "Ret" Usage: whoami [OPTION]... Print the user name associated with the current effective user id. Same as id -un. --help display this help and exit --version output version information and exit Report bugs to sh-utils-bugs@gnu.ai.mit.edu $ This command outputs some usage information about the whoami tool, including a short description and a list of possible options. NOTE: Not all tools take the '--help' option; some tools take a '-h' or '-?' option instead, which performs the same function. 2.8.4 READING A PAGE FROM THE SYSTEM MANUAL In the olden days, the hardcopy reference manual that came with most Unix systems also existed electronically on the system itself; each software program that came with the system had its own manual page (often called a "man page") that described it. This is still true on Linux-based systems today, except they don't always come with a hardcopy manual. Use the man tool to view a page in the system manual. As an argument to man, give the name of the program whose manual page you want to view (so to view the manual page for man, you would type man man). To view the manual page for w, type: `$ man w "Ret"` This command displays the manual page for w: W(1) Linux Programmer's Manual W(1) NAME w - Show who is logged on and what they are doing. SYNOPSIS w - [husfV] [user] DESCRIPTION w displays information about the users currently on the machine, and their processes. The header shos, in this order, the current time, how long the system has been running, how many users are currently logged on, and the system load averages for the past 1, 5, and 15 minutes. The following entries are displayed for each user: login name, the tty name, the remote host, login time, idle time, JCPU, PCPU, and the command line of their current process. The JCPU time is the time used by all processes attached Manual page w(1) line 1 Use the up and down arrow keys to move through the text. Type q to stop viewing the manual page and exit man. Since man uses less to display the text, you can use any of the less keyboard commands to peruse the manual page (see Recipe 9.1 Perusing Text, page 111). Despite its name, a manual page does not always contain the complete documentation to a program, but it's more like a quick reference. It usually gives a short description of the program, and lists the options and arguments it takes; some manual pages also include an example or a list of related commands. (Sometimes, commands have very complete, extensive manual pages, but more often, their complete documentation is found either in other help files that come with it or in its Info documentation; these are subjects of the following two recipes.) To prepare a man page for printing, see Recipe 25.3.4 Preparing a Man Page for Printing, page 278. 2.8.5 USING THE GNU INFO SYSTEM The GNU Info System is an online hypertext reference system for documentation prepared in the Info format. This documentation tends to be more complete than a typical man page, and often, the Info documentation for a given software package will be an entire book or manual. All of the manuals published by the Free Software Foundation are released in Info format; these manuals contain the same text (sans illustrations) as the paper manuals that you can purchase directly from the Free Software Foundation. There are different ways to peruse the Info documentation: you can use the standalone info tool, read Info files in the Emacs editor (see Recipe 10.2 Emacs, page 121), or use one of the other tools designed for this purpose. Additionally, tools exist for converting Info documentation to HTML that you can read in a Web browser (see Recipe 5.9 Browsing Files, page 81) To read the Info manual for a tool or application with the info tool, give its name as an argument. With no arguments, info opens your system's Top Info menu, which lists all of the available manuals that are installed on the system. To view all of the Info manuals on the system, type: `$ info "Ret"` This command starts info at the system's Top menu, which shows some of the info key commands and displays a list of available manuals: `File: dir, Node: Top, This is the top of the INFO tree This (the Directory node) gives a menu of major topics. Typing "q" exits, "?" lists all Info commands, "d" returns here, "h" gives a primer for first-timers, "mEmacs<return>" visits the Emacs manual, etc.` In Emacs, you can click mouse button 2 on a menu item or cross-reference to select it. * Menu: Texinfo documentation system * Info: (info). Documentation browsing system. * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo) Invoking install-info Updating info/dir entries * texi2dvi: (texinfo) Format with texi2dvi. Printing text info documentation textindex: (texinfo)Format with text.textindex. Sorting Textinfo index fils. makeinfo: (texinfo)makeinfo Prefferred. Translate Texinfo source. ----Info: (dir) Top, 211 lines --Top-------------------------------------- Welcome to Info version 2,18. "C-h" for help, "m" for menue item Use the arrow keys to move through each \page" of information, called an Info node. Nodes are the base unit of information in Info, and are arranged hierarchically : a manual's Top node will contain an Info menu containing links to its various chapters, and a chapter node will contain a menu with links for its sections, and so on. Links also appear as cross references in the text. Links look the same in both menu items and cross-references: an asterisk (`'), the name of the node it links to, and either one or two colon characters (`:'). To follow a link to the node it points to, move the cursor over any part of the node name in the link and press RET. To run a tutorial that describes how to use info, type h. Type q at any time to stop reading the documentation and exit info. To read Info documentation for a tool or application, give its name as an argument to info; if no Info manual exists for that tool, info displays the man page for that tool instead. To read the Info documentation for the tar tool, type: `$ info tar RET` This command opens a copy of The GNU tar Manual in info. To read the contents of a file written in Info format, give the name of the file to read with the `-f' option. This is useful for reading an Info file that you have obtained elsewhere, and is not in the `/usr/info` directory with the rest of the installed Info files. Info can automatically recognize and expand Info files that are compressed and have a `.gz' file name extension (see Recipe 8.5 Compressed Files, page 102). To read`faq.info', an Info file in the current directory, type: `$ info -f faq.info RET` This command starts info and opens the Info file `faq.info', beginning at the top node in the file. To read a specific node in an Info file, give the name of the node to use in quotes as an argument to the`-n' option. To read `faq.info', an Info le in the current directory, beginning with the node Text, type: `$ info -n 'Text' -f faq.info RET` NOTE: You can also read Info documentation directly from the Emacs editor; you type C-h i from Emacs to start the Info reader, and then use the same commands as in the standalone info tool (see Recipe 10.2.1 Getting Acquainted with Emacs, page 121). The Emacs \incremental" search command, C-s, also works in info; it's a very fast, efficient way to search for a word or phrase in an entire Info text (like this entire book); see Recipe 14.6.1 Searching Incrementally in Emacs, page 173. 2.8.6 Reading System Documentation and Help Files Debian: ` doc-linux-text ' WWW: http://linuxdoc.org The `/usr/doc` directory is for miscellaneous documentation: HOWTOs, FAQs, Debian-specific documentation files and documentation files that come with commands. (To learn more about files and directories, see Chapter 5 Files and Directories, page 65.) To peruse any of these files, use less, described in full in Recipe 9.1 Perusing Text, page 111. When a software package is installed, any additional documentation files it might have beyond a manual page and Info manual are placed here, in a subdirectory with the name of that package. For example, additional documentation for the hostname package is in `/usr/doc/hostname`, and documentation for the passwd package is in `/usr/doc/passwd`. Most packages have a file called `README', which usually contains relevant information. Often this file is compressed as `README.gz', in which caseyou can use zless instead of less. The Linux Documentation Project (LDP) has overseen the creation of more than 100 "HOWTO" files, each of which covers a particular aspect of the installation or use of Linux-based systems. The LDP HOWTOs are compressed text files stored in the `/usr/doc/HOWTO` directory; to view them, use zless. The file `/usr/doc/HOWTO/HOWTO-Index.gz` contains an annotated index of all the HOWTO documents installed on the system [FOOTNOTE: LDP documents are available in other formats as well, including HTML and DVI.]. Finally, the `/usr/doc/FAQ` directory contains a number of FAQ (\Frequently Asked Questions") files on various subjects, and the files that make up the Debian FAQ are in the `/usr/doc/debian/FAQ` directory. The Debian FAQ is available both in HTML format, which you can view in a Web browser (see Recipe 5.9 Browsing Files, page 81), and as a compressed text file, which you can view in zless. To view the HTML version of the Debian FAQ in the lynx Web browser, type: `$ lynx /usr/doc/debian/FAQ/debian-faq.html RET` `To view the compressed text version of the Debian FAQ inzless, type:` `$ zless /usr/doc/debian/FAQ/debian-faq.txt.gz RET` NOTE: It's often very useful to use a Web browser to browse through the documentation files in these directories (see Recipe 5.9 Browsing Files, page 81.) On some systems, `/usr/doc` is superseded by the `/usr/share/doc` directory. As a technology correspondent with Wired News/Reuters, MICHAEL STUTZ* was one of the first journalists to write about Linux and the Open Source movement in the mainstream press. He has contributed to the GNU Project and the Linux Documentation Project, and created the Design Science License (DSL), a generalized "copyleft" license designed to fit any work.
	<< Page 5 of 5