Shaun McCance
shaunm@gnome.org 2008-2009
Include notes, tips, warnings, and other parenthetical information.

# Anmerkungen

    mal_block_note = element note {
      attribute style { xsd:NMTOKENS } ?,
      attribute * - (mal:* | local:*) { text } *,

      mal_block_title ?,
      mal_block +
    }

The `note` element allows you to insert parenthetical block-level content into your document. Notes are visually distinct blocks, allowing readers to skip them or focus on them, depending on their needs. You can use notes to give tips, warn readers of potentially dangerous operations, point out known bugs, or otherwise provide additional information without interfering with the main text of your document.

# Anmerkungen

The `note` element contains an optional title element and any general block content.

The `note` element can occur in any general block context, including inside pages, sections, and certain block elements.

The `style` attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.

The following style hints are recommended:

`advanced` | information that advanced users may find useful
`bug` | a note about a known bug in the software
`important` | important information highlighted in a note
`tip` | a general tip that may help the reader perform an operation better
`warning` | a warning to the reader about a potentially dangerous operation

The `note` element can have attributes from external namespaces. See for more information on external-namespace attributes.

# Beispiele

Insert a basic note into your document:

<note> <p>Information in this section is non-normative.</p> </note>

Information in this section is non-normative.

Fügen Sie einen Hinweis mit zusätzlichen Informationen für fortgeschrittene Leser hinzu:

<note style="advanced"> <p>The Mallard schema is maintained in RELAX-NG Compact Syntax in code blocks embedded within the specification.</p> </note>

The Mallard schema is maintained in RELAX-NG Compact Syntax in code blocks embedded within the specification.

Erwähnen Sie einen bekannten Fehler, dem der Leser wahrscheinlich auch begegnen wird:

<note style="bug"> <title>Cannot Save Files</title> <p>Due to <link href="http://bugs.example.com/1234">bug #1234</link> you cannot actually save files. If you try to save your files, the application will crash. We recommend memorizing all your data on a regular basis.</p> </note>

## Cannot Save Files

Due to bug #1234 you cannot actually save files. If you try to save your files, the application will crash. We recommend memorizing all your data on a regular basis.

Highlight a vital piece of information to ensure readers see it even when skimming a document:

<note style="important"> <title>Supply Your Name and Email Address</title> <p>Before making any commits to a git repository, make sure to supply your name and email address so that your commits are correctly attributed.</p> <code> git config --global user.name <var>full_name</var> git config --global user.email <var>email_address</var></code> </note>

## Fügen Sie Ihren Namen und Ihre E-Mail-Adresse hinzu

Bevor Sie irgendetwas in einen Git-Softwarebestand einspielen, stellen Sie bitte sicher, dass Sie Ihren Namen und Ihre E-Mail-Adresse hinzugefügt haben. Nur so können Ihre Einspielungen korrekt zugeordnet werden.

`git config --global user.name full_name git config --global user.email email_address`

Provide a helpful but non-essential tip:

<note style="tip"> <p>Press <keyseq><key>Ctrl</key><key>J</key></keyseq> to jump to the currently playing track.</p> </note>

Drücken Sie Strg J, um zum gegenwärtig abgespielten Titel zu springen.

Warnen Sie den Benutzer vor gefährlichen Operationen:

<note style="warning"> <p>There is no way to recover files deleted with the <cmd>shred</cmd> command.</p> </note>

Es gibt keine Möglichkeit, mit dem shred-Befehl gelöschte Dateien wiederherzustellen.

# Processing Expectations

Notes are displayed as block elements, with each of their child elements being interpreted as block elements. When present, the title should be displayed in a way that makes it clear that it is the title of the block. Notes should have a border, background color, or other styling effect to distinguish them from the surrounding block content. Notes often use an icon to identify what type of note is being displayed.

# Vergleich mit anderen Formaten

The `note` element is similar to the `caution`, `important`, `note`, `tip`, and `warning` elements in DocBook. Rather than use separate elements, Mallard uses single `note` element which can be specialized and extended through style hints. This document recommends the style hints `advanced` and `bug`, which have no counterpart in DocBook. This document does not recommend separate `caution` and `warning` types, as there is rarely a useful distinction in practice.