DECdocument provides a symbol generator that automatically generates symbol names and adds them to any tag in an SDML file that accepts a symbol name, but does not currently have one specified. The symbol name created consists of a symbol prefix that you supply, with an appended sequential number that DECdocument generates.

The following example shows how to use the symbol generator for a single SDML file. The symbol prefix supplied is "alaska." Note that you need to supply quotes around the symbol prefix to preserve case-sensitivity.

$ DOCUMENT/GENERATE_SYM/PREFIX="alaska" CHAP1.SDML

Before you use the symbol generator, your SDML file may look like this.

<HEAD1>(Introduction\intro) . . . <HEAD2>(Climate) . . . <TABLE>(Birds of Alaska) . . .

After you use the symbol generator, your SDML file would look like this.

<HEAD1>(Introduction\intro) . . . <HEAD2>(Climate\alaska_1) . . . <TABLE>(Birds of Alaska\alaska_2) . . .

DECdocument creates a new version of the SDML file with symbol names added to tags that did not already have symbol names. The original SDML file is not deleted.

The symbol generator checks whether the symbol names that already exist end in a number. If so, it identifies the largest such number in the symbols file and increments the new symbol names from that point. Thus, you can use the symbol generator on any SDML file as many times as necessary.

The symbol generator does not process the file through the tag translator, text formatter, or device converter.

You can use the symbol generator on your profile file¹. You can also use the symbol generator on SDML files that use the <INCLUDE> tag. The symbol generator adds symbols (using the same prefix symbol you supplied on the DOCUMENT command line) to all SDML files included in a profile file, as well as SDML files included with the <INCLUDE> tag.

See the Command Summary in Using Global Tags for more information on using the symbol generator.

An effective index directly impacts the usability of a book. It provides a map to the topics discussed in the book. Whether you include index entries as you write your book, or add them after completing your book, you should value the importance of a comprehensive index.

If you are writing a book to be displayed by Bookreader, an index becomes essential because it is a direct pathway to the information in the book. You can click on an entry in the index to move automatically to the referenced information in the book.

For the printed version of the book, the index displays page numbers that aid the reader in locating particular information in the book.

Producing an index using DECdocument requires two main steps:

1. Label index entries using specific tags
2. Process the index from the command line

This chapter describes the tags involved in creating an index. Section 9.8 describes how to process an index.

5.1 Index Entries in Printed and Bookreader Books

Entries in an index are either topic headings or cross-references. For printed books, a main entry has a certain page number associated with it, such as "Menus, 1-2." For Bookreader books, no page numbers are attached to index entries; rather, the reader clicks on an entry to display the associated text in the Bookreader topic window. Cross-reference entries have no page number for either printed or Bookreader versions, and indicate that the reader should see another entry, such as "Food, See Menus."

An index subentry is indented under the main or cross-reference entry in the index. The following example depicts the output of a printed index, where the text "See Menus" and "High Protein" are both index subentries. (The index for a book displayed by Bookreader would display without page numbers.)

Foods See Menus Menus 1-1 to 1-7 High Protein 1-3, 2-5

In a book displayed by Bookreader, an index entry that contains more than one reference displays all the selections in a separate popup window, as shown in Figure 5-1.

Figure 5-1 Bookreader Index Entry with Two References

Table 5-1 lists the tags used to label index entries for an index.

Table 5-1 Tags Used to Create Index Entries

SDML Tag	Description
<X>	Labels a main index entry. For a printed book, it creates a reference to the page on which the tag appears. For a Bookreader book, it creates a hotspot on the index entry for the reader to click on to display the associated text.
<Y>	Labels a cross-reference with no page reference for a printed book, and no hotspot for a Bookreader book. Use this tag to create cross-reference entries, such as "See" and "See also" entries.
<XSUBENTRY> or <XS>	Labels a subentry inside an <X> or <Y> tag. For a printed book, it creates a reference to the page on which the tag appears. For a Bookreader book, it creates a hotspot on the index entry with no page reference. You can abbreviate this tag as <XS>.

The argument for the <X> or <Y> tag supplies the text for the main entry and subentries in the index. The text used in this argument is placed in the index exactly as entered.

Both the <X> and <Y> tags can have subentries (also called subheadings or modifications), which are index entries indented under either a main entry or a cross-reference. You can use up to three levels of subentries in an index.

The following example shows part of an SDML file that contains <X>, <Y>, and <XSUBENTRY> tags.

Example

<head1>(Usage of Official Vehicles\vehicles) <X>(Vehicles<XSUBENTRY>usage of) <Y>(CORP-AUTO report<XSUBENTRY>See Vehicles) <p> Official vehicle usage is listed in a separate report CORP-AUTO-1439u2. This report is organized as in the following outline.

If these tags occurred on page 3--1 of a printed book, they would create the following index entry. For a Bookreader book, the output would display without page numbers.

Output

CORP-AUTO report See Vehicles Vehicles usage of, 3-1

See the index in this manual for an example of an index produced using DECdocument.

5.3 Correct Placement of Index Tags

For both printed and Bookreader books, the most important aspect of using the index tags is placing them correctly in your source files. Always code index entries within the section, element, or online chunk of information you want the entry to point to. For example, coding an index entry to a figure after the <ENDFIGURE> tag causes the online entry to point to the section or text after the figure, not to the figure. In the printed version, the index entry might also be "off by one" if a page break immediately follows the figure.

Follow the rules in this section to ensure a correct and effective index.

5.3.1 Using Index Tags in Text

The best way to index a section is to place an index tag immediately after the heading tag. If you code an index tag before the heading, the index entry will refer to the previous section.

Example

<HEAD1>(Section One\sec_one) <X>(Index entry for Section One) <P> Make sure that you place your index entry after the heading tag that it should refer to. <HEAD1>(Section Two\sec_two) <X>(Index entry for Section Two) . . .

Use the <EMPHASIS> tag to bold or italicize an index entry. See Chapter 4 for more information on using the <EMPHASIS> tags.

The following example shows how to italicize the entry "Language Tools":

Example

<X>(<emphasis>(Language Tools))

5.3.2 Using Index Tags in Tables

You can code index entries almost anywhere in your tables. The index tags can fall between and within table rows, after the <TABLE_SETUP> tag, and after the <TABLE_HEADS> tag.

However, for a Bookreader book, make sure that you do not code an index tag directly after the <TABLE> tag otherwise the index entries will point to the previous text instead of the popup table.

For example, the following code produces index entries that point to the popup table:

Example

<TABLE>(Table One\tab_one) <TABLE_SETUP>(2\2) <X>(Index entry) <TABLE_HEADS>(One\Two) <X>(Index entry) <TABLE_ROW>(Three<X>(Index entry)\Four) <X>(Index entry) <ENDTABLE>

5.3.3 Using Index Tags in Figures and Examples

In figures and examples, code your index tags before the <ENDFIGURE> or <ENDEXAMPLE> tag. Do not place index entries between <CODE_EXAMPLE> and <ENDCODE_EXAMPLE> tags. Doing so may interfere with the formatting of the example.

The following example shows that correct placement of the index tag is before the <ENDFIGURE> and <ENDEXAMPLE> tags, and after the <ENDCODE_EXAMPLE> tag:

Example

<FIGURE>(Figure One\one) <FIGURE_FILE>(ps\fig.ps\8) <FIGURE_FILE>(bookreader\fig.decw$bookfig\12) <FIGURE_FILE>(...) . . . <X>(Index entry) <ENDFIGURE> . . . <EXAMPLE>(Example One\one) <CODE_EXAMPLE> <S>($) <U>(input) . . . <ENDCODE_EXAMPLE> <X>(Index entry) <ENDEXAMPLE>

For Bookreader books, if you place any index entries to informal tables, figures, or examples within an online popup sequence, and the reader clicks on that index entry, Bookreader will display the popup window alone. Without additional context, these index entries could be useless to the reader. If you want to reference text in addition to the popup, place an index entry within the text as well as within the popup.

5.4 Controlling Index Attributes

You can use various attributes to control the sorting and formatting of individual index entries. (DECdocument ignores certain index attributes for books displayed by Bookreader.)

The index tag attributes include:

• Specifying page ranges using the BEGIN and END attributes (works only for a printed book)
• Bolding and italicizing page numbers using the BOLD and ITALIC attributes (works only for a printed book)
• Appending information to a page number using the XAPPEND attribute (works only for a printed book)
• Controlling the sorting of individual index entries using the XSORT attribute (works for both a printed and Bookreader book)

See Using Global Tags for information on using these index tag attributes.

5.5 Specifying Individual and Master Index Entries

An individual index is an index for a single document or book. A master index is an index for an entire documentation set. You can specify whether entries will appear in an individual index, a master index, or both.

To control whether entries appear in an individual index, a master index, or both, assign specific attributes to the index tag argument. Then, process your SDML file using arguments on the command line. The attributes you can use as arguments to the index tag are the following:

• MASTER
• NOMASTER
• BOTH

See Using Global Tags for more information on the index tag arguments. See the DECdocument Command Summary in Using Global Tags for information on how to use the command line to control the output of the index entries.

You can only create a master index for printed books. Any index tag attributes relating to a master index are ignored when you process books for Bookreader display.

This chapter describes how to create the front matter file for a document. The front matter file usually consists of four components:

• Title page
• Copyright page
• Table of contents
• Preface

Table 6-1 lists the tags to create the front matter of a document. The tags are listed in the order that you use them. See Using Global Tags for more information on these tags.

Table 6-1 Tags Used to Create Front Matter

SDML Tag	Description
<FRONT_MATTER>	Labels the beginning of the front matter of a document. This tag requires a symbol name argument if the front matter will be part of a bookbuild.
<TITLE_PAGE>	Labels the beginning of the title page.
<TITLE>	Labels the title of the document.
<ORDER_NUMBER>	Labels the order number of a printed document. This tag has no functionality in books displayed by Bookreader.
<ABSTRACT>	Labels the beginning of the abstract that contains a summary of the document.
<ENDABSTRACT>	Labels the end of the abstract.
<REVISION_INFO>	Labels a section on a title page that tells what previous books have been superseded by the current one.
<ENDTITLE_PAGE>	Labels the end of the title page.
<COPYRIGHT_PAGE>	Labels where the copyright page will be included in a document.
<PRINT_DATE>	Inserts a print date line on the copyright page.
<COPYRIGHT_DATE>	Inserts a copyright date line on the copyright page along with other system-specific copyright information.
<ENDCOPYRIGHT_PAGE>	Labels the end of the copyright page.
<CONTENTS_FILE>	Specifies where the table of contents will be included in a printed document. The table of contents is required in an online document, and always appears in a separate window on Bookreader. You can place the <CONTENTS_FILE> tag in either the front matter or the profile file.
<PREFACE>	Labels the beginning of the preface.
<PREFACE_SECTION>	Creates a major section in the preface.
<ENDPREFACE>	Labels the end of the preface.
<ENDFRONT_MATTER>	Labels the end of the front matter.

When you create front matter for a printed document, the only required tags are the <FRONT_MATTER> and <ENDFRONT_MATTER> tags, and whatever optional front matter component you choose to include.

The front matter for a Bookreader book, however, requires not only the <FRONT_MATTER> and <ENDFRONT_MATTER> tags, but the following three tags:

• <TITLE_PAGE>
• <TITLE>
• <ENDTITLE_PAGE>

Example 6-1 shows a sample front matter file.

Example 6-1 Sample Front Matter File

<FRONT_MATTER>(front) <TITLE_PAGE> <TITLE>(User's Manual) <ORDER_NUMBER>(11-222-333) <ABSTRACT> . . . <ENDABSTRACT> <ENDTITLE_PAGE> <COPYRIGHT_PAGE> <PRINT_DATE>(August 1988) <COPYRIGHT_DATE>(1988) <ENDCOPYRIGHT_PAGE> <CONTENTS_FILE> <PREFACE>(11) <PREFACE_SECTION>(Intended Audience\audience_sym) . . <PREFACE_SECTION>(New and Changed Features\features_sym) . . <ENDPREFACE> <ENDFRONT_MATTER>

You can also combine, in one main front matter file, separate SDML files that contain the various front matter components, as shown in Example 6-2.

Example 6-2 Including Separate Files in a Front Matter File

<FRONT_MATTER>(front) <INCLUDE>(TITLEPAGE.SDML) <INCLUDE>(COPYRIGHT_PAGE.SDML) <CONTENTS_FILE> <INCLUDE>(PREFACE.SDML) <ENDFRONT_MATTER>

6.2.1 Title Page

The front matter for your Bookreader book must contain a title page with the <TITLE_PAGE> and <ENDTITLE_PAGE> tags.

Do not place any tags that generate text before the <TITLE_PAGE> tag, such as the <CONTENTS_FILE> tag or <P> tags with accompanying text. If you code any text before the <TITLE_PAGE> tag, the online bookbuild will fail, giving you the following message:

%DVC-E-PAGECOORDLOST, PAGE COORDINATION LOST TeXpage = 1, ChunkID = 2 %DVC-E-BOOKABORT, aborting run -- book TEST_PRO.SDML DECW$BOOK not created -DVC-I-INPUTFILE, input file is:

Example 6-3 shows the title page component of the front matter.

Example 6-3 Title Page Component of Front Matter

<TITLE_PAGE> <TITLE>(User's Manual) <ORDER_NUMBER>(11-222-333) <ABSTRACT> This document contains information on ... <ENDABSTRACT> <REVISION_INFO>(Revision/Update Information:\This is a new manual.) <ENDTITLE_PAGE>

You must use the <TITLE> tag in the front matter of your Bookreader book.

The <ORDER_NUMBER> tag used on a title page has no functionality for books displayed by Bookreader.

The abstract component is not required for printed or Bookreader books. If you include an abstract, enter text between the <ABSTRACT> and <ENDABSTRACT> tags.

The revision component is not required for printed or Bookreader books. The revision component provides information on what previous books have been superseded by the current one.