Inline Highlight Element
This page proposes adding an inline element that allows you to highlight text that has been added in successive examples, or to otherwise mark text that should stand out.
This proposal is still under consideration. Revisions may still be made based on your input. Discuss this proposal on.
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. Thebuilds 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:
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:
added — content in a diff that has been added, formatted with a green or yellow background
deleted — content in a diff that has been deleted, formatted with a red background and possibly a strikethrough
From the hi to show another complete example with added content., create a basic example of a Mallard page, then use
<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 del element to give screen readers more information.attributes as appropriate. In particular, for deleted text, implementations should use the HTML
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. Thein the 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.
Compatibility and Fallback
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><e:hi>This is added text.</e: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.
Comparison to Other Formats
This section is not yet written. Discuss this proposal on.