DECdocument

DECdocument
Tutorial and
Application Guide

This manual explains how to get started with DECdocument. It describes how to use the format tags and document types to create documentation that can be printed and displayed. It also explains how to create HTML and MANPAGE output files.

Revision/Update Information: Updated 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


NOTICE

Copyright ©1995, 1999 Touch Technologies, Inc.

All Rights Reserved

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.

The following are trademarks of Touch Technologies, Inc., and may be used only to describe products of Touch Technologies, Inc.:
DYNAMIC TAPE ACCELERATOR INTOUCH 4GL
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.

May 1997

Contents Index


Preface

DECdocument can be used to produce simple to complex manuals, articles, reports, brochures, letters and overhead slides which can be printed, displayed on a terminal or viewed with Bookreader (an online information access tool provided with DECwindows software).

This manual describes how DECdocument works, the main elements, some of the most commonly used tags (format instructions), document types and provides examples of how to use DECdocument.

This manual also explains how to use DECdocument to create HTML and UNIX MANPAGE output files.

Purpose

The purpose of this Tutorial and Application Guide is to help new users get familiar with DECdocument and to provide some basic documentation examples.

Intended Audience

This manual is intended for new users who wish to learn how to use DECdocument to product formatted documentation. This manual can also be used as a reference guide.

Users should be familiar with a text editor and have a basic knowledge of the OpenVMS operating system.

Associated Documents

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

Conventions

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.
<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.
\ A backslash separates multiple arguments to a tag.


Chapter 1
Overview - How DECdocument Works

DECdocument is used to produce manuals, letters, articles and various forms of documents that can be printed, displayed or viewed. Basically, DECdocument processes an edited text file and creates a formatted file for an output device. The user specifies the document type (i.e. manual, letter, article, etc.) and the output device (PostScript printer, terminal, etc.).

This chapter explains the goals of the Tutorial and Application GuideTutorial and Application Guide and how DECdocument creates formatted documentation files.

1.1 Goals of this Manual

This manual was written for new users of DECdocument. This manual provides users with a straight-forward means of getting acquainted with the DECdocument tools.

DECdocument can be used to create very complex documentation and you will be able to greatly enhance your documenting skills once you have learned the basic fundamentals of DECdocument. After you have completed this manual, you will better understand the other DECdocument manuals and how the various types of documents are created for the different output devices.

In this manual, we will create several types of documents using the DECdocument format instructions. The format instructions are given in the form of tags. Tags are described in Section 1.2.1 and in Chapter 2.

1.2 Main Elements

There are four main elements that DECdocument uses. These elements are:
  1. DOCUMENT command
    This is the command you use to tell DECdocument to process the SDML file.
  2. SDML file
    This is the editor-created text file that is processed by DECdocument. This text file has the extension of SDML. For example: SAMPLE_DOC.SDML
  3. DOCTYPE
    This is the type of document you are creating. This can be a manual, letter, article, etc.
  4. DESTINATION
    This is the output device that the document is going to be printed, displayed or viewed on.

1.2.1 The SDML File

The SDML file that you create using an editor contains:

The format instructions you give to DECdocument are represented by TAGS. Tags are specific words or letters enclosed in <> angle brackets. The tags tell such things as when to start a new paragraph or chapter, indent or bold text, list items, etc. For example:

Some tags are followed by arguments or text enclosed in () parenthesis. For example, the <CHAPTER> tag would be followed by the chapter name.

1.2.2 Doctypes

The DOCTYPE tells what type of document is to be created. Manuals, letters, articles and other types of documents can be created by DECdocument. The doctype is one or two words separated by a period. Some doctypes are:

You can refer to Using Doctypes and Related Tags for more detailed information on the different doctypes and the specific tags that are used with them.

1.2.3 Destinations

The DESTINATION is the output device that the document is going to be printed, displayed or viewed on. When you give the destination, DECdocument processes your SDML file and creates a specific file for the destination (output device) you specified. For example:

Table 1-1 Destination Table
Destination Output file
PS creates a file with the extension of PS that can be printed on a PostScript printer (i.e. SAMPLE_DOC.PS)
MAIL creates a text file with the extension of TXT that can be displayed on a terminal or printed on a line printer (i.e. SAMPLE_DOC.TXT)
TERM creates a file with the extension of TERM that can be typed on a terminal or printed on a line printer; when typed or printed, the bold and underlined text will be shown (i.e. SAMPLE_DOC.TERM)
HTML creates a file with the extension of HTML that can be put on-line to the World Wide Web (i.e. SAMPLE_DOC.HTML)
BOOKREADER creates a file with the extension of DECW$BOOK that can be viewed using BOOKREADER (i.e. SAMPLE_DOC.DECW$BOOK)

Note

The examples in this manual will be using the PS, MAIL, TERM and HTML destinations.

1.3 DOCUMENT Command

After you have created your SDML file, you give DECdocument the DOCUMENT command to process the SDML file. The command line consists of the four main elements. These are:


      $ DOCUMENT        file_name.SDML          doctype         destination 
           |                  |                    |                 | 
           |                  |                    |                 | 
    (1) the command to         |             (3) type of document      | 
    process the file          |             to be created            | 
                              |                                      | 
                     (2) name of the file                       (4) the output 
                     that is to be processed                   device 

Here are examples of DECdocument command lines:


Chapter 2
Tags and Examples

TAGS are used to tell DECdocument how to format the text in an SDML file. There are different tags for all the various formatting operations. DECdocument takes care of the margins and spacing but you need to tell when new chapters, sections and paragraphs begin, when to indent special text, when items are part of a list and other formatting that you want done.

This chapter provides some information about the DECdocument tags and the examples used in this manual.

2.1 Types of Tags

Some tags can be used with ALL the different doctypes (MANUAL, LETTER, ARTICLE, etc.). Other tags can only be used with specific doctypes. For example, there are certain tags that can only be used with the LETTER doctype and there are tags that can only be used with the ARTICLE doctype. There are also tags that can be used with several doctypes but not all doctypes. Tags that can be used with ALL doctypes are called global tags. For the most part, we will be using global tags in the sample documentation we create. However, we will also use some of the specialized tags.

The Tags Quick ReferenceTags Quick Reference guide contains a summary of all the DECdocument tags and tells what doctypes they are used with.

2.2 Examples in This Manual

The examples in this manual will show:
  1. the actual text you write using an editor; this includes the tag or tags that are being described.
  2. the commands you can give DECdocument to process the text.
  3. the PostScript printed output.

Note

The text file you create with the editor MUST have the extension of SDML.

For example, you could edit a file called MYFILE.SDML or SAMPLE_DOC.SDML.

2.3 Using DECdocument

Before we start using the tags, we will see how DECdocument automatically sets up page margins and spacing. The following example shows how DECdocument processes an SDML file and what the printed output text will look like.

Example: No tags

Using the editor, the SDML file, SAMPLE_DOC.SDML is created and the following two paragraphs of text are typed into the file:


There are many groups of dogs.  Each group type will perform a different 
specialized task.  One group is used for herding, one is used for hunting, 
another is used for searching and so on.  Within each group, there are 
numerous breeds of dogs.  For example, in the hunting group, there are 
Labrador Retrievers, Golden Retrievers, Pointers, etc. 
 
Before you get a dog, you should consider what type of dog you want and 
what the dog will be used for.  If you just want a family pet, some breeds 
are better than others.  Some breeds tend to bond to only one person while 
others will bond to all family members.  Selecting the right breed of dog 
is very important. 

Command

The following command is used to process the SDML file and create a PS output file that can be printed on a PostScript printer. The output file will be called SAMPLE_DOC.PS. The name of the output file is the same as the name of the SDML file except that the extension is different. The extension represents the destination device which is PS in this case.

The GENERAL doctype was used to create this manual and is used for many of the examples in this manual.

As the SAMPLE_DOC.SDML file is processed, DECdocument displays some information about the processing steps. Here is what you will see displayed on your screen:


    %DOC-I-IDENT, DECdocument V3.2 
    [ T a g    T r a n s l a t i o n ]... 
    %TAG-I-DEFSLOADD, End of Loading of Tag Definitions 
    %TAG-I-ENDPASS_1, End of first pass over the input 
    [ T e x t    F o r m a t t i n g ]... 
    %TEX-I-PAGESOUT, 1 page written. 
    -TEX-I-OUTFILENAME, 'USER:[DOC]SAMPLE_DOC.DVI_PS' 
    [ D e v i c e    C o n v e r s i o n ]... 
    %DVC-I-PAGESOUT, 1 page written to file: 
       USER:[DOC]SAMPLE_DOC.PS 
    $ 

There are several chapters in the Producing Online and Printed Documentation manual that describe the actual processing steps.

When you print the created SAMPLE_DOC.PS file on a PostScript printer, you will see the following output text.

Output

There are many groups of dogs. Each group type will perform a different specialized task. One group is used for herding, one is used for hunting, another is used for searching and so on. Within each group, there are numerous breeds of dogs. For example, in the hunting group, there are Labrador Retrievers, Golden Retrievers, Pointers, etc. Before you get a dog, you should consider what type of dog you want and what the dog will be used for. If you just want a family pet, some breeds are better than others. Some breeds tend to bond to only one person while others will bond to all family members. Selecting the right breed of dog is very important.

Comments

On the printed hardcopy, you would see that DECdocument provided margins at the top, bottom and sides and the page number "1" at the bottom of the page.

Also, note that there is only one paragraph. This occurred because we did not provide the paragraph tags which would have marked where the paragraphs began. The next chapter will explain how to use the paragraph tag and some of the other tags.


Next Contents Index