3 Getting help from the system itself

In this chapter you’ll be introduced to:

• the manual pages and the GNU Info, the two primary documentation systems which should be built into any Unix system
• the --help option provided by almost all the command line tools and the help command of the shell
• command completion and command history - two features which greatly simplify your typing.

3.1 The manual pages

The original UNIX Programmer’s Manual documents the sytem divided into nine sections: Section 1 deals with the commands for the end user, the commands we discuss in this course. Incidentally games too were a part of the system, section 6 contains information on games. The remaining sections handle details which are aimed for the programmer and the system administrator. This documentation was always a part of the system.

The man program searches, formats, and displays the information contained in those manual pages. Because many topics have a lot of information, output is piped through a terminal pager program for convenient viewing one page at a time; at the same time the information is formatted for a good visual display. You can call man just by giving the name of the program which would like to know more about. For example:

The output says that the page is from section 1 ’User Commands’ and explains its usage.

Note that the man pages have a well defined structure, part of which is listed in next table. Thanks to their structure the man pages can be automatically converted to HTML, to book form or to graphical help programs. You will encounter them if you continue working in the shell after the course, but during this course we expect you to refer the local man pages with the help of man.

For reading long manual pages on screen man delivers them through a pager, which depends on the Unix flavour. The pager used in Linux is called less. You navigate in less with single key strokes: f, Ctrl+f or space bar to scroll page-wise forward or b, Ctrl+b, or Shift+space to scroll back and ’q’ for quit. The key ’h’ gives your the the full list of commands.

Another useful key is / (forward slash), the search key. Often all you need to know is what a specific option of a command does, for example what ’uname -s’ really means. In such cases just call ’man uname’ and then press / - s. If the first hit is not the one you were looking for, keep on pressing n (for next).

Exercise. Call the man pages of the commands you already know and note down options you find interesting. Don’t forget ’man man’ too!

By default the man command prints only the dedicated page specifically about the topic. You can broaden this to view all man pages containing a particular string in their name by using the -f option. The following dialog shows that there is only one date command whereas there are two time commands.

You select the section of the manual by giving its number as an optin:

You get the same effect of ’man -f’ by the command whatis.

A common problem with the man command is that you need to know the name of the command you want to know more about. The -k option broaden the search by including all commands whose description contains the search string:

The apropos command is equivalent to ’man -k’:

3.2 GNU info

The GNU Project distributes most of its on-line manuals in the Info format, which is more free-form than man pages. Functionally, the GNU Info System resembles man in many ways. However, topics are connected using links (even though its design predates the World Wide Web). There are two primary Info readers: the text-based program info designed just for this purpose and the ’info’ package in GNU Emacs, which supports using a mouse. In this course we look at info only.

Typing ’info’ in a terminal with no arguments displays an index of the available topics. You can browse through the topic list using the regular movement keys: arrows, Page-Up, and Page-Down.

You can view the documentation for a particular topic by typing ’info topic’. The system then searches for the topic in all available info files. Some useful keys are: h for help, and Enter to select a menu item and q for quit.

The topic which you view in the info page is called a node. Nodes are similar to sections and subsections in written documentation. You can move between nodes or view each node sequentially. Each node may contain menus and linked subtopics, or items.

Items can be compared to Internet hyperlinks. They are identified by an asterisk (*) at the beginning of the item name. Named items (outside a menu) are identified with double-colons (::) at the end of the item name. Items can refer to other nodes within the file or to other files. The folloing table lists the basic keystrokes for moving between nodes.

3.3 The help option

The third source of Linux documentation is to use the help option.

Most commands have short help screen available which can be viewed using the –help or the -h option along with the command or application. For example, to learn more about the uname command, you can run:

The help option is useful as a quick reference and it displays information faster than the man or info pages.

3.4 The help command

Some popular shell commands (such as echo) silently run their own built-in versions of system programs or utilities, because it is more efficient to do so. To view a synopsis of these built-in commands, you can use the help command of the shell.

To get a list of the available topics, just run help. For these built-in commands, help performs the same basic function as the -h and –help arguments (which we will discuss shortly) perform for stand-alone programs.

3.5 Command completion, command history

Most of the Unix shells have a feature called command completion. If for example you know only the beginning of a command, let’s say ’up’ for ’uptime’, you can type ’up’ and then press the Tab-key. Since there are many commands which starts with ’up’ the shell will not react. Press the Tab-kay a second time and it will list all the available commands which start with ’up’.

On the other hand, if what you typed unique, the shell will immediately complete the command once you press the Tab-kay.

The same thing with file names. You can start typing a file name and then press Tab for the shell to complete it.

Another very useful feature to minimize typing is the command history. In its simplest form, just press the Up-arrow for the shell to bring the stack of previous commands one-by-one.

3.6 Assignment for the week

Take the test in the course platform:

• All the MC questions have a single correct answer.
• The fill-in fields expect a single word, the case (simple or capitol) is important.
• There is no time limit for the test.
• You have three attempts. The best score counts.

Allowed material: You are allowed to consult only the course lecture note and the help built in to the shell of the Raspberry Pi you are working in.

Hint: You can open two terminals to your training computer at the same time. In one you can consult the built-in documentation and in the other test your answers to the questions.

Summary

• The main sources of Linux documentation are the manual pages, the GNU Info documents, the –help option and the help command.
• The man utility searches, formats, and displays man pages.
• The manual pages provide in-depth documentation about programs and other topics about the system including configuration files, system calls, library routines, and the kernel.
• The GNU Info is the starndard documentation system of the GNU project. Its nodes are hyperlinked and accessible via command line, web, and graphical tools using Info.
• Short descriptions for commands are usually displayed with the –help argument.
• The help command displays a synopsis of the commands built-in to the shell.
• The Tab-key and the Up-arrow greatly simplfy the typing: the former auto-completes program and file names, the latter brings up previous commands from the command buffer.