Specifies an ampersand (&) anywhere in your file. To specify an ampersand in an argument to a tag or in the context of the <MATH> tag, you must use this tag.

SYNTAX

<AMPERSAND>

ARGUMENTS

None.

related tags

• The following tags label other characters that you must tag when they occur in an argument to a tag:
  • <BACKSLASH>
  • <CPAREN>---required only if there is no opening parenthesis
  • <OPAREN>---required only if there is no closing parenthesis
  • <VBAR>

restrictions

You must use the <AMPERSAND> tag to specify an ampersand in an argument to a tag or in the context of the <MATH> tag.

DESCRIPTION

The <AMPERSAND> tag specifies an ampersand (&) anywhere in your file. Because the ampersand has a special meaning to the tag translator when it occurs within an argument to a tag, you must use the <AMPERSAND> tag to output an ampersand within an argument to a tag or in the context of the <MATH> tag, or it may be misinterpreted by the tag translator. Outside of an argument to a tag, use the ampersand keyboard character rather than the tag.

Example

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

<SUBHEAD1>(Continuing the Line with <AMPERSAND>\cont_ampersand) 
<P>Your BASIC statement may be formatted over two or more lines 
by terminating all lines except the last with an ampersand (&). 

This example produces the following output:

Continuing the Line with &

Your BASIC statement may be formatted over two or more lines by terminating all lines except the last with an ampersand (&).

Begins an appendix.

SYNTAX

<APPENDIX> (appendix title[\symbol name])

ARGUMENTS

appendix title

Specifies the title for the appendix.

symbol name

This is an optional argument. It specifies the symbol name used in all cross-references to this appendix. The value of the symbol name in the cross-reference file is the letter assigned to the appendix.

If the appendix is part of a book, the appendix letter is determined by the position of the appendix with respect to other appendixes in the book.

If the file being processed is not currently part of a book, the first appendix in the source file is lettered A, and subsequent appendixes are sequentially lettered.

Symbol names must not exceed 31 characters and must only contain alphabetic letters, numbers, or underscores. Do not begin a symbol name with an underscore.

related tags

• <SET_APPENDIX_LETTER>

restrictions

If you include the file containing this tag in a bookbuild, you must provide a symbol name.

required terminator

<ENDAPPENDIX>

DESCRIPTION

The <APPENDIX> tag begins an appendix. An appendix contains supplementary material at the end of a book and can contain any number of other tags.

DOCUMENT considers each appendix to be an online topic. See Producing Online and Printed Documentation for more information about online topics.

Example

The following example shows how to code an appendix.

<APPENDIX>(<REFERENCE>(product_name) Command Summary\command_app)
   .
   .
   .
<ENDAPPENDIX>
 

See Appendix A in this manual for a sample appendix.

Specifies a backslash anywhere in your file. To specify a backslash in an argument to a tag, you must use this tag.

SYNTAX

<BACKSLASH>

ARGUMENTS

None.

related tags

• The following tags label other characters that you must tag when they occur in an argument to a tag:
  • <AMPERSAND>
  • <CPAREN>--required only if there is no opening parenthesis
  • <OPAREN>--required only if there is no closing parenthesis
  • <VBAR>

restrictions

You must use the <BACKSLASH> tag to specify a backslash in an argument to a tag.

DESCRIPTION

The <BACKSLASH> tag specifies a backslash anywhere in your file. Because the literal backslash character is used to separate the arguments in the argument list to a tag, you must use the <BACKSLASH> tag to include a backslash as part of your argument. Outside of an argument to a tag, use the backslash keyboard character rather than the tag.

Example

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

<SUBHEAD1>(Using the Backslash (<BACKSLASH>)\using_backslash) 
<P>Use the backslash character (\) to separate BASIC statements 
on the same line. 
 

This example produces the following output:

Using the Backslash (\)

Use the backslash character (\) to separate BASIC statements on the same line.

Produces a box that surrounds a user-specified character string.

SYNTAX

<BOX> (label)

ARGUMENTS

label

Specifies the character string to be surrounded by the box.

restrictions

Invalid in the context of a <MATH> tag.

The character string can be as many as 15 characters long. The box format is not available for all output devices.

DESCRIPTION

The <BOX> tag produces a box that surrounds a user-specified character string. The case of the text is output as you entered it. The font, however, that the <BOX> tag uses distinguishes the enclosed text from the rest of the text.

Example

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

<P>You may need to enclose some text in a box, <BOX>(like this). 

This example produces the following output:

You may need to enclose some text in a box, [like this].

Identifies a number that is printed as a white letter in a black box or circle (depending on the output device) in an example. (The <CALLOUT> tag is identical to the <CO> tag.)

SYNTAX

<CALLOUT> [(number)]

ARGUMENTS

number

This is an optional argument. It specifies the number of the callout. If you do not specify a callout number, the callouts are numbered sequentially.

related tags

• <CALLOUT_REF>
• <CALLOUTS>
• <CO>
• <LIST>(CALLOUT)

restrictions

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

DESCRIPTION

The <CALLOUT> tag identifies a number that is printed as a white letter in a black box or circle (depending on the output device) in an example.

Examples

See the examples in the discussion of the <CALLOUTS> tag.

Labels a reference in text to a callout number.

SYNTAX

<CALLOUT_REF> (callout number)

ARGUMENTS

callout number

Specifies the number in the callout.

related tags

• <CALLOUT>
• <CALLOUTS>
• <CO>
• The following tags label other types of references:
  • <REFERENCE>(symbol name)
  • <GREF>(glossary term)

restrictions

Invalid in the context of a <MATH> and an <EXAMPLE> tag.

DESCRIPTION

The <CALLOUT_REF> tag labels a reference in text to a callout number. You create the callout number by using the <CALLOUT> tag in an example or figure.

Example

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

<P>In <REFERENCE>(page_transitions_fig), 
callout <CALLOUT_REF>(1) 
labels the beginning of the process. Callout <CALLOUT_REF>(2) labels the 
intermediate stage. 

This example produces the following output:

In Figure 3-3, callout (1) labels the beginning of the process. Callout (2) labels the intermediate stage.

Labels the beginning of a series of callouts contained in an example and enables the use of the <CALLOUT> and <CO> tags.

SYNTAX

<CALLOUTS> [([callout number] [\PREFIX])]

ARGUMENTS

callout number

This is an optional argument. It sets the number that begins numbering the callouts. If you do not specify a number, the numbering begins with one.

PREFIX

This is an optional keyword argument. It specifies that the callouts appear before the line they label, rather than at the end of the line. All callouts in any one example must precede the line they label or appear inside or at the end of the line they label. You cannot mix the location of the callouts.

This argument, if specified, must be the second argument, for example, <CALLOUTS>(\PREFIX).

related tags

• <CALLOUT>
• <CALLOUT_REF>
• <CO>
• <LIST>(CALLOUT)

restrictions

The <CALLOUTS> and <ENDCALLOUTS> tags must surround the examples within which the callouts are used.

required terminator

<ENDCALLOUTS>

DESCRIPTION

The <CALLOUTS> tag labels the beginning of a series of callouts contained in an example and enables the use of the <CALLOUT> and <CO> tags. See the <LIST> tag description for information about how to label callouts in a list.

Examples

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

<CALLOUTS>
<CODE_EXAMPLE>
           DO WHILE (^EOF);  <CALLOUT>
              READ FILE(INFILE) INTO(Y); 
              PUT LIST(Y);   <CALLOUT>
              END; 
<ENDCODE_EXAMPLE>
<ENDCALLOUTS>
<LIST>(CALLOUT) 
<LE>This is a <KEYWORD>(DO) statement. 
<LE>This <KEYWORD>(PUT) statement outputs the line read. 
<ENDLIST>

This example produces the following output:

DO WHILE (^EOF); (1) READ FILE(INFILE) INTO(Y); PUT LIST(Y); (2) END;

1. (1) This is a DO statement.
2. (2) This PUT statement outputs the line read.

The following example shows how you can set the number from which to begin numbering the callout sequence and how you can cause the callouts to precede the line to which they belong by using the PREFIX argument.

<CALLOUTS>(3\PREFIX) 
<CODE_EXAMPLE>
                  <CALLOUT>    DO WHILE (^EOF); 
                                  READ FILE(INFILE) INTO(Y); 
                  <CALLOUT>       PUT LIST(Y); 
                                  END; 
<ENDCODE_EXAMPLE>
<ENDCALLOUTS>

This example produces the following output:

(3) DO WHILE (^EOF); READ FILE(INFILE) INTO(Y); (4) PUT LIST(Y); END;

The following example shows how you can place callouts inside of lines and how you can use an argument to the <CALLOUT> tag to control the number of the callout.

#3

<CALLOUTS> <CODE_EXAMPLE> DO WHILE <CALLOUT>(9) (^EOF); READ FILE(INFILE) INTO(Y); PUT <CALLOUT>(12) LIST(Y); END; <ENDCODE_EXAMPLE> <ENDCALLOUTS>

This example produces the following output:

DO WHILE (9) (^EOF); READ FILE(INFILE) INTO(Y); PUT (12) LIST(Y); END;

Specifies a line of text you want to center in the current text margin.

SYNTAX

<CENTER_LINE> (text [

• \BIGSKIP
• \SMALLSKIP

])

ARGUMENTS

text

Specifies a line of text you want to center.

BIGSKIP

SMALLSKIP

These are optional keyword arguments. They specify a set amount of vertical space to precede the element identified as a line or block of text. The actual amount of space created is determined by the doctype.

related tags

• <CHEAD>
• <LINE>
• <RIGHT_LINE>

restrictions

Invalid in monospaced examples, in the context of a <MATH> tag, and in arguments to tags that provide title or heading text.

Centered text must fit within the current text margin. If you specify text that is too wide, the text formatter issues a warning message, and you should examine your output.

DESCRIPTION

The <CENTER_LINE> tag specifies a line of text you want to center in the current margin.

Example

The following example shows how to use both the BIGSKIP and SMALLSKIP keywords.

<P>Please include the following information: 
 
<CENTER_LINE>(Name\smallskip) 
<CENTER_LINE>(Address\bigskip) 
<CENTER_LINE>(Phone Number) 

This example produces the following output:

Please include the following information:

Name

Begins a chapter.

SYNTAX

<CHAPTER> (chapter title [\symbol name])

ARGUMENTS

chapter title

Specifies the name of the chapter. The doctype may also use this argument in the running title.

symbol name

This is an optional argument. It specifies the symbol name used in all cross-references to this chapter. The value of the symbol name is the number assigned to the chapter. Each chapter is sequentially numbered.

Symbol names must not exceed 31 characters and must only contain alphabetic letters, numbers, or underscores. Do not begin a symbol name with an underscore.

related tags

• <REFERENCE>
• <SET_CHAPTER_NUMBER>

restrictions

Invalid in the context of a <FRONT_MATTER> tag.

If you include a file containing the <CHAPTER> tag in a bookbuild, including a bookbuild for Bookreader, you must provide a symbol name argument with the tag.

DESCRIPTION

The <CHAPTER> tag begins a chapter. When printed, the chapter title and number are printed in a larger font. DOCUMENT automatically increments chapter numbers.

DOCUMENT considers each chapter to be an online topic. See Producing Online and Printed Documentation for more information about online topics.

Example

The following example shows how to code a chapter.

<CHAPTER>(Global Tag Descriptions\tags_chap) 
 
<P>This chapter includes descriptions of all global tags. The tags are 
listed alphabetically. 
 

See the beginning of this chapter for a sample chapter.

Specifies an unnumbered centered heading.

SYNTAX

<CHEAD> (heading text[\symbol name])

ARGUMENTS

heading text

Specifies the text of the heading.

symbol name

This is an optional argument. It specifies the name of the symbol used in all references to this heading. Symbol names must not exceed 31 characters and must only contain alphabetic letters, numbers, or underscores. Do not begin a symbol name with an underscore.

related tags

• <CENTER_LINE>
• <HEAD>
• <HEADN>
• <SUBHEADN>

---

DESCRIPTION

The <CHEAD> tag specifies an unnumbered centered heading. The heading does not appear in the table of contents. Use the <CHEAD> tag when the clarity of your document requires such a fine level of distinction.

---

Example

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

<CHEAD>(How to Use the <TAG>(chead) Tag\use_of_chead) <P>The use of centered headings should be restricted to occasions when the clarity of your document absolutely requires one.

This example produces the following output:

How to Use the <CHEAD> Tag

The use of centered headings should be restricted to occasions when the clarity of your document absolutely requires one.

---

<CHECK_FOR_INCLUSION>

Marks a definitions file to ensure that the file is read only once.

---

SYNTAX

<CHECK_FOR_INCLUSION> (file label)

---

ARGUMENTS

file label

Specifies a string that uniquely identifies this file. This string is not the name of the file; rather, it sets an internal switch to indicate that the following input should be read only once. The string can contain up to 15 alphanumeric characters or underscores and must not begin with an underscore.

restrictions

You must put the <CHECK_FOR_INCLUSION> tag at the top of the definitions file and the <ENDCHECK_FOR_INCLUSION> tag at the bottom of the file.

required terminator

<ENDCHECK_FOR_INCLUSION>

DESCRIPTION

The <CHECK_FOR_INCLUSION> tag marks a definitions file to ensure that the file is read only once, because to force the tag translator to process the definitions twice would be a waste of processing time. The tag is useful:

• For excluding the definitions file from being read when processing an individual element of a book, because the file has already been read for an entire bookbuild
• For excluding the definitions file from being read during a bookbuild if the source files already contain the same definitions

Example

The following example shows how you can use the <CHECK_FOR_INCLUSION> tag to exclude a file (in this example, the file MY_DEFINITIONS_FILE) from being read during a bookbuild.

<CHECK_FOR_INCLUSION>(MY_DEFINITIONS_FILE) 
<DEFINE>(ansi_long\ANSI General Purpose Subset (BSR X3.74)) 
<DEFINE>(ansi_short\ANSI GPSubset) 
   .
   .
   .
<ENDCHECK_FOR_INCLUSION>