The SOFTWARE doctype-specific tags let you describe software elements in structured reference material and in less structured tutorial material. Use these tags to describe the following, as discussed in following sections:

• Terminal keys and keypads
• Code fragments and their results
• Software messages
• Software arguments, parameters, and qualifiers
• Interactive terminal sessions

The SOFTWARE doctype contains several tags that let you accurately represent terminal keys, keypads, and key names both in text and in examples. These tags fall into two groups:

• Tags that describe keys used throughout the SOFTWARE doctype.
• Tags used to create keypad diagrams used only in the context of the <KEYPAD_SECTION> tag in the SOFTWARE doctype.

2.3.1 Describing Individual Keys

Using the <CPOS> Tag

Use the <CPOS> tag to mark the position of the cursor in a terminal example. The cursor is depicted as the underline character. The following example shows how to use the <CPOS> tag.

<P> Correct the directory specification to <QUOTE>([TEXTFILES]) by moving the cursor to the misspelled letter in the directory specification, as in the following example: <DISPLAY> $ COPY ABC.TXT [T<CPOS>(R)XTFILES] <ENDDISPLAY>

This example produces the following output:

Correct the directory specification to "[TEXTFILES]" by moving the cursor to the misspelled letter in the directory specification, as in the following example:

$ COPY ABC.TXT [TRXTFILES]

Using the <DELETE_KEY> Tag

Use the <DELETE_KEY> tag to create the character used on most terminal and typewriter keyboards for the DELETE key. The following example shows how to use the <DELETE_KEY> tag.

<P> Press the DELETE key (<DELETE_KEY>) to delete a character.

This example produces the following output:

Press the DELETE key (<X|) to delete a character.

Using the <GRAPHIC> Tag

Use the <GRAPHIC> tag to create special graphic characters that appear on the terminal screen. The <GRAPHIC> tag accepts two characters as arguments and formats them next to each other, with the second character formatted slightly below the first character. This tag lets you create representations of the linefeed and formfeed characters, as well as other similarly formatted characters.

The following example shows how to use the <GRAPHIC> tag.

<P> Two special characters that will appear in your editing session are the linefeed (<GRAPHIC>(L\F)) and the formfeed (<GRAPHIC>(F\F)) characters.

This example produces the following output:

Two special characters that will appear in your editing session are the linefeed (LF ) and the formfeed (FF ) characters.

Using the <KEY> Tag

Use the <KEY> tag to represent a terminal key, either in text or in an example. The <KEY> tag accepts a key label argument, which specifies the name of the key.

To represent a terminal key in text, use the TEXT keyword argument to the <KEY> tag to place angle brackets before and after the key label. To represent a terminal key in an example, use the BOX keyword argument to the <KEY> tag to place the key label in a box that resembles a key. If you specify neither the TEXT nor the BOX keyword, the default format is BOX.

Note that the <KEY> tag is used in the context of the <KEY_SEQUENCE> tag. See the description of the <KEY_SEQUENCE> tag in this section for more information on that tag.

The following example shows how to code the <KEY> tag, as it would appear in text using the TEXT keyword argument, and as it would appear in an example using the BOX keyword argument.

<P> You should now press the <KEY>(RETURN\TEXT) key to insert a line. <KEY_SEQUENCE> <KEY>(RETURN\BOX) <ENDKEY_SEQUENCE>

This example produces the following output:

You should now press the <RETURN> key to insert a line. [RETURN]

Using the <KEY_NAME> Tag

Use the <KEY_NAME> tag to differentiate the name of a key from the other output in an example or in text.

The following example shows how to use the <KEY_NAME> tag.

<P> Press the <KEY_NAME>(HELP) or the <KEY_NAME>(DO) key for more information.

This example produces the following output:

Press the or the key for more information.

Using the <KEY_SEQUENCE> Tag

Use the <KEY_SEQUENCE> tag to give an example of a sequence of keys. For example, you might want to describe the sequence of keys needed to exit a text editor.

The <KEY_SEQUENCE> tag enables the <KEY_PLUS> and the <KEY_TYPE> tags to make creating such key sequences easier. The <KEY_PLUS> tag creates a plus sign (+) between two keys, and the <KEY_TYPE> tag lets you associate a key sequence with some textual information, such as a terminal type. In addition to these two tags, you can use the <KEY> tag in the context of the <KEY_SEQUENCE> tag.

When you use the <KEY> tag in a key sequence, it accepts an additional argument, which lets you place two key labels rather than one inside a box or angle brackets. When you use two key labels, they are stacked together with the first argument placed on the top. This extra argument makes it possible to specify keys that use two stacked words as their label, such as the Next Screen key.

The following code fragment contains a series of key examples in a <KEY_SEQUENCE> section. Note that the <KEY> tag is used in two contexts in this example. In the context of the <KEY_SEQUENCE> tag, the <KEY> tag accepts two key label arguments. Outside the context of the <KEY_SEQUENCE> tag, the <KEY> tag accepts only a single-key label argument.

Note also that the first <KEY> tag is specifed with no keyword argument, so that the default BOX is used. The second <KEY> tag explicitly uses the BOX keyword to specify BOX formatting. The third <KEY> tag specifies the TEXT keyword argument.

<P> You would use the following sequence of keys: <KEY_SEQUENCE> <KEY>(Next\Screen) <KEY_PLUS> <KEY>(PF3\BOX) <ENDKEY_SEQUENCE> <P> These keys are not associated with the <key>(WHITE\TEXT) keys.

This example produces the following output:

You would use the following sequence of keys: NextScreen + [PF3]

These keys are not associated with the <WHITE> keys.

A keypad is a group of keys separate from those on the typing keyboard. These keys are typically used for special applications, such as editing, data entry, or cursor movement. The following diagram shows such a keypad.

Showing keypads and keypad keys is often difficult because it involves preparing artwork by hand. Using the SOFTWARE doctype, you can prepare your own keypad and keypad key diagrams by using the <KEYPAD_SECTION> tag and the tags it enables.

The <KEYPAD_SECTION> tag begins a section in which keypad diagrams can be created and described. This section terminates with the <ENDKEYPAD_SECTION> tag. Each keypad or portion of a keypad is created using the following tags:

• <KEYPAD>
  Begins a single illustration of a keypad or a portion of a keypad, and optionally allows a title to be placed on each illustration. A keypad cannot be more than four columns wide or more than five rows long. This tag is terminated by the <ENDKEYPAD> tag. You cannot create more than one keypad in a keypad section using the <KEYPAD> and <ENDKEYPAD> tags.
• <KEYPAD_ROW>
  Creates a 4-column keypad row for all but the bottom row of the keypad.
• <KEYPAD_ENDROW>
  Creates a special 3-column keypad row for the larger keys on the bottom row of the keypad.

If you use the DISPLAY keyword argument with the <KEYPAD> tag, you can specify arguments to the <KEYPAD_ROW> and <KEYPAD_ENDROW> tags that place text on the appropriate key in the keypad diagram.

If you do not use the DISPLAY keyword, you can specify only one of three keywords as arguments to the <KEYPAD_ROW> and <KEYPAD_ENDROW> tags.

The following keywords are accepted by the <KEYPAD_ROW> and <KEYPAD_ENDROW> tags:

• OPEN---Specifies that the key in that column is to be left blank. OPEN is the default.
• CLOSED---Specifies that the key in that column is to be shaded in.
• NONE---Specifies that no key should be drawn in that column.

The <KEYPAD_ROW> and <KEYPAD_ENDROW> tags accept the same keyword arguments, which let you specify whether a key should be drawn, and whether a key that is drawn should be shaded in. If you specify no keyword argument for a particular keypad column, the key is drawn and it is left open (not shaded in).

The following examples show how to use the keypad section tags to create various keypad diagrams. The first example shows a complete keypad with one key shaded in.

<KEYPAD_SECTION> <KEYPAD>(A Complete Keypad Diagram) <KEYPAD_ROW>( \ \ \ ) <KEYPAD_ROW>( \ \ \ ) <KEYPAD_ROW>( \ \CLOSED\ ) <KEYPAD_ROW>( \ \ \NONE ) <KEYPAD_ENDROW>( \ \ ) <ENDKEYPAD> <ENDKEYPAD_SECTION>

This example produces the following output:

A Complete Keypad Diagram

The following example shows a single line from the previous keypad diagram:

<KEYPAD_SECTION> <KEYPAD>(A Single Keypad Line) <KEYPAD_ROW>( \ \CLOSED\ ) <ENDKEYPAD> <ENDKEYPAD_SECTION>

This example produces the following output:

A Single Keypad Line

The following example shows the complete keypad with some keys eliminated from the diagram. You can use the NONE keyword argument to eliminate keys from the keypad diagram.

<KEYPAD_SECTION> <KEYPAD>(An Irregular Keypad) <KEYPAD_ROW>( \ \ \NONE) <KEYPAD_ROW>( \CLOSED\ \NONE) <KEYPAD_ROW>(NONE\ \NONE\NONE) <KEYPAD_ROW>(CLOSED\ \CLOSED\NONE) <ENDKEYPAD> <ENDKEYPAD_SECTION>

This example produces the following output:

An Irregular Keypad

The following examples show how the DISPLAY keyword argument to the <KEYPAD> tag lets you specify text in some keys and shade other keys:

<KEYPAD_SECTION> <KEYPAD>(The Editing Keypad with Key Labels\DISPLAY) <KEYPAD_ROW>(PF1\PF2\PF3\PF4) <KEYPAD_ROW>(7\8\9\-) <KEYPAD_ROW>(4\5\6\,) <KEYPAD_ROW>(1\2\3\ ) <KEYPAD_ENDROW>(0\.\ENTER) <ENDKEYPAD> <ENDKEYPAD_SECTION>

This example produces the following output:

The Editing Keypad with Key Labels

PF1	PF2	PF3	PF4
7	8	9	-
4	5	6	,
1	2	3	ENTER
0		.

<KEYPAD_SECTION> <KEYPAD>(The Editing Keypad with Key Labels and Shaded Keys\DISPLAY) <KEYPAD_ROW>(CLOSED\PF2\PF3\PF4) <KEYPAD_ROW>(7\8\9\-) <KEYPAD_ROW>(CLOSED\5\6\,) <KEYPAD_ROW>(1\2\3\ ) <KEYPAD_ENDROW>(0\.\ENTER) <ENDKEYPAD> <ENDKEYPAD_SECTION>

This example produces the following output:

The Editing Keypad with Key Labels and Shaded Keys

PF2	PF3	PF4
7	8	9	-
5	6	,
1	2	3	ENTER
0		.

2.4 Documenting Code Fragments

There are three tags available in the SOFTWARE doctype that let you describe software code fragments. These tags let you create syntax statements, emphasize arguments, and create samples of screen displays.

<SYNTAX>	Formats text on the page exactly as entered to allow correct positioning of code or syntax statements.
<ARGUMENT>	Emphasizes arguments to functions, procedures, or tags in text using an altered text font (such as bold face or italic).
<DISPLAY>	Simulates a screen display.

Using the <DISPLAY> tag

The <DISPLAY> tag lets you create an example that simulates a screen display. You terminate this example with the <ENDDISPLAY> tag. The <DISPLAY> tag accepts one of two keyword arguments.

The WIDE keyword argument extends the display format into the left margin if the example is too wide for normal formatting. The KEEP keyword argument specifies that the entire display example is placed on the next page if it does not fit on the existing page. You use this argument to prevent unnecessary page breaks in display examples.

The following example shows how to use the <DISPLAY> tag to simulate a screen display. This example is coded using the WIDE argument due to the width of the example. Note that all the spacing in the display is retained as it was entered.

<DISPLAY>(WIDE) VAX/VMS V4.4 on node XXXXXX 6-NOV-1994 17:43:18.03 Uptime 0 02:08:56 Pid Process Name State Pri I/O CPU Page flts Ph.Mem 20400080 NULL COM 0 0 0 00:15:46.03 0 0 20400081 SWAPPER HIB 16 0 0 00:00:19.74 0 0 20400085 ERRFMT HIB 7 157 0 00:00:01.32 67 104 20400086 CACHE_SERVER HIB 16 6 0 00:00:00.12 57 92 20400087 CLUSTER_SERVER HIB 10 14 0 00:00:00.61 109 257 20400088 OPCOM LEF 7 126 0 00:00:01.06 332 77 20400089 JOB_CONTROL HIB 8 2081 0 00:00:22.95 190 322 2040008A CONFIGURE HIB 9 19 0 00:00:00.18 99 136 20400092 SYMBIONT_0001 HIB 6 312 0 00:00:06.34 2886 63 <ENDDISPLAY>

This example produces the following output:

VAX/VMS V4.4 on node XXXXXX 6-NOV-1994 17:43:18.03 Uptime 0 02:08:56 Pid Process Name State Pri I/O CPU Page flts Ph.Mem 20400080 NULL COM 0 0 0 00:15:46.03 0 0 20400081 SWAPPER HIB 16 0 0 00:00:19.74 0 0 20400085 ERRFMT HIB 7 157 0 00:00:01.32 67 104 20400086 CACHE_SERVER HIB 16 6 0 00:00:00.12 57 92 20400087 CLUSTER_SERVER HIB 10 14 0 00:00:00.61 109 257 20400088 OPCOM LEF 7 126 0 00:00:01.06 332 77 20400089 JOB_CONTROL HIB 8 2081 0 00:00:22.95 190 322 2040008A CONFIGURE HIB 9 19 0 00:00:00.18 99 136 20400092 SYMBIONT_0001 HIB 6 312 0 00:00:06.34 2886 63

Using the <SYNTAX> tag

The <SYNTAX> tag lets you distinguish the syntax of a programming language statement from regular text. The <SYNTAX> tag distinguishes the syntax statement by making the typeface of the statement different from the typeface used in the surrounding text. You terminate the <SYNTAX> tag with the <ENDSYNTAX> tag.

The <SYNTAX> tag accepts two optional arguments. The WIDE keyword argument allows more width for the syntax statement by letting the syntax statement extend into the left margin. The alternate heading argument lets you specify a heading for the syntax statement.

The following example shows how to use the <SYNTAX> tag to separate a syntax statement from surrounding text. Note that all the spacing in the statement is retained as it was entered.

<SYNTAX> IF condition THEN statement list [ELSE statement list]; <ENDSYNTAX>

This example produces the following output:

IF condition THEN statement list [ELSE statement list];

Using the <ARGUMENT> tag

The <ARGUMENT> tag lets you label an argument by displaying that argument in a typeface that differs from that of surrounding text (for example, in some doctypes it may cause the argument to be displayed in a bold typeface). This tag accepts only the argument name as an argument.

The following example shows how to use the <ARGUMENT> tag to separate the argument from the surrounding text.

The CHR$ function converts the <ARGUMENT>(char data) argument into a numeric value.

This example produces the following output:

The CHR$ function converts the char data argument into a numeric value.

You can describe the messages issued by software programs by using the <MESSAGE_SECTION> tag and the tags it enables.

Tags enabled by the <MESSSAGE_SECTION> tag are summarized in the following list:

<MESSAGE_TYPE>	Specifies the type of message being described using the <MSG> or <MSGS> tag.
<MSG>	Labels and formats up to two lines of message text in the message description section.
<MSGS>	Labels and formats up to nine lines of message text in the message description section.
<MSG_TEXT>	Specifies the explanatory text associated with the messages described with the <MSG> or the <MSGS> tag.

Messages generally come in one of three forms:

• A message text string only. An example of this type of string is System Resources Unavailable.
• A message text string preceded by a text string identification code. An example of this type of string is %DIRECT-W-NOFILES, no files found.
• A message text string preceded by a numeric string identification code. An example of this type of string is %1288374 file lookup failed.

• The format your messages most closely follows
• The number of lines each message occupies on the terminal display

Using the <MESSAGE_TYPE> tag

Use the <MESSAGE_TYPE> tag to specify the type of message labeled by the <MSG> or <MSGS> tags. The <MESSAGE_TYPE> tag accepts one of three keyword arguments to determine the type of messages being described:

• NOIDENT
  Specifies that the <MSG> and <MSGS> tags in the message section will not be given a numeric or text identification string as the first argument. NOIDENT is the default keyword. Specifying NOIDENT as the keyword argument has the same effect as not specifying the <MESSAGE_TYPE> tag at all.
• TEXTIDENT
  Specifies that the <MSG> and <MSGS> tags in the message section will be given a text identification string as an argument.
  You specify text identification strings and message text arguments as pairs. The TEXTIDENT keyword creates a comma (,) between text identification strings and message text arguments.
• NUMIDENT
  Specifies that the <MSG> and <MSGS> tags in the message section will be given a numeric identification string as an argument.
  You specify numeric identification strings and message text arguments as pairs. The NUMIDENT keyword assumes that the numeric identification string specified will not exceed a total length of 6 picas (approximately 10 characters).

<MESSAGE_SECTION> <MESSAGE_TYPE>(NUMIDENT) <MSG>(%1288374 \file lookup failed.) . . .

Using the <MSG> tag

Use the <MSG> tag for messages that occupy only one or two lines when they are output. The arguments accepted by the <MSG> tag are based upon the type of message being described. The message type is determined by the keyword argument used with the <MESSAGE_TYPE> tags, as follows:

• NOIDENT keyword
  The <MSG> tag requires a message text argument and accepts an optional second message text argument.
• TEXTIDENT keyword
  The <MSG> tag requires a text message identification string and a message text argument. It also accepts a second line of message text as an optional third argument. The TEXTIDENT keyword creates a comma (,) between text identification strings and message text arguments. The optional second message text argument is stacked under the first message text.
• NUMIDENT keyword
  The <MSG> tag requires a numeric message identification string and a message text argument. It also accepts a second line of message text as an optional third argument. The numeric message identification string must be no longer than 10 characters (6 picas). The optional second message text argument is stacked under the first message text.

<MESSAGE_SECTION> <MESSAGE_TYPE>(NUMIDENT) <MSG>(%1244374\file lookup failed\directory not found) . . . <ENDMESSAGE_SECTION>

Using the <MSGS> tag

Use the <MSGS> tag for messages that occupy from one to nine lines when they are output. The arguments accepted by the <MSGS> tag are based upon the type of message being described. The message type is determined by the keyword argument used with the <MESSAGE_TYPE> tag.

• NOIDENT keyword
  The <MSGS> tag requires one message text argument and accepts up to a total of nine message text arguments.
• TEXTIDENT keyword
  The <MSGS> tag requires text message identification strings as the first and optionally as the third, fifth, and seventh arguments. It also requires a message text argument as the second argument and optionally as the fourth, sixth, and eighth arguments. The TEXTIDENT keyword creates a comma (,) between text identification strings and message text arguments. The optional arguments are stacked under the required arguments.
• NUMIDENT keyword
  The <MSGS> tag requires numeric message identification strings as the first and optionally as the third, fifth, and seventh arguments. It also requires a message text argument as the second argument and optionally as the fourth, sixth, and eighth arguments. The text message identification strings must be no longer than 10 characters (approximately 6 picas). The optional arguments are stacked under the required arguments.

<MESSAGE_SECTION> <MESSAGE_TYPE>(NUMIDENT) <MSGS>(%133455\read write error\%0000221\disk not available \$6644544\file not found) . . .

Using the <MSG_TEXT> tag

The <MSG_TEXT> tag labels the text that describes the messages listed by the <MSG> or <MSGS> tags. By default, the <MSG_TEXT> tag has a default heading of Explanation:. If you want the heading for your text to be more descriptive, you can specify an alternate heading for this tag (for example, User Action). Note that any alternate heading you specify for the <MSG_TEXT> tag will have a colon (:) appended to the end of the heading when it is output.