Notes

This is a draft specification. It is likely that changes will still be made before the final specification.

Use the note element 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.

Notes

The note element contains an optional info element, 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 External Namespaces for more information on external-namespace attributes.

Examples

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.

Include a note with extra information for advanced readers:

<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.

Mention a known bug the reader is likely to encounter:

<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>
  <screen>
git config --global user.name <var>full_name</var>
git config --global user.email <var>email_address</var></screen>
</note>

Supply Your Name and Email Address

Before making any commits to a git repository, make sure to supply your name and email address so that your commits are correctly attributed.

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>

Press Ctrl+J to jump to the currently playing track.

Warn the reader about dangerous operations:

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

There is no way to recover files deleted with the shred command.

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.

The optional info element can provide metadata for the note, such as attributions, licensing information, and additional titles for extensions. It is not displayed directly.

Comparison to Other Formats

The note element is similar to the caution, important, note, tip, and warning elements in DocBook. Rather than use separate elements, Mallard uses a 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.

The note element is similar to the note element in DITA. Like DITA, Mallard uses a single note element and distinguishes different types of notes using an attribute. The Mallard note takes block content, optionally with a title. The DITA note can take block or inline content.

Schema

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the note element. The namespace declarations for this definition are on the page Pages.

mal_block_note = element note {
  mal_block_note_attr,
  mal_info ?,
  mal_block_title ?,
  mal_block_note_content +
}
mal_block_note_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_block_attr,
  mal_attr_external *
)
mal_block_note_content = mal_block