| Previous | Contents | Index |
Provides a text description of a tag or set of tags that may be related to the tag being described.
<RELATED_ITEM>
None.
- <RELATED_TAG>
- <RELATED_TAGS>
Valid only in the context of a <RELATED_TAGS> tag section in the Tag template.
The <RELATED_ITEM> tag provides a text description of a tag or set of tags that may be related to the tag being described. This text begins right after the <RELATED_ITEM> tag and is terminated by the next related tag section tag.
The following example shows how to enter text describing information related to the use of a tag.
<RELATED_TAGS> <RELATED_ITEM> Use the <TAG>(INTRO) and <TAG>(ENDINTRO) tags to label introductory material in your book. <ENDRELATED_TAGS> |
This example produces the following output:
- Use the <INTRO> and <ENDINTRO> tags to label introductory material in your book.
<RELATED_TAG>
Specifies a single tag that is related to the current tag.
Syntax
<RELATED_TAG> (tag name)
ARGUMENTS
tag name
Specifies the name of a DECdocument tag. Do not place angle brackets around the tag name; the <RELATED_TAG> tag supplies them by default.
- <RELATED_ITEM>
- <RELATED_TAGS>
Valid only in the context of the <RELATED_TAGS> tag in the Tag template.
The <RELATED_TAG> tag specifies a single tag that is related to the current tag. The <RELATED_TAG> tag automatically places angle brackets around the tag name argument, so angle brackets should not be specified.Use the <RELATED_ITEM> tag to list related tag information in another format.
The following example specifies the names of two related tags in the context of the <RELATED_TAGS> tag. Note how the names of the related tags are specified without the angle brackets.
<RELATED_TAGS> <RELATED_TAG>(SET_TEMPLATE_TAG) <RELATED_TAG>(TAG_SECTION) <ENDRELATED_TAGS> |
This example produces the following output:
- <SET_TEMPLATE_TAG>
- <TAG_SECTION>
<RELATED_TAGS>
Provides a summary of tags whose use is related to the tag being described.
Syntax
<RELATED_TAGS> [(NONE)]
ARGUMENTS
NONE
This is an optional keyword argument. It indicates that there are no tags whose use is related to the tag being described.
- <RELATED_ITEM>
- <RELATED_TAG>
Valid only in the context of the Tag template. If you specify NONE, do not specify the <ENDRELATED_TAGS> tag.
<ENDRELATED_TAGS>
The <RELATED_TAGS> tag provides a summary of tags whose use is related to the tag being described.
The following example shows how to specify two related tags in a <RELATED_TAGS> tag section.
| #1 |
|---|
<RELATED_TAGS> <RELATED_TAG>(SET_TEMPLATE_TAG) <RELATED_TAG>(TAG_SECTION) <ENDRELATED_TAGS> |
This example produces the following output:
related tags
- <SET_TEMPLATE_TAG>
- <TAG_SECTION>
The following example shows how to use the NONE keyword to show that there are no related tags. Note that, in this case, the <ENDRELATED_TAGS> tag is omitted.
#2
<RELATED_TAGS>(NONE)This example produces the following output:
related tags
None.
Provides the restrictions on the use of a tag.
<RESTRICTIONS> [(
)]
- alternate heading[\LIST]
- NONE
- LIST
alternate heading
This is an optional argument. It specifies a heading to override the current default text heading for this use of the <RESTRICTIONS> tag. The default heading provided by DECdocument is Restrictions. See the reference description of the <SET_TEMPLATE_HEADING> tag for information on how to modify the default headings for the <RESTRICTIONS> tag.NONE
This is an optional keyword argument. It indicates that there are no restrictions on the use of the tag. If you specify the NONE keyword, do not use the <ENDRESTRICTIONS> tag to end the <RESTRICTIONS> tag section.LIST
This is an optional keyword argument. It indicates that a number of restrictions are to be listed. To list the restrictions, use the <RITEM> for each of the individual restriction items in the list.
- <RITEM>
- <TAG_SECTION>
Valid only in the context of the Tag template. If you specify NONE, do not specify the <ENDRESTRICTIONS> tag.
<ENDRESTRICTIONS>
The <RESTRICTIONS> tag provides the restrictions on the use of a tag.
The following example shows how to set a simple paragraph of text for the restrictions section using the <RESTRICTIONS> tag.
| #1 |
|---|
<RESTRICTIONS> Valid only in the context of the <tag>(COMMAND_SECTION) tag. <ENDRESTRICTIONS> |
This example produces the following output:
restrictions
Valid only in the context of the <COMMAND_SECTION> tag.The following example shows how to use the NONE keyword to indicate that there are no restrictions on the use of a tag.
| #2 |
|---|
<RESTRICTIONS>(NONE) |
This example produces the following output:
restrictions
None.The following example shows how to create a set of restrictions in a list.
| #3 |
|---|
<RESTRICTIONS>(LIST) <RITEM>If you specify NONE, you must not specify <tag>(ENDPARAMDEFLIST). <RITEM>Use of a default heading is restricted to the reference templates. <ENDRESTRICTIONS> |
This example produces the following output:
- If you specify NONE, you must not specify <ENDPARAMDEFLIST>.
- Use of a default heading is restricted to the reference templates.
Provides general information about the attributes of the value returned by the routine.
<RETTEXT>
- <RETURNS>
<ENDRETTEXT>
Valid only following the <RETURNS> tag in the Routine template.
The <RETTEXT> tag provides general information about the attributes of the value returned by the routine. It places one or more paragraphs of information after some usage of the <RETURNS> tag. This information begins immediately after the <RETTEXT> tag and continues until the <ENDRETTEXT> tag is encountered.You typically use this tag when the arguments given to the <RETURNS> tag are not sufficiently descriptive.
See the example in the <RETURNS> tag description.
Provides information about the value returned by a routine.
<RETURNS> (usage information
\data type \access \mechanism[\optional info])<RETURNS> (HEADONLY)
usage information
Specifies a keyword indicating the category of data to which the return value belongs. These keywords are system dependent, and are specified by agreed-upon conventions.data type
Indicates the data type of the return value, for example, longword, byte, G_floating, and so on.access
Indicates the access applied to the return value, for example, read-only, write-only, and so on.mechanism
Specifies the mechanism by which the return value is passed; for example, by descriptor, by reference, or by value.optional info
This is an optional argument. It specifies additional information which may be appended to the mechanism argument output.HEADONLY
This alternative keyword argument indicates that specific usage information is not relevant, and that text will be provided to describe the return attributes of the routine.
- <RETTEXT>
Valid only in the context of the Routine template.
The <RETURNS> tag provides information about the value returned by a routine. The returns section of the Routine reference template and its specialized argument list are used only by convention for those documenting callable routines.
The following two input examples show various uses of the <RETURNS> tag. Outputs from these coding examples appear after the last input example.The following input example shows how to specify multiple arguments to the <RETURNS> tag.
| #1 |
|---|
<RETURNS>(floating_point\ F_Floating, D_Floating, or G_Floating\write only\by value in R0) |
The following input example shows a use of the HEADONLY argument. The return value from a routine or set of related routines may be too complex to express using the conventional arguments.
| #2 |
|---|
<RETURNS>(headonly) <RETTEXT>The square roots of F_Floating, D_Floating, and G_Floating input parameters are returned by immediate value in R0 and R1. The square root of an H_Floating parameter is returned by reference in the output parameter <VARIABLE>(sqrt). <ENDRETTEXT> |
These input examples produce the following output:
VMS usage: floating_point type: F_Floating, D_Floating, or G_Floating access: write only mechanism: by value in R0
RETURNS
The square roots of F_Floating, D_Floating, and G_Floating input parameters are returned by immediate value in R0 and R1. The square root of an H_Floating parameter is returned by reference in the output parameter sqrt.
<RETURN_VALUE>
Labels a character string return value.
Syntax
<RETURN_VALUE> [(alternate heading)]
ARGUMENTS
alternate heading
This is an optional argument. It specifies a heading to override the current default text heading for this use of the <RETURN_VALUE> tag. The default heading provided by DECdocument is Return Value. See the reference description of the <SET_TEMPLATE_HEADING> tag for information on how to modify the default headings for all <RETURN_VALUE> tags.restrictions
Valid only in the context of the Command template.required terminator
<ENDRETURN_VALUE>
DESCRIPTION
The <RETURN_VALUE> tag labels a character string return value.
Example
The following example shows how to use the <RETURN_VALUE> tag.
<RETURN_VALUE> abc-def-ghi <ENDRETURN_VALUE>This example produces the following output:
Return Value
abc-def-ghi
<RITEM>
Labels an item in a list of restrictions.
ARGUMENTS
None.
Syntax
<RITEM>
related tags
- <RESTRICTIONS>
restrictions
Valid only in the context of the <RESTRICTIONS> tag.
DESCRIPTION
The <RITEM> tag labels an item in a list of restrictions.
Example
The following example shows how to create a list of restrictions. Note how you specify the <RESTRICTIONS> tag with the LIST keyword argument. Note how this enables the <RITEM> tag.
<RESTRICTIONS>(LIST) <RITEM>You must not unplug this appliance while it is operating. <RITEM>This appliance should not be immersed in water. <ENDRESTRICTIONS>This example produces the following output:
restrictions
- You must not unplug this appliance while it is operating.
- This appliance should not be immersed in water.
<ROUTINE>
Begins a new routine description.
Syntax
<ROUTINE> (routine name[\info1[\info2]]\symbol name)
ARGUMENTS
routine name
Specifies the name of the routine to be described.info1
info2
These are optional arguments. They specify an optional text description of the routine's function.symbol name
Specifies the name of the symbol used in all references to the routine.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
- <ROUTINE_SECTION>
- <SET_TEMPLATE_ROUTINE>
restrictions
Valid only in the context of the Routine template.
DESCRIPTION
The <ROUTINE> tag begins a new routine description. This description is for a single routine in the context of the <ROUTINE_SECTION> tag. This tag has the following default format:To replace the <ROUTINE> tag with a tag more specific to a certain task (for example, the <DCL_ROUTINE>) tag, or to change the default attributes of the <ROUTINE> tag, use the <SET_TEMPLATE_ROUTINE> tag. See the description of the <SET_TEMPLATE_ROUTINE> tag in this chapter for more information.
- Each <ROUTINE> tag begins a new page of output.
- Each output page carries a single running title, which is the current routine name.
- If you use the optional info arguments with the <ROUTINE> tag, these arguments output after the routine name argument and are separated from the routine name argument by an em dash (---).
Examples
In the following example, the <ROUTINE_SECTION> tag enables the tags for a routine description.
#1
<ROUTINE_SECTION> <ROUTINE>($OPEN) <OVERVIEW> . . .The description of the routine $OPEN has the following default attributes:
- The routine description starts a new page.
- If the routine carries for more than a page, the name $OPEN is carried as a running top title on each page.
#2
<ROUTINE>($CLOSE\Close a File)When two arguments are specified to the <ROUTINE> tag, the routine name, $CLOSE, appears at the beginning of the routine description. The text specified in the second argument, Close a File, follows the routine name at the top of the page, separated from the routine name by an em dash (---).
#3
<ROUTINE>(SMG$BEGIN_PASTEBOARD_UPDATE\\Begin Batching of Pasteboard Updates)This example illustrates special coding required when a routine's name is extremely long and may require special formatting. If the second argument is null, the third argument is stacked under the first argument. No em dash is output:
Use this form only if the output from the other formats appears wrong.
SMG$BEGIN_PASTEBOARD_UPDATE Begin Batching of Pasteboard Updates
#4
<ROUTINE>(OTS$SCOPY_R_DX\Copy a Source String \Passed by Reference to a Destination String)This example illustrates special coding required when a routine's name and descriptive name creates unreasonable output using the default formatting attributes. If you specify three arguments, the first and second arguments are output on the first line, separated by an em dash. The third argument is stacked under the first argument (instead of wrapping) following the em dash:
Use this form only if examination of your output indicates a formatting problem.
OTS$SCOPY_R_DX---Copy a Source String given by Reference to a Destination String
<ROUTINE_SECTION>
Begins a routine reference section, enables tags reserved for use in routine sections, and sets paging attributes.
Syntax
<ROUTINE_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 routine 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 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 indicates that the routine section begins on a new page. This argument is only meaningful in two cases:
- When you have previously entered the <SET_TEMPLATE_ROUTINE> tag with the NONEWPAGE keyword to specify that each new routine in this routine section should not begin on a new page
- When you want to place one or more pages of text between the end of a part page and the beginning of a routine section
related tags
- <ARGDEF>
- <ARGDEFLIST>
- <ARGITEM>
- <ARGTEXT>
- <DESCRIPTION>
- <EXAMPLE_SEQUENCE>
- <FARG>
- <FARGS>
- <FFUNC>
- <FORMAT>
- <FRTN>
- <OVERVIEW>
- <RETURNS>
- <RETTEXT>
- <ROUTINE>
- <RSDEFLIST>
- <RSITEM>
- <SET_TEMPLATE_HEADING>
- <SET_TEMPLATE_LIST>
- <SET_TEMPLATE_PARA>
- <SET_TEMPLATE_TABLE>
required terminator
<ENDROUTINE_SECTION>
DESCRIPTION
The <ROUTINE_SECTION> tag begins a routine reference section, enables tags reserved for use in routine sections, and sets paging attributes. You can place more than one routine section in a single document. However, you must end each previous routine section before you begin the next one.You can tailor the default format of the routine reference template to meet your own documentation requirements. Either you can alter the default attributes of the <ROUTINE_SECTION> tag by specifying one of the arguments to that tag, or you can use the <SET_TEMPLATE_ROUTINE> tag to alter the default attributes for the <ROUTINE> tag that begins each new routine description.
You can place a routine 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 routine section in a chapter or an appendix in the same manner; command sections in parts are handled differently.
If your routine section follows a part page, and you include text between the part page and the routine section, specify the NEWPAGE keyword as the third argument to the <ROUTINE_SECTION> tag. This causes the routine section to begin on a new page. The following code fragment shows a routine section that begins on a new page:
<ROUTINE_SECTION>(\AB\NEWPAGE) <HEAD1>(Routine Format\42_RoutineFormat)When you use the <ROUTINE_SECTION> tag in a chapter or an appendix, and you want to place text after the routine section in that chapter or appendix, you must end the routine section with the <ENDROUTINE_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 <ENDROUTINE_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 routine section that specifies that the subsequent text not be placed on a new page:
<ENDROUTINE_SECTION>(NONEWPAGE)When the <ENDROUTINE_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 routine description in the routine section may not carry the last routine's name as the running heading. Instead it may carry the running title used by the chapter or appendix.
Examples
The following example shows how to begin a routine section in a document part.
#1
<PART> <PART_PAGE> <TITLE>(PART II\AAA Routine Descriptions) <ABSTRACT>This Part contains complete reference descriptions of the AAA routines. <ENDABSTRACT> <ENDPART_PAGE>(RENUMBER) <endtag_section> <ROUTINE_SECTION>(AAA Routines\AAA) <SET_TEMPLATE_ROUTINE>(AAA_ROUTINE\DOUBLERUNNINGHEADS) <AAA_ROUTINE>(AAA$CLOSE) <OVERVIEW> Closes the specified file. <ENDOVERVIEW . . . <ENDROUTINE_SECTION>The tags in the previous example perform the following functions:
- The global <PART> tag begins the part.
- The global <PART_PAGE> tag creates a part page.
- The global <TITLE> tag is used in the context of the <PART_PAGE> tag to create a title on the part page.
- The RENUMBER argument to the global <ENDPART_PAGE> tag specifies that the pages are renumbered beginning with the part page. This causes the first page of text following the part page to be numbered page 3 (page 1 is the unnumbered page the part page title is placed on, page 2 is the back of page 1, and page 3 is the first numbered page after the part page).
- The <ROUTINE_SECTION> tag begins the routine section and specifies the running title AAA Routines as the running title for the routine section.
The <ROUTINE_SECTION> tag also specifies that the prefix AAA should be used to construct numbers for pages and for formal figures, tables, and examples in the routine section (for example, AAA--11, AAA--32, Table AAA--1, Example AAA--2, and so on).- The <SET_TEMPLATE_ROUTINE> tag specifies that all routine descriptions in this routine section are identified using the tag <AAA_ROUTINE> rather than the default <ROUTINE> tag. The <AAA_ROUTINE> tag has the default attributes of the <ROUTINE> tag.
The DOUBLERUNNINGHEADS argument to the <SET_TEMPLATE_ROUTINE> tag specifies that the routine section has a double running heading at the top of the page. The top heading is the running title specified as an argument to the <ROUTINE_SECTION> tag, and the lower heading is the name of the current routine.
Previous Next Contents Index