introduction to reference pages

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.

There are three alternatives for accessing the reference pages to each command through the CLI man command.

The possible prefixes for CLI commands are integrity, aa, si, and im. Using workflow and document functionality to illustrate, first, you may simply type the im prefix and the command together as one word. Second, you may type the im prefix and the command with an underscore between them. Third, you may quote the im prefix and the command, with a space in the middle. For example:

See the reference page for the man command itself, by typing man man, to find out more details.

This reference page describes the parts of a reference page with examples taken from real reference pages for workflow and document management.

The following sections discuss the various elements of a reference page.

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 im createissue command.

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 you should do it in. 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. The workflow and document management commands all include the im prefix. In PTC RV&S documentation, command names are always written in bold Courier font.

After the command name comes a list of options. A typical command option consists of either a single dash (-) followed by a single character, usually an uppercase or lowercase letter, or it may consist of a double dash (--) followed by a multi-character option name. Often there are single-character and multi-character options that do the same thing. The multi-character strings are not case sensitive, but are shown in mixed case to facilitate readability. For example, you might have -? or --usage.

To view a list of all available im CLI commands, enter im.

The synopsis line shows options in bold Courier font.

In some cases, value provides extra information for using an option. For example, the im editissue command allows you to edit one or more issues; here is the command's synopsis:

In this example, note the option

This option tells the im editissue command to select the issues returned in the specified query for editing. 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.

When you specify a value for an option, such as --query=query, values that contain spaces must be enclosed in double quotes, for example, --query="Cosmos Defects"; however, since the query Defects does not contain spaces, --query=Defects is acceptable. Values that contain special characters must be enclosed in double quotes.

The end of the im editissue synopsis is

Since there are no square brackets around the list, in this example, it is mandatory.

The ellipsis means one or more issue IDs. The ellipsis (...) stands for repetitions of whatever immediately precedes it. Most CLI commands allow you to specify lists of multiple issues using spaces between them.

See the options reference page for more details on general and universal options that apply to CLI commands.

The order of issues 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 - or a --; they do not have to be given in the exact order shown in the synopsis. However, all the - or -- options must appear in the correct area of the command line. For example, you can specify

but you will not get correct results if you specify

and so on.

The DESCRIPTION section simply describes what the command does and how each option works.

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 Arial font.

The See Also section refers to other reference pages that may contain information relevant to the reference page you have just read.