Supplies parentheses around a character you specify, resulting in better spacing of the character between the parentheses.

Format

<PARENDCHAR> (char)

ARGUMENTS

char

Specifies the character within parentheses. You specify only the character; the parentheses are added during processing.

restrictions

Invalid in the context of a <MATH> tag.

DESCRIPTION

The <PARENDCHAR> tag supplies parentheses around a character you specify, resulting in better spacing of the character within the parentheses. Frequently, writers use the name for a special character followed by that character in parentheses. For instance, in discussing wildcard characters, it is usual to say, "The percent sign (%) is the wildcard for a single character."

A problem in using proportionally spaced fonts is that single characters surrounded by parentheses can look crowded, like this: "The percent sign (%) is the wildcard for a single character." Compare the percent sign in parentheses in this paragraph to the percent sign in parentheses in the previous paragraph; you can see the slight crowding of the percent sign in this paragraph.

Typographers put a small amount of space, called a "thin space," between the parentheses and the single character to achieve a balance. When you use the <PARENDCHAR> tag, that thin space is added for you.

Use the <PARENDCHAR> tag to label characters that are small or that are more vertical than horizontal in shape. The parentheses are added during processing.

Example

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

<P>The tilde <PARENDCHAR>(~) is used to prevent the word 
following it from becoming a main entry in the index. 

This example produces the following output:

The tilde (~) is used to prevent the word following it from becoming a main entry in the index.

Without the <PARENDCHAR> tag, your output would look like this:

The tilde (~) is used to prevent the word following it from becoming a main entry in the index.

Labels the start of a major division within a document and starts it on a new page.

Format

<PART> [(part title[\symbol name])]

ARGUMENTS

part title

This is an optional argument for printed output when you process a single file, but required if you include the file in a bookbuild, including a Bookreader bookbuild. This argument specifies the title for this part of your document.

symbol name

This is an optional argument for printed output when you process a single file, but required if you include the file in a bookbuild, including a Bookreader bookbuild. This argument specifies the term that you assign to this part and then use to reference the part throughout your document.

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

• <PART_PAGE>

---

DESCRIPTION

The <PART> tag labels the start of a major division within a document and starts it on a new page. Parts may consist of the following:

• A set of chapters or appendixes whose contents are logically related. The chapters or appendixes are numbered sequentially from the start of the document to the end, regardless of the parts; that is, the chapters or appendixes within each part do not begin at "1".
• A collection of units of logically related information, for example, reference items in the SOFTWARE doctype.

Like chapters, parts are automatically numbered. If you specify a symbol name argument, a symbol table entry is created for the part. The part title and symbol name arguments are required for Bookreader output.

The <PART_PAGE> tag creates a divider page for a part. You can specify a title for the part that is printed on the part page, a running title for the part (same or different from the title) that is printed on each page of the part, and an abstract printed on the part page to describe the information in the part.

By default, the part page is assigned the next odd page number in the current numbering sequence (except for Bookreader output, where there are no page numbers) in a document that does not have chapters. If you specify the RENUMBER argument to the <ENDPART_PAGE> tag, the part page is assigned the number 1, and the next printed page of output is assigned the number 3. See the <ENDPART_PAGE> tag description for more information.

Using the RENUMBER argument and the <RUNNING_TITLE> tag have no effect for Bookreader output.

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

---

Example

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

<part>(Introduction to Global Tags\intro_part) <part_page> <title>(<reference>(intro_part)\<reference>(intro_part\text)) <abstract> This part contains introductory chapters. <reference>(ref_part) contains more detailed reference information. <endabstract> <running_title>(Introduction to Global Tags) <endpart_page>(RENUMBER)

This example produces the following output on the part page if this is the first part specified in the document:

• The <PART_PAGE> tag creates a new page of output. The page is assigned the next odd page number in the numbering sequence.
• The title: "PART I Introduction to Global Tags" will be printed at the top of the part page. The first <REFERENCE> tag within the <TITLE> tag generates "PART I"; the second <REFERENCE> tag generates "Introduction to Global Tags", as a result of using the text argument. You need to use the two <REFERENCE> tags to create both the part number and the part title. The use of uppercase Roman numerals to display the part number depends on the doctype you use.
• The abstract text is printed.
• The running title, "Introduction to Global Tags" is printed on each page of the part.
• Using the RENUMBER argument to the <ENDPART_PAGE> tag assigns the part page to be number 1, and the next printed page is assigned to be page 3. If you do not use the RENUMBER argument, the part page is assigned the next odd page number in the current numbering sequence in a document that does not have chapters.

---

<PART_PAGE>

Inserts a divider page for a new part of a document.

---

Format

<PART_PAGE>

---

ARGUMENTS

None.

related tags

• <ABSTRACT>
• <PART>
• <RUNNING_TITLE>
• <TITLE>

required terminator

<ENDPART_PAGE>

DESCRIPTION

The <PART> tag inserts a divider page for a new part of a document. You can use the <TITLE>, <RUNNING_TITLE>, and <ABSTRACT> tags to provide infomation on the part page and to specify a running title for that part of your document.

The <RUNNING_TITLE> tag has no effect for Bookreader output.

Example

See the example in the discussion of the <PART> tag.

Labels the beginning of a preface.

Format

<PREFACE> [(page number [\symbol name])]

ARGUMENTS

page number

This is an optional argument. It specifies the page number on which you want the preface to begin. You must specify the number with an Arabic numeral (the number in the formatted result will be a lowercase Roman numeral). If you do not specify a number, the default page on which the preface begins is Roman numeral five (v). This argument has no effect for Bookreader output.

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

• <PREFACE_SECTION>

restrictions

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

required terminator

<ENDPREFACE>

DESCRIPTION

The <PREFACE> tag labels the beginning of a preface. If you want the preface of your document placed after the table of contents, which usually begins on page (Roman numeral) iii, you must specify the starting page number for the preface for printed output; the page number argument has no effect for Bookreader output. You cannot know what this number will be until the document is nearly completed and you know what the page count is for the table of contents.

The preface always begins on a right-hand page following the table of contents; thus, it always begins with an odd page number, by default the Roman numeral five (v). You must adjust the page numbering of the preface, however, if the table of contents is longer than you expected (that is, longer than three pages).

If the table of contents ends on an even page (therefore, a left-hand page), you add one to the preface's page number, which starts the preface on the right-hand page. For example, if the table of contents ends on page 8, you would use the following tag to specify that the preface begin on page 9:

<PREFACE>(9)

If the table of contents ends on an odd page (therefore, a right-hand page), you add two to that page number, which starts the preface on the right-hand page (and in this case, leaving a blank left-hand page). For example, if the table of contents ends on page 9, you would use the following tag to specify that the preface begin on page 11:

<PREFACE>(11)

You cannot reference any headings from the preface; sections you code within the preface with <HEADN> tags are unnumbered and do not produce table of contents entries.

If your preface includes a section that you want to appear in the table of contents, you must code it as follows:

<PREFACE_SECTION>(New Section)

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

Example

See the example in the discussion of the <FRONT_MATTER> tag.

Creates a major section in the preface of a book to provide information, such as a summary of changes to the book.

Format

<PREFACE_SECTION> (title [\symbol name])

ARGUMENTS

title

Specifies the title you give to the preface section.

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

• <PREFACE>

restrictions

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

DESCRIPTION

The <PREFACE_SECTION> tag creates a major section in the preface of a book to provide information, such as a summary of changes to the book.

Note that because <HEADN> tags in a preface do not produce table of contents entries, you must code sections of your preface that you want to appear in the table of contents as follows:

<PREFACE_SECTION>(New Section)

Example

See the example in the discussion of the <FRONT_MATTER> tag.

Inserts a print date line on the copyright page.

Format

<PRINT_DATE> (date)

ARGUMENTS

date

Specifies official printing date information for the book.

restrictions

Valid only in the context of a <COPYRIGHT_PAGE> tag in the front matter of a document.

DESCRIPTION

The <PRINT_DATE> tag inserts a print date line on the copyright page.

Example

See the example in the discussion of the <FRONT_MATTER> tag.

Indicates that the source file is a profile that generates a bookbuild.

Format

<PROFILE>

ARGUMENTS

None.

related tags

• <ELEMENT>
• <INCLUDES_FILE>

required terminator

<ENDPROFILE>

DESCRIPTION

The <PROFILE> tag indicates that the source file is a profile that generates a bookbuild. A profile of a book is required in order to build (process) a book. Between the <PROFILE> and <ENDPROFILE> tags, you introduce each element of the book with an <ELEMENT> tag.

Only those files listed with <ELEMENT> tags are included in the book during the bookbuild. List them in the profile in the order in which they appear in the book.

Within a profile file, never include a tag that produces text. Also, do not place an <INCLUDE> tag in a profile.

There are several optional tags that you can include between the <PROFILE> and <ENDPROFILE> tags, other than <ELEMENT> tags. These include the following:

• <COMMENT> and <ENDCOMMENT>
• <CONDITION> and <ENDCONDITION>
• <CONTENTS_FILE>
• <INCLUDES_FILE>
• <INDEX_FILE>
• <REVISION>
• <SET_CONDITION>
• <SET_ONLINE_TOPIC>

See Producing Online and Printed Documentation for more information on bookbuilding.

Example

The following example shows the profile of a book that contains a table of contents, four chapters, an appendix, and an index. The profile shown in this example must be in a file by itself. You should call the file by a name that indicates it is a profile, such as "COMPUTER_PROFILE.SDML."

Each of the files named in the <ELEMENT> tags should begin with one of the book element tags, such as <CHAPTER>(Introduction\introduction_chap).

<PROFILE>     <COMMENT>(***Profile for How to Use a Computer***) 
 
<CONTENTS_FILE> <COMMENT>(***insert table of contents here***) 
<ELEMENT>(Mydisk:[Mydirectory]front_matter.sdml) 
<ELEMENT>(Mydisk:[Mydirectory]intro_chap.sdml) 
<ELEMENT>(Mydisk:[Mydirectory]applications_chap.sdml) 
<ELEMENT>(Mydisk:[Mydirectory]tools_chap.sdml) 
<ELEMENT>(Mydisk:[Mydirectory]conclusion_chap.sdml) 
<ELEMENT>(Mydisk:[Mydirectory]questions_app.sdml) 
 
<INDEX_FILE> <COMMENT>(***insert index here***) 
<ENDPROFILE>
 

Encloses text in quotation marks. The quotation marks appear as if they are typeset.

Format

<QUOTE> (quoted text)

or

<QUOTE>

quoted text

.
.
.

<ENDQUOTE>

ARGUMENTS

quoted text

Specifies the quoted text.

related tags

• <DOUBLE_QUOTE>
• <SINGLE_QUOTE>

required terminator

<ENDQUOTE> ---Required if you do not specify the quoted text argument to the <QUOTE> tag.

DESCRIPTION

The <QUOTE> tag encloses text in quotation marks. The quotation marks appear as if they are typeset.

Your terminal keyboard has two possible characters you can use for quotation marks: the double quote (") (ASCII 34) and the single quote (') (ASCII 39). Neither distinguishes between opening quotation marks and closing quotation marks. You use the same character twice to enclose a word in quotation marks.

Documents that are typeset, however, use distinct opening quotation marks and closing quotation marks. To obtain these distinct quotation marks in your output, label the text you want inside the quotation marks with the <QUOTE> tag. If you use the keyboard quote character instead of the <QUOTE> tag, the opening and closing quotation marks in your output will not be different from each other.

Examples

The following example shows how to use the <QUOTE> tag to obtain distinct opening and closing quotation marks in your output.

<P>The symbol B will be defined to be the string <QUOTE>(April 
showers.) 

This example produces the following output:

The symbol B will be defined to be the string "April showers."

The following example shows the same output as the first example using the keyboard quotation marks instead of using the <QUOTE> tag.

<P>The symbol B will be defined to be the string "April 
showers." 

This example produces the following output:

The symbol B will be defined to be the string "April showers."

The following example shows how to code some text if you want a punctuation mark outside the quotation marks. Put the punctuation mark outside of the closing parenthesis of the argument to the <QUOTE> tag or after the <ENDQUOTE> tag.

<P>Did Abraham Lincoln write, <QUOTE> I claim not to have controlled 
events, but confess plainly that events have controlled me <ENDQUOTE>? 
 

This example produces the following output:

Did Abraham Lincoln write, " I claim not to have controlled events, but confess plainly that events have controlled me "?

Makes a reference to a symbol name in a book element or text element. When processed, the <REFERENCE> tag is replaced with the current value of the symbol name that is stored in the cross-reference file.

Format

<REFERENCE> (symbol name [

• \FULL
• \TEXT
• \VALUE

])

ARGUMENTS

symbol name

Specifies the name of a symbol assigned in a book element or text element tag (for example, <HEADN> or <TABLE>). 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.

FULL

This is an optional keyword argument. It outputs all information associated with the symbol, including the value, type, and text.

TEXT

This is an optional keyword argument. It outputs only the text associated with the symbol table entry, that is, the caption (for figures, tables, and examples), or the heading text (for chapter, section, and heading-level tags).

VALUE

This is an optional keyword argument. It outputs only the current value of the symbol, for example, the heading level number or the table number, without any related text.

If you do not specify any of the keywords, the current value of the symbol and the text related to the kind of symbol it is, for example, Figure 3-2 or Table 3-2, is output. This is the default.

related tags

• <HOTSPOT>--See Using Doctypes and Related Tags

---

DESCRIPTION

The <REFERENCE> tag makes a reference to a symbol name in a book element or text element. When processed, the <REFERENCE> tag is replaced with the current value of the symbol name that is stored in the cross-reference file.

A second argument to the tag controls the exact output of the reference. When you do not specify a second argument, the output defaults according to whether the symbol refers to a heading, a figure, a table, a chapter, and so on. Table 1-4 summarizes the default output for each type of text or book element.

Table 1-4 Element Types and Default Output of Symbol Names

	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

See Producing Online and Printed Documentation for more information on symbol names and cross-referencing.

For a book you create for Bookreader, you must use the <REFERENCE> tag to allow DOCUMENT to automatically cross-reference the symbol names you assign to the tag.

The following tags require a symbol name for a book you create for Bookreader:

• <APPENDIX>
• <CHAPTER>
• <CHEAD>
• <EXAMPLE>
• <FIGURE>
• <HEAD>
• <HEADN>
• <PREFACE>
• <PREFACE_SECTION>
• <SUBHEADN>
• <TABLE>
• <COMMAND>

• <ROUTINE>
• <SDML_TAG>
• <STATEMENT>
• <SUBCOMMAND>

The last five tags are listed in Using Doctypes and Related Tags.

The following tags accept a symbol name, but do not require one, for both printed books and books you create for Bookreader:

• <FRONT_MATTER>
• <GLOSSARY>
• <PART>
• <MATH>

The following tags, listed in Using Doctypes and Related Tags, accept a symbol name for a printed book; the tags are ignored for books you create for Bookreader:

• <REF_NOTE>
• <SECTION>

When you use the <REFERENCE> tag to refer to a formal example, figure, or table, the words that appear in the hotspot are directly related to the way you code the <REFERENCE> tag. For example, suppose you enter a <REFERENCE>(symbol name\VALUE) tag when referring to a hotspot, but you physically type in an identifying reference before the tag, like "See Figure <REFERENCE>(symbol name\VALUE)". The word that you used as the identifying reference will appear ouside of the hotspot; for example, "1--1" would appear in the hotspot, but "Figure" would not.

---

Examples

The following example shows how to use the <REFERENCE> and <TABLE> tags to make a default reference to the symbol name of a table. The symbol name "lognames_tab" is defined in the <TABLE> tag and then referred to with the <REFERENCE> tag.

#1

<REFERENCE>(lognames_tab) shows ten default system logical names. <TABLE>(System Logical Names\lognames_tab) . . .

---

Previous

Next

Contents

Index