73 lines
2.7 KiB
ReStructuredText
73 lines
2.7 KiB
ReStructuredText
|
.. _notices:
|
||
|
|
|
||
|
|
Notices: Notes, Cautions, Warnings, and Dangers
|
||
|
|
###############################################
|
||
|
|
|
||
|
|
We use four special types of notices: notes, cautions, warnings, and
|
||
|
|
dangers. Here are some specific rules and tips with regard to these
|
||
|
|
notices:
|
||
|
|
|
||
|
|
* Do not use a notice directly after a heading. Notices must follow a
|
||
|
|
variant of body text.
|
||
|
|
* Avoid back-to-back notices.
|
||
|
|
* To improve readability, rewrite content to eliminate multiple
|
||
|
|
notices in a single module.
|
||
|
|
* If there is no clean way to avoid using back-to-back notices, use a
|
||
|
|
different style or multiple paragraphs, for example, combine two
|
||
|
|
notes into one or separate them with body text.
|
||
|
|
|
||
|
|
Notes
|
||
|
|
*****
|
||
|
|
|
||
|
|
Use notes sparingly. Avoid having more than one note per subsection. If
|
||
|
|
you exceed this number consistently, consider rewriting the notes as
|
||
|
|
main body text. Example:
|
||
|
|
|
||
|
|
.. note::
|
||
|
|
A note is supposed to provide supplemental information, not
|
||
|
|
emphasized information.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
Cautions, Warnings, and Dangers
|
||
|
|
*******************************
|
||
|
|
|
||
|
|
Tell readers what will happen if they do not heed cautions or warnings,
|
||
|
|
circuits will fry, electrical shock may kill you, etc.
|
||
|
|
|
||
|
|
* Use "Caution" to identify hazards resulting in property damage
|
||
|
|
accidents, including data loss. Also use "Caution" to alert against
|
||
|
|
unsafe practices.
|
||
|
|
* Use "Warning" and "Danger" for property damage accidents only if
|
||
|
|
personal injury risk appropriate to these levels is also involved.
|
||
|
|
|
||
|
|
These are examples of typical notices, the correct syntax and the
|
||
|
|
conditions for their usage:
|
||
|
|
|
||
|
|
.. note::
|
||
|
|
Notes are ancillary bits of information, subordinate to the main
|
||
|
|
flow. Reserve the note tag for information that does not readily
|
||
|
|
flow with the main text but which you want to set apart for one
|
||
|
|
reason or another. Notes should be relatively short. If there is
|
||
|
|
more than enough information to warrant a short paragraph,
|
||
|
|
consider rewriting the note as body text.
|
||
|
|
|
||
|
|
.. caution::
|
||
|
|
Cautions are low-level hazard messages that alert the user of
|
||
|
|
possible equipment, product, and software damage, including loss
|
||
|
|
of data. Cautions typically appear as a yellow triangle with a
|
||
|
|
black exclamation point.
|
||
|
|
|
||
|
|
.. warning::
|
||
|
|
Warnings are mid-level hazards (more serious than cautions) that
|
||
|
|
are likely to cause product damage as well as bodily injury to
|
||
|
|
humans. Warnings may appear in a black triangle with orange hazard-
|
||
|
|
specific graphics for warnings (or with the colors reversed). The
|
||
|
|
most common warning is for electrical hazards, but there are many
|
||
|
|
other hazard-specific graphics.
|
||
|
|
|
||
|
|
.. danger::
|
||
|
|
Dangers are high-level hazards that are likely to cause product
|
||
|
|
damage as well as bodily injury and even death to humans. Dangers
|
||
|
|
use a red triangle with white (and black) hazard-specific
|
||
|
|
graphics, the same as found on warnings.
|