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 <CO> tag is identical to the <CALLOUT> tag.)

SYNTAX

<CO> [(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>
• <CALLOUT_REF>
• <CALLOUTS>
• <LIST>(CALLOUT)

restrictions

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

DESCRIPTION

The <CO> 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.

Begins an example of code. Code consists of words or lines of instructions written in a programming language or a command language.

SYNTAX

<CODE_EXAMPLE> (inline code example)

or

<CODE_EXAMPLE> [(

• KEEP
• WIDE [\MAXIMUM]
• MAXIMUM

)]

code example text

.
.
.

<ENDCODE_EXAMPLE>

ARGUMENTS

inline code example

Specifies code you want to insert into your text.

If you do not use this argument, you must use the terminating tag <ENDCODE_EXAMPLE>.

KEEP

This is an optional keyword argument. It specifies that the example is not to be broken across pages; that is, if the example does not fit on the current page, it is placed on the next page. If the example itself does not fit on an entire single page of output, it is broken anyway. This keyword has no effect for Bookreader output.

WIDE

This is an optional keyword argument. It specifies that the width of the example exceeds the document's default width for text. Depending on the doctype, this argument is interpreted as follows:

• If the doctype contains a left margin area that is normally used for headings, the example's width spans that area as well as the normal text area.
• If the document uses a multicolumn format, the example suspends the multicolumn output while the example is processed. The example is output across two columns and then multicolumn output is restored.
  You must encase the code example in <EXAMPLE>, <FIGURE>, or <TABLE> tags in order to print the code example across two columns.
• Depending on the doctype, this argument provides a range of font sizes and font styles for examples.

MAXIMUM

This is an optional keyword argument. It specifies that the text of the code example is adjusted to a smaller point size in order to fit within the boundaries of the left and right margins of the page. You can use this keyword in conjunction with WIDE to indicate that the example may require additional adjustment to fit within the boundaries of the page. You should use this keyword with discretion, and it may not be suitable in all doctypes.

related tags

• <INTERACTIVE>
• <VALID_BREAK>

restrictions

Invalid in the context of a <FOOTNOTE> tag.

You cannot use indexing tags (<X> and <Y> tags) in code examples.

You cannot use tab characters to format code examples. You must use spaces.

You cannot use text element tags within a code example (for example, <P>, <LIST>, or <NOTE> tags).

If you use double hyphens within the <CODE_EXAMPLE>(code) tag, the double hyphens are converted to a single en dash. This does not occur if you use double hyphens in the context of the <CODE_EXAMPLE> and <ENDCODE_EXAMPLE> tags.

required terminator

<ENDCODE_EXAMPLE> ---Required if you do not provide the inline code example argument to the <CODE_EXAMPLE> tag.

DESCRIPTION

The <CODE_EXAMPLE> tag begins an example of code. Code consists of words or lines of instructions written in a programming language or a command language. The code that is begun with a <CODE_EXAMPLE> tag is distinguished typographically in the output. The size of the example, whether it will be indented and how much it will be indented from the current left margin of text, is controlled by the doctype.

Using the <CODE_EXAMPLE> tag makes the code example an informal example, in that the code example has no number or caption, cannot be referenced, and is not listed in the table of contents. If you enclose the code example within <EXAMPLE> and <ENDEXAMPLE> tags, however, the code example becomes a formal example; it then has a number and caption, can be referenced, and is listed in the table of contents.

By default, informal code examples do not pop up when viewed with Bookreader; formal code examples do. If you want an informal code example to pop up, use the <ONLINE_POPUP> tag.

There are two types of code examples. The first is a short fragment that you may want included with the surrounding text. In this case, enter the code as an argument to the <CODE_EXAMPLE> tag and do not use a terminating tag.

The second type of code example is one or more lines that you may want broken out of the text that surrounds it. In this case, enter the code between the <CODE_EXAMPLE> and <ENDCODE_EXAMPLE> tags. The character spaces and blank lines you enter to format the code are retained. You can also use the <ELLIPSIS> tag to achieve a vertical ellipsis showing that you have omitted some lines of code. If your code example is longer than a few lines, use the <VALID_BREAK> tag to indicate the acceptable points for a page break.

Examples

The following example shows a short code example that is run in with the surrounding text. The <VARIABLE> tag simply distinguishes a variable typographically. See the <VARIABLE> tag description for more information.

<P>The <CODE_EXAMPLE>(WHILE INLOOP) statement causes the 
following block to be repeated until the <VARIABLE>(INLOOP) variable 
is set to FALSE. 

This example produces the following output:

The WHILE INLOOP statement causes the following block to be repeated until the INLOOP variable is set to FALSE.

The following example shows how to use the <CODE_EXAMPLE> tag with a longer example that is broken out of the surrounding text. In this case, you need the <ENDCODE_EXAMPLE> tag, because the code is not used as an argument to the <CODE_EXAMPLE> tag.

<P>The call frame is built on the stack by the following four instructions: 
<CODE_EXAMPLE>
     PUSHAB    B^SRVEXIT 
     PUSHL     FP 
     PUSHL     AP 
     CLRQ      -(SP) 
<ENDCODE_EXAMPLE>
 

This example produces the following output:

The call frame is built on the stack by the following four instructions:

PUSHAB B^SRVEXIT PUSHL FP PUSHL AP CLRQ -(SP)

The following example shows a longer code example that uses the <ELLIPSIS> tag.

<P>The instruction sequence listed here (patterned after code in 
module PROCSTRT) shows this second technique. 
<CODE_EXAMPLE>
PUSHL     executive-mode-PSL 
BSBB      DOREI 
<ELLIPSIS>
PUSHL     user-mode-PSL 
BSBB      DOREI 
<ELLIPSIS>
DOREI:    REI 
<ENDCODE_EXAMPLE>

This example produces the following output:

The instruction sequence listed here (patterned after code in module PROCSTRT) shows this second technique.

PUSHL executive-mode-PSL BSBB DOREI . . . PUSHL user-mode-PSL BSBB DOREI . . . DOREI: REI

Marks a section of an SDML file that you do not want to appear in your output. Text marked by a <COMMENT> tag is ignored by the tag translator during processing.

SYNTAX

<COMMENT> (comment text)

or

<COMMENT>

comment text

.
.
.

<ENDCOMMENT>

ARGUMENTS

comment text

Specifies the text you do not want to appear in your output. This is a required argument, unless you use the <COMMENT> and <ENDCOMMENT> tags with comment text between the two tags.

restrictions

You cannot nest <COMMENT> tags.

required terminator

<ENDCOMMENT> --- Required if you do not specify an argument to the <COMMENT> tag.

DESCRIPTION

The <COMMENT> tag marks a section of an SDML file that you do not want to appear in your output. Text marked by a <COMMENT> tag is ignored by the tag translator during processing.

Comments can provide useful reminders for your own use or use by writers who may modify your SDML file in the future. You can also use comments to exclude portions of text from the output file that you want to save for later inclusion. The text remains in the SDML file, but does not appear in the output.

Example

The following example shows a code example with a comment embedded in the code. The tag translator ignores the text between the <COMMENT> and <ENDCOMMENT> tags.

<CODE_EXAMPLE>
        ; 
        ; SECONDARY POOL COMMAND BUFFER BLOCKS 
        ; 
        .=0 
000000  C.CLK:   .BLKW  1 ;LINK WORD 
000002  C.CTCB:  .BLKW  1 ;TCB ADDRESS OF TASK TO RECEIVE COMMAND 
000004  C.CUCB:  .BLKW  1 ;UCB ADDRESS IF RESPONSIBLE TERMINAL 
000006  C.CCT:   .BLKW  1 ;CHARACTER COUNT, EXCLUDING TRAILING CR 
000010  C.CSTS:  .BLKW  1 ;STATUS MASK 
<COMMENT>            
000012  C.CMCD:           ;SYSTEM MESSAGE CODE 
000012  C.CSO:   .BLKW  1 ;STARTING OFFSET OF VALID COMMAND TEXT 
<ENDCOMMENT>         
OOOO14  C.CTR:   .BLKW  1 ;TERMINATING CHARACTER 
OOOO15  C.BLK:   .BLKW  1 ;SIZE OF PACKET IN SEC POOL (32 WD.) BLOCKS 
000016  C.CTXT:           ;COMMAND TEXT, FOLLOWED BY CR 
<ENDCODE_EXAMPLE>

This example produces the following output:

; ; SECONDARY POOL COMMAND BUFFER BLOCKS ; .=0 000000 C.CLK: .BLKW 1 ;LINK WORD 000002 C.CTCB: .BLKW 1 ;TCB ADDRESS OF TASK TO RECEIVE COMMAND 000004 C.CUCB: .BLKW 1 ;UCB ADDRESS IF RESPONSIBLE TERMINAL 000006 C.CCT: .BLKW 1 ;CHARACTER COUNT, EXCLUDING TRAILING CR 000010 C.CSTS: .BLKW 1 ;STATUS MASK OOOO14 C.CTR: .BLKW 1 ;TERMINATING CHARACTER OOOO15 C.BLK: .BLKW 1 ;SIZE OF PACKET IN SEC POOL (32 WD.) BLOCKS 000016 C.CTXT: ;COMMAND TEXT, FOLLOWED BY CR

Marks a section of an SDML file that is not processed unless one of the arguments to the tag matches the argument in the related <SET_CONDITION> tag or matches the condition you set with the /CONDITION qualifier on the DOCUMENT command line.

SYNTAX

<CONDITION> (condition name-1 [\condition name-2] [\condition name-3])

conditional text

.
.
.

<ENDCONDITION>

ARGUMENTS

condition name

Specifies up to three condition names created with the <SET_CONDITION> tag. At least one condition name is required.

related tags

• <SET_CONDITION>

restrictions

You cannot nest <CONDITION> tags.

In monospaced examples, <CONDITION> and <ENDCONDITION> tags cannot occupy the same line as text for the example.

required terminator

<ENDCONDITION>

DESCRIPTION

The <CONDITION> tag marks a section of an SDML file that is not processed unless one of the arguments to the tag matches the argument in the related <SET_CONDITION> tag or matches the condition you set with the /CONDITION qualifier on the DOCUMENT command line.

If the two tags' arguments are identical, the marked text is processed and included in the output file. If the arguments differ, the text is excluded from processing.

This tag can be very useful if you must produce two or more documents that differ in minor ways but contain much of the same text. It is efficient to maintain one SDML file and identify the portions of text that are unique to each document.

Before processing the SDML file, you can specify the condition name for the desired document by using the <SET_CONDITION> tag or the /CONDITION qualifier on the DOCUMENT command line. When the tag translator processes the file, it includes all portions of text tagged with that condition name argument and ignores all portions of text tagged with any other condition name. To obtain another version of the document, change the condition name in the argument to the <SET_CONDITION> tag or change the /CONDITION qualifier and reprocess the file.

When you supply more than one condition name argument to the <CONDITION> tag, only one of the condition names needs to be present for the conditional text to be processed.

Examples

The following example shows how you could organize a file if you were writing about holidays in general, and Christmas, Chanukah, and Passover in particular. Any of three different condition states could be set at the top of your file with the <SET_CONDITION>(Christmas), <SET_CONDITION>(Chanukah), or <SET_CONDITION>(Passover) tags. The example contains four paragraphs, with each paragraph conditionalized differently.

If the file is processed with the <SET_CONDITION>(Christmas) tag, the information on Christmas and religious holidays is processed. If the file is processed with the <SET_CONDITION>(Chanukah) tag, the information on Chanukah and religious holidays is processed. If the file is processed with the <SET_CONDITION>(Passover) tag, the information on Passover is processed.

The function of the <SET_CONDITION> tag can be obtained by using the /CONDITION qualifier on the DOCUMENT command line instead. See Producing Online and Printed Documentation or Command Summary and Processing Messages for more information.

<CONDITION>(Christmas)
<P>Christmas, by convention, is celebrated on December 25th...
<ENDCONDITION>
 
<CONDITION>(Chanukah)
<P>Chanukah is called the Festival of Lights...
<ENDCONDITION>
 
<CONDITION>(Passover)
<P>Passover is usually celebrated...
<ENDCONDITION>
 
<CONDITION>(Christmas\Chanukah)
<HEAD1>(Religious Holidays)
<P>This paragragh contains general information about several religious 
holidays...
<ENDCONDITION>
 

The following example shows how you can omit one of two clauses from processing based on the condition name specified in the <SET_CONDITION> tag. The section of text that is identified with <CONDITION>(VMS) would be processed and placed in the output file, whereas the other text would be omitted.

<SET_CONDITION>(VMS) 
   .
   .
   .
When the 
<CONDITION>(VMS)VAX/VMS<ENDCONDITION>
<CONDITION>(RSX)RSX11M/RSX11M-PLUS<ENDCONDITION>
command language interpreter translates the logical name...
 

This example produces the following output:

When the VAX/VMS command language interpreter translates the logical name...

The following example shows how you can differentiate text that is applicable to the two condition names (VMS and RSX) from text that is applicable to the condition name RSTS. By supplying both the VMS and RSX arguments to the first <CONDITION> tag, you ensure that the text is included in the output if either the VMS or RSX condition name is set. (Other text in the same SDML file might be conditional for only one of these condition names.)

<SET_CONDITION>(RSX) 
<P>When RSX...
   .
   .
   .
<CONDITION>(VMS\RSX) 
<P>When the operating system...
   .
   .
   .
<ENDCONDITION>
 
<CONDITION>(RSTS) 
<P>When RSTS...
   .
   .
   .
<ENDCONDITION>
 

Specifies the position in a source file where a table of contents output file will be included; it does not produce a table of contents.

SYNTAX

<CONTENTS_FILE> [(file spec)]

ARGUMENTS

file spec

This is an optional argument. It specifies the name of the table of contents file. Use this argument if you want to include a table of contents file with a name other than the default file name.

The default file name is file spec_contents.DVI_device. If you specify a file type, be sure that the device name matches the destination device you specify on the DOCUMENT command line. For example, if you specify file spec_contents.DVI_PS, be sure you specify PS as the destination on the command line.

related tags

• <FRONT_MATTER>
• <PROFILE>

restrictions

Valid only in the context of a <FRONT_MATTER> or <PROFILE> tag. This tag must occur within front matter or a profile in order for processing to continue.

DESCRIPTION

The <CONTENTS_FILE> tag specifies the position in a source file where a table of contents output file will be included; it does not produce a table of contents. A contents file is produced when you specify the qualifier /CONTENTS on the DOCUMENT command line.

It is recommended that you place the <CONTENTS_FILE> tag in the front matter file immediately before the <PREFACE> tag. This ensures correct placement of the table of contents in both printed and Bookreader output.

A contents file always receives the filetype .DVI _device, where device is the type of output device you specified on the DOCUMENT command line. To generate a table of contents from an individual file that contains a <CONTENTS_FILE> tag, specify the /CONTENTS qualifier on the DOCUMENT command line.

If you specify the /CONTENTS qualifier on the DOCUMENT command line without using the <CONTENTS_FILE> tag in your front matter file, a table of contents is generated separately from your document. For more information on generating a table of contents, see Producing Online and Printed Documentation.

Because a table of contents is required for a book you create for Bookreader, a table of contents file is generated automatically if you do not use a <CONTENTS_FILE> tag or the /CONTENTS qualifier on the DOCUMENT command line. If you do use the <CONTENTS_FILE> tag in a Bookreader bookbuild, however, the tag must not precede the <TITLE_PAGE> tag.

Example

To see the result of the <CONTENTS_FILE> tag, refer to the table of contents in this manual. See the example in the <FRONT_MATTER> tag description for an example of placing the <CONTENTS_FILE> tag before the <PREFACE> tag in the front matter of a book.

Inserts a copyright date line on the copyright page along with other system-specific copyright information.

SYNTAX

<COPYRIGHT_DATE> (date[\owner])

ARGUMENTS

date

Specifies official printing date information for the book.

owner

This is an optional argument. It specifies the owner of the copyright.

Note For Bookreader output, the arguments you specify are used to generate the copyright notice on the title page, not on the copyright page.

related tags

• <COPYRIGHT_PAGE>
• <FRONT_MATTER>

restrictions

Valid only in the context of a <COPYRIGHT_PAGE> tag, which you can use only within the front matter of a book.

DESCRIPTION

The <COPYRIGHT_DATE> tag inserts a copyright date line on the copyright page along with other system-specific copyright information.

Example

The following example shows how to use the <COPYRIGHT_PAGE> tag to produce a full page of output.

<FRONT_MATTER>(front) 
<COPYRIGHT_PAGE>
<COPYRIGHT_DATE>(1990\Smith Publishing, Inc.) 
<ENDCOPYRIGHT_PAGE>
<ENDFRONT_MATTER>

This example produces the following output:

Copyright ©1990 Smith Publishing, Inc. All Rights Reserved.