DECdocument
Using Doctypes and Related Tags
Volume 2
Previous Contents Index

This example produces the following output.

codes

2-byte||3-byte||4-byte abc def
ghi

<SET_TEMPLATE_TAG>

Defines a new reference element tag name to use in the tag template, and specifies formatting attributes for the newly defined tag.

Syntax

<SET_TEMPLATE_TAG> (tag name
[\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 SDML_TAG (which is the default tag name).

DOUBLERUNNINGHEADS

This is an optional keyword argument. It specifies that the tag descriptions for the tag name tag will have two running titles at the top of every page. The top running title is set by the <TAG_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 tag name prints at the top of each page.

NONEWPAGE

This is an optional keyword argument. It specifies that tag descriptions are not to start on new pages. By default, each tag name template tag begins a tag description on a new page.

STACK

This is an optional keyword argument. It specifies that when you give multiple arguments to the tag name tag, the arguments are stacked at the beginning of the page.

By default, when you specify multiple arguments, the second and third arguments are assumed to be optional descriptive information, and are output on the same line as the tag 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

restrictions

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

DESCRIPTION

The <SET_TEMPLATE_TAG> tag defines a new reference element tag name to use in the tag template, and specifies formatting attributes for the newly-defined tag.

This tag also lets you alter the default attributes associated with the <SDML_TAG> tag (or the tag you replaced with the <SDML_TAG> tag using the <SET_TEMPLATE_TAG> tag).

Example

The following example shows how to use the <SET_TEMPLATE_TAG> tag to alter the default format of the Tag template. 

<TAG_SECTION>(Tag Template Tags) 
<SET_TEMPLATE_TAG>(LOCAL_TAG\DOUBLERUNNINGHEADS) 
<LOCAL_TAG>(LEVEL1)

This tag sequence begins a tag section and defines the <LOCAL_TAG> tag for introducing new tag descriptions. These attributes are as follows:

<SIGNATURES>

Begins a list of signatures that are to appear in the front matter portion of a document processed using the SOFTWARE.SPECIFICATION doctype.

Syntax

<SIGNATURES> [(NEWPAGE)]

ARGUMENTS

NEWPAGE

This is an optional keyword argument. It specifies that the signature list is to begin on a new page.

related tags

restrictions

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

DESCRIPTION

The <SIGNATURES> tag begins a list of signatures that are to appear in the front matter portion of a document processed using the SOFTWARE.SPECIFICATION doctype. Each person's name is listed by using the <BYLINE> tag following the <SIGNATURES> tag. The <BYLINE> tag places the name of the person, and additional information about that person (such as his or her title or affiliation), below a line on which the person is to sign.

See the reference description of the <BYLINE> tag for more information on that tag.

Example

See the example in the <BYLINE> tag description.

<STATEMENT>

Begins a new statement description.

Syntax

<STATEMENT> (statement name\symbol name)

ARGUMENTS

statement name

Specifies the name of the statement 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

DESCRIPTION

The <STATEMENT> tag begins a new statement description. This description is for a single statement in the context of the <STATEMENT_SECTION> tag. This tag has the following default format: Use the <SET_TEMPLATE_STATEMENT> tag to replace the <STATEMENT> tag with a tag specific to your task (for example, the <ABC_STATEMENT> tag), or if you wish to change the default attributes of the <STATEMENT> tag. See the description of the <SET_TEMPLATE_STATEMENT> tag for more information.

Example

In the following example, the <STATEMENT_SECTION> tag enables the tags for a statement description. By default, the description of the statement OPEN has the following attributes: 


<STATEMENT_SECTION> 
<STATEMENT>(OPEN) 
<OVERVIEW> 
<ellipsis>

<STATEMENT_FORMAT>

Begins a section that illustrates the syntax of a statement or function, including keywords and parameters.

Syntax

<STATEMENT_FORMAT> [([alternate heading]
[\MULTIPLE])]

ARGUMENTS

alternate heading

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

MULTIPLE

This is an optional keyword argument. It indicates that the statement has more than one format, and that each format will be introduced using the <FORMAT_SUBHEAD> tag. This keyword is valid only as the second argument to the <STATEMENT_FORMAT> tag.

related tags

required terminator

<ENDSTATEMENT_FORMAT>

DESCRIPTION

The <STATEMENT_FORMAT> tag begins a section that illustrates the syntax of a statement or function, including keywords and parameters. Like the global <FORMAT> tag, the <STATEMENT_FORMAT> tag enables the <FCMD> and <FPARMS> tags to label specific portions of a statement format section.

The following is a list of some of the most regularly used statement format section tag combinations:

Following the formatted statement, the <CONSTRUCT_LIST> and <STATEMENT_LINE> tags can be used to expand on the meanings of variable names specified in the format. Such variable names can be coded using the <VARIABLE> or <KEYWORD> tags.

Examples

The following two input examples show various uses of the <STATEMENT_FORMAT> tag. Output from these coding examples appears after the last input example.

The following input example shows a statement format section that uses the <FFUNC> tag to present the format of a statement.

#1 

<STATEMENT_FORMAT> 
<FFUNC>(real-vbl\=ABS<VARIABLE>((real-exp))) 
<endstatement_format>

The following input example illustrates the use of multiple formats for a single statement, with special headings for each. Note the special use of the <FORMAT_SUBHEAD> tag to introduce each specific format.

#2 

<statement_format>(\multiple) 
<FORMAT_SUBHEAD>(String Variable To Array) 
<FCMD>(CHANGE) <FPARMS>(str-exp <KEYWORD>(TO) num-array) 
<FORMAT_SUBHEAD>(Array to String Variable) 
<FCMD>(CHANGE) <FPARMS>(num-array <KEYWORD>(TO) str-vbl) 
<endstatement_format>

These input examples produce the following output:

Format

real-vbl =ABS(real-exp)

Format

String Variable To Array

CHANGE str-exp TO num-array

Array to String Variable

CHANGE num-array TO str-vbl

<STATEMENT_LINE>

Indicates the position of a valid statement line in the context of a statement format or a construct list.

Syntax

<STATEMENT_LINE> [(text[\INDENT])]

ARGUMENTS

text

This is an optional argument. It specifies the text for a valid statement line. If no text is specified, the default statement line output is as follows: 


[ statement ]...

INDENT

This is an optional keyword argument. It indicates that the statement line is to be indented from the margin at which the current statement format or construct list is being set.

related tags

restrictions

Valid only in the context of the Statement reference template.

DESCRIPTION

The <STATEMENT_LINE>tag indicates the position of a valid statement line in the context of a statement format or a construct list.

Examples

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

The following input example shows how to use <STATEMENT_LINE> in a formatted statement section.

#1 

<STATEMENT_FORMAT> 
<FCMD>(RECORD) <FPARMS>(rec-nam) 
<STATEMENT_LINE>(rec-component) 
<ELLIPSIS> 
<FCMD>(END RECORD) <FPARMS>([ rec-nam ]) 
<ENDSTATEMENT_FORMAT>

The following input example shows how to use the <STATEMENT_LINE> tag in a construct list. Note that the first use of the tag specifies INDENT as the second argument.

#2 

<STATEMENT_FORMAT> 
<CONSTRUCT_LIST>(group-clause:) 
<construct>(group-clause:) 
    <keyword>(GROUP) group-nam [ ( int-const,<hellipsis> ) ] 
    <statement_line>(rec-component\indent) 
    <ellipsis> 
    <statement_line>(<keyword>(END GROUP) [ group-nam ]) 
<ENDCONSTRUCT_LIST> 
<ENDSTATEMENT_FORMAT>

The following input example shows the default output for the <STATEMENT_LINE> tag when it is used in a statement format section.

#3 

<STATEMENT_FORMAT> 
<FCMD>(SUB) <FPARMS>(sub-name [ pass-mech ] [ ( [ formal-param ], 
                     <hellipsis> ) ]) 
<statement_line> 
<FCMD>(<list>(stacked\braces) 
        <le>END SUB 
        <le>SUBEND<endlist>) <FPARMS>() 
<endstatement_format>

These input examples produce the following outputs:

Format

RECORD rec-nam


rec-component
.
.
.

END RECORD [ rec-nam ]

Format

group-clause: GROUP group-nam [ ( int-const,...)]
rec-component
.
.
.
END GROUP [ group-nam ]

Format

SUB sub-name [ pass-mech ] [ ( [ formal-param ],...)]


[ statement ]...

<STATEMENT_SECTION>

Begins a statement reference section, enables tags reserved for use in statement sections, and sets paging attributes.

Syntax

<STATEMENT_SECTION> ([([running title]
[\number prefix]
[\NEWPAGE])])

ARGUMENTS

running title

This is an optional argument. It specifies a top-level running heading to be used throughout the statement section. If you do not specify this argument, the running headings are determined as described in 2.13.

number prefix

This is an optional argument. It specifies a character-string prefix to be used to construct page numbers (folios) and formal figure, table, and example numbers. If you do not specify this argument, the page and formal element numbering are determined as described in 2.13.

NEWPAGE

This is an optional keyword argument. It indicates that the statement section should begin on a new page. This argument is only meaningful in two cases:

related tags

required terminator

<ENDSTATEMENT_SECTION>

DESCRIPTION

The <STATEMENT_SECTION> tag begins a statement reference section, enables tags reserved for use in statement sections, and sets paging attributes. You can locate a statement section in a chapter or an appendix, or following a part page (that is, in a document section begun with the <PART_PAGE> tag). You code a statement section in a chapter or an appendix in the same manner; statement sections in parts are handled differently.

If your statement section follows a part page, and you include text between the part page and the statement section, specify the NEWPAGE keyword as the third argument to the <STATEMENT_SECTION> tag. This causes the statement section to begin on a new page. The following code fragment shows a statement section that begins on a new page: 


<STATEMENT_SECTION>(\SD\NEWPAGE) 
<HEAD1>(Statement Format\44_StatementFormat)

When you use the <STATEMENT_SECTION> tag in a chapter or an appendix, and you want to place text after the statement section in that chapter or appendix, you must end the statement section with the <ENDSTATEMENT_SECTION> tag and place the text after that tag. By default, this text begins on a new page of output.

Specify the NONEWPAGE argument to the <ENDSTATEMENT_SECTION> tag if you do not want the text to begin on a new page of output. The following code fragment shows the end of a statement section that specifies that the subsequent text not be placed on a new page: 


<ENDSTATEMENT_SECTION>(NONEWPAGE)

When the <ENDSTATEMENT_SECTION> tag is specified in the context of a chapter or appendix, it resets the default running titles to those in effect for the chapter or appendix, so the last page of the last statement description in the statement section may not carry the last statement's name as the running heading. Instead it may carry the running title used by the chapter or appendix.

The <STATEMENT_SECTION> tag can be used more than once in a document. By specifying arguments to that tag, and by using the <SET_TEMPLATE_STATEMENT> tag to specify additional attributes, you can tailor statement sections that meet the specific requirements of your documentation.

Examples

The following example shows how to begin a statement section in a document part.
#1 

<PART> 
<PART_PAGE> 
<TITLE>(Part III\BASIC Statements and Functions) 
<ENDPART_PAGE>(RENUMBER) 
<STATEMENT_SECTION>(Statements and Functions\SF) 
<SET_TEMPLATE_STATEMENT>(BASIC_STATEMENT) 
 
<BASIC_STATEMENT>(GROUP) 
<OVERVIEW> 
Creates a group in a database. 
<ENDOVERVIEW 
. 
. 
. 
<ENDSTATEMENT_SECTION>

The tags in the previous example perform the following functions:

The following example shows how you can create a statement section in which each statement description (begun with a <STATEMENT> or <FUNCTION> tag) is in a separate SDML file, and all these descriptions are included into a primary statement description file. For example, the file MYSTATEMENTS.SDML contains the following SDML tags: 


<INCLUDE>(CLOSE_GROUP.SDML) 
<INCLUDE>(OPEN_GROUP.SDML) 
<INCLUDE>(READ_GROUP.SDML) 
<INCLUDE>(WRITE_GROUP.SDML)

Each of the included files contains one statement reference description begun with a <STATEMENT> or <FUNCTION> tag. For these files to process correctly, they must be preceded with the <STATEMENT_SECTION> tag that enables the <STATEMENT> and <FUNCTION> tag. These files can have the necessary tags processed by specifying the /INCLUDE qualifier on the command line to include a startup definition file. This startup file might include the following tags:

#2 

<STATEMENT_SECTION>(Group Statements\GS) 
<SET_TEMPLATE_STATEMENT>(STATEMENT\DOUBLERUNNINGHEADS)

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


$ DOCUMENT mystatements SOFT.REF LN03-
_$ /INCLUDE=GS_STATEMENT_STARTUP.SDML

When each individual file in MYSTATEMENTS.SDML is processed, the correct sequence of tags is read in to begin the statement section.

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

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


<PROFILE> 
<ELEMENT>(CLOSE_GROUP.SDML) 
<ELEMENT>(OPEN_GROUP.SDML) 
<ELEMENT>(READ_GROUP.SDML) 
<ELEMENT>(WRITE_GROUP.SDML 
          <COMMENT>(**contains <ENDSTATEMENT_SECTION> tag**) 
<ENDPROFILE>

Note that the PROFILE file should include the <ENDSTATEMENT_SECTION> tag in the appropriate file, so that the template will be terminated and the bookbuild will process correctly.

<SUBCOMMAND>

Begins a new subcommand description.

Syntax

<SUBCOMMAND> (subcommand name\symbol name)

ARGUMENTS

subcommand name

Names the command described in the subcommand section.

symbol name

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

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

DESCRIPTION

The <SUBCOMMAND> tag begins a new subcommand description. Subcommand sections have these format defaults:

To change the name of the <SUBCOMMAND> tag, or to change its default attributes, see the description of the <SET_TEMPLATE_SUBCOMMAND> tag.

Examples

In the following example, the <SUBCOMMAND_SECTION> tag enables the tags for a subcommand description. The description of the subcommand OPEN, by default, has the following attributes:
  1. The subcommand description begins on a new page.
  2. If the subcommand carries for more than a page, the name OPEN is carried as a running top title on each page.
#1 

<SUBCOMMAND_SECTION> 
<SUBCOMMAND>(OPEN) 
<OVERVIEW> 
   .
   .
   .

In the following example, the <SUBCOMMAND_SECTION> tag starts a subcommand section and gives it the title File System Subcommands. In this command section, each page of output carries this title at the top of the page, with the name of the current subcommand just below it, until the <ENDSUBCOMMAND_SECTION> tag ends that titling.

#2 

<SUBCOMMAND_SECTION>(File System Subcommands) 
<SUBCOMMAND>(CLOSE)

Previous Next Contents Index