Chapter 2. User's Guide for the DocBook DTD

[Prev] [Next]


2.3 Admonitions and Sidebars

The admonition and Sidebar elements allow you to set off information that has a special context for proper understanding by readers. Note, Important, Caution, and Warning set off information that is, for whatever reason, more important than the surrounding text. Tip sets off information meant for novice readers who need additional suggestions to work effectively. Sidebar is like a boxed section within a magazine article: it sets off information that is related to the main topic but need not be presented in-flow.

In computer documentation, different levels of admonition have precise meanings related to the consequences of ignoring the contained information. However, these meanings vary from one company to another. Here is a fairly mainstream summary of these meanings:

DocBook does not have an element for Danger, which some hardware and manufacturing manuals require, but which is uncommon in software documentation.

[Graphic: Figure from the text]

All the admonition elements contain an optional Title and one or more object-level elements from the %admon.mix; mixture. If no Title is supplied a title should be generated by formatting applications.

[Graphic: Figure from the text]

Sidebar contains an optional Title and TitleAbbrev, and any number of object-level elements from the %sidebar.mix; mixture.


[Prev] Paragraphs and Text Blocks
[Next] Lists, MsgSets, and Procedures
[User's Guide Home] [Davenport Group Home]