W3C home > Mailing lists > Public > public-html@w3.org > January 2013

Re: current definition of <figure> in HTML is problematic

From: Michael[tm] Smith <mike@w3.org>
Date: Fri, 25 Jan 2013 05:21:38 +0900
To: Steve Faulkner <faulkner.steve@gmail.com>
Cc: HTMLWG WG <public-html@w3.org>
Message-ID: <20130124202135.GK46651@sideshowbarker>
Steve Faulkner <faulkner.steve@gmail.com>, 2013-01-24 09:44 +0000:

> I think the current definition [4] of  the figure element leads to
> developers thinking that they cannot use it to caption an image or images
> that are ket parts of the content:
> 
> "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."

I agree that statement seems to be confusing people, and so maybe some
language should be added around there to make it more clear that the figure
element is not necessarily restricted to being used only for the purpose
described there.

But I'm not sure it's the fault of the spec that some people are
misunderstanding it. For one thing, that sentence above is clearly not
stating any normative requirement. Or at least I think, to anybody who's
taken time to get familiar with the editorial style the spec consistently
uses, it would be clear that sentence states no normative requirements.

For context about what I mean, it's worth also quoting what the spec says
just before that statement you quote above. What it says is:

  The figure element represents some flow content, optionally with a
  caption, that is self-contained and is typically referenced as a single
  unit from the main flow of the document.

As far as I can see, that sentence is the only statement in the spec that
normatively defines the meaning of the figure element. And the parts of
that sentence that are qualified with "optionally" and "typically" are not
stating absolute requirements, so the only statement that's actually fully
normative is "The figure element represents some flow content that is
self-contained."

The spec very consistently uses a particular style to clearly distinguish
between parts that are normative and parts that are just informative or
illustrative. For a lot of elements, the only normative part is a sentence
that uses "The foo element represents" pattern. And the part of the spec
that gives those statements normative weight as authoring-conformance
requirements is here:

  http://www.w3.org/html/wg/drafts/html/master/dom.html#elements

  Elements, attributes, and attribute values in HTML are defined (by this
  specification) to have certain meanings (semantics). For example, the ol
  element represents an ordered list, and the lang attribute represents the
  language of the content.

  Authors must not use elements, attributes, or attribute values for
  purposes other than their appropriate intended semantic purpose, as doing
  so prevents software from correctly processing the page.

If elements have other normative authoring-conformance requirements, the
spec states them very clearly by using RFC 2119 "must", "must not", etc.,
language. For example, for the "address" element, the spec states these
additional normative authoring constraints:

  The address element must not be used to represent arbitrary addresses
  (e.g. postal addresses), unless those addresses are in fact the relevant
  contact information.

  The address element must not contain information other than contact
  information.

So if the spec were going to actually normatively state what purposes a
figure element is restricted to, it would state it with some "must" or
"must not" language, like this:

  The figure element must not be used to contain the main content of a
  document or the main content of a section of a document.

  The figure element must only 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.

But it doesn't say that. Instead, it just says the figure element "can be"
used in a particular way. That implies that it's not necessarily restricted
to the particular use it describes, and there's a possibility it can be
used for other purposes.

In other words, that statement is simply illustrative. It's just additional
guidance that's there to help people understand what the element is by
describing a common case where it can be used.

> For example, in this current discussion
> http://html5doctor.com/html5-simplequiz-7-pinterest/
> 
> developers are making statements such as [1]:
> 
> "I don’t think figure is appropriate, because it’s for things that can be
> taken out of flow and moved to an appendix, and the pins on the page are
> the whole point of the flow"

So yeah the person quoted is making a mistaken inference about what the
spec actually says.  The spec doesn't say that it's *only* for things that
can be taken out of flow and moved to an appendix.

> "<figure>s are intended to contain accessory content, not the main
> substance of the section in question."

And here I think the person quoted is making another mistaken inference
that's going even farther away from what the spec actually says. The spec
doesn't use the word "accessory" nor anything like it here, nor does it say
that figure must not be used to mark up the main substance of anything.

> "The spec says they can be moved away from the main flow of the document
> without affecting the document’s meaning. I therefore don’t think it’s
> appropriate to use them for the main image and description here." [2]

So the spec doesn't say at all what the person quoted there is claiming.
That is, it doesn't say that a figure is something that absolutely can
always be moved away. It says the figure element "can be" used for things
that could be moved away without affecting the document's "flow" (not
"meaning", by the way, as misquoted above). It does not say that the figure
element must only be used for those things, but not for anything else.

I think in general some people do way too much hair-splitting about how a
particular element should or should not be used -- I mean in cases like
this, where the authoring restriction they're asserting is something that's
not even possible to check with a validator and that has no relation to how
the content is handled by a Web browser.

But anyway, clearly for the case of figure we have some people that are
reading more restrictions into its use than what the spec actually says. So
I agree it would be worthwhile to come up with some additions or
refinements to the language there to avoid having people unnecessarily
restrict their use of the figure element in particular ways that there's no
good reason they need to be restricting it to.

  --Mike

-- 
Michael[tm] Smith http://people.w3.org/mike
Received on Thursday, 24 January 2013 20:21:51 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 24 January 2013 20:21:52 GMT