Highlights

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

Use the hi element to highlight added or changed text, such as when building up a code example. Use the ins and del style hints for added and deleted text, such as in a diff.

Notes

The hi element can contain a mixture of text and any general inline elements.
The hi element can occur in any general inline context, including inside most inline elements, some basic block elements, and certain informational elements.
The hi element can link to other pages or documents. See Ubiquitous Linking for more information.
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:

ins

Text that has been inserted

del

Text that has been deleted
The hi element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

From the Ten Minute Tour, create a basic example of a Mallard page, then use hi to show another complete example with added content.

<code><![CDATA[
<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="planting">
<title>Planting Beans</title>
</page>]]></code>
  <code><![CDATA[
<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="planting">
]]><hi><![CDATA[<info>
  <link type="guide" xref="index"/>
</info>]]></hi><![CDATA[
<title>Planting Beans</title>
</page>]]></code>

<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="planting">
<title>Planting Beans</title>
</page>

<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="planting">
<info>
  <link type="guide" xref="index"/>
</info>
<title>Planting Beans</title>
</page>

Processing Expectations

Highlighted text is typically rendered with a colored background in environments where that is possible. Processing tools may change the color or use different presentations based on style hints.

This specification recommends two style hints: ins for inserted text and del for deleted text. Inserted text typically has a green background. Deleted text typically has a red background, sometimes with a strikethrough. When converting to HTML, processing tools should use the semantic ins and del elements.

Comparison to Other Formats

DocBook does not have an element for highlighting text. The emphasis or phrase elements could be used with a role attribute with some tooling work.

DITA does not have an element for highlighting text. The ph could be used with an outputclass attribute with some tooling work, or a custom specialization of the ph element could be used.

HTML has the mark element with similar semantics. HTML also has the ins and del elements for added and deleted text. These are recommended style hints for the hi element in Mallard.

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 hi element. The namespace declarations for this definition are on the page Pages.

mal_inline_hi = element hi {
  mal_inline_hi_attr,
  mal_inline_hi_inline
}
mal_inline_hi_attr = (
  mal_attr_link *,
  attribute style { xsd:NMTOKENS } ?,
  mal_inline_attr,
  mal_attr_external *
)
mal_inline_hi_inline = mal_inline