intro -- introduction to reference pages

Reference Pages introduction to reference pages	Introduction

DESCRIPTION

A description of an individual topic (for example, a command) is loosely called the reference page for that topic, even if it is actually several pages long. This reference page describes the parts of a reference page with examples taken from real MKS Toolkit reference pages. Any of these parts may be omitted if they are irrelevant to the software being described.

The reference pages are divided into four categories:

Commands and Utilities
Functions
File Formats
Miscellaneous

Each reference page is made up of several sections, although not all reference pages contain all references. The remainder of this reference page describes each of these sections:

The NAME Section

The NAME section provides the name of the command and a brief functional description.

The SYNOPSIS Section

In the reference page for a command, the SYNOPSIS section provides a quick summary of the command's format. For example, here is the synopsis of the ls command.

ls [-AabCcdFfgikLlmnopqRrstux1] [-X attr] [pathname...]

The synopsis takes the form of a command line as you might type it into the system; it shows what you can type in and the order in which you should do it. The parts that are enclosed in square brackets are optional; you may omit them if you choose. Parts that are not enclosed in square brackets must be present for the command to be correct.

The synopsis begins with the name of the command itself. In MKS Toolkit documentation, command names are always written in bold Courier font.

After the command name comes a list of options, if there are any. A typical MKS Toolkit command option consists of a dash (-) followed by a single character, usually an uppercase or lowercase letter. For example, you might have -l or -t. If you are going to specify several options for the same command, you can put all the option characters after the same dash; for example,

ls -l -t
ls -lt
ls -t -l
ls -tl

are all equivalent.

The synopsis line shows options in bold Courier font. Note that the case of letters is important; for example, in the synopsis of ls, -f and -F are different options, with different effects.

In the description of ls, all options are shown in one long string after the single dash. Another common option form is

-x value

where -x is a dash followed by a character, and value provides extra information for using that option. For example, the sort command takes unsorted input and sorts it; here's the command's synopsis:

sort [-cmu] [-o outfile] [-tchar] [-yn] [-zn] [-bdfiMnr]
     [-k startpos[,endpos]] ...  [file ...]

In this example, there is the option

-o outfile

This option tells the sort command where to save its sorted output. The form of the option is -o, followed by a space, followed by outfile. In a command synopsis, anything appearing in italics is a placeholder for information that you are expected to supply. Sometime after the synopsis, the reference page explains what kind of information is expected in place of the placeholder. In the sort example, outfile stands for the name of a file where you want sort to store its output. For example, if you wanted to store the output in the file sorted.dat, you would specify

sort -o sorted.dat

(followed by the rest of the command).

Notice that the synopsis for sort also contains an option of the form

-tchar

This is similar to the option form just discussed, except that there is no space between the -t and char. As before, char in italics is a placeholder; in this case, it stands for any single character. If you want to use the -t option for sort, you just type -t followed immediately by another character, as in

sort -t:

In this case, a colon (:) is specified in the position of the placeholder char.

The end of the sort synopsis is

[file ...]

This means a list of one or more file names; the ellipsis (...) stands for repetitions of whatever immediately precedes it. Since there are square brackets around the previous list, the list can be omitted if you like.

The synopsis of ls ended in

[pathname ...]

As you might guess, this means that an ls command may end with an optional list of one or more path names. The difference between this and a sort example is that pathname may be the name of either a file or a directory; file is always the name of a file.

The order of items on the command line is important. When you type in a command line, you should specify the parts of the command line in the order they appear in the command synopsis. The exceptions to this are options marked with a -; they do not have to be given in the exact order shown in the synopsis. However, all the - options must appear in the correct area of the command line. For example, you can specify

ls -l -t myfiles
ls -t -l myfiles

but you will not get correct results if you specify

ls myfiles -l -t           ***incorrect***
ls -l myfiles -t           ***incorrect***

and so on. If you type the last command, for example, ls interprets -t as the path name of a file or directory and the command tries to list the characteristics of that item.

As a special notation, most MKS Toolkit commands let you specify -- to separate the options from the non-option arguments; -- means: "There are no more options." Thus if you really have a directory named -t, you could specify

ls -- -t

to list the contents of that directory.

The DESCRIPTION Section

The DESCRIPTION section describes what the command does and how each option works. For particularly complex software, this section may be divided into a large number of subsections, each dealing with a particular aspect of the command.

The description section often mentions the standard input and the standard output. The standard input is usually the terminal keyboard; the standard output is usually the display screen. The process of redirection can change this. Redirection is explained in the Using the MKS KornShell document and in the File Descriptors and Redirection section of the sh reference page.

Inside the DESCRIPTION section, the names of files and directories are written in normal Courier font. The names of environment variables are written in italic Courier font.

The EXAMPLES Section

The EXAMPLES section is present in many reference pages, giving examples of how the software can be used. This section tries to provide to a mix of simple examples that show how the command works on an elementary level, and more complex examples that show how the command can perform complicated tasks.

The ENVIRONMENT VARIABLES Section

The ENVIRONMENT VARIABLES section lists the environment variables, if any, that affect the command and describes the purposes that those variables serve. For example, the ls reference page lists two environment variables COLUMNS and TZ and informs you that COLUMNS is the terminal width and that TZ contains information about the local time zone.

The FILES Section

The FILES section lists the supplementary files that the command refers to, if any. Supplementary files are files that are not specified on the command line. Such files usually provide information that the command needs; the command accesses these files during its operation. If the files cannot be found, the command displays a message to this effect.

Files documented in this section may be temporary files, output files, databases, configuration files, and so on.

The Diagnostics Section

The DIAGNOSTICS division contains information about the exit status returned by the command. You can test this status to determine the result of the operation the command was asked to perform.

The PORTABILITY Section

The PORTABILITY section includes three types of information:

Availability of an MKS implementation of the command on MPE/iX
Availability of a version of the command on existing UNIX^® systems (System V, BSD)
Compatibility with industry standards (for example, the POSIX.2 Standard or the x/OPEN Portability Guide, Issue 4)

The PORTABILITY section is also used to describe additional operating system-specific options provided for that utility.

The LIMITS Section

The LIMITS section lists any limits on the operation of the software. For example, the dc command is intended to work like a desk calculator that can handle numbers of any size. However, at the time of this writing, it actually has a limit of 1000 digits when typing in a single number. Limits of this sort are inevitable when writing software, but the MKS Toolkit's limits are high enough that they should not get in the way of users.

Some limits are implicit rather than explicit, and may be lower than the explicitly stated limit. For example, if you are already using a lot of memory, you may not have enough memory left to get up to the explicitly stated limit.

The WARNING Section

The WARNING section contains important advice for users. In MKS Toolkit documentation, the WARNING section is often aimed at those who are familiar with UNIX systems. Since MKS Toolkit runs MPE/iX, its behavior may not precisely match the corresponding UNIX commands. The WARNING section may point out discrepancies in behavior that may catch experienced POSIX or UNIX users by surprise.

The NOTES Section

The NOTES section gives additional notes for those using the software. The purpose of the NOTES section is similar to that of the WARNING section -- to provide important information that the reader should not overlook; however, the NOTES section usually deals with issues that are more benign than WARNINGS.

The SEE ALSO Section

The SEE ALSO section refers to other reference pages that may contain information relevant to the reference page you have just read. For example, consider the compress command; this command helps you shrink data files into a compact form to save storage space. Its SEE ALSO section refers you to uncompress, the command that restores shrunken data files to their original state.

Reference Pages

Introduction