figure

From Microformats Wiki
Revision as of 15:52, 21 February 2008 by TobyInk (talk | contribs) (Add note about design patterns.)
Jump to navigation Jump to search

figure 0.1

Specification

This is a DRAFT specification.

Author
Toby Inkster (affiliations above)
Acknowledgments
See acknowledgments.

Copyright and patents statements apply.

Introduction

Many HTML documents include supporting images, such as photographs, flow charts, graphs, blueprints or screen captures. These are usually incorporated using the HTML <img> element, however this offers no way of differentiating between such supplementary content and mere decorative images.

Authors often wish to annotate these images with captions or attributions. Currently there is no markup to explicitly associate such text with an image and readers must rely on the proximity of the image and text on the finished rendered page.

This specification aims to allow authors to mark up captions and credits, explicitly associating them with an image.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Format

Root Class

The root class name for a figure is "figure".

Properties

The properties of the figure are represented by elements within the figure. Elements with class names of the listed properties represent the values of those properties.

Required:

  • image (exactly one occurance)

Optional:

  • legend ? (zero or one occurances)
  • credit * (zero or more occurances)
  • subject * (zero or more occurances)

Additionally, an figure MAY contain zero or more links marked up with rel-tag and MAY contain zero or more links marked up with rel-license.

If an element with class "credit" also has class "vcard" then the element SHOULD be considered to be the hcard for a credited person or organisation. Otherwise it MUST be considered as a plain text credit.

If an element with class "subject" also has a class "vcard" then the element SHOULD be considered to be the hcard for the subject of the image - for example a person in a photograph or sketch. If an element with class "subject" also has a class "adr" or "geo" then the element should be considered to be the address or geographic location of the subject of the photo - for example the location of a landscape in a photo or the address of a the building shown in blueprints. If an element with class "subject" also has a class "vevent" then the element should be considered to be the vevent for the subject of a photo - for example a photograph of a sporting event, or a diagramme of a military operation.

The subject, credit, tags and licence may be children of the legend, in which case the text within them forms part of the legend as well as part of the child elements.

Example

<div class="figure">
  <img class="image" src="photo.jpeg" alt="">
  <p class="legend">
    <a rel="tag" href="http://en.wikipedia.org/wiki/Photography">Photo</a> of
    <span class="subject vcard">
      <a class="fn url" href="http://einstein.physics.invalid">Albert Einstein</a>
    </span> by
    <span class="credit">Paul Ehrenfest</span>
  </p>
</div>

Parsed as:

  • Image: photo.jpeg
  • Legend: Photo of Albert Einstein by Paul Ehrenfest
  • Credit: Paul Ehrenfest
  • Subject: Albert Einstein (hCard)
  • Categories: Phtotography
  • License: (unspecified)

Include Pattern and ABBR Pattern

The include pattern MAY be used within figures. As the figure microformat does not specify any properties that are not human-readble, the abbr design pattern SHOULD NOT be used directly within a figure, though it MAY be used within children formatted in accordance to another microformat - e.g. as vevents often use the abbr design pattern to specify their start time, a figure subject formatted as a vevent MAY use the abbr design pattern in accordance with the hcalendar specification.

Minimisation

To simplify markup, a number of shortcuts are explicitly allowed by this specification.

  1. When no "image" class is found within the figure, the first <img> element MUST be taken to be the image.
  2. If the "legend" class is found on the same element as the "image" class (or the image inferred by the previous rule), then the contents of the title attribute MUST be used as the legend.
  3. The "image" and/or "legend" classes may be attached to the same element as the element with the "figure" class.

Examples

The following examples should all be considered equivalent:

<div class="figure">
  <img class="image" src="foo.jpeg" alt="">
  <span class="legend">Foo</span>
</div>
<div class="figure">
  <img src="foo.jpeg" alt="">
  <span class="legend">Foo</span>
</div>
<div class="figure">
  <img class="legend" src="foo.jpeg" alt="" title="Foo">
</div>
<img class="figure legend" src="foo.jpeg" alt="" title="Foo">

Inspiration and Acknowledgments

Copyright

This specification is released into the public domain.

Public Domain Contribution Requirement. Since the author(s) released this work into the public domain, in order to maintain this work's public domain status, all contributors to this page agree to release their contributions to this page to the public domain as well. Contributors may indicate their agreement by adding the public domain release template to their user page per the Voluntary Public Domain Declarations instructions. Unreleased contributions may be reverted/removed.

Patents

This specification is subject to a royalty free patent policy, e.g. per the W3C Patent Policy, and IETF RFC3667 & RFC3668.