DECdocument Command Summary and Processing Messages

DECdocument
Command Summary and
Processing Messages

This manual describes the DECdocument commands and qualifiers and explains all the DECdocument processing messages.

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

May 1997

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 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

Preface

Document Structure

This manual describes and lists:

Intended Audience

This book is intended for writers, editors, and general users who wish to produce manuals, brochures, business letters, overhead slides, or online documentation using DECdocument.

Associated Documents

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

Chapter 1
DECdocument Command Summary

This chapter lists and describes all the DECdocument commands. The chapter is separated into two command summaries:

The HELP file also provides a summary of commands for using the Graphics Editor. You can type the following command at the DCL prompt: 


$ HELP DOCUMENT/GRAPHICS

See the Graphics Editor User's Guide for Motif for more information about the Graphics Editor.

DOCUMENT[/FORMATTER]

Starts the DECdocument formatting system.

Format

DOCUMENT[/FORMATTER] input-file doctype destination

Command Qualifier Default
/[NO]BATCH[=qualifier-keyword] /NOBATCH
/CONDITION=condition-name None.
/[NO]CONTENTS /NOCONTENTS
/CONTENTS (Bookreader)
/[NO]DEVICE_CONVERTER[=device-keyword] /DEVICE_CONVERTER
/[NO]DIAGNOSTICS[=file-spec] /NODIAGNOSTICS
/ELEMENT=file-spec None.
/INCLUDE=file-spec None.
/[NO]INDEX[=index-keyword] /NOINDEX
/[NO]KEEP[=filetype-keyword] /NOKEEP
/[NO]LIST[=file-spec] /NOLIST
/[NO]LOG /LOG
/[NO]MAP[=file-spec] /NOMAP
/[NO]MASTER_INDEX[=index-keyword] /NOMASTER_INDEX
/OUTPUT=file-spec See text.
/[NO]PRINT[=qualifier-keyword] /NOPRINT
/PROFILE=file-spec None.
/[NO]SYMBOLS=file-spec /NOSYMBOLS
/[NO]TAG_TRANSLATOR /TAG_TRANSLATOR
/[NO]TEXT_FORMATTER /TEXT_FORMATTER

restrictions

The /FORMATTER command is the default. It is positional; if you use it, it must immediately follow DOCUMENT.

PARAMETERS

input-file

Specifies the input file to be processed. You cannot use wildcards in the input file specification.

The default file type of the input file is SDML. If you specify qualifiers, DECdocument determines the default file type based on the qualifiers and the destination keyword you specify. Table 1-1 lists the qualifiers, the default destinations, and the default file types.

Table 1-1 Default File Types
DECdocument
Qualifiers Used 		Default Destination
Keyword Used 		Default Input
File Type
None. Any SDML
/TAG_TRANSLATOR Any SDML
  • /NOTAG_TRANSLATOR
  • /TEXT_FORMATTER
¹ 		Any TEX
  • /NOTAG_TRANSLATOR
  • /NOTEXT_FORMATTER
  • /DEVICE_CONVERTER
BOOKREADER
LN03
PS
LINE
MAIL
TERMINAL 		DVI_LN03
DVI_PS
DVI_LINE
DVI_LINE
DVI_LINE
  • /NOTAG_TRANSLATOR
  • /NOTEXT_FORMATTER
  • /NODEVICE_CONVERTER
  • /PRINT
LN03
PS
LINE
MAIL
TERMINAL 		DVI_BOOKREADER
LN03
PS
LINE
TXT
TERM

¹Braces in this table indicate that the enclosed qualifiers occur together on the command line.

doctype

The doctype you indicate on the command line determines both the style of your output and the SDML tags you can use. Note that some tags are valid only in specific doctypes.

A number of doctypes have a choice of designs. A design is a specialized form of a doctype. You specify the design keyword immediately after the doctype keyword and separate them with a period (.); for example, SOFTWARE.REFERENCE. You can abbreviate the doctype keyword; for example, you could shorten SOFTWARE.REFERENCE to S.R, as long as each keyword is unique.

See Using Doctypes and Related Tags for more information on doctypes and doctype-specific tags.

destination

Specifies the output device destination for the document. DECdocument supports the following output destinations; your local destinations may be different.
Destination Keyword Formatted For Output File Type
BOOKREADER Bookreader output .DECW$BOOK
HELP Building a Help file .HLP
HTML World Wide Web file .HTML
LINE A line printer .LINE
LN03 An LN03 laser printer .LN03
PS Any Digital-supported POSTSCRIPT output device, such as the PRINTSERVER 40 or the LN03R SCRIPTPRINTER .PS
MAIL Sending through the VMS Mail Utility .TXT
TERMINAL A standard ANSI terminal, such as the VT-100 .TERM
You can abbreviate the destination keyword. For example, you could abbreviate LN03 to LN0, or even LN, as long as that destination is unique.

Note that monospaced fonts defined for all the sizes are provided for text fonts in the POSTSCRIPT destination.

You can have additional local destination keywords defined at your site. See your DECdocument system administrator for information on local destination keywords.

DESCRIPTION

DOCUMENT is the command you specify to start DECdocument. It requires three parameters:

You can use qualifiers to the DOCUMENT command to create an index, master index, and table of contents, and to modify the default processing of your input file.

QUALIFIERS

/BATCH[=(qualifier keyword[,qualifier keyword...])]

/NOBATCH

Specifies whether DECdocument should be run interactively or run as a batch job. The default qualifier is /NOBATCH, which specifies that DECdocument be run interactively.

The /BATCH qualifier submits a job to SYS$BATCH with a job name that has the same file name as the input-file, prefixed with the string "DOC$." For example, the file ROUTINES.SDML would be submitted as the job DOC$ROUTINES.

You can use any of the DCL SUBMIT command qualifiers with DECdocument by using these qualifiers as keywords to the /BATCH qualifier. For example, if you want DOCUMENT to be run after 9:00 and want to be notified when it completes, you could use the following command: 


$ DOCUMENT file-spec /BATCH=(AFTER=09:00,NOTIFY) LETTER LN03

When you use the /BATCH qualifier, a file is created in your current default directory that contains information about the batch job. This file has the same file name as the input file, with a default file type of LOG. When your batch job completes, this file is printed to the queue defined by the logical SYS$PRINT, and the file is deleted.

You must define any process logical names you enter on the DOCUMENT command line in your LOGIN.COM file. Otherwise, DECdocument is unable to translate the logical name during batch processing and issues an error message.

/CONDITION=condition name

Specifies a condition keyword for an SDML input file. This qualifier accepts a condition name argument that is a text string used to mark the condition being set. For more information on using the /CONDITION qualifier, see the <SET_CONDITION> tag description and Producing Online and Printed Documentation.

The /CONDITION qualifier is valid only if tag translation is being done. If you specify /NOTAG_TRANSLATOR with the /CONDITION qualifier, the /CONDITION qualifier is ignored, and DECdocument issues an informational message stating that you specified conflicting qualifiers.

/CONTENTS

/NOCONTENTS

Specifies whether a table of contents file is produced. The /NOCONTENTS qualifier is the default (except when processing for Bookreader, where /CONTENTS is the default) and specifies that no table of contents is produced. When you specify the /CONTENTS qualifier, DECdocument creates a table of contents file with a file name of input_filename_CONTENTS.

If you place the <CONTENTS_FILE> tag in your front matter or profile SDML file, the current table of contents file is included at the corresponding point in the final printable output file (filename.LN03, filename.PS, and so on). If you do not place the <CONTENTS_FILE> tag in your SDML file, the table of contents is not incorporated into your final output file, but is placed in the separate file, input_filename_CONTENTS, and processed separately.

For Bookreader output, a table of contents is generated automatically even if you do not specify the /CONTENTS qualifier on the command line or use the <CONTENTS_FILE> tag in your SDML file.

If you do not specify /CONTENTS on the DOCUMENT command line when you process a file that contains a <CONTENTS_FILE> tag, DECdocument issues warning messages and the most recent version of the table of contents file is included. Note that this may result in an outdated table of contents being included in your document. If there is no previous table of contents file to be included, you receive a warning message and a blank page of output.

The /CONTENTS qualifier is valid only if text formatting is being done. If you specify /NOTEXT_FORMATTER with the /CONTENTS qualifier, DECdocument issues a warning message stating that you specified an illegal combination of command elements.

Note that if you process your document with the /NOTAG_TRANSLATOR and /CONTENTS qualifiers, and the table of contents is included using the <CONTENTS_FILE> tag, the table of contents is incorporated into your document, placed in the file filename_CONTENTS, and processed separately.

Note
The maximum length of a VMS file name is 39 characters. If you want to generate a contents file, your input file name must have no more than 30 characters, because appending _CONTENTS to it adds 9 more characters.

For more information on generating a table of contents, see Producing Online and Printed Documentation and the <CONTENTS_FILE> tag description.

/DEVICE_CONVERTER[=(device keyword [,device keyword...])]

/NODEVICE_CONVERTER

Specifies whether the device converter is run. Using /NODEVICE_CONVERTER excludes device conversion.

The device converter reads and processes an intermediate file (with the file type .DVI_device) and converts it to a file suitable for output on the destination device. The output from the device converter has the same file name as the input file you specified on the command line, and a file type based on the destination keyword you specified on the command line.

The /DEVICE_CONVERTER qualifier optionally accepts the following keywords for special processing of your file:
Device Keyword Description
BLANK_PAGES Specifies that the POSTSCRIPT device converter insert blank pages where needed in the POSTSCRIPT output to create a two-sided document for printing on a duplex printer or for copying on a two-sided copier.
HORIZONTAL_OFFSET= number of points Specifies where the text is to be positioned, relative to the left edge of the paper. The default horizontal offset for the page is one inch (72 points).

The number of points argument specifies the number of points the text page should be moved to the right from the left edge of the paper. This argument must be zero or a positive integer. The left edge of the paper is assumed to be zero.

VERTICAL_OFFSET= number of points Specifies where the text is to be positioned, relative to the top edge of the paper. The default vertical offset for the page is one inch (72 points).

The number of points argument specifies the number of points the text page should be moved toward the page bottom from the top edge of the page. This argument must be zero or a positive integer. The top edge of the paper is assumed to be zero.

STARTING_PAGE= folio spec Specifies the beginning page number of the first page in a range of pages to be printed. If you do not specify an ending page, the rest of the file is printed. The folio spec value can be any valid page number that DECdocument produces on the page.
ENDING_PAGE= folio spec Specifies the ending page number of the last page in a range of pages to be printed. The folio spec value can be any valid page number that DECdocument produces on the page. If both the ENDING_PAGE and NUMBER_OF_PAGES keywords are used together on the same command line, DECdocument issues an error message.
NUMBER_OF_PAGES= maximum pages Specifies the number of pages to print when you do not specify the ENDING_PAGE keyword. If both the ENDING_PAGE and NUMBER_OF_PAGES keywords are used together on the same command line, DECdocument issues an error message.

The maximum pages value must be an integer specifying the total number of pages to print. If this number is specified as a number larger than the number of pages in the document (for example, 99999), all pages of the document are printed.

Use the STARTING_PAGE and ENDING_PAGE keywords to specify the page numbers that are to be processed. Each of these keywords accepts a folio spec argument. A folio spec has the following syntax: 


[{folio prefix}{separator}] {page number}

The following list describes the rules for each of the folio spec syntax elements:

The following DOCUMENT command specifies that pages 11--3 through 11--8 of file MYREPORT.DVI_LN03 be processed by the device converter. 


$ DOCUMENT/NOTAG_TRANSLATOR/NOTEXT_FORMATTER myreport.DVI_LN03 - 
_$  REPORT LN03/DEVICE=(STARTING=11-3,ENDING=11-8)

/DIAGNOSTICS[=file spec]

/NODIAGNOSTICS

Causes the tag translator to write VAX Language-Sensitive Editor (LSE) diagnostics records to a file. LSE uses these records during its REVIEW phase to locate and describe translation errors. The default qualifier is /NODIAGNOSTICS. See Producing Online and Printed Documentation for more information on LSE.

If you omit the file specification, the output file has the same name as the input file, with a file type of DIA.

The /DIAGNOSTICS qualifier is valid only if tag translation is being done. If you specify /NOTAG_TRANSLATOR with the /DIAGNOSTICS qualifier, DECdocument issues a warning message stating that you specified an illegal combination of command elements.

/ELEMENT=file spec

Names the book element that includes the input file specified on the command line. When you use the /ELEMENT qualifier to process a subelement of a book, you must also use the /PROFILE qualifier to specify the profile for the book that contains the book element. If you do not specify the file type of the element file, the default file type is SDML. For more information on processing a subelement of a book, see Producing Online and Printed Documentation.

The /ELEMENT qualifier is valid only if tag translation is being done. If you specify /NOTAG_TRANSLATOR with the /ELEMENT qualifier, DECdocument issues a warning message stating that you specified an illegal combination of command elements.

/INCLUDE=file spec

Specifies a DECdocument file that you want to be included before the input file you specified on the command line. If you do not specify the file type of the file to be included, SDML is the default file type. You can use the /INCLUDE qualifier on the command line only once. For more information about using the \INCLUDE qualifier, see Producing Online and Printed Documentation.

The /INCLUDE qualifier is valid only if tag translation is being done. If you specify /NOTAG_TRANSLATOR with the /INCLUDE qualifier, DECdocument issues a warning message stating that you specified an illegal combination of command elements.

/INDEX[=(index keyword [,index keyword...])]

/NOINDEX

Specifies whether an index file is produced. The /NOINDEX qualifier is the default and specifies that no index is produced. When you specify the /INDEX qualifier, DECdocument creates an index file with a file name of input_filename_INDEX.

When you place the <INDEX_FILE> tag in your profile file, the current index file is included at the corresponding point in the final printable output file (filename.LN03, filename.PS, and so on). If you do not place the <INDEX_FILE> tag in your profile file, the index is not incorporated into your final output file, but is placed in the file input_filename_INDEX, which is printable separately.

Next Contents Index