MEP: The thumb Element

Attaching a MEP for adding a thumb element to info elements, including
in the info of block elements as provided by MEP0002. This is the
groundwork for finally formalizing a number of extensions in Yelp, such
as the hover links, image tile links, and media overlays.

Text version of the proposal below. If you're using uix:thumb in Yelp
right now, note that media thumbs go into an info element, allowed by
MEP0002, and there's no uix:caption child. Instead, titles and descs can
be provided in the containing info element.


== Background

Mallard provides title and desc elements for pages and sections, and
even allows for multiple titles 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 or 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.


== Proposal

This page proposes allowing zero or more ui:thumb elements in any info
element, where the namespace of the ui:thumb element is the Mallard UI
namespace:

http://projectmallard.org/ui/1.0/

The ui:thumb element has no content, and it may contain the following
attributes:

src
  The URL of the media file being used as a thumbnail.
width
height
  The width and height of the file referenced by the src attribute.
mime
  The MIME type of the thumbnail.
role
  A role, similar to the role on link titles, that may be used to
  select the most appropriate thumbnail.

Unlike the media element, the ui:thumb element does not take a type
attribute, because it is assumed that thumbnails will be images. If
this is a problem in the future, a type attribute can easily be added,
since it defaults to "image" anyway.

The role attribute works similarly to the role attribute on link
titles. It may be used to select the most appropriate thumbnail from a
list of alternatives. When thumbnails are used for links such as from a
links element, the same logic used to select a link title should be
used to select a thumbnail. Other uses of thumbnails may specify roles
to prefer.

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.


== Examples

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

<page xmlns="http://projectmallard.org"
      xmlns:ui="http://projectmallard.org/ui/1.0/"
      id="network-panel">
  <info>
    <ui: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"
      xmlns:ui="http://projectmallard.org/ui/1.0/"
      id="network-panel">
  <info>
    <title type="link" role="topic">Network Panel</title>
    <ui:thumb src="network-panel-big.png" role="topic" width="300"
height="200"/>
    <title type="link" role="gallery">Network</title>
    <ui: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>
    <ui:thumb src="open-apps-thumb.png" width="300" height="200"/>
  </info>
</media>


== Accessibility

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.


== Internationalization

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.


== Alternatives

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.

Although thumbnails will be useful for a number of Mallard UI features,
they may also be useful for designs that are accomplished only with the
style hint, or from other extensions. It may be better to add the thumb
element to Mallard core.


== Compatibility and Fallback

This proposal makes no backwards-incompatible changes. That is, 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.


== Comparison to Other Formats

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.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: mep-ui-thumbs.page
Type: text/x-mallard-page+xml
Size: 9355 bytes
Desc: not available
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20140204/f6420cdd/attachment.bin>