MEP-0017

Mallard allows for flexible, non-linear page organization using its system of informational links. However, for certain applications, it can be useful to reference a set of pages without those pages being grouped in an actual guide page that users can navigate to. For example, a help system integrated into an app may want to show all topics relevant to a particular screen. Or, a faceted navigation system may need to filter topics based on user selections. These are both real-world experimental developments that led to this proposal.

This page proposes adding an informational tags element, which may be used in any info element. The tags element contains a space-separated list of tags as text content. No inline markup is allowed in the text content. Tags provide a lightweight taxonomy that is not tied to page organization or linking. This may be used by extensions or future Mallard features, but this proposal does not address specific future uses.

Each tag is written in the form context:value. For example, in a collection of tutorials about different technologies, the tag context tech might be used to indicate the technology each tutorial addresses. Example tags in that context would be tech:html, tech:gtk, and tech:mallard. Tag contexts and values are all user-defined.

The tags in a particular info element apply only to the element containing that info element, and not to any sections or formal elements contained in that element. If there are multiple tags elements in an info element, those tags are merged, as if those elements were all joined with space characters between.

Tag a help page to indicate that it is relevant to a particular screen or window:

<page>
  <info>
    <tags>screen:settings-power</tags>
  </info>
  <title>Set screen brightness</title>
</page>

Tag a tutorial to indicate that it deals with a particular technology:

<page>
  <info>
    <tags>tech:mallard</tags>
  </info>
  <title>Mallard tutorial</title>
</page>

Use multiple tags in a space-separated list:

<page>
  <info>
    <tags>tech:mallard tech:svg</tags>
  </info>
  <title>Mallard and SVG</title>
</page>

Equivalently, use multiple tags in separate elements:

<page>
  <info>
    <tags>tech:mallard</tags>
    <tags>tech:svg</tags>
  </info>
  <title>Mallard and SVG</title>
</page>

Tags should not be translated by default. However, since they are in text content rather than attributes, the default behavior for ITS will be to translate tags. ITS rules for Mallard should mark the tags element as untranslated.

<its:translateRule translate="no" selector="//mal:tags"/>

Occasionally, an author might decide certain tags should be translated, such as tags specific to a language or region. In these cases, the author can put the translatable tags in a separate tags element and mark it as translatable with local ITS markup.

The first proposed use of tags was in an experimental extension for faceted navigation. This use of tags had them in an extension namespace. The system for tagging pages, however, was generally useful enough to live in the Mallard core where multiple features and extensions can take advantage of it.

The first proposal did use the context-value (or key-value) concept found in this proposal, but it split the context and value into separate attribute values. We later considered the syntax in this proposal, somewhat mirroring test tokens in Mallard Conditionals, but putting them in an attribute. Finally, we switched to putting the tags in text content, mostly because the Ducktype syntax is easier that way.

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 info element is that is is ignored. This proposal doesn't make any recommendations for navigation or other features using tags. Extensions or future Mallard features may do so, and those features may have loss of functionality in fallback.

DocBook provides the subjectset, subject, and subjectterm elements, which can be used to tag documents and certain other elements according to some controlled taxonomy. Multiple subject elements can be used with different scheme attributes to tag according to diifferent taxonomies. DocBook subjects are more intended for tagging documents according to an external taxonomy, whereas this proposal is intended for tagging pages within a document with an ad hoc taxonomy. DocBook subjects use multiple nested elements, whereas this proposal prefers a single element with a simple inline syntax.

DITA provides the category element to tag topics. There is no specific mechanism to identify categories with particular taxonomies. Unlike this proposal, which prefers short tag identifiers, DITA categories are often used with text intended for readers to view, and some tools even make automatic navigation using these labels.