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 PTC 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 provides the name of the command and a brief functional description.
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.
-AabCcdFfgikLlmnopqRrstux1] [ -Xattr] [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 PTC 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 PTC MKS Toolkit command option consists of a dash (
ls -l -t ls -lt ls -t -l ls -tl
are all equivalent.
The synopsis line shows options in
In the description of ls, all options are shown in one long string after the single dash. Another common option form is
-cmu] [ -ooutfile] [ -tchar] [ -yn] [ -zn] [ -bdfiMnr] [ -kstartpos[,endpos]] ... [file ...]
In this example, there is the option
This option tells the sort command where to save its sorted
The form of the option is
sort -o sorted.dat
(followed by the rest of the command).
Notice that the synopsis for sort also contains an option of the form
This is similar to the option form just discussed, except that there is no
space between the
In this case, a colon (:) is specified in the position of the placeholder char.
The end of the sort synopsis is
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
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
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
As a special notation, most PTC MKS Toolkit commands let you specify
ls -- -t
to list the contents of that directory.
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 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 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 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 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 includes three types of information:
- Availability of an MKS implementation of the command on various Windows systems.
- 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 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 PTC 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 contains important advice for users. In PTC MKS Toolkit documentation, the WARNING section is often aimed at those who are familiar with UNIX systems. Since PTC MKS Toolkit runs on Windows, 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 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 AVAILABILITY section lists which members of the MKS Toolkit Product Family contain the utility or utilities described in the reference page.
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 mkszip 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.
PTC MKS Toolkit 10.3 Documentation Build 39.