This part of this chapter provides reference information on the SOFTWARE doctype tags and templates.

Begins the text that defines an item in an argument definition list.

Syntax

<ARGDEF>

ARGUMENTS

None.

related tags

• <ARGDEFLIST>
• <ARGITEM>

restrictions

Valid only in the context of the <ARGDEFLIST> tag.

DESCRIPTION

The <ARGDEF> tag begins the text that defines an item in an argument definition list. This text describes the item listed by the previous <ARGITEM> tag. Terminate the text begun by the <ARGDEF> tag with the next <ARGITEM> or <ENDARGDEFLIST> tag.

Example

The following example shows an argument definition list used outside the routine template.

<ARGDEFLIST>(Arguments) 
<ARGITEM>(data-1\data-2) 
<ARGDEF>Specifies the arguments through which data is given to the routine. 
<ENDARGDEFLIST> 
 

This example produces the following output:

---

ARGUMENTS

data-1

data-2

Specifies the arguments through which data is given to the routine.

Begins a definition list of arguments.

Syntax

<ARGDEFLIST> [(

• alternate heading
• NOHEAD
• NONE

)]

ARGUMENTS

alternate heading

This is an optional argument. It specifies a heading to override the current default text heading. The default heading provided by DECdocument for the <ARGDEFLIST> tag can vary. See the DESCRIPTION section for more information on default argument definition list headings.

NOHEAD

This is an optional keyword argument. It suppresses the output of the default heading for the <ARGDEFLIST> tag.

NONE

This is an optional keyword argument. It causes the text None to be written to indicate that no arguments are available. Note that when you use the NONE keyword, do not use the <ENDARGDEFLIST> tag.

related tags

• <ARGDEF>
• <ARGITEM>
• <ARGTEXT>
• <PARAMDEFLIST>
• <QUALDEFLIST>
• <SET_TEMPLATE_ARGITEM>
• <SET_TEMPLATE_HEADING>
• The global <DEFINITION_LIST> tag

required terminator

<ENDARGDEFLIST>

Required unless you specify the NONE keyword as an argument to the <ARGDEFLIST> tag.

DESCRIPTION

The <ARGDEFLIST> tag begins a definition list of arguments. This tag is similar in format and syntax to the global <DEFINITION_LIST> tag. See Using Global TagsUsing Global Tags for more information on the <DEFINITION_LIST> tag.

The <ARGDEFLIST> tag enables two tags to create an argument definition list. The <ARGITEM> tag labels the list item being defined, and the <ARGDEF> tag begins the definition of the list item.

When you use the <ARGDEFLIST> tag in the Routine template, the arguments accepted by the <ARGITEM> tag are changed, and the <ARGTEXT> tag is enabled. The change in the arguments accepted by the <ARGITEM> tag and the addition of the <ARGTEXT> tag give you a more structured environment in which to create Routine template argument definition lists. See the descriptions of these tags in this chapter for more information.

When you use the <ARGDEFLIST> tag in the templates, a default heading is provided. Modify this heading for that single argument definition list using the alternate heading argument. A heading specified in this way overrides any existing default heading.

Use the <SET_TEMPLATE_HEADING> tag to create your own default headings in a reference template. Using this tag modifies the default headings for all subsequent <ARGDEFLIST> tags used in that reference template. See the reference description of the <SET_TEMPLATE_HEADING> tag for more information on that tag.

When you use the <ARGDEFLIST> tag outside a template, you define no default heading. Create your own heading for a single argument definition list by specifying that heading as the alternate heading argument.

The following informal table lists the default headings for the <ARGDEFLIST> by their context:

Context	Default Heading
Command Template	Arguments
Routine Template	Arguments
Statement Template	No default heading
Tag Template	Arguments
Outside a Template	No default heading

Examples

The following examples show various uses of the <ARGDEFLIST> tag. The following example shows an argument definition list used outside the context of the Routine template. Note the syntax used for the <ARGITEM> tag.

<ARGDEFLIST>(Arguments) 
<ARGITEM>(data-1\data-2) 
<ARGDEF>Specifies the arguments through which data is given to the routine. 
<ENDARGDEFLIST> 
 

This example produces the following output:

---

ARGUMENTS

data-1

data-2

Specifies the arguments through which data is given to the routine.

The following example shows two argument definition lists used in the Routine template. The first list is coded using the Routine template-specific <ARGITEM> tag syntax. Note the headings produced by the <ARGITEM> tag in the output of this example.

The second argument definition list illustrates a use of the <ARGTEXT> tag. Typically, the <ARGTEXT> tag is used instead of the <ARGITEM> or <ARGDEF> tags.

<ROUTINE_SECTION> 
. 
. 
. 
<ARGDEFLIST> 
<ARGITEM>(x\floating_point\F_Floating, D_Floating, G_Floating, or H_Floating 
\read only\by reference\may also be given by value) 
<ARGDEF>The number for which the square root is desired. 
<ENDARGDEFLIST> 
<ARGDEFLIST> 
<ARGTEXT> 
The arguments to the SYS$NONE routine are identical to those used 
by the SYS$NULL routine.  See the description of the SYS$NULL routine for 
more information on these arguments. 
<ENDARGTEXT> 
<ENDARGDEFLIST> 
. 
. 
<ENDROUTINE_SECTION> 
 

This example produces the following output:

ARGUMENTS

x

VMS usage:	floating_point
type:	F_Floating, D_Floating, G_Floating, or H_Floating
access:	read only
mechanism:	by reference

The number for which the square root is desired.

ARGUMENTS

The arguments to the SYS$NONE routine are identical to those used by the SYS$NULL routine. See the description of the SYS$NULL routine for more information on these arguments.

Labels one to seven routine argument items to be defined in an argument definition list outside the Routine template, or a single routine argument and its attributes in the Routine template.

Syntax

<ARGITEM> (item-1 [\item-2...[\item-7]])

<ARGITEM> (arg name[\usage information
\data type \access \mechanism[\mechanism info]])

ARGUMENTS

item-n

Specifies the item in the argument list to be defined. This tag accepts a minimum of one item-n argument and a maximum of seven. When you specify more than one item-n argument, each subsequent item-n argument after the initial argument formats under the first argument.

arg name

Specifies the descriptive name assigned to the argument for reference purposes.

usage information

This is an optional argument. It specifies a keyword indicating the category of data to which the argument's value belongs. These keywords are system dependent, and are specified by agreed-upon conventions.

data type

This is an optional argument. It specifies the data type of the argument; for example, longword, byte, G_floating, and so on.

access

This is an optional argument. It specifies the access applied to the argument; for example, read-only, write-only, and so on.

mechanism

This is an optional argument. It specifies the mechanism by which the argument is passed; for example, by descriptor, by reference, or by value.

mechanism info

This is an optional argument. It specifies additional information you may append to the mechanism argument output.

related tags

• <ARGDEF>
• <ARGDEFLIST>
• <ARGTEXT>

restrictions

The first syntax listed in the format section is valid in an argument definition list outside the Routine template. The second syntax listed in the format section is valid only in an argument definition list inside the Routine template.

required terminator

<ARGDEF>

DESCRIPTION

The <ARGITEM> tag labels one to seven routine argument items to be defined in an argument definition list outside the Routine template, or a single routine argument and its attributes in the Routine template. This tag accepts one of two sets of arguments, depending on whether or not the <ARGITEM> tag is used in the Routine reference template.

Outside the Routine template, the <ARGITEM> tag accepts the item-n argument, which may be repeated up to seven times, as specified in the first syntax listed in the Format section. This form of the <ARGITEM> tag lets you label one to seven routine argument items inside an argument definition list.

In the Routine template, the <ARGITEM> tag uses the arguments listed in the second syntax listed in the Format section. This form of the <ARGITEM> tag lets you label a single routine argument and its attributes.

Example

See the example in the <ARGDEFLIST> tag description.

Labels definition text in an argument definition list that replaces the information contained in a pair of <ARGITEM> and <ARGDEF> tags.

Syntax

<ARGTEXT>

related tags

• <ARGDEF>
• <ARGDEFLIST>
• <ARGITEM>

restrictions

Valid only in the context of the <ARGDEFLIST> tag in the Routine template.

required terminator

<ENDARGTEXT>

DESCRIPTION

The <ARGTEXT> tag labels definition text in an argument definition list that replaces the information contained in a pair of <ARGITEM> and <ARGDEF> tags. This tag is most useful when the arguments to be described are already listed elsewhere in the reference documentation.

Example

The following example shows how to use the <ARGTEXT> tag to replace a pair of <ARGDEF> and <ARGITEM> tags. Note that this tag is restricted to argument definition lists used in the context of the Routine template.

<ROUTINE_SECTION> 
. 
. 
. 
<argdeflist> 
<argtext> 
The arguments to the SYS$NONE routine are identical to those used 
by the SYS$NULL routine.  See the description of the SYS$NULL routine for 
more information on these arguments. 
<endargtext> 
<endargdeflist> 
. 
. 
. 
<endroutine_section> 
 

This example produces the following output:

ARGUMENTS

The arguments to the SYS$NONE routine are identical to those used by the SYS$NULL routine. See the description of the SYS$NULL routine for more information on these arguments.

Emphasizes an argument name in text.

Syntax

<ARGUMENT> (argument name)

ARGUMENTS

argument name

Specifies an argument name to be emphasized.

related tags

• <KEYWORD>
• <VARIABLE>

---

DESCRIPTION

The <ARGUMENT> tag emphasizes an argument name in text. This tag causes the argument name to appear in an altered font (such as boldface). However, the tag does not alter the case of its argument.

---

Example

The following example shows a sample use of the <ARGUMENT> tag.

<P> The <ARGUMENT>(newadr) argument to the $ADJSTK function provides the address of a longword to receive the updated value.

This example produces the following output:

The newadr argument to the $ADJSTK function provides the address of a longword to receive the updated value.

---

<ARG_SEP>

Creates a separator character (\) between arguments in the FORMAT section of a tag description.

---

Syntax

<TAG_NAME> (argument-1<ARG_SEP>argument-2)

---

ARGUMENTS

argument-1

Whenever you specify an argument to a tag, use the <ARG_SEP> tag to create the argument separator character, the backslash (\).

argument-2

Whenever you specify an argument to a tag, use the <ARG_SEP> tag to create the argument separator character, the backslash (\).

related tags

• <FTAG>

restrictions

Valid only in the FORMAT section of a <FTAG> tag description in the Tag template.

DESCRIPTION

The <ARG_SEP> tag creates a separator character (\) between arguments in the FORMAT section of a tag description.

The <ARG_SEP> tag has no other function than to output the tag separator character (the backslash) in a Tag template format section.

Example

The following example shows how to use the <ARG_SEP> tag to separate the arguments in a tag description that has one required and two optional arguments.

<format> 
<ftag>(ROUTINE\name[<arg_sep>info1[<arg_sep>info2]]) 
<endformat> 
 

This example produces the following output:

Format

<ROUTINE> (name[\info1[\info2]])

Places the name of an author and one or two additional lines of information about the author in the front matter portion of a document processed using the SOFTWARE.SPECIFICATION doctype.

Syntax

<AUTHOR> (author name [\author info-1] [\author info-2])

ARGUMENTS

author name

Specifies the name of the author. If you use the author info-n arguments, this line will be the top line.

author info-n

This is an optional argument. It specifies any additional information on the author. Information specified as author info-1 is placed above information specified as author info-2.

related tags

• <BYLINE>
• <SIGNATURES>
• The global <FRONT_MATTER> tag

restrictions

Available only in the SOFTWARE.SPECIFICATION doctype following the global <FRONT_MATTER> tag.

DESCRIPTION

The <AUTHOR> tag places the name of an author and one or two additional lines of information about the author in the front matter portion of a document processed using the SOFTWARE.SPECIFICATION doctype. This tag accepts two optional arguments to provide additional information about the author.

If you want a signatory line for the author in the front matter, use the <BYLINE> and <SIGNATURES> tags. See the reference descriptions of those tags in this chapter for more information.

Example

The following example shows how to use the <AUTHOR> tag in the front matter of a document. Note how the optional second argument to the <AUTHOR> tag lists the position of the author.

<FRONT_MATTER> 
<TITLE_PAGE> 
<TITLE>(The NYUC Simulator Reference Manual) 
<ORDER_NUMBER>(AA-Z0000-TE) 
<ABSTRACT> 
This manual describes the NYUC Simulator. 
This program simulates a conversation between three people 
by analyzing the syntactic and semantic components of three 
related statements, and then synthesizing statements and responses 
based upon these original statements. 
<ENDABSTRACT> 
<REVISION_INFO>(This revision is personally signed.) 
<AUTHOR>(Mr. Jones\Research Head, STG Inc.) 
<SIGNATURES> 
<BYLINE>(Nat Jones\Author) 
<DATE>(July 11, 1985) 
<PRINT_DATE>(June 1987) 
<ENDTITLE_PAGE> 
<ENDFRONT_MATTER> 
 

Places a name and other optional information below a ruled line in a signature list processed using the SOFTWARE.SPECIFICATION doctype.

Syntax

<BYLINE> (name [\additional info])

ARGUMENTS

name

This is an optional argument. It specifies the name of the signatory. This name is placed under the beginning of the signature line on the left side of the page.

additional info

Specifies any additional information about the signatory. This information is placed on the same line as the name argument with an em dash (---) between the two arguments.

related tags

• <AUTHOR>
• <SIGNATURES>
• The global <FRONT_MATTER> tag

restrictions

Valid only in the context of the <SIGNATURES> tag.

DESCRIPTION

The <BYLINE> tag places a name and other optional information below a ruled line in a signature list processed using the SOFTWARE.SPECIFICATION doctype. One use of this tag is to create an approval line in the front matter of a document and to place the name of the signatory beneath that line. You can optionally place additional information about the signer by using the additional info argument. Additional information formats to the right of the name of the signer, on the same line, separated by an em dash (---).

Use as many <BYLINE> tags as you want to create approval lines in the front matter of a document, as long as all these tags follow the <SIGNATURES> tag. Use the <SIGNATURES> tag to begin all the approval lines on a separate page of the front matter. See the reference description of the <SIGNATURES> tag in this section for more information on that tag.

Example

The following example shows three occurrences of the <BYLINE> tag. The first two occurrences list the positions of the signers using the optional additional info argument; the third occurrence omits the optional argument. Note that all three tags follow the <SIGNATURES> tag.

<FRONT_MATTER> 
<TITLE_PAGE> 
<TITLE>(The NYUC Simulator Reference Manual) 
<REVISION_INFO>(This revision is personally signed.) 
<AUTHOR>(Mr. Jones\Research Head, STG Inc.) 
<SIGNATURES> 
<BYLINE>(Nat Jones\Author) 
<BYLINE>(Cecil Mills\Co-author) 
<BYLINE>(Matt Smith) 
<DATE>(July 11, 1985) 
<PRINT_DATE>(June 1987) 
<ENDTITLE_PAGE> 
<ENDFRONT_MATTER> 
 

Begins a new command description.

Syntax

<COMMAND> (command name[\informational name]\symbol name)

ARGUMENTS

command name

Names the command described in the section.

informational name

This is an optional argument. It specifies an optional description of the command's function.

symbol name

Specifies the name of the symbol used in all references to the command.

Symbol names must not exceed 31 characters and must only contain alphabetic letters, numbers, or underscores. Do not begin a symbol name with an underscore.

related tags

• <COMMAND_SECTION>
• <SET_TEMPLATE_ARGITEM>
• <SET_TEMPLATE_COMMAND>

restrictions

Valid only in the context of the Command template.

DESCRIPTION

The <COMMAND> tag to begins a new command description. This description is for a single command in the context of the <COMMAND_SECTION> tag. This tag has the following default format:

• Each <COMMAND> tag begins a new page of output.
• Each output page carries a single running title, which is the current command name.
• If the optional informational name argument is used with the <COMMAND> tag, this argument will be output after the command name argument and the two arguments will be separated by an em dash (---).

Use the <SET_TEMPLATE_COMMAND> tag to replace the <COMMAND> tag with a tag specific to your task (for example, <INTERNAL_COMMAND>), or to change the default attributes of the <COMMAND> tag. See the description of the <SET_TEMPLATE_COMMAND> tag in this chapter for more information.

Examples

The following example shows a command section begun using the <COMMAND_SECTION> tag. in this command section, the <COMMAND> tag begins the command description for the OPEN command.

<COMMAND_SECTION> 
<COMMAND>(OPEN) 
<OVERVIEW> 
. 
. 
. 
 

In the following example, the <COMMAND> tag has two arguments. The command name, CLOSE, appears at the beginning of the command description. The text specified in the second argument, Close a File, is printed on the same line as the command name, separated by an em dash (---).

<COMMAND_SECTION> 
<COMMAND>(CLOSE\Close a File)