$Revision: 2258 $
$Date: 2002-11-26 09:26:23 -0500 (Tue, 26 Nov 2002) $
callout — A “called out” description of a marked Area
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
)+)
Name | Type | Default |
arearefs | IDREFS | Required |
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.
mvoldfile
newfile
Somewhere else in the document, usually close by, a CalloutList
provides a description for each of the callouts:
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.
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.
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
.
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
.