This manual describes the DECdocument SOFTWARE doctype and the tags specific to this doctype.

Revision/Update Information: No Updates for Version 3.2

Operating System and Version: VAX OpenVMS Version 5.4 or higher
Alpha OpenVMS Version 6.1
or higher

Software Version:
DECdocument Version 3.2

The information in this document is subject to change without notice and should not be construed as a commitment by Touch Technologies, Inc. Touch Technologies, Inc. assumes no responsibility for any errors that may appear in this document.

The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license.

No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies.

Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013.

Copyright ©1995, 1997 Touch Technologies, Inc.

All Rights Reserved

The following are trademarks of Touch Technologies, Inc., and may be used only to describe products of Touch Technologies, Inc.:

DYNAMIC TAPE ACCELERATOR	INTOUCH 4 GL
DYNAMIC LOAD BALANCER PLUS	INTOUCH INSA
REMOTE DEVICE FACILITY

The following are trademarks of Digital Equipment Corporation:

DEC	DIBOL	UNIBUS
DEC/CMS	EduSystem	VAX
DEC/MMS	IAS	VAXcluster
DECnet	MASSBUS	VMS/OpenVMS
DECsystem--10	PDP	VT
DECSYSTEM--20	PDT
DECUS	RSTS
DECwriter	RSX	Digital logo

PostScript is a registered trademark of Adobe Systems, Inc.

Contents

Index

Document Structure

This manual describes the DECdocument doctype-specific tags that are restricted to the SOFTWARE doctype. These tags are not available in all doctypes.

With each discussion of doctype-specific tags, an example shows how you use those tags in an input file, and what the output is when you process that input file.

The description of tags specific to one style also contains reference information about the tags. This reference information describes the syntax and any restrictions associated with each tag. It also provides an example of the tag used in an SDML (Standard DIGITAL Markup Language) file.

Chapter 1 provides an overview of all the doctypes discussed in the two volumes of Using Doctypes and Related Tags. The remainder of this manual discusses the SOFTWARE doctype and its designs. Examples of tag use in SDML files and corresponding processed outputs is provided.

Intended Audience

This book is intended for writers, editors, and general users who want to produce articles, letters and memos, military specifications, technical and non-technical manuals, reports, overhead slides or documentation that you can read with Bookreader. You should be familiar with a text editor.

Associated Documents

This manual is part of the DECdocument documentation set that includes the following books:

• Installation Guide
• Tutorial and Application Guide
• Producing Online and Printed Documentation
• Using Global Tags
• Using Doctypes and Related Tags - 2 Volumes
• Tags Quick Reference
• Command Summary and Processing Messages
• Graphics Editor User's Guide for Motif

Conventions

In Volumes 1 and 2 of Using Doctypes and Related TagsUsing Doctypes and Related Tags, the discussion of each tag follows a fixed order. First, the name of the tag is followed by a brief overview that describes the purpose of the tag. Following the overview is a syntax section that displays the syntax of the tag: any required or optional arguments, any related tags, any restrictions on the use of the tag, and any required terminators to the tag, if needed.

The category of "related tag" is defined broadly. A tag is related to the tag under discussion if one of the following criteria is met:

• It is required for use of the tag under discussion.
• It marks a text element of the same kind as the tag under discussion.
• It is commonly used with the tag under discussion.

Following the syntax section is a description section. The description expands the overview and presents more detailed information on using the tag.

The discussion of a tag concludes with at least one example, or a reference to an example. The example shows how to code the tag in an SDML file.

Each output example is introduced by the sentence "This example produces the following output:". Output examples may vary, however, depending on the doctype you use and on whether any doctype modifications have been made to your local installation of DECdocument.

Table 1 lists the typographical conventions used in this manual.

Table 1 Conventions Used in this Manual

Convention	Meaning
. . .	In examples, a vertical ellipsis represents the omission of data that the system displays in response to a command or to data you enter.
...	In examples, a horizontal ellipsis indicates that you can enter additional parameters, values, or other information. In tag syntax, a horizontal ellipsis indicates that arguments to the tag have been omitted.
TERM	A term that appears in bold type is defined in the glossary in the Producing Online and Printed Documentation manual.
<TAG>(argument)	Parentheses enclose an argument to a tag. A lowercase word as an argument to a tag indicates that a user-specified argument must be entered.
<TAG>[(argument)]	Brackets indicate that the enclosed argument to the tag is optional.
<TAG>[(argument-1 [ \argument-2])]	This tag syntax indicates that both arguments are optional. Only if you use argument-1, however, do you have the choice of using argument-2.
<TAG>[([argument-1] \ [argument-2])]	This tag syntax indicates that both arguments are optional. You can use either argument as the first argument.
<TAG> [( argument-1 KEYWORD-1 [ \KEYWORD-2] )]	This tag syntax indicates that all arguments are optional. The braces indicate a choice between argument-1 and KEYWORD-1. You must choose your first argument. If you choose KEYWORD-1, you also have the option of indicating KEYWORD-2 as the second argument.
<TAG>(KEYWORD)	An uppercase word within an argument to a tag indicates that the word is a keyword, and that you must enter the specific keyword.
<TAG>(\KEYWORD)	A keyword following a backslash in an argument to a tag indicates that that keyword must follow a backslash.
\	A backslash separates multiple arguments to a tag.

This manual describes the DECdocument SOFTWARE doctypes and the associated tags. These doctype-specific tags are restricted to certain doctypes and so are not available in all doctypes.

Using this Manual

All the doctypes and doctype-specific tags are described in Volumes 1 and 2 of Using Doctypes and Related Tags. As shown in Table 1-1, these chapters are ordered alphabetically by doctype name. Each chapter provides an overview of a specific doctype and its designs. It describes how to use that doctype and what doctype-specific tags and global tags are available within it (some doctypes do not use all the global tags).

The description of doctype-specific tags also contains reference information about the tags. The reference information describes the syntax and restrictions associated with each tag.

Each chapter includes an input and output sample of at least one SDML file that uses these tags.

Table 1-1 lists the supported doctypes, explains what each doctype is generally used for, and tells which chapters in this manual describe them.

Table 1-1 Supported Doctypes

Doctype Keyword	Used to Create	Tutorial/Reference Volume/Chapter
ARTICLE	Two-column articles	Vol. 1, Chapter 2
GENERAL	Manuals and general output	Vol. 1, Chapter 3
HELP	.HLP files used for online Help	Vol. 1, Chapter 4
LETTER	Letters and memos	Vol. 1, Chapter 5
MANUAL	User manuals about topics other than software	Vol. 1, Chapter 6
MILSPEC	Military specifications	Vol. 1, Chapter 7
ONLINE	Output that can be read with the DECwindows Bookreader	Vol. 1, Chapter 8
OVERHEADS	Transparencies for overhead or 35mm slides	Vol. 1, Chapter 9
REPORT	General-purpose documents or formal outlines	Vol. 1, Chapter 10
SOFTWARE	User manuals containing software-specific information	Vol. 2, Chapter 2

1.1 Using Doctypes and Doctype-Specific Tags

The language you use to mark up a file for processing through DECdocument is called generic because it is used, unchanged, to produce any type of document. However, part of using DECdocument involves specifying a doctype to create the particular document format you want. For example, you want a different format for a manual than you want for a letter.

DECdocument automatically specifies the correct formatting instructions for a chosen doctype, freeing you from the task of formatting text and letting you concentrate on the task of writing.

All your writing is done in an input file, which is also called an SDML file because of its file extension of .SDML. When you create a file to be processed through DECdocument, always give the file an .SDML extension.

The SOFTWARE doctype has six designs for printed software documentation, shown in Figure 2-1, and one design for Bookreader documentation.

• SOFTWARE.BROCHURE
  Creates a brochure in a 7 x 9 -inch format with unnumbered headings.
• SOFTWARE.GUIDE
  Creates a users' guide in a 7 x 9 -inch format with numbered headings.
• SOFTWARE.HANDBOOK
  Creates a handbook in a 7 x 9 -inch format with numbered headings.
• SOFTWARE.POCKET_REFERENCE
  Creates a pocket reference in a 5 1
  2 x 7 -inch format with numbered headings.
• SOFTWARE.REFERENCE
  Creates a reference manual in an 8 1
  2 x 11 -inch format with numbered headings.
• SOFTWARE.SPECIFICATION
  Creates a specification in an 8 1
  2 x 11 -inch format with numbered headings.
• SOFTWARE.ONLINE
  Creates an online reference manual in a 5.9 x 6.6 -inch format with numbered headings and ragged right margin. This design is solely for Bookreader display. Refer to Producing Online and Printed Documentation for full information about producing Bookreader documentation.

Figure 2-1 SOFTWARE Doctype Designs

2.1 Characteristics of the SOFTWARE Designs

• Table 2-1 is for the SOFTWARE.BROCHURE design.
• Table 2-2 is for the SOFTWARE.GUIDE design.
• Table 2-3 is for the SOFTWARE.HANDBOOK design.
• Table 2-4 is for the SOFTWARE.POCKET_REFERENCE design.
• Table 2-5 is for the SOFTWARE.REFERENCE design.
• Table 2-6 is for the SOFTWARE.SPECIFICATION design.

Table 2-1 Page Layout of the SOFTWARE.BROCHURE Doctype Design

Page Layout Characteristics
Running heads	None
Running feet	Chapter title text¹ and page number
Page numbering	Chapter oriented
Trim size	7 x 9
Gutter width	6 picas
Right margin	Unjustified (Ragged right)
Text Element Characteristics
Headings	Unnumbered
Paragraphs	Flush left at gutter width
Figures, tables, and examples	Numbered, table of contents entry

Table 2-2 Page Layout of the SOFTWARE.GUIDE Doctype Design

Page Layout Characteristics
Running heads	Chapter title text
Running feet	Chapter number and page number
Page numbering	Chapter oriented
Trim size	7 x 9 inches
Gutter width	5 picas
Right margin	Unjustified (Ragged right)
Text Element Characteristics
Headings	Numbered
Paragraphs	Flush left at gutter width
Figures, tables, and examples	Numbered, table of contents entry

Table 2-3 Page Layout of the SOFTWARE.HANDBOOK Doctype Design

Page Layout Characteristics
Running heads	None
Running feet	Chapter title text and page number
Page numbering	Chapter oriented
Trim size	7 x 9 inches
Gutter width	6 picas
Right margin	Unjustified (Ragged right)
Text Element Characteristics
Headings	Numbered
Paragraphs	Flush left at gutter width
Figures, tables, and examples	Numbered, table of contents entry

Table 2-4 Page Layout of the SOFTWARE.POCKET_REFERENCE Doctype Design

Page Layout Characteristics
Trim size	5 1/2 x 7 inches
Gutter width	0
Right margin	Unjustified (Ragged right)
Text Element Characteristics
Headings	Numbered, rule only under <HEAD1>
Paragraphs	Flush left, no first line indent
Figures, tables, and examples	Numbered; table of contents entry

Table 2-5 Page Layout of the SOFTWARE.REFERENCE Doctype Design

Page Layout Characteristics
Running heads	Chapter title text
Running feet	Page number
Page numbering	Chapter oriented
Trim size	8 1/2 x 11 inches
Gutter width	9.5 picas
Right margin	Unjustified (Ragged right)
Text Element Characteristics
Headings	Numbered
Paragraphs	Flush left at gutter width
Figures, tables, and examples	Numbered, table of contents entry

Table 2-6 Page Layout of the SOFTWARE.SPECIFICATION Doctype Design

Page Layout Characteristics
Trim size	8 1/2 x 11 inches
Gutter width	0
Right margin	Unjustified (Ragged right)
Text Element Characteristics
Headings	Numbered
Paragraphs	Flush left, no first line indent
Figures, tables, and examples	Numbered; table of contents entry

The following example shows how to process a file named MYSOFTWARE.SDML with the SOFTWARE.GUIDE doctype:

$ DOCUMENT mysoftware SOFTWARE.GUIDE LN03

Of the six available designs, SOFTWARE.REFERENCE is the default. To use this doctype, you need only enter SOFTWARE (or a truncated form of SOFTWARE) as a keyword on your DOCUMENT command line.

The SOFTWARE doctype provides four templates for documenting reference information. In any of the six SOFTWARE doctype designs, you can use one or more of the following reference templates:

• The Command template
• The Routine template

• The Statement template
• The Tag template

• The specific tags used for each SOFTWARE doctype The SOFTWARE doctype-specific tags are available only in the SOFTWARE doctype and let you create basic writing elements you need to describe computer software. See Section 2.19 for detailed information on these tags.
• The groups of tags specific to each of the four reference templates The reference template tags are available only in the reference templates of the SOFTWARE doctype. With these tags, you can specify the format of a software command, the restrictions on such commands, prompts used in an interactive environment, and so on. See Section 2.8 for detailed information on these tags.