Use the DCL PRINT command with the appropriate qualifiers to print any of your output files. The queue names are defined by your system manager. To print output files automatically after processing, use /PRINT on the DOCUMENT command line.

See the DECdocument Command Summary in Using Global Tags for more information on the print commands and their qualifiers.

9.5 Processing Selected Pages

If you want to process and print (or reprocess and print) selected pages of a document, you need to have kept the .DVI_device file. To process selected pages, use the /DEVICE_CONVERTER command line qualifier with (for example) the following keywords:

• /DEVICE_CONVERTER=STARTING_PAGE=5, which instructs the printer to begin printing with page 5 of the document.
• /DEVICE_CONVERTER=ENDING_PAGE=3, which instructs the printer to print pages 1, 2, and 3.
• /DEVICE_CONVERTER=(START=5, NUMBER=3), which instructs the printer to print pages 5, 6, and 7.

Alternately, you can use the following qualifier:

• /DEVICE_CONVERTER=(NUMBER_OF_PAGES=total-pages) which specifies the number of pages to print, when no ENDING_PAGE keyword is specified.

The ENDING_PAGE and NUMBER_OF_PAGES keywords cannot be used together on the same command line. If they are used together, DECdocument issues an error message.

9.6 Bookbuilding

Besides processing an individual file, you can process a group of files as a book. This process is called a bookbuild. One major benefit of processing a file as part of a book is that the bookbuild creates a file containing all the symbol names you created throughout the book. You can subsequently reprocess individual elements of the book using the file of symbol names to resolve cross-references to other elements of the book.

There are three steps in creating and building a book:

1. Create the book element input files, naming them with .SDML file types. Each file must contain a book element tag, and each book element tag must have a symbol name.
2. Create a profile, naming this file with an .SDML file type. A profile contains a list of <ELEMENT> tags that specify the elements composing your book. Once created, this profile becomes the file you specify for processing on the DOCUMENT command line.
3. Process the profile.

The following sections describe each step in building a book.

9.6.1 Creating Input Files

Create a file for each element of your book. Use a <CHAPTER> or <APPENDIX> tag to head each element, and add <HEADN> tags if you have an outline of the chapter.

If you have not yet decided on the order of the chapters, or if the order could change, name each chapter with a descriptive name (for example, REFERENCE_CHAP.SDML) instead of a numbered title (as in CHAP3.SDML). You can then easily reorder the chapters without renaming the files that contain them.

When you create your book element input files, remember the following:

• Place each book element in a separate file and use one of the following book element tags as the first tag in the file:
  • <APPENDIX>
  • <CHAPTER>
  • <FRONT_MATTER>
  • <GLOSSARY>
  • <PART>
• A book element file should contain only one of the book element tags. For example, two <CHAPTER> tags should not be placed in one file if you want to process that file in a bookbuild.
• Each book element tag must contain a symbol name argument if it will be part of a bookbuild.

A profile is an SDML file that contains a list of all the elements in a book, for example, the front matter, chapters, appendixes, and glossary. The profile can also contain tags that specify where to place a table of contents or index in the book, and tags that specify logical names for files to include. Only the profile tags listed in Table 9-1 can be placed in the profile.

Table 9-1 Profile Tags

Tag	Purpose
<PROFILE>	Signals DECdocument that the file is a profile submitted for a bookbuild. Always the first tag to appear in a profile.
<ELEMENT>(file spec)	Identifies the file specification of an element of the book.
<INCLUDES_FILE>(logical name \file spec)	Defines a logical name for a file included within the previous book element.
<CONTENTS_FILE>+	Specifies the location in the book where a table of contents file should be included.
<INDEX_FILE>+	Specifies the location in the book where an index file should be included.
<COMMENT>+	Used to make comments about the elements of the profile.
<ENDPROFILE>	Ends the profile.

To create a profile, create an SDML file with a name that indicates it is a profile (for example, MYBOOK_PRO.SDML). List in this file all the files that are part of the book, tagging each file name in the list with an <ELEMENT> tag. Place the <PROFILE> tag in the front of the file, and place the <ENDPROFILE> tag at the end of the file. An example of a profile for a book named How to Use a Computer follows:

Example

<PROFILE> <COMMENT>(***Profile for How to Use a Computer***) <ELEMENT>(Mydisk:[Mydirectory]front_matter.sdml) <CONTENTS_FILE> <COMMENT>(***insert table of contents here***) <ELEMENT>(Mydisk:[Mydirectory]intro_chap.sdml) <ELEMENT>(Mydisk:[Mydirectory]applications_chap.sdml) <ELEMENT>(Mydisk:[Mydirectory]tools_chap.sdml) <ELEMENT>(Mydisk:[Mydirectory]conclusion_chap.sdml) <ELEMENT>(Mydisk:[Mydirectory]questions_app.sdml) <INDEX_FILE> <COMMENT>(***insert index here***) <ENDPROFILE>

Each file listed in the example must contain a book element tag and a symbol name for that element. For example, the chapter TOOLS_CHAP.SDML should begin with the following tag:

<CHAPTER>(Using Basic Computer Tools\comp_tools_chap)

9.6.3 Processing a Profile

To build a book, use the following command:

$ DOCUMENT profile-spec doctype destination

Profile-spec is the name of your profile file, with a file type of .SDML.

DECdocument recognizes that it is building a book when it reads the <PROFILE> tag in the profile. Processing the profile creates a cross-reference (XREF) file for the book. For example, if MYBOOK_PRO.SDML is the profile name, typing the following line creates a complete cross-reference file of all the symbol names in the book.

$ DOCUMENT MYBOOK_PRO REPORT LN03

The cross-reference file is called MYBOOK_PRO.XREF, and the final output file (processed for the REPORT doctype) is called MYBOOK_PRO.LN03.

You can use the /MAP qualifier to list all the input files processed by DECdocument in a separate MAP_LIS file, thereby keeping track of the files included and their order. The list starts with the first input file processed and includes any input files specified by <ELEMENT> or <INCLUDE> tags. In the list, files that are included by other files are indented under those files. If you do not specify a file type, the MAP file is given the same name as the profile with a file type of MAP_LIS.

9.7 Generating a Table of Contents

When you use the /CONTENTS qualifier while processing your SDML file, DECdocument generates a table of contents entry for each of the following:

• Appendixes, chapters, glossaries, indexes, parts, and prefaces
• Formal examples, figures, and tables (if specified with a caption or a symbol name argument)
• Numbered heading tags (table of contents entries for the <HEAD5> and <HEAD6> tags are doctype-dependent)
• Tags in the SOFTWARE doctype templates for creating reference documentation: <COMMAND>, <ROUTINE>, <SDML_TAG>, <STATEMENT>, and <FUNCTION>
• SOFTWARE doctype subcommand tags: <SUBCOMMAND> and <SUBCOMMAND_SECTION_HEAD>
• REPORT doctype <SECTION> tags

DECdocument creates a file for the table of contents and names it by adding "_CONTENTS" to the end of the file name on the command line. To create a table of contents along with the output of the file MYREPORT.SDML, type:

$ DOCUMENT myreport REPORT LN03 /CONTENTS

The table of contents generated by this command would be
MYREPORT_CONTENTS.LN03.

If you want the table of contents file to be incorporated into your document, use the <CONTENTS_FILE> tag in your front matter file. The table of contents file is incorporated into the final output file where the <CONTENTS_FILE> tag is placed, not in a separate file.

To ensure that the latest version of the table of contents is incorporated into your file, use the /CONTENTS qualifier whenever you process a file that contains the <CONTENTS_FILE> tag. This guarantees that the table of contents file correctly reflects the latest organization and pagination of your SDML file.

9.8 Processing an Index

Create an index by first placing index tags in your SDML file. Then use the /INDEX qualifier to process the file. (For information on using the index tags in an SDML file, see Chapter 5.)

After creating an index, produce it in one of two ways:

1. Process the SDML files using the /INDEX qualifier. This yields a filename_INDEX.PS, filename_INDEX.LN03, or filename_INDEX.TXT output file that you can print.
2. Place the <INDEX_FILE> tag in your document where you want the index contents to appear. Process the SDML files using the /INDEX qualifier. A separate index file is not created. Since the index is integrated with the output file, print the entire output file to see the index.

A sample command line to process a file and produce its index follows:

$ DOCUMENT myreport REPORT LN03 /INDEX

The index generated by this command would be named
MYREPORT_INDEX.LN03.

To ensure that the latest version of the index is incorporated into your file, use the /INDEX qualifier whenever you process a file that contains the <INDEX_FILE> tag. This guarantees that the index file correctly reflects the latest organization and pagination of your SDML file.

When creating an index, you can use keywords to control whether guide headings are used, how master index entries should be processed, and how index entries should be sorted. For more information, see the description of /INDEX keywords in the DECdocument Command Summary in Using Global Tags.

9.8.1 Processing a Master Index

DECdocument lets you combine the indexes from several documents to create a master index.

A master index differs in two ways from a single-document index:

• Master index entries are referred to by the title of the document where they originated and by page number. Document titles are italicized in these index entries.
• Index entries that were specified using the MASTER attribute are automatically entered into the master index. See Using Global Tags for information on using the MASTER attribute.

Create a master index by performing the following steps:

1. Create individual intermediate index (INX) files using the /INDEX and /KEEP=(INX) qualifiers to the DOCUMENT command. For example:

   $ DOCUMENT mybook.sdml REPORT LN03 /INDEX /KEEP=(INX)

   
   Use this command to create a filename.INX for every chapter or element in your document.

2. Put all the resulting individual filename.INX files into one file called filename.INX_LIST.
   Enter the full name of each INX file on a single line, with no other characters preceding it. You can use the /BOOK_IDENTIFIER qualifier inside the index data file to specify the title of a book. If you do not use this qualifier, the title of the book will be the file name of the INX file.
   The following is a sample of a master index data file. Because the books listed in this file all have numeric file names, the /BOOK_IDENTIFIER qualifier is used to specify more meaningful book titles.

   Example
   

   !Master index data file !Created Dec 1, 1988 !Updated Jan 4, 1989 ! 2041.INX/BOOK_IDENTIFIER="System Generation" 2323.INX/BOOK_IDENTIFIER="Writing I/O Driver" 2050.INX/BOOK_IDENTIFIER="MCR Operations" 2053.INX/BOOK_IDENTIFIER="Program Development" 2054.INX/BOOK_IDENTIFIER="Executive" 2055.INX/BOOK_IDENTIFIER="Task Builder" 2056.INX/BOOK_IDENTIFIER="System Library" 2057.INX/BOOK_IDENTIFIER="Utilities" 2059.INX/BOOK_IDENTIFIER="I/O Drivers" 2176.INX/BOOK_IDENTIFIER="Release Notes"

   
   If you want to generate a master index without book titles, specify a null string to the /BOOK_IDENTIFIER qualifier for all your intermediate index files. For example:

   2041.INX/BOOK_IDENTIFIER=""

3. Process the master index data file, using the /MASTER_INDEX qualifier on the DOCUMENT command line. For example:

   $ DOCUMENT MYMASTER.INX_LIST REPORT LN03 /MASTER_INDEX

   
   DECdocument will produce a printable master index file with the file name MYMASTER.LN03.

You can control how DECdocument processes an index for your document by specifying keywords to the /INDEX qualifier on the DOCUMENT command line. You can control the following:

• Whether alphabetic guide headings are created for each letter group in the index, by using the GUIDE_HEADINGS and NOGUIDE_HEADINGS keyword
• The sorting method used to order entries in an index, by using the SORT keyword

See the DECdocument Command Summary in Using Global Tags for information on using these keywords.

9.9 Processing an Element of a Book

A book element is a major section of a document marked by a tag, such as <CHAPTER>, <FRONT_MATTER>, or <PART>, and is contained in a single SDML file. To process an individual book element and have all its references resolved correctly, you must have previously built the book to create an XREF file. Then, to process only one element, use the /PROFILE qualifier on the command line to name the XREF file and resolve the references. Page numbering begins with 1. For example:

$ DOCUMENT INTRO.SDML MANUAL.GUIDE LN03 /PROFILE=MYBOOK_PRO.XREF

In this example, INTRO.SDML is the file name of the book element you want to process.

Notice that the /PROFILE qualifier is used only to identify the XREF file during an element or subelement build. (For more information on subelement builds, see Section 9.10.) Do not use the /PROFILE qualifier when doing a bookbuild because you specify the profile name as the file to be processed.

When you want to process your whole book again, you need only use the TEX file from your previous bookbuild (unless you have modified your SDML source files). Also, use the /NOTAG_TRANSLATOR qualifier (which prohibits you from using any related qualifiers: /CONDITION, /DIAGNOSTICS, /ELEMENT, /INCLUDE, /MAP, /PROFILE, and /SYMBOLS), because all the references and qualifiers have been resolved for you during the tag translation process when you first built your book. For example:

$ DOCUMENT MYBOOK_PRO.TEX MANUAL.GUIDE LN03 /NOTAG_TRANSLATOR /CONTENTS/INDEX

See Chapter 4 for more information about referring to symbol names.

9.10 Processing a Subelement of a Book

You can divide a long book element into two or more files, called subelements, and process those subelements individually. Cross-references within the subelement are resolved and a new XREF file is created. Page numbering begins with 1.

You need to process a subelement if one of the following conditions exists:

• The subelement is included in an <ELEMENT> tag in a profile.
• The subelement contains references to symbols defined in other files.
• The output file has the same heading level numbers, table, and figure numbers, and so on, as if the file were processed with the entire element.

To process a subelement, use the following command line:

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

In this example, input-file-spec specifies the subelement file to be processed.

/ELEMENT=file-spec identifies the file that includes the subelement.

/PROFILE=profile-spec identifies the XREF file containing the book's symbol names.

Heading level numbers, figure numbers, and table numbers are correct only if they have symbol name arguments.

You do not need to use a subelement build if you are processing a file only to check text content or spelling. In this case, you can process the subelement file as a standalone file.