| Previous | Contents | Index |
DECdocument provides the following tags for the creation of specialized reference template tags:
Each of these tags defines a template tag and its terminator for use in a template section. You can specify the following arguments to these tags:
Each of the tags defined using these tags accepts an alternate heading
argument and the NONE keyword argument. Note that these user-defined
template tags have the same behavior as standard template tags. If the
NONE keyword argument is specified, the terminating tag must not be
used.
2.10 Creating Your Own Template Tables
The <SET_TEMPLATE_TABLE> tag lets you create your own set of tags
for making a table with optional headings in a template. Tables created
using this tag can have either two or three columns. This tag requires
five arguments and accepts the optional table column headings
argument. This tag has the following syntax:
<SET_TEMPLATE_TABLE>( table tag name
\default table heading
\table row tag name
\column count
\column widths
[\table column headings]) The following list
summarizes the arguments allowed by this tag in the order in which you
must specify them:
table tag name
Specifies the user-defined name of the tag that begins the user-defined table.default table heading
Specifies the default text heading to be output over the entire user-defined table. You override this heading by an alternate heading specified as an argument to the table tag name tag.table row tag name
Specifies the name of the tag to be used to indicate individual table rows in the table being defined. For example, if the table row tag name argument is specified as SAMP_ROW, the individual table row tag will be <SAMP_ROW>.The tag you create by this argument is similar to the global <TABLE_ROW> tag.
column count
Specifies the number of columns in the user-defined table. The accepted arguments are:
- 2 --- Specifies that the table is to have two columns.
- 3 --- Specifies that the table is to have three columns.
table column widths
Specifies the approximate widths of the table columns. The width of the last table column is determined by DECdocument. So, if you specify a 2-column list, you must specify only one column-width argument, as shown in the following code example.
<SET_TEMPLATE_TABLE>(KEYVALS\Keyword Values\KEYVAL\2\10\Keyword\Value)If you specify a 3-column list, you must specify two column-width arguments, as shown in the following code example.
<SET_TEMPLATE_TABLE>(KEYVAL_LIST\Keyword Ranges\KEYVAL\3\10\10 \Keyword\High\Lower)table column headings
Specifies optional default headings for each column in the user-defined table. If you specified a 2-column list, you may specify up to two heading arguments. If you specified a 3-column list, you may specify up to three heading arguments.
The following examples show a definition of the user-defined <RECORDTABLE> table tags. In this example, the <RECORDTABLE> tag is defined as a 2-column list with column headings, and with a default table heading of Best Songs.
The first use of these table tags in the following example sets the text supplied to the two <45RPM> tags in the table, and then terminates the table. The second use shows how the NONE keyword argument can be used.
<SET_TEMPLATE_TABLE>(RECORDTABLE\Best Songs\45RPM\2\12 \Performer\Song Title) <RECORDTABLE> <45RPM>(Sinatra\Strangers in the Night) <45RPM>(Moody Blues\Nights in White Satin) <ENDRECORDTABLE> <RECORDTABLE>(NONE) |
This example produces the following output:
| Performer||Song Title | Sinatra |
|---|---|
| Strangers in the Night | Moody Blues |
| Nights in White Satin |
In most cases, you will not find it necessary to modify the reference templates. However, if you do want to modify these formats, you can do so by using one of the following tags:
The modifications made by these tags only affect those tags that follow
the modifying tag in the SDML file in the current reference template.
2.12 Modifying Default Headings in a Template
Each reference template enables several tags that place default headings on the output page. In most cases you will not want to change these default headings, because of the possibility of introducing typographical errors into the text of the heading. Changing the default headings can also cause your new headings to be incompatible with other headings in the current template or with headings in other reference sections.
However, if you do want to modify these headings, you can do so by
using the <SET_TEMPLATE_HEADING> tag, which lets you specify a
new default heading for a template tag in one of the reference
templates. This tag has the following syntax:
<SET_TEMPLATE_HEADING> (element keyword\default
heading)
The <SET_TEMPLATE_HEADING> tag accepts two arguments: the name of
the template tag to receive the new default heading, and the text of
the new default heading. The new default heading will then be used by
all subsequent uses of the template tag named as an argument to the
<SET_TEMPLATE_HEADING> tag in the current template. This heading
overrides any previously defined default heading for that template tag
in the current template.
A default heading created using the <SET_TEMPLATE_HEADING> tag will be in effect until that heading is reset in the current template by another <SET_TEMPLATE_HEADING> tag. Note also that the <SET_TEMPLATE_HEADING> tag has no effect on templates other than the one in which it is used.
The following example shows how you would create a new default heading. In this example, the default heading for the <RSDEFLIST> tag is set to be Conditions Signalled.
<ROUTINE_SECTION> <SET_TEMPLATE_HEADING>(RSDEFLIST\Conditions Signalled) <RSDEFLIST> <RSITEM>(SS$_NORMAL\Service successfully completed.) <RSITEM>(SS$_ACCVIO\Access violation.) <ENDRSDEFLIST> |
This example produces the following output:
SS$_NORMAL Service successfully completed. SS$_ACCVIO Access violation.
Table 2-7 summarizes the default headings assigned to the standard template tags.
| Template Tag | Default Heading |
|---|---|
| Command Template Tags | |
| <FORMAT> | Format |
| <PARAMDEFLIST> | Parameters |
| <QUALDEFLIST> | Qualifiers |
| <DESCRIPTION> | Description |
| <RESTRICTIONS> | Restrictions |
| <PROMPTS> | Prompts |
| Routine Template Tags | |
| <FORMAT> | Format |
| <ARGDEFLIST> | Arguments |
| <DESCRIPTION> | Description |
| <RSDEFLIST> | Return Values |
| Tag Template | |
| <FORMAT> | Format |
| <PARAMDEFLIST> | Arguments |
| <RELATED_TAGS> | Related Tags |
| <TERMINATING_TAG> | Required Terminator |
| <DESCRIPTION> | Description |
| Statement Template | |
| <STATEMENT_FORMAT> | Format |
| <DESCRIPTION> | Description |
| <FORMAT> | Format |
You use template-enabling tags to begin a reference template, and may optionally use them to alter the default format of that template. The following table lists the template-enabling tags for each template.
| Template Name | Template-enabling Tag |
|---|---|
| Command Template | <COMMAND_SECTION> |
| Routine Template | <ROUTINE_SECTION> |
| Statement Template | <STATEMENT_SECTION> |
| Tag Template | <TAG_SECTION> |
All the template-enabling tags have the same syntax and perform the same functions. The syntax for the Command template form of the template-enabling tags is as follows:
<COMMAND_SECTION>[([running title][\number prefix][\NEWPAGE])] . . . <ENDCOMMAND_SECTION> |
If you decide to modify a template using the template-enabling tag, these modifications will be in effect only in that particular template. The three arguments accepted by the template-enabling tags are given in the following list.
running title
Sets the second running heading for the page to be the text specified as the running title argument. This argument is valid only when double running heads are being used in the template.number prefix
Sets the numbering prefix to be used to construct page numbers and formal figure, table, and example numbers. Such numbers might be DCL-12, STAT-5, or Table STAT-3.NEWPAGE
Causes the initial text for the reference section to start on a new page. This argument also causes any template reference element (such as the <COMMAND> tag) to begin on a new page.
When you use the SOFTWARE.SPECIFICATION doctype, an SDML file that contains both reference templates and chapters has the following output format:
When you use the SOFTWARE.SPECIFICATION doctype, an SDML file that contains reference templates but no chapters has the following output format:
When you use a reference template, you typically use it in one of the following contexts:
DECdocument does not allow you to nest reference templates inside one another and will signal an error if this occurs. |
Using Reference Templates in Chapters
When a set of command or routine sections occur in a chapter, page and formal element numbering remain the same. That is, if the current chapter is 2, page numbering will continue to be 2--n.
You can let the chapter-heading text be carried at the top of each page (if that is the current doctype style), with the command name as the second-level heading. In a doctype in which the chapter heading text is carried at the bottom of the page, the running feet will remain unchanged.
By specifying the following tags and arguments:
<CHAPTER>(debug_chap) . . . <COMMAND_SECTION>(Debugger Commands) <SET_TEMPLATE_COMMAND>(DBG_COMMAND\DOUBLERUNNINGHEADS) <DBG_COMMAND>(ALLOCATE) |
the page numbering will use the current number as the page number prefix, for example 3--n, with formal elements being numbered in the same way. In the command reference descriptions, the top-level title Debugger Commands will appear at the top of each page. The name of the current command will appear just below this heading.
When a document consists of chapters, each of which contains related reference elements, the chapter's running title will almost always be used as the running title. However, you can override this heading with the reference section enabling tags:
<CHAPTER>(aci_routines_chap) <ROUTINE_SECTION>(ACI Routines) |
When you specify a character-string prefix following a <CHAPTER> tag, the prefix will be used for:
For example:
<CHAPTER>(FDL_routines_chap) <COMMAND_SECTION>(\FDL) |
In this example, the <COMMAND_SECTION> tag sets the folio using the string FDL. The header levels in this chapter will continue to be numbered using the chapter number (that is, 2.1, 2.1.1, and so on) but the pages and formal figures, tables, and examples will be numbered FDL--1, FDL--2, and so on.
Using Reference Templates in the Appendix Document Zone
If you want to document routines or commands or other reference
elements in pull-out sections suitable for placing in a binder with
other system commands or routines, and want these sections to be
distinctly labeled, you can specify a character-string prefix to be
used throughout your pullout reference section.
2.14 Using the <SET_TEMPLATE_TEMPLATENAME> Tags
The <SET_TEMPLATE_TEMPLATENAME> tag is not a DECdocument tag. It is a generic name given to a set of four tags that have the same syntax, and that perform the same functions. These tags differ only in their names and in the templates in which they are available:
| Command Template | <SET_TEMPLATE_COMMAND> |
| Routine Template | <SET_TEMPLATE_ROUTINE> |
| Statement Template | <SET_TEMPLATE_STATEMENT> |
| Tag Template | <SET_TEMPLATE_TAG> |
These tags have the following syntax (illustrated by the
<SET_TEMPLATE_COMMAND> tag in this case):
<SET_TEMPLATE_COMMAND> (tag name[\attribute]
[\attribute][\attribute])
These tags let you override the default formatting attributes for
reference elements used in each of the reference templates. These tags
require a first argument that is the name of the reference element tag
in the template. You can specify the name of the default reference
element tag (such as the <ROUTINE> tag in the Routine template),
or you can specify a new tag name (such as <MY_ROUTINE>).
If you specify a new reference element tag name, you may not use the old tag name. It is no longer valid. The new tag name replaces the previous reference element tag. All subsequent uses of a reference element tag should use the last established tag name.
You can then specify one or more of the following keywords that are accepted by these tags (note that these keyword arguments must be separated by backslashes):
NONEWPAGE
Specifies that reference descriptions are not to start on new pages. By default, the tag defined by the first argument of the <SET_TEMPLATE_TEMPLATENAME> tag begins a command description on a new page.DOUBLERUNNINGHEADS
Specifies that the command descriptions have two running titles at the top of every page. You set the top running title by the <COMMAND_SECTION> tag or by the heading of the most recent <CHAPTER> tag. By default, if a doctype design option does not call for running top titles, only the current command name is placed at the top of each page.STACK
Specifies that when there are multiple arguments for the tag defined by the first argument to the <SET_TEMPLATE_TEMPLATENAME> 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 output on the same line as the command name.
The following code example shows a sample use of the <SET_TEMPLATE_COMMAND> tag. In this example, the tag <XYZ_COMMAND> is defined and used. The keyword argument NONEWPAGE is specified to the <COMMAND_SECTION> tag so that the first description will not start on a new page. The keyword argument STACK is specified so that the two arguments FIND_FIRST and FF are stacked with the first argument on top.
<COMMAND_SECTION>(XYZ Commands\\NEWPAGE) <SET_TEMPLATE_COMMAND>(XYZ_COMMAND\NONEWPAGE\STACK) <XYZ_COMMAND>(FIND_FIRST\FF) |
This example produces the following output:
| Previous | Next | Contents | Index |