To use a footnote in a table, use a combination of two tags: <FOOTNOTE> and <FOOTREF>. You need to first define the footnote directly after the <TABLE_SETUP> tag; do not define the footnote within a table row. Then, use the <FOOTREF> tag within any of the table rows to identify the information to be footnoted, as follows:

Example

<table>(Tennis Players) <table_setup>(2\10) <footnote>(1\A left-handed tennis player.) <table_heads>(Females\Males) <table_row>(Chris Evert\Bjorn Borg) <table_row>(Gretchen Magers\Michael Chang) <table_row>(Steffi Graf\John McEnroe<footref>(1)) <endtable>

Output

Table n--n: Tennis Players

Females	Males
Chris Evert	Bjorn Borg
Gretchen Magers	Michael Chang
Steffi Graf	John McEnroe¹

For both printed and Bookreader display, the footnotes used in a table are placed at the bottom of the table.

See Using Global Tags for more information on using footnotes in tables.

2.5.3 Using Change Bars

Use the <MARK> and <ENDMARK> tags to indicate new or changed text in both printed and Bookreader documents. When you use these tags, DECdocument displays a vertical change bar that appears alongside the marked text. Note that change bars are enabled only if you use the <REVISION> tag before the first <MARK> and <ENDMARK> tags.

See Using Global Tags for information on using update pages.

The following example shows how to update a list with change bars depicting the new material.

Example

<REVISION> <P> To dial in to the server: <LIST>(NUMBERED) <LE>Log in to your account. <LE>Press EXIT to bypass the initial menu. <MARK> <LE>Enter SER at the Main Menu. <LE>Enter NCP SET LINE SPEED and the current baud rate of your modem. <P> For example, if your modem is set to 1200 b/s, enter the command NCP SET LINE SPEED 1200. <ENDMARK> <LE>Enter NCP SET LINE STATE ON. <ENDLIST>

2.5.4 Coding Hyphens and Dashes in Text

When two or three consecutive hyphens are used in proportionally spaced text, DECdocument translates them into en dashes and em dashes. (An en dash is slightly longer than a hyphen, and an em dash is slightly longer than an en dash.) This does not occur in monospaced text, such as text in examples. Table 2-4 illustrates how to code a hyphen, an en dash, an em dash, and a minus sign in text. You can produce an em dash in either of two ways.

Table 2-4 How to Code Hyphens and Dashes in Text

Character Produced	Sample of SDML coding	Output
em dash¹	That is -	That is---what I mean to say
em dash¹	That is---what I mean to say	That is---what I mean to say
en dash	1981--1983	1981--1983
hyphen	two-column	two-column
minus sign	<MATH>(a<MINUS>b)	a-b

A part is a unit of information within a document that you want to group together. Parts can consist of:

• A set of chapters or appendixes whose contents are logically related
• A collection of units of logically related information

Use the <PART> and <PART_PAGE> tags to label the start of a major division within your document and to start that new division on a separate page.

The <PART> tag begins a new part and assigns a title to it. The title and symbol name reference arguments are required for a Bookreader book. Use the <PART_PAGE> tag to create a divider page for a part and provide an abstract describing the information in the part.

Example

<PART>(Writing the Book\ref_part) <PART_PAGE> <TITLE>(Writing the Book) <ABSTRACT> This part combines all the chapters describing how to write a book. <ENDABSTRACT> <ENDPART_PAGE>

See Using Global Tags for more information on the <PART> tag.

2.6 Considerations for Bookreader Display

DECdocument provides some Bookreader formatting tags for controlling the format of Bookreader output without affecting the printed output. This section describes the <ONLINE_CHUNK>, <ONLINE_TITLE>, <SET_ONLINE_TOPIC>, and <ONLINE_POPUP> tags.

2.6.1 Dividing Long Sections or Examples into Online Chunks

Chunks are the smallest units of information that Bookreader can access. A topic is a collection of online chunks of information.

DECdocument provides the <ONLINE_CHUNK> tag to break a long segment of text or example into smaller online chunks. DECdocument needs this segmentation to supply desired text formatter page breaks and conserve memory. Use this tag only if you have formatting problems that you cannot solve any other way or if DECdocument runs out of memory and issues this text formatter error.

%TEX-E-NOROOM, Exceeded memory capacity:

You may need to insert several <ONLINE_CHUNK> tags at intervals to correct these memory or formatting problems. Note that the <ONLINE_CHUNK> tag does not affect printed output; the purpose of the tag is to prevent problems in processing Bookreader books.

Thinking visually about a Bookreader book helps its readability. You should break long pieces of text into smaller pieces to create a more user-friendly document both visually and practically. If you leave long portions of text in one topic, the information may be difficult to read because the user will have to keep scrolling. Shorter topics are read and digested more easily.

2.6.2.1 Controlling the Topic Level Bookreader Displays

To help format your Bookreader book into topics, use the <SET_ONLINE_TOPIC> tag. This tag controls which level of heading DECdocument uses to create new topics in Bookreader. If you do not use the <SET_ONLINE_TOPIC> tag, DECdocument considers the following as topics, by default:

• Chapters
• First-level headings
• Appendixes
• Parts
• Templates
• Title pages
• Copyright pages
• Prefaces
• Glossaries
• Formal tables, figures, and examples

Your document might contain second-level and third-level headings that should be broken into separate topics. If your headings need to be broken up into separate topics, use the <SET_ONLINE_TOPIC> tag.

To use the <SET_ONLINE_TOPIC> tag, supply one argument that specifies the level of heading you want to begin topics. That heading and all higher level headings then become topics. For example, specifying <SET_ONLINE_TOPIC>(HEAD2) adds second-level headings to the list of entities DECdocument considers as topics.

If you supply no arguments to <SET_ONLINE_TOPIC>, the effect is the same as not using the tag; the default DECdocument topic levels are used.

You can vary how you use the <SET_ONLINE_TOPIC> tag within your book. For example, you can set the topic level to display all third-level headings for all your chapters, and then you can reset the topic level to display only first-level headings for all your appendixes.

You can specify the online topic level in individual SDML files. The following <SET_ONLINE_TOPIC> tag sets all second-level headings and higher headings as topics in the "Introduction" chapter and all third-level headings and higher in the "Environmental Issues" chapter:

Example

<SET_ONLINE_TOPIC>(head2) <CHAPTER>(Introduction\intro_chap) <SET_ONLINE_TOPIC>(head3) <CHAPTER>(Environmental Issues\envir_chap)

See Part 4 for an example of how to use the <SET_ONLINE_TOPIC> tag within your profile to set online topic levels for an entire book.

See Chapter 7 for information on using the <SET_ONLINE_TOPIC> tag with the [NO]MASTER argument for glossary and messages sections.

2.6.3 Changing Topic Labels

Use the <ONLINE_TITLE> tag if you want to change the topic label that appears directly over the text when a book is displayed by Bookreader. By default, DECdocument automatically displays the topic title from the SDML tag that generated the title. Sometimes, however, your title might comprise two lines for a printed book, which would be too long for a Bookreader book. In that case, you could use the <ONLINE_TITLE> tag to create a new title that would fit into the topic label for online display. The tag produces output only for Bookreader display, so the printed title would stay the same.

In the following example, the <SET_ONLINE_TOPIC>(head3) tag has been specified and the <ONLINE_TITLE> tag is used to override a <HEAD3> title:

Example

<SET_ONLINE_TOPIC>(head3) . . . <ONLINE_TITLE>(Online Documentation) <HEAD3>(Introduction to Online Documentation\intro_online)

The <ONLINE_TITLE> tag overrides only the current title; Bookreader displays the next topic title as usual unless you override it with another <ONLINE_TITLE> tag.

Try to limit your topic label to 40 characters. If you use more than 40 characters, users will have to resize the text window to read the entire title.

Popup windows are most useful for displaying tables, figures, examples, or text segments that are peripheral to the flow of text in the book. Experiment to determine if a popup is a useful and effective way of presenting peripheral information. Too many popups create clutter on the screen and confuse the reader.

Use the <ONLINE_POPUP> tag to specify text that you want to appear as an online popup. An online popup is a separate window in Bookreader that can contain any information such as text, figures, tables, or examples. Online popups are accessed by either a hotspot within the text of your document, or from the table of contents. You can use the <ONLINE_POPUP> tag with any segment of text, such as paragraphs, lists, or notes.

The following example shows how a segment of text would be made into an online popup:

<ONLINE_POPUP>(TEXT) <P> Silly Putty was invented by General Electric engineer James Wright as a by-product of WWII research for a synthetic rubber. <ENDONLINE_POPUP>

The argument you supply to the <ONLINE_POPUP> tag creates the name in the hotspot, as follows:

You cannot use the <ONLINE_POPUP> tag with formal figures, tables, and examples because they are automatically popped up in separate windows for Bookreader books. You can, however, use the <ONLINE_POPUP> tag with informal tables, figures, and examples as described in Section 3.4.

Using the <ONLINE_POPUP> tag does not affect printed display.

DECdocument lets you include tables, figures, and examples in your document. This chapter describes how to code these elements into a document that will be either printed or viewed by Bookreader.

Tables, figures, and examples can be either formal or informal. Formal tables, figures, and examples are numbered, have captions, and are listed in the table of contents. They can be referenced from anywhere in your document. Informal tables, figures, and examples are unnumbered, do not have captions, and are not listed in the table of contents. They cannot be cross-referenced.

DECdocument displays tables, figures, and examples differently in printed documents and Bookreader. For printed documents, you can control where they are printed within the text. For documents displayed by Bookreader, you can control whether they appear in a separate popup window or within the text.

See Section 3.4 for more information on how to properly code tables, figures, and examples to be viewed in a Bookreader book.

3.1 Tables

Use tables in your document to present lengthy and repetitive information in a more clear and tabular form. Tables can effectively illustrate long sections of text. If you make a table formal by using a caption and a symbol name as the arguments, you can refer to it from anywhere in the document.

Four basic tags create a table:

• <TABLE>
• <TABLE_SETUP>
• <TABLE_ROW>
• <ENDTABLE>

Table 3-1 describes these tags and other tags not required to create a table but that you can use to specify special formatting. Table 3-1 lists the tags in the order that they should occur in your SDML file. Use the <TABLE_ROW> tag once for each row in the table.

Table 3-1 Table Tags

Tag	Description
<TABLE>	Creates a table and enables all other table tags. For a formal table, supply a caption argument and a symbol name.
<TABLE_ATTRIBUTES>	Specifies special formatting for the table, such as wide, multipage, or a table that is not to be broken between pages. This tag is ignored if it does not precede the <TABLE_SETUP> tag.
<TABLE_SETUP>	Establishes the number of columns in the table and the width of each column. If excluded, the table will not be created. You do not specify the width of the last column.
<TABLE_HEADS>	Specifies headings for the table columns.
<TABLE_KEY>	Begins a key or a legend for a table.
<ENDTABLE_KEY>	Terminates the <TABLE_KEY> tag.
<TABLE_ROW>	Specifies text for one row of the table. Each argument supplies the text for a column in a row. Can precede or follow table units (grouped sections of the table) as required. Can be repeated throughout the sequence of table tags.
<TABLE_UNIT>	Begins a portion of a table containing rows that you want to group as a logical unit.
<TABLE_UNIT_HEADS>	Specifies headings you want to use in a table unit.
<ENDTABLE_UNIT>	Terminates the <TABLE_UNIT> tag.
<ENDTABLE>	Terminates the <TABLE> tag.

To make a table formal, supply a caption argument to the <TABLE> tag. When you specify a caption, DECdocument automatically assigns a number to the table. When you do not specify a caption, DECdocument does not assign a number to the table. A table without a caption (and, therefore without a number) is called an informal table.

When you specify a symbol name as the second argument, you can use the <REFERENCE> tag to refer to the table's symbol name, thereby always producing the correct table number and caption.

Tables are numbered sequentially throughout each chapter. With the exception of the REPORT doctype ¹, you cannot control table numbering; it is an attribute of the doctype.

3.1.2 Dividing a Table into Units

You can divide any table into units by using all the <TABLE> tags and by adding a few tags to separate the units from one another. Table units are useful when groups of information fit easily into a larger classification.

You create table units by grouping <TABLE_ROW> tags. Table units do not change the number of columns or attributes of a table; they merely group rows.

The <TABLE_UNIT> tag comes after the <TABLE_HEADS> tag or after any <TABLE_ROW> tag. You do not have to use the <TABLE_HEADS> tag to use the <TABLE_UNIT> tag, however. The <TABLE_UNIT> tag sets up the first group and can be followed by the <TABLE_UNIT_HEADS> tag. Terminate a table unit with the <ENDTABLE_UNIT> tag.

If the table units are long and you want to allow them to break across pages, you must use the <TABLE_ROW_BREAK>(first) and <TABLE_ROW_BREAK>(last) tags within the bounds of each <TABLE_UNIT> and <ENDTABLE_UNIT> tag.

You can use the <SPAN> tag to stretch information in a table heading or table row across a specified number of rows. The argument to the <SPAN> tag determines how many rows to span.

Example

<TABLE>(The Fruit Groups\fruit_tab) <TABLE_ATTRIBUTES> <TABLE_SETUP>(2\15) <TABLE_HEADS>(<span>(2)Fruit Groups) <TABLE_UNIT> <TABLE_UNIT_HEADS>(Acid Fruits\Calorie Count) <TABLE_ROW>(Oranges\1 med., 65) <TABLE_ROW>(Grapefruit\Half med., 45) <TABLE_ROW>(Pineapple\1 cup fresh, 75) <TABLE_ROW>(Lemons\Half med., 15) <TABLE_ROW>(Limes\4 T juice, 10) <ENDTABLE_UNIT> <TABLE_UNIT> <TABLE_UNIT_HEADS>(Sub-Acid Fruits\Calorie Count) <TABLE_ROW>(Apples\1 med., 70) <TABLE_ROW>(Pears\1 med., 100) <TABLE_ROW_BREAK>(FIRST) <TABLE_ROW>(Apricots\3 med., 55) <TABLE_ROW>(Cherries\1 cup fresh, 80) <TABLE_ROW_BREAK>(LAST) <TABLE_ROW>(Berries\Half cup, 40) <TABLE_ROW>(Mangoes\1 med., 85) <ENDTABLE_UNIT> <TABLE_UNIT> <TABLE_UNIT_HEADS>(Sweet Fruits\Calorie Count) <TABLE_ROW>(Banana\1 med., 100) <TABLE_ROW>(Date\Quarter cup, 125) <TABLE_ROW>(Fig\1 large, 60) <ENDTABLE_UNIT> <ENDTABLE>

Output

Table n--n: The Fruit Groups

Fruit Groups
Acid Fruits	Calorie Count
Oranges	1 med., 65
Grapefruit	Half med., 45
Pineapple	1 cup fresh, 75
Lemons	Half med., 15
Limes	4 T juice, 10
Sub-Acid Fruits	Calorie Count
Apples	1 med., 70
Pears	1 med., 100
Apricots	3 med., 55
Cherries	1 cup fresh, 80
Berries	Half cup, 40
Mangoes	1 med., 85
Sweet Fruits	Calorie Count
Banana	1 med., 100
Date	Quarter cup, 125
Fig	1 large, 60