[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:

• A Note is for information that should be heeded by all readers.

• An Important element is a variation on Note.

• A Caution is for information regarding possible data loss or software damage.

• A Warning is for information regarding possible hardware damage or injury to life or limb.

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

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.

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]