| DocBook: The Definitive Guide 2.0.17 (Alpha)

# callout

$Revision: 2258 $

$Date: 2002-11-26 09:26:23 -0500 (Tue, 26 Nov 2002) $

callout — A “called out” description of a marked `Area`

## Synopsis

### Content Model

    callout ::=
    ((calloutlist|glosslist|bibliolist|itemizedlist|orderedlist|
      segmentedlist|simplelist|variablelist|caution|important|note|
      tip|warning|literallayout|programlisting|programlistingco|
      screen|screenco|screenshot|synopsis|cmdsynopsis|funcsynopsis|
      classsynopsis|fieldsynopsis|constructorsynopsis|
      destructorsynopsis|methodsynopsis|formalpara|para|simpara|
      address|blockquote|graphic|graphicco|mediaobject|mediaobjectco|
      informalequation|informalexample|informalfigure|informaltable|
      equation|example|figure|table|msgset|procedure|sidebar|qandaset|
      task|productionset|constraintdef|anchor|bridgehead|remark|
      highlights|abstract|authorblurb|epigraph|indexterm|beginpage)+)

### Attributes

Common attributes

Name | Type | Default
arearefs | IDREFS | Required

## Description

A “callout” is a visual device for associating annotations with an image, program listing, or similar figure. Each location is identified with a mark, and the annotation is identified with the same mark. This is somewhat analagous to the notion of footnotes in print.

An example will help illustrate the concept. In the following example, the synopsis for the mv command is annotated with two marks. Note the location of the old and new filenames.

    mv oldfile newfile

Somewhere else in the document, usually close by, a `CalloutList` provides a description for each of the callouts:

| The old filename. The mv command renames the file currently called `oldfile`, which must exist when mv is executed.
| The new filename. The mv command changes the name of the old file to `newfile`. If `newfile` exists when mv is executed, it will be replaced by the old file.

Each `Callout` contains an annotation for an individual callout or a group of callouts. The `Callout` points to the areas that it annotates with ID references. The areas are identified by coordinates in an an `Area` or `AreaSet`, or by an explicit `CO` element.

### Processing expectations

Formatted as a displayed block.

`CallOut`s usually generate text that points the reader to the appropriate area on the object being augmented. Often, these are numbered bullets or other distinct visual icons. The same icons should be used in both places. In other words, whatever identifies the callouts on the object should generate the same icons on the respective callouts.

In online environments, it may also be possible to establish a linking relationship between the two elements.

The processing expectations of `Callout`s are likely to deserve special consideration for interchange. See Appendix F, Interchanging DocBook Documents. This is especially true if your interchange partners are producing documentation in a medium that has restricted visual presentation features, such as aural media or Braille.

### Parents

These elements contain callout: `calloutlist`.

### Children

The following elements occur in callout: `abstract`, `address`, `anchor`, `authorblurb`, `beginpage`, `bibliolist`, `blockquote`, `bridgehead`, `calloutlist`, `caution`, `classsynopsis`, `cmdsynopsis`, `constraintdef`, `constructorsynopsis`, `destructorsynopsis`, `epigraph`, `equation`, `example`, `fieldsynopsis`, `figure`, `formalpara`, `funcsynopsis`, `glosslist`, `graphic`, `graphicco`, `highlights`, `important`, `indexterm`, `informalequation`, `informalexample`, `informalfigure`, `informaltable`, `itemizedlist`, `literallayout`, `mediaobject`, `mediaobjectco`, `methodsynopsis`, `msgset`, `note`, `orderedlist`, `para`, `procedure`, `productionset`, `programlisting`, `programlistingco`, `qandaset`, `remark`, `screen`, `screenco`, `screenshot`, `segmentedlist`, `sidebar`, `simpara`, `simplelist`, `synopsis`, `table`, `task`, `tip`, `variablelist`, `warning`.

## Attributes

arearefs

  `AreaRefs` must point to one or more callouts. Callouts can be identified with `Area` or `AreaSet` elements in a `GraphicCO`, `MediaObjectCO`, `ProgramListingCO`, or `ScreenCO` element or with a simple `CO` element in a number of other environments. These callouts identify the portions of the object described by this `Callout`.

## Examples

For examples, see `programlistingco`, `screenco`.

bridgehead |  | calloutlist

Copyright © 1999, 2000, 2001, 2002, 2003 O'Reilly & Associates, Inc. All rights reserved.