| Previous | Contents | Index |
DECdocument automatically creates popups for all formal tables, figures, and examples, regardless of size. Therefore, do not use the <ONLINE_POPUP> tag for formal tables, figures, and examples. Remember that in Bookreader, you can expand the window size both vertically and horizontally or you can scroll to view the whole window. DECdocument attempts to create a large enough window to contain all the popup information without the user needing to resize the window. If the popup information cannot fit in the standard size popup window, DECdocument will create a window that can be expanded.
For your table, figure, or example to be viewed properly by Bookreader, use the symbol-name argument and at least one reference (using the <REFERENCE> tag). Using symbol names along with the <REFERENCE> tag is necessary in Bookreader books because no hotspot can be created without a specific text reference. Without a hotspot, you will only be able to view tables, figures, and examples through the table of contents if you know they exist. See Chapter 4 for information on using the <REFERENCE> tag and symbol name arguments.
When you use the <REFERENCE> tag to reference a formal table, figure, or example, the only words that will appear in the actual hotspot are the words in the argument to the <REFERENCE> tag. For example, if you use the \VALUE qualifier in the <REFERENCE> tag when referring to a hotspot, and you type in an identifying reference before the tag, the word that you used as the identifying reference will appear outside of the hotspot. (See Section 4.3 for more information on using the \VALUE qualifier.)
To include an illustration to be viewed by Bookreader, use the following line within a formal or informal figure:
<FIGURE_FILE>(BOOKREADER\figurename.brf\nn)
|
BOOKREADER indicates the output destination, figurename.brf represents the corresponding input figure file, and nn represents the vertical pica size of the figure.
A common practice in documentation, called cross-referencing, is to refer readers to other sections or chapters within either the current document or other related documents. DECdocument helps to automate this process of cross-referencing by providing the ability to refer to a symbol name that is attached to an SDML tag, rather than hard coding the specific text or graphic element's number and title.
This chapter describes how to assign symbol names to certain elements and refer to those elements using the <REFERENCE> tag. It also describes the <HOTSPOT> tag and the symbol generator that automatically generates and includes symbol name arguments for any SDML file.
This chapter also describes special considerations for books to be
viewed by Bookreader (for example, certain tags requiring symbol name
arguments).
4.1 When to Use Symbol Names to Cross Reference
The advantage to using symbol names when cross-referencing is that although the structure of your document may change, your references are tied to a unique symbol name instead of to hard-coded text or an element number. For example, you can assign a symbol name to Table 1--1 in your document and cross-reference that table by referring to its symbol name. If you then modify Table 1--1 to be the second table in your document, its number would become Table 1--2. The next time you process your files, DECdocument automatically replaces all the references of that table with the number, Table 1--2. If you had hard coded the actual table number, Table 1--1, throughout your document, you would need to manually replace every occurrence with the new table number.
If you process your book for Bookreader, you must use symbol names for the following tags or DECdocument will return an error-level message and your bookbuild will not complete:
For books displayed by Bookreader, you also need to use symbol names with the <REFERENCE> tag for cross-references. A cross-reference in a Bookreader book appears as a hotspot. You can simply click on the hotspot and Bookreader displays the referenced information in a separate popup window. If the reference is a section within the book, Bookreader will automatically display that section in the main topic window. See Section 4.6 for information on using the <HOTSPOT> tag to create hotspots for any piece of text in your Bookreader book.
You should use the symbol name argument for formal tables, figures, and
examples along with an introductory sentence using the
<REFERENCE> tag. DECdocument automatically makes formal tables,
figures, and examples into popups that are accessible from a hotspot
created by the <REFERENCE> tag. Without the hotspot, the formal
table, figure, or example is only accessible from the table of
contents. If you do not use the symbol name argument, DECdocument
will issue a warning-level message.
4.2 Creating Symbol Names
A symbol name cannot exceed 31 characters, and can contain any of the following characters in any order:
The following list shows all tags that accept symbols names for both printed and Bookreader books. (See Section 4.1 for a listing of the tags that require symbol names for Bookreader books.)
To set up a cross-reference, specify a symbol name as an argument to one of the tags that accepts symbols. For example, to create a symbol name for an example with the caption VAXcluster Multi-File Summary, you could put the following tag into your SDML file:
<EXAMPLE>(VAXcluster Multi-File Summary\multi_file_exam)
|
The symbol name assigned to each tag must be unique or DECdocument issues a warning message:
%TAG-W-DUPSYMBOL, tag <SYMBOL_TABLE_ENTRY>, line 6, file
NODE$DUA1:[ANDERSON]FILE.SDML;
The symbol multi_file_exam is being defined twice.
The earlier definition is replaced by the new definition
|
To create unique and meaningful symbol names, you can end the name with an abbreviation for the type of text element for which you are creating a symbol. For example, a symbol name for a table might be "american_kings_tab," or for a chapter, "american_kings_chap." This convention lets you identify different types of symbol names as you edit a file.
You should frequently process your SDML files to ensure that
DECdocument refers to each symbol correctly. See Chapter 9 for
more information on bookbuilding and processing files.
4.3 Referring to Symbol Names
You can refer to symbol names anywhere in the document with the <REFERENCE> tag. For example, refer to the symbol name multi_file_exam as follows:
<REFERENCE>(multi_file_exam)
|
In your source file, the reference to a symbol name can precede or follow the tag that defines the symbol name. Therefore, the following line,
<Define_Symbol>(plan_tab\The 43rd Project Plan)
|
<p>The series of steps are identified in <reference>(plan_tab).
|
When DECdocument processes the <REFERENCE> tag, it substitutes information defined by the symbol name. You can control how the information will be displayed by using arguments to the <REFERENCE> tag.
The first argument to the <REFERENCE> tag is always the symbol name you want to refer to. By default, DECdocument automatically assigns a keyword, such as "Chapter," and a symbol value for each symbol name. For example:
<reference>(ref_chap)
|
Chapter 4
|
You can use a second argument to specify that you want either a portion of your reference or the entire reference placed in your document. For example, you might want to refer to a chapter by title only rather than by number.
Optional second arguments to <REFERENCE> include the following:
For example, if "Running the Program" is the title of the fourth chapter, you might use the \FULL argument to include that title in your reference.
<reference>(ref_chap\FULL)
|
Chapter 4, Running the Program
|
For a Bookreader book, make sure that the <REFERENCE> tag argument contains exactly the information that you want to appear as a hotspot. For example, coding a <REFERENCE> tag with the \VALUE qualifier, as follows, causes the "1--1" to be outlined, but not the entire "Figure 1--1."
Example
<P>
The automobile was invented by German Karl Benz,
who designed the first internal-combustion car,
the Benz, a three-wheeler (see Figure <REFERENCE>(car_fig\VALUE)),
in 1885.
|
Output
The automobile was invented by German Karl Benz, who designed the first internal-combustion car, the Benz, a three-wheeler (see Figure [1-1]), in 1885.
To outline the entire "Figure 1--1," code the <REFERENCE> tag without the \VALUE qualifier, as follows:
Example
<P>
The automobile was invented by German Karl Benz,
who designed the first internal-combustion car,
the Benz, a three-wheeler (see <REFERENCE>(car_fig)),
in 1885.
|
Output
The automobile was invented by German Karl Benz, who designed the first internal-combustion car, the Benz, a three-wheeler (see [Figure 1-1]), in 1885.
Table 4-1 summarizes the default output for each type of text or book element. Each book element requires a symbol name if the book will be processed through a bookbuild. See Section 9.6 for more information on bookbuilds.
| Second Argument to<REFERENCE> | ||||
|---|---|---|---|---|
| Text Element | (default) | VALUE | TEXT | FULL |
| BOOK TITLE | The title argument specified in <DEFINE_BOOK_NAME>. | |||
| EXAMPLE | "Example" number | number | caption | "Example" number, caption |
| FIGURE | "Figure" number | number | caption | "Figure" number, caption |
| HEADn | "Section" number | number | caption | "Section" number, caption |
| TABLE | "Table" number | number | caption | "Table" number, caption |
| TEXT STRING | The text-string argument specified in <DEFINE_SYMBOL>. | |||
| Book Elements | (default) | VALUE | TEXT | FULL |
| APPENDIX | "Appendix" letter | letter | title | "Appendix" letter, title |
| CHAPTER | "Chapter" number | number | title | "Chapter" number, title |
| PART | "Part" number | number | title | "Part" number, title |
| SECTION | "Section" number | number | title | "Section" number, title |
You can place all <DEFINE_SYMBOL> and <DEFINE_BOOK_NAME> tags in one symbol definitions file. To refer to the symbol names stored in this file, specify the name of the symbol definitions file by using the /SYMBOLS qualifier on the DOCUMENT command line.
For example, a symbol definitions file named INTRO_BOOK_SYMS.SDML might contain the following symbol names:
<define_symbol>(PROGRAM_NAME\Matrix Maker)
<define_symbol>(PROGRAM_VERSION\3.2)
|
When you process a file that refers to either of these symbols, specify the name of the symbol definitions file on the DOCUMENT command line by typing the following:
$ DOCUMENT filename doctype destination /SYMBOLS=INTRO_BOOK_SYMS
|
The /SYMBOLS qualifier assumes a file type of .SDML.
You can only use the /SYMBOLS qualifier on the command line once, and can only specify one symbols definitions file. If you use the qualifier twice, DECdocument ignores the first use of the /SYMBOLS qualifier and uses only the second. If you have multiple symbols files that you want to include, you can use the <INCLUDE> tag in the first symbols file to pull in all the other symbols files as shown in Example 4-1. You can include as many files as you want. Then, specify the first symbols file using the /SYMBOLS qualifier on the command line.
| Example 4-1 FIRST_SYMBOLS_FILE.SDML |
|---|
.
.
.
all the definitions in the first symbols file
.
.
.
<include>(SECOND_SYMBOLS_FILE.SDML)
<include>(THIRD_SYMBOLS_FILE.SDML)
<include>(FOURTH_SYMBOLS_FILE.SDML)
|
During a bookbuild, DECdocument automatically creates a cross-reference file that contains a list of the symbol names used in one or more files. When you process a file that contains symbol names, DECdocument places those symbol names in the cross-reference file. DECdocument uses this file to resolve all symbol name references.
When you process a group of files through a bookbuild, or an element of a book through an element build, DECdocument again creates a cross-reference file and uses it to resolve all references. Because the bookbuilding process requires that symbol names be stored for later use, DECdocument copies the cross-reference file into the directory that contains the profile¹ used to perform the bookbuild. DECdocument names this file with the profile name and gives it the file type of XREF. See Section 9.9 and Section 9.10 for more information on using the filename.XREF file to process subelements and elements.
You cannot read the filename.XREF file; do not attempt to edit it. Also, do not delete it; if it is deleted, you must rebuild the book before any subsequent element builds can be done. |
¹ See Chapter 9 for more information on the profile file and bookbuilding. |
4.6 Creating Hotspots for Any Piece of Text
In addition to using the <REFERENCE> tag with symbol names to create printed cross-references and online hotspots, you can use the <HOTSPOT> tag to create these references. For Bookreader books, this tag creates a working hotspot. For printed books, this tag generates the text you specify followed by a reference (in parentheses) to the section, chapter, or table, and so on.
The <HOTSPOT> tag accepts two arguments: a required symbol name and an optional text argument. The symbol name argument specifies the symbol name defined by the text element that you want to use as the cross-reference. The optional text argument allows you to specify text that will appear as the actual hotspot for books displayed by Bookreader and as regular text for printed output. If you do not specify the optional text argument, the title of the text element you are referring to is used as both the hotspot for Bookreader display and as the cross-reference for printed output. For printed output, the text element keyword plus the symbol value (for example, Section 1.1) of the text you are referring to will always appear in parentheses after the cross-reference.
The following example shows how to use the <HOTSPOT> tag with the optional text argument for books displayed by Bookreader:
Bookreader Example
<HEAD1>(Introduction\intro)
<P>
The section <HOTSPOT>(cat_section\cats) discusses cats.
.
.
.
<HEAD1>(All About Cats\cat_section)
|
Output
The section []cats discusses cats.
The following example shows how to use the <HOTSPOT> tag without the optional text argument for books displayed by Bookreader:
Bookreader Example
<HEAD1>(Introduction\intro)
<P>
The section <HOTSPOT>(cat_section) discusses cats.
.
.
.
<HEAD1>(All About Cats\cat_section)
|
Output
The section []All About Cats discusses cats.
The following example shows how to use the <HOTSPOT> tag with the optional text argument for printed books:
Printed Example
<HEAD1>(Introduction\intro)
<P>
The section <HOTSPOT>(cat_section\cats) discusses cats.
.
.
.
<HEAD1>(All About Cats\cat_section)
|
Output
The section (see Section n.n) discusses cats.
The following example shows how to use the <HOTSPOT> tag without the optional text argument for printed books:
Printed Example
<HEAD1>(Introduction\intro)
<P>
The section <HOTSPOT>(cat_section) discusses cats.
.
.
.
<HEAD1>(All About Cats\cat_section)
|
Output
The section All About Cats (see Section n.n) discusses cats.
See Using Doctypes and Related Tags for more information on the <HOTSPOT> tag.
| Previous | Next | Contents | Index |