MEP-0009

When writing developer documentation or documentation for file formats, it is common to successively build up example code, with each code block showing parts of what was presented before, but with new code or content added. When doing this, it’s useful to highlight the new content.

This happens even on the Mallard web site. The Ten Minute Tour builds up an example Mallard document by adding new markup and content, and highlights the new text in each example.

To accomplish this, the Yelp stylesheets for Mallard have supported the experimental hi element since before Mallard 1.0 was even final. This element is supported in the experimental namespace:

http://projectmallard.org/experimental/

This page proposes adding the hi element to the core Mallard namespace, making it required for implementations to support. The recommended processing would be to highlight the text with a background color, generally yellow by default.

The specification could also recommend some style hints, such as:

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>

Using background colors or other visual presentations to render text will not be useful to readers using a screen reader. For added content, the worst case will be that all content will be read, with no indication of what content is new. For deleted text, however, the reading could very confusing if there is no indication of which content is deleted and which remains.

When converting to HTML, implementations should take care to use semantic HTML element wherever possible, and to set ARIA attributes as appropriate. In particular, for deleted text, implementations should use the HTML del element to give screen readers more information.

As with any text rendered with a different background or foreground color, implementations should ensure the colors do not cause problems for readers with low vision or color blindness. The minimum contrast guideline in the Web Content Accessibility Guidelines provides a good method of ensuring text is legible. Implementations that use green and red to indicate added and deleted text should use shades of these colors that color blind individuals can distinguish.

We considered naming the element mark, following the name used by HTML. However, the HTML mark element is not semantically equivalent, although it may sometimes be a suitable output element for a Mallard hi element.

Earlier versions of this MEP recommended the style hints added and deleted. These were changed to ins and del to mimic the similar HTML elements.

This proposal makes no backwards-incompatible changes. Any page written in a version prior to the implementation of this proposal will work exactly the same in a processing tool that implements this proposal.

The fallback behavior for a new inline element is to process the contents of the element as inline content. When using hi to mark up added or inserted text, this is a reasonable fallback behavior. When using it to mark up deleted text, this could be very confusing. Only use hi for deleted text if you are sure it will only be processed by a supporting tool.

The Yelp stylesheets have supported hi in an experimental namespace for a long time. If you want to ensure highlighting in older tools, you can use both elements:

<hi><hi>This is added text.</hi></hi>

Implementations that want to continue to support both may provide a special case for this to avoid outputting excess markup. For ease of implementation, the hi element in the core namespace should wrap the e:hi element in the experimental namespace.

Note that the Yelp stylesheets never supported deleted text for the e:hi element, so this is not a suitable compatibility workaround for that case.

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, which this proposal treats as recommended style hints on the proposed hi element.