The following example shows how to create a routine section in which each routine description (begun with a <ROUTINE> tag) is in a separate SDML file, and all these descriptions are included into a primary routine description file. For example, the file MYROUTINES.SDML contains the following SDML tags:

<INCLUDE>(AAA$CLOSE.SDML) <INCLUDE>(AAA$OPEN.SDML) <INCLUDE>(AAA$READ.SDML) <INCLUDE>(AAA$WRITE.SDML)

Each of the included files contains one routine reference description begun with a <ROUTINE> tag. For these files to process correctly, you must precede them with the <ROUTINE_SECTION> tag, which enables the <ROUTINE> tag. These files can have the necessary tags processed before them by specifying the /INCLUDE qualifier on the command line to include a startup definition file. This startup file might include the following tags:

#2

<ROUTINE_SECTION>(AAA Routines\AAA) <SET_TEMPLATE_ROUTINE>(ROUTINE\DOUBLERUNNINGHEADS)

If this startup file were named AAAROUTINE_STARTUP.SDML, it could be included using the DOCUMENT /INCLUDE qualifier as in the following example:

$ DOCUMENT myroutines SOFT.REF LN03- _$ /INCLUDE=AAAROUTINE_STARTUP.SDML

When each individual file in MYROUTINES.SDML is processed, the correct sequence of tags will be read in to begin the routine section.

Process multiple files together by using the <INCLUDE> tag to include them into a single master file (such as MYROUTINES.SDML), or include them into a bookbuild profile.

Use the <ELEMENT> tags to include multiple files into a profile. For example, the bookbuild profile file AAAPRO.SDML could contain the following tags:

<PROFILE> <ELEMENT>(AAA$CLOSE.SDML) <ELEMENT>(AAA$OPEN.SDML) <ELEMENT>(AAA$READ.SDML) <ELEMENT>(AAA$WRITE.SDML) <COMMENT>(contains <ENDROUTINE_SECTION> tag) <ENDPROFILE>

Note that the PROFILE file should include the <ENDROUTINE_SECTION> tag in the appropriate file, so that the template terminates and the book builds correctly.

Begins a return status definition list in the Routine template.

Syntax

<RSDEFLIST> [(

• alternate heading[ \NONE
• \TEXT
• NONE

)]

ARGUMENTS

alternate heading

This is an optional argument. It specifies a heading to override the current default text heading for this use of the <RSDEFLIST> tag. The default heading provided by DECdocument is Return Values. See the reference description of the <SET_TEMPLATE_HEADING> tag for information on how to modify the default headings for all <RSDEFLIST> tags.

TEXT

This is an optional keyword argument. It specifies that a block of text appears in place of a list of return status values. If you use this keyword, you must position it as the second argument to the <RSDEFLIST> tag.

To use the default heading and to indicate that text follows, specify the following:

<RSDEFLIST>(\TEXT)

NONE

This is an optional keyword argument. It indicates that the routine does not return any values.

related tags

• <RSITEM>

restrictions

Valid only in the context of the Routine template. If you specify NONE as an argument to the <RSDEFLIST> tag, do not use the <ENDRSDEFLIST> tag.

required terminator

<ENDRSDEFLIST>

DESCRIPTION

The <RSDEFLIST> tag begins a return status definition list in the Routine template. DECdocument formats this list as a 2-column, multipage table. This lets you use the <TABLE_ROW_BREAK>(FIRST) and <TABLE_ROW_BREAK>(LAST) tags to control page breaks in the table if such control is needed.

Examples

The following three input examples show various uses of the <RSDEFLIST> tag. Outputs from these coding examples appear after the last input example.

The following input example illustrates a return status definition list for a routine with two possible return values.

<RSDEFLIST> 
<RSITEM>(SS$_NORMAL\Service successfully completed.) 
<RSITEM>(SS$_ACCVIO\Access violation.) 
<ENDRSDEFLIST> 
 

The following input example uses the NONE keyword argument to indicate that a routine does not return any status values. Note that the <ENDRSDEFLIST> tag must not be specified.

<RSDEFLIST>(NONE) 
 

The following input example illustrates a single line of descriptive text in a Return Status section.

<RSDEFLIST>(\TEXT) 
Any condition values returned by the Record Management Service (RMS), 
Parse. 
<ENDRSDEFLIST> 
 

These input examples produce the following outputs:

Return Values

SS$_NORMAL	Service successfully completed.
SS$_ACCVIO	Access violation.

Return Values

Return Values

Any condition values returned by the Record Management Service (RMS), Parse.

Specifies the return status value of a routine and lists its meaning.

Syntax

<RSITEM> (code\code description)

ARGUMENTS

code

Specifies the system keyword assigned to the status value.

code description

Specifies the descriptive text explaining the meaning of the return status value.

related tags

• <RSDEFLIST>

restrictions

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

DESCRIPTION

The <RSITEM> tag specifies the return status value of a routine and lists its meaning.

Examples

These examples show only code fragments, and no actual output. See the <RSDEFLIST> tag description for sample output.

<RSDEFLIST> 
<RSITEM>(SS$_NORMAL\Normal, successful completion.) 
<RSITEM>(SS$_ACCVIO\Access violation.) 
<ENDRSDEFLIST> 
 

This example illustrates a Return Status section for a routine that has two possible return values.

<RSDEFLIST> 
<RSITEM>(SS$_NORMAL\Normal successful completion.) 
<RSITEM>(SMG$_WRONNUMARG\Wrong number of arguments.) 
<RSITEM>(<SPAN>(2\LEFT)Any condition values returned by 
LIB$SCOPY_DXDX, SMG$ADD_KEY_DEF, or by CLI$ routines.) 
<ENDRSDEFLIST> 
 

This example illustrates the Return Status definition list for a routine that has two specific return values, and uses the <SPAN> tag to place additional explanatory text in the table.

Creates a single line heading at the bottom of each page in a document processed using the SOFTWARE.SPECIFICATION doctype.

Syntax

<RUNNING_FEET> (title text)

ARGUMENTS

title text

Specifies the text to be used as a running heading at the foot of the page.

related tags

• <RUNNING_TITLE>

restrictions

Valid only in the SOFTWARE.SPECIFICATION doctype.

DESCRIPTION

The <RUNNING_FEET> tag creates a single line heading at the bottom of each page in a document processed using the SOFTWARE.SPECIFICATION doctype. This heading is called a footer because it appears at the foot of the page. When the same footer is used for several pages, the footers are collectively called running feet.

This tag accepts one argument, the text that should appear as the footer at the bottom of the page. This text outputs exactly as entered, including spacing and capitalization.

Use the <RUNNING_TITLE> tag to create a heading at the top of the page. See the reference description of the <RUNNING_TITLE> tag for more information on that tag.

Example

The following example shows how to use the <RUNNING_FEET> tag to place the heading Getting the Piece of Paper at the bottom of each page. Note that the running footer will be output exactly as entered.

<RUNNING_FEET>(Getting the Piece of Paper) 
<HEAD2>(Getting the Piece of Paper\36_GettingthePieceofPaper) 
<P> 
You can buy clean paper in most major supermarkets, department stores, 
and hardware stores.  You should try to get ruled paper so that 
your letter will be neat and easy to read. 
 

Creates a 1- or 2-line running heading at the top of each page in a document processed using the SOFTWARE.SPECIFICATION doctype.

Syntax

<RUNNING_TITLE> (

• OFF
• title-1 [\title-2]
• [\FIRST_PAGE]

)

ARGUMENTS

OFF

Specifies that any existing running titles created using the <RUNNING_TITLE> tag should be disabled for the page on which this tag occurs and on any subsequent pages.

title-1

Specifies the text of a running title. If a 2-line title is specified, this title outputs on the upper title line.

title-2

Specifies the optional bottom line of a running title that has two lines.

FIRST_PAGE

This is an optional keyword argument. It specifies that the running title is to begin output on the first output page. If you do not specify this keyword, the running title is output on the page after the current page.

related tags

• <RUNNING_FEET>

restrictions

Valid only in the SOFTWARE.SPECIFICATION doctype.

DESCRIPTION

The <RUNNING_TITLE> tag creates a 1- or 2-line running heading at the top of each page in a document processed using the SOFTWARE.SPECIFICATION doctype. Use the FIRST_PAGE argument to the <RUNNING_TITLE> tag to begin the title lines on the first page of output, rather than on the page after the current page as is the default.

Use the OFF argument to disable any existing running titles created using the <RUNNING_TITLE> tag. These titles will then be disabled for the page on which this tag occurs and on any subsequent pages.

Use the <RUNNING_FEET> tag to create a heading that appears at the bottom of the page. See the reference description of the <RUNNING_FEET> tag for more information on that tag.

Examples

The following example shows how to use the <RUNNING_TITLE> tag to create the 2-line running title An E. B. Bartz Course: and Writing Quality Correspondence. Since the FIRST_PAGE argument is used, the 2-line running title will appear at the top of the first page.

<RUNNING_TITLE>(An E. B. Bartz Course:\Writing Quality Correspondence\FIRST_PAGE) 
<HEAD1>(How to Write a Letter\37_HowtoWriteaLetter) 
<P> 
The first thing that you should do in writing a letter is to get 
a clean piece of paper and a well-sharpened pencil. 
 

The following example shows how to disable a running title by using the OFF argument to the <RUNNING_TITLE> tag.

<COMMENT>(turn off running titles for the following example page) 
<RUNNING_TITLE>(OFF) 
<HEAD>(An Example of a Letter\38_AnExampleofaLetter) 
. 
. 
. 
 

Begins a new tag description.

Syntax

<SDML_TAG> (tag name\symbol name)

ARGUMENTS

tag name

Specifies the name of the tag to be described.

symbol name

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

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

• <SET_TEMPLATE_TAG>
• <TAG_SECTION>

restrictions

Valid only in the context of the Tag template.

DESCRIPTION

The <SDML_TAG> tag begins a new tag description. The <SDML_TAG> tag has the following default format:

• Each <SDML_TAG> tag begins a new page of output.
• Each output page carries a single running title, which is the current SDML tag name.

Use the <SET_TEMPLATE_TAG> tag to replace the <SDML_TAG> tag with a tag specific to your task (for example, <LOCAL_TAG>) or if you want to change the default attributes of the <SDML_TAG> tag. See the description of the <SET_TEMPLATE_TAG> tag in this chapter for more information.

Example

The following example shows the Tag template begun using the <TAG_SECTION> tag. In this tag section, the <SDML_TAG> tag begins the tag description for the local <LEVEL1> tag.

<TAG_SECTION>(Local Tags) 
<SDML_TAG>(LEVEL1\level_tag_sym) 
<OVERVIEW> 
Labels the first level of a diagram. 
<ENDOVERVIEW> 
 

Sets up a user-defined argument list for documenting callable routines for multiple operating system platforms. Also allows translation of the argument list.

Syntax

<SET_TEMPLATE_ARGITEM> (tag name

• \text one
• \text two
• \text three
• [\text four]
• [\text five]
• \longest text

)

ARGUMENTS

tag name

Defines the <ARGITEM> tag name.

text one

Defines the first related text to be automatically output for argument two in the list.

text two

Defines the second related text to be automatically output for argument three in the list.

text three

Defines the third related text to be automatically output for argument four in the list.

text four

This is an optional argument; if you do not use it, you must specify it as null. Defines the fourth related text to be automatically output for argument five in the list.

text five

This is an optional argument; if you do not use it, you must specify it as null. Defines the fifth related text to be automatically output for argument six in the list.

longest text

Defines the longest text in the argument list. It is positional; it must be argument seven.

related tags

• <ARGDEFLIST>
• <ARGITEM>
• <ROUTINE_SECTION>

restrictions

Valid only in the context of a <ROUTINE_SECTION> tag.

Only one <SET_TEMPLATE_ARGITEM> tag has effect at a time, so that an occurrence of the <SET_TEMPLATE_ARGITEM> tag cancels the setting of a previous one.

DESCRIPTION

The <SET_TEMPLATE_ARGITEM> tag sets up a user-defined argument list for documenting callable routines for multiple operating system platforms. This tag also allows translation of the argument list.

Example

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

<ROUTINE_SECTION>
<SET_TEMPLATE_ARGITEM>(UNIX_ARGS 
                      \UNIX type 
                      \MS-DOS type 
                      \access 
                      \mechanism 
                      \special 
                      \MS-DOS type) <COMMENT>( Longest text ) 
 
<ARGDEFLIST>
 
<UNIX_ARGS>(unix argument\one\two\three\four) 
<ARGDEF>This invocation of <UNIX_ARG> tag has four parameters. 
 
<UNIX_ARGS>(unix argument two\one\two\three\four\five) 
<ARGDEF>This invocation of <UNIX_ARG> tag has five parameters. 
<ENDARGDEFLIST>
 
<SET_TEMPLATE_ARGITEM>(MSDOS_ARGS 
                       \MS-DOS type 
                       \access 
                       \mechanism 
                       \usage 
                       \ <COMMENT>(Note blank argument; longest 
                                   text must be in argument 7!) 
                       \additionallongertext) 
 
<ARGDEFLIST>
<ARGITEM>(argument\one\two\three\four) 
<ARGDEF>This is a standard <ARGDEF> tag. 
 
 
<MSDOS_ARGS>(msdos argument two\one\two\three\four) 
<ARGDEF>This is a new tag, overriding the last. 
 
<ARGITEM>(argument\one\two\three\four) 
<ARGDEF>This is a standard <ARGDEF> tag. 
 
 
<ENDARGDEFLIST>
<ARGDEFLIST>
<MSDOS_ARGS>(msdos argument two\one\two\three\four) 
<ARGDEF>This is a new tag, overriding the last. 
 
<ENDARGDEFLIST>
 
<SET_TEMPLATE_ARGITEM>(OST_ARGS 
                       \OST type 
                       \access 
                       \mechanism 
                       \ <COMMENT>(Note blank argument; 
                                   longest text must be in argument 7!) 
                       \
                       \additionallongertext) 
 
<ARGDEFLIST>
<MGDOS_ARGS>(msdos argument two\one\two\three) 
<ARGDEF>This is a new tag, overriding the last. 
 
<MGDOS_ARGS>(msdos argument two\one\two\three) 
<ARGDEF>This is a new tag, overriding the last. 
 
<MGDOS_ARGS>(msdos argument two\one\two\three\four) 
<ARGDEF>This is a new tag, overriding the last. 
 
<ENDARGDEFLIST>
<ENDROUTINE_SECTION>

Defines a new tag with the same function as the <COMMAND> tag, and changes the format of command descriptions produced using the new tag.

Syntax

<SET_TEMPLATE_COMMAND> (tag name

• [\DOUBLE-
• RUNNINGHEADS]
• [\NONEWPAGE]
• [\STACK]

[\symbol name])

ARGUMENTS

tag name

Specifies the name of the template tag being defined. This tag name must be a valid tag name less than 31 characters and must not be the same as an existing tag name other than COMMAND (the default tag name).

DOUBLERUNNINGHEADS

This is an optional keyword argument. It enables two running titles at the top of every page. The top running title is set by the <COMMAND_SECTION> tag or by the heading of the most recent <CHAPTER> or <APPENDIX> tag. By default, if a doctype does not call for running top titles, only the current command name is placed at the top of each page.

NONEWPAGE

This is an optional keyword argument. It prevents command descriptions from starting on new pages. By default, each tag name template tag begins a command description on a new page.

STACK

This is an optional keyword argument. It stacks multiple arguments to the tag name tag. By default, when you specify multiple arguments, the second and third arguments are assumed to be optional descriptive information, and output on the same line as the command name.

symbol name

This is an optional argument for printed output, but is required for using the file in a bookbuild for Bookreader. This argument specifies the name of the symbol used in all references to this tag.

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>
• <COMMAND_SECTION>

restrictions

Valid only in the context of the <COMMAND_SECTION> tag in the Command template.

DESCRIPTION

The <SET_TEMPLATE_COMMAND> tag defines a new tag with the same function as the <COMMAND> tag, and changes the format of command descriptions produced using the new tag.

This tag also changes the default attributes associated with the <COMMAND> tag, or gives your new tag different attributes than the <COMMAND> tag.

Examples

<COMMAND_SECTION>(FDL Commands\\NEWPAGE) 
<SET_TEMPLATE_COMMAND>(FDL_COMMAND\NONEWPAGE\STACK\DOUBLERUNNINGHEADS) 
<FDL_COMMAND>(STARTUP_FILE\STF) 
 
 

These tags begin a command section and define the <FDL_COMMAND> tag as the command descriptor tag. The attributes set are as follows:

• Commands do not start on new pages.
• When two arguments are specified to the <FDL_COMMAND> tag, the arguments are stacked. That is, the second argument is printed under the first.
• Each page carries a 2-line running title. The top line is FDL Commands and the second line is the name of the command description that is current at the top of the page.

Note that this command sequence is most appropriate for a series of command descriptions that occur in a chapter.

<PART> 
<PART_PAGE> 
<TITLE>(PART II\XYZ Commands) 
<ENDPART_PAGE>(RENUMBER) 
<COMMAND_SECTION>(XYZ Commands\XYZ) 
<SET_TEMPLATE_COMMAND>(XYZ_COMMAND) 
 
 

These tags begin a document part in which only command descriptions occur. The RENUMBER argument on the <ENDPART_PAGE> tag specifies that the first page of the new Part (the part page itself) should be numbered page 1. The <COMMAND_SECTION> tag sets the folio prefix to XYZ; that is, pages will be numbered XYZ--3, XYZ--4, and so on.

No attributes are specified for the command descriptions produced by the <XYZ_COMMAND> tag. These commands will have default attributes. The first command will start on a new page. Since RENUMBER was specified on the <ENDPART_PAGE>tag, the first command will be on the page numbered XYZ--3.