figure: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
No edit summary
m (Replace <entry-title> with {{DISPLAYTITLE:}})
 
(53 intermediate revisions by 8 users not shown)
Line 1: Line 1:
= figure/0.1 =
{{DISPLAYTITLE:figure 0.3}}
{{Template:DraftSpecification}}
 
{{TOC-right}}


== Specification ==
== Specification ==
'''This is a DRAFT specification.'''


<div class="vcard">
<div class="vcard">
Line 7: Line 12:
: <span class="fn">[[User:TobyInk|Toby Inkster]]</span> (<span class="url">http://tobyinkster.co.uk/</span>)
: <span class="fn">[[User:TobyInk|Toby Inkster]]</span> (<span class="url">http://tobyinkster.co.uk/</span>)
</div>
</div>
; Author: Toby Inkster (affiliations above)
; Authors
: Toby Inkster (affiliations above)
: <div class="vcard"><span class="fn">[[User:Csarven|Sarven Capadisli]]</span> (<span class="url">http://csarven.ca/</span>)</div>


; Acknowledgments: See [[figure#Inspiration_and_Acknowledgements|acknowledgments]].
; Acknowledgements: See [[figure#Inspiration_and_Acknowledgements|acknowledgements]].


[[figure#Copyright|Copyright]] and [[figure#Patents|patents]] statements apply.
[[figure#Copyright|Copyright]] and [[figure#Patents|patents]] statements apply.
Line 17: Line 24:
Many HTML documents include supporting images, such as photographs, flow charts, graphs, blueprints or screen captures. These are usually incorporated using the HTML &lt;img> element, however this offers no way of differentiating between such supplementary content and mere decorative images.
Many HTML documents include supporting images, such as photographs, flow charts, graphs, blueprints or screen captures. These are usually incorporated using the HTML &lt;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.
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.  


This specification aims to allow authors to mark up captions and credits, explicitly associating them with an image.
This specification ''is not'' intended as a method for marking up ''all'' images on web pages — the HTML <code><nowiki><img/></nowiki></code> element is adequate for decorative and many other images. This specification is intended to be used for images that add or clarify information to the article's text.


{{rfc-2119-intro}}
{{rfc-2119-intro}}
Line 25: Line 32:
== Format ==
== Format ==


=== Root Class ===
=== Properties ===
The root class name for a figure is "figure".
 
<div style="float:right;width:50%;font-size:85%;margin:0 0 1em 1em">
====Key====
Based on Perl's [http://www.perl.com/doc/manual/html/pod/perlre.html standard quantifiers]:
{| border="1" cellpadding="2"
| '''bold''' {1} || {{must}} be present exactly once
|-
| ''italic''<nowiki>*</nowiki> || {{optional}}, and {{may}} occur more than once
|-
| + || {{must}} be present, and {{may}} occur more than once
|-
| ? || {{optional}}, but {{must-not}} occur more than once
|-
| [square brackets] || list of common values
|-
| (parentheses) || data format
|-
| # || comment
|-
| ! || awaiting documentation
|}
</div>
 
* '''figure''' {1}
** '''image''' {1}
** '''legend''' +
** ''credit'' (text | [[hcard|hCard]])*
** ''subject'' (text | [[hcard|hCard]] | [[geo]] | [[adr]] | [[hcalendar|hcalendar event]])*
 
Additionally, an figure {{may}} contain zero or more links marked up with [[rel-tag]].
 
Please note that the "legend" element should contain what would normally be called a "[http://en.wiktionary.org/wiki/Caption caption]". The term "legend" is used in this specification instead of "caption" in order to maintain parity with the element names used in HTML5. (In turn HTML 5 uses &lt;legend> instead of &lt;caption> to avoid triggering table layouts in legacy browsers.)
 
The subject, credit and tags 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.
 
====Embedded Microformats====
 
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 the person depicted by 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 [[adr|address]] or [[geo|geographic location]] of the subject of the picture - 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 [[hcalendar|vevent]] for the subject of a figure - for example a photograph of a sporting event, or a diagram of a military operation.
 
====Design Patterns Used====
 
The [[include-pattern|include pattern]] {{may}} be used within figures.
 
As the figure microformat does not specify any properties that are not human-readable, the [[abbr-design-pattern|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 [[hcalendar|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.


=== Properties ===
=== Minimisation ===
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:'''
To simplify markup, a number of shortcuts are explicitly allowed by this specification.
* '''image''' (exactly one occurance)


Optional:
# When no "image" class is found within the figure, the first &lt;img> element {{must}} be taken to be the image.
* legend ? (zero or one occurances)
# The longdesc attribute {{may}} be used to point to a legend elsewhere on the page in a manner similar to the [[include-pattern|include pattern]]. As with the inclusion, parsers should ignore the pattern if the fragment linked to is an off-page resource.
* credit * (zero or more occurances)
# If the "legend" class is found on the same element as the "image" class (or the image inferred by the previous rule), then the title attribute {{must}} be used as the legend.
* subject * (zero or more occurances)
#* Rationale: some people have questioned the use of the title attribute rather than the alt attribute. The purpose of the figure's legend is to display explanatory text alongside the image. The purpose of the alt attribute is "to serve as content when the element cannot be rendered normally" [http://www.w3.org/TR/REC-html40/struct/objects.html#adef-alt] — i.e. when the image cannot be displayed. Thus the alt and legend fulfil different purposes. Authors are encouraged to consider accessibility carefully when building their page, and supply appropriate alt text in addition to the image's legend.
# If no legend can be found using the legend class or longdesc attribute, then the alt attribute {{must}} be used in its place.
# The "image" and/or "legend" classes may be attached to the same element as the element with the "figure" class.


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]].
=== XHTML Meta Data Profile ===


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.
Authors using the figure microformat {{should}} add a profile link to the XMDP profile. The preferred URL is <tt><nowiki>http://purl.org/uF/figure/draft</nowiki></tt>. For more information on how to link to the profile, see [[profile-uris|Profile URIs]].


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 [[adr|address]] or [[geo|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 [[hcalendar|vevent]] for the subject of a photo - for example a photograph of a sporting event, or a diagramme of a military operation.
<dl class="profile">
<dt id="class">class
<dd>[http://www.w3.org/TR/REC-html40/struct/global.html#adef-class HTML 4 definition of "class".] This profile defines the following class names:
<dl>
<dt id="figure">figure
<dd>A section containing a graphical element which provides information relevant to the document. A figure will include one image and at least one legend. The legend may be implied from the image's <code>longdesc</code> attribute.
<dt id="image">image
<dd>The primary graphical element contained within a section with <code>class="figure"</code>.
<dt id="legend">legend
<dd>A description or explanation for a graphic, intended to be displayed alongside it.
<dt id="subject">subject
<dd>A person, place, event or other thing or concept depicted by a graphic.
<dt id="credit">credit
<dd>A person, organisation or other agent that created, contributed to or supplied a graphic.
</dl>
</dl>


=== Example ===
== Examples ==


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


== Minimisation ==
Parsed as:
 
* '''Image''': photo.jpeg
* '''Legend''': Photo of Albert Einstein by Paul Ehrenfest (photographer)
* '''Credit''': Paul Ehrenfest (hCard)
* '''Subject''': Albert Einstein
* '''Categories''': Photography
 
<pre>
<p class="figure">
  <label style="display:block" class="legend">January sales data</label>
  <img class="image" src="salesdata.png"
  alt="Widget sales have fallen slightly, but widget repair kits have sold well.">
</p>
</pre>
 
Parsed as:
 
* '''Image''': salesdata.png
* '''Legend''': January sales data
 
=== Examples Using Minimisation ===
 
The following examples {{must}} all be considered equivalent:
 
<pre>
<!-- Full (non-minimised) version. -->
<div class="figure">
  <img class="image" src="foo.jpeg" alt="">
  <span class="legend">Foo</span>
</div>
</pre>
 
<pre>
<!-- class="image" can be omitted if the image is the first child of the figure -->
<div class="figure">
  <img src="foo.jpeg" alt="">
  <span class="legend">Foo</span>
</div>
</pre>
 
<pre>
<!-- class="image" can be omitted if the image is the first child of the figure -->
<!-- If the legend and figure are the same node, then use the title attribute as legend -->
<div class="figure">
  <img class="legend" src="foo.jpeg" alt="" title="Foo">
</div>
</pre>
 
<pre>
<!-- class="image" can be omitted if the image is the first child of the figure -->
<!-- If the legend and figure are the same node, then use the title attribute as legend -->
<!-- legend and image properties may be on the figure root element -->
<img class="figure legend" src="foo.jpeg" alt="" title="Foo">
</pre>
 
<pre><nowiki><!-- Use @longdesc to point to a legend outside of the figure root element -->
<div class="figure">
  <img class="image" src="foo.jpeg" longdesc="#the-legend" alt="" />
</div>
<!-- ... -->
<p class="legend" id="the-legend">Foo</p></nowiki></pre>
 
== HTML 5 Considerations ==
 
When used in [http://www.w3.org/html/wg/html5/ HTML 5], any &lt;figure> element has an implied class "figure"; any &lt;legend> element has an implied class "legend". For example, the following HTML 5:
 
<pre>
<figure>
  <img src="foo.jpeg" alt="">
  <legend>Foo</legend>
</figure>
</pre>
 
is interpreted as if it were:


To simplify markup, a number of shortcuts are explicitly allowed by this specification.
<pre>
<figure class="figure">
  <img src="foo.jpeg" alt="">
  <legend class="legend">Foo</legend>
</figure>
</pre>


== Inspiration and Acknowledgments ==
== Inspiration and Acknowledgments ==


[http://www.w3.org/html/wg/html5/ HTML 5 Draft Specification]
This microformat is largely intended to be a simple [http://en.wikipedia.org/wiki/Porting "port"] of HTML 5's <code>&lt;figure></code> construct to other versions of HTML and XHTML.
[[figure-examples]] (various authors)
 
The three required properties (figure, image and caption) are derived from that. The additional properties (credit, subject) are included because this information seems to be commonly supplied in figures "in the wild" in prose even if it is not marked up with wrapper elements.
 
* [http://www.whatwg.org/specs/web-apps/current-work/#the-figure-element HTML 5 Draft Specification: <code style="text-decoration:underline">&lt;figure></code> element]
* [http://theresa.oconnor.cx/2007/08/figure-markup-redux Theresa O'Connor: Figure markup redux]
* [http://www.contentwithstyle.co.uk/Articles/161/figure-microformats/ Matthias Willerich: Figure Microformats]
* [[figure-examples]] (various authors)
 
Other references which were considered:
 
* [http://www.w3.org/MarkUp/html3/figures HTML 3 Specification: Figures] — never caught on, not implemented in browsers.
* [http://www.w3.org/Style/Examples/007/figures.html Bert Bos: figures & captions]
* [http://rjohara.net/server/css-figures-captions/ Robert J O'Hara: Scalable figures and captions with CSS and HTML]
* [http://www.cs.tut.fi/~jkorpela/www/captions.html Jukka Korpela: Image captions on Web pages]


== Copyright ==
== Copyright ==
Line 76: Line 236:
== Patents ==
== Patents ==
{{MicroFormatPatentStatement}}
{{MicroFormatPatentStatement}}
==See also==
*[[figure-examples]]
*[[figure-formats]]
*[[figure-brainstorming]]
*[[figure-issues]]

Latest revision as of 16:22, 18 July 2020

This document represents a draft microformat specification. Although drafts are somewhat mature in the development process, the stability of this document cannot be guaranteed, and implementers should be prepared to keep abreast of future developments and changes. Watch this wiki page, or follow discussions on the #microformats IRC channel to stay up-to-date.

Specification

This is a DRAFT specification.

Authors
Toby Inkster (affiliations above)
Acknowledgements
See acknowledgements.

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.

This specification is not intended as a method for marking up all images on web pages — the HTML <img/> element is adequate for decorative and many other images. This specification is intended to be used for images that add or clarify information to the article's text.

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

Properties

Key

Based on Perl's standard quantifiers:

bold {1} MUST be present exactly once
italic* OPTIONAL, and MAY occur more than once
+ MUST be present, and MAY occur more than once
? OPTIONAL, but MUST NOT occur more than once
[square brackets] list of common values
(parentheses) data format
# comment
! awaiting documentation

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

Please note that the "legend" element should contain what would normally be called a "caption". The term "legend" is used in this specification instead of "caption" in order to maintain parity with the element names used in HTML5. (In turn HTML 5 uses <legend> instead of <caption> to avoid triggering table layouts in legacy browsers.)

The subject, credit and tags 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.

Embedded Microformats

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 the person depicted by 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 picture - 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 figure - for example a photograph of a sporting event, or a diagram of a military operation.

Design Patterns Used

The include pattern MAY be used within figures.

As the figure microformat does not specify any properties that are not human-readable, 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. The longdesc attribute MAY be used to point to a legend elsewhere on the page in a manner similar to the include pattern. As with the inclusion, parsers should ignore the pattern if the fragment linked to is an off-page resource.
  3. If the "legend" class is found on the same element as the "image" class (or the image inferred by the previous rule), then the title attribute MUST be used as the legend.
    • Rationale: some people have questioned the use of the title attribute rather than the alt attribute. The purpose of the figure's legend is to display explanatory text alongside the image. The purpose of the alt attribute is "to serve as content when the element cannot be rendered normally" [1] — i.e. when the image cannot be displayed. Thus the alt and legend fulfil different purposes. Authors are encouraged to consider accessibility carefully when building their page, and supply appropriate alt text in addition to the image's legend.
  4. If no legend can be found using the legend class or longdesc attribute, then the alt attribute MUST be used in its place.
  5. The "image" and/or "legend" classes may be attached to the same element as the element with the "figure" class.

XHTML Meta Data Profile

Authors using the figure microformat SHOULD add a profile link to the XMDP profile. The preferred URL is http://purl.org/uF/figure/draft. For more information on how to link to the profile, see Profile URIs.

class
HTML 4 definition of "class". This profile defines the following class names:
figure
A section containing a graphical element which provides information relevant to the document. A figure will include one image and at least one legend. The legend may be implied from the image's longdesc attribute.
image
The primary graphical element contained within a section with class="figure".
legend
A description or explanation for a graphic, intended to be displayed alongside it.
subject
A person, place, event or other thing or concept depicted by a graphic.
credit
A person, organisation or other agent that created, contributed to or supplied a graphic.

Examples

<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">Albert Einstein</span> by
    <span class="vcard credit">
      <span class="fn">Paul Ehrenfest</span>
      (<span class="role">photographer</span>)
    </span>
  </p>
</div>

Parsed as:

  • Image: photo.jpeg
  • Legend: Photo of Albert Einstein by Paul Ehrenfest (photographer)
  • Credit: Paul Ehrenfest (hCard)
  • Subject: Albert Einstein
  • Categories: Photography
<p class="figure">
  <label style="display:block" class="legend">January sales data</label>
  <img class="image" src="salesdata.png"
  alt="Widget sales have fallen slightly, but widget repair kits have sold well.">
</p>

Parsed as:

  • Image: salesdata.png
  • Legend: January sales data

Examples Using Minimisation

The following examples MUST all be considered equivalent:

<!-- Full (non-minimised) version. -->
<div class="figure">
  <img class="image" src="foo.jpeg" alt="">
  <span class="legend">Foo</span>
</div>
<!-- class="image" can be omitted if the image is the first child of the figure -->
<div class="figure">
  <img src="foo.jpeg" alt="">
  <span class="legend">Foo</span>
</div>
<!-- class="image" can be omitted if the image is the first child of the figure -->
<!-- If the legend and figure are the same node, then use the title attribute as legend -->
<div class="figure">
  <img class="legend" src="foo.jpeg" alt="" title="Foo">
</div>
<!-- class="image" can be omitted if the image is the first child of the figure -->
<!-- If the legend and figure are the same node, then use the title attribute as legend -->
<!-- legend and image properties may be on the figure root element -->
<img class="figure legend" src="foo.jpeg" alt="" title="Foo">
<!-- Use @longdesc to point to a legend outside of the figure root element -->
<div class="figure">
  <img class="image" src="foo.jpeg" longdesc="#the-legend" alt="" />
</div>
<!-- ... -->
<p class="legend" id="the-legend">Foo</p>

HTML 5 Considerations

When used in HTML 5, any <figure> element has an implied class "figure"; any <legend> element has an implied class "legend". For example, the following HTML 5:

<figure>
  <img src="foo.jpeg" alt="">
  <legend>Foo</legend>
</figure>

is interpreted as if it were:

<figure class="figure">
  <img src="foo.jpeg" alt="">
  <legend class="legend">Foo</legend>
</figure>

Inspiration and Acknowledgments

This microformat is largely intended to be a simple "port" of HTML 5's <figure> construct to other versions of HTML and XHTML.

The three required properties (figure, image and caption) are derived from that. The additional properties (credit, subject) are included because this information seems to be commonly supplied in figures "in the wild" in prose even if it is not marked up with wrapper elements.

Other references which were considered:

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.

See also