MEP-0004

Mallard provides title and desc elements for pages and sections. It even allows for multiple titles for different purposes, and pending MEP-0008, it will allow multiple descriptions for different purposes. These can be used to create rich text links. For some designs and extensions, it's useful to associate an image with a page or section. For example, a page may provide a representative screenshot or an icon that indicates its contents,and this could be shown along with the topic link from a guide page.

Additionally, some extensions may display galleries of images or videos that open the media in a popup or fullscreen window. These extensions can benefit from allowing a separate thumbnail image for the media objects that is distinct from a scaled-down version of the image or a randomly selected video frame.

This page proposes allowing zero or more thumb elements in any info element. The thumb element has no content, and it may contain the following attributes:

The type and role attributes work similarly to the same attribute on link titles. Looking up the correct thumbnail would follow the new lookup rules defined in MEP-0018: Type-and-Role Data.

In some cases, it may be useful to provide alternative sizes of the same thumbnail for the same role. In additional to using the role attribute, implementations may check the width and height attribute to select a thumbnail that has the most optimal dimensions.

In addition to using thumbs for pages and sections, a thumb element for a video-type media element should be used as a poster image for the video, instead of the current non-standard convention of using a child media element with the style attribute set to "poster".

Use a scaled down screenshot as a thumbnail for a page.

<page xmlns="http://projectmallard.org"
      id="network-panel">
  <info>
    <thumb src="network-panel-screenshot.png" width="300" height="200"/>
  </info>
  ...
</page>

Provide multiple thumbnails with roles for a page to match the roles of the link titles.

<page xmlns="http://projectmallard.org"
      id="network-panel">
  <info>
    <title type="link" role="topic">Network Panel</title>
    <thumb src="network-panel-big.png" role="topic" width="300" height="200"/>
    <title type="link" role="gallery">Network</title>
    <thumb src="network-panel-small.png" role="gallery" width="150" height="100"/>
  </info>
  ...
</page>

Provide a thumbnail image to be used for a video.

<media src="open-apps.webm" type="video" width="300" height="200">
  <info>
    <thumb src="open-apps-thumb.png" width="300" height="200"/>
  </info>
</media>

This proposal provides no way to provide alternative text for thumbnails. However, the title and desc of the parent elements is available. Implementations should take care to either set alternative text from these elements or to show the thumbnails in a way that obviates the need for alternative text, such as with background images.

Thumbnails, like all media objects, may contain translatable material, such as user interface text in a screenshot. Translation tools should allow thumbnails to be translated using the same mechanism used for media elements.

Yelp contains a number of features that use thumbnails provided by similar elements in an experimental namespace. When used on media elements, those features allow a uix:caption element to be a child of the uix:thumb element. The uix:caption element, in turn, may contain a title and desc element. (The extra wrapper element is necessary for proper fallback processing.)

The title and desc provided by uix:caption are used alongside thumbnails, which open the full media object in a popup. Because this proposal depends on MEP-0002 to provide an info element in block elements, a title and desc can simply be placed in that info element instead, possibly with role attributes.

The original version of this proposal placed the thumb element in the ui namespace from Mallard UI. Though there are many uses for thumbnails in UI extensions, there are also uses for it in other potential extensions or in core Mallard features. Consequently, we decided to put the thumb element in Mallard core.

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.

This page adds an informational element. Unknown informational elements are ignored by non-supporting tools, so pages using this extension will be processed as well as can be expected with non-supporting tools. It's worth noting that, because this proposal depends on MEP-0002 to add info elements to block elements, the compatiblity notes of that MEP apply to the info element. Inside the info element, however, there are no compatibility issues.

DocBook allows any number of mediaobject elements inside info elements, although there are no processing expectations for these. It's possible to create some special stylings that use these elements for thumbnails.

DITA does not have a mechanism for providing thumbnails, but a specialization could do so by specializing the data element in the prolog of a topic.