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
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 |
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.
The purpose of this Tutorial and Application Guide is to help new users get familiar with DECdocument and to provide some basic documentation examples.
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.
This manual is part of the DECdocument documentation set that includes the following manuals:
| 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. |
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.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:
| 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) |
| 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) |
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:
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:
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.
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. |
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.
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.
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 |