The following example shows how to use the tags enabled by the <MESSAGE_SECTION> tag to create a message description section. Note how using the <MESSAGE_TYPE> tag with the TEXTIDENT keyword results in a comma (,) being placed after each message identification string.

<MESSAGE_SECTION> <MESSAGE_TYPE>(TEXTIDENT) <MSG>(BACKLINK\Incorrect directory back link) <MSG_TEXT>(Facility) VERIFY, Verify Utility <MSG_TEXT>(Severity) BACKLINK-F-BADLINK <MSG_TEXT> The Verify Utility could not process your command, please check the syntax of your statement. <MSGS>(UAF-E-NAOFIL\Unable to open file SYSUAF.DAT \-RMS-E-FNF\file not found) <MSG_TEXT>(User Action) Check the syntax and reenter the command. <MSG_TEXT> This is some explanatory text for the previous message. <ENDMESSAGE_SECTION>

This example produces the following output:

BACKLINK, Incorrect directory back link

UAF-E-NAOFIL, Unable to open file SYSUAF.DAT -RMS-E-FNF file not found

There are four sets of tags available in the SOFTWARE doctype for describing arguments, parameters, and qualifiers in a list.

<ARGDEFLIST>	Creates a definition list of arguments
<PARAMDEFLIST>	Creates a definition list of parameters
<QUALDEFLIST>	Creates a definition list of qualifiers
<QUAL_LIST>	Creates a summary list of qualifiers

The tags used to create these SOFTWARE doctype definition lists and the form of these lists are very similar to those used by the global <DEFINITION_LIST> tag. The qualifier summary list differs from the definition lists in that it is designed only as a summary list of qualifiers and contains no provision for definition text.

These SOFTWARE doctype-specific tags are used to label lists of arguments, parameters, or qualifiers inside or outside the context of the reference templates.

Using the SOFTWARE Definition List Tags

The following list describes the software definition list tag sets. Note that tags that function in the same manner in each of the definition lists are described together.

SOFTWARE DEFINITION LIST TAGS

<ARGDEFLIST>

<PARAMDEFLIST>

<QUALDEFLIST>

Begins each type of list and enables the tags that follow. Each of these tags allows an optional heading to be specified as an argument. Use the NONE keyword argument if you want to indicate that the list contains no items.

If you use these tags inside a reference template, you may define default headings.

<ARGITEM>

<PARAMITEM>

<QUALITEM>

Labels the argument, parameter, or qualifier to be listed. Each of these tags requires one argument and accepts up to a total of seven arguments to list any related arguments, parameters, or qualifiers.

<ARGDEF>

<PARAMDEF>

<QUALDEF>

Labels the text string that describes the appropriate argument, parameter, or qualifier.

<ENDARGDEFLIST>

<ENDPARAMDEFLIST>

<ENDQUALDEFLIST>

Terminates each type of list and disables the contained tags.

The following examples show how to create a parameter definition list, an argument definition list, and a qualifier definition list.

The first example shows a parameter definition list in the Command template. This coding of the <PARAMDEFLIST> tag uses the NOHEAD keyword to suppress the output of a default heading (in this case, the heading parameters). If this definition list were coded outside the context of a reference template, no default heading would be defined and the NOHEAD argument would not be needed.

<P>The system maintains logical names and their associated equivalence strings in two types of tables: <PARAMDEFLIST>(NOHEAD) <PARAMITEM>(process-private) <PARAMDEF>These tables contain logical names that are available only to your process. <PARAMITEM>(shareable) <PARAMDEF>These tables contain logical names that are available to other processes on the system. <ENDPARAMDEFLIST>

This example produces the following output:

The system maintains logical names and their associated equivalence strings in two types of tables:

process-private

These tables contain logical names that are available only to your process.

shareable

These tables contain logical names that are available to other processes on the system.

The following example shows how to use the <ALIGN_AFTER> tag for additional formatting flexibility in an argument definition list outside a reference template.

<ARGDEFLIST> <ARGITEM>(STATUS:arg\ <ALIGN_AFTER>(STATUS:)COMMAND\ <ALIGN_AFTER>(STATUS:)TASK) <ARGDEF>Specifies whether exit status is to be returned from the RUN command. <ENDARGDEFLIST>

This example produces the following output:

STATUS:arg

COMMAND

TASK

Specifies whether exit status is to be returned from the RUN command.

The following example shows a qualifier definition list in the Command template. Note how the related qualifiers are stacked.

<COMMAND_SECTION> <QUALDEFLIST>(Qualifiers) <QUALITEM>(/HERE\/THERE) <QUALDEF> The /HERE qualifier specifies the location of your workplace; the /THERE qualifier specifies the location of your home; /THERE is the default. <QUALITEM>(/TIME\/NOTIME) <QUALDEF> Specifies the amount of free time you have available. If the /TIME qualifier is used, an amount must be given; /NOTIME is the default. <ENDQUALDEFLIST> <ENDCOMMAND_SECTION>

This example produces the following output:

QUALIFIERS

/HERE

/THERE

The /HERE qualifier specifies the location of your workplace; the /THERE qualifier specifies the location of your home; /THERE is the default.

/TIME

/NOTIME

Specifies the amount of free time you have available. If the /TIME qualifier is used, an amount must be given; /NOTIME is the default.

Using the Software Qualifier Summary List Tags

DECdocument provides several tags to create a summary list of command qualifiers. The list generated by these tags creates two default headings, and places one heading over each qualifier listed by the <QPAIR> tag. Although qualifier summary lists are most often used following the <FORMAT> tag in the Command template, they may be used either inside or outside the context of the reference templates.

Use the following tags to create a qualifier summary list:

• <QUAL_LIST>
  Begins the list and enables the <QUAL_LIST_HEADS>, <QUAL_LIST_DEFAULT_HEADS>, <QPAIR>, and <ENDQUAL_LIST> tags. This tag places two default headings on the page. The heading Command Qualifiers is placed over the first list column and the heading Defaults is placed over the second list column. You may override these headings by using the <QUAL_LIST_HEADS> or <QUAL_LIST_DEFAULT_HEADS> tags.
  Use the NONE keyword argument to indicate there are no qualifiers. If you use the NONE keyword, do not use the <ENDQUAL_LIST> tag. Otherwise, terminate this tag with the <ENDQUAL_LIST> tag.
• <QUAL_LIST_HEADS>
  Creates alternate headings for a single qualifier summary list. This tag requires two arguments that specify the alternate headings. If either argument is null, the associated heading is not output.
• <QUAL_LIST_DEFAULT_HEADS>
  Creates new default headings for all subsequent qualifier summary lists. This tag requires two arguments that specify the new default headings. If either argument is null, the associated heading is not output.
• <QPAIR>
  Specifies the pair of qualifiers to be listed. This tag requires two qualifier arguments; the first argument is listed under the default heading Command Qualifiers, and the second argument is listed under the default heading Defaults.

The following example shows a qualifier summary list. Note how no description text is used. Note also how each list has a default heading.

<QUAL_LIST> <QPAIR>(/HERE\/THERE) <QPAIR>(/TIME\/NOTIME) <ENDQUAL_LIST>

This example produces the following output:

Command Qualifiers	Defaults
/HERE	/THERE
/TIME	/NOTIME

2.7 Creating a Series of Interactive or Code Examples

Often, it is useful to explain concepts through the use of examples. You can create a series of numbered interactive and code examples by using the <EXAMPLE_SEQUENCE> tag.

Interactive and code examples in an example sequence have the same form and accept the same tags as examples created using the global <INTERACTIVE> and <CODE_EXAMPLE> tags.

You can use the following tags to construct a sequence of examples:

• <EXAMPLE_SEQUENCE> tag
  Begins a sequence of numbered, informal examples. This tag accepts two optional arguments, used to alter the heading and suppress the numbering of examples.
  The heading info argument alters the example sequence heading. This argument can be one of the following:
  • An alternate heading for the example sequence.
  • The NOHEAD keyword, which suppresses the output of a heading for the example sequence.
  • The EXAMPLE keyword, which suppresses numbering of the examples in the sequence and outputs the heading Example; this keyword should be used when you have a single informal example rather than a series of examples.
  
  The NONUMBER keyword argument suppresses the numbering of examples in an example sequence. When you use the keyword EXAMPLE as the heading info argument, the NONUMBER keyword argument is unnecessary.
  The <EXAMPLE_SEQUENCE> tag enables the <EXAMPLES_INTRO>, <EXC>, <EXI>, and <EXTEXT> tags. You terminate this tag by the <ENDEXAMPLE_SEQUENCE> tag.
• <EXAMPLES_INTRO>
  Specifies introductory text for the example sequence.
• <EXC>
  Specifies the beginning of a code example in an example sequence. You format this code example exactly the same as you would if using the global <CODE_EXAMPLE> tag. You terminate the code example by the <EXTEXT> tag.
• <EXI>
  Specifies the beginning of an interactive example in an example sequence. This tag uses the global <S> and <U> tags in the example in the same manner as the global <INTERACTIVE> tag. You terminate the interactive example by the <EXTEXT> tag.
• <EXTEXT>
  Specifies text that explains the previous example in the sequence. You must use this tag to terminate examples begun using the <EXC> and <EXI> tags.

The following example shows how to use the example sequence tags. Note the alternate heading specified as an argument to the <EXAMPLE_SEQUENCE> tag.

<EXAMPLE_SEQUENCE>(An Interactive Example and a Code Example) <EXAMPLES_INTRO> This is introductory text for the sample examples. <exi><S>($ )<U>(SET WORK/NOTIME) <EXTEXT> This command sets the /NOTIME qualifier to the SET WORK command. <EXC>This is a code example, ined, exactly as entered. note how f a o t r e matting is r <EXTEXT> This shows the flexibility available in a code example in an example sequence. <ENDEXAMPLE_SEQUENCE>

This example produces the following output:

An Interactive Example and a Code Example

This is introductory text for the sample examples.

$ SET WORK/NOTIME

This command sets the /NOTIME qualifier to the SET WORK command.

This is a code example,                         ined, exactly as entered. 
                       note how f             a 
                                o            t 
                                r           e 
                                matting is r 

This shows the flexibility available in a code example in an example sequence.

The SOFTWARE doctype contains four templates called reference templates that help you create software reference documentation. A reference template is a set of tags intended for some specialized documentation purpose, such as creating an outline, composing the front matter of a book, or documenting a set of software commands.

Every reference template has a beginning and an end. These template boundaries are set by a pair of tags:

• The template-enabling tag begins the template and sets up all the template-specific formats and tag definitions.
• The template-ending tag ends the template and disables the template-specific formats and tag definitions.

If template-specific tags are encountered outside the template in which they are defined, DECdocument treats these tags as undefined and issues a warning message.

There is one rule about using templates:

1. You must end one template before you begin another template; you may not nest one template inside another.

Reference templates are especially useful in creating and maintaining reference documentation. They make the coding of reference information easier in several ways:

• The structured nature of reference templates makes it easier to consistently code, format, and order reference information.
• Text coded into a reference template is more modular and structured than the text in a nontemplated SDML file, which makes it easier to modify and maintain reference information.
• Using a template for reference information allows the writer to fill in the blanks, and helps ensure that no essential information, such as restrictions or the lack of restrictions on a command, is omitted.
• Using a tag template for reference information lets you use default formats, headings, and tags. This helps guarantee that even when several writers work on different portions of the same book, all of these portions look alike.

Using the SOFTWARE Doctype Reference Templates

There are four reference templates available in the SOFTWARE doctype:

• Command template
  Describes commands and their various components. Examples of command descriptions are the descriptions of the DCL commands used in the VMS operating system.
• Routine template
  Describes software routines and their various components. Examples of routines descriptions are the descriptions of the VMS run-time library routines.
• Statement template
  Describes programming language constructs (such as statements and functions) and their various components. An example of a statement description is the CASE statement available in the VAX Pascal programming language.
• Tag template
  Describes DECdocument tags and their components. Examples of tag descriptions can be found in all chapters in this manual.

All reference templates are similar in design because all are intended to be used to create similarly formatted reference material. This similarity means that certain tags are common to all four templates. However, because each template is customized for the presentation of a particular kind of information, several tags are available only in specific templates. For example, all four templates have a description section that describes the current command, routine, statement, or tag. However, only the Routine template has a section for describing in detail the values returned by a routine.

Like all tag templates, the software reference templates are begun by a template-enabling tag (for example, the <COMMAND_SECTION> tag), and terminated by a similarly named template-ending tag (for example, the <ENDCOMMAND_SECTION> tag). However, because the reference templates are designed to create reference-oriented documentation, they also must contain one or more reference element tags.

A reference element is a single element in a reference section, such as the description of a single command in a command reference section, or the description of a single routine in a routine reference section. The collection of these single elements into a group creates a reference section.

The default reference element tag names match the templates they are used in. The <COMMAND> tag occurs in the Command template, the <ROUTINE> tag occurs in the Routine template, and so on. When these reference element tags occur in a reference template, they signal the beginning of a new reference element description.

By default, each new reference element description begins on a new output page, with the name of the current reference element output at the top of the page.

Reference element tags are not terminated by matching ending tags, as are most template tags. Instead, a reference element description is terminated either by the next reference element tag, by the end of the reference template, or by the end of the SDML file.

Note that of all the tags used in the various reference templates, only the template-enabling tags and the reference element tags are required; all other tags used in the templates are optional.

The following list shows the template-enabling tag and the reference element tag for each template.

Template Name	Template-Enabling Tag	Reference Element Tag
Command	<COMMAND_SECTION>	<COMMAND>
Routine	<ROUTINE_SECTION>	<ROUTINE>
Statement	<STATEMENT_SECTION>	<STATEMENT>¹ <FUNCTION>
Tag	<TAG_SECTION>	<SDML_TAG>

The Default Format of the Reference Templates

The software reference templates all have the same default output format. When a reference template is begun by specifying a template-enabling tag, the template has the following format:

• A new reference element description is begun and placed at the beginning of a new output page.
  For example, each time a <COMMAND> tag is encountered in the command template, a new reference element description is begun and placed at the beginning of the next output page.
• The name of the current reference element is placed on each output page. The placement of this name depends on the doctype used. In most doctypes, this name is placed at the top of the page.
  For example, if a command called SET TIME was being described and had been specified as <COMMAND>(SET TIME) in the SOFTWARE.REFERENCE doctype, then the single line running heading SET TIME would be placed at the top of the output page above the reference description.
• Each page is numbered using the last major page number prefix.
  For example, if Chapter 2 was the immediately preceding chapter, then 2 would be the prefix associated with the page numbers in the reference section. Similarly, A would be the prefix if appendix A had preceded the reference section.
• Default headings are defined by the reference template for those tags that have such headings.
  For example, the <RESTRICTIONS> tag has associated with it the default heading text Restrictions in the templates in which it is available.

Using the NONE Keyword Argument to Template Tags

Most of the reference template tags place a heading on the output page. Almost all of these tags accept the keyword NONE as an argument. This keyword indicates that the heading should be placed on the output page followed by the text None.

By using the NONE keyword, you ensure that a particular kind of information is explicitly declared as nonexistent or not applicable in a reference element description. Use the NONE keyword rather than typing the word None under the heading because inconsistencies in formatting and spelling of the word may otherwise be introduced.

When you use the NONE keyword as an argument to a template tag, the tag that terminates that template tag must be omitted. For example, if you specify the NONE argument to the <PARAMDEFLIST> tag, the <ENDPARAMDEFLIST> tag must be omitted.

Of all the tags that output a heading in the reference templates, only the <FORMAT>, <STATEMENT_FORMAT>, and <DESCRIPTION> tags do not accept a keyword argument of NONE, because placing the text None beneath the headings output by any of these tags would be inappropriate. If there are no format or description sections, these tags should be omitted.

Using Samples of the Reference Templates

DECdocument provides the following sample reference template SDML files in the directory DOC$TEMPLATES:

Command Template:	DOC$TEMPLATES:COMMAND.SDML
Routine Template:	DOC$TEMPLATES:ROUTINE.SDML
Statement Template:	DOC$TEMPLATES:STATEMENT.SDML
Tag Template:	DOC$TEMPLATES:TAG.SDML

You can also enter an editing session with LSE and expand the appropriate template tags into a reference template SDML file.

See the template samples at the end of this chapter for examples of the SDML code and output from each of the four reference templates.