MEP-0002

Mallard provides an info element that can be placed at the beginning of a page or section element and may contain any number of informational elements to provide automatic linking, alternate titles, credits and copyright information, and much more.

Sometimes it's useful to provide some of this information for a smaller portion of a page. For example, you may wish to credit the programmer who contributed a code block, or the illustrator who created an image. You might also want to provide alternate titles, even without linking, as these can be used by extensions such as UI Expanders.

This page proposes allowing the info element as an optional first element in any block element that contains other block elements, as well as any block elements with structured content. As of Mallard 1.0, that includes media, comment, example, figure, listing, note, quote, synopsis, list, steps, terms, tree, and table.

As with the existing info element, there are no processing expectations associated with the info element used on block elements. Certain informational elements may introduce processing expectations of their own. In Mallard 1.0, the only informational elements that normatively affect page processing are related to linking. This page does not propose adding block elements to automatic linking (although this proposal would be a prerequisite for doing so).

Specify that a code block may be reused under the terms of the MIT license as published by the OSI.

<listing>
<info>
<license href="http://opensource.org/licenses/MIT"/>
</info>
<code><![CDATA[
def match_locale(extrange, locale):
    # Extended filtering for extended language ranges as                                                    
    # defined by RFC4647, part of BCP47.                                                                    
    # http://tools.ietf.org/html/rfc4647#section-3.3.2                                                      
    rangelist = [x.lower() for x in extrange.split('-')]
    localelist = [x.lower() for x in locale.split('-')]
    if rangelist[0] not in ('*', localelist[0]):
        return False
    rangei = localei = 0
    while rangei < len(rangelist):
        if rangelist[rangei] == '*':
            rangei += 1
            continue
        if localei >= len(localelist):
            return False
        if rangelist[rangei] in ('*', localelist[localei]):
            rangei += 1
            localei += 1
            continue
        if len(localelist[localei]) == 1:
            return False
        localei += 1
    return True
]]></code>
</listing>

Give credit to illustrators and videographers.

<media type="image" src="graph.png">
  <info>
    <credit type="illustrator copyright">
      <name>Rupert</name>
      <email>rupert@example.com</email>
      <years>2013</years>
    </credit>
  </info>
</media>

<media type="video" src="presentation.webm">
  <info>
    <credit type="videographer copyright">
      <name>Wanda</name>
      <email>wanda@example.com</email>
      <years>2013</years>
    </credit>
  </info>
</media>

Provide an alternate title for when a figure is collapsed using UI Expanders.

<figure ui:expanded="false">
  <info>
    <title type="ui:collapsed">Show Chart</title>
  </info>
  <title>Chart</title>
  <media type="image" src="chart.png"/>
</figure>

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 proposal adds an element where a block element may be expected. Normally, if a new block element were to be added, its fallback behavior would be subject to the default block context fallback behavior. This behavior is mostly suitable for this addition, although there is potential for a multi-purpose element to be accidentally processed in restricted block context.

However, the processing expectations for the info element explicitly say "If an info element appears in any context other than as the first element of a page or section, it is ignored." Therefore, the fallback behavior for any conformant processor that does not implement this proposal is to ignore the additional element, which is the desired behavior.

This page also proposes allowing the info element in list and table elements. These elements do not take block content, but rather have structured content specific to each element. None of these elements specifies the fallback behavior for unrecognized elements. All known implementations ignore unrecognized elements, so this change is considered safe.

Docbook 5 allows the generic info element to be used on many block-level elements, similar to this proposal. DocBook 4 contained more specialized info elements, including the blockinfo element for many block elements and the objectinfo element for media objects.

DITA does not contain an element to record metadata about block elements, and only allows the prolog elements on topic and derivative elements.