callout

callout — A “called out” description of a marked area.

Synopsis

callout ::=

One or more of:
- bridgehead
- dialogue
- drama
- poetry
- remark
- revhistory
- Indexing inlines
  indexterm (db.indexterm.endofrange)
  indexterm (db.indexterm.singular)
  indexterm (db.indexterm.startofrange)
- Admonition elements
  note
- Formal elements
  equation
  example
  figure
  table
- Graphic elements
  mediaobject
- Informal elements
  informalequation
  informalexample
  informalfigure
  informaltable
- List elements
  bibliolist
  calloutlist
  glosslist
  itemizedlist
  orderedlist
  procedure
  qandaset
  simplelist
  variablelist
- Paragraph elements
  anchor
  formalpara
  para
  simpara
- Publishing elements
  address
  blockquote
  epigraph
  sidebar
- Technical elements
  procedure
  task
- Verbatim elements
  literallayout

Attributes

Common attributes.

Additional attributes:

arearefs (IDREFS)

Required attributes are shown in bold.

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 analogous 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 area or areaset, or by an explicit co element.

Processing expectations

Formatted as a displayed block.

A callout usually generates 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 callouts are likely to deserve special consideration for interchange. See Appendix C, 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.

Attributes

Common attributes.

arearefs: Identifies the areas described by this callout.

Parents

These elements contain callout: calloutlist.

Children

The following elements occur in callout: address, anchor, bibliolist, blockquote, bridgehead, calloutlist, dialogue, drama, epigraph, equation, example, figure, formalpara, glosslist, indexterm (db.indexterm.endofrange), indexterm (db.indexterm.singular), indexterm (db.indexterm.startofrange), informalequation, informalexample, informalfigure, informaltable, itemizedlist, literallayout, mediaobject, note, orderedlist, para, poetry, procedure, qandaset, remark, revhistory, sidebar, simpara, simplelist, table, task, variablelist.


bridgehead		calloutlist