This manual describes, for the new and experienced user, how to use DECdocument to produce documentation that can be printed, viewed on a terminal, or viewed with Bookreader.
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.
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 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.
| Contents | Index |
This book describes how to use DECdocument to produce documentation that can be printed, viewed on a character-cell terminal, or viewed with Bookreader (an online information access tool provided with DECwindows software).
This book is divided into four main parts, has one appendix, a glossary, and an index.
| 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. |
| <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. |
This book is intended for writers, editors, and general users who wish to produce technical manuals, books, brochures, business letters, or overhead slides using DECdocument. Users should be familiar with a text editor, and have a basic knowledge of the VMS operating system.
This manual is part of the DECdocument documentation set that includes the following manuals:
DECdocument is a text processing system that lets you produce a variety of documents such as memos, letters, articles, overhead transparencies, and technical documentation. When you produce documentation using DECdocument, you use a generic markup language called SDML (Standard DIGITAL Markup Language) to create source files. With a generic markup language you can use one source file to produce output for a wide range of devices, including printed and online display.
When you use DECdocument to create a document, you do not have to think about margins, spacing, and other formatting characteristics. Instead, you must think about text elements. A text element is any individual piece of text, such as a paragraph, an emphasized word, a heading, and so on. Using DECdocument, you identify the different text elements for the processor by tagging them.
Example
<CHAPTER>(Introduction to DECdocument\intro)
<P>
DECdocument is a text processing system
that lets you produce
a variety of documents such as
memos, letters, articles, overhead transparencies,
and technical documentation.
|
With a generic markup language, the document type
(doctype) controls the underlying format for consistency.
DECdocument automatically specifies the correct formatting
instructions for a chosen doctype, freeing the writer from the task of
formatting text and allowing the writer to concentrate on the task of
writing.
1.1 Writing Books for Both Printed and Bookreader Display
When you use DECdocument, you create a document comprising one or several SDML files. If you are writing an entire book, you will create several SDML files and process them together in a bookbuild. Then, you will be able to print your book or display it with Bookreader. DECdocument provides the ability to create SDML files that you can process once for Bookreader display, and once for printed display.
Coding for Bookreader books is much the same as coding for printed
books, but presenting a book through Bookreader creates a new set of
visual considerations. If you are creating a book to be read only in
printed form now, you can still adhere to the Bookreader considerations
described throughout this guide. Later, you may want to display your
book by Bookreader, and if you have followed all the Bookreader
formatting guidelines, placing your book on Bookreader will be one
DOCUMENT command away.
1.1.1 Topics and Online Chunks
To successfully create a Bookreader book, you need to envision how the book will look when viewed by Bookreader.
The biggest difference between a printed book and a Bookreader book is that no physical pages exist in Bookreader; there are no page numbers in Bookreader books. Instead, information is kept in a collection of online chunks and topics. Online chunks are the smallest units of information that Bookreader can access from the table of contents, the index, or other sections that refer to them. A topic is a collection of information chunks. Topics appear in the table of contents.
Because Bookreader has no knowledge of the contents of online chunks, it cannot go directly to a line in a paragraph from an index entry. Instead, Bookreader accesses the whole online chunk that has been referenced. If the length of the online chunk is larger than the length of the topic window, the reader must use the vertical scroll bar to read all the text. Therefore, the information is more accessible if you create smaller online chunks to fit onto the screen.
DECdocument creates chunks from the following elements of your book:
As you think about topics and online chunks of information, consider graphics for Bookreader. You can display tables, figures, and examples in separate windows that are popped up on the DECwindows screen. To pop up these graphics, the reader uses the hotspot feature. Hotspots are regions in the windows the user clicks on with a mouse to access cross-referenced topics, such as graphics.
¹ Formal tables, figures, and examples have captions and numbers, and appear in the table of contents. Informal tables, figures, and examples do not have captions and numbers, and do not appear in the table of contents. |
1.2 Using the DOCUMENT Command Line
After you write a document using SDML tags, you can process your file once for each output device you want to use to view your finished book. To process your SDML source file, use the DOCUMENT command line.
$ DOCUMENT input-file-spec doctype destination
|
The DOCUMENT command requires three parameters
On the command line, you can abbreviate the command, qualifiers, and keywords to the shortest unique string. For example, you can abbreviate DOCUMENT to DOCU, and the local destination, PS_LOCAL_PRINTER to PS. |
You can add qualifiers to the DOCUMENT command to create tables of contents, indexes, master indexes, or to modify the processing of your input file. The DOCUMENT command, parameters, and qualifiers are explained in the DECdocument Command Summary in Using Global Tags.
When creating a document for printed and Bookreader display, you use basic text elements such as:
DECdocument provides tags related to each of the elements you use to create a book. This chapter introduces these tags and provides guidelines for using these tags and their arguments in an SDML file. It also describes some of the most basic tags used to create documents for printed and Bookreader display.
See Using Global Tags and Using Doctypes and Related Tags for more information on each of the
tags in this chapter.
2.1 Global Tags and Doctype-Specific Tags
Many of the SDML tags you use to code your text are valid in any doctype. Tags that work in any doctype are called global tags. For example, all doctypes provide paragraphs and lists, so <P> and <LIST> are global tags.
Tags that you use exclusively in one doctype are called doctype-specific tags. For example, using the <FROM_ADDRESS> tag in anything but the LETTER doctype produces an error:
%TAG-W-TAGNOTDEF, text, line 5, file
VAXNODE$DUA0:[ANDERSON.DOCUMENT]MY_LETTER.SDML;
Tag <FROM_ADDRESS> is undefined
|
When you write for both printed and Bookreader output, you can use Bookreader formatting tags without concern because these special tags do not affect printed doctypes.
See Using Global Tags for more information on all global tags.
See Using Doctypes and Related Tags for more information on doctype-specific tags.
See the Tags Quick Reference for a list of all the global and doctype-specific
tags.
2.2 Tags and Tag Arguments
You must follow three basic rules when you use DECdocument tags and arguments.
Tag every text element.
This rule is true whether or not the tag requires an argument list, a terminating tag, or both.
For example, the following text contains three text elements. Therefore, you need to use three tags:
Example
<HEAD1>(Employment\emp)
<P>
Employment opportunities grew throughout the company. If the president
of the company had realized what a <NEWTERM>(matrix) would start
developing...
|
In this example, the writer started a new paragraph and tagged it with the <P> tag. The writer also wanted to identify a new term in this document with some special format. Thus, the writer treated the new term as an individual text element and tagged it.
Output
Employment
Employment opportunities grew throughout the company. If the president of the company had realized what a matrix would start developing...
Type each tag as shown in the documentation, adding no punctuation or spaces. Use angle brackets to enclose tags. The tag name may be in uppercase or lowercase letters, or a combination of both.
For every text element (that is, every individually treated portion of text), insert a unique tag to identify that type of text element -- a paragraph, a table, and so on. Here are some sample tags.
| Tag | Function |
|---|---|
| <P> | Starts a paragraph |
| <CHAPTER> | Marks the beginning of a chapter |
| <TABLE> | Begins a table (like this one) |
| <ENDTABLE> | Ends a table |
| <LIST> | Begins a list |
| <ENDLIST> | Ends a list |
DECdocument provides two types of tags:
Supply only those arguments that are permitted by the tag's format. Use parentheses to enclose arguments.
An argument is additional processing information supplied to an SDML tag. Enclose arguments in parentheses immediately after the closing angle bracket of the tag. A space or an end of line cannot separate the tag from its argument. However, if a tag does not require or accept an argument, you can separate the tag from surrounding text by a space or an end of line.
DECdocument provides two types of tag arguments:
When you include more than one argument within the parentheses (this is called an argument list), use a backslash (\) to separate multiple arguments. For example, the <CHAPTER> tag takes two arguments, a chapter title and a symbol name for that title; these arguments are separated by a backslash, as follows:
<CHAPTER>(Introduction to Farming\intro_farm)
|
Each tag description given in Using Global Tags and in Using Doctypes and Related Tags includes a list of valid or required arguments to that tag. (See Chapter 4 in this book for more information on using symbol names.)
DECdocument treats certain characters and character strings in a special manner when they are placed in an argument to an SDML tag. Table 2-1 summarizes these characters and shows how to code them correctly.
The tag translator displays an error message when you have incorrectly coded any of these special characters in an argument.
| Next | Contents | Index |