Labels a permissible page break within a monospaced example (created with the <CODE_EXAMPLE>, <DISPLAY>, <INTERACTIVE>, or <LINE_ART> tags).

Format

<VALID_BREAK>

ARGUMENTS

None.

related tags

• <CODE_EXAMPLE>
• <DISPLAY>---in the SOFTWARE doctype
• <INTERACTIVE>
• <LINE_ART>

restrictions

Valid only in the context of monospaced examples created with the <CODE_EXAMPLE>, <DISPLAY> (in the SOFTWARE doctype), <INTERACTIVE>, or <LINE_ART> tags.

DESCRIPTION

The <VALID_BREAK> tag labels a permissible page break within a monospaced example (created with the <CODE_EXAMPLE>, <DISPLAY>, <INTERACTIVE>, or <LINE_ART> tags).

The text formatter attempts to keep an example together on a single page. If there is not enough room for an example on the current page, the text formatter chooses page breaks using blank lines in the example as valid places to break. If your example contains no blank lines, or if you want to specify better breaking points, you can use the <VALID_BREAK> tag to specify the places that are acceptable page breaks.

This tag has no effect for Bookreader output.

Example

The following example shows how to use the <VALID_BREAK> tag.

<INTERACTIVE>
<S>($) 
<U>(@SYS$SYSTEM:SHUTDOWN)
 
        
<S>(SHUTDOWN -- Perform an Orderly System Shutdown)
<ELLIPSIS>
<S>(CENTRAL, PRINTER, TAPES, DISKS, DEVICES, CARDS, NETWORK, OPER1)
<S>(OPER3, OPER4, OPER5, OPER6, OPER7, OPER8, OPER9, OPER10, OPER11,)
<S>(OPER12)
<VALID_BREAK>
 
<S>(%SHUTDOWN-I-DISLOGINS, Interactive logins will now be disabled.)
<S>(%SET-I-INTSET, login interactive limit = 0 current interactive value = 17)
<S>(%SHUTDOWN-I-SHUTNET, The DECnet network will now be shut down.)
<S>(%SHUTDOWN-I-STOPQUEMAN, The queue manager will now be stopped.)
<ENDINTERACTIVE>

Marks a permissible place that a first-level table row, not a nested table row, may be broken across pages.

Format

<VALID_TABLE_ROW_BREAK>

ARGUMENTS

None.

related tags

• <NESTED_TABLE_BREAK>

restrictions

Valid only in the context of a <TABLE> tag.

Valid only in the last column of a 2- or 3-column, first-level table; you cannot specify this tag in a nested table.

DESCRIPTION

The <VALID_TABLE_ROW_BREAK> tag marks a permissible place that a first-level table row, not a nested table row, may be broken across pages. If you do not use the <VALID_TABLE_ROW_BREAK> tag inside a long table row, the text formatter tries to keep all the text on the same page of output and might issue an error message. In extreme cases, the text formatter could run out of memory trying to process the table row and terminate processing.

This tag has no effect for Bookreader output.

Example

The following example shows how to use the <VALID_TABLE_ROW_BREAK> tag in a table with a long table row.

<TABLE>
<TABLE_ATTRIBUTES>(MULTIPAGE) 
<TABLE_SETUP>(2\9) 
<TABLE_ROW>(Item\Text that goes on for several paragraphs. 
<VALID_TABLE_ROW_BREAK>
Text that is still inside the first table row. 
<P>
<VALID_TABLE_ROW_BREAK>
The last paragraphs for this table row.) 
<ENDTABLE>

Labels a program variable or number you want to typographically distinguish.

Format

<VARIABLE> (variable name)

ARGUMENTS

variable name

Specifies the name of the variable to be typographically distinguished.

related tags

• <KEYWORD>

---

DESCRIPTION

The <VARIABLE> tag labels a program variable or number you want to typographically distinguish. Use this tag to format a variable consistently throughout a document and a document set.

---

Example

The following example shows how to use the <VARIABLE> tag.

<P>At this point in the processing, <VARIABLE>(VERSION_NUMBER) has the value of 2.

This example produces the following output:

At this point in the processing, VERSION_NUMBER has the value of 2.

---

<VBAR>

Specifies a vertical bar anywhere in your file. You must use this tag, however, to specify a vertical bar in an argument to a tag.

---

Format

<VBAR>

---

ARGUMENTS

None.

related tags

• The following tags label other characters that you must tag when they occur in an argument to a tag:
  • <AMPERSAND>
  • <BACKSLASH>
  • <CPAREN>
  • <OPAREN>

restrictions

Valid only in an argument to a tag.

DESCRIPTION

The <VBAR> tag specifies a vertical bar anywhere in your file. You must use this tag, however, to specify a vertical bar in an argument to a tag. If you use a literal vertical bar within an argument to a tag, the tag translator reads the vertical bar as beginning a section of text it should treat literally. This is because the tag translator uses a vertical bar (|) to begin a quoted string. The vertical bar may prevent the tag translator from correctly evaluating a tag, thus causing an error in your output.

Example

The following example shows how to use the <VBAR> tag.

<SUBHEAD1>(Labeling the Vertical Bar (<VBAR>) Within Your 
Code\label_vbar) 
<P>To pass a vertical bar (|) in an argument to a tag through 
to your output, ...

This example produces the following output:

Labeling the Vertical Bar (|) Within Your Code

To pass a vertical bar (|) in an argument to a tag through to your output, ...

Creates a main index entry. For a printed book, the <X> tag creates a reference to the page on which this tag appears. For a book you create for Bookreader, the <X> tag creates a hotspot on the index entry that you click on to display the associated text.

Format

<X> (index entry[\attribute])

ARGUMENTS

index entry

Specifies the index entry you want to appear in the index. The capitalization you use is the capitalization that appears in the index.

attribute

This is an optional argument. It specifies the attributes that control the sorting and formatting of the index entry. Each attribute must be a separate argument.

Attribute	Function
<XAPPEND>(string)	Appends the specified string to the page reference in the index. You must leave a space between the left parenthesis of the <XAPPEND> tag's argument and the word you want to append, in order to have a space in the output between the page number and the appended word. In page-range references, append the string to the <X>(...\END) tag, not to the <X>(...\BEGIN) tag. The <XAPPEND> tag has no effect for Bookreader output.
BEGIN	Begins a page-range reference. When you use this attribute, you must pair it with a following <X> tag that has identical text (including capitalization) and the END attribute. BEGIN and END have no effect for Bookreader output.
BOLD	Causes the page reference number to appear in boldface. This is distinct from any boldfacing that appears in the text of the index entry itself. Use the <EMPHASIS> tag if you want to bold the index entry. BOLD has no effect for Bookreader output.
BOTH	Specifies an index entry that you want to appear in both a single-document and a master index. BOTH has no effect for Bookreader output.
END	Ends a page-range reference. When you use this attribute, you must pair it with a previous <X> tag that has identical text (including capitalization) and the BEGIN attribute. BEGIN and END have no effect for Bookreader output.
ITALIC	Causes page reference numbers to appear in italics in your index entry. If you specify both BOLD and ITALIC, the entry is output in bold italics. Use the <EMPHASIS> tag if you want to bold the index entry. ITALIC has no effect for Bookreader output.
MASTER	Specifies that an index entry appear only in a master index. A master index is an index generated by specifying /MASTER on the DOCUMENT command line. By default, the entries appear only in a single-document index. Using /MASTER allows you to specify different entries for a single book's index and for the master index of the document set. MASTER has no effect for Bookreader output.
NOMASTER	Specifies that an index entry appear only in a single-document index and not in a master index. NOMASTER has no effect for Bookreader output.
<XSORT>(string)	Uses the specified string as the sort key when placing this entry in the index, forcing the entry to sort in a place different from where it would by default.

related tags

• <XS>
• <XSUBENTRY>
• <Y>

restrictions

Invalid in informal code examples. Using this tag in a code example interferes with the formatting of the example.

In tables, place <X> tags directly next to the items you want to index (within the arguments to the <TABLE_ROW> tag, so that the page references will be correct if the table breaks across pages), or after the <TABLE_HEADS> or <TABLE_SETUP> tags.

In tables you create for Bookreader, place <X> tags after <TABLE_HEADS>, <TABLE_ROW>, or <TABLE_SETUP> tags so that the index entry points to the table pop-up window.

If you want an index entry to point to a small section of text, you must place the index tag within the section of text, so that the index entry refers to the correct page.

If you want an index entry to point to a large section of text denoted by a heading, you must place the index tag after the relevant <HEADN> tag, not before it, so that the index entry refers to the correct page.

DESCRIPTION

The <X> tag creates a main index entry in either a single-document or a master index. A master index is an index generated by specifying the /MASTER_INDEX qualifier on the DOCUMENT command line; a single-document index is an index generated by specifying /INDEX on the command line.

For a printed book, the <X> tag creates a reference to the page on which this tag appears. For a book you create for Bookreader, the <X> tag creates a hotspot on the index entry that you click on to display the associated text. The entry is composed of the main entry and optional subentries, which you specify in the first argument to the tag using the <XSUBENTRY> tag. See the <XSUBENTRY> tag description for more information.

Code your index entries within the information you want the entry to point to, which ensures that the index will point to the correct page or section of information.

You can control how the index entry is sorted and how it appears by specifying particular keywords as attribute arguments.

For example, the <XAPPEND> attribute is useful when appending text to the end of a page reference, as when referring to an example (5-4ex) or to a table (9-8tab). You can also use the <XAPPEND> attribute to append "ff" or "passim", for example, to the page number. The <XAPPEND> attribute has no effect for Bookreader output.

The appended string is boldfaced or italicized if its page reference is boldfaced or italicized. You can use the BOLD and ITALIC attributes together. BOLD and ITALIC have no effect for Bookreader output.

You can create an index entry for several inclusive pages by using the BEGIN and END attribute. When using a BEGIN and END pair, you must be certain that the index entries are identical and that any other attributes you specify are the same for each entry, as well. The BEGIN and END pair have no effect for Bookreader output.

If you have an index entry for which you want to control the sorting, use the <XSORT> attribute. For example, you can sort the word "Cat" under the "--D--" entries. If you want to control the sorting of nonalphabetic characters, use the /INDEX=SORT= qualifier on the DOCUMENT command line. See Command Summary and Processing Messages for more information on the command line.

You can specify that an index entry appear in a master index by using the MASTER attribute. No entry marked with the MASTER attribute appears in the single-document index.

You can specify an index entry that you do not want to appear in a master index by using the NOMASTER attribute. This attribute limits the entry to appear only in a single-document index.

You can specify an index entry that you want to appear in both a single-document and a master index by using the BOTH attribute.

If you do not specify an attribute, the entry appears only in the single-document index unless you override this default with the following DOCUMENT command line qualifiers:

\INDEX=OVERRIDE_MASTER	Creates a single-document index containing both master and single-document index entries.
\MASTER_INDEX=OVERRIDE_MASTER	Creates a master index containing both master and single-document index entries.

An index entry that you label with the NOMASTER attribute is included only in the single-document index regardless of which "OVERRIDE" qualifier you use on the command line.

An index entry that you label with the BOTH attribute is included in both the single-document and the master index regardless of which "OVERRIDE" qualifier you use on the command line.

Table 1-5 summarizes how the <X> tag attributes and the command line indexing options for a single-document and a master index interact. An "X" specifies that an index entry with the listed tag attribute runs with the command line option to produce an index.

Table 1-5 Interaction of<X> Tag Arguments and Command Line Indexing Options

	Command Line Options
	For a Single-document Index		For a Master Index
<X> Tag Attributes	/INDEX	/INDEX=OVERRIDE	/MASTER	/MASTER=OVERRIDE
none	X	X		X
BOTH	X	X	X	X
MASTER		X	X	X
NOMASTER	X	X

For example, if you want to specify that certain index entries appear in a master index but not in a single-document index, code the entries using the MASTER attribute.

If you want to generate a single-document index that includes index entries that you coded with the MASTER attribute, use the /INDEX=OVERRIDE qualifier on the command line.

If you want to generate a master index that includes index entries that you coded without the MASTER attribute, use the /MASTER=OVERRIDE qualifier on the command line.

If you want to generate a master index that includes some of your coded index entries (both with and without using the MASTER attribute) while excluding other entries, do the following:

1. Edit your .SDML file by adding the NOMASTER attribute to the entries you want excluded.
2. Process your book using the /MASTER=OVERRIDE qualifier on the command line.

If you want to generate a single-document index that includes some but not all of the entries you coded using the MASTER attribute, without having to remove the MASTER attribute from the entries you want to include, do the following:

1. Edit your .SDML file by changing the MASTER attribute to BOTH for those entries you want to include.
2. Process your book to generate a single-document index by using the /INDEX qualifier on the command line.

Consider the following when indexing for Bookreader output:

• Be sure to place your index entries within the information you want the entry to point to, which ensures that the entry in the index will point to the correct topic of information.
• You can place index tags anywhere in your table, except directly after the <TABLE> tag, or else the entries will point to the previous text instead of to the table in the pop-up window.
• In formal examples and formal figures, place the index tags before the <ENDEXAMPLE> or <ENDFIGURE> tag, so that clicking on the entry in the index causes the actual example or figure to pop up. Do not place index entries within a code example, or the code example may not be formatted correctly.

Refer to Command Summary and Processing Messages for more information on using the /INDEX qualifier on the DOCUMENT command line.

Examples

The following example shows how to position the <X> tag to provide an index entry for a chapter.

<CHAPTER>(Creating Routines\creating_routine_sec) 
<X>(Routines<XSUBENTRY>creation of) 
<P>
In order to create a routine, you must first . . . 

If the previous text appeared on page 11-2, the <X> tag would create the following output under the heading "R":

Routines creation of, 11-2

The following example shows how to create an inclusive index entry using the BEGIN and END attributes.

<X>(File structure\begin) 
   .
   .
   .
<X>(File structure\end) 

This example produces the following output under the heading "F":

File structure, 5-4 to 5-7

The following example shows how to use the <XAPPEND> attribute. Notice that you must leave a space between the left parenthesis of the <XAPPEND> attribute's argument and the word you want to append, in order to have a space in the output between the page number and the appended word.

<X>(File structure\begin) 
   .
   .
   .
<X>(File structure\end\<XAPPEND>( passim)) 
 

This example produces the following output under the heading "F":

File structure, 5-4 to 5-7 passim

The following example shows how to code multiple subentries for a particular main entry.

<X>(Debugger<XS>features of) 
   .
   .
   .
<X>(Debugger<XS>exiting from) 
   .
   .
   .
<X>(Debugger<XS>invoking) 
 

This example produces the following output under the heading "D":

Debugger exiting from, 2-4 features of, 1-7 invoking, 3-9

The following example shows where to put an index tag in a table, and creates an index entry that correctly specifies the page that the text "bananas" appears on, no matter where DECdocument breaks the table.

<TABLE_ROW>(apples\oranges\pears) 
<TABLE_ROW>(<X>(Tropical fruits<XS>bananas)bananas\pineapples\mangos) 
<TABLE_ROW>(blackberries\blueberries\strawberries) 
 

This example produces the following output under the heading "T":

Tropical fruits bananas, 3-21

The following example shows how to use the <XSORT> attribute. "Tsar" is placed with the "C" entries after "Czar" rather than with the "T" entries.

<X>(Tsar<XSUBENTRY>country of\<XSORT>(Czar)) 

This example produces the following output:

Cat, 3-6 Czar, 1-16 Tsar country of, 3-21

The following example shows how to code an index entry that you want to appear only in a master index.

<X>(Classical music\MASTER) 

The following example shows how to code an index entry that you want to appear only in an individual index and not in a master index.

<X>(Jazz music\NOMASTER) 

The following example shows how to code an index entry that you want to appear in both an individual and a master index.

<X>(Alternative rock music\BOTH)