The Command Manual

As it is humanly impossible to memorize the syntax of hundreds of commands, most executable programs intended for command-line use provide a formal piece of documentation called a manual.

Although manual pages may vary in their format, they generally contain:

• The command's name and summary.
• A synopsis.
• A detailed description.
• A list of options.
• A list of exit statuses.

Here is for example, an excerpt of the echo command's manual page:

NAME
     echo – write arguments to the standard output

SYNOPSIS
     echo [-n] [string ...]

DESCRIPTION
     The echo utility writes any specified operands, separated by single blank (' ') characters
     and followed by a newline ('\n') character, to the standard output.

     The following option is available:

     -n    Do not print the trailing newline character.

EXIT STATUS
     The echo utility exits 0 on success, and >0 if an error occurs.

Displaying a command's manual page

There are essentially two commands you can use to display the documentation page of a shell command: man and help.

The man command

To consult the manual page of a command, you can use the man command:

$ man command

Where command is the name of the command.

Upon execution, this will open a paging program in which you can use:

• The down arrow key to scroll the page down.
• The up arrow key to scroll the page up.
• The q key to quit the program and come back to your shell session.

Note: Manual pages almost never include examples and are intended as a reference, not a tutorial.

Example

For example, this command will display the echo command's manual page:

$ man echo

The help command

It will sometimes happen that when trying to open the manual page of a command, the shell opens the following special page instead:

NAME
     builtin, !, %, ., :, @, {, }, alias, alloc, bg, bind, bindkey, break, breaksw, builtins, case, cd,
     chdir, command, complete, continue, default, dirs, do, done, echo, echotc, elif, else, end, endif,
     endsw, esac, eval, exec, exit, export, false, fc, fg, filetest, fi, for, foreach, getopts, glob,
     goto, hash, hashstat, history, hup, if, jobid, jobs, kill, limit, local, log, login, logout, ls-F,
     nice, nohup, notify, onintr, popd, printenv, pushd, pwd, read, readonly, rehash, repeat, return,
     sched, set, setenv, settc, setty, setvar, shift, source, stop, suspend, switch, telltc, test, then,
     time, times, trap, true, type, ulimit, umask, unalias, uncomplete, unhash, unlimit, unset, unsetenv,
     until, wait, where, which, while -- shell built-in commands

This behavior is completely normal as it indicates that you are trying to access a builtin's manual page, which is a functionality that is built into the source code of the shell, unlike executables, which are standalone programs installed independently from your shell.

To display the usage information of a builtin, you can use the help command:

$ help builtin

Where builtin is the name of the builtin command.

Example

For example, this command will display the cd builtin's usage information:

$ help cd

Note: While different shells may implement the same builtin commands, their usage and behavior may differ from one another.

RTFM

Most of the commands that will be introduced in this program often have dozens, if not hundreds of options.

As it is impossible to describe all of them, I encourage you to systematically consult their documentation pages using the man and help commands.

Reading a command synopsis

A command synopsis is a brief summary of a command's interface that explains how to use the command, its flags, and pass arguments.

The general rules for reading a synopsis are:

• The boldface indicates that the text must be written as-is.
• The brackets [] indicate that the content is optional.
• The vertical bar | indicates a choice list.
• The ellipsis ... indicates a repeatable parameter.

Example

For example, let's consider the synopsis of the echo command:

echo [-n] [string ...]

Where:

• The -n flag is surrounded by brackets, which means that it is optional.
• The string parameter is surrounded by brackets, which means that it is optional.
• The ellipsis ... after the string parameter indicates that the string argument can eventually be repeated several times.

In short, this synopsis reads as: "The echo command has one optional flag -n and takes zero or more strings as arguments".

This means that the echo command can be executed the following ways:

$ echo

$ echo -n
$ echo Hello
Hello
$ echo Hello World
Hello World
$ echo -n Hello
Hello$

Summary

Here's a summary of what you've learned in this lesson:

• Shell programs provide a formal piece of documentation called a manual.
• The man command is used to open the manual page of shell executables.
• The help command is used to display the usage information of shell builtins.