This chapter describes how DECdocument processes an SDML file, and describes the informational messages displayed when you process your document.

8.1 DECdocument Processors

Three software processors work sequentially on the SDML file when you execute the DOCUMENT command:

1. Tag translator
2. Text formatter
3. Device converter

These processors check and convert the generically marked text through intermediate files to final printed or online form. Each file keeps the same name as the original source file but gets a file type specific to that processor. (Table 8-1 lists the file types generated by each processor.) The processing sequence displays on your terminal (or, appears in the log file if you choose to process in batch mode).

First, the tag translator translates the tags in the SDML file. As the tag translator processes your file, it checks for coding errors and displays messages accordingly on your terminal. For example, if you misspell a tag name or fail to use an ending parenthesis, an error message is displayed. Processing continues to find as many errors as possible. If you have consistently misspelled a tag, you receive a message only for the first occurrence of that error, then a final message shows how many undefined tags the tag translator found. The tag translator's output is a file with the same name as the input file but with the file type TEX (for example, filename.TEX).

Second, the text formatter reads the TEX file and formats the pages of output. This processor also issues error messages. The text formatter then creates a DVI file with the file type that reflects the destination you specified on the command line. For example, if you specify that you want the file processed for a POSTSCRIPT printer, the DVI file is named filename.DVI_PS. If you specify that you want a file processed for display with Bookreader, the DVI file is named filename.DVI_BOOKREADER.

Third, the device converter creates a device-specific file, with the file type specific to the output device, for example, DECW$BOOK or PS. This file reflects the destination you specified on the command line. If you specified LN03, PS, or BOOKREADER, the text in the file will be proportionally spaced. If you specified LINE, the text will be monospaced.

The device-specific file is ready for printing, viewing with Bookreader, viewing on an ASCII terminal, or mailing through electronic mail.

The three processors interact in the following ways:

• You can run all three processors sequentially with the DOCUMENT command, which is the default. Or, you can use three separate DOCUMENT commands to execute the three processors separately. For more information on how to send SDML files through the three processors separately, see Section 9.3.
• Text formatting depends on both the doctype and the output destination.
• Printing or displaying online depends on the actual output destination you specify, and you must specify each destination separately.

The three processors and the different output file types are summarized in Table 8-1.

Table 8-1 DECdocument Processors

Processor	File Types Created	Description
Tag Translator	TEX	Translates the source files into files used by the text formatter. The tag translator makes two passes over the source file, first checking for errors and then translating the tags.
Text Formatter	DVI_BOOKREADER DVI_LN03 DVI_LINE DVI_PS	Reads the TEX file and formats the pages of output. This processor also searches for errors, but only for errors in the format, not in text elements or tags. Like the tag translator, it issues error messages when necessary. It creates a DVI file for the destination that you specified on the command line. A DVI_LINE file is produced for the destinations LINE, TERM, and MAIL. As the text formatter makes up a page, it automatically formats all page parameters. For printed output, it considers the best arrangement of paragraphs and text elements and appends to the page the appropriate running head and page number. For Bookreader output, it creates online topics and chunks.
Device Converter	DECW$BOOK DECW$BOOKSHELF LN03 LINE PS TERM TXT	Reads the .DVI_ device file created by the text formatter. Once the text formatter has made the page and line breaking decisions, based on the fonts in a given doctype, the device converter makes the formatted file into a file that can be displayed with Bookreader, printed, read on an ASCII terminal, or mailed electronically.

Table 8-2 lists the choices of destination keywords to use on the DOCUMENT command line, the target destination, and the output file type that is created by the destination specified on the DOCUMENT command line.

Table 8-2 Destination Keywords and Output File Types

Destination Keyword	Formatted For	Output File Type
BOOKREADER	Bookreader display	.DECW$BOOK .DECW$BOOKSHELF
HTML	World Wide Web display	.HTML
LINE	A line printer	.LINE
LN03	An LN03 laser printer	.LN03
MAIL	Sending through electronic mail	.TXT
PS	Any Digital-supported POSTSCRIPT output device, such as the PRINTSERVER 40 or the LN03R SCRIPTPRINTER	.PS
TERMINAL	A standard ANSI terminal, such as the VT-320	.TERM

8.2 Informational Messages

Each DECdocument processor displays informational messages when the DOCUMENT command is used interactively, as shown in the following example. (If you process your SDML file as a batch job, DECdocument creates a log file containing the informational messages.)

(1)$ DOCUMENT myreport REPORT PS %DOC-I-IDENT, DECdocument V3.0 (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 (3)[T e x t F o r m a t t i n g ]... %TEX-I-PAGESOUT, 17 pages written. -TEX-I-OUTFILENAME, 'DUA1:[DOCFILES]MYREPORT.DVI_PS' (4)[ D e v i c e C o n v e r s i o n ]... %DVC-I-PAGESOUT, 17 pages written to file: DUA1:[DOCFILES]MYREPORT.PS

(1) Identifies the DOCUMENT command line that you type at the DCL prompt. In this example, the DOCUMENT command was issued for a file called MYREPORT.SDML. (The SDML file type is assumed by the tag translator.) The file was processed for the REPORT doctype, and the output can be printed on a POSTSCRIPT printer.

(2) Indicates that the tag translator has begun to process the file, and will log its activities. Any tag translator errors are reported here.

(3) Signifies that text formatting has begun. Any text formatting errors are reported here.

(4) Indicates the point when device conversion begins. Any device conversion errors are reported here.

This chapter describes how to use the DOCUMENT command line to process SDML files to print or read on supported devices. You can process a single file or a group of files.

This chapter assumes you have read Chapter 1 and understand how to use the DOCUMENT command line and how DECdocument processes a file.

9.1 Processing Single Files

Process a single SDML file by entering the DOCUMENT command line.

$ DOCUMENT input-file-spec doctype destination

You must type the command line parameters in this order. For more information on the DOCUMENT command line, see Using Global Tags.

You can process a single input file and print it on a hardcopy device, view it using Bookreader (see Part 3 for information on processing and viewing books through the Bookreader), view it on a terminal screen, or view it within electronic mail.

DECdocument processes files interactively, by default. You can process files in batch to enable you to use your terminal while DECdocument processes the files. See Section 9.2.2 for more information on processing files in batch.

When processing interactively, you can use the /LIST qualifier on the DOCUMENT command line to capture any error messages. In response, DECdocument creates a file named filename.LIS to hold the messages, and places the file in your current directory. To use the /LIST qualifier, type the following command line:

$ DOCUMENT input-file-spec doctype destination /LIST

Avoid concurrent processing of a single input file from the same default directory. DECdocument cannot use the same intermediate files to process builds of the same file simultaneously.

9.2 Controlling File Processing

You can add qualifiers to the command line to control how processing occurs, which processors will be used, and what portion of a document gets processed. The following qualifiers can be particularly useful in processing your files. Make sure that you use each of these qualifiers only once on the command line.

9.2.1 Keeping Intermediate Files (Using /KEEP)

By default, DECdocument deletes intermediate files from your directory after using them during processing. To keep the intermediate files for later use, specify the /KEEP qualifier on the command line.

By keeping the intermediate files, you can normally reprocess a document starting from any stage of processing. For more information, see Section 9.3.

9.2.2 Processing in Batch Mode (Using /BATCH)

Use the /BATCH qualifier on the command line to process your files as a batch job (interactive processing occurs by default). This frees your terminal for other tasks while your job is processing.

By default, the /BATCH qualifier creates a log file named filename.LOG. DECdocument places the log file in your current directory, and lists any processing errors found by the tag translator or by the text formatter. You can type or edit the .LOG file. The .LOG file differs only slightly from the .LIS file you get when you use the /LIST qualifier. Normally you do not need to specify both the /LIST and /BATCH qualifier.

The /BATCH qualifier accepts many keywords to modify the batch processing activity. These keywords are the same as the DIGITAL Command Language (DCL) SUBMIT command qualifiers.

9.2.3 Altering Page Alignment (Using /DEVICE_CONVERTER)

Use the /DEVICE_CONVERTER=(device-keyword) qualifier to alter the page positioning of an entire document. The following qualifiers shift the printed image on the page:

• /DEVICE_CONVERTER=(HORIZONTAL_OFFSET= number-of-points) specifies the position of a document's left margin. The HORIZONTAL_OFFSET keyword shifts the image horizontally.
• /DEVICE_CONVERTER=(VERTICAL_OFFSET=number-of-points) specifies the position of a document's top margin. The VERTICAL_OFFSET keyword shifts the image vertically.

In both cases, the number of points is an integer that specifies how far from the margin the text should be shifted (72 points is equal to 1 inch). The default horizontal and vertical offsets are both set at 72 points.

9.2.4 Including Additional Files (Using /INCLUDE)

To include an additional file at the front of your final output, specify the /INCLUDE qualifier on the DOCUMENT command line. The /INCLUDE qualifier assumes a file type of SDML for the included file if none is specified, but accepts other file types.

You can use /INCLUDE only once on the DOCUMENT command line. If you use it more than once, only the last /INCLUDE is valid.

An example of a file that might be included with the /INCLUDE qualifier is a cover page that reads "For Internal Use Only." The input file that contains the cover page text, called COVERPAGE.SDML, would be specified on the command line with /INCLUDE=coverpage.

You can include a file another way by using the <INCLUDE>(file-spec) tag in your SDML file. This tag serves the same purpose as /INCLUDE, except that DECdocument includes the file in your output file at the exact location of the tag in your document.

9.2.5 Setting Conditions for Files (Using /CONDITION)

DECdocument allows you to set conditions for an input file so you can process the same file to obtain different output for different purposes. Use the /CONDITION qualifier on the DOCUMENT command line to establish the condition under which the file is processed.

For example, consider the following situation: you want to write two letters, one to a friend and one to an acquaintance. Most of the text of the two letters will be the same, but you want to add a personal note to your friend. By using the /CONDITION qualifier, you need to write only one letter.

Assume that the file containing the letter is named MYLETTER. Create conditional sections in MYLETTER, with <CONDITION>(personal) tags, where "personal" is the condition name. Process the letter to the acquaintance, using the usual DOCUMENT command line. Then, process the letter to your friend, this time using the /CONDITION qualifier on the command line, specifying the condition as "personal." For example:

$ DOCUMENT myletter LETTER LN03 /CONDITION=personal

When you specify the condition name used in the <CONDITION> tag on the command line, DECdocument includes all the text that was tagged with that condition name in the output. This time, all the text tagged with <CONDITION>(personal) is included. DECdocument suppresses this text when you do not specify the /CONDITION qualifier on the command line.

You can also set a condition by using the <SET_CONDITION> tag. When you use the <SET_CONDITION> tag, you do not need to use the /CONDITION qualifier when you process the file. For more information on the <SET_CONDITION> tag, see Using Global Tags.

You can use /CONDITION only once on the DOCUMENT command line. If you use it more than once, only the last /CONDITION is valid.

9.2.6 Including a Symbols File (Using /SYMBOLS)

If you have a file that contains definitions of symbols, and you want DECdocument to read that file during the processing stage, use the /SYMBOLS qualifier on the DOCUMENT command line.

The following example shows how to process CHAP1.SDML using the SOFTWARE.HANDBOOK doctype, with the PS destination, and calling in a symbols file named MYSYMBOLS.SDML:

$ DOCUMENT CHAP1 SOFTWARE.HANDBOOK PS /SYMBOLS=MYSYMBOLS

The symbols file should contain only symbols defined with the <DEFINE_SYMBOL> tag or the <DEFINE_BOOK_NAME> tag.

DECdocument reads the /SYMBOLS qualifier only during the tag translator processing stage. If you specify the /NOTAG_TRANSLATOR qualifier with the /SYMBOLS qualifier, DECdocument issues an informational message stating that you have specified conflicting qualifiers.

You can use /SYMBOLS only once on the DOCUMENT command line. If you use it more than once, only the last /SYMBOLS is valid.

9.2.7 Assigning a New Output File Name (Using /OUTPUT)

If you process a conditionalized file twice to get two different output files, you may want to use a DOCUMENT command line qualifier that assigns a new name to the output file. The /OUTPUT=filespec qualifier gives the final output file any name that you choose.

The example of the letter to your friend (in Section 9.2.5) can be processed and the output renamed if you use the following command line:

$ DOCUMENT myltr LETTER LN03 /CONDITION=personal /OUTPUT=sam_ltr

You can use /OUTPUT only once on the DOCUMENT command line. If you use it more than once, only the last /OUTPUT is valid.

9.3 Processing Intermediate Files

If you use the /KEEP qualifier to keep intermediate files during DECdocument processing, you can reprocess a document at any stage of processing. For example, if your system is interrupted after tag translation but before text formatting or device conversion, you can reprocess the document starting at the text formatting stage.

If you specify the appropriate combination of command line qualifiers, processing starts at the specified point:

• To start processing after tag translation, specify /NOTAG_TRANSLATOR on the DOCUMENT command line. You must have a .TEX file to start at this point. For example:

  $ DOCUMENT CALC_GUIDE.TEX SOFTWARE.HANDBOOK PS /NOTAG_TRANSLATOR

  
  DECdocument will begin processing the TEX file at the text formatting stage.
  Do not try to reprocess a TEX file using a different doctype from the one specified on the original command line. This could cause errors and the results are unpredictable.

• To start processing after text formatting, specify /NOTAG_TRANSLATOR and /NOTEXT_FORMATTER on the DOCUMENT command line. (Using /NOTAG_TRANSLATOR prohibits use of the following related qualifiers: /CONDITION, /DIAGNOSTICS, /ELEMENT, /INCLUDE, /MAP, /PROFILE, and /SYMBOLS. Using /NOTEXT_FORMATTER prohibits use of the following related qualifiers: /CONTENTS and /INDEX.) You must have a .DVI_device file to start at this point. For example:

  $ DOCUMENT CALC_GUIDE.DVI_PS SOFTWARE.HANDBOOK PS/NOTAG_TRANSLATOR /NOTEXT_FORMATTER

  Note See the DECdocument Command Summary in the Command Summary and Processing Messages for more information on command-line qualifiers and how to use them.

  
  DECdocument will begin processing the .DVI_device file at the device conversion stage.
  You cannot reprocess a .DVI_device file to make the file readable by a device other than the one for which the file was originally processed. The exceptions to this rule are files processed for the LINE, TERMINAL, and MAIL destinations. These destinations all use the same DVI_LINE intermediate file, so you can reprocess for these different destinations.
• To print the output file without reprocessing it, specify /NOTAG_TRANSLATOR, /NOTEXT_FORMATTER, /NODEVICE_CONVERTER, and /PRINT to suppress the tag translator, the text formatter, and the device converter. Use the /PRINT qualifier if you want to print the file automatically on an output device, rather than enter the DCL PRINT command yourself. You must have a device-specific output file, such as a filename.LN03 file.

If any of your book element input files contain enough tag translator errors to halt the processor, the tag translator will not produce a .TEX file of that element, and the bookbuild will stop after the last element has been processed. To fix this, perform the following steps:

1. Fix the errors in the book element input files.
2. Reprocess each revised book element file by typing the following command:

   $ DOCUMENT input-file-spec doctype destination /NOTEXT_FORMATTER /PROFILE=profile-spec

   
   The input-file-spec is the name of the individual book element file, and the profile-spec is the name of the profile.

3. Submit the bookbuild again, this time using the /NOTAG_TRANSLATOR qualifier to avoid sending the entire book through the tag translator for a second time.

   $ DOCUMENT profile-spec doctype destination /NOTAG_TRANSLATOR