[at] (1) Broaden the possible use case for <figure>.

Affected topics: HTML git-svn-id: http://svn.whatwg.org/webapps@7991 340c8d12-0b0e-0410-8428-c7bf67bfef74
whatwg · Jun 19, 2013 · 63aaf58 · 63aaf58
1 parent d890d44
commit 63aaf58
Show file tree

Hide file tree

Showing 3 changed files with 102 additions and 21 deletions.
diff --git a/complete.html b/complete.html
@@ -18745,18 +18745,44 @@ <h4 id=the-figure-element><span class=secno>4.5.11 </span>The <dfn><code>figure<
    <dt><a href=#element-dfn-dom title=element-dfn-dom>DOM interface</a>:</dt><!--TOPIC:DOM APIs-->
    <dd>Uses <code><a href=#htmlelement>HTMLElement</a></code>.</dd>
   </dl><!--TOPIC:HTML--><!-- v2: Add a <credit> element for photo credits --><p>The <code><a href=#the-figure-element>figure</a></code> element <a href=#represents>represents</a> some <a href=#flow-content>flow content</a>,
-  optionally with a caption, that is self-contained and is typically referenced as a single unit
-  from the main flow of the document.</p>
+  optionally with a caption, that is self-contained (like a complete sentence) and is typically
+  referenced as a single unit from the main flow of the document.</p>
 
-  <p>The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc,
-  that are referred to from the main content of the document, but that could, without affecting the
-  flow of the document, be moved away from that primary content, e.g. to the side of the page, to
-  dedicated pages, or to an appendix.</p>
+  <p class=note>Self-contained in this context does not necessarily mean independent. For example,
+  each sentence in a paragraph is self-contained; an image that is part of a sentence would be
+  inappropriate for <code><a href=#the-figure-element>figure</a></code>, but an entire sentence made of images would be fitting.</p>
+
+  <p>The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc.</p>
+
+  <div class=note>
+
+   <p>When a <code><a href=#the-figure-element>figure</a></code> is referred to from the main content of the document by identifying
+   it by its caption (e.g. by figure number), it enables such content to be easily moved away from
+   that primary content, e.g. to the side of the page, to dedicated pages, or to an appendix, without
+   affecting the flow of the document.</p>
+
+   <p>If a <code><a href=#the-figure-element>figure</a></code> element is referenced by its relative position, e.g. "in the
+   photograph above" or "as the next figure shows", then moving the figure would disrupt the page's
+   meaning. Authors are encouraged to consider using labels to refer to figures, rather than using
+   such relative references, so that the page can easily be restyled without affecting the page's
+   meaning.</p>
+
+  </div>
 
   <p>The <span class=impl>first</span> <code><a href=#the-figcaption-element>figcaption</a></code> element child of the element, if
   any, represents the caption of the <code><a href=#the-figure-element>figure</a></code> element's contents. If there is no child
   <code><a href=#the-figcaption-element>figcaption</a></code> element, then there is no caption.</p>
 
+  <p>A <code><a href=#the-figure-element>figure</a></code> element's contents are part of the surrounding flow. If the purpose of
+  the page is to display the figure, for example a photograph on an image sharing site, the
+  <code><a href=#the-figure-element>figure</a></code> and <code><a href=#the-figcaption-element>figcaption</a></code> elements can be used to explicitly provide a
+  caption for that figure. For content that is only tangentially related, or that serves a separate
+  purpose than the surrounding flow, the <code><a href=#the-aside-element>aside</a></code> element should be used (and can itself
+  wrap a <code><a href=#the-figure-element>figure</a></code>). For example, a pull quote that repeats content from an
+  <code><a href=#the-article-element>article</a></code> would be more appropriate in an <code><a href=#the-aside-element>aside</a></code> than in a
+  <code><a href=#the-figure-element>figure</a></code>, because it isn't part of the content, it's a repetition of the content for
+  the purposes of enticing readers or highlighting key topics.</p>
+
   <div class=example>
 
    <p>This example shows the <code><a href=#the-figure-element>figure</a></code> element to mark up a code listing.</p>
@@ -18791,7 +18817,8 @@ <h4 id=the-figure-element><span class=secno>4.5.11 </span>The <dfn><code>figure<
   <div class=example>
 
    <p>In this example, we see an image that is <em>not</em> a figure, as well as an image and a
-   video that are.</p>
+   video that are. The first image is literally part of the example's second sentence, so it's not a
+   self-contained unit, and thus <code><a href=#the-figure-element>figure</a></code> would be inappropriate.</p>
 
    <pre>&lt;h2&gt;Malinko's comics&lt;/h2&gt;
 

diff --git a/index b/index
@@ -18745,18 +18745,44 @@ first matching case):&lt;/p&gt;
    <dt><a href=#element-dfn-dom title=element-dfn-dom>DOM interface</a>:</dt><!--TOPIC:DOM APIs-->
    <dd>Uses <code><a href=#htmlelement>HTMLElement</a></code>.</dd>
   </dl><!--TOPIC:HTML--><!-- v2: Add a <credit> element for photo credits --><p>The <code><a href=#the-figure-element>figure</a></code> element <a href=#represents>represents</a> some <a href=#flow-content>flow content</a>,
-  optionally with a caption, that is self-contained and is typically referenced as a single unit
-  from the main flow of the document.</p>
+  optionally with a caption, that is self-contained (like a complete sentence) and is typically
+  referenced as a single unit from the main flow of the document.</p>
 
-  <p>The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc,
-  that are referred to from the main content of the document, but that could, without affecting the
-  flow of the document, be moved away from that primary content, e.g. to the side of the page, to
-  dedicated pages, or to an appendix.</p>
+  <p class=note>Self-contained in this context does not necessarily mean independent. For example,
+  each sentence in a paragraph is self-contained; an image that is part of a sentence would be
+  inappropriate for <code><a href=#the-figure-element>figure</a></code>, but an entire sentence made of images would be fitting.</p>
+
+  <p>The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc.</p>
+
+  <div class=note>
+
+   <p>When a <code><a href=#the-figure-element>figure</a></code> is referred to from the main content of the document by identifying
+   it by its caption (e.g. by figure number), it enables such content to be easily moved away from
+   that primary content, e.g. to the side of the page, to dedicated pages, or to an appendix, without
+   affecting the flow of the document.</p>
+
+   <p>If a <code><a href=#the-figure-element>figure</a></code> element is referenced by its relative position, e.g. "in the
+   photograph above" or "as the next figure shows", then moving the figure would disrupt the page's
+   meaning. Authors are encouraged to consider using labels to refer to figures, rather than using
+   such relative references, so that the page can easily be restyled without affecting the page's
+   meaning.</p>
+
+  </div>
 
   <p>The <span class=impl>first</span> <code><a href=#the-figcaption-element>figcaption</a></code> element child of the element, if
   any, represents the caption of the <code><a href=#the-figure-element>figure</a></code> element's contents. If there is no child
   <code><a href=#the-figcaption-element>figcaption</a></code> element, then there is no caption.</p>
 
+  <p>A <code><a href=#the-figure-element>figure</a></code> element's contents are part of the surrounding flow. If the purpose of
+  the page is to display the figure, for example a photograph on an image sharing site, the
+  <code><a href=#the-figure-element>figure</a></code> and <code><a href=#the-figcaption-element>figcaption</a></code> elements can be used to explicitly provide a
+  caption for that figure. For content that is only tangentially related, or that serves a separate
+  purpose than the surrounding flow, the <code><a href=#the-aside-element>aside</a></code> element should be used (and can itself
+  wrap a <code><a href=#the-figure-element>figure</a></code>). For example, a pull quote that repeats content from an
+  <code><a href=#the-article-element>article</a></code> would be more appropriate in an <code><a href=#the-aside-element>aside</a></code> than in a
+  <code><a href=#the-figure-element>figure</a></code>, because it isn't part of the content, it's a repetition of the content for
+  the purposes of enticing readers or highlighting key topics.</p>
+
   <div class=example>
 
    <p>This example shows the <code><a href=#the-figure-element>figure</a></code> element to mark up a code listing.</p>
@@ -18791,7 +18817,8 @@ API declaration.&lt;/p&gt;
   <div class=example>
 
    <p>In this example, we see an image that is <em>not</em> a figure, as well as an image and a
-   video that are.</p>
+   video that are. The first image is literally part of the example's second sentence, so it's not a
+   self-contained unit, and thus <code><a href=#the-figure-element>figure</a></code> would be inappropriate.</p>
 
    <pre>&lt;h2&gt;Malinko's comics&lt;/h2&gt;
 

diff --git a/source b/source
@@ -19526,18 +19526,44 @@ first matching case):&lt;/p&gt;
   <!-- v2: Add a <credit> element for photo credits -->
 
   <p>The <code>figure</code> element <span>represents</span> some <span>flow content</span>,
-  optionally with a caption, that is self-contained and is typically referenced as a single unit
-  from the main flow of the document.</p>
+  optionally with a caption, that is self-contained (like a complete sentence) and is typically
+  referenced as a single unit from the main flow of the document.</p>
 
-  <p>The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc,
-  that are referred to from the main content of the document, but that could, without affecting the
-  flow of the document, be moved away from that primary content, e.g. to the side of the page, to
-  dedicated pages, or to an appendix.</p>
+  <p class="note">Self-contained in this context does not necessarily mean independent. For example,
+  each sentence in a paragraph is self-contained; an image that is part of a sentence would be
+  inappropriate for <code>figure</code>, but an entire sentence made of images would be fitting.</p>
+
+  <p>The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc.</p>
+
+  <div class="note">
+
+   <p>When a <code>figure</code> is referred to from the main content of the document by identifying
+   it by its caption (e.g. by figure number), it enables such content to be easily moved away from
+   that primary content, e.g. to the side of the page, to dedicated pages, or to an appendix, without
+   affecting the flow of the document.</p>
+
+   <p>If a <code>figure</code> element is referenced by its relative position, e.g. "in the
+   photograph above" or "as the next figure shows", then moving the figure would disrupt the page's
+   meaning. Authors are encouraged to consider using labels to refer to figures, rather than using
+   such relative references, so that the page can easily be restyled without affecting the page's
+   meaning.</p>
+
+  </div>
 
   <p>The <span class="impl">first</span> <code>figcaption</code> element child of the element, if
   any, represents the caption of the <code>figure</code> element's contents. If there is no child
   <code>figcaption</code> element, then there is no caption.</p>
 
+  <p>A <code>figure</code> element's contents are part of the surrounding flow. If the purpose of
+  the page is to display the figure, for example a photograph on an image sharing site, the
+  <code>figure</code> and <code>figcaption</code> elements can be used to explicitly provide a
+  caption for that figure. For content that is only tangentially related, or that serves a separate
+  purpose than the surrounding flow, the <code>aside</code> element should be used (and can itself
+  wrap a <code>figure</code>). For example, a pull quote that repeats content from an
+  <code>article</code> would be more appropriate in an <code>aside</code> than in a
+  <code>figure</code>, because it isn't part of the content, it's a repetition of the content for
+  the purposes of enticing readers or highlighting key topics.</p>
+
   <div class="example">
 
    <p>This example shows the <code>figure</code> element to mark up a code listing.</p>
@@ -19572,7 +19598,8 @@ API declaration.&lt;/p>
   <div class="example">
 
    <p>In this example, we see an image that is <em>not</em> a figure, as well as an image and a
-   video that are.</p>
+   video that are. The first image is literally part of the example's second sentence, so it's not a
+   self-contained unit, and thus <code>figure</code> would be inappropriate.</p>
 
    <pre>&lt;h2>Malinko's comics&lt;/h2>