DocBook: The Definitive GuideBy Norman Walsh & Leonard Muellner
1st Edition October 1999
1-56592-580-7, Order Number: 5807
652 pages, $36.95 , Includes CD-ROM
NameCallout -- A "called out" description of a marked Area
Content ModelCallout ::= ((CalloutList|GlossList|ItemizedList|OrderedList|SegmentedList| SimpleList|VariableList|Caution|Important|Note|Tip|Warning| LiteralLayout|ProgramListing|ProgramListingCO|Screen|ScreenCO| ScreenShot|Synopsis|CmdSynopsis|FuncSynopsis|FormalPara|Para| SimPara|Address|BlockQuote|Graphic|GraphicCO|MediaObject| MediaObjectCO|InformalEquation|InformalExample|InformalFigure| InformalTable|Equation|Example|Figure|Table|MsgSet|Procedure| Sidebar|QandASet|Anchor|BridgeHead|Comment|Highlights|Abstract| AuthorBlurb|Epigraph|IndexTerm)+)
AreaRefs IDREFS Required
The start-tag is required for this element. The end-tag is optional, if your SGML declaration allows minimization.
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.
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.
CallOuts 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 Callouts are likely to deserve special consideration for interchange. See Appendix F. 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.
These elements contain Callout: CalloutList.
The following elements occur in Callout: Abstract, Address, Anchor, AuthorBlurb, BlockQuote, BridgeHead, CalloutList, Caution, CmdSynopsis, Comment, Epigraph, Equation, Example, Figure, FormalPara, FuncSynopsis, GlossList, Graphic, GraphicCO, Highlights, Important, IndexTerm, InformalEquation, InformalExample, InformalFigure, InformalTable, ItemizedList, LiteralLayout, MediaObject, MediaObjectCO, MsgSet, Note, OrderedList, Para, Procedure, ProgramListing, ProgramListingCO, QandASet, Screen, ScreenCO, ScreenShot, SegmentedList, Sidebar, SimPara, SimpleList, Synopsis, Table, Tip, VariableList, Warning.
Back to: DocBook: The Definitive Guide
© 2001, O'Reilly & Associates, Inc.