DECdocument
Using Global Tags

The following example shows how to use the <CODE_EXAMPLE> and <ENDCODE_EXAMPLE> tags in an informal example.

#2

<EXAMPLE> <CODE_EXAMPLE> $! $! The next two lines redefine the cmd. line prompt to be the node $! name's initial. $! $ NODE :=='F$LOGICAL("SYS$NODE")' $ SET PROMPT="''F$EXTRACT(1,1,NODE)':" $! <ENDCODE_EXAMPLE> <ENDEXAMPLE>

This example produces the following output:
$! $! The next two lines redefine the cmd. line prompt to be the node $! name's initial. $! $ NODE :=='F$LOGICAL("SYS$NODE")' $ SET PROMPT="''F$EXTRACT(1,1,NODE)':" $!
The following example shows how to use the <CODE_EXAMPLE> and <ENDCODE_EXAMPLE> tags in a formal example.

#3

<EXAMPLE>(Login Commands\login_exam) 
<CODE_EXAMPLE>
 
$! 
$!   The next two lines redefine the cmd. line prompt to be the node 
$!   name's initial. 
$! 
$ NODE :=='F$LOGICAL("SYS$NODE")' 
$ SET PROMPT="''F$EXTRACT(1,1,NODE)':" 
$! 
 
<ENDCODE_EXAMPLE>
<ENDEXAMPLE>

This example produces the following output:
Example n--n: Login Commands
________________________________________________________________________ $! $! The next two lines redefine the cmd. line prompt to be the node $! name's initial. $! $ NODE :=='F$LOGICAL("SYS$NODE")' $ SET PROMPT="''F$EXTRACT(1,1,NODE)':" $! ________________________________________________________________________
The following example shows how to use the <INTERACTIVE>, <ENDINTERACTIVE>, <S>, and <U> tags within an example. Note that you should specify whatever space follows the system prompt within the <S> tag.

#4

<P>If you do not specify the full command line, DCL will prompt 
you for the missing information. For example, if you do not specify an 
input file and an output file when you enter the COPY command, you will 
be prompted as follows: 
<EXAMPLE>(Using the COPY Command\using_copy_command) 
<INTERACTIVE>
<S>($ )<U>(COPY) 
<S>($_From: )<U>(INTERACT.SDML) 
<S>($_To: )<U>(NEWFILE.SDML) 
<ENDINTERACTIVE>
<ENDEXAMPLE>

This example produces the following output:
If you do not specify the full command line, DCL will prompt you for the missing information. For example, if you do not specify an input file and an output file when you enter the COPY command, you will be prompted as follows:
Example n--n: Using the COPY Command
________________________________________________________________________ $ COPY $_From: INTERACT.SDML $_To: NEWFILE.SDML ________________________________________________________________________
The following example shows how to use the <SAMPLE_TEXT> tag within the <EXAMPLE> and <ENDEXAMPLE> tags to get specially formatted sample text within a formal example.

#5

<EXAMPLE>(Some Sample Text\sample_text) 
<SAMPLE_TEXT>
<P>This paragraph shows how to use the <tag>(sample_text) tag within the 
<tag>(example) and <tag>(endexample) tags to get specially formatted sample 
text within a formal example. 
<ENDSAMPLE_TEXT>
<ENDEXAMPLE>

This example produces the following output:
Example n--n: Some Sample Text
______________________________________________________________________
This paragraph shows how to use the <SAMPLE_TEXT> tag within the <EXAMPLE> and <ENDEXAMPLE> tags to get specially formatted sample text within a formal example.
______________________________________________________________________

<EXAMPLE_ATTRIBUTES>

Specifies attributes for the current example.

SYNTAX

<EXAMPLE_ATTRIBUTES> (

FLOAT
KEEP
MULTIPAGE
[\WIDE])

ARGUMENTS

FLOAT
Specifies whether the location of a one-page example is allowed to float. FLOAT indicates that if there is not enough room on the current page for the example, the text processor will fill the current page with the text from the source file that follows the <EXAMPLE> tag sequence, and place the example at the top of the next page of output.
Float is the default for an example that has a caption and does not specify MULTIPAGE or KEEP. FLOAT has no effect for Bookreader output.
KEEP
Specifies whether the example is to be kept with the text that immediately precedes it. KEEP has no effect for Bookreader output.
MULTIPAGE
Specifies that the example has multiple elements, and that each element is allowed to break at the start of a new page. This argument is required if the example elements require more than one page. When an example is continued, the example caption is automatically repeated at the beginning of each new page of output. MULTIPAGE has no effect for Bookreader output.
WIDE
This is an optional keyword argument. It specifies that the width of the example exceeds the document's default width for text. You can use WIDE with FLOAT, KEEP, or MULTIPAGE, or you can use WIDE as the only argument. Depending on the doctype, this argument is interpreted as follows:

If the doctype contains a left margin area that is normally used for headings, the example's width will span that area as well as the normal text area.
If the document uses a multicolumn format, the example suspends multicolumn output while the example is processed. The example is output across two columns and then multicolumn output is restored.
Depending on the doctype, this argument provides a range of font sizes and font styles for examples.

related tags

<EXAMPLE>
<EXAMPLE_FILE>
<EXAMPLE_SPACE>
<REFERENCE>

restrictions

Valid only in the context of an <EXAMPLE> tag.

DESCRIPTION

The <EXAMPLE_ATTRIBUTES> tag specifies attributes for the current example. By default, if an example does not fit on the current output page, it is placed at the top of the next page. The text that follows the example in the SDML file is used to fill the current output page. Thus, the example's position in the text may change. It is said to float. Formal examples that float, then, may appear out of place. Use the <EXAMPLE_ATTRIBUTES>(KEEP) tag to force the formal example to be kept with the text that immediately precedes it.
If you think the example will be longer than a page, use the MULTIPAGE keyword argument to indicate that the example requires more than one page of output. The example will not be allowed to float.
If the example is formal and you want to align the caption with the example (that has been extended into the left column), use the WIDE argument with both the <EXAMPLE_ATTRIBUTES> and <CODE_EXAMPLE> tags.

Example

This example shows how to use the MULTIPAGE and WIDE arguments to the <EXAMPLE_ATTRIBUTES> tag. Note the following:

The <VALID_BREAK> tags in the <CODE_EXAMPLE> provide the text formatter with information about suitable places to break pages.
Because the example is wide, the WIDE argument is specified not only for the <EXAMPLE_ATTRIBUTES> tag, but also for the <CODE_EXAMPLE> tag within the example.

<EXAMPLE>(Command Procedure for Adding a User\adduserex) 
<EXAMPLE_ATTRIBUTES>(MULTIPAGE\WIDE) 
<CODE_EXAMPLE>(WIDE) 
$ ! 
$ !   ADDUSER.COM -- Adds a new user to the system authorization file 
$ ! 
$ USERDISK = "WRKD$:"                ! Default disk for new users 
$ UAF = "$AUTHORIZE" 
<VALID_BREAK>
$ ON CONTROLY THEN GOTO CLEANUP 
$ ON WARNING THEN GOTO CLEANUP 
$ OLDDIR = F$LOGICAL("SYS$DISK") + F$DIRECTORY()' 
$ PREVPRIV = F$SETPRV("SYSPRV") 
$ IF .NOT. F$PRIVILEGE("SYSPRV") THEN GOTO NOPRIV 
$ SET DEFAULT SYS$SYSTEM 
$ ! 
$ !     Request account information 
$ ! 
$ INQUIRE USERNAME "Username" 
$ INQUIRE FULLNAME "Full name" 
$ SET TERMINAL/NOECHO 
$ INQUIRE PASSWORD "Password [''Username']" 
$ SET TERMINAL/ECHO 
$ IF PASSWORD .EQS. "" THEN PASSWORD = USERNAME 
$GET_GRP: 
$ INQUIRE GRP "UIC Group Number" 
$ IF GRP .EQS. "" THEN GRP = "*" 
$ WRITE SYS$OUTPUT "" 
$ WRITE SYS$OUTPUT "Determine the UIC from the following listing:" 
$ WRITE SYS$OUTPUT "" 
$ UAF SHOW ['GRP',*]/BRIEF 
$ INQUIRE UIC 
$ IF UIC .EQS. "" THEN GOTO GET_GRP 
$ IF F$LOCATE("[",UIC) .EQ. F$LENGTH(UIC) .AND. - 
      F$LOCATE("<",UIC) .EQ. F$LENGTH(UIC) THEN UIC = "[" + UIC + "]" 
$ INQUIRE ACCOUNT "Account Name [VMS]" 
$ IF ACCOUNT .EQS. "" THEN ACCOUNT = "VMS" 
$ INQUIRE PRIVS "Privileges [NONE]" 
$ IF PRIVS .NES. "" THEN PRIVS = "/PRIV=(" + PRIVS + ")" 
$ USERDIR = F$EXTRACT(0,9,USERNAME) 
$ INQUIRE TMP "Login Directory [''USERDIR']" 
$ IF TMP .NES. "" THEN USERDIR = TMP 
$ INQUIRE TMP "Login Device [''USERDISK']" 
$ IF TMP .NES. "" THEN USERDISK = TMP 
$ DQUOTA = 0 
$ IF F$SEARCH("''USERDISK'[0,0]QUOTA.SYS") .EQS. "" THEN GOTO NQ0 
$ DQUOTA = 1 
<VALID_BREAK>
 
$ ! 
$ !     Restore prior working environment 
$ ! 
$CLEANUP: 
$ SET TERMINAL/ECHO 
$ PREVPRIV = F$SETPRV(PREVPRIV) 
$ SET DEFAULT 'OLDDIR' 
$ EXIT 
$ ! 
$ !     In case proper privileges are not set 
$ ! 
s$NOPRIV: 
$ WRITE SYS$OUTPUT "You need SETPRV or SYSPRV privilege to run this procedure" 
$ GOTO CLEANUP 
<ENDCODE_EXAMPLE>
<ENDEXAMPLE>

This example produces the following output:

Example n--n: Command Procedure for Adding a User ___________________________________________________________________________________________________________ $ ! $ ! ADDUSER.COM -- Adds a new user to the system authorization file $ ! $ USERDISK = "WRKD$:" ! Default disk for new users $ UAF = "$AUTHORIZE" $ ON CONTROLY THEN GOTO CLEANUP $ ON WARNING THEN GOTO CLEANUP $ OLDDIR = F$LOGICAL("SYS$DISK") + F$DIRECTORY()' $ PREVPRIV = F$SETPRV("SYSPRV") $ IF .NOT. F$PRIVILEGE("SYSPRV") THEN GOTO NOPRIV $ SET DEFAULT SYS$SYSTEM $ ! $ ! Request account information $ ! $ INQUIRE USERNAME "Username" $ INQUIRE FULLNAME "Full name" $ SET TERMINAL/NOECHO $ INQUIRE PASSWORD "Password [''Username']" $ SET TERMINAL/ECHO $ IF PASSWORD .EQS. "" THEN PASSWORD = USERNAME $GET_GRP: $ INQUIRE GRP "UIC Group Number" $ IF GRP .EQS. "" THEN GRP = "*" $ WRITE SYS$OUTPUT "" $ WRITE SYS$OUTPUT "Determine the UIC from the following listing:" $ WRITE SYS$OUTPUT "" $ UAF SHOW ['GRP',*]/BRIEF $ INQUIRE UIC $ IF UIC .EQS. "" THEN GOTO GET_GRP $ IF F$LOCATE("[",UIC) .EQ. F$LENGTH(UIC) .AND. - F$LOCATE("<",UIC) .EQ. F$LENGTH(UIC) THEN UIC = "[" + UIC + "]" $ INQUIRE ACCOUNT "Account Name [VMS]" $ IF ACCOUNT .EQS. "" THEN ACCOUNT = "VMS" $ INQUIRE PRIVS "Privileges [NONE]" $ IF PRIVS .NES. "" THEN PRIVS = "/PRIV=(" + PRIVS + ")" $ USERDIR = F$EXTRACT(0,9,USERNAME) $ INQUIRE TMP "Login Directory [''USERDIR']" $ IF TMP .NES. "" THEN USERDIR = TMP $ INQUIRE TMP "Login Device [''USERDISK']" $ IF TMP .NES. "" THEN USERDISK = TMP $ DQUOTA = 0 $ IF F$SEARCH("''USERDISK'[0,0]QUOTA.SYS") .EQS. "" THEN GOTO NQ0 $ DQUOTA = 1 $ ! $ ! Restore prior working environment $ ! $CLEANUP: $ SET TERMINAL/ECHO $ PREVPRIV = F$SETPRV(PREVPRIV) $ SET DEFAULT 'OLDDIR' $ EXIT $ ! $ ! In case proper privileges are not set $ ! $NOPRIV: $ WRITE SYS$OUTPUT "You need SETPRV or SYSPRV privilege to run this procedure" $ GOTO CLEANUP ___________________________________________________________________________________________________________

<EXAMPLE_FILE>

Causes a separate file containing an example to be included in the source file.

SYNTAX

<EXAMPLE_FILE> (file spec)

ARGUMENTS

file spec
Specifies the file containing the example. The file can be a logical name. See the <INCLUDES_FILE> tag description for information on how to define a logical name.

related tags

<EXAMPLE>
<EXAMPLE_ATTRIBUTES>
<EXAMPLE_SPACE>
<REFERENCE>

restrictions

Valid only in the context of an <EXAMPLE> tag.

DESCRIPTION

The <EXAMPLE_FILE> tag causes a separate file containing an example to be included in the source file.
The included file should be an SDML file containing a complete coded example, perhaps using <CODE_EXAMPLE> or <INTERACTIVE> tags. If the <EXAMPLE> tag specifies the WIDE argument, the included file must specify the WIDE argument in the appropriate tags. For more information on correctly coding examples and example files, see Producing Online and Printed Documentation.
You can give the <EXAMPLE_FILE> tag a logical name for an argument. Define the logical name by first entering an <INCLUDES_FILE> tag in the profile. The information in that tag is used to make the proper logical name assignment during processing.

Example

See the example in the discussion of the <EXAMPLE> tag.

<EXAMPLE_SPACE>

Leaves space for an example to be pasted in during final production.

SYNTAX

<EXAMPLE_SPACE> (

value
FULL_PAGE
[\text])

ARGUMENTS

value
Specifies the size of the space in picas, a scale used by typesetters. There are approximately 6 picas in an inch (and 12 points in a pica). Thus, if the example is 4 inches high, you should specify 24 picas. The value must not exceed page length limitations for the current doctype. If you omit the value, a default value of 2 picas is used.
FULL_PAGE
This keyword specifies that a full blank page be reserved for the example. For Bookreader output, a small amount (smaller than a printed page or a Bookreader page) of blank space is left.
text
This is an optional argument. It specifies the text to be printed in the center of the space. (For example, an art file number, a file name that contains the example, or some other note.)

related tags

<EXAMPLE>
<EXAMPLE_ATTRIBUTES>
<EXAMPLE_FILE>
<REFERENCE>

restrictions

Valid only in the context of an <EXAMPLE> tag.
The value argument must not exceed page length limitations.

DESCRIPTION

The <EXAMPLE_SPACE> tag, leaves space for an example to be pasted in during final production. Any text you supply as the second argument is printed in the center of the space.

Example

This example shows how to use the <EXAMPLE_SPACE> tag.

<EXAMPLE>(Completing Form DD-214\annotated_dd214_exam) 
<EXAMPLE_ATTRIBUTES>(wide) 
<EXAMPLE_SPACE>(12\Photo-reduced copy of the end of DD-214 here.) 
<ENDEXAMPLE>

This example produces the following output:
Example n--n: Completing Form DD-214
_______________________________________________________________ _______________________________________________________________

<FCMD>

Specifies the keyword portion of a command/parameter pair in a format section.

SYNTAX

<FCMD> (keyword [\parameters])

ARGUMENTS

keyword
Specifies the keyword portion of the command/parameter pair.
parameters
This is an optional argument. It specifies the command parameters, if any.
Parameters specified in this argument differ in your output from arguments specified using the <FPARMS> tag. If you do specify the <FCMD> tag with a null second argument, it is recommended that you explicitly declare the absence of parameters using the <FPARMS> tag, as follows:
<FCMD>(KEYWORD) <FPARMS>()
If you do not specify a second argument, and if the <FPARMS> tag is not specified, the tag translator issues a warning message that it has no explicit declaration of parameters.

related tags

<FORMAT>
<FPARM>
<FPARMS>

restrictions

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

DESCRIPTION

The <FCMD>tag specifies the keyword portion of a command/parameter pair in a format section. You can specify the keyword's argument list as the second argument to this tag. The <FCMD>tag should be used only in the context of a format section. A format section is established by <FORMAT> and <ENDFORMAT> tags.
If the text of the parameters argument does not fit on one line, the text formatter chooses suitable line breaks based on the presence of spaces.

Examples

The following example specifies a single command keyword. The <FPARMS> tag is explicitly specified as null. The output that this example produces is shown in Output Sample 1.

#1

<FORMAT> 
<FCMD>(exit) <FPARMS>() 
<ENDFORMAT>

The following example specifies the command keyword and its parameters using both the <FCMD> and <FPARMS> tags. The output that this example produces is shown in Output Sample 2.

#2

<FORMAT> 
<FCMD>(append) <FPARMS>(input-file-spec output-file-spec) 
<ENDFORMAT

The following example specifies both the keyword and the parameters arguments to the <FCMD> tag. The output that this example produces is shown in Output Sample 3.
Notice the difference between Output Sample 2 and 3. In Sample 2, space is left between the keyword and the parameters. In Sample 3, no space is left. The formatting is produced by the syntax used in the <FCMD> tag.

#3

<FORMAT> 
<FCMD>(f$element\(element-number,delimiter,string)) 
<ENDFORMAT

The following example shows how to control the interpretation of keywords tagged with the <KEYWORD> tag when they are mixed in with the parameters of a format specification. The output that this example produces is shown in Output Sample 4.

#4

<FORMAT> 
<FCMD>(set protection\[=code]<keyword>(/DEFAULT)) 
<ENDFORMAT

The following example specifies the command keyword and its parameters using the <FCMD>, <FPARMS>, and <FPARM> tags. The output that this example produces is shown in Output Sample 5.

#5

<FORMAT> 
<FCMD>(append) <FPARMS>(one parameter) <FPARM>(two parameters) 
<FPARM>(three parameters) 
<ENDFORMAT

Output Sample 1

exit

Output Sample 2

append input-file-spec output-file-spec

Output Sample 3

f$element (element-number,delimiter,string)

Output Sample 4

set protection [=code]/DEFAULT

Output Sample 5

append one parameter

two parameters
three parameters

<FIGURE>

Labels the beginning of a figure.

Format

<FIGURE> [(figure caption[\symbol name])]

ARGUMENTS

figure caption
This is an optional argument. It specifies the text of the caption to be associated with the figure. The figure caption and the associated figure number will be included in the table of contents for the document. If the body of the figure spans more than a single page of text, the figure caption is repeated on each page on which the figure continues.
symbol name
This is an optional argument. It specifies the symbolic identifier to be associated with the example. The symbol name is assigned a numeric value, which becomes the current figure number. The symbol name and its value are placed in the symbol table.
Symbol names must not exceed 31 characters and must only contain alphabetic letters, numbers, or underscores in them. Do not begin a symbol name with an underscore.

related tags

<FIGURE_ATTRIBUTES>
<FIGURE_FILE>
<FIGURE_SPACE>
<ICON>
<ICON_FILE>
<LINE_ART>
<REFERENCE>

restrictions

Invalid in the context of a <FOOTNOTE> tag.

required terminator

<ENDFIGURE>

DESCRIPTION

The <FIGURE> tag labels the beginning of a figure. A formal figure has a number and a caption, can be cross-referenced, and is listed in the table of contents. An informal figure does not have a number or a caption, cannot be cross-referenced, and is not listed in the table of contents.
A formal figure is sometimes long. If you think one of your figures will be longer than a page, label it as a multipage figure in the <FIGURE_ATTRIBUTES> tag. See the <FIGURE_ATTRIBUTES> tag description for more information.
Note the following when processing a book for Bookreader display:

You must use the symbol name argument to process a formal figure for Bookreader display.
DOCUMENT automatically creates pop-up windows for all formal figures.
When introducing and cross-referencing a formal figure, you must use the <REFERENCE> tag to create a hotspot. Hotspots are regions in the windows you click on with your mouse to access cross-referenced topics.
You can use the <ONLINE_POPUP> tag if you want to make informal figures pop up.

When you print an informal or formal figure, or process an informal figure for Bookreader display, the figure is indented in the same way the regular text is for the particular doctype you are using.

Examples

In the following example, the <FIGURE_ATTRIBUTES> tag contains a KEEP argument, to specify that the figure should be kept with the immediately preceding text. The <LINE_ART> tag also has a KEEP argument, to specify that the figure should not break across pages.
The figures you are able to create using your terminal keyboard may be adequate for draft purposes, but may not be acceptable in the context of typeset output.

#1

<FIGURE>(Example of Terminal-Created Art\transfer_vector_exam) 
<FIGURE_ATTRIBUTES>(KEEP) 
<LINE_ART>(KEEP) 
 
               Shareable Image           Executable Image 
                +-----------+             +------------+ 
       +----| Vector A  |<-------+    |      .     | 
           |    +-----------+        |    |      .     | 
           | +--| Vector B  |<---+   +----- Invoke A   | 
           | |  +-----------+    |        |      .     | 
           +--->|           |    |        |      .     | 
             |  | Routine A |    +--------- Invoke B   | 
             |  |           |             |      .     | 
             |  +-----------+             |      .     | 
             +->|           |             +------------+ 
                | Routine B | 
                |           | 
                +-----------+ 
 
<ENDLINE_ART>
<ENDFIGURE>

This example produces the following output:

Figure n--n: Example of Terminal-Created Art

_________________________________________________________________ Shareable Image Executable Image +-----------+ +------------+ +----| Vector A |<-------+ | . | | +-----------+ | | . | | +--| Vector B |<---+ +----- Invoke A | | | +-----------+ | | . | +--->| | | | . | | | Routine A | +--------- Invoke B | | | | | . | | +-----------+ | . | +->| | +------------+ | Routine B | | | +-----------+ _________________________________________________________________

Contents

Index

DECdocumentUsing Global Tags

<EXAMPLE_ATTRIBUTES>

SYNTAX

<EXAMPLE_ATTRIBUTES> ( FLOAT KEEP MULTIPAGE [\WIDE])

ARGUMENTS

FLOAT

KEEP

MULTIPAGE

WIDE

related tags

restrictions

DESCRIPTION

Example

<EXAMPLE_FILE>

SYNTAX

<EXAMPLE_FILE> (file spec)

ARGUMENTS

file spec

related tags

restrictions

DESCRIPTION

Example

<EXAMPLE_SPACE>

SYNTAX

<EXAMPLE_SPACE> ( value FULL_PAGE [\text])

ARGUMENTS

value

FULL_PAGE

text

related tags

restrictions

DESCRIPTION

Example

<FCMD>

SYNTAX

<FCMD> (keyword [\parameters])

ARGUMENTS

keyword

parameters

related tags

restrictions

DESCRIPTION

Examples

Output Sample 1

exit

Output Sample 2

append input-file-spec output-file-spec

Output Sample 3

f$element (element-number,delimiter,string)

Output Sample 4

set protection [=code]/DEFAULT

Output Sample 5

append one parameter

<FIGURE>

Format

<FIGURE> [(figure caption[\symbol name])]

ARGUMENTS

figure caption

symbol name

related tags

restrictions

required terminator

DESCRIPTION

Examples

DECdocument
Using Global Tags

<EXAMPLE_ATTRIBUTES> (

FLOAT
KEEP
MULTIPAGE
[\WIDE])

<EXAMPLE_SPACE> (

value
FULL_PAGE
[\text])