2.3. Admonitions

There are five types of admonitions in DocBook: Caution, Important, Note, Tip, and Warning.

All of the admonitions have the same structure: an optional Title followed by paragraph-level elements. The DocBook DTD does not impose any specific semantics on the individual admonitions. For example, DocBook does not mandate that Warnings be reserved for cases where bodily harm can result.

2.3.1. Creating Notes, Tips, Cautions, Importants, and Warnings

There are several ways to bring attention to text within a document. A Note is used to bring additional information to the users' attention. A Tip is used to show the user helpful information or another way to do something. A Caution is used to show the user they must be careful when attempting a certain step. An Important tag set can be used to show the user a piece of information that should not be overlooked. While this information may not change anything the user is doing, it should show the user that this piece of information could be vital. A Warning is used to show the reader that their current setup will change or be altered, such as files being removed, and they should not choose this operation unless they are alright with the consequences.

The following lines of code will show the basic setup for each case as mentioned above, along with an example of how it would be displayed in the HTML.


<note>
<title>Note</title>
<para>Body of text goes here.</para>
</note>

[Note]Note

Body of text goes here.


<tip>
<title>Tip</title>
<para>Body of text goes here.</para>
</tip>

[Tip]Tip

Body of text goes here


<caution>
<title>Caution</title>
<para>Body of text goes here.</para>
</caution>

[Caution]Caution

Body of text goes here.


<important>
<title>Important</title>
<para>Body of text goes here.</para>
</important>

[Important]Important

Body of text goes here.


<warning>
<title>Warning</title>
<para>Body of text goes here.</para>
</warning>

[Warning]Warning

Body of text goes here.