DECdocument
Using Doctypes and Related Tags
Volume 2
Previous Contents Index

<COMMAND_SECTION>

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

Syntax

<COMMAND_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 command section. If you do not specify this argument, the running headings are determined as described in Section 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 Section 2.13.

NEWPAGE

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

related tags

restrictions

Valid only in the context of the Command template.

required terminator

<ENDCOMMAND_SECTION>

DESCRIPTION

The <COMMAND_SECTION> tag begins a new command description. Place a command 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 command section in a chapter or an appendix in the same manner; command sections in parts are handled differently.

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


<COMMAND_SECTION>(\CD\NEWPAGE)

Examples

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

<PART> 
<PART_PAGE> 
<TITLE>(Part III\Command Dictionary) 
<ENDPART_PAGE>(RENUMBER) 
<COMMAND_SECTION>(Command Dictionary\CD) 
<SET_TEMPLATE_COMMAND>(DCL_COMMAND) 
 
<DCL_COMMAND>(GOTO) 
<OVERVIEW> 
Transfers control to a labeled statement in a command procedure. 
<ENDOVERVIEW 
. 
. 
. 
<ENDCOMMAND_SECTION>

The tags in the previous example perform the following functions:

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


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

Each of the included files contains one command reference description begun with a <COMMAND> tag. For these files to process correctly, you must precede them with the <COMMAND_SECTION> tag, which enables the <COMMAND> 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.

#2 

<COMMAND_SECTION>(Command Dictionary\CD) 
<SET_TEMPLATE_COMMAND>(COMMAND\DOUBLERUNNINGHEADS)

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


 
$DOCUMENT mycom SOFT.REF LN03 /INCLUDE=CM_DCT_ST_UP.SDML

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

Process multiple files together by using the <INCLUDE> tag to include them into a single master file (such as MYCOM.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 CDPRO.SDML could contain the following tags: 


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

Note that the PROFILE file includes the <ENDCOMMAND_SECTION> tag in the appropriate file, so that the template terminates and the book builds correctly.

<CONSTRUCT>

Specifies a variable construct and gives its expansion.

Syntax

<CONSTRUCT> [(construct name)]

ARGUMENTS

construct name

This is an optional argument. It specifies the name of a construct. If you omit this argument, text following the <CONSTRUCT> tag formats as if you had specified text. The text is set at the same margin as additional construct items.

related tags

restrictions

Valid only in the context of the <STATEMENT_FORMAT> tag in the Statement template.

DESCRIPTION

The <CONSTRUCT> tag specifies a variable construct and gives its expansion.

Example

The following example shows statement format for a statement with a single construct list. Note the use of <LIST> tags to specify the output and the <KEYWORD> tag to control the representation of programming keywords in variable name text. 

<statement_format> 
<FCMD>(REMAP) <FPARMS>((map nam) remap item,<hellipsis>) 
<construct_list>(remap item:) 
<construct>(remap item:)<list>(stacked\braces) 
    <le>num vbl nam 
    <LE>str array nam ( [ int exp,<hellipsis>] )[ = int exp ] 
    <LE>[ data type ] <keyword>(FILL) [ ( int exp) ] [ = int exp ] 
    <LE><keyword>(FILL%) [ ( int exp ) ] 
    <LE><keyword>(FILL$) [ ( int exp ) ][ = int exp ] 
    <endlist> 
<endconstruct_list> 
<endstatement_format>

This example produces the following output:

Format

REMAP (map nam) remap item,...

remap item:

<CONSTRUCT_LIST>

Begins a list of construct items and definitions that expand on variables specified in the context of the <STATEMENT_FORMAT> tag.

Syntax

<CONSTRUCT_LIST> (construct name)

ARGUMENTS

construct name

Specifies the text of the longest name referenced in the construct list; that is, a name specified as an argument to <CONSTRUCT>.

related tags

restrictions

Valid only in the context of a <STATEMENT_FORMAT> tag section in the Statement template.

required terminator

<ENDCONSTRUCT_LIST>

DESCRIPTION

The <CONSTRUCT_LIST> tag begins a list of construct items and definitions that expand on variables specified in the context of the <STATEMENT_FORMAT> tag. A construct list is a set of semantic rules for a programming language. Each item in a construct list is a semantic entity that may expand to one or more sets of additional constructs or entities. Using the global <LIST> tag in a construct list in a statement section, you can present the semantic rules for language statements in a highly structured way.

Examples

The following are two examples of various uses of the <CONSTRUCT_LIST>tag in the context of the <STATEMENT_FORMAT> tag. Output from these coding examples appear after the last input example.

The following example shows a construct list with only one construct.

#1 

<statement_format> 
<fcmd>(<list>(stacked\braces) 
<le>COM 
<le>COMMON<endlist>) <fparms>([ ( com nam ) ] {[data type ] com item },<hellipsis>) 
<construct_list>(com item:) 
<construct>(com item:) 
<list>(stacked\braces) 
<le><VARIABLE>(num unsubs vbl nam) 
<le><VARIABLE>(num array nam ( int const,<hellipsis>)) 
<le><VARIABLE>(str unsubs vbl nam = int const) 
<le><VARIABLE>(str array nam ( int const,<hellipsis> ) [ = int const ]) 
<le><VARIABLE>(<keyword>(FILL) [ ( int const ) ][ = int const ]) 
<le><VARIABLE>(<keyword>(FILL%) [ ( int const ) ]) 
<le><VARIABLE>(<keyword>(FILL$) [ ( int const ) ][ = int const ]) 
<endlist> 
<endconstruct_list> 
<endstatement_format>

The following example illustrates a construct list with more than one construct. The argument to the <CONSTRUCT_LIST> tag sets the margins for the individual items identified by <CONSTRUCT> tags. Note that the text of the longest item, formal param:, is specified.

#2 

<FCMD>(<list>(stacked\braces) 
        <le>END SUB 
        <le>SUBEND<endlist>) <FPARMS>() 
<construct_list>(formal param:) 
<construct>(pass mech:)<list>(stacked\braces) 
                       <le><keyword>(BY DESC) 
                       <le><keyword>(BY REF)<endlist> 
<construct>(formal param:) 
[ data type ] <list>(stacked\braces) 
               <le>unsubs vbl nam 
               <le>array nam ( <list>(stacked\brackets) 
                                <le>int const 
                                <le><keyword>(,)<endlist> 
                                <list>(stacked) 
                                <le><keyword>(,<hellipsis>) 
                                <le><keyword>(<hellipsis>)<endlist>)<endlist> 
<endconstruct_list> 
<endstatement_format>

The SDML examples produce the following output:

Format

[ ( com nam ) ] {[data type ] com item },...

com item:

Format

pass mech: formal param: [ data type ]

<CPOS>

Marks the cursor position in a screen display.

Syntax

<CPOS> (placement character)

ARGUMENTS

placement character

Specifies the character occupying the position of the cursor. This character can be a blank space.

related tags

DESCRIPTION

The <CPOS> tag marks the cursor position in a screen display. It places a special character in the screen display.

Example

The following example shows how to use the <CPOS> tag to indicate a cursor's position. In this case the cursor is placed on the letter X in the directory specification [TRXTFILES]. 

<P> 
To correct the file specification, move the 
cursor to the incorrect letter as shown in the following example: 
<DISPLAY> 
     $ COPY ABC.TXT [TR<CPOS>(X)TFILES] 
<ENDDISPLAY>

This example produces the following output:

To correct the file specification, move the cursor to the incorrect letter as shown in the following example: 


     $ COPY ABC.TXT [TRXTFILES]

<DELETE_KEY>

Creates a special character resembling a DELETE key on a keyboard.

Syntax

<DELETE_KEY>

ARGUMENTS

None.

related tags

DESCRIPTION

The <DELETE_KEY> tag creates a special character resembling a DELETE key on a keyboard.

Example

The following example shows how to use the <DELETE_KEY> tag to create the delete key symbol. 

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

This example produces the following output:

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

<DESCRIPTION>

Begins a section of descriptive text providing detailed information on the current reference element.

Syntax

<DESCRIPTION> [(alternate heading)]

ARGUMENTS

alternate heading

This is an optional argument. It specifies a heading. The default heading is Description. For information on how to modify the default headings for all subsequent <DESCRIPTION> tags, refer to the description of the <SET_TEMPLATE_HEADING> tag in this section.

related tags

restrictions

Valid only in the context of a reference template. Valid only in the context of a reference section tag: <COMMAND_SECTION>, <ROUTINE_SECTION>, <STATEMENT_SECTION>, or <TAG_SECTION>.

required terminator

<ENDDESCRIPTION>

DESCRIPTION

The <DESCRIPTION> tag begins a section of descriptive text providing detailed information on the current reference element. It separates and labels detailed descriptive text concerning the current reference element (command, routine, and so on). This text can describe the following aspects of the reference element:

Do not use a <P> tag immediately after the <DESCRIPTION> tag. The <DESCRIPTION> tag generates the initial open line so that you need only begin typing the first paragraph of text.

Example

The following example shows a sample use of the <OVERVIEW> and <DESCRIPTION> tags in the context of the Command template. The Command template <COMMAND> tag and the global <FORMAT> and <PARAMDEFLIST> tags are included to make a more complete example. Notice that the <COMMAND> tag forces a page break by default. 

<COMMAND_SECTION> 
<COMMAND>(SET TIME) 
<OVERVIEW> 
Resets the system time to the time specified as a parameter to this command. 
<ENDOVERVIEW> 
<format>(Syntax) 
<FCMD>(SET TIME) 
<FPARMS>(time specification) 
<ENDFORMAT> 
<PARAMDEFLIST> 
<PARAMITEM>(time specification) 
<PARAMDEF> Specifies the time to which the system should be set. 
<ENDPARAMDEFLIST> 
<DESCRIPTION> 
The SET TIME command resets the system time to the time specified as a 
parameter to this command. You generally use this command to reset the 
system clock on your VMS system, for example to allow for daylight 
savings time and other such events. 
<ENDDESCRIPTION> 
<ENDCOMMAND_SECTION>

<DISPLAY>

Simulates the appearance and position of characters on a terminal screen.

Syntax

<DISPLAY> (display text)


<DISPLAY> [(
  • KEEP
  • WIDE[\MAXIMUM]
)]

ARGUMENTS

display text

Specifies a display fragment you want to insert into your text. If you do not specify this argument, the <ENDDISPLAY> tag is required.

KEEP

This is an optional keyword argument. It specifies that the display example should be placed on the next page rather than breaking it between the current page and the next page. If the display example is longer than a single page, it breaks between the current page and the next page.

WIDE

This is an optional keyword argument. It specifies a wide display that may exceed the normal right margin of the text.

MAXIMUM

This is an optional keyword argument. It specifes that the example may require adjustment to fit in the bounds of the text page. May be used only with the WIDE keyword. Using this argument may result in the display text being output in a smaller type face.

related tags

restrictions

You cannot use tab characters, index tags (such as <X> and <Y>), text element tags (such as <P>, <LIST>, or <NOTE>), or the <MATH> tag in any example.

required terminator

<ENDDISPLAY> Required if you do not specify the display example as the display text argument.

DESCRIPTION

The <DISPLAY> tag simulates the appearance and position of characters on a terminal screen. This tag lets you create display examples either as fragments in text or as extended examples. Such display examples are distinguished typographically from the surrounding text upon output.

To place a display fragment in the text of your document, specify the display text argument as the only argument to the <DISPLAY> tag and do not specify the <ENDDISPLAY> tag. This format is shown first in the format section of the <DISPLAY> tag.

If you have a long display example that you want to appear distinctly separate from the text of your document, place the text for the example between the <DISPLAY> and <ENDDISPLAY> tags. This format is shown second in the format section of the <DISPLAY> tag.

Display examples specified in this way retain all spaces and line breaks as entered. This lets you position the text in the example so that it appears similar to a terminal screen display. When you specify display examples in this form, you use the KEEP, WIDE, and MAXIMUM keyword arguments to control the formatting of your example.

If you have an especially long display example, you may want to use the <VALID_BREAK> tag in your example to indicate where a page may break.

Examples

The following example shows a display example that uses the <DISPLAY> and <ENDDISPLAY> tags. Note the use of the KEEP keyword to ensure that the display example is not broken across the page.
#1 

<P> 
The operating system indicates success with the following 
message: 
<DISPLAY>(KEEP) 
            Welcome to VAX/VMS Version 5.4 
   Username: 
<ENDDISPLAY>

This example produces the following output:

The operating system indicates success with the following message: 


            Welcome to VAX/VMS Version 5.4 
 
   Username:

The following example shows the <DISPLAY> tag used to create a display fragment in text. Note that the <ENDDISPLAY> tag is omitted and that no keywords to the <DISPLAY> tag can be specified.

#2 

<P>The message <DISPLAY>(Welcome to VAX/VMS Version 5.4) 
is issued by default  when a user presses RETURN.

This example produces the following output:

The message Welcome to VAX/VMS Version 5.4 is issued by default when a user presses RETURN.

Previous Next Contents Index