Admonitions: Tips, hints, and Warnings.Admonitions are set off from the main body of the text. Use these sparingly, as they disturb the flow of the writing, but do not be afraid to use them where necessary. Just make sure they are necessary when you do use them.
We have settled on a preliminary order of importance for these elements, which differs from that explained in the Duck Book. Note that this particular order is for KDE Documentation only, and use your own judgement which is the most appropriate element if your situation differs from those outlined.
<warning>Use warning when data loss could occur if you follow the procedure being described.
<caution>A note of caution. Use this for example when the reader may lose easily recovered or replaceable information (e.g. user settings), or when they could cause data loss if they do not correctly follow the procedure being outlined.
<important>When there is no danger of data loss, but you wish to make clear to the reader a consequence that isn't immediately obvious (e.g. when changing the font for one instance of a program also changes the default setting, and this isn't clear from the GUI.)
<note>Information the user should be aware of, but is peripheral to the actual task being described.
<tip>When you are giving a hint to make things easier or more productive for the reader.
<footnote id="">Use very sparingly for things that really are footnotes. An example might be to note that the situation being described will be changing at some currently unknown future time. Most footnotes would better be marked up as notes, or tips.
<footnoteref linkend="">You can refer to a footnote more than once, by using this element to refer to its unique id. The footnote does not need to be in the same chapter. Use this very sparingly.