The WHATWG
version of this specification is available under a more
permissive license.

Abstract

This specification defines the 5th major revision of the core
language of the World Wide Web: the Hypertext Markup Language
(HTML). In this version, new features are introduced to help Web
application authors, new elements are introduced based on research
into prevailing authoring practices, and special attention has been
given to defining clear conformance criteria for user agents in an
effort to improve interoperability.

Status of this document

This section describes the status of this document at the
time of its publication. Other documents may supersede this
document. A list of current W3C publications and the most recently
formally published revision of this technical report can be found
in the W3C technical reports
index at http://www.w3.org/TR/.

Implementors should be aware that this specification is not
stable. Implementors who are not taking part in the
discussions are likely to find the specification changing out from
under them in incompatible ways. Vendors interested in
implementing this specification before it eventually reaches the
Candidate Recommendation stage should join the aforementioned
mailing lists and take part in the discussions.

The publication of this document by the W3C as a W3C Working
Draft does not imply that all of the participants in the W3C HTML
working group endorse the contents of the specification. Indeed,
for any section of the specification, one can usually find many
members of the working group or of the W3C as a whole who object
strongly to the current text, the existence of the section at all,
or the idea that the working group should even spend time
discussing the concept of that section.

The latest stable version of the editor's draft of this
specification is always available on
the W3C CVS server and in the WHATWG Subversion repository . The
latest editor's working copy (which may contain unfinished text in
the process of being prepared) is available on the WHATWG
site . Detailed change history can be obtained from the
following locations:

Stability

Different parts of this specification are at different levels of
maturity.

Some of the more major known issues are marked
like this. There are many other issues that have been raised as
well; the issues given in this document are not the only known
issues! There are also some spec-wide issues that have not yet been
addressed: case-sensitivity is a very poorly handled topic right
now, and the firing of events needs to be unified (right now some
bubble, some don't, they all use different text to fire events,
etc). It would also be nice to unify the rules on downloading
content when attributes change (e.g. src
attributes) - should they initiate downloads when the element
immediately, is inserted in the document, when active scripts end,
etc. This matters e.g. if an attribute is set twice in a row (does
it hit the network twice).

1.
Introduction

This section is non-normative.

The World Wide Web's markup language has always been HTML. HTML
was primarily designed as a language for semantically describing
scientific documents, although its general design and adaptations
over the years has enabled it to be used to describe a number of
other types of documents.

The main area that has not been adequately addressed by HTML is
a vague subject referred to as Web Applications. This specification
attempts to rectify this, while at the same time updating the HTML
specifications to address issues raised in the past few years.

1.1 Scope

This section is non-normative.

This specification is limited to providing a semantic-level
markup language and associated semantic-level scripting APIs for
authoring accessible pages on the Web ranging from static documents
to dynamic applications.

The scope of this specification does not include providing
mechanisms for media-specific customization of presentation
(although default rendering rules for Web browsers are included at
the end of this specification, and several mechanisms for hooking
into CSS are provided as part of the language).

The scope of this specification does not include documenting
every HTML or DOM feature supported by Web browsers. Browsers
support many features that are considered to be very bad for
accessibility or that are otherwise inappropriate. For example, the
blink element is clearly presentational and authors
wishing to cause text to blink should instead use CSS.

The scope of this specification is not to describe an entire
operating system. In particular, hardware configuration software,
image manipulation tools, and applications that users would be
expected to use with high-end workstations on a daily basis are out
of scope. In terms of applications, this specification is targeted
specifically at applications that would be expected to be used by
users on an occasional basis, or regularly but from disparate
locations, with low CPU requirements. For instance online
purchasing systems, searching systems, games (especially
multiplayer online games), public telephone books or address books,
communications software (e-mail clients, instant messaging clients,
discussion software), document editing software, etc.

For sophisticated cross-platform applications, there already
exist several proprietary solutions (such as Mozilla's XUL, Adobe's
Flash, or Microsoft's Silverlight). These solutions are evolving
faster than any standards process could follow, and the
requirements are evolving even faster. These systems are also
significantly more complicated to specify, and are orders of
magnitude more difficult to achieve interoperability with, than the
solutions described in this document. Platform-specific solutions
for such sophisticated applications (for example the MacOS X Core
APIs) are even further ahead.

1.1.1 Relationship
to HTML 4.01, XHTML 1.1,4.01 and DOM2 HTML

This section is non-normative.

This specification represents a new version of HTML4 and XHTML1,HTML4, along with a new version of the associated
DOM2 HTML API. Migration from HTML4 or
XHTML1 to the format and APIs described in this specification
should in most cases be straightforward, as care has been taken to
ensure that backwards-compatibility is retained. [HTML4][DOM2HTML]

1.1.2Relationship to
XHTML 1.x

This section is
non-normative.

This specification will eventually
supplant Web Forms 2.0is intended to
replace XHTML 1.0 as well.the normative definition of the XML
serialisation of the HTML vocabulary.[WF2][XHTML10]

While this specification updates the
semantics and requirements of the vocabulary defined by XHTML
Modularization 1.1 and used by XHTML 1.1, it does not attempt to
provide a replacement for the modularization scheme defined and
used by those (and other) specifications, and therefore cannot be
considered a complete replacement for them.[XHTMLMOD][XHTML11]

Thus, authors and implementors who do not
need such a modularization scheme can consider this specification a
replacement for XHTML 1.x, but those who do need such a mechanism
are encouraged to continue using the XHTML 1.1 line of
specifications.

1.1.21.1.3
Relationship to XHTML2

This section is non-normative.

XHTML2 [XHTML2] defines a new HTML
vocabulary with better features for hyperlinks, multimedia content,
annotating document edits, rich metadata, declarative interactive
forms, and describing the semantics of human literary works such as
poems and scientific papers.

However, it lacks elements to express the semantics of many of
the non-document types of content often seen on the Web. For
instance, forum sites, auction sites, search engines, online shops,
and the like, do not fit the document metaphor well, and are not
covered by XHTML2.

This specification aims to extend HTML so that it is
also suitable in these contexts.

XHTML2 and this specification use different namespaces and
therefore can both be implemented in the same XML processor.

1.1.31.1.4Relationship to Web Forms 2.0 and
XForms

This section is
non-normative.

This specification will eventually
supplant Web Forms 2.0. The current Web Forms 2.0 draft can be
considered part of this specification for the time being; its
features will eventually be merged into this specification.[WF2]

As it stands today, this specification is
unrelated and orthognoal to XForms. When the forms features defined
in HTML4 and Web Forms 2.0 are merged into this specification, then
the relationship to XForms described in the Web Forms 2.0 draft
will apply to this specification.[XForms]

This specification is independent of the various proprietary UI
languages that various vendors provide. As an open, vendor-neutral
language, HTML provides for a solution to the same problems without
the risk of vendor lock-in.

Documents are built from elements. These elements form a tree
using the DOM. Each element also has a predefined meaning, which is
explained in this section. User agent requirements for how to
handle each element are also given, along with rules for authors on
how to use the element.

HTML documents do not exist in a vacuum — this section
defines many of the features that affect environments that deal
with multiple pages, links between pages, and running scripts.

APIs

User interaction : HTML documents can
provide a number of mechanisms for users to interact with and
modify content, which are described in this section.

The Communication APIs : Applications
written in HTML often require mechanisms to communicate with remote
servers, as well as communicating with other applications from
different domains running on the same client.

All of these features would be for naught if they couldn't be
represented in a serialized form and sent to other people, and so
this section defines the syntax of HTML, along with rules for how
to parse HTML.

1.2.1 How to read this
specification

This specification should be read like all other specifications.
First, it should be read cover-to-cover, multiple times. Then, it
should be read backwards at least once. Then it should be read by
picking random sections from the contents list and following all
the cross-references.

1.3 Conformance
requirements

All diagrams, examples, and notes in this specification are
non-normative, as are all sections explicitly marked non-normative.
Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD
NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts
of this document are to be interpreted as described in RFC2119. For
readability, these words do not appear in all uppercase letters in
this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms
(such as "strip any leading space characters" or "return false and
abort these steps") are to be interpreted with the meaning of the
key word ("must", "should", "may", etc) used in introducing the
algorithm.

This specification describes the conformance criteria for user
agents (relevant to implementors) and documents (relevant to
authors and authoring tool implementors).

There is no implied relationship between document
conformance requirements and implementation conformance
requirements. User agents are not free to handle non-conformant
documents as they please; the processing model described in this
specification applies to implementations regardless of the
conformity of the input documents.

User agents fall into several (overlapping) categories with
different conformance requirements.

Web browsers and other interactive user
agents

Web browsers that support XHTML must
process elements and attributes from the HTML namespace found in XML documents as described in this
specification, so that users can interact with them, unless the
semantics of those elements have been overridden by other
specifications.

A conforming XHTML processor would, upon finding
an XHTML script element in an
XML document, execute the script contained in that element.
However, if the element is found within an XSLT transformation
sheet (assuming the UA also supports XSLT), then the processor
would instead treat the script
element as an opaque element that forms part of the transform.

Web browsers that support HTML must process documents labeled as
text/html as described in this specification, so that
users can interact with them.

Non-interactive presentation user
agents

User agents that process HTML and XHTML documents purely to
render non-interactive versions of them must comply to the same
conformance criteria as Web browsers, except that they are exempt
from requirements regarding user interaction.

Typical examples of non-interactive presentation
user agents are printers (static UAs) and overhead displays
(dynamic UAs). It is expected that most static non-interactive
presentation user agents will also opt to lack scripting support .

A non-interactive but dynamic presentation UA
would still execute scripts, allowing forms to be dynamically
submitted, and so forth. However, since the concept of "focus" is
irrelevant when the user cannot interact with the document, the UA
would not need to support any of the focus-related DOM APIs.

User agents with no scripting
support

Implementations that do not support scripting (or which have
their scripting features disabled entirely) are exempt from
supporting the events and DOM interfaces mentioned in this
specification. For the parts of this specification that are defined
in terms of an events model or in terms of the DOM, such user
agents must still act as if events and the DOM were supported.

Scripting can form an integral part of an
application. Web browsers that do not support scripting, or that
have scripting disabled, might be unable to fully convey the
author's intent.

Conformance checkers

Conformance checkers must verify that a document conforms to the
applicable conformance criteria described in this specification.
Automated conformance checkers are exempt from detecting errors
that require interpretation of the author's intent (for example,
while a document is non-conforming if the content of a
blockquote element is not a
quote, conformance checkers running without the input of human
judgement do not have to check that blockquote elements only contain quoted
material).

Conformance checkers must check that the input document conforms
when parsed without a browsing context
(meaning that no scripts are run, and that the parser's scripting flag is disabled), and should also
check that the input document conforms when parsed with a browsing context in which scripts execute, and
that the scripts never cause non-conforming states to occur other
than transiently during script execution itself. (This is only a
"SHOULD" and not a "MUST" requirement because it has been proven to
be impossible. [HALTINGPROBLEM] )

The term "HTML5 validator" can be used to refer to a conformance
checker that itself conforms to the applicable requirements of this
specification.

XML DTDs cannot express all the conformance requirements of this
specification. Therefore, a validating XML processor and a DTD
cannot constitute a conformance checker. Also, since neither of the
two authoring formats defined in this specification are
applications of SGML, a validating SGML system cannot constitute a
conformance checker either.

To put it another way, there are three types of conformance
criteria:

Criteria that can be expressed in a DTD.

Criteria that cannot be expressed by a DTD, but can still be
checked by a machine.

Criteria that can only be checked by a human.

A conformance checker must check for the first two. A simple
DTD-based validator only checks for the first class of errors and
is therefore not a conforming conformance checker according to this
specification.

Data mining tools

Applications and tools that process HTML and XHTML documents for
reasons other than to either render the documents or check them for
conformance should act in accordance to the semantics of the
documents that they process.

A tool that generates document outlines but increases the nesting level for
each paragraph and does not increase the nesting level for each
section would not be conforming.

Authoring tools and markup generators

Authoring tools and markup generators must generate conforming
documents. Conformance criteria that apply to authors also apply to
authoring tools, where appropriate.

Authoring tools are exempt from the strict requirements of using
elements only for their specified purpose, but only to the extent
that authoring tools are not yet able to determine author
intent.

For example, it is not conforming to use an
address element for arbitrary
contact information; that element can only be used for marking up
contact information for the author of the document or section.
However, since an authoring tool is likely unable to determine the
difference, an authoring tool is exempt from that requirement.

In terms of conformance checking, an editor is
therefore required to output documents that conform to the same
extent that a conformance checker will verify.

When an authoring tool is used to edit a non-conforming
document, it may preserve the conformance errors in sections of the
document that were not edited during the editing session (i.e. an
editing tool is allowed to round-trip erroneous content). However,
an authoring tool must not claim that the output is conformant if
errors have been so preserved.

Authoring tools are expected to come in two broad varieties:
tools that work from structure or semantic data, and tools that
work on a What-You-See-Is-What-You-Get media-specific editing basis
(WYSIWYG).

The former is the preferred mechanism for tools that author
HTML, since the structure in the source information can be used to
make informed choices regarding which HTML elements and attributes
are most appropriate.

However, WYSIWYG tools are legitimate. WYSIWYG tools should use
elements they know are appropriate, and should not use elements
that they do not know to be appropriate. This might in certain
extreme cases mean limiting the use of flow elements to just a few
elements, like div , b , i , and
span and making liberal use of the
style
attribute.

All authoring tools, whether WYSIWYG or not, should make a best
effort attempt at enabling users to create well-structured,
semantically rich, media-independent content.

Some conformance requirements are phrased as requirements on
elements, attributes, methods or objects. Such requirements fall
into two categories: those describing content model restrictions,
and those describing implementation behavior. The former category
of requirements are requirements on documents and authoring tools.
The second category are requirements on user agents.

Conformance requirements phrased as algorithms or specific steps
may be implemented in any manner, so long as the end result is
equivalent. (In particular, the algorithms defined in this
specification are intended to be easy to follow, and not intended
to be performant.)

User agents may impose
implementation-specific limits on otherwise unconstrained inputs,
e.g. to prevent denial of service attacks, to guard against running
out of memory, or to work around platform-specific limitations.

For compatibility with existing content and prior
specifications, this specification describes two authoring formats:
one based on XML (referred to as XHTML5 ), and one using a custom
format inspired by SGML (referred to as HTML5 ). Implementations may support only one of
these two formats, although supporting both is encouraged.

XHTML documents (
XML documents using elements from the
HTML namespace ) that use the new
features described in this specification and that are served over
the wire (e.g. by HTTP) must be sent using an XML MIME type such as
application/xml or application/xhtml+xml
and must not be served as text/html . [RFC3023]

Such XML documents may contain a DOCTYPE if
desired, but this is not required to conform to this
specification.

According to the XML specification, XML processors
are not guaranteed to process the external DTD subset referenced in
the DOCTYPE. This means, for example, that using entity references
for characters in XHTML documents is unsafe (except for
&lt; , &gt; ,
&amp; , &quot;
and &apos; ).

HTML
documents , if they are served over the wire (e.g. by HTTP)
must be labeled with the text/html MIME type.

The language in this specification
assumes that the user agent expands all entity references, and
therefore does not include entity reference nodes in the DOM. If
user agents do include entity reference nodes in the DOM, then user
agents must handle them as if they were fully expanded when
implementing this specification. For example, if a requirement
talks about an element's child text nodes, then any text nodes that
are children of an entity reference that is a child of that element
would be used as well. Entity references to unknown entities must
be treated as if they contained just an empty text node for the
purposes of the algorithms defined in this specification.

1.3.1 Common conformance
requirements for APIs exposed to JavaScript

A lot of arrays/lists/ collection s in this spec assume zero-based
indexes but use the term " index th" liberally.
We should define those to be zero-based and be clearer about
this.

Unless otherwise specified, if a DOM attribute that is a
floating point number type ( float ) is
assigned an Infinity or Not-a-Number value, a NOT_SUPPORTED_ERR exception must be raised.

Unless otherwise specified, if a method with an argument that is
a floating point number type ( float ) is
passed an Infinity or Not-a-Number value, a NOT_SUPPORTED_ERR exception must be raised.

Unless otherwise specified, if a method is passed fewer
arguments than is defined for that method in its IDL definition, a
NOT_SUPPORTED_ERR exception must be
raised.

Unless otherwise specified, if a method is passed more arguments
than is defined for that method in its IDL definition, the excess
arguments must be ignored.

1.3.2
Dependencies

This specification relies on several other underlying
specifications.

XML

Implementations that support XHTML5 must support some version of
XML, as well as its corresponding namespaces specification, because
XHTML5 uses an XML serialization with namespaces. [XML][XMLNAMES]

XML Base

User agents must follow the rules given by XML Base
to resolve relative URIs in HTML and XHTML fragments. That is the
mechanism used in this specification for resolving relative URIs in
DOM trees. [XMLBASE]

It is possible for xml:base attributes
to be present even in HTML fragments, as such attributes can be
added dynamically using script. (Such scripts would not be
conforming, however, as xml:base attributes as not allowed in
HTML documents .)

DOM

Implementations must support some version of DOM Core and DOM
Events, because this specification is defined in terms of the DOM,
and some of the features are defined as extensions to the DOM Core
interfaces. [DOM3CORE][DOM3EVENTS]

ECMAScript

Implementations that use ECMAScript to implement the APIs
defined in this specification must implement them in a manner
consistent with the ECMAScript Bindings defined in the Web IDL
specification, as this specification uses that specification's
terminology. [WebIDL]

Media Queries

Implementations must support some version of the Media Queries
language. [MQ]

This specification does not require support of any particular
network transport protocols, style sheet language, scripting
language, or any of the DOM and WebAPI specifications beyond those
described above. However, the language described by this
specification is biased towards CSS as the styling language,
ECMAScript as the scripting language, and HTTP as the network
protocol, and several features assume that those languages and
protocols are in use.

This specification might have certain additional
requirements on character encodings, image formats, audio formats,
and video formats in the respective sections.

1.3.3 Features defined
in other specifications

Some elements are defined in terms of their DOM textContent attribute. This is an
attribute defined on the Node interface in DOM3 Core.
[DOM3CORE]

Should textContent be defined differently for
dir="" and <bdo> ? Should we come up with an alternative to
textContent that handles those and other things, like alt=""?

Certain features are defined in terms of CSS <color>
values. When the CSS value currentColor is
specified in this context, the "computed value of the 'color'
property" for the purposes of determining the computed value of the
currentColor keyword is the computed value of
the 'color' property on the element in question. If the computed
value of the 'color' property is undefined for a particular case
(e.g. because the element is not in a document), then the "computed
value of the 'color' property" for the purposes of determining the
computed value of the currentColor keyword is
fully opaque black. [CSS3COLOR]

If a canvas gradient's addColorStop() method is called with the
currentColor keyword as the color, then the
computed value of the 'color' property on the canvas element is the one that is used.

1.4
Terminology

This specification refers to both HTML and XML attributes and
DOM attributes, often in the same context. When it is not clear
which is being referred to, they are referred to as content attributes for HTML and XML attributes, and
DOM attributes for those from the
DOM. Similarly, the term "properties" is used for both ECMAScript
object properties and CSS properties. When these are ambiguous they
are qualified as object properties and CSS properties
respectively.

To ease migration from HTML to XHTML, UAs
conforming to this specification will place elements in HTML in the
http://www.w3.org/1999/xhtml namespace, at least for
the purposes of the DOM and CSS. The term " elements in the HTML namespace ", or " HTML elements " for short, when used in this
specification, thus refers to both HTML and XHTML elements.

Unless otherwise stated, all elements defined or mentioned in
this specification are in the
http://www.w3.org/1999/xhtml namespace, and all
attributes defined or mentioned in this specification have no
namespace (they are in the per-element partition).

The term HTML documents is sometimes used
in contrast with XML documents to
specifically mean documents that were parsed using an HTML parser (as opposed to using an XML parser or
created purely through the DOM).

Generally, when the specification states that a feature applies
to HTML or XHTML, it also includes the other. When a feature
specifically only applies to one of the two languages, it is called
out by explicitly stating that it does not apply to the other
format, as in "for HTML, ... (this does not apply to XHTML)".

This specification uses the term document to refer to
any use of HTML, ranging from short static documents to long essays
or reports with rich multimedia, as well as to fully-fledged
interactive applications.

For readability, the term URI is used to refer to both ASCII
URIs and Unicode IRIs, as those terms are defined by RFC 3986 and
RFC 3987 respectively. On the rare occasions where IRIs are not
allowed but ASCII URIs are, this is called out explicitly. [RFC3986][RFC3987]

The term root element , when not
explicitly qualified as referring to the document's root element,
means the furthest ancestor element node of whatever node is being
discussed, or the node itself if it has no ancestors. When the node
is a part of the document, then that is indeed the document's root
element; however, if the node is not currently part of the document
tree, the root element will be an orphaned node.

An element is said to have been inserted into a document
when its root element changes and is
now the document's root element .

The term tree order means a
pre-order, depth-first traversal of DOM nodes involved (through the
parentNode / childNodes
relationship).

When it is stated that some element or attribute is ignored , or treated as some other
value, or handled as if it was something else, this refers only to
the processing of the node after it is in the DOM. A user agent
must not mutate the DOM in such situations.

When an XML name, such as an attribute or element name, is
referred to in the form prefix :
localName , as in xml:id or
svg:rect , it refers to a name with the local name
localName and the namespace given by the
prefix, as defined by the following table:

xml

http://www.w3.org/XML/1998/namespace

html

http://www.w3.org/1999/xhtml

svg

http://www.w3.org/2000/svg

For simplicity, terms such as shown ,
displayed , and visible might sometimes be used
when referring to the way a document is rendered to the user. These
terms are not meant to imply a visual medium; they must be
considered to apply to other media in equivalent ways.

DOM interfaces defined in this specification use Web IDL. User
agents must implement these interfaces as defined by the Web IDL
specification. [WEBIDL]

The construction "a Foo object", where
Foo is actually an interface, is sometimes used
instead of the more accurate "an object implementing the interface
Foo ".

A DOM attribute is said to be getting when its value is
being retrieved (e.g. by author script), and is said to be
setting when a new value is assigned to it.

If a DOM object is said to be live , then
that means that any attributes returning that object must always
return the same object (not a new object each time), and the
attributes and methods on that object must operate on the actual
underlying data, not a snapshot of the data.

The terms fire and dispatch are used
interchangeably in the context of events, as in the DOM Events
specifications. [DOM3EVENTS]

The term text node refers to any
Text node, including CDATASection nodes;
specifically, any Node with node type TEXT_NODE (3) or CDATA_SECTION_NODE
(4). [DOM3CORE]

The term plugin is used to mean any
content handler, typically a third-party content handler, for Web
content types that are not supported by the user agent natively, or
for content types that do not expose a DOM, that supports rendering
the content as part of the user agent's interface.

One example of a plugin would be a PDF viewer
that is instantiated in a browsing context
when the user navigates to a PDF file. This would count as a plugin
regardless of whether the party that implemented the PDF viewer
component was the same as that which implemented the user agent
itself. However, a PDF viewer application that launches separate
from the user agent (as opposed to using the same interface) is not
a plugin by this definition.

This specification does not define a mechanism for
interacting with plugins, as it is expected to be user-agent- and
platform-specific. Some UAs might opt to support a plugin mechanism
such as the Netscape Plugin API; others might use remote content
converters or have built-in support for certain types. [NPAPI]

Browsers should take extreme care when
interacting with external content intended for plugins . When third-party software is run with
the same privileges as the user agent itself, vulnerabilities in
the third-party software become as dangerous as those in the user
agent.

Some of the algorithms in this specification, for historical
reasons, require the user agent to pause
until some condition has been met. While a user agent is paused, it
must ensure that no scripts execute (e.g. no event handlers, no
timers, etc). User agents should remain responsive to user input
while paused, however, albeit without letting the user interact
with Web pages where that would involve invoking any script.

1.4.1 HTML vs
XHTML

This section is non-normative.

This specification defines an abstract language for describing
documents and applications, and some APIs for interacting with
in-memory representations of resources that use this language.

The in-memory representation is known as "DOM5 HTML", or "the
DOM" for short.

There are various concrete syntaxes that can be used to transmit
resources that use this abstract language, two of which are defined
in this specification.

The first such concrete syntax is "HTML5". This is the format
recommended for most authors. It is compatible with all legacy Web
browsers. If a document is transmitted with the MIME type
text/html , then it will be processed as an
"HTML5" document by Web browsers.

The second concrete syntax uses XML, and is known as "XHTML5".
When a document is transmitted with an XML MIME type, such as
application/xhtml+xml , then it is processed
by an XML processor by Web browsers, and treated as an "XHTML5"
document. Authors are reminded that the processing for XML and HTML
differs; in particular, even minor syntax errors will prevent an
XML document from being rendered fully, whereas they would be
ignored in the "HTML5" syntax.

The "DOM5 HTML", "HTML5", and "XHTML5" representations cannot
all represent the same content. For example, namespaces cannot be
represented using "HTML5", but they are supported in "DOM5 HTML"
and "XHTML5". Similarly, documents that use the noscript feature can be represented using
"HTML5", but cannot be represented with "XHTML5" and "DOM5 HTML".
Comments that contain the string " --> "
can be represented in "DOM5 HTML" but not in "HTML5" and "XHTML5".
And so forth.

2. The Document Object
Model

The Document Object Model (DOM) is a representation — a
model — of a document and its content. [DOM3CORE] The DOM is not just an API; the
conformance criteria of HTML implementations are defined, in this
specification, in terms of operations on the DOM.

This specification defines the language represented in the DOM
by features together called DOM5 HTML. DOM5 HTML consists of DOM
Core Document nodes and DOM Core Element
nodes, along with text nodes and other content.

Elements in the DOM represent things; that is, they have
intrinsic meaning , also known as semantics.

In addition, documents and elements in the DOM host APIs that
extend the DOM Core APIs, providing new features to application
developers using DOM5 HTML.

2.1 Documents

Every XML and HTML document in an HTML UA is represented by a
Document object. [DOM3CORE]

Document objects are assumed to be XML documents unless they are flagged as
being HTML documents when they are created.
Whether a document is an HTML document or an XML document affects the behavior of
certain APIs, as well as a few CSS rendering rules. [CSS21]

All Document objects (in user agents implementing
this specification) must also implement the HTMLDocument interface, available using
binding-specific methods. (This is the case whether or not the
document in question is an HTML document or indeed whether it contains
any HTML elements at all.)
Document objects must also implement the
document-level interface of any other namespaces found in the
document that the UA supports. For example, if an HTML
implementation also supports SVG, then the Document
object must implement HTMLDocument and
SVGDocument .

Because the HTMLDocument interface is now obtained
using binding-specific casting methods instead of simply being the
primary interface of the document object, it is no longer defined
as inheriting from Document .

2.1.2Resource metadata management

The URL attribute must return
the document's address .

The referrer attribute must
return either the URI of the active document
of the source browsing context at the time
the navigation was started (that is, the page which navigated the browsing context to the current document), or the
empty string if there is no such originating page, or if the UA has
been configured not to report referrers in this case, or if the
navigation was initiated for a hyperlink
with a noreferrer keyword.

In the case of HTTP, the referrer DOM
attribute will match the Referer (sic) header
that was sent when fetching the current page.

Typically user agents are configured to not report
referrers in the case where the referrer uses an encrypted protocol
and the current page does not (e.g. when navigating from an
https: page to an http:
page).

On setting, if the sandboxed origin
browsing context flag is set on the browsing context of the document, the user agent
must raise a security exception .
Otherwise, the user agent must act as it would when processing
cookies if it had just attempted to fetch the document's
address over HTTP, and had received a response with a
Set-Cookie header whose value was the specified value,
as per RFC 2109 sections 4.3.1, 4.3.2, and 4.3.3. [RFC2109]

Since the cookie
attribute is accessible across frames, the path restrictions on
cookies are only a tool to help manage which cookies are sent to
which parts of the site, and are not in any way a security
feature.

The lastModified
attribute, on getting, must return the date and time of the
Document 's source file's last modification, in the
user's local timezone, in the following format:

The month component of the date.

A U+002F SOLIDUS character ('/').

The day component of the date.

A U+002F SOLIDUS character ('/').

The year component of the date.

A U+0020 SPACE character.

The hours component of the time.

A U+003A COLON character (':').

The minutes component of the time.

A U+003A COLON character (':').

The seconds component of the time.

All the numeric components above, other than the year, must be
given as two digits in the range U+0030 DIGIT ZERO to U+0039 DIGIT
NINE representing the number in base ten, zero-padded if
necessary.

The Document 's source file's last modification
date and time must be derived from relevant features of the
networking protocols used, e.g. from the value of the HTTP
Last-Modified header of the document, or from
metadata in the file system for local files. If the last
modification date and time are not known, the attribute must return
the string 01/01/1970 00:00:00 .

A Document is always set to one of three modes:
no quirks mode , the default; quirks mode , used typically for legacy documents;
and limited quirks mode , also known as
"almost standards" mode. The mode is only ever changed from the
default by the HTML parser , based on the
presence, absence, or value of the DOCTYPE string.

The compatMode DOM
attribute must return the literal string " CSS1Compat " unless the document has been set to quirks mode by the HTML parser
, in which case it must instead return the literal string "
BackCompat ".

Safari and IE have special parsing rules for <% ... %>
(even in standards mode, though clearly this should be
quirks-only).

Documents have an associated character encoding . When a
Document object is created, the document's character encoding must be initialized
to UTF-16. Various algorithms during page loading affect this
value, as does the charset setter. [IANACHARSET]

The charset DOM attribute
must, on getting, return the preferred MIME name of the document's character encoding . On setting, if
the new value is an IANA-registered alias for a character encoding,
the document's character encoding must be
set to that character encoding. (Otherwise, nothing happens.)

The defaultCharset DOM
attribute must, on getting, return the preferred MIME name of a
character encoding, possibly the user's default encoding, or an
encoding associated with the user's current geographical location,
or any arbitrary encoding name.

Each document has a current document
readiness . When a Document object is created,
it must have its current document readiness
set to the string "loading". Various algorithms during page loading
affect this value. When the value is set, the user agent must
fire a simple event called readystatechanged at the
Document object.

2.2 Elements

The nodes representing HTML
elements in the DOM must implement, and expose to scripts, the
interfaces listed for them in the relevant sections of this
specification. This includes XHTML elements
in XML documents , even when those
documents are in another context (e.g. inside an XSLT
transform).

The basic interface, from which all the HTML elements ' interfaces inherit, and which
must be used by elements that have no additional requirements, is
the HTMLElement
interface.

As with the HTMLDocument interface, the
HTMLElement interface holds
methods and attributes related to a number of disparate features,
and the members of this interface are therefore described in
various different sections of this specification.

2.2.1 Reflecting
content attributes in DOM attributes

Some DOM attributes are
defined to reflect a particular
content attribute . This means that on getting, the
DOM attribute returns the current value of the content attribute,
and on setting, the DOM attribute changes the value of the content
attribute to the given value.

If a reflecting DOM attribute is a DOMString
attribute whose content attribute is defined to contain a URI, then
on getting, the DOM attribute must return the value of the content
attribute, resolved to an absolute URI, and on setting, must set
the content attribute to the specified literal value. If the
content attribute is absent, the DOM attribute must return the
default value, if the content attribute has one, or else the empty
string.

If a reflecting DOM attribute is a DOMString
attribute whose content attribute is defined to contain one or more
URIs, then on getting, the DOM attribute must split the content attribute on
spaces and return the concatenation of each token URI,
resolved to an absolute URI, with a single U+0020 SPACE character
between each URI; if the content attribute is absent, the DOM
attribute must return the default value, if the content attribute
has one, or else the empty string. On setting, the DOM attribute
must set the content attribute to the specified literal value.

If a reflecting DOM attribute is a DOMString whose
content attribute is an enumerated
attribute , and the DOM attribute is limited
to only known values , then, on getting, the DOM attribute
must return the conforming value associated with the state the
attribute is in (in its canonical case), or the empty string if the
attribute is in a state that has no associated keyword value; and
on setting, if the new value case-insensitively matches one of the
keywords given for that attribute, then the content attribute must
be set to the conforming value associated with the state that the
attribute would be in if set to the given new value, otherwise, if
the new value is the empty string, then the content attribute must
be removed, otherwise, the setter must raise a
SYNTAX_ERR exception.

If a reflecting DOM attribute is a DOMString but
doesn't fall into any of the above categories, then the getting and
setting must be done in a transparent, case-preserving manner.

If a reflecting DOM attribute is a boolean attribute, then on
getting the DOM attribute must return true if the attribute is set,
and false if it is absent. On setting, the content attribute must
be removed if the DOM attribute is set to false, and must be set to
have the same value as its name if the DOM attribute is set to
true. (This corresponds to the rules for boolean content attributes .)

If a reflecting DOM attribute is a signed integer type (
long ) then, on getting, the content attribute must be
parsed according to the rules for parsing signed
integers , and if that is successful, the resulting value must
be returned. If, on the other hand, it fails, or if the attribute
is absent, then the default value must be returned instead, or 0 if
there is no default value. On setting, the given value must be
converted to the shortest possible string representing the number
as a valid integer in base ten and then that
string must be used as the new content attribute value.

If a reflecting DOM attribute is an unsigned integer
type ( unsigned long ) then, on getting, the content
attribute must be parsed according to the rules for parsing
unsigned integers , and if that is successful, the resulting
value must be returned. If, on the other hand, it fails, or if the
attribute is absent, the default value must be returned instead, or
0 if there is no default value. On setting, the given value must be
converted to the shortest possible string representing the number
as a valid non-negative integer in base ten
and then that string must be used as the new content attribute
value.

If a reflecting DOM attribute is an unsigned integer type (
unsigned long ) that is limited to
only positive non-zero numbers , then the behavior is similar
to the previous case, but zero is not allowed. On getting, the
content attribute must first be parsed according to the rules
for parsing unsigned integers , and if that is successful, the
resulting value must be returned. If, on the other hand, it fails,
or if the attribute is absent, the default value must be returned
instead, or 1 if there is no default value. On setting, if the
value is zero, the user agent must fire an
INDEX_SIZE_ERR exception. Otherwise, the given value
must be converted to the shortest possible string representing the
number as a valid non-negative integer in base
ten and then that string must be used as the new content attribute
value.

If a reflecting DOM attribute is a floating point number type (
float ) and the content attribute is defined to
contain a time offset, then, on getting, the content attribute must
be parsed according to the rules for parsing time
offsets , and if that is successful, the resulting value, in
seconds, must be returned. If that fails, or if the attribute is
absent, the default value must be returned, or the not-a-number
value (NaN) if there is no default value. On setting, the given
value, interpreted as a time offset in seconds, must be converted
to a string using the time offset
serialization rules , and that string must be used as the new
content attribute value.

If a reflecting DOM attribute is a floating point number type (
float ) and it doesn't fall into one of the earlier
categories, then, on getting, the content attribute must be parsed
according to the rules for
parsing floating point number values , and if that is
successful, the resulting value must be returned. If, on the other
hand, it fails, or if the attribute is absent, the default value
must be returned instead, or 0.0 if there is no default value. On
setting, the given value must be converted to the shortest possible
string representing the number as a valid
floating point number in base ten and then that string must be
used as the new content attribute value.

If a reflecting DOM attribute is of the type DOMTokenList , then on getting it must
return a DOMTokenList
object whose underlying string is the element's corresponding
content attribute. When the DOMTokenList object mutates its
underlying string, the content attribute must itself be immediately
mutated. When the attribute is absent, then the string represented
by the DOMTokenList
object is the empty string; when the object mutates this empty
string, the user agent must first add the corresponding content
attribute, and then mutate that attribute instead. DOMTokenList attributes are always
read-only. The same DOMTokenList object must be returned
every time for each attribute.

If a reflecting DOM attribute has the type HTMLElement , or an interface that
descends from HTMLElement ,
then, on getting, it must run the following algorithm (stopping at
the first point where a value is returned):

If the corresponding content attribute is absent, then the DOM
attribute must return null.

Let candidate be the element that the
document.getElementById() method would find
if it was passed as its argument the current value of the
corresponding content attribute.

If candidate is null, or if it is not
type-compatible with the DOM attribute, then the DOM attribute must
return null.

Otherwise, it must return candidate .

On setting, if the given element has an id attribute, then the content
attribute must be set to the value of that id attribute. Otherwise, the DOM
attribute must be set to the empty string.

When a collection is created, a filter and a root are
associated with the collection.

For example, when the HTMLCollection object for the
document.images attribute is created, it is
associated with a filter that selects only img elements, and rooted at the root of the
document.

The collection
then represents a live view of the subtree rooted at the collection's
root, containing only nodes that match the given filter. The view
is linear. In the absence of specific requirements to the contrary,
the nodes within the collection must be sorted in tree order .

The item( index ) method must return the index th node in the collection. If there is no
index th node in the collection, then the
method must return null.

The namedItem(
key ) method must act according to
the following algorithm:

If, at the time the method is called, there is exactly one node
in the collection that has either an id attribute or a name attribute equal to key
, then return that node and stop the algorithm.

Otherwise, if there are no nodes in the collection that have
either an id
attribute or a name attribute equal
to key , then return null and stop the
algorithm.

Otherwise, create a NodeList object representing a
live view of the HTMLFormControlsCollection
object, further filtered so that the only nodes in the
NodeList object are those that have either an
id attribute or a
name attribute equal to key . The nodes in the NodeList object must
be sorted in tree order .

On setting, the behavior depends on whether the new value is
equal to, greater than, or less than the number of nodes represented by the collection at that time. If
the number is the same, then setting the attribute must do nothing.
If the new value is greater, then n new
option elements with no attributes and no child nodes
must be appended to the select element on which the
HTMLOptionsCollection is
rooted, where n is the difference between the
two numbers (new value minus old value). If the new value is lower,
then the last n nodes in the collection must be
removed from their parent nodes, where n is the
difference between the two numbers (old value minus new value).

Setting length never removes or adds any
optgroup elements, and never adds new children to
existing optgroup elements (though it can remove
children from them).

The item( index ) method must return the index th node in the collection. If there is no
index th node in the collection, then the
method must return null.

The namedItem( key ) method must act according to the
following algorithm:

If, at the time the method is called, there is exactly one node
in the collection that has either an id attribute or a name attribute equal to key
, then return that node and stop the algorithm.

Otherwise, if there are no nodes in the collection that have
either an id
attribute or a name attribute equal
to key , then return null and stop the
algorithm.

Otherwise, create a NodeList object representing a
live view of the HTMLOptionsCollection object,
further filtered so that the only nodes in the
NodeList object are those that have either an
id attribute or a
name attribute equal to
key . The nodes in the NodeList
object must be sorted in tree order
.

Return that NodeList object.

We may want to add add() and
remove() methods here too because IE implements
HTMLSelectElement and HTMLOptionsCollection on the same object, and
so people use them almost interchangeably in the wild.

2.3.2
DOMTokenList

Which string underlies a particular DOMTokenList object is defined when the
object is created. It might be a content attribute (e.g. the string
that underlies the classList object is the class attribute), or it
might be an anonymous string (e.g. when a DOMTokenList object is passed to an
author-implemented callback in the datagrid APIs).

The item(
index ) method must split the underlying
string on spaces , sort the resulting list of tokens by Unicode
codepoint , remove exact duplicates, and then return the
index th item in this list. If index is equal to or greater than the number of tokens,
then the method must return null.

The has(
token ) method must run the
following algorithm:

If the token argument contains any space characters , then raise
an INVALID_CHARACTER_ERR exception and stop the
algorithm.

If the given token is already one of the
tokens in the DOMTokenList object's underlying string
then stop the algorithm.

Otherwise, if the DOMTokenList object's underlying string
is not the empty string and the last character of that string is
not a space character , then append a U+0020
SPACE character to the end of that string.

Append the value of token to the end of the
DOMTokenList object's
underlying string.

The remove(
token ) method must run the
following algorithm:

If the token argument contains any space characters , then raise
an INVALID_CHARACTER_ERR exception and stop the
algorithm.

Otherwise, if the DOMTokenList object's underlying string
is not the empty string and the last character of that string is
not a space character , then append a U+0020
SPACE character to the end of that string.

Append the value of token to the end of the
DOMTokenList object's
underlying string.

Return true.

Objects implementing the DOMTokenList interface must stringify to the
object's underlying string representation.

2.3.3
DOMStringMap

The DOMStringMap
interface represents a set of name-value pairs. When a
DOMStringMap object is
instanced, it is associated with three algorithms, one for getting
values from names, one for setting names to certain values, and one
for deleting names.

The names of the methods on this interface are
temporary and will be fixed when the Web IDL / "Language Bindings
for DOM Specifications" spec is ready to handle this case.

The XXX1(
name ) method must call the
algorithm for getting values from names, passing name as the name, and must return the corresponding value,
or null if name has no corresponding value.

The XXX2(
name , value )
method must call the algorithm for setting names to certain values,
passing name as the name and value as the value.

The XXX3(
name ) method must call the
algorithm for deleting names, passing name as
the name, and must return true.

2.3.4 DOM feature
strings

DOM3 Core defines mechanisms for checking for interface support,
and for obtaining implementations of interfaces, using feature
strings . [DOM3CORE]

A DOM application can use the hasFeature( feature ,
version ) method of the
DOMImplementation interface with parameter values "
HTML " and " 5.0 "
(respectively) to determine whether or not this module is supported
by the implementation. In addition to the feature string "
HTML ", the feature string " XHTML " (with version string " 5.0 ") can be
used to check if the implementation supports XHTML. User agents
should respond with a true value when the hasFeature method is queried with these
values. Authors are cautioned, however, that UAs returning true
might not be perfectly compliant, and that UAs returning false
might well have support for features in this specification; in
general, therefore, use of this method is discouraged.

The values " HTML " and " XHTML " (both with version " 5.0 ") should
also be supported in the context of the getFeature()
and isSupported() methods, as defined by DOM3
Core.

The interfaces defined in this specification are
not always supersets of the interfaces defined in DOM2 HTML; some
features that were formerly deprecated, poorly supported, rarely
used or considered unnecessary have been removed. Therefore it is
not guaranteed that an implementation that supports " HTML " " 5.0 " also supports " HTML " " 2.0 ".

2.4DOM tree accessors

The html element of a
document is the document's root element, if there is one and it's
an html element, or null
otherwise.

The head element of a
document is the first head element
that is a child of the html
element , if there is one, or null otherwise.

The title element of a
document is the first title
element in the document (in tree order), if there is one, or null
otherwise.

The title attribute must, on
getting, run the following algorithm:

If the root element is an
svg element in the " http://www.w3.org/2000/svg " namespace, and the user
agent supports SVG, then the getter must return the value that
would have been returned by the DOM attribute of the same name on
the SVGDocument interface.

If the root element is an
svg element in the " http://www.w3.org/2000/svg " namespace, and the user
agent supports SVG, then the setter must defer to the setter for
the DOM attribute of the same name on the SVGDocument
interface. Stop the algorithm here.

A single Text node whose data is the new value
being assigned must be appended to the
title element .

The title attribute on the HTMLDocument interface should shadow the
attribute of the same name on the SVGDocument
interface when the user agent supports both HTML and SVG.

The body element of a document is the
first child of the html
element that is either a body
element or a frameset element. If there is no such
element, it is null. If the body element is null, then when the
specification requires that events be fired at "the body element",
they must instead be fired at the Document object.

The body attribute, on getting,
must return the body element of the
document (either a body element,
a frameset element, or null). On setting, the
following algorithm must be run:

If the new value is not a body or frameset element, then
raise a HIERARCHY_REQUEST_ERR exception and abort
these steps.

Otherwise, if the new value is the same as the body element , do nothing. Abort these
steps.

Otherwise, if the body element is not
null, then replace that element with the new value in the DOM, as
if the root element's replaceChild() method
had been called with the new value and the incumbent body element as its two
arguments respectively, then abort these steps.

Otherwise, the the body element is
null. Append the new value to the root element.

The images attribute must
return an HTMLCollection rooted at the
Document node, whose filter matches only
img elements.

The embeds attribute must
return an HTMLCollection rooted at the
Document node, whose filter matches only
embed elements.

The plugins attribute must
return the same object as that returned by the embeds
attribute.

The links attribute must return
an HTMLCollection
rooted at the Document node, whose filter matches only
a elements with href attributes
and area elements with
href
attributes.

The forms attribute must return
an HTMLCollection
rooted at the Document node, whose filter matches only
form elements.

The anchors attribute must
return an HTMLCollection rooted at the
Document node, whose filter matches only
a elements with name attributes.

The scripts attribute must
return an HTMLCollection rooted at the
Document node, whose filter matches only
script elements.

The getElementsByName(
name ) method a string name , and must return a live NodeList
containing all the a , applet , button ,
form , iframe ,
img , input ,
map , meta , object , select , and
textarea elements in that document that have a
name attribute whose value is equal to the
name argument.

The getElementsByClassName(
classNames ) method takes a string
that contains an unordered set of unique
space-separated tokens representing classes. When called, the
method must return a live NodeList object containing
all the elements in the document that have all the classes
specified in that argument, having obtained the classes by splitting a string on
spaces . If there are no tokens specified in the argument, then
the method must return an empty NodeList .

The getElementsByClassName()
method on the HTMLElement
interface must return a live NodeList with the nodes
that the HTMLDocumentgetElementsByClassName()
method would return when passed the same argument(s), excluding any
elements that are not descendants of the HTMLElement object on which the method
was invoked.

HTML, SVG, and MathML elements define which classes they are in
by having an attribute in the per-element partition with the name
class containing a space-separated list of
classes to which the element belongs. Other specifications may also
allow elements in their namespaces to be labeled as being in
specific classes. UAs must not assume that all attributes of the
name class for elements in any namespace work
in this way, however, and must not assume that such attributes,
when used as global attributes, label other elements as being in
specific classes.

A call to
document.getElementById('example').getElementsByClassName('aaa')
would return a NodeList with the two paragraphs
p1 and p2 in it.

A call to getElementsByClassName('ccc bbb')
would only return one node, however, namely p3 . A
call to
document.getElementById('example').getElementsByClassName('bbb ccc ')
would return the same thing.

A call to getElementsByClassName('aaa,bbb') would
return no nodes; none of the elements above are in the "aaa,bbb"
class.

The dir attribute on the HTMLDocument interface is defined along
with the dir
content attribute.

2.5Dynamic markup insertion

The document.write() family of methods and
the innerHTML family of DOM attributes enable
script authors to dynamically insert markup into the document.

bz argues that innerHTML should be called
something else on XML documents and XML elements. Is the sanity
worth the migration pain?

Because these APIs interact with the parser, their behavior
varies depending on whether they are used with HTML documents (and the HTML
parser ) or XHTML in XML documents
(and the XML parser ). The following table
cross-references the various versions of these APIs.

Regardless of the parsing mode, the document.writeln(...)
method must call the document.write() method with the same
argument(s), and then call the document.write() method with, as its
argument, a string consisting of a single line feed character
(U+000A).

2.5.1 Controlling
the input stream

The open() method comes in
several variants with different numbers of arguments.

When called with two or fewer arguments, the method must act as
follows:

Let type be the value of the first argument,
if there is one, or " text/html " otherwise.

Let replace be true if there is a second
argument and it has the value "replace" , and false otherwise.

If the document has an active parser that isn't a
script-created parser , and the
insertion point associated with that
parser's input stream is not undefined (that
is, it does point to somewhere in the input stream), then
the method does nothing. Abort these steps and return the
Document object on which the method was invoked.

This basically causes document.open() to
be ignored when it's called in an inline script found during the
parsing of data sent over the network, while still letting it have
an effect when called asynchronously or on a document that is
itself being spoon-fed using these APIs.

If the document has an active parser , then stop
that parser, and throw away any pending content in the input
stream. what about if it doesn't, because
it's either like a text/plain, or Atom, or PDF, or XHTML, or image
document, or something?

Add a new entry just before the last entry that is associated
with the text that was parsed by the previous parser associated
with the Document object, as well as the state of the
document at the start of these steps. (This allows the user to step
backwards in the session history to see the page before it was
blown away by the document.open() call.)

We shouldn't hard-code text/plain
there. We should do it some other way, e.g. hand off to the section
on content-sniffing and handling of incoming data streams, the part
that defines how this all works when stuff comes over the
network.

When called with three or more arguments, the open() method on the
HTMLDocument object must
call the open()
method on the Window interface
of the object returned by the defaultView attribute of the
DocumentView interface of the HTMLDocument object, with the same
arguments as the original call to the open() method, and
return whatever that method returned. If the defaultView attribute of the
DocumentView interface of the HTMLDocument object is null, then the
method must raise an INVALID_ACCESS_ERR exception.

Otherwise, the tokeniser must process the characters that were
inserted, one at a time, processing resulting tokens as they are
emitted, and stopping when the tokeniser reaches the insertion
point or when the processing of the tokeniser is aborted by the
tree construction stage (this can happen if a script start tag token is emitted by the
tokeniser).

In HTML, the innerHTML DOM attribute of
all HTMLElement and
HTMLDocument nodes returns
a serialization of the node's children using the HTML
syntax . On setting, it replaces the node's children with
new nodes that result from parsing the given value. The formal
definitions follow.

On setting, if the node is a document, the innerHTML DOM
attribute must run the following algorithm:

If the document has an active parser , then stop
that parser, and throw away any pending content in the input
stream. what about if it doesn't, because
it's either like a text/plain, or Atom, or PDF, or XHTML, or image
document, or something?

Remove the children nodes of the Document whose
innerHTML attribute is being set.

Create a new HTML parser , in its initial
state, and associate it with the Document node.

Start the parser and let it run until it has consumed all the
characters just inserted into the input stream. (The
Document node will have been populated with elements
and a load
event will have fired on its body element .)

Otherwise, if the node is an element, then setting the
innerHTML DOM attribute must cause the
following algorithm to run instead:

Invoke the HTML fragment parsing
algorithm , with the element whose innerHTML
attribute is being set as the context element,
and the string being assigned into the innerHTML
attribute as the input . Let new
children be the result of this algorithm.

Remove the children of the element whose innerHTML
attribute is being set.

Let target document be the ownerDocument of the Element node whose
innerHTML attribute is being set.

Set the ownerDocument of all the nodes in
new children to the target
document .

Append all the new children nodes to the
node whose innerHTML attribute is being set,
preserving their order.

script elements
inserted using innerHTML do not execute when they are
inserted.

2.5.3 Dynamic markup
insertion in XML

In an XML context, the document.write() method
must raise an INVALID_ACCESS_ERR exception.

On the other hand, however, the innerHTML attribute is
indeed usable in an XML context.

In an XML context, the innerHTML DOM attribute on HTMLElement s must return a string in the
form of an internal
general parsed entity , and on HTMLDocument s must return a string in
the form of a document entity .
The string returned must be XML namespace-well-formed and must be
an isomorphic serialization of all of that node's child nodes, in
document order. User agents may adjust prefixes and namespace
declarations in the serialization (and indeed might be forced to do
so in some cases to obtain namespace-well-formed XML). If any of
the elements in the serialization are in no namespace, the default
namespace in scope for those elements must be explicitly declared
as the empty string. [XML][XMLNS]

If any of the following cases are found in the DOM being
serialized, the user agent must raise an
INVALID_STATE_ERR exception:

A Document node with no child element nodes.

A DocumentType node that has an external subset
public identifier or an external subset system identifier that
contains both a U+0022 QUOTATION MARK ('"') and a U+0027 APOSTROPHE
("'").

These are the only ways to make a DOM
unserializable. The DOM enforces all the other XML constraints; for
example, trying to set an attribute with a name that contains an
equals sign (=) will raised an INVALID_CHARACTER_ERR
exception.

If the innerHTML attribute is being set on an
element, the user agent must feed the parser just
created the string corresponding to the start tag of that element,
declaring all the namespace prefixes that are in scope on that
element in the DOM, as well as declaring the default namespace (if
any) that is in scope on that element in the DOM.

The user agent must feed the parser just created
the string being assigned into the innerHTML
attribute.

If the innerHTML attribute is being set on an
element, the user agent must feed the parser the
string corresponding to the end tag of that element.

If the parser found a well-formedness error, the attribute's
setter must raise a SYNTAX_ERR exception and abort
these steps.

The user agent must remove the children nodes of the node whose
innerHTML attribute is being set.

If the attribute is being set on a Document node,
let new children be the children of the
document, preserving their order. Otherwise, the attribute is being
set on an Element node; let new
children be the children of the document's root element,
preserving their order.

If the attribute is being set on a Document node,
let target document be that
Document node. Otherwise, the attribute is being set
on an Element node; let target
document be the ownerDocument of that
Element .

Set the ownerDocument of all the nodes in
new children to the target
document .

Append all the new children nodes to the
node whose innerHTML attribute is being set,
preserving their order.

script elements
inserted using innerHTML do not execute when they are
inserted.

These attributes return tag names in all uppercase and attribute
names in all lowercase, regardless of the case with which they were
created.

Document.createElement()

The canonical form of HTML markup is all-lowercase; thus, this
method will lowercase the argument before creating the requisite
element. Also, the element created must be in the HTML namespace .

This doesn't apply to Document.createElementNS() . Thus, it is possible, by
passing this last method a tag name in the wrong case, to create an
element that claims to have the tag name of an element defined in
this specification, but doesn't support its interfaces, because it
really has another tag name not accessible from the DOM APIs.

Element.setAttributeNode()

When an Attr node is set on an HTML element , it must
have its name lowercased before the element is affected.

This doesn't apply to Document.setAttributeNodeNS() .

Element.setAttribute()

When an attribute is set on an HTML element , the name argument must be
lowercased before the element is affected.

This doesn't apply to Document.setAttributeNS() .

Document.getElementsByTagName() and
Element.getElementsByTagName()

These methods (but not their namespaced counterparts) must
compare the given argument case-insensitively when looking at
HTML elements ,
and case-sensitively otherwise.

Thus, in an HTML document with nodes in multiple
namespaces, these methods will be both case-sensitive and
case-insensitive at the same time.

Document.renameNode()

If the new namespace is the HTML
namespace , then the new qualified name must be lowercased
before the rename takes place.

3. Semantics and
structure of HTML elements

3.1
Introduction

This section is non-normative.

An introduction to marking up a document.

3.2 Common
microsyntaxes

There are various places in HTML that accept particular data
types, such as dates or numbers. This section describes what the
conformance criteria for content in those formats is, and how to
parse them.

Need to go through the whole spec and make
sure all the attribute values are clearly defined either in terms
of microsyntaxes or in terms of other specs, or as "Text" or some
such.

3.2.1 Common parser
idioms

The space
characters , for the purposes of this specification, are
U+0020 SPACE, U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED
(LF), U+000C FORM FEED (FF), and U+000D CARRIAGE RETURN (CR).

Some of the micro-parsers described below follow the pattern of
having an input variable that holds the string
being parsed, and having a position variable
pointing at the next character to parse in input .

For parsers based on this pattern, a step that requires the user
agent to collect a sequence of characters
means that the following algorithm must be run, with characters being the set of characters that can be
collected:

Let input and position
be the same variables as those of the same name in the algorithm
that invoked these steps.

Let result be the empty string.

While position doesn't point past the end of
input and the character at position is one of the characters ,
append that character to the end of result and
advance position to the next character in
input .

3.2.2 Boolean
attributes

A number of attributes in HTML5 are boolean attributes . The presence of a
boolean attribute on an element represents the true value, and the
absence of the attribute represents the false value.

If the attribute is present, its value must either be the empty
string or a value that is a case-insensitive match for the
attribute's canonical name, with no leading or trailing
whitespace.

3.2.3 Numbers

3.2.3.1. Unsigned
integers

A string is a valid non-negative integer
if it consists of one of more characters in the range U+0030 DIGIT
ZERO (0) to U+0039 DIGIT NINE (9).

The rules for parsing non-negative
integers are as given in the following algorithm. When
invoked, the steps must be followed in the order given, aborting at
the first step that returns a value. This algorithm will either
return zero, a positive integer, or an error. Leading spaces are
ignored. Trailing spaces and indeed any trailing garbage characters
are ignored.

Let input be the string being parsed.

Let position be a pointer into input , initially pointing at the start of the string.

If the next character is not one of U+0030 DIGIT ZERO (0) ..
U+0039 DIGIT NINE (9), then return an error.

If the next character is one of U+0030 DIGIT ZERO (0) .. U+0039
DIGIT NINE (9):

Multiply value by ten.

Add the value of the current character (0..9) to value .

Advance position to the next
character.

If position is not past the end of
input , return to the top of step 7 in the
overall algorithm (that's the step within which these substeps find
themselves).

Return value .

3.2.3.2. Signed
integers

A string is a valid integer if it
consists of one of more characters in the range U+0030 DIGIT ZERO
(0) to U+0039 DIGIT NINE (9), optionally prefixed with a U+002D
HYPHEN-MINUS ("-") character.

The rules for parsing integers are
similar to the rules for non-negative integers, and are as given in
the following algorithm. When invoked, the steps must be followed
in the order given, aborting at the first step that returns a
value. This algorithm will either return an integer or an error.
Leading spaces are ignored. Trailing spaces and trailing garbage
characters are ignored.

Let input be the string being parsed.

Let position be a pointer into input , initially pointing at the start of the string.

If the character indicated by position (the
first character) is a U+002D HYPHEN-MINUS ("-") character:

Let sign be "negative".

Advance position to the next
character.

If position is past the end of input , return an error.

If the next character is not one of U+0030 DIGIT ZERO (0) ..
U+0039 DIGIT NINE (9), then return an error.

If the next character is one of U+0030 DIGIT ZERO (0) .. U+0039
DIGIT NINE (9):

Multiply value by ten.

Add the value of the current character (0..9) to value .

Advance position to the next
character.

If position is not past the end of
input , return to the top of step 9 in the
overall algorithm (that's the step within which these substeps find
themselves).

If sign is "positive", return value , otherwise return 0- value
.

3.2.3.3. Real
numbers

A string is a valid floating point number
if it consists of one of more characters in the range U+0030 DIGIT
ZERO (0) to U+0039 DIGIT NINE (9), optionally with a single U+002E
FULL STOP (".") character somewhere (either before these numbers,
in between two numbers, or after the numbers), all optionally
prefixed with a U+002D HYPHEN-MINUS ("-") character.

The rules for parsing floating point number
values are as given in the following algorithm. As with the
previous algorithms, when this one is invoked, the steps must be
followed in the order given, aborting at the first step that
returns a value. This algorithm will either return a number or an
error. Leading spaces are ignored. Trailing spaces and garbage
characters are ignored.

Let input be the string being parsed.

Let position be a pointer into input , initially pointing at the start of the string.

If the character indicated by position (the
first character) is a U+002D HYPHEN-MINUS ("-") character:

Let sign be "negative".

Advance position to the next
character.

If position is past the end of input , return an error.

If the next character is not one of U+0030 DIGIT ZERO (0) ..
U+0039 DIGIT NINE (9) or U+002E FULL STOP ("."), then return an
error.

If the next character is U+002E FULL STOP ("."), but either that
is the last character or the character after that one is not one of
U+0030 DIGIT ZERO (0) .. U+0039 DIGIT NINE (9), then return an
error.

If the next character is one of U+0030 DIGIT ZERO (0) .. U+0039
DIGIT NINE (9):

Multiply value by ten.

Add the value of the current character (0..9) to value .

Advance position to the next
character.

If position is past the end of input , then if sign is "positive",
return value , otherwise return 0- value .

Otherwise return to the top of step 10 in the overall algorithm
(that's the step within which these substeps find themselves).

Otherwise, if the next character is not a U+002E FULL STOP
("."), then if sign is "positive", return
value , otherwise return 0- value .

The next character is a U+002E FULL STOP ("."). Advance
position to the character after that.

Let divisor be 1.

If the next character is one of U+0030 DIGIT ZERO (0) .. U+0039
DIGIT NINE (9):

Multiply divisor by ten.

Add the value of the current character (0..9) divided by
divisor , to value .

Advance position to the next
character.

If position is past the end of input , then if sign is "positive",
return value , otherwise return 0- value .

Otherwise return to the top of step 14 in the overall algorithm
(that's the step within which these substeps find themselves).

3.2.3.4. Ratios

The algorithms described in this section are used
by the progress and
meter elements.

A valid denominator punctuation character
is one of the characters from the table below. There is a value
associated with each denominator punctuation character , as
shown in the table below.

Denominator Punctuation Character

Value

U+0025 PERCENT SIGN

%

100

U+066A ARABIC PERCENT SIGN

٪

100

U+FE6A SMALL PERCENT SIGN

﹪

100

U+FF05 FULLWIDTH PERCENT SIGN

％

100

U+2030 PER MILLE SIGN

‰

1000

U+2031 PER TEN THOUSAND SIGN

‱

10000

The steps for finding one or two numbers of a
ratio in a string are as follows:

If the string is empty, then return nothing and abort these
steps.

Find a number in the string according to
the algorithm below, starting at the start of the string.

If the sub-algorithm in step 2 returned nothing or returned an
error condition, return nothing and abort these steps.

Set number1 to the number returned by the
sub-algorithm in step 2.

Starting with the character immediately after the last one
examined by the sub-algorithm in step 2, skip any characters in the
string that are in the Unicode character class Zs (this might match
zero characters). [UNICODE]

If the string contains any other characters in the range U+0030
DIGIT ZERO to U+0039 DIGIT NINE, return nothing and abort these
steps.

Otherwise, return number1 and number2 .

The algorithm to find a number is as
follows. It is given a string and a starting position, and returns
either nothing, a number, or an error condition.

Starting at the given starting position, ignore all characters
in the given string until the first character that is either a
U+002E FULL STOP or one of the ten characters in the range U+0030
DIGIT ZERO to U+0039 DIGIT NINE.

If there are no such characters, return nothing and abort these
steps.

Starting with the character matched in step 1, collect all the
consecutive characters that are either a U+002E FULL STOP or one of
the ten characters in the range U+0030 DIGIT ZERO to U+0039 DIGIT
NINE, and assign this string of one or more characters to
string .

If string contains more than one U+002E
FULL STOP character then return an error condition and abort these
steps.

3.2.3.5. Percentages and dimensions

3.2.3.6. Lists of
integers

A valid list of integers is a number of
valid integers
separated by U+002C COMMA characters, with no other characters
(e.g. no space
characters ). In addition, there might be restrictions on the
number of integers that can be given, or on the range of values
allowed.

The rules for parsing a list of integers
are as follows:

Let input be the string being parsed.

Let position be a pointer into input , initially pointing at the start of the string.

Let numbers be an initially empty list of
integers. This list will be the result of this algorithm.

If there is a character in the string input
at position position , and it is either a
U+0020 SPACE, U+002C COMMA, or U+003B SEMICOLON character, then
advance position to the next character in
input , or to beyond the end of the string if
there are no more characters.

If position points to beyond the end of
input , return numbers and
abort.

If the character in the string input at
position position is a U+0020 SPACE, U+002C
COMMA, or U+003B SEMICOLON character, then return to step 4.

Let negated be false.

Let value be 0.

Let started be false. This variable is set
to true when the parser sees a number or a " - " character.

Let got number be false. This variable is
set to true when the parser sees a number.

Let finished be false. This variable is set
to true to switch parser into a mode where it ignores characters
until the next separator.

Let bogus be false.

Parser: If the character in the string input at position position is:

A U+002D HYPHEN-MINUS character

Follow these substeps:

If got number is true, let finished be true.

If finished is true, skip to the next step
in the overall set of steps.

If started is true, let negated be false.

Otherwise, if started is false and if
bogus is false, let negated
be true.

Let started be true.

A character in the range U+0030 DIGIT ZERO .. U+0039 DIGIT
NINE

Follow these substeps:

If finished is true, skip to the next step
in the overall set of steps.

Multiply value by ten.

Add the value of the digit, interpreted in base ten, to
value .

Let started be true.

Let got number be true.

A U+0020 SPACE character

A U+002C COMMA character

A U+003B SEMICOLON character

Follow these substeps:

If got number is false, return the
numbers list and abort. This happens if an
entry in the list has no digits, as in " 1,2,x,4 ".

If negated is true, then negate value .

Append value to the numbers list.

Jump to step 4 in the overall set of steps.

A U+002E FULL STOP character

Follow these substeps:

If got number is true, let finished be true.

If finished is true, skip to the next step
in the overall set of steps.

Let negated be false.

Any other character

Follow these substeps:

If finished is true, skip to the next step
in the overall set of steps.

Let negated be false.

Let bogus be true.

If started is true, then return the
numbers list, and abort. (The value in
value is not appended to the list first; it is
dropped.)

Advance position to the next character in
input , or to beyond the end of the string if
there are no more characters.

If position points to a character (and not
to beyond the end of input ), jump to the big
Parser step above.

If negated is true, then negate value .

If got number is true, then append
value to the numbers
list.

Return the numbers list and abort.

3.2.4 Dates and
times

In the algorithms below, the number of days in
month month of year year is: 31 if month is
1, 3, 5, 7, 8, 10, or 12; 30 if month
is 4, 6, 9, or 11; 29 if month is 2
and year is a number divisible by 400, or if
year is a number divisible by 4 but not by 100;
and 28 otherwise. This takes into account leap years in
the Gregorian calendar. [GREGORIAN]

3.2.4.1. Specific
moments in time

A string is a valid datetime if it has
four digits (representing the year), a literal hyphen, two digits
(representing the month), a literal hyphen, two digits
(representing the day), optionally some spaces, either a literal T
or a space, optionally some more spaces, two digits (for the hour),
a colon, two digits (the minutes), optionally the seconds (which,
if included, must consist of another colon, two digits (the integer
part of the seconds), and optionally a decimal point followed by
one or more digits (for the fractional part of the seconds)),
optionally some spaces, and finally either a literal Z (indicating
the time zone is UTC), or, a plus sign or a minus sign followed by
two digits, a colon, and two digits (for the sign, the hours and
minutes of the timezone offset respectively); with the month-day
combination being a valid date in the given year according to the
Gregorian calendar, the hour values ( h ) being
in the range 0 ≤ h
≤ 23, the minute values ( m ) in
the range 0 ≤ m
≤ 59, and the second value ( s )
being in the range 0 ≤ h
< 60. [GREGORIAN]

The digits must be characters in the range U+0030 DIGIT ZERO (0)
to U+0039 DIGIT NINE (9), the hyphens must be a U+002D HYPHEN-MINUS
characters, the T must be a U+0054 LATIN CAPITAL LETTER T, the
colons must be U+003A COLON characters, the decimal point must be a
U+002E FULL STOP, the Z must be a U+005A LATIN CAPITAL LETTER Z,
the plus sign must be a U+002B PLUS SIGN, and the minus U+002D
(same as the hyphen).

One millisecond after noon on October 14th 1979, in the time
zone in use on the east coast of North America during daylight
saving time.

" 8592-01-01 T 02:09 +02:09 "

Midnight UTC on the 1st of January, 8592. The time zone
associated with that time is two hours and nine minutes ahead of
UTC.

Several things are notable about these dates:

Years with fewer than four digits have to be zero-padded. The
date "37-12-13" would not be a valid date.

To unambiguously identify a moment in time prior to the
introduction of the Gregorian calendar, the date has to be first
converted to the Gregorian calendar from the calendar in use at the
time (e.g. from the Julian calendar). The date of Nero's birth is
the 15th of December 37, in the Julian Calendar, which is the 13th
of December 37 in the Gregorian Calendar.

The time and timezone components are not optional.

Dates before the year 0 or after the year 9999 can't be
represented as a datetime in this version of HTML.

Time zones differ based on daylight savings time.

Conformance checkers can use the algorithm below to
determine if a datetime is a valid datetime or not.

To parse a string as a datetime
value , a user agent must apply the following algorithm to
the string. This will either return a time in UTC, with associated
timezone information for round tripping or display purposes, or
nothing, indicating the value is not a valid
datetime . If at any point the algorithm says that it "fails",
this means that it returns nothing.

Let input be the string being parsed.

Let position be a pointer into input , initially pointing at the start of the string.

Collect a sequence of characters in the
range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the
collected sequence is not exactly four characters long, then fail.
Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the year .

If position is beyond the end of input or if the character at position
is not a U+002D HYPHEN-MINUS character, then fail. Otherwise, move
position forwards one character.

Collect a sequence of characters in the
range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the
collected sequence is not exactly two characters long, then fail.
Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the month .

If position is beyond the end of input or if the character at position
is not a U+002D HYPHEN-MINUS character, then fail. Otherwise, move
position forwards one character.

Collect a sequence of characters in the
range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the
collected sequence is not exactly two characters long, then fail.
Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the day .

If day is not a number in the range
1 ≤ month ≤
maxday , then fail.

Collect a sequence of characters that are
either U+0054 LATIN CAPITAL LETTER T characters or space characters . If the collected
sequence is zero characters long, or if it contains more than one
U+0054 LATIN CAPITAL LETTER T character, then fail.

Collect a sequence of characters in the
range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the
collected sequence is not exactly two characters long, then fail.
Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the hour .

If hour is not a number in the range
0 ≤ hour ≤ 23, then
fail.

If position is beyond the end of input or if the character at position
is not a U+003A COLON character, then fail. Otherwise, move
position forwards one character.

Collect a sequence of characters in the
range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the
collected sequence is not exactly two characters long, then fail.
Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the minute .

If minute is not a number in the range
0 ≤ minute ≤ 59,
then fail.

Let second be a string with the value
"0".

If position is beyond the end of input , then fail.

If the character at position is a U+003A
COLON, then:

Advance position to the next character in
input .

If position is beyond the end of input , or at the last character in input , or if the next two characters in
input starting at position
are not two characters both in the range U+0030 DIGIT ZERO (0) to
U+0039 DIGIT NINE (9), then fail.

Collect a sequence of characters that are
either characters in the range U+0030 DIGIT ZERO (0) to U+0039
DIGIT NINE (9) or U+002E FULL STOP characters. If the collected
sequence has more than one U+002E FULL STOP characters, or if the
last character in the sequence is a U+002E FULL STOP character,
then fail. Otherwise, let the collected string be second instead of its previous value.

Interpret second as a base-ten number
(possibly with a fractional part). Let that number be second instead of the string version.

If second is not a number in the range
0 ≤ hour < 60, then
fail. (The values 60 and 61 are not allowed: leap seconds cannot be
represented by datetime values.)

If the character at position is a U+005A
LATIN CAPITAL LETTER Z, then:

Let timezone hours be
0.

Let timezone minutes be
0.

Advance position to the next character in
input .

Otherwise, if the character at position is
either a U+002B PLUS SIGN ("+") or a U+002D HYPHEN-MINUS ("-"),
then:

If the character at position is a U+002B
PLUS SIGN ("+"), let sign be "positive".
Otherwise, it's a U+002D HYPHEN-MINUS ("-"); let sign be "negative".

Advance position to the next character in
input .

Collect a sequence of characters in the
range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the
collected sequence is not exactly two characters long, then fail.
Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the timezone hours .

If timezone hours is
not a number in the range 0 ≤ timezone
hours ≤ 23, then fail.

If sign is "negative", then negate
timezone hours .

If position is beyond the end of input or if the character at position
is not a U+003A COLON character, then fail. Otherwise, move
position forwards one character.

Collect a sequence of characters in the
range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the
collected sequence is not exactly two characters long, then fail.
Otherwise, interpret the resulting sequence as a base-ten integer.
Let that number be the timezone minutes .

If timezone minutes is
not a number in the range 0 ≤ timezone
minutes ≤ 59, then
fail.

If sign is "negative", then negate
timezone minutes .

If position is not beyond the end
of input , then fail.

Let time be the moment in time at year
year , month month , day
day , hours hour , minute
minute , second second ,
subtracting timezone hours
hours and timezone minutes
minutes. That moment in time is a moment in the UTC timezone.

3.2.4.2. Vaguer moments
in time

This section defines date or time strings . There are two
kinds, date or time strings in
content , and date or time strings in
attributes . The only difference is in the handling of
whitespace characters.

To parse a date or time string , user
agents must use the following algorithm. A date
or time string is a valid date or time string if the
following algorithm, when run on the string, doesn't say the string
is invalid.

The algorithm may return nothing (in which case the string will
be invalid), or it may return a date, a time, a date and a time, or
a date and a time and a timezone. Even if the algorithm returns one
or more values, the string can still be invalid.

Let input be the string being parsed.

Let position be a pointer into input , initially pointing at the start of the string.

Let results be the collection of results
that are to be returned (one or more of a date, a time, and a
timezone), initially empty. If the algorithm aborts at any point,
then whatever is currently in results must be
returned as the result of the algorithm.

If position is past the end of input , or if the character at position is not a U+002D HYPHEN-MINUS ("-")
character, then the string is invalid, abort these steps.
Otherwise, advance position to the next
character.

Collect a sequence of characters in the
range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the
collected sequence is empty, then the string is invalid; abort
these steps.

If the sequence collected in the last step is not exactly two
digits long, then the string is invalid.

Interpret the sequence of characters collected two steps ago as
a base-ten integer, and let that number be day
.

If day is not a number in the range
1 ≤ day ≤
maxday , then the string is invalid, abort
these steps.

Collect a sequence of characters in the
range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the
collected sequence is empty, then the string is invalid; abort
these steps.

Let s be the sequence of characters
collected in the last step.

If s is not exactly two digits long, then
the string is invalid.

Interpret the sequence of characters collected two steps ago as
a base-ten integer, and let that number be hour
.

If hour is not a number in the range
0 ≤ hour ≤ 23, then
the string is invalid, abort these steps.

If position is past the end of input , or if the character at position is not a U+003A COLON character, then
the string is invalid, abort these steps. Otherwise, advance
position to the next character.

Collect a sequence of characters in the
range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the
collected sequence is empty, then the string is invalid; abort
these steps.

If the sequence collected in the last step is not exactly two
digits long, then the string is invalid.

Interpret the sequence of characters collected two steps ago as
a base-ten integer, and let that number be minute .

If minute is not a number in the range
0 ≤ minute ≤ 59,
then the string is invalid, abort these steps.

Let second be 0. It may be changed to
another value in the next step.

If position is not past the end of
input and the character at position is a U+003A COLON character, then:

Collect a sequence of characters that are
either characters in the range U+0030 DIGIT ZERO (0) to U+0039
DIGIT NINE (9) or are U+002E FULL STOP. If the collected sequence
is empty, or contains more than one U+002E FULL STOP character,
then the string is invalid; abort these steps.

If the first character in the sequence collected in the last
step is not in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE
(9), then the string is invalid.

Interpret the sequence of characters collected two steps ago as
a base-ten number (possibly with a fractional part), and let that
number be second .

If second is not a number in the range
0 ≤ minute < 60,
then the string is invalid, abort these steps.

Add the time represented by hour ,
minute , and second to the
results .

If position is not past the end of
input , then the string is invalid.

Abort these steps (the string is parsed).

3.2.5 Time
offsets

valid time offset ,
rules for parsing time offsets , time offset serialization rules ; in the format
"5d4h3m2s1ms" or "3m 9.2s" or "00:00:00.00" or similar.

3.2.6 Tokens

A set of space-separated tokens is a set
of zero or more words separated by one or more space characters , where words consist
of any string of one or more characters, none of which are space characters .

An ordered set of unique space-separated
tokens is a set of space-separated
tokens where none of the words are duplicated but where the
order of the tokens is meaningful.

Sets of
space-separated tokens sometimes have a defined set of allowed
values. When a set of allowed values is defined, the tokens must
all be from that list of allowed values; other values are
non-conforming. If no such set of allowed values is provided, then
all values are conforming.

When a user agent has to split a string on
spaces , it must use the following algorithm:

Let input be the string being parsed.

Let position be a pointer into input , initially pointing at the start of the string.

If position is not past the end of
input , and output is not
the empty string, append a single U+0020 SPACE character at the end
of output .

Otherwise, append s to the end of
output .

Return to step 6 in the overall set of steps.

This causes any occurrences of the token to be
removed from the string, and any spaces that were surrounding the
token to be collapsed to a single space, except at the start and
end of the string, where such spaces are removed.

3.2.7 Keywords and
enumerated attributes

Some attributes are defined as taking one of a finite set of
keywords. Such attributes are called enumerated attributes . The keywords
are each defined to map to a particular state (several
keywords might map to the same state, in which case some of the
keywords are synonyms of each other; additionally, some of the
keywords can be said to be non-conforming, and are only in the
specification for historical reasons). In addition, two default
states can be given. The first is the invalid value
default , the second is the missing value default
.

If an enumerated attribute is specified, the attribute's value
must be one of the given keywords that are not said to be
non-conforming, with no leading or trailing whitespace. The keyword
may use any mix of uppercase and lowercase letters.

When the attribute is specified, if its value
case-insensitively matches one of the given keywords
then that keyword's state is the state that the attribute
represents. If the attribute value matches none of the given
keywords, but the attribute has an invalid value default ,
then the attribute represents that state. Otherwise, if the
attribute value matches none of the keywords but there is a
missing value default state defined, then that is
the state represented by the attribute. Otherwise, there is no
default, and invalid values must be ignored.

When the attribute is not specified, if there is a
missing value default state defined, then that is the
state represented by the (missing) attribute. Otherwise, the
absence of the attribute means that there is no state
represented.

The empty string can be one of the keywords in some
cases. For example the contenteditable attribute has two
states: true , matching the true
keyword and the empty string, false , matching
false and all other keywords (it's the
invalid value default ). It could further be thought of as
having a third state inherit , which would be the default
when the attribute is not specified at all (the missing value
default ), but for various reasons that isn't the way this
specification actually defines it.

3.2.8
References

A valid hash-name reference to an element
of type type is a string consisting of a U+0023
NUMBER SIGN ( # ) character followed by a
string which exactly matches the value of the name attribute of an element in the document with type
type .

The rules for parsing a hash-name
reference to an element of type type are
as follows:

If the string being parsed does not contain a U+0023 NUMBER SIGN
character, or if the first such character in the string is the last
character in the string, then return null and abort these
steps.

Let s be the string from the character
immediately after the first U+0023 NUMBER SIGN character in the
string being parsed up to the end of that string.

Return the first element of type type that
has an id or
name attribute whose value case-insensitively
matches s .

3.2.9 URLs

This section will do the following:

define how to resolve relative URLs in markup attributes (using
XMLBase as defined elsewhere right now)

define how to resolve relative URLs in APIs, using the script's base URI maybe

define what it means to resolve a relative URL when the base
URL doesn't have a path hierarchy (e.g. data:, javascript:,
about:blank URLs)

define how to handle URIs that contain non-ascii characters
(and it's not the same as handling as IRIs, especially if the
character encoding of the document isn't UTF-8)

define URL as IRI and replace all uses of URIs and IRIs in the
rest of the spec with URL

define "valid URL" in terms of valid URIs and IRIs and replace
that concept through the spec to a pointer here, getting rid of
references to [RFC3986][RFC3987]

define "valid URL reference" in terms of valid URI references
and IRI references and replace that concept through the spec to a
pointer here, getting rid of references to [RFC3986][RFC3987]

define how to parse URLs (maybe by deferring to RFCs)

define "an element's base URI " and
make the various places that talk about a base URI in the context
of an element use that definition

make the language used to refer to resolving a base URI
consistent throughout, maybe make it hyperlink to a definition each
time

define a cheap, interoperable mechanism for URL attributes and
anything else that relies on xml:base and the base element to
handle dynamic changes to those attributes and elements, possibly
by defining some mechanism which causes changes to be ignored in
some reliable way.

3.3 Documents and
document fragments

3.3.1 Semantics

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, and attribute values
for purposes other than their appropriate intended semantic
purpose.

For example, the following document is non-conforming, despite
being syntactically correct:

This next document fragment, intended to represent the heading
of a corporate site, is similarly non-conforming because the second
line is not intended to be a heading of a subsection, but merely a
subheading or subtitle (a subordinate heading for the same
section).

<body>
<h1>ABC Company</h1>
<h2>Leading the way in widget design since 1432</h2>
...

Through scripting and using other mechanisms, the values of
attributes, text, and indeed the entire structure of the document
may change dynamically while a user agent is processing it. The
semantics of a document at an instant in time are those represented
by the state of the document at that instant in time, and the
semantics of a document can therefore change over time. User agents
must update their presentation of the document as this occurs.

HTML has a progress element that describes a progress
bar. If its "value" attribute is dynamically updated by a script,
the UA would update the rendering to show the progress
changing.

3.3.2 Structure

All the elements in this specification have a defined content
model, which describes what nodes are allowed inside the elements,
and thus what the structure of an HTML document or fragment must
look like.

The space
characters are always allowed between elements. User agents
represent these characters between elements in the source markup as
text nodes in the DOM. Empty text nodes and text nodes consisting of just sequences of those
characters are considered inter-element
whitespace .

Inter-element whitespace , comment
nodes, and processing instruction nodes must be ignored when
establishing whether an element matches its content model or not,
and must be ignored when following algorithms that define document
and element semantics.

An element A is said to be preceded or followed by a second element
B if A and B have the same parent node and there are no other element
nodes or text nodes (other than inter-element whitespace ) between them.

Authors must not use elements in the HTML
namespace anywhere except where they are explicitly allowed, as
defined for each element, or as explicitly required by other
specifications. For XML compound documents, these contexts could be
inside elements from other namespaces, if those elements are
defined as providing the relevant contexts.

The SVG specification defines the SVG foreignObject
element as allowing foreign namespaces to be included, thus
allowing compound documents to be created by inserting subdocument
content under that element. This specification defines the
XHTML html element as being
allowed where subdocument fragments are allowed in a compound
document. Together, these two definitions mean that placing an
XHTML html element as a child of
an SVG foreignObject element is conforming. [SVG]

The Atom specification defines the Atom content element, when its type
attribute has the value xhtml , as requiring
that it contains a single HTML div
element. Thus, a div element is
allowed in that context, even though this is not explicitly
normatively stated by this specification. [ATOM]

Some elements have unique requirements and do not fit into any
particular category.

3.3.3.1. Metadata
content

Metadata content is content that sets
up the presentation or behavior of the rest of the content, or that
sets up the relationship of the document with other documents, or
that conveys other "out of band" information.

Elements from other namespaces whose semantics are primarily
metadata-related (e.g. RDF) are also metadata
content .

3.3.3.2. Flow
content

Most elements that are used in the body of documents and
applications are categorized as flow
content .

As a general rule, elements whose content model allows any
flow content should have either at
least one descendant text node that is not inter-element whitespace , or at least one
descendant element node that is embedded
content . For the purposes of this requirement, del elements and their descendants must not be
counted as contributing to the ancestors of the del element.

This requirement is not a hard requirement, however, as there
are many cases where an element can be empty legitimately, for
example when it is used as a placeholder which will later be filled
in by a script, or when the element is part of a template and would
on most pages be filled in but on some pages is not relevant.

As a general rule, elements whose content model allows any
phrasing content should have either at
least one descendant text node that is not inter-element whitespace , or at least one
descendant element node that is embedded
content . For the purposes of this requirement, nodes that are
descendants of del elements must
not be counted as contributing to the ancestors of the
del element.

Most elements that are categorized as phrasing
content can only contain elements that are themselves categorized
as phrasing content, not any flow content.

Elements that are from namespaces other than the HTML namespace and that convey content but
not metadata, are embedded content for the
purposes of the content models defined in this specification. (For
example, MathML, or SVG.)

Some embedded content elements can have fallback content : content that is to be used when
the external resource cannot be used (e.g. because it is of an
unsupported format). The element definitions state what the
fallback is, if any.

3.3.3.7.
Interactive content

Parts of this section should eventually be
moved to DOM3 Events.

Interactive content is content that
is specifically intended for user interaction.

Certain elements in HTML can be activated, for instance
a elements, button
elements, or input elements when their
type attribute is set to radio .
Activation of those elements can happen in various (UA-defined)
ways, for instance via the mouse or keyboard.

When activation is performed via some method other than clicking
the pointing device, the default action of the event that triggers
the activation must, instead of being activating the element
directly, be to fire a click event on the same element.

The default action of this click event, or of the real click event if the element was activated by
clicking a pointing device, must be to fire a further DOMActivate event at the same
element, whose own default action is to go through all the elements
the DOMActivate event
bubbled through (starting at the target node and going towards the
Document node), looking for an element with an
activation behavior ; the first element,
in reverse tree order, to have one, must have its activation
behavior executed.

The above doesn't happen for arbitrary synthetic
events dispatched by author script. However, the click() method can be used
to make it happen programmatically.

3.3.4 Transparent
content models

Some elements are described as transparent ; they have "transparent" as their
content model. Some elements are described as semi-transparent ; this means that part of
their content model is "transparent" but that is not the only part
of the content model that must be satisfied.

When a content model includes a part that is "transparent",
those parts must not contain content that would not be conformant
if all transparent and semi-transparent elements in the tree were
replaced, in their parent element, by the children in the
"transparent" part of their content model, retaining order.

When a transparent or semi-transparent element has no parent,
then the part of its content model that is "transparent" must
instead be treated as accepting any flow
content .

3.3.5
Paragraphs

A paragraph is typically a block of
text with one or more sentences that discuss a particular topic, as
in typography, but can also be used for more general thematic
grouping. For instance, an address is also a paragraph, as is a
part of a form, a byline, or a stanza in a poem.

Paragraphs in flow content are
defined relative to what the document looks like without the
ins and del elements complicating matters. Let
view be a view of the DOM that replaces all
ins and del elements in the document with their contents.
Then, in view , for each run of phrasing content uninterrupted by other types of
content, in an element that accepts content other than phrasing content , let first
be the first node of the run, and let last be
the last node of the run. For each run, a paragraph exists in the
original DOM from immediately before first to
immediately after last . (Paragraphs can thus
span across ins and del elements.)

The p element can be
used to wrap individual paragraphs when there would otherwise not
be any content other than phrasing content to separate the
paragraphs from each other.

In the following example, there are two paragraphs in a section.
There is also a header, which contains phrasing content that is not
a paragraph. Note how the comments and intra-element
whitespace do not form paragraphs.

<section>
<h1>Example of paragraphs</h1>
This is the <em>first</em> paragraph in this example.
<p>This is the second.</p>
<!-- This is not a paragraph. -->
</section>

The following example takes that markup and puts ins and del
elements around some of the markup to show that the text was
changed (though in this case, the changes don't really make much
sense, admittedly). Notice how this example has exactly the same
paragraphs as the previous one, despite the ins and del
elements.

<section>
<ins><h1>Example of paragraphs</h1>
This is the <em>first</em> paragraph in</ins> this example<del>.
<p>This is the second.</p></del>
<!-- This is not a paragraph. -->
</section>

3.4 Global
attributes

The following attributes are common to and may be specified on
all HTML elements (even those not
defined in this specification):

In HTML, the xmlns attribute
has absolutely no effect. It is basically a talisman. It is allowed
merely to make migration to and from XHTML mildly easier. When
parsed by an HTML parser , the attribute ends
up in no namespace, not the "
http://www.w3.org/2000/xmlns/ " namespace like
namespace declaration attributes in XML do.

In XML, an xmlns attribute is
part of the namespace declaration mechanism, and an element cannot
actually have an xmlns attribute in no
namespace specified.

3.4.1 The id attribute

The id attribute
represents its element's unique identifier. The value must be
unique in the subtree within which the element finds itself and
must contain at least one character. The value must not contain any
space characters .

If the value is not the empty string, user agents must associate
the element with the given value (exactly, including any space
characters) for the purposes of ID matching within the subtree the
element finds itself (e.g. for selectors in CSS or for the
getElementById() method in the DOM).

Identifiers are opaque strings. Particular meanings should not
be derived from the value of the id attribute.

This specification doesn't preclude an element having multiple
IDs, if other mechanisms (e.g. DOM Core methods) can set an
element's ID in a way that doesn't conflict with the id attribute.

3.4.2 The title attribute

The title
attribute represents advisory information for the element, such as
would be appropriate for a tooltip. On a link, this could be the
title or a description of the target resource; on an image, it
could be the image credit or a description of the image; on a
paragraph, it could be a footnote or commentary on the text; on a
citation, it could be further information about the source; and so
forth. The value is text.

If this attribute is omitted from an element, then it implies
that the title
attribute of the nearest ancestor HTML element with a title attribute set is
also relevant to this element. Setting the attribute overrides
this, explicitly stating that the advisory information of any
ancestors is not relevant to this element. Setting the attribute to
the empty string indicates that the element has no advisory
information.

If the title attribute's value contains U+000A LINE
FEED (LF) characters, the content is split into multiple lines.
Each U+000A LINE FEED (LF) character represents a line break.

Some elements, such as link and
abbr , define additional semantics
for the title
attribute beyond the semantics described above.

3.4.3 The lang (HTML only) and
xml:lang
(XML only) attributes

The lang
attribute specifies the primary language
for the element's contents and for any of the element's attributes
that contain text. Its value must be a valid RFC 3066 language
code, or the empty string. [RFC3066]

If these attributes are omitted from an element, then it implies
that the language of this element is the same as the language of
the parent element. Setting the attribute to the empty string
indicates that the primary language is unknown.

To determine the language of a node, user agents must look at
the nearest ancestor element (including the element itself if the
node is an element) that has an xml:lang attribute
set or is an HTML
element and has a lang attribute set. That attribute specifies the
language of the node.

If both the xml:lang attribute and the lang attribute are set on an
element, user agents must use the xml:lang attribute,
and the lang
attribute must be ignored for
the purposes of determining the element's language.

If no explicit language is given for the root element , then language information from a
higher-level protocol (such as HTTP), if any, must be used as the
final fallback language. In the absence of any language
information, the default value is unknown (the empty string).

User agents may use the element's language to determine proper
processing or rendering (e.g. in the selection of appropriate fonts
or pronunciations, or for dictionary selection).

3.4.4 The xml:base
attribute (XML only)

3.4.5 The dir attribute

The dir
attribute specifies the element's text directionality. The
attribute is an enumerated attribute with
the keyword ltr mapping to the state
ltr , and the keyword rtl mapping to
the state rtl . The attribute has no defaults.

If the attribute has the state ltr , the element's
directionality is left-to-right. If the attribute has the state
rtl , the element's directionality is right-to-left.
Otherwise, the element's directionality is the same as its parent
element, or ltr if there is no parent element.

The processing of this attribute depends on the presentation
layer. For example, CSS 2.1 defines a mapping from this attribute
to the CSS 'direction' and 'unicode-bidi' properties, and defines
rendering in terms of those properties.

Assigning classes to an element affects class
matching in selectors in CSS, the getElementsByClassName()
method in the DOM, and other such features.

Authors may use any value in the class attribute, but are
encouraged to use the values that describe the nature of the
content, rather than values that describe the desired presentation
of the content.

The className and classList DOM
attributes must both reflect the
class content
attribute.

3.4.7 The style attribute

All elements may have the style content attribute set. If specified, the
attribute must contain only a list of zero or more
semicolon-separated (;) CSS declarations. [CSS21]

The attribute, if specified, must be parsed and treated as the
body (the part inside the curly brackets) of a declaration block in
a rule whose selector matches just the element on which the
attribute is set. For the purposes of the CSS cascade, the
attribute must be considered to be a 'style' attribute at the
author level.

Documents that use style attributes on any of their elements must
still be comprehensible and usable if those attributes were
removed.

In particular, using the style attribute to hide
and show content, or to convey meaning that is otherwise not
included in the document, is non-conforming.

The style
DOM attribute must return a CSSStyleDeclaration whose
value represents the declarations specified in the attribute, if
present. Mutating the CSSStyleDeclaration object must
create a style attribute on
the element (if there isn't one already) and then change its value
to be a value representing the serialized form of the
CSSStyleDeclaration object. [CSSOM]

In the following example, the words that refer to colors are
marked up using the span element
and the style
attribute to make those words show up in the relevant colors in
visual media.

The dataset DOM attribute provides
convenient accessors for all the data-* attributes on an element. On getting,
the dataset
DOM attribute must return a DOMStringMap object, associated with
the following three algorithms, which expose these attributes on
their element:

The algorithm for getting values from names

Let name be the concatenation of the string
data- and the name passed to the
algorithm.

If the element does not have an attribute with the name
name , then the name has no corresponding
value, abort.

Otherwise, return the value of the attribute with the name
name .

The algorithm for setting names to certain values

Let name be the concatenation of the string
data- and the name passed to the
algorithm.

Let value be the value passed to the
algorithm.

Set the value of the attribute with the name name , to the value value , replacing
any previous value if the attribute already existed. If
setAttribute() would have raised an exception
when setting an attribute with the name name ,
then this must raise the same exception.

The algorithm for deleting names

Let name be the concatenation of the string
data- and the name passed to the
algorithm.

Remove the attribute with the name name ,
if such an attribute exists. Do nothing otherwise.

If a Web page wanted an element to represent a space ship, e.g.
as part of a game, it would have to use the class attribute along with data-* attributes:

The title element represents
the document's title or name. Authors should use titles that
identify their documents even when they are used out of context,
for example in a user's history or bookmarks, or in search results.
The document's title is often different from its first header,
since the first header does not have to stand alone when taken out
of context.

Here are some examples of appropriate titles, contrasted with
the top-level headers that might be used on those same pages.

<title>Introduction to The Mating Rituals of Bees</title>
...
<h1>Introduction</h1>
<p>This companion guide to the highly successful
<cite>Introduction to Medieval Bee-Keeping</cite> book is...

The next page might be a part of the same site. Note how the
title describes the subject matter unambiguously, while the first
header assumes the reader knowns what the context is and therefore
won't wonder if the dances are Salsa or Waltz:

<title>Dances used during bee mating rituals</title>
...
<h1>
The
Dances</h1>

The string to use as the document's title is given by the
document.title DOM attribute. User
agents should use the document's title when referring to the
document in their user interface.

A base element must have either
an href
attribute, a target attribute, or both.

The href content attribute, if
specified, must contain a URI (or IRI).

A base element, if it has an
href
attribute, must come before any other elements in the tree that
have attributes with URIs (except the html element and its manifest
attribute).

User agents must use the value of the href attribute of the first base element that is both a child of the head element and has an
href attribute, if there is such
an element, as the document entity's base URI for the purposes of
section 5.1.1 of RFC 3986 ("Establishing a Base URI": "Base URI
Embedded in Content"). This base URI from RFC 3986 is referred to
by the algorithm given in XML Base, which is a
normative part of this specification . [RFC3986]

If the base URI given by this attribute is a relative URI, it
must be resolved relative to the higher-level base URIs (i.e. the
base URI from the encapsulating entity or the URI used to retrieve
the entity) to obtain an absolute base URI. All xml:base attributes
must be ignored when resolving relative URIs in this href attribute.

If there are multiple base elements with href attributes, all but the first are
ignored.

The link element allows authors
to link their document to other resources.

The destination of the link is given by the href attribute, which
must be present and must contain a URI (or IRI). If the
href
attribute is absent, then the element does not define a link.

The type of link indicated (the relationship) is given by the
value of the rel attribute, which must be
present, and must have a value that is a set of
space-separated tokens . The allowed
values and their meanings are defined in a later section. If
the rel
attribute is absent, or if the value used is not allowed according
to the definitions in this specification, then the element does not
define a link.

Two categories of links can be created using the link element. Links to external resources are
links to resources that are to be used to augment the current
document, and hyperlink
links are links to
other documents . The link types
section defines whether a particular link type is an external
resource or a hyperlink. One element can create multiple links (of
which some might be external resource links and some might be
hyperlinks); exactly which and how many links are created depends
on the keywords given in the rel attribute. User agents must process the links
on a per-link basis, not a per-element basis.

The exact behavior for links to external resources depends on
the exact relationship, as defined for the relevant link type. Some
of the attributes control whether or not the external resource is
to be applied (as defined below). For external resources that are
represented in the DOM (for example, style sheets), the DOM
representation must be made available even if the resource is not
applied. (However, user agents may opt to only fetch such resources
when they are needed, instead of pro-actively downloading all the
external resources that are not applied.)

HTTP semantics must be followed when fetching external
resources. (For example, redirects must be followed and 404
responses must cause the external resource to not be applied.)

Interactive user agents should provide users with a means to
follow the
hyperlinks created using the link element, somewhere within their user
interface. The exact interface is not defined by this
specification, but it should include the following information
(obtained from the element's attributes, again as defined below),
in some form or another (possibly simplified), for each hyperlink
created with each link element in
the document:

The relationship between this document and the resource (given
by the rel
attribute)

User agents may also include other information, such as the type
of the resource (as given by the type attribute).

Hyperlinks created with the link element and its rel attribute apply to
the whole page. This contrasts with the rel attribute of
a and area elements, which indicates the type of a
link whose context is given by the link's location within the
document.

The media attribute says which
media the resource applies to. The value must be a valid media query . [MQ]

If the link is a hyperlink then the media attribute is
purely advisory, and describes for which media the document in
question was designed.

However, if the link is an external resource
link , then the media attribute is prescriptive. The user
agent must apply the external resource to views while
their state match the listed media, and must not apply them
otherwise.

The default, if the media attribute is
omitted, is all , meaning that by default links apply
to all media.

The type attribute gives the MIME
type of the linked resource. It is purely advisory. The value must
be a valid MIME type, optionally with parameters. [RFC2046]

For external
resource links , user agents may use the type given in this
attribute to decide whether or not to consider using the resource
at all. If the UA does not support the given MIME type for the
given link relationship, then the UA may opt not to download and
apply the resource.

User agents must not consider the type attribute
authoritative — upon fetching the resource, user agents must
not use metadata included in the link to the resource to determine
its type.

If the attribute is omitted, but the user agent would fetch the
resource if the type was known and supported, then the user agent
must fetch the resource and determine its type from its Content-Type
metadata to determine if it supports (and can apply) that
external resource. If no type metadata is specified, but the
external resource link type has a default type defined, then the
user agent must assume that the resource is of that type.

...then a compliant UA that supported only CSS style sheets
would fetch the B and C files, and skip the A file (since
text/plain is not the MIME type for CSS style
sheets).

For files B and C, it would then check the actual types returned
by the server. For those that are sent as text/css ,
it would apply the styles, but for those labeled as
text/plain , or any other type, it would not.

If one the two files was returned without a Content-Type metadata, or with a syntactically
incorrect type like Content-Type: "null"
, then the default type for stylesheet links would kick in. Since that
default type is text/css , the style sheet
would nonetheless be applied.

The title attribute gives the
title of the link. With one exception, it is purely advisory. The
value is text. The exception is for style sheet links, where the
title
attribute defines alternative style sheet
sets .

The title attribute on link elements differs from the global
title
attribute of most other elements in that a link without a title
does not inherit the title of the parent element: it merely has no
title.

The sizes attribute is used with the icon link type. The
attribute must not be specified on link elements that do not have a rel attribute that
specifies the icon keyword.

Some versions of HTTP defined a Link:
header, to be processed like a series of link elements. If supported, for the purposes of
ordering links defined by HTTP headers must be assumed to come
before any links in the document, in the order that they were given
in the HTTP entity header. Relative URIs in these headers are
resolved according to the rules given in HTTP, not relative to base
URIs set by the document (e.g. using a base element or xml:base attributes).
[RFC2616][RFC2068]

The DOM attributes href , rel , media , hreflang , and
type , and
sizes
each must reflect the respective content
attributes of the same name.

The DOM attribute disabled only applies to
style sheet links. When the link
element defines a style sheet link, then the disabled
attribute behaves as defined for the alternative style sheets DOM .
For all other link elements it
always return false and does nothing on setting.

The meta element can represent
document-level metadata with the name attribute, pragma
directives with the http-equiv attribute, and the file's
character encoding declaration when an
HTML document is serialized to string form (e.g. for transmission
over the network or for disk storage) with the charset
attribute.

The content attribute gives the
value of the document metadata or pragma directive when the element
is used for those purposes. The allowed values depend on the exact
context, as described in subsequent sections of this
specification.

If a meta element has a
name
attribute, it sets document metadata. Document metadata is
expressed in terms of name/value pairs, the name attribute on the
meta element giving the name, and
the content attribute on the same element giving
the value. The name specifies what aspect of metadata is being set;
valid names and the meaning of their values are described in the
following sections. If a meta
element has no content attribute, then the value part of
the metadata name/value pair is the empty string.

If a meta element has the
http-equiv attribute specified, it must
be either in a head element or in
a noscript element that itself
is in a head element. If a
meta element does not have the
http-equiv attribute specified, it must
be in a head element.

The DOM attributes name and content must reflect the respective content attributes of the
same name. The DOM attribute httpEquiv must reflect the content attribute http-equiv
.

3.6.5.1. Standard
metadata names

This specification defines a few names for the name attribute of the
meta element.

application-name

The value must be a short free-form string that giving the name
of the Web application that the page represents. If the page is not
a Web application, the application-name metadata name must
not be used. User agents may use the application name in UI in
preference to the page's title ,
since the title might include status messages and the like relevant
to the status of the page at a particular moment in time instead of
just being the name of the application.

description

The value must be a free-form string that describes the page.
The value must be appropriate for use in a directory of pages, e.g.
in a search engine.

generator

The value must be a free-form string that identifies the
software used to generate the document. This value must not be used
on hand-authored pages.

3.6.5.2. Other metadata
names

Anyone is free to edit the WHATWG Wiki MetaExtensions page at
any time to add a type. These new names must be specified with the
following information:

Keyword

The actual name being defined. The name should not be
confusingly similar to any other defined name (e.g. differing only
in case).

Brief description

A short description of what the metadata name's meaning is,
including the format the value is required to be in.

Link to more details

A link to a more detailed description of the metadata name's
semantics and requirements. It could be another page on the Wiki,
or a link to an external page.

Synonyms

A list of other names that have exactly the same processing
requirements. Authors should not use the names defined to be
synonyms, they are only intended to allow user agents to support
legacy content.

Status

One of the following:

Proposal

The name has not received wide peer review and approval.
Someone has proposed it and is using it.

Accepted

The name has received wide peer review and approval. It has a
specification that unambiguously defines how to handle pages that
use the name, including when they use it in incorrect ways.

Unendorsed

The metadata name has received wide peer review and it has been
found wanting. Existing pages are using this keyword, but new pages
should avoid it. The "brief description" and "link to more details"
entries will give details of what authors should use instead, if
anything.

If a metadata name is added with the "proposal" status and found
to be redundant with existing values, it should be removed and
listed as a synonym for the existing value.

Conformance checkers must use the information given on the
WHATWG Wiki MetaExtensions page to establish if a value not
explicitly defined in this specification is allowed or not. When an
author uses a new type not defined by either this specification or
the Wiki page, conformance checkers should offer to add the value
to the Wiki, with the details described above, with the "proposal"
status.

This specification does not define how new values will get
approved. It is expected that the Wiki will have a community that
addresses this.

Metadata names whose values are to be URIs must not be proposed
or accepted. Links must be represented using the link element, not the meta element.

3.6.5.3. Pragma
directives

When the http-equiv attribute is
specified on a meta element, the
element is a pragma directive.

The http-equiv attribute is
an enumerated attribute . The following
table lists the keywords defined for this attribute. The states
given in the first cell of the rows with keywords give the states
to which those keywords map.

When a meta element is
inserted into the document, if its http-equiv
attribute is present and represents one of the above states, then
the user agent must run the algorithm appropriate for that state,
as described in the following list:

If the document contains a meta element in the Encoding declaration state
then that element must be the first element in the document's
head element, and the document
must not contain a meta element
with the charset attribute present.

If another meta element in the
Refresh
state has already been successfully processed (i.e. when it was
inserted the user agent processed it and reached the last step of
this list of steps), then abort these steps.

If the meta element has no
content attribute, or if that attribute's
value is the empty string, then abort these steps.

Resolve the url value to an absolute URI
using the base
URI of the meta element.

Perform one or more of the following steps:

Set a timer so that in time seconds,
adjusted to take into account user or user agent preferences, if
the user has not canceled the redirect, the user agent navigates the document's browsing
context to url , with replacement enabled , and with the document's
browsing context as the source browsing
context .

a valid non-negative integer , followed by
a U+003B SEMICOLON ( ; ), followed by one or
more space characters
, followed by either a U+0055 LATIN CAPITAL LETTER U or a U+0075
LATIN SMALL LETTER U, a U+0052 LATIN CAPITAL LETTER R or a U+0072
LATIN SMALL LETTER R, a U+004C LATIN CAPITAL LETTER L or a U+006C
LATIN SMALL LETTER L, a U+003D EQUALS SIGN ( = ), and then a valid URI (or IRI).

In the former case, the integer represents a number of seconds
before the page is to be reloaded; in the latter case the integer
represents a number of seconds before the page is to be replaced by
the page at the given URI.

There must not be more than one meta element with any particular state in the
document at a time.

3.6.5.4. Specifying the
document's character encoding

A character encoding declaration is a
mechanism by which the character encoding used to store or transmit
a document is specified.

The following restrictions apply to character encoding
declarations:

The character encoding name given must be the name of the
character encoding used to serialize the file.

The value must be a valid character encoding name, and must be
the preferred name for that encoding. [IANACHARSET]

The character encoding declaration must be serialized without
the use of character
references or character escapes of any kind.

An ASCII-compatible character
encoding is one that is a superset of US-ASCII (specifically,
ANSI_X3.4-1968) for bytes in the set 0x09, 0x0A, 0x0C, 0x0D, 0x20 -
0x22, 0x26, 0x27, 0x2C - 0x3F, 0x41 - 0x5A, and 0x61 - 0x7A .

Authors should not use JIS_X0212-1990, x-JIS0208, and encodings
based on EBCDIC. Authors should not use UTF-32. Authors must not
use the CESU-8, UTF-7, BOCU-1 and SCSU encodings. [CESU8][UTF7][BOCU1][SCSU]

Authors are encouraged to use UTF-8. Conformance checkers may
advise against authors using legacy encodings.

In XHTML, the XML declaration should be used for inline
character encoding information, if necessary.

If the type attribute is given, it
must contain a valid MIME type, optionally with parameters, that
designates a styling language. [RFC2046]
If the attribute is absent, the type defaults to
text/css . [RFC2138]

When examining types to determine if they support the language,
user agents must not ignore unknown MIME parameters — types
with unknown parameters must be assumed to be unsupported.

The media attribute says which
media the styles apply to. The value must be a valid media query . [MQ] User agents
must apply the styles to views while their state match
the listed media, and must not apply them otherwise. [DOM3VIEWS]

The default, if the media attribute is
omitted, is all , meaning that by default styles apply
to all media.

The scoped attribute is a
boolean attribute . If the attribute is
present, then the user agent must apply the specified style
information only to the style
element's parent element (if any), and that element's child nodes.
Otherwise, the specified styles must, if applied, be applied to the
entire document.

The title attribute on style elements, like the title attribute on
link elements, differs from the
global title
attribute in that a style block
without a title does not inherit the title of the parent element:
it merely has no title.

All descendant elements must be processed, according to their
semantics, before the style
element itself is evaluated. For styling languages that consist of
pure text, user agents must evaluate style elements by passing the concatenation of
the contents of all the text
nodes that are direct children of the style element (not any other nodes such as
comments or elements), in tree order , to
the style system. For XML-based styling languages, user agents must
pass all the children nodes of the style element to the style system.

This specification does not specify a style system,
but CSS is expected to be supported by most Web browsers. [CSS21]

The media , type and scoped DOM attributes
must reflect the respective content
attributes of the same name.

3.6.7Styling

The link and style elements can provide styling information
for the user agent to use when rendering the document. The DOM
Styling specification specifies what styling information is to be
used by the user agent and how it is to be used. [CSSOM]

For style elements, if the
user agent does not support the specified styling language, then
the sheet attribute of the
element's LinkStyle interface must return null.
Similarly, link elements that do
not represent external
resource links that contribute to the styling processing model
(i.e. that do not have a stylesheet keyword in their rel attribute), and
link elements whose specified
resource has not yet been downloaded, or is not in a supported
styling language, must have their LinkStyle
interface's sheet
attribute return null.

Otherwise, the LinkStyle interface's sheet attribute must return a
StyleSheet object with the attributes implemented as
follows: [CSSOM]

The media must be the same as the value of the element's
media content attribute.

The style sheet title ( title DOM attribute)

The title must be the same as the value of the element's
title content attribute. If the attribute is
absent, then the style sheet does not have a title. The title is
used for defining alternative style sheet
sets .

The disabled DOM attribute
on link and style elements must return false and do
nothing on setting, if the sheet attribute of their
LinkStyle interface is null. Otherwise, it must return
the value of the StyleSheet interface's disabled attribute on getting, and
forward the new value to that same attribute on setting.

In conforming documents, there is only one body element. The document.body DOM
attribute provides scripts with easy access to a document's
body element.

Some DOM operations (for example, parts of the
drag and drop model) are defined in terms
of " the body element ". This refers to a
particular element in the DOM, as per the definition of the term,
and not any arbitrary body
element.

The section element
represents a generic document or application section. A section, in
this context, is a thematic grouping of content, typically with a
header, possibly with a footer.

Examples of sections would be chapters, the
various tabbed pages in a tabbed dialog box, or the numbered
sections of a thesis. A Web site's home page could be split into
sections for an introduction, news items, contact information.

The nav element represents a
section of a page that links to other pages or to parts within the
page: a section with navigation links. Not all groups of links on a
page need to be in a nav element
— only sections that consist of primary navigation blocks are
appropriate for the nav element. In
particular, it is common for footers to have a list of links to
various key parts of a site, but the footer element is more appropriate in such
cases.

In the following example, the page has several places where
links are present, but only one of those places is considered a
navigation section.

The article element
represents a section of a page that consists of a composition that
forms an independent part of a document, page, or site. This could
be a forum post, a magazine or newspaper article, a Web log entry,
a user-submitted comment, or any other independent item of
content.

An article
element is "independent" in that its contents could stand alone,
for example in syndication. However, the element is still
associated with its ancestors; for instance, contact information
that applies to a parent
body element still covers the
article as well.

When article elements are
nested, the inner article
elements represent articles that are in principle related to the
contents of the outer article. For instance, a Web log entry on a
site that accepts user-submitted comments could represent the
comments as article elements
nested within the article
element for the Web log entry.

Author information associated with an article element (q.v. the address element) does not apply to nested
article elements.

The aside element represents a
section of a page that consists of content that is tangentially
related to the content around the aside element, and which could be considered
separate from that content. Such sections are often represented as
sidebars in printed typography.

The following example shows how an aside is used to mark up
background material on Switzerland in a much longer news story on
Europe.

<aside>
<h1>Switzerland</h1>
<p>Switzerland, a land-locked country in the middle of geographic
Europe, has not joined the geopolitical European Union, though it is
a signatory to a number of European treaties.</p>
</aside>

The following example shows how an aside is used to mark up a
pull quote in a longer article.

...
<p>He later joined a large company, continuing on the same work.
<q>I love my job. People ask me what I do for fun when I'm not at
work. But I'm paid to do my hobby, so I never know what to
answer. Some people wonder what they would do if they didn't have to
work... but I know what I would do, because I was unemployed for a
year, and I filled that time doing exactly what I do
now.</q></p>
<aside>
<q> People ask me what I do for fun when I'm not at work. But I'm
paid to do my hobby, so I never know what to answer. </q>
</aside>
<p>Of course his work — or should that be hobby? —
isn't his only passion. He also enjoys other pleasures.</p>
...

The header element represents
the header of a section. The element is typically used to group a
set of h1 – h6 elements to mark up a page's title with its
subtitle or tagline. However, header elements may contain more than just the
section's headings and subheadings — for example it would be
reasonable for the header to include version history
information.

For the purposes of document summaries, outlines, and the like,
header elements are equivalent
to the highest rankedh1 – h6 element descendant of the header element (the first such element if
there are multiple elements with that rank
).

Other heading elements in the header element indicate subheadings or
subtitles.

The rank of a header element is the same as for an
h1 element (the highest rank).

The footer element represents
the footer for the section it applies
to. A footer typically contains information about its section such
as who wrote it, links to related documents, copyright data, and
the like.

Contact information for the section given in a footer should be marked up using the
address element.

Footers don't necessarily have to appear at the end of a
section, though they usually do.

Here is a page with two footers, one at the top and one at the
bottom, with the same content:

The address element must not
be used to represent arbitrary addresses (e.g. postal addresses),
unless those addresses are contact information for the section.
(The p element is the appropriate
element for marking up such addresses.)

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

For example, the following is non-conforming use of the
address element:

<ADDRESS>
Last
Modified:
1999/12/24
23:37:50</ADDRESS>

Typically, the address
element would be included with other information in a
footer element.

To determine the contact information for a sectioning content element (such as a document's
body element, which would give
the contact information for the page), UAs must collect all the
address elements that apply to that sectioning content element and its ancestor
sectioning content elements. The contact
information is the collection of all the information given by those
elements.

Contact information for one sectioning content element, e.g. an
aside element, does not apply to
its ancestor elements, e.g. the page's body .

3.7.10Headings and sections

The first element of heading content in
an element of sectioning content gives
the header for that section. Subsequent headers of equal or higher
rank start new (implied) sections, headers of
lower rank start subsections that are part of
the previous one.

Sectioning content elements are
always considered subsections of their nearest ancestor element of
sectioning content , regardless of what
implied sections other headings may have created.

Certain elements are said to be sectioning roots , including blockquote and td elements. These elements can have their own
outlines, but the sections and headers inside these elements do not
contribute to the outlines of their ancestors.

Notice how the section ends
the earlier implicit section so that a later paragraph ("Grunt") is
back at the top level.

Sections may contain headers of any rank ,
but authors are strongly encouraged to either use only
h1 elements, or to use elements of
the appropriate rank for the section's nesting
level.

Authors are also encouraged to explicitly wrap sections in
elements of sectioning content , instead
of relying on the implicit sections generated by having multiple
heading in one element of sectioning
content .

Both of the documents above are semantically identical and would
produce the same outline in compliant user agents.

3.7.10.1. Creating an
outline

This section defines an algorithm for creating an outline for a sectioning
content element or a sectioning root
element. It is defined in terms of a walk over the nodes of a DOM
tree, in tree order, with each node being visited when it is
entered and when it is exited during the walk.

The outline for a sectioning content
element or a sectioning root element
consists of a list of one or more potentially nested sections. Each
section can have one heading associated with it. The algorithm for
the outline also associates each node in the DOM tree with a
particular section and potentially a heading. (The sections in the
outline aren't section
elements, though some may correspond to such elements — they
are merely conceptual sections.)

The algorithm that must be followed during a walk of a DOM
subtree rooted at a sectioning content
element or a sectioning root element to
determine that element's outline is as follows:

Let current outlinee be null. (It holds the
element whose outline is being created.)

Let current section be null. (It holds a
pointer to a section, so that elements in the DOM can all be
associated with a section.)

Create a stack to hold elements, which is used to handle
nesting. Initialize this stack to empty.

As you walk over the DOM in tree order
, trigger the first relevant step below for each element as you
enter and exit it.

If the top of the stack is an element, and you are exiting that
element

If the current section has no heading, let
the element being entered be the heading for the current section .

Otherwise, if the element being entered has a rank equal to or
greater than the heading of the current section
, then create a new section and append it to the outline of the
current outlinee element, so that this new
section is the new last section of that outline. Let current section be that new section. Let the element being
entered be the new heading for the current
section .

Otherwise, run these substeps:

Let candidate section be current section .

If the element being entered has a rank lower than the rank of
the heading of the candidate section , then
create a new section, and append it to candidate
section . (This does not change which section is the last
section in the outline.) Let current section be
this new section. Let the element being entered be the new heading
for the current section . Abort these
substeps.

Let candidate section be the section that
contains the previous candidate section in the
outline of current outlinee .

Return to step 2.

Push the element being entered onto the stack. (This causes the
algorithm to skip any descendants of the element.)

Otherwise

Do nothing.

In addition, whenever you exit a node,
after doing the steps above, if current section
is not null, associate the node with the section current section .

Associate any nodes that were not associated a section in the
steps above with current outlinee as their
section.

Associate all nodes with the heading of the section with which
they are associated, if any.

If current outlinee is the body element , then the outline
created for that element is the outline of the entire document.

The tree of sections created by the algorithm above, or a proper
subset thereof, must be used when generating document outlines, for
example when generating tables of contents.

When creating an interactive table of contents, entries should
jump the user to the relevant sectioning
content element, if the section was created for a real element
in the original document, or to the relevant heading content element, if the section in the tree
was generated for a heading in the above process.

Selecting the first section of the document
therefore always takes the user to the top of the document,
regardless of where the first header in the body is to be found.

The following JavaScript function shows how the tree walk could
be implemented. The root argument is the root
of the tree to walk, and the enter and
exit arguments are callbacks that are called
with the nodes as they are entered and exited. [ECMA262]

3.7.10.2.
Distinguishing site-wide headings from page headings

Given the outline of a document, but
ignoring any sections created for nav and aside
elements, and any of their descendants, if the only root of the
tree is the body element 's
section, and it has only a single subsection which is created by an
article element, then the
heading of the body element
should be assumed to be a site-wide heading, and the heading of the
article element should be
assumed to be the page's heading.

If a page starts with a heading that is common to the whole
site, the document must be authored such that, in the document's
outline , ignoring any sections created for
nav and aside elements and any of their descendants,
the tree has only one root section, the
body element 's section, its heading is the
site-wide heading, the body
element has just one subsection, that subsection is created by
an article element, and that
article 's heading is the page
heading.

If a page does not contain a site-wide heading, then the page
must be authored such that, in the document's outline , ignoring any sections created for
nav and aside elements and any of their descendants,
either the body element has
no subsections, or it has more than one subsection, or it has a
single subsection but that subsection is not created by an
article element, or there is
more than one section at the root of the outline.

Conceptually, a site is thus a document with many
articles — when those articles are split into many pages, the
heading of the original single page becomes the heading of the
site, repeated on every page.

Including an e-mail, with paragraphs indicated by blank lines,
lists indicated by lines prefixed with a bullet, and so on.

Including fragments of computer code, with structure indicated
according to the conventions of that language.

Displaying ASCII art.

To represent a block of computer code, the pre element can be used with a code element; to represent a block of computer
output the pre element can be used
with a samp element. Similarly,
the kbd element can be used within
a pre element to indicate text that
the user is to enter.

In the following snippet, samp
and kbd elements are mixed in the
contents of a pre element to show a
session of Zork I.

<pre><samp>You are in an open field west of a big white house with a boarded
front door.
There is a small mailbox here.
></samp> <kbd>open mailbox</kbd>
<samp>Opening the mailbox reveals:
A leaflet.
>
</samp>
</pre>

The following shows a contemporary poem that uses the
pre element to preserve its unusual
formatting, which forms an intrinsic part of the poem itself.

<pre> maxling
it is with a heart
heavy
that i admit loss of a feline
so loved
a friend lost to the
unknown
(night)
~cdr
11dec07</pre>

Text in a dt element
in a dialog element is
implicitly the source of the text given in the following
dd element, and the contents of the
dd element are implicitly a quote
from that speaker. There is thus no need to include cite , q , or
blockquote elements in this
markup. Indeed, a q element inside a
dd element in a conversation would
actually imply the people talking were themselves quoting another
work. See the cite ,
q , and blockquote elements for other ways to cite
or quote.

The ol element represents a list
of items, where the items have been intentionally ordered, such
that changing the order would change the meaning of the
document.

The items of the list are the li
element child nodes of the ol
element, in tree order .

The reversed attribute is a
boolean attribute . If present, it
indicates that the list is a descending list (..., 3, 2, 1). If the
attribute is omitted, the list is an ascending list (1, 2, 3,
...).

The start attribute, if present,
must be a valid integer giving the ordinal
value of the first list item.

If the start attribute is present, user agents must
parse it as an
integer , in order to determine the attribute's value. The
default value, used if the attribute is missing or if the value
cannot be converted to a number according to the referenced
algorithm, is 1 if the element has no reversed
attribute, and is the number of child li elements otherwise.

The first item in the list has the ordinal value given by the
ol element's start attribute,
unless that li element has a
value
attribute with a value that can be successfully parsed, in which
case it has the ordinal value given by that value attribute.

Each subsequent item in the list has the ordinal value given by
its value
attribute, if it has one, or, if it doesn't, the ordinal value of
the previous item, plus one if the reversed is
absent, or minus one if it is present.

The reversed DOM attribute must
reflect the value of the reversed content
attribute.

The start DOM attribute must reflect the value of the start content
attribute.

The following markup shows a list where the order matters, and
where the ol element is therefore
appropriate. Compare this list to the equivalent list in the
ul section to see an example of the
same items using the ul element.

<p>I have lived in the following countries (given in the order of when
I first lived there):</p>
<ol>
<li>Switzerland
<li>United Kingdom
<li>United States
<li>Norway
</ol>

Note how changing the order of the list changes the meaning of
the document. In the following example, changing the relative order
of the first two items has changed the birthplace of the
author:

<p>I have lived in the following countries (given in the order of when
I first lived there):</p>
<ol>
<li>United Kingdom
<li>Switzerland
<li>United States
<li>Norway
</ol>

The ul element represents a list
of items, where the order of the items is not important —
that is, where changing the order would not materially change the
meaning of the document.

The items of the list are the li
element child nodes of the ul
element.

The following markup shows a list where the order does not
matter, and where the ul element is
therefore appropriate. Compare this list to the equivalent list in
the ol section to see an example of
the same items using the ol
element.

<p>I have lived in the following countries:</p>
<ul>
<li>Norway
<li>Switzerland
<li>United Kingdom
<li>United States
</ul>

Note that changing the order of the list does not change the
meaning of the document. The items in the snippet above are given
in alphabetical order, but in the snippet below they are given in
order of the size of their current account balance in 2007, without
changing the meaning of the document whatsoever:

<p>I have lived in the following countries:</p>
<ul>
<li>Switzerland
<li>Norway
<li>United Kingdom
<li>United States
</ul>

The li element represents a list
item. If its parent element is an ol
, ul , or menu element, then the element is an item of the
parent element's list, as defined for those elements. Otherwise,
the list item has no defined list-related relationship to any other
li element.

The value attribute, if present,
must be a valid integer giving the ordinal
value of the list item.

If the value attribute is present, user agents must
parse it as an
integer , in order to determine the attribute's value. If the
attribute's value cannot be converted to a number, the attribute
must be treated as if it was absent. The attribute has no default
value.

The value attribute is processed relative to the
element's parent ol element (q.v.),
if there is one. If there is not, the attribute has no effect.

The value DOM attribute must reflect the value of the value content
attribute.

The following example, the top ten movies are listed (in reverse
order). Note the way the list is given a title by using a
figure element and its
legend .

The dl element introduces an
association list consisting of zero or more name-value groups (a
description list). Each group must consist of one or more names (
dt elements) followed by one or more
values ( dd elements).

Name-value groups may be terms and definitions, metadata topics
and values, or any other groups of name-value data.

The values within a group are alternatives; multiple paragraphs
forming part of the same value must all be given within the same
dd element.

The order of the list of groups, and of the names and values
within each group, may be significant.

If a dl element contains only
dt elements, then it consists of one
group with names but no values.

If a dl element contains only
dd elements, then it consists of one
group with values but no names.

If a dl element starts with one
or more dd elements, then the first
group has no associated name.

If a dl element ends with one or
more dt elements, then the last
group has no associated value.

When a dl element
doesn't match its content model, it is often due to accidentally
using dd elements in the place of
dt elements and vice versa.
Conformance checkers can spot such mistakes and might be able to
advise authors how to correctly use the markup.

In the following example, one entry ("Authors") is linked to two
values ("John" and "Luke").

<dl>
<dt> Authors
<dd> John
<dd> Luke
<dt> Editor
<dd> Frank
</dl>

In the following example, one definition is linked to two
terms.

<dl>
<dt lang="en-US"> <dfn>color</dfn> </dt>
<dt lang="en-GB"> <dfn>colour</dfn> </dt>
<dd> A sensation which (in humans) derives from the ability of
the fine structure of the eye to distinguish three differently
filtered analyses of a view. </dd>
</dl>

The following example illustrates the use of the dl element to mark up metadata of sorts. At the
end of the example, one group has two metadata labels ("Authors"
and "Editors") and two values ("Robert Rothman" and "Daniel
Jackson").

The following example shows the dl element used to give a set of instructions. The
order of the instructions here is important (in the other examples,
the order of the blocks was not important).

<p>Determine the victory points as follows (use the
first matching case):</p>
<dl>
<dt> If you have exactly five gold coins </dt>
<dd> You get five victory points </dd>
<dt> If you have one or more gold coins, and you have one or more silver coins </dt>
<dd> You get two victory points </dd>
<dt> If you have one or more silver coins </dt>
<dd> You get one victory point </dd>
<dt> Otherwise </dt>
<dd> You get no victory points </dd>
</dl>

The following snippet shows a dl
element being used as a glossary. Note the use of dfn to indicate the word being defined.

The dt element represents the
term, or name, part of a term-description group in a description
list ( dl element), and the talker,
or speaker, part of a talker-discourse pair in a conversation (
dialog element).

The dt element
itself, when used in a dl element,
does not indicate that its contents are a term being defined, but
this can be indicated using the dfn
element.

If the dt element is the child of
a dialog element, and it further
contains a time element, then that
time element represents a
timestamp for when the associated discourse ( dd element) was said, and is not part of the name
of the talker.

The following extract shows how an IM conversation log could be
marked up.

<dialog>
<dt> <time>14:22</time> egof
<dd> I'm not that nerdy, I've only seen 30% of the star trek episodes
<dt> <time>14:23</time> kaj
<dd> if you know what percentage of the star trek episodes you have seen, you are inarguably nerdy
<dt> <time>14:23</time> egof
<dd> it's unarguably
<dt> <time>14:24</time> kaj
<dd> you are not helping your case
</dialog>

The dd element represents the
description, definition, or value, part of a term-description group
in a description list ( dl element),
and the discourse, or quote, part in a conversation (
dialog element).

Interactive user agents should allow users to follow hyperlinks
created using the a element. The
href
, target and ping attributes
decide how the link is followed. The rel , media ,
hreflang , and type attributes
may be used to indicate to the user the likely nature of the target
resource before the user follows the link.

If the DOMActivate event
in question is not trusted (i.e. a click() method call was
the reason for the event being dispatched), and the a element's target
attribute is ... then raise an
INVALID_ACCESS_ERR exception and abort these
steps.

If the target of the DOMActivate event is an img element with an ismap attribute
specified, then server-side image map processing must be performed,
as follows:

If the DOMActivate event
was dispatched as the result of a real pointing-device-triggered
click event on the img element, then let x be
the distance in CSS pixels from the left edge of the image to the
location of the click, and let y be the
distance in CSS pixels from the top edge of the image to the
location of the click. Otherwise, let x and
y be zero.

Let the hyperlink suffix
be a U+003F QUESTION MARK character, the value of x expressed as a base-ten integer using ASCII digits
(U+0030 DIGIT ZERO to U+0039 DIGIT NINE), a U+002C COMMA character,
and the value of y expressed as a base-ten
integer using ASCII digits.

One way that a user agent can enable users to
follow hyperlinks is by allowing a
elements to be clicked, or focussed and activated by the keyboard.
This will cause the
aforementioned activation behavior to be
invoked.

Quotation punctuation (such as quotation marks), if any, must be
placed inside the q element.

Content inside a q element must be
quoted from another source, whose URI, if it has one, should be
cited in the cite attribute.

If the cite attribute is present, it must be a URI (or
IRI). User agents should allow users to follow such citation
links.

If a q element is contained
(directly or indirectly) in a paragraph
that contains a single cite
element and has no other q element
descendants, then, the title of the work given by that
cite element gives the source of
the quotation contained in the q
element.

<p>The man said <q>"Things that are impossible just take
longer"</q>.
I
disagreed
with
him.</p>

Here is an example with both an explicit citation link in the
q element, and an explicit citation
outside:

<p>The W3C page <cite>About W3C</cite> says the W3C's
mission is <q cite="http://www.w3.org/Consortium/">"To lead the
World Wide Web to its full potential by developing protocols and
guidelines that ensure long-term growth for the Web"</q>. I
disagree
with
this
mission.</p>

In the following example, the quotation itself contains a
quotation:

<p>In <cite>Example One</cite>, he writes <q>"The man
said <q>'Things that are impossible just take longer'</q>. I
disagreed
with
him"</q>.
Well,
I
disagree
even
more!</p>

The cite element represents
the title of a work (e.g. a book, a paper, an essay, a poem, a
score, a song, a script, a film, a TV show, a game, a sculpture, a
painting, a theatre production, a play, an opera, a musical, an
exhibition, etc). This can be a work that is being quoted or
referenced in detail (i.e. a citation), or it can just be a work
that is mentioned in passing.

A person's name is not the title of a work — even if
people call that person a piece of work — and the element
must therefore not be used to mark up people's names. (In some
cases, the b element might be
appropriate for names; e.g. in a gossip article where the names of
famous people are keywords rendered with a different style to draw
attention to them. In other cases, if an element is really
needed, the span element can be
used.)

A ship is similarly not a work, and the element must not be used
to mark up ship names (the i element
can be used for that purpose).

<p>According to the Wikipedia article <cite>HTML</cite>, as it
stood in mid-February 2008, leaving attribute values unquoted is
unsafe.
This
is
obviously
an
over-simplification.</p>

The following, however, is incorrect usage, as the
cite element here is containing
far more than the title of the work:

<!-- do not copy this example, it is an example of bad usage! -->
<p>According to <cite>the Wikipedia article on HTML</cite>, as it
stood in mid-February 2008, leaving attribute values unquoted is
unsafe.
This
is
obviously
an
over-simplification.</p>

The cite element is obviously
a key part of any citation in a bibliography, but it is only used
to mark the title:

<p><cite>Universal Declaration of Human Rights</cite>, United Nations,
December
1948.
Adopted
by
General
Assembly
resolution
217
A
(III).</p>

The level of emphasis that a particular piece of content has is
given by its number of ancestor em
elements.

The placement of emphasis changes the meaning of the sentence.
The element thus forms an integral part of the content. The precise
way in which emphasis is used in this way depends on the
language.

These examples show how changing the emphasis changes the
meaning. First, a general statement of fact, with no emphasis:

<p>
Cats
are
cute
animals.</p>

By emphasizing the first word, the statement implies that the
kind of animal under discussion is in question (maybe someone is
asserting that dogs are cute):

<p>
<em>
Cats</em>
are
cute
animals.</p>

Moving the emphasis to the verb, one highlights that the truth
of the entire sentence is in question (maybe someone is saying cats
are not cute):

<p>
Cats
<em>
are</em>
cute
animals.</p>

By moving it to the adjective, the exact nature of the cats is
reasserted (maybe someone suggested cats were mean
animals):

<p>
Cats
are
<em>
cute</em>
animals.</p>

Similarly, if someone asserted that cats were vegetables,
someone correcting this might emphasize the last word:

<p>
Cats
are
cute
<em>
animals</em>.</p>

By emphasizing the entire sentence, it becomes clear that the
speaker is fighting hard to get the point across. This kind of
emphasis also typically affects the punctuation, hence the
exclamation mark here.

<p>
<em>
Cats
are
cute
animals!</em>
</p>

Anger mixed with emphasizing the cuteness could lead to markup
such as:

The relative level of importance of a piece of content is given
by its number of ancestor strong
elements; each strong element
increases the importance of its contents.

Changing the importance of a piece of text with the
strong element does not change
the meaning of the sentence.

Here is an example of a warning notice in a game, with the
various parts marked up according to how important they are:

<p><strong>Warning.</strong> This dungeon is dangerous.
<strong>Avoid the ducks.</strong> Take any gold you find.
<strong><strong>Do not take any of the diamonds</strong>,
they are explosive and <strong>will destroy anything within
ten
meters.</strong>
</strong>
You
have
been
warned.</p>

<p>Example Corp today announced record profits for the
second quarter <small>(Full Disclosure: Foo News is a subsidiary of
Example Corp)</small>, leading to speculation about a third quarter
merger
with
Demo
Group.</p>

In this last example, the small element is marked as being
important small print.

<p>
<strong>
<small>
Continued
use
of
this
service
will
result
in
a
kiss.</small>
</strong>
</p>

The mark element represents a
run of text in one document marked or highlighted for reference
purposes, due to its relevance in another context. When used in a
quotation or other block of text referred to from the prose, it
indicates a highlight that was not originally present but which has
been added to bring the reader's attention to a part of the text
that might not have been considered important by the original
author when the block was originally written, but which is now
under previously unexpected scrutiny. When used in the main prose
of a document, it indicates a part of the document that has been
highlighted due to its likely relevance to the user's current
activity.

The rendering section will eventually suggest
that user agents provide a way to let users jump between
mark elements. Suggested rendering
is a neon yellow background highlight, though UAs maybe should
allow this to be toggled.

This example shows how the mark
example can be used to bring attention to a particular part of a
quotation:

<p lang="en-US">Consider the following quote:</p>
<blockquote lang="en-GB">
<p>Look around and you will find, no-one's really
<mark>colour</mark> blind.</p>
</blockquote>
<p lang="en-US">As we can tell from the <em>spelling</em> of the word,
the
person
writing
this
quote
is
clearly
not
American.</p>

Another example of the mark
element is highlighting parts of a document that are matching some
search string. If someone looked at a document, and the server knew
that the user was searching for the word "kitten", then the server
might return the document with one paragraph modified as
follows:

<p>I also have some <mark>kitten</mark>s who are visiting me
these days. They're really cute. I think they like my garden! Maybe I
should
adopt
a
<mark>
kitten</mark>.</p>

In the following snippet, a paragraph of text refers to a
specific part of a code fragment.

This is another example showing the use of mark to highlight a part of quoted text that was
originally not emphasised. In this example, common typographic
conventions have led the author to explicitly style mark elements in quotes to render in
italics.

Note, incidentally, the distinction between the em element in this example, which is part of the
original text being quoted, and the mark element, which is highlighting a part for
comment.

The following example shows the difference between denoting the
importance of a span of text ( strong ) as opposed to denoting the
relevance of a span of text ( mark ). It is an extract from a textbook, where
the extract has had the parts relevant to the exam highlighted. The
safety warnings, important though they may be, are apparently not
relevant to the exam.

<h3>Wormhole Physics Introduction</h3>
<p><mark>A wormhole in normal conditions can be held open for a
maximum of just under 39 minutes.</mark> Conditions that can increase
the time include a powerful energy source coupled to one or both of
the gates connecting the wormhole, and a large gravity well (such as a
black hole).</p>
<p><mark>Momentum is preserved across the wormhole. Electromagnetic
radiation can travel in both directions through a wormhole,
but matter cannot.</mark></p>
<p>When a wormhole is created, a vortex normally forms.
<strong>Warning: The vortex caused by the wormhole opening will
annihilate anything in its path.</strong> Vortexes can be avoided when
using sufficiently advanced dialing technology.</p>
<p><mark>An obstruction in a gate will prevent it from accepting a
wormhole
connection.</mark>
</p>

Defining term : If the dfn element has a title attribute, then the exact
value of that attribute is the term being defined. Otherwise, if it
contains exactly one element child node and no child text nodes , and that child
element is an abbr element with a
title
attribute, then the exact value of that attribute is the
term being defined. Otherwise, it is the exact textContent of the dfn element that gives the term being
defined.

If the title attribute of the dfn element is present, then it must contain only
the term being defined.

The title attribute of ancestor elements does not
affect dfn elements.

An a element that links to a
dfn element represents an instance
of the term defined by the dfn
element.

In the following fragment, the term "GDO" is first defined in
the first paragraph, then used in the second.

<p>The <dfn><abbr title="Garage Door Opener">GDO</abbr></dfn>
is a device that allows off-world teams to open the iris.</p>
<!-- ... later in the document: -->
<p>Teal'c activated his <abbr title="Garage Door Opener">GDO</abbr>
and
so
Hammond
ordered
the
iris
to
be
opened.</p>

With the addition of an a element,
the reference can be made explicit:

<p>The <dfn id=gdo><abbr title="Garage Door Opener">GDO</abbr></dfn>
is a device that allows off-world teams to open the iris.</p>
<!-- ... later in the document: -->
<p>Teal'c activated his <a href=#gdo><abbr title="Garage Door Opener">GDO</abbr></a>
and
so
Hammond
ordered
the
iris
to
be
opened.</p>

The abbr element represents an
abbreviation or acronym, optionally with its expansion. The
title
attribute may be used to provide an expansion of the abbreviation.
The attribute, if specified, must contain an expansion of the
abbreviation, and nothing else.

The paragraph below contains an abbreviation marked up with the
abbr element. This paragraph
defines the term "Web
Hypertext Application Technology Working Group".

<p>The <dfn id=whatwg><abbr title="Web Hypertext Application
Technology Working Group">WHATWG</abbr></dfn> is a loose
unofficial collaboration of Web browser manufacturers and interested
parties who wish to develop new technologies designed to allow authors
to
write
and
deploy
Applications
over
the
World
Wide
Web.</p>

This paragraph has two abbreviations. Notice how only one is
defined; the other, with no expansion associated with it, does not
use the abbr element.

<p>The <abbr title="Web Hypertext Application Technology Working
Group">
WHATWG</abbr>
started
working
on
HTML5
in
2004.</p>

This paragraph links an abbreviation to its definition.

<p>The <a href="#whatwg"><abbr title="Web Hypertext Application
Technology Working Group">WHATWG</abbr></a> community does not
have
much
representation
from
Asia.</p>

This paragraph marks up an abbreviation without giving an
expansion, possibly as a hook to apply styles for abbreviations
(e.g. smallcaps).

<p>Philip` and Dashiva both denied that they were going to
get the issue counts from past revisions of the specification to
backfill
the
<abbr>
WHATWG</abbr>
issue
graph.</p>

If an abbreviation is pluralized, the expansion's grammatical
number (plural vs singular) must match the grammatical number of
the contents of the element.

Here the plural is outside the element, so the expansion is in
the singular:

<p>Two <abbr title="Working Group">WG</abbr>s worked on
this specification: the <abbr>WHATWG</abbr> and the
<abbr>
HTMLWG</abbr>.</p>

Here the plural is inside the element, so the expansion is in
the plural:

<p>Two <abbr title="Working Groups">WGs</abbr> worked on
this specification: the <abbr>WHATWG</abbr> and the
<abbr>
HTMLWG</abbr>.</p>

The datetime attribute, if
present, must contain a date or time string
that identifies the date or time being specified.

If the datetime attribute is not present, then the
date or time must be specified in the content of the element, such
that parsing the element's textContent according to the rules for
parsing date or time strings in
content successfully extracts a date or time.

If result is empty (because the parsing
failed), then the date is unknown, the time is unknown, and the timezone is
unknown.

Otherwise: if result contains a date, then
that is the date ; if
result contains a time, then that is the
time ; and if
result contains a timezone, then the timezone
is the element's timezone . (A timezone can only be
present if both a date and a time are also present.)

The date DOM attribute must return
null if the date is
unknown, and otherwise must return the time corresponding to
midnight UTC (i.e. the first second) of the given date .

The time DOM attribute must return
null if the time is
unknown, and otherwise must return the time corresponding to the
given time of
1970-01-01, with the timezone UTC.

The timezone DOM attribute must
return null if the timezone is unknown, and otherwise must
return the time corresponding to 1970-01-01 00:00 UTC in the given
timezone ,
with the timezone set to UTC (i.e. the time corresponding to
1970-01-01 at 00:00 UTC plus the offset corresponding to the
timezone).

In the following snippet:

<p>
Our
first
date
was
<time
datetime="2006-09-23">
a
Saturday</time>.</p>

...the time element's
date
attribute would have the value 1,158,969,600,000ms, and the
time and
timezone attributes would return null.

In the following snippet:

<p>
We
stopped
talking
at
<time
datetime="2006-09-24
05:00
-7">
5am
the
next
morning</time>.</p>

...the time element's
date
attribute would have the value 1,159,056,000,000ms, the
time
attribute would have the value 18,000,000ms, and the timezone
attribute would return −25,200,000ms. To obtain the actual
time, the three attributes can be added together, obtaining
1,159,048,800,000, which is the specified date and time in UTC.

Finally, in the following snippet:

<p>
Many
people
get
up
at
<time>
08:00</time>.</p>

...the time element's
date
attribute would have the value null, the time attribute would
have the value 28,800,000ms, and the timezone
attribute would return null.

These APIs may be suboptimal. Comments on
making them more useful to JS authors are welcome. The primary use
cases for these elements are for marking up publication dates e.g.
in blog entries, and for marking event dates in hCalendar markup.
Thus the DOM APIs are likely to be used as ways to generate
interactive calendar widgets or some such.

The progress element
represents the completion progress of a task. The progress is
either indeterminate, indicating that progress is being made but
that it is not clear how much more work remains to be done before
the task is complete (e.g. because the task is waiting for a remote
host to respond), or the progress is a number in the range zero to
a maximum, giving the fraction of work that has so far been
completed.

There are two attributes that determine the current task
completion represented by the element.

The value attribute specifies
how much of the task has been completed, and the max attribute
specifies how much work the task requires in total. The units are
arbitrary and not specified.

Instead of using the attributes, authors are recommended to
include the current value and the maximum value inline as text
inside the element.

Here is a snippet of a Web application that shows the progress
of some automated task:

(The updateProgress() method in this example would
be called by some other code on the page to update the actual
progress bar as the task progressed.)

Author requirements : The max and value
attributes, when present, must have values that are valid floating point
numbers . The max attribute, if present, must have a value
greater than zero. The value attribute, if present, must have a value
equal to or greater than zero, and less than or equal to the value
of the max attribute, if present.

The progress
element is the wrong element to use for something that is just a
gauge, as opposed to task progress. For instance, indicating disk
space usage using progress
would be inappropriate. Instead, the meter element is available for such use
cases.

Using the results of this processing, user agents must determine
whether the progress bar is an indeterminate progress bar, or
whether it is a determinate progress bar, and in the latter case,
what its current and maximum values are, all as follows:

If the max attribute is omitted, and the value is
omitted, and the results of parsing the textContent was nothing, then the
progress bar is an indeterminate progress bar. Abort these
steps.

Otherwise, it is a determinate progress bar.

If the max attribute is included, then, if a value could
be parsed out of it, then the maximum value is that value.

Otherwise, if the max attribute is absent but the value attribute
is present, or, if the max attribute is present but no value could be
parsed from it, then the maximum is 1.

Otherwise, if neither attribute is included, then, if the
textContent contained one
number with an associated denominator punctuation character, then
the maximum value is the value associated with that
denominator punctuation character ; otherwise, if the
textContent contained two
numbers, the maximum value is the higher of the two values;
otherwise, the maximum value is 1.

If the value attribute is present on the element and
a value could be parsed out of it, that value is the current value
of the progress bar. Otherwise, if the attribute is present but no
value could be parsed from it, the current value is zero.

Otherwise if the value attribute is absent and the max attribute is
present, then, if the textContent was parsed and found to
contain just one number, with no associated denominator punctuation
character, then the current value is that number. Otherwise, if the
value attribute is absent and the max attribute is
present then the current value is zero.

Otherwise, if neither attribute is present, then the current
value is the lower of the one or two numbers that were found in the
textContent of the
element.

If the maximum value is less than or equal to zero, then it is
reset to 1.

If the current value is less than zero, then it is reset to
zero.

Finally, if the current value is greater than the maximum
value, then the current value is reset to the maximum value.

UA requirements for showing the progress bar :
When representing a progress
element to the user, the UA should indicate whether it is a
determinate or indeterminate progress bar, and in the former case,
should indicate the relative position of the current value relative
to the maximum value.

The max and value DOM attributes
must reflect the elements' content
attributes of the same name. When the relevant content attributes
are absent, the DOM attributes must return zero. The value parsed
from the textContent never
affects the DOM values.

The meter element represents a
scalar measurement within a known range, or a fractional value; for
example disk usage, the relevance of a query result, or the
fraction of a voting population to have selected a particular
candidate.

This is also known as a gauge.

The meter element
should not be used to indicate progress (as in a progress bar). For
that role, HTML provides a separate progress element.

The meter element
also does not represent a scalar value of arbitrary range —
for example, it would be wrong to use this to report a weight, or
height, unless there is a known maximum value.

There are six attributes that determine the semantics of the
gauge represented by the element.

The min
attribute specifies the lower bound of the range, and the max attribute
specifies the upper bound. The value attribute specifies the
value to have the gauge indicate as the "measured" value.

The other three attributes can be used to segment the gauge's
range into "low", "medium", and "high" parts, and to indicate which
part of the gauge is the "optimum" part. The low attribute specifies the
range that is considered to be the "low" part, and the high attribute
specifies the range that is considered to be the "high" part. The
optimum attribute gives the
position that is "optimum"; if that is higher than the "high" value
then this indicates that the higher the value, the better; if it's
lower than the "low" mark then it indicates that lower values are
better, and naturally if it is in between then it indicates that
neither high nor low values are good.

Authoring requirements : The recommended way of
giving the value is to include it as contents of the element,
either as two numbers (the higher number represents the maximum,
the other number the current value, and the minimum is assumed to
be zero), or as a percentage or similar (using one of the
characters such as "%"), or as a fraction.

User agents must then use all these numbers to obtain values for
six points on the gauge, as follows. (The order in which these are
evaluated is important, as some of the values refer to earlier
ones.)

The minimum value

If the min attribute is specified and a value could be
parsed out of it, then the minimum value is that value. Otherwise,
the minimum value is zero.

The maximum value

If the max attribute is specified and a value could be
parsed out of it, the maximum value is that value.

Otherwise, if the max attribute is specified but no value could be
parsed out of it, or if it was not specified, but either or both of
the min or
value
attributes were specified, then the maximum value is
1.

Otherwise, none of the max , min , and value attributes were specified. If the result
of processing the textContent of the element was either
nothing or just one number with no denominator punctuation
character, then the maximum value is 1; if the result was one
number but it had an associated denominator punctuation character,
then the maximum value is the value
associated with that denominator punctuation character ; and
finally, if there were two numbers parsed out of the textContent , then the maximum is the
higher of those two numbers.

If the above machinations result in a maximum value less than
the minimum value, then the maximum value is actually the same as
the minimum value.

The actual value

If the value attribute is specified and a value could
be parsed out of it, then that value is the actual value.

If the value attribute is not specified but the
max
attribute is specified and the result of processing the
textContent of the element
was one number with no associated denominator punctuation
character, then that number is the actual value.

If neither of the value and max attributes are
specified, then, if the result of processing the textContent of the element was one number
(with or without an associated denominator punctuation character),
then that is the actual value, and if the result of processing the
textContent of the element
was two numbers, then the actual value is the lower of the two
numbers found.

Otherwise, if none of the above apply, the actual value is
zero.

If the above procedure results in an actual value less than the
minimum value, then the actual value is actually the same as the
minimum value.

If, on the other hand, the result is an actual value greater
than the maximum value, then the actual value is the maximum
value.

The low boundary

If the low attribute is specified and a value could be
parsed out of it, then the low boundary is that value. Otherwise,
the low boundary is the same as the minimum value.

If the above results in a low boundary that is less than the
minimum value, the low boundary is the minimum value.

The high boundary

If the high attribute is specified and a value could be
parsed out of it, then the high boundary is that value. Otherwise,
the high boundary is the same as the maximum value.

If the above results in a high boundary that is higher than the
maximum value, the high boundary is the maximum value.

The optimum point

If the optimum attribute is specified and a value
could be parsed out of it, then the optimum point is that value.
Otherwise, the optimum point is the midpoint between the minimum
value and the maximum value.

If the optimum point is then less than the minimum value, then
the optimum point is actually the same as the minimum value.
Similarly, if the optimum point is greater than the maximum value,
then it is actually the maximum value instead.

All of which should result in the following inequalities all
being true:

minimum value ≤ actual value ≤ maximum value

minimum value ≤ low boundary ≤ high boundary ≤ maximum
value

minimum value ≤ optimum point ≤ maximum value

UA requirements for regions of the gauge : If
the optimum point is equal to the low boundary or the high
boundary, or anywhere in between them, then the region between the
low and high boundaries of the gauge must be treated as the optimum
region, and the low and high parts, if any, must be treated as
suboptimal. Otherwise, if the optimum point is less than the low
boundary, then the region between the minimum value and the low
boundary must be treated as the optimum region, the region between
the low boundary and the high boundary must be treated as a
suboptimal region, and the region between the high boundary and the
maximum value must be treated as an even less good region. Finally,
if the optimum point is higher than the high boundary, then the
situation is reversed; the region between the high boundary and the
maximum value must be treated as the optimum region, the region
between the high boundary and the low boundary must be treated as a
suboptimal region, and the remaining region between the low
boundary and the minimum value must be treated as an even less good
region.

UA requirements for showing the gauge : When
representing a meter element to
the user, the UA should indicate the relative position of the
actual value to the minimum and maximum values, and the
relationship between the actual value and the three regions of the
gauge.

User agents may combine the value of the title attribute and the
other attributes to provide context-sensitive help or inline text
detailing the actual values.

For example, the following snippet:

<meter
min=0
max=60
value=23.2
title=seconds>
</meter>

...might cause the user agent to display a gauge with a tooltip
saying "Value: 23.2 out of 60." on one line and "seconds" on a
second line.

The min
, max ,
value ,
low ,
high ,
and optimum DOM attributes must
reflect the elements' content attributes of
the same name. When the relevant content attributes are absent, the
DOM attributes must return zero. The value parsed from the
textContent never affects
the DOM values.

The code element represents a
fragment of computer code. This could be an XML element name, a
filename, a computer program, or any other string that a computer
would recognize.

Although there is no formal way to indicate the language of
computer code being marked up, authors who wish to mark
code elements with the language
used, e.g. so that syntax highlighting scripts can use the right
rules, may do so by adding a class prefixed with " language- " to the element.

The following example shows how the element can be used in a
paragraph to mark up element names and computer code, including
punctuation.

<p>The <code>code</code> element represents a fragment of computer
code.</p>
<p>When you call the <code>activate()</code> method on the
<code>robotSnowman</code> object, the eyes glow.</p>
<p>The example below uses the <code>begin</code> keyword to indicate
the start of a statement block. It is paired with an <code>end</code>
keyword, which is followed by the <code>.</code> punctuation character
(full
stop)
to
indicate
the
end
of
the
program.</p>

The following example shows how a block of code could be marked
up using the pre and code elements.

In this second example, the user is told to pick a particular
menu item. The outer kbd element
marks up a block of input, with the inner kbd elements representing each individual step of
the input, and the samp elements
inside them indicating that the steps are input based on something
being displayed by the system, in this case menu labels:

<p>To make George eat an apple, select
<kbd><kbd><samp>File</samp></kbd>|<kbd><samp>Eat Apple...</samp></kbd></kbd>
</p>

The sup element represents a
superscript and the sub element
represents a subscript.

These elements must be used only to mark up typographical
conventions with specific meanings, not for typographical
presentation for presentation's sake. For example, it would be
inappropriate for the sub and
sup elements to be used in the name
of the LaTeX document preparation system. In general, authors
should use these elements only if the absence of those
elements would change the meaning of the content.

When the sub element is used
inside a var element, it represents
the subscript that identifies the variable in a family of
variables.

<p>The coordinate of the <var>i</var>th point is
(<var>x<sub><var>i</var></sub></var>, <var>y<sub><var>i</var></sub></var>).
For example, the 10th point has coordinate
(<var>
x<sub>
10</sub>
</var>,
<var>
y<sub>
10</sub>
</var>
).</p>

In certain languages, superscripts are part of the typographical
conventions for some abbreviations.

Mathematical expressions often use subscripts and superscripts.
Authors are encouraged to use MathML for marking up mathematics,
but authors may opt to use sub and
sup if detailed mathematical markup
is not desired. [MathML]

The i element represents a span of
text in an alternate voice or mood, or otherwise offset from the
normal prose, such as a taxonomic designation, a technical term, an
idiomatic phrase from another language, a thought, a ship name, or
some other prose whose typical typographic presentation is
italicized.

Terms in languages different from the main text should be
annotated with lang attributes ( xml:lang in XML).

In the following example, a dream sequence is marked up using
i elements.

<p>Raymond tried to sleep.</p>
<p><i>The ship sailed away on Thursday</i>, he
dreamt. <i>The ship had many people aboard, including a beautiful
princess called Carey. He watched her, day-in, day-out, hoping she
would notice him, but she never did.</i></p>
<p><i>Finally one night he picked up the courage to speak with
her—</i></p>
<p>
Raymond
woke
with
a
start
as
the
fire
alarm
rang
out.</p>

The i element should be used as a
last resort when no other element is more appropriate. In
particular, citations should use the cite element, defining instances of terms
should use the dfn element, stress
emphasis should use the em element,
importance should be denoted with the strong element, quotes should be marked up
with the q element, and small print
should use the small element.

Authors are encouraged to use the class attribute on the
i element to identify why the element
is being used, so that if the style of a particular use (e.g. dream
sequences as opposed to taxonomic terms) is to be changed at a
later date, the author doesn't have to go through the entire
document (or series of related documents) annotating each use.

Style sheets can be used to format i elements, just like any other element can be
restyled. Thus, it is not the case that content in i elements will necessarily be italicized.

The b element represents a span of
text to be stylistically offset from the normal prose without
conveying any extra importance, such as key words in a document
abstract, product names in a review, or other spans of text whose
typical typographic presentation is boldened.

The following example shows a use of the b element to highlight key words without marking
them up as important:

<p>
The
<b>
frobonitor</b>
and
<b>
barbinator</b>
components
are
fried.</p>

In the following example, objects in a text adventure are
highlighted as being special by use of the b element.

<article>
<h2>Kittens 'adopted' by pet rabbit</h2>
<p><b>Six abandoned kittens have found an unexpected new
mother figure — a pet rabbit.</b></p>
<p>Veterinary nurse Melanie Humble took the three-week-old
kittens to her Aberdeen home.</p>
[...]

The b element should be used as a
last resort when no other element is more appropriate. In
particular, headers should use the h1 to h6 elements,
stress emphasis should use the em
element, importance should be denoted with the strong element, and text marked or highlighted
should use the mark element.

The following would be incorrect usage:

<p>
<b>
WARNING!</b>
Do
not
frob
the
barbinator!</p>

In the previous example, the correct element to use would have
been strong , not b .

Style sheets can be used to format b elements, just like any other element can be
restyled. Thus, it is not the case that content in b elements will necessarily be boldened.

Authors must specify the dir attribute on this element, with the value
ltr to specify a left-to-right override and with the
value rtl to specify a right-to-left override.

If the element has the dir attribute set to the exact value
ltr , then for the purposes of the bidi algorithm, the
user agent must act as if there was a U+202D LEFT-TO-RIGHT OVERRIDE
character at the start of the element, and a U+202C POP DIRECTIONAL
FORMATTING at the end of the element.

If the element has the dir attribute set to the exact value
rtl , then for the purposes of the bidi algorithm, the
user agent must act as if there was a U+202E RIGHT-TO-LEFT OVERRIDE
character at the start of the element, and a U+202C POP DIRECTIONAL
FORMATTING at the end of the element.

The requirements on handling the bdo element for the bidi algorithm may be
implemented indirectly through the style layer. For example, an
HTML+CSS user agent should implement these requirements by
implementing the CSS unicode-bidi property. [CSS21]

The ruby element allows one or
more spans of phrasing content to be marked with ruby
annotations.

A ruby element represents the
spans of phrasing content it contains, ignoring all the child
rt and rp elements and their descendants. Those spans of
phrasing content have associated annotations created using the
rt element.

In this example, each ideograph in the text 斎藤信男 is annotated with its
reading.

An rt element that is a child of
a ruby element represents an
annotation (given by its children) for the zero or more nodes of
phrasing content that immediately precedes it in the ruby element, ignoring rp elements.

An rt element that is not a child
of a ruby element represents the
same thing as its children.

3.9.24 The rp element

Categories

None.

Contexts in which this element may be used:

As a child of a ruby element,
either immediately before or immediately after an rt element.

Content model:

If the rp element is immediately
after an rt element that is
immediately preceded by another rp
element: a single character from Unicode character class Pe.

The rp element can be used to
provide parentheses around a ruby text component of a ruby
annotation, to be shown by user agents that don't support ruby
annotations.

An rp element that is a child of
a ruby element represents nothing
and it and its contents must be ignored. An rp element whose parent element is not a
ruby element represents the same
thing as its children.

The example above, in which each ideograph in the text
斎藤信男 is
annotated with its reading, could be expanded to use rp so that in legacy user agentthe readings are in
parentheses:

<dialog>
<dt>Customer
<dd>Hello! I wish to register a complaint. Hello. Miss?
<dt>Shopkeeper
<dd><span title="Colloquial pronunciation of 'What do you'"
>Watcha</span> mean, miss?
<dt>Customer
<dd>Uh, I'm sorry, I have a cold. I wish to make a complaint.
<dt>Shopkeeper
<dd>Sorry, <span title="This is, of course, a lie.">we're
closing for lunch</span>.
</dialog>

For longer annotations, the a
element should be used, pointing to an element later in the
document. The convention is that the contents of the link be a
number in square brackets.

In this example, a footnote in the dialog links to a paragraph
below the dialog. The paragraph then reciprocally links back to the
dialog, allowing the user to return to the location of the
footnote.

<dialog>
<dt>Announcer
<dd>Number 16: The <i>hand</i>.
<dt>Interviewer
<dd>Good evening. I have with me in the studio tonight Mr
Norman St John Polevaulter, who for the past few years has
been contradicting people. Mr Polevaulter, why <em>do</em>
you contradict people?
<dt>Norman
<dd>I don't. <a href="#fn1" id="r1">[1]</a>
<dt>Interviewer
<dd>You told me you did!
</dialog>
<section>
<p id="fn1"><a href="#r1">[1]</a> This is, naturally, a lie,
but paradoxically if it were true he could not say so without
contradicting the interviewer and thus making it false.</p>
</section>

For side notes, longer annotations that apply to entire sections
of the text rather than just specific words or sentences, the
aside element should be used.

In this example, a sidebar is given after a dialog, giving some
context to the dialog.

<dialog>
<dt>Customer
<dd>I will not buy this record, it is scratched.
<dt>Shopkeeper
<dd>I'm sorry?
<dt>Customer
<dd>I will not buy this record, it is scratched.
<dt>Shopkeeper
<dd>No no no, this's'a tobacconist's.
</dialog>
<aside>
<p>In 1970, the British Empire lay in ruins, and foreign
nationalists frequented the streets — many of them Hungarians
(not the streets — the foreign nationals). Sadly, Alexander
Yalt has been publishing incompetently-written phrase books.
</aside>

The following example represents the addition of two paragraphs,
the second of which was inserted in two parts. The first
ins element in this example thus
crosses a paragraph boundary, which is considered poor form.

The cite attribute may be used to
specify a URI that explains the change. When that document is long,
for instance the minutes of a meeting, authors are encouraged to
include a fragment identifier pointing to the specific part of that
document that discusses the change.

If the cite attribute is present, it must be a URI (or
IRI) that explains the change. User agents should allow users to
follow such citation links.

The datetime attribute may be
used to specify the time and date of the change.

User agents must parse the datetime
attribute according to the parse a
string as a datetime value algorithm. If that doesn't return a
time, then the modification has no associated timestamp (the value
is non-conforming; it is not a valid datetime
). Otherwise, the modification is marked as having been made at the
given datetime. User agents should use the associated timezone
information to determine which timezone to present the given
datetime in.

3.10.4 Edits and
paragraphs

Since the ins and del elements do not affect paragraphing , it is possible, in some cases
where paragraphs are implied (without explicit p elements), for an ins or del
element to span both an entire paragraph or other non- phrasing content elements and part of another
paragraph.

For example:

<section>
<ins>
<p>
This is a paragraph that was inserted.
</p>
This is another paragraph whose first sentence was inserted
at the same time as the paragraph above.
</ins>
This is a second sentence, which was there all along.
</section>

By only wrapping some paragraphs in p elements, one can even get the end of one
paragraph, a whole second paragraph, and the start of a third
paragraph to be covered by the same ins or del
element (though this is very confusing, and not considered good
practice):

<section>
This is the first paragraph. <ins>This sentence was
inserted.
<p>This second paragraph was inserted.</p>
This sentence was inserted too.</ins> This is the
third paragraph in this example.
</section>

However, due to the way implied paragraphs are defined, it is not possible
to mark up the end of one paragraph and the start of the very next
one using the same ins or
del element. You instead have to
use one (or two) p element(s) and two
ins or del elements:

For example:

<section>
<p>This is the first paragraph. <del>This sentence was
deleted.</del></p>
<p><del>This sentence was deleted too.</del> That
sentence needed a separate &lt;del&gt; element.</p>
</section>

Partly because of the confusion described above, authors are
strongly recommended to always mark up all paragraphs with the
p element, and to not have any
ins or del elements that cross across any implied paragraphs .

3.10.5 Edits and
lists

The content models of the ol and
ul elements do not allow
ins and del elements as children. Lists always represent
all their items, including items that would otherwise have been
marked as deleted.

To indicate that an item is inserted or deleted, an
ins or del element can be wrapped around the contents of
the li element. To indicate that an
item has been replaced by another, a single li element can have one or more del elements followed by one or more
ins elements.

In the following example, a list that started empty had items
added and removed from it over time. The bits in the example that
have been emphasised show the parts that are the "current" state of
the list. The list item numbers don't take into account the edits,
though.

The figure element represents
some flow content , optionally with a
caption, which can be moved away from the main flow of the document
without affecting the document's meaning.

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.

The first legend element
child of the element, if any, represents the caption of the
figure element's contents. If
there is no child legend
element, then there is no caption.

The remainder of the element's contents, if any, represents the
content.

<figure>
<p>'Twas brillig, and the slithy toves<br>
Did gyre and gimble in the wabe;<br>
All mimsy were the borogoves,<br>
And the mome raths outgrabe.</p>
<legend><cite>Jabberwocky</cite> (first verse). Lewis Carroll, 1832-98</legend>
</figure>

In this example, which could be part of a much larger work
discussing a castle, the figure has three images in it.

<figure>
<img src="castle1423.jpeg" title="Etching. Anonymous, ca. 1423."
alt="The castle has one tower, and a tall wall around it.">
<img src="castle1858.jpeg" title="Oil-based paint on canvas. Maria Towle, 1858."
alt="The castle now has two towers and two walls.">
<img src="castle1999.jpeg" title="Film photograph. Peter Jankle, 1999."
alt="The castle lies in ruins, the original tower all that remains in one piece.">
<legend>The castle through the ages: 1423, 1858, and 1999 respectively.</legend>
</figure>

The image given by the src attribute is the embedded
content, and the value of the alt attribute is the
img element's fallback content .

Authoring requirements : The src attribute must be
present, and must contain a URI (or IRI).

Should we restrict the URI to pointing to an
image? What's an image? Is PDF an image? (Safari supports PDFs in
<img> elements.) How about SVG? (Opera supports those). WMFs?
XPMs? HTML?

The requirements for the alt attribute depend on what the image is
intended to represent:

A phrase or paragraph with an alternative graphical
representation

Sometimes something can be more clearly stated in graphical
form, for example as a flowchart, a diagram, a graph, or a simple
map showing directions. In such cases, an image can be given using
the img element, but the lesser
textual version must still be given, so that users who are unable
to view the image (e.g. because they have a very slow connection,
or because they are using a text-only browser, or because they are
listening to the page being read out by a hands-free automobile
voice Web browser, or simply because they are blind) are still able
to understand the message being conveyed.

The text must be given in the alt attribute, and must
convey the same message as the image specified in the src attribute.

In the following example we have a flowchart in image form,
with text in the alt attribute rephrasing the flowchart in prose
form:

<p>In the common case, the data handled by the tokenisation stage
comes from the network, but it can also come from script.</p>
<p><img src="images/parsing-model-overview.png" alt="The network
passes data to the Tokeniser stage, which passes data to the Tree
Construction stage. From there, data goes to both the DOM and to
Script Execution. Script Execution is linked to the DOM, and, using
document.write(),
passes
data
to
the
Tokeniser.">
</p>

Here's another example, showing a good solution and a bad
solution to the problem of including an image in a description.

First, here's the good solution. This sample shows how the
alternative text should just be what you would have put in the
prose if the image had never existed.

<!-- This is the correct way to do things. -->
<p>
You are standing in an open field west of a house.
<img src="house.jpeg" alt="The house is white, with a boarded front door.">
There is a small mailbox here.
</p>

Second, here's the bad solution. In this incorrect way of doing
things, the alternative text is simply a description of the image,
instead of a textual replacement for the image. It's bad because
when the image isn't shown, the text doesn't flow as well as in the
first example.

<!-- This is the wrong way to do things. -->
<p>
You are standing in an open field west of a house.
<img src="house.jpeg" alt="A white house, with a boarded front door.">
There is a small mailbox here.
</p>

It is important to realize that the alternative text is a
replacement for the image, not a description of the
image.

Icons: a short phrase or label with an alternative graphical
representation

A document can contain information in iconic form. The icon is
intended to help users of visual browsers to recognize features at
a glance.

In some cases, the icon is supplemental to a text label
conveying the same meaning. In those cases, the alt attribute must be
present but must be empty.

Here the icons are next to text that conveys the same meaning,
so they have an empty alt attribute:

In other cases, the icon has no text next to it describing what
it means; the icon is supposed to be self-explanatory. In those
cases, an equivalent textual label must be given in the
alt
attribute.

Here, posts on a news site are labeled with an icon indicating
their topic.

<body>
<article>
<header>
<h1>Ratatouille wins <i>Best Movie of the Year</i> award</h1>
<p><img src="movies.png" alt="Movies"></p>
</header>
<p>Pixar has won yet another <i>Best Movie of the Year</i> award,
making this its 8th win in the last 12 years.</p>
</article>
<article>
<header>
<h1>Latest TWiT episode is online</h1>
<p><img src="podcasts.png" alt="Podcasts"></p>
</header>
<p>The latest TWiT episode has been posted, in which we hear
several tech news stories as well as learning much more about the
iPhone. This week, the panelists compare how reflective their
iPhones' Apple logos are.</p>
</article>
</body>

Many pages include logos, insignia, flags, or emblems, which
stand for a particular entity such as a company, organization,
project, band, software package, country, or some such.

If the logo is being used to represent the entity, the
alt attribute
must contain the name of the entity being represented by the logo.
The alt
attribute must not contain text like the word "logo", as
it is not the fact that it is a logo that is being conveyed, it's
the entity itself.

If the logo is being used next to the name of the entity that it
represents, then the logo is supplemental, and its alt attribute must instead
be empty.

If the logo is merely used as decorative material (as branding,
or, for example, as a side image in an article that mentions the
entity to which the logo belongs), then the entry below on purely
decorative images applies. If the logo is actually being discussed,
then it is being used as a phrase or paragraph (the description of
the logo) with an alternative graphical representation (the logo
itself), and the first entry above applies.

In the following snippets, all four of the above cases are
present. First, we see a logo used to represent a company:

<h1>
<img
src="XYZ.gif"
alt="The
XYZ
company">
</h1>

Next, we see a paragraph which uses a logo right next to the
company name, and so doesn't have any alternative text:

<article>
<h2>News</h2>
<p>We have recently been looking at buying the <img src="alpha.gif"
alt=""> ΑΒΓ company, a small Greek company
specializing
in
our
type
of
product.</p>

In this third snippet, we have a logo being used in an aside, as
part of the larger article discussing the acquisition:

<aside><p><img src="alpha-large.gif" alt=""></p></aside>
<p>The ΑΒΓ company has had a good quarter, and our
pie chart studies of their accounts suggest a much bigger blue slice
than its green and orange slices, which is always a good sign.</p>
</article>

Finally, we have an opinion piece talking about a logo, and the
logo is therefore described in detail in the alternative text.

<p>Consider for a moment their logo:</p>
<p><img src="/images/logo" alt="It consists of a green circle with a
green question mark centered inside it."></p>
<p>How unoriginal can you get? I mean, oooooh, a question mark, how
<em>revolutionary</em>, how utterly <em>ground-breaking</em>, I'm
sure everyone will rush to adopt those specifications now! They could
at least have tried for some sort of, I don't know, sequence of
rounded squares with varying shades of green and bold white outlines,
at
least
that
would
look
good
on
the
cover
of
a
blue
book.</p>

This example shows how the alternative text should be written
such that if the image isn't available, and the text is used
instead, the text flows seamlessly into the surrounding text, as if
the image had never been there in the first place.

A graphical representation of some of the surrounding text

In many cases, the image is actually just supplementary, and its
presence merely reinforces the surrounding text. In these cases,
the alt
attribute must be present but its value must be the empty
string.

A flowchart that repeats the previous paragraph in graphical
form:

<p>The network passes data to the Tokeniser stage, which
passes data to the Tree Construction stage. From there, data goes
to both the DOM and to Script Execution. Script Execution is
linked to the DOM, and, using document.write(), passes data to
the Tokeniser.</p>
<p>
<img
src="images/parsing-model-overview.png"
alt="">
</p>

A graph that repeats the previous paragraph in graphical
form:

<p>According to a study covering several billion pages,
about 62% of documents on the Web in 2007 triggered the Quirks
rendering mode of Web browsers, about 30% triggered the Almost
Standards mode, and about 9% triggered the Standards mode.</p>
<p>
<img
src="rendering-mode-pie-chart.png"
alt="">
</p>

In general, an image falls into this category if removing the
image doesn't make the page any less useful, but including the
image makes it a lot easier for users of visual browsers to
understand the concept.

A purely decorative image that doesn't add any information but
is still specific to the surrounding content

In some cases, the image isn't discussed by the surrounding
text, but it has some relevance. Such images are decorative, but
still form part of the content. In these cases, the alt attribute must be
present but its value must be the empty string.

Examples where the image is purely decorative despite being
relevant would include things like a photo of the Black Rock City
landscape in a blog post about an event at Burning Man, or an image
of a painting inspired by a poem, on a page reciting that poem. The
following snippet shows an example of the latter case (only the
first verse is included in this snippet):

<h1>The Lady of Shalott</h1>
<p><img src="shalott.jpeg" alt=""></p>
<p>On either side the river lie<br>
Long fields of barley and of rye,<br>
That clothe the wold and meet the sky;<br>
And through the field the road run by<br>
To many-tower'd Camelot;<br>
And up and down the people go,<br>
Gazing where the lilies blow<br>
Round an island there below,<br>
The
island
of
Shalott.</p>

In general, if an image is decorative but isn't especially
page-specific, for example an image that forms part of a site-wide
design scheme, the image should be specified in the site's CSS, not
in the markup of the document.

A key part of the content

In some cases, the image is a critical part of the content. This
could be the case, for instance, on a page that is part of a photo
gallery. The image is the whole point of the page
containing it.

When it is possible for alternative text to be provided, for
example if the image is part of a series of screenshots in a
magazine review, or part of a comic strip, or is a photograph in a
blog entry about that photograph, text that conveys can serve as a
substitute for the image must be given as the contents of the
alt
attribute.

In a rare subset of these cases, there might be no alternative
text available. This could be the case, for instance, on a photo
upload site, if the site has received 8000 photos from a user
without the user annotating any of them. In such cases, the
alt attribute
may be omitted, but the alt attribute should be included, with a useful
value, if at all possible.

In any case, if an image is a key part of the content, the
alt attribute
must not be specified with an empty value.

A screenshot in a gallery of screenshots for a new OS, with some
alternative text:

<figure>
<img src="KDE%20Light%20desktop.png"
alt="The desktop is blue, with icons along the left hand side in
two columns, reading System, Home, K-Mail, etc. A window is
open showing that menus wrap to a second line if they
cannot fit in the window. The window has a list of icons
along the top, with an address bar below it, a list of
icons for tabs along the left edge, a status bar on the
bottom, and two panes in the middle. The desktop has a bar
at the bottom of the screen with a few buttons, a pager, a
list of open applications, and a clock.">
<legend>Screenshot of a KDE desktop.</legend>
</figure>

A photo on a photo-sharing site, if the site received the image
with no metadata other than the caption:

In this case, though, it would be better if a detailed
description of the important parts of the image obtained from the
user and included on the page.

Sometimes there simply is no text that can do justice to an
image. For example, there is little that can be said to usefully
describe a Rorschach inkblot test.

<figure>
<img src="/commons/a/a7/Rorschach1.jpg">
<legend>A black outline of the first of the ten cards
in the Rorschach inkblot test.</legend>
</figure>

Note that the following would be a very bad use of alternative
text:

<!-- This example is wrong. Do not copy it. -->
<figure>
<img src="/commons/a/a7/Rorschach1.jpg" alt="A black outline
of the first of the ten cards in the Rorschach inkblot test.">
<legend>A black outline of the first of the ten cards
in the Rorschach inkblot test.</legend>
</figure>

Including the caption in the alternative text like this isn't
useful because it effectively duplicates the caption for users who
don't have images, taunting them twice yet not helping them any
more than if they had only read or heard the caption once.

Since some users cannot use images at all (e.g.
because they have a very slow connection, or because they are using
a text-only browser, or because they are listening to the page
being read out by a hands-free automobile voice Web browser, or
simply because they are blind), the alt attribute is only
allowed to be omitted when no alternative text is available and
none can be made available, e.g. on automated image gallery
sites.

An image in an e-mail or document intended for a specific
person who is known to be able to view images

When an image is included in a communication (such as an HTML
e-mail) aimed at someone who is known to be able to view images,
the alt
attribute may be omitted. However, even in such cases it is
strongly recommended that alternative text be included (as
appropriate according to the kind of image involved, as described
in the above entries), so that the e-mail is still usable should
the user use a mail client that does not support images, or should
the e-mail be forwarded on to other users whose abilities might not
include easily seeing images.

The img must not be used as a
layout tool. In particular, img
elements should not be used to display fully transparent images, as
they rarely convey meaning and rarely add anything useful to the
document.

There has been some suggestion that the
longdesc attribute from HTML4, or some other
mechanism that is more powerful than alt="" ,
should be included. This has not yet been considered.

User agent requirements : When the alt attribute is present
and its value is the empty string, the image supplements the
surrounding content. In such cases, the image may be omitted
without affecting the meaning of the document.

When the alt attribute is present and its value is not the
empty string, the image is a graphical equivalent of the string
given in the alt attribute. In such cases, the image may be
replaced in the rendering by the string given in the attribute
without significantly affecting the meaning of the document.

When the alt attribute is missing, the image represents a
key part of the content. Non-visual user agents should apply image
analysis heuristics to help the user make sense of the image.

The alt
attribute does not represent advisory information. User agents must
not present the contents of the alt attribute in the same way as content of the
title
attribute.

If the src
attribute is omitted, the image represents whatever string is given
by the element's alt attribute, if any, or nothing, if that
attribute is empty or absent.

The src
attribute, on setting, must cause the user agent to immediately
begin to download the specified resource , unless the user agent
cannot support images, or its support for images has been
disabled.

This, unfortunately, can be used to perform a
rudimentary port scan of the user's local network (especially in
conjunction with scripting, though scripting isn't actually
necessary to carry out such an attack). User agents may implement
cross-origin access control
policies that mitigate this attack.

Once the download has completed, if the image is a valid image,
the user agent must fire a load event on the img element (this happens after complete starts
returning true). If the download fails or it completes but the
image is not a valid or supported image, the user agent must
fire an error
event on the img element.

The remote server's response metadata (e.g. an HTTP 404 status
code, or associated
Content-Type headers ) must be ignored when determining whether
the resource obtained is a valid image or not.

This allows servers to return images with error
responses.

User agents must not support non-image resources with the
img element.

The usemap attribute, if present, can indicate
that the image has an associated image map
.

The ismap attribute, when used on
an element that is a descendant of an a element with an href attribute,
indicates by its presence that the element provides access to a
server-side image map. This affects how events are handled on the
corresponding a element.

The ismap attribute is a boolean attribute . The attribute must not be
specified on an element that does not have an ancestor
a element with an href
attribute.

The DOM attributes alt , src , useMap , and isMap each must reflect the respective content attributes of the
same name.

The DOM attributes height and width must return the
rendered height and width of the image, in CSS pixels, if the image
is being rendered, and is being rendered to a visual medium, or 0
otherwise. [CSS21]

The DOM attribute complete must return true if
the user agent has downloaded the image specified in the
src attribute,
and it is a valid image, and false otherwise.

A single image can have different appropriate alternative text
depending on the context.

In each of the following cases, the same image is used, yet the
alt text is
different each time. The image is the coat of arms of the Canton
Geneva in Switzerland.

Here it is used as a supplementary icon:

<p>
I
lived
in
<img
src="carouge.svg"
alt="">
Carouge.</p>

Here it is used as an icon representing the town:

<p>
Home
town:
<img
src="carouge.svg"
alt="Carouge">
</p>

Here it is used as part of a text on the town:

<p>Carouge has a coat of arms.</p>
<p><img src="carouge.svg" alt="The coat of arms depicts a lion, sitting in front of a tree."></p>
<p>
It
is
used
as
decoration
all
over
the
town.</p>

Here it is used as a way to support a similar text where the
description is given as well as, instead of as an alternative to,
the image:

<p>Carouge has a coat of arms.</p>
<p><img src="carouge.svg" alt=""></p>
<p>The coat of arms depicts a lion, sitting in front of a tree.
It
is
used
as
decoration
all
over
the
town.</p>

Here it is used as part of a story:

<p>He picked up the folder and a piece of paper fell out.</p>
<p><img src="carouge.svg" alt="Shaped like a shield, the paper had a
red background, a green tree, and a yellow lion with its tongue
hanging out and whose tail was shaped like an S."></p>
<p>He stared at the folder. S! The answer he had been looking for all
this time was simply the letter S! How had he not seen that before? It all
came together now. The phone call where Hector had referred to a lion's tail,
the
time
Marco
had
stuck
his
tongue
out...</p>

Here are some more examples showing the same picture used in
different contexts, with different appropriate alternate texts each
time.

<article>
<h1>My cats</h1>
<h2>Fluffy</h2>
<p>Fluffy is my favourite.</p>
<img src="fluffy.jpg" alt="She likes playing with a ball of yarn.">
<p>She's just too cute.</p>
<h2>Miles</h2>
<p>My other cat, Miles just eats and sleeps.</p>
</article>

<article>
<h1>Photography</h1>
<h2>Shooting moving targets indoors</h2>
<p>The trick here is to know how to anticipate; to know at what speed and
what distance the subject will pass by.</p>
<img src="fluffy.jpg" alt="A cat flying by, chasing a ball of yarn, can be
photographed quite nicely using this technique.">
<h2>Nature by night</h2>
<p>To achieve this, you'll need either an extremely sensitive film, or
immense flash lights.</p>
</article>

<article>
<h1>About me</h1>
<h2>My pets</h2>
<p>I've got a cat named Fluffy and a dog named Miles.</p>
<img src="fluffy.jpg" alt="Fluffy, my cat, tends to keep itself busy.">
<p>My dog Miles and I like go on long walks together.</p>
<h2>music</h2>
<p>After our walks, having emptied my mind, I like listening to Bach.</p>
</article>

<article>
<h1>Fluffy and the Yarn</h1>
<p>Fluffy was a cat who liked to play with yarn. He also liked to jump.</p>
<aside><img src="fluffy.jpg" alt="" title="Fluffy"></aside>
<p>He would play in the morning, he would play in the evening.</p>
</article>

When content loads in an iframe , after any load events are fired
within the content itself, the user agent must fire a load event at
the iframe element. When content
fails to load (e.g. due to a network error), then the user agent
must fire an error event at the element instead.

While the sandbox attribute is specified, the
iframe element's nested browsing context , and all the browsing
contexts nested within it (either directly or
indirectly through other nested browsing contexts) must have the
following flags set:

First, it can be used to allow content from the same site to be
sandboxed to disable scripting, while still allowing access to the
DOM of the sandboxed content.

Second, it can be used to embed content from a third-party site,
sandboxed to prevent that site from opening popup windows, etc,
without preventing the embedded page from communicating back to its
originating site, using the database APIs to store data, etc.

The sandboxed forms browsing context
flag , unless the sandbox attribute's value, when split on spaces , is
found to have the allow-forms
keyword set

These flags must not be set unless the conditions listed above
define them as being set.

In this example, some completely-unknown, potentially hostile,
user-provided HTML content is embedded in a page. Because it is
sandboxed, it is treated by the user agent as being from a unique
origin, despite the content being served from the same site. Thus
it is affected by all the normal cross-site restrictions. In
addition, the embedded page has scripting disabled, plugins
disabled, forms disabled, and it cannot navigate any frames or
windows other than itself (or any frames or windows it itself
embeds).

Note that cookies are still send to the server in the
getusercontent.cgi request, though they are
not visible in the document.cookies DOM attribute.

In this example, a gadget from another site is embedded. The
gadget has scripting and forms enabled, and the origin sandbox
restrictions are lifted, allowing the gadget to communicate with
its originating server. The sandbox is still useful, however, as it
disables plugins and popups, thus reducing the risk of the user
being exposed to malware and other annoyances.

In a CSS-supporting user agent: the user agent must add all the
style sheets that apply to the iframe element to the cascade of the active document of the iframe element's nested
browsing context , at the appropriate cascade levels, before
any style sheets specified by the document itself.

In a CSS-supporting user agent: the user agent must, for the
purpose of CSS property inheritance only, treat the root element of
the active document of the iframe element's nested
browsing context as being a child of the iframe element. (Thus inherited properties on
the root element of the document in the iframe will inherit the computed values of
those properties on the iframe
element instead of taking their initial values.)

In visual media, in a CSS-supporting user agent: the user agent
should set the intrinsic width of the iframe to the width that the element would
have if it was a non-replaced block-level element with 'width:
auto'.

In visual media, in a CSS-supporting user agent: the user agent
should set the intrinsic height of the iframe to the height of the bounding box
around the content rendered in the iframe at its current width.

This is intended to get around the otherwise
circular dependency of percentage dimensions that depend on the
height of the containing block, thus affecting the height of the
document's bounding box, thus affecting the height of the viewport,
thus affecting the size of the initial containing block.

In speech media, the user agent should render the nested browsing context without announcing that it
is a separate document.

For example if the user agent supports listing
all the links in a document, links in "seamlessly" nested documents
would be included in that list without being significantly
distinguished from links in the document itself.

Parts of the above might get moved into the
rendering section at some point.

In this example, the site's navigation is embedded using a
client-side include using an iframe . Any links in the iframe will, in new user agents, be
automatically opened in the iframe 's parent browsing context; for legacy
user agents, the site could also include a base element with a target attribute
with the value _parent . Similarly, in new
user agents the styles of the parent page will be automatically
applied to the contents of the frame, but to support legacy user
agents authors might wish to include the styles explicitly.

Plugins are disabled in sandboxed browsing
contexts because they might not honor the restrictions imposed by
the sandbox (e.g. they might allow scripting even when scripting in
the sandbox is disabled). User agents should convey the danger of
overriding the sandbox to the user if an option to do so is
provided.

Otherwise, the src attribute is present, and the element is not
in a sandboxed browsing context:

When the src attribute is set, user agents are expected
to find an appropriate plugin for the
specified resource, based on the content's type , and hand that plugin the content of the resource. If the plugin supports a scriptable interface, the
HTMLEmbedElement
object representing the element should expose that interfaces.

The user agent should pass the names and values of all the
attributes of the embed element
that have no namespace to the plugin used.
Any (namespace-less) attribute may be specified on the
embed element.

The embed element has no
fallback content . If the user agent can't
display the specified resource, e.g. because the given type is not
supported, then the user agent must use a default plugin for the
content. (This default could be as simple as saying "Unsupported
Format", of course.)

The type attribute, if present,
gives the MIME type of the linked resource. The value must be a
valid MIME type, optionally with parameters. [RFC2046]

The type of the
content being embedded is defined as follows:

If the element has a type attribute, then the value of the
type
attribute is the content's type .

Objects implementing the HTMLObjectElement interface must
also implement the EmbeddingElement interface defined
in the Window Object specification. [WINDOW]

Depending on the type of content instantiated by the
object element, the node may
also support other interfaces.

The object element can
represent an external resource, which, depending on the type of the
resource, will either be treated as an image, as a nested browsing context , or as an external resource to
be processed by a plugin .

The data attribute, if present,
specifies the address of the resource. If present, the attribute
must be a URI (or IRI).

The type attribute, if present,
specifies the type of the resource. If present, the attribute must
be a valid MIME type, optionally with parameters. [RFC2046]

When the element is created, and subsequently whenever the
classid attribute changes,
or, if the classid
attribute is not present, whenever the data attribute
changes, or, if neither classid attribute nor the data attribute are
present, whenever the type attribute changes, the user agent must run
the following steps to determine what the object element represents:

If the classid
attribute is present, and has a value that isn't the empty string,
then: if the user agent can find a plugin
suitable according to the value of the classid attribute, and plugins aren't being sandboxed , then
that pluginshould
be used , and the value of the data attribute, if
any, should be passed to the plugin . If no
suitable plugin can be found, or if the
plugin reports an error, jump to the last
step in the overall set of steps (fallback).

If the type attribute is present and its value is not
a type that the user agent supports, and is not a type that the
user agent can find a plugin for, then the
user agent may jump to the last step in the overall set of steps
(fallback) without downloading the content to examine its real
type.

If the resource is not yet available (e.g. because the resource
was not available in the cache, so that loading the resource
required making a request over the network), then jump to the last
step in the overall set of steps (fallback). When the resource
becomes available, or if the load fails, restart this algorithm
from this step. Resources can load incrementally; user agents may
opt to consider a resource "available" whenever enough data has
been obtained to begin processing the resource.

If the load failed (e.g. an HTTP 404 error, a DNS error),
fire an error
event at the element, then jump to the last step in the overall
set of steps (fallback).

If the resource type is unknown or "
application/octet-stream " and there is a
type
attribute present on the object
element, then change the resource type to
instead be the type specified in that type attribute.

(Fallback.) The object
element represents what the element's contents represent, ignoring
any leading param element
children. This is the element's fallback
content .

When the algorithm above instantiates a
plugin , the user agent should pass the names
and values of all the parameters given by param elements that are children of the
object element to the plugin used. If the plugin
supports a scriptable interface, the HTMLObjectElement object
representing the element should expose that interface. The plugin is not a nested browsing
context .

Due to the algorithm above, the contents of object elements act as fallback content , used only when referenced
resources can't be shown (e.g. because it returned a 404 error).
This allows multiple object
elements to be nested inside each other, targeting multiple user
agents with different capabilities, with the user agent picking the
first one it supports.

The usemap attribute, if present while the
object element represents an
image, can indicate that the object has an associated image map . The attribute must be ignored if the
object element doesn't represent
an image.

The DOM attributes data , type , name , and useMap each must
reflect the respective content attributes of
the same name.

In the following example, a Java applet is embedded in a page
using the object element.
(Generally speaking, it is better to avoid using applets like these
and instead use native JavaScript and HTML to provide the
functionality, since that way the application will work on all Web
browsers without requiring a third-party plugin. Many devices,
especially embedded devices, do not support third-party
technologies like Java.)

Content may be provided inside the video element. User agents should not show
this content to the user; it is intended for older Web browsers
which do not support video , so
that legacy video plugins can be tried, or to show text to the
users of these older browser informing them of how to access the
video contents.

In particular, this content is not fallback content intended to address
accessibility concerns. To make video content accessible to the
blind, deaf, and those with other physical or cognitive
disabilities, authors are expected to provide alternative media
streams and/or to embed accessibility aids (such as caption or
subtitle tracks) into their media streams.

The videoWidth DOM attribute
must return the native width of the video in CSS pixels. The
videoHeight DOM
attribute must return the native height of the video in CSS pixels.
In the absence of resolution information defining the mapping of
pixels in the video to physical dimensions, user agents may assume
that one pixel in the video corresponds to one CSS pixel. If no
video data is available, then the attributes must return 0.

When a video element is
paused at any other
position, the element represents the frame of video corresponding
to the current playback position , or, if
that is not yet available (e.g. because the video is seeking or
buffering), the last frame of the video to have been rendered.

When a video element is
neither actively playing nor paused (e.g. when seeking or
stalled), the element represents the last frame of the video to
have been rendered.

Which frame in a video stream corresponds to a
particular playback position is defined by the video stream's
format.

In addition to the above, the user agent may provide messages to
the user (such as "buffering", "no video loaded", "error", or more
detailed information) by overlaying text or icons on the video or
other areas of the element's playback area, or in another
appropriate manner.

User agents that cannot render the video may instead make the
element represent a link to an external video playback utility or
to the video data itself.

Video content should be rendered inside the element's playback
area such that the video content is shown centered in the playback
area at the largest possible size that fits completely within it,
with the video content's adjusted aspect
ratio being preserved. Thus, if the aspect ratio of the
playback area does not match the adjusted
aspect ratio of the video, the video will be shown letterboxed.
Areas of the element's playback area that do not contain the video
represent nothing.

The adjusted aspect ratio of a video is
the ratio of its intrinsic width to its intrinsic height. The
intrinsic height of a video is the height given by the resource
itself. If the video's pixel ratio override
's is none , then the video's intrinsic width is the width
given by the resource itself. If the video has a pixel ratio override other than none , then
the intrinsic width of the video is the width given by the resource
itself, divided by the pixel ratio given by the resource itself,
multiplied by the video's pixel ratio
override .

If the resource doesn't give an explicit height, then user
agents should assume that the height of each pixel of the video
data is exactly one CSS pixel. If the resource doesn't give an
explicit width, then user agents should assume that the width of
each pixel of the video data is exactly one CSS pixel multiplied by
the resource's pixel ratio. If the resource doesn't give an
explicit pixel ratio, then user agents should assume that the pixel
ratio is 1.0.

User agents may adjust the intrinsic height and width of the
video to ensure that each pixel of video data corresponds to at
least one device pixel, so long as this doesn't affect the adjusted aspect ratio (this is especially relevant
for pixel ratios that are less than 1.0).

The intrinsic height of a video element's playback area is the intrinsic
height of the video resource, if available, otherwise it is 150 CSS
pixels.

The intrinsic width of a video element's playback area is the intrinsic
width of the video resource, if available, otherwise it is 300 CSS
pixels.

The image given by the poster attribute
does not influence the element's intrinsic dimensions.

User agents should provide controls to enable or disable the
display of closed captions associated with the video stream, though
such features should, again, not interfere with the page's normal
rendering.

User agents may allow users to view the video content in manners
more suitable to the user (e.g. full-screen or in an independent
resizable window). As for the other user interface features,
controls to enable this should not interfere with the page's normal
rendering unless the user agent is exposing a user interface
. In such an independent context, however, user agents may make
full user interfaces visible, with, e.g., play, pause, seeking, and
volume controls, even if the controls
attribute is absent.

User agents may allow video playback to affect system features
that could interfere with the user's experience; for example, user
agents could disable screensavers while video playback is in
progress.

User agents should not provide a public API to
cause videos to be shown full-screen. A script, combined with a
carefully crafted video file, could trick the user into thinking a
system-modal dialog had been shown, and prompt the user for a
password. There is also the danger of "mere" annoyance, with pages
launching full-screen videos when links are clicked or pages
navigated. Instead, user-agent specific interface features may be
provided to easily allow the user to obtain a full-screen playback
mode.

The spec does not currently define the
interaction of the "controls" attribute with the "height" and
"width" attributes. This will likely be defined in the rendering
section based on implementation experience. So far, browsers seem
to be making the controls overlay-only, thus somewhat sidestepping
the issue.

User agents may support any video and audio codecs and container
formats.

It would be helpful for interoperability if
all browsers could support the same codecs. However, there are no
known codecs that satisfy all the current players: we need a codec
that is known to not require per-unit or per-distributor licensing,
that is compatible with the open source development model, that is
of sufficient quality as to be usable, and that is not an
additional submarine patent risk for large companies. This is an
ongoing issue and this section will be updated once more
information is available.

Content may be provided inside the audio element. User agents should not show
this content to the user; it is intended for older Web browsers
which do not support audio , so
that legacy audio plugins can be tried, or to show text to the
users of these older browser informing them of how to access the
audio contents.

In particular, this content is not fallback content intended to address
accessibility concerns. To make audio content accessible to the
deaf or to those with other physical or cognitive disabilities,
authors are expected to provide alternative media streams and/or to
embed accessibility aids (such as transcriptions) into their media
streams.

The src attribute gives the
address of the media resource . The value
must be a URI (or IRI). This attribute must be present.

The type attribute gives the type
of the media resource , to help the user
agent determine if it can play this media
resource before downloading it. Its value must be a MIME type.
The codecs parameter may be specified and
might be necessary to specify exactly how the resource is encoded.
[RFC2046][RFC4281]

The following list shows some examples of how to use the
codecs= MIME parameter in the type attribute.

The media attribute gives the
intended media type of the media resource ,
to help the user agent determine if this media
resource is useful to the user before downloading it. Its value
must be a valid media query . [MQ]

Either the type attribute, the media attribute or
both, must be specified, unless this is the last source element child of the parent
element.

The pixelratio attribute
allows the author to specify the pixel ratio of anamorphic media resources that do not
self-describe their pixel ratio. The attribute value, if specified,
must be a valid floating point number giving
the ratio of the correct rendered width of each pixel to the actual
width of each pixel in the image (i.e., the multiple by which the
video's intrinsic width is to be multiplied to obtain the rendered
width that gives the correct aspect ratio). The default value, if
the attribute is omitted or cannot be parsed, is 1.0.

The only way this default is used is in deciding
what number the pixelRatio DOM attribute will return if
the content attribute is omitted or cannot be parsed. If the
content attribute is omitted or cannot be parsed, then the user
agent doesn't adjust the intrinsic width of the video at all; the
intrinsic dimensions and the intrinsic pixel ratio of the video are
honoured.

If a source element is
inserted into a media element that is already
in a document and whose networkState is in the EMPTY state, the user
agent must implicitly invoke the load() method on the
media element as soon as all other scripts
have finished executing. Any exceptions raised must be ignored.

The DOM attributes src , type , and media must reflect the respective content attributes of the
same name.

Media elements are
used to present audio data, or video and audio data, to the user.
This is referred to as media data in this
section, since this section applies equally to media elements for audio or for video.
The term media resource is used to refer to
the complete set of media data, e.g. the complete video file, or
complete audio file.

3.11.10.1. Error
codes

All media elements
have an associated error status, which records the last error the
element encountered since the load() method was last invoked. The error
attribute, on getting, must return the MediaError object created for this last
error, or null if there has not been an error.

The code attribute of a
MediaError object must
return the code for the error, which must be one of the
following:

MEDIA_ERR_ABORTED
(numeric value 1)

The download of the media resource was
aborted by the user agent at the user's request.

MEDIA_ERR_NETWORK
(numeric value 2)

A network error of some description caused the user agent to
stop downloading the media resource .

MEDIA_ERR_DECODE
(numeric value 3)

An error of some description occurred while decoding the
media resource .

3.11.10.2. Location of
the media resource

The src
content attribute on media
elements gives the address of the media resource (video, audio)
to show. The attribute, if present, must contain a URI (or
IRI).

If the src attribute of a media
element that is already in a document and whose networkState is in the EMPTY state is added,
changed, or removed, the user agent must implicitly invoke the
load()
method on the media element as soon as all
other scripts have finished executing. Any exceptions raised must
be ignored.

If a src attribute is specified, the resource it
specifies is the media resource that will be
used. Otherwise, the resource specified by the first suitable
source element child of the
media element is the one used.

the candidate element has a type attribute and
that attribute's value, when parsed as a MIME type, does not
represent a type that the user agent can render (including any
codecs described by the codec parameter), or
[RFC2046][RFC4281]

the candidate element has a media attribute
and that attribute's value, when processed according to the rules
for media queries , does not match the current
environment, [MQ]

...then the candidate is not suitable; go to
the next step.

Otherwise, the address given in that candidate element's src attribute is the address of the media resource ; jump to the last step.

Let candidate be the next source element child in the media element , or null if there are no more such
children.

3.11.10.3. Network
states

As media elements
interact with the network, they go through several states. The
networkState attribute,
on getting, must return the current network state of the element,
which must be one of the following values:

EMPTY (numeric value 0)

The element has not yet been initialized. All attributes are in
their initial states.

Enough of the resource has been obtained that the metadata
attributes are initialized (e.g. the length is known). The API will
no longer raise exceptions when used.

LOADED_FIRST_FRAME
(numeric value 3)

Actual media data has been obtained. In
the case of video, this specifically means that a frame of video is
available and can be shown.

LOADED (numeric value 4)

The entire media resource has been
obtained and is available to the user agent locally. Network
connectivity could be lost without affecting the media
playback.

The algorithm for the load() method defined below describes exactly
when the networkState attribute changes
value.

3.11.10.4. Loading the
media resource

All media elements
have a begun flag , which must begin in the
false state, a loaded-first-frame
flag , which must begin in the false state, and an autoplaying flag , which must begin in the true
state.

When the load() method on a media element is invoked, the user agent must run the
following steps. Note that this algorithm might get aborted, e.g.
if the load() method itself is invoked again.

Any already-running instance of this algorithm for this element
must be aborted. If those method calls have not yet returned, they
must finish the step they are on, and then immediately return.

Playback of any previously playing media resource for this element stops.

If a download is in progress for the media
element , the user agent should stop the download.

The user agent must then begin to download the chosen media resource . The rate of the download may
be throttled, however, in response to user preferences (including
throttling it to zero until the user indicates that the download
can start), or to balance the download with other connections
sharing the same bandwidth.

While the download is progressing, the user agent must fire a progress event called progress at the
element every 350ms (±200ms) or for every byte received, whichever
is least frequent.

If at any point the user agent has received no data for more
than about three seconds, the user agent must fire a progress event called stalled at the
element.

User agents may allow users to selectively block or slow
media data downloads. When a media element 's download has been blocked, the user
agent must act as if it was stalled (as opposed to acting as if the
connection was closed).

The user agent may use whatever means necessary to download the
resource (within the constraints put forward by this and other
specifications); for example, reconnecting to the server in the
face of network errors, using HTTP partial range requests, or
switching to a streaming protocol. The user agent must consider a
resource erroneous only if it has given up trying to download
it.

If the media data cannot be downloaded at
all, due to network errors, causing the user agent to give up
trying to download the resource

DNS errors and HTTP 4xx and 5xx errors (and equivalents in other
protocols) must cause the user agent to execute the following
steps. User agents may also follow these steps in response to other
network errors of similar severity.

If the media data
can be downloaded but is in an unsupported format, or can otherwise
not be rendered at all

The server returning a file of the wrong kind (e.g. one that
that turns out to not be pure audio when the media element is an audio element), or the file using unsupported
codecs for all the data, must cause the user agent to execute the
following steps. User agents may also execute these steps in
response to other codec-related fatal errors, such as the file
requiring more resources to process than the user agent can provide
in real time.

The download is aborted by the user, e.g. because the user
navigated the browsing context to another page, the user agent must
execute the following steps. These steps are not followed if the
load()
method itself is reinvoked, as the steps above handle that
particular kind of abort.

The user agent should cancel the download.

The error attribute must be set to a new
MediaError object whose
code
attribute is set to MEDIA_ERR_ABORT .

If the media
data can be downloaded but has non-fatal errors or uses, in
part, codecs that are unsupported, preventing the user agent from
rendering the content completely correctly but not preventing
playback altogether

The server returning data that is partially usable but cannot be
optimally rendered must cause the user agent to execute the
following steps.

Should we fire a 'warning' event? Set the
'error' flag to 'MEDIA_ERR_SUBOPTIMAL' or something?

Once enough of the media data has been
downloaded to determine the duration of the media resource , its dimensions, and other
metadata

If a media element whose networkState has the value EMPTY is inserted
into a document, user agents must implicitly invoke the
load()
method on the media element as soon as all
other scripts have finished executing. Any exceptions raised must
be ignored.

The bufferingRate
attribute must return the average number of bits received per
second for the current download over the past few seconds. If there
is no download in progress, the attribute must return 0.

The bufferingThrottled
attribute must return true if the user agent is intentionally
throttling the bandwidth used by the download (including when
throttling to zero to pause the download altogether), and false
otherwise.

Typically this will be a single range anchored at
the zero point, but if, e.g. the user agent uses HTTP range
requests in response to seeking, then there could be multiple
ranges.

The bufferedBytes
attribute must return a static normalized
ByteRanges object that represents the ranges of
the media resource , if any, that the user
agent has buffered, at the time the attribute is evaluated.

The totalBytes attribute must
return the length of the media resource , in
bytes, if it is known and finite. If it is not known, is infinite
(e.g. streaming radio), or if no media data
is available, the attribute must return 0.

User agents may discard previously buffered data.

Thus, a time or byte position included within a
range of the objects return by the buffered or
bufferedBytes attributes at one time
can end up being not included in the range(s) of objects returned
by the same attributes at a later time.

3.11.10.5. Offsets into
the media resource

The duration attribute must
return the length of the media resource , in
seconds. If no media data is available, then
the attributes must return 0. If media data
is available but the length is not known, the attribute must return
the Not-a-Number (NaN) value. If the media
resource is known to be unbounded (e.g. a streaming radio),
then the attribute must return the positive Infinity value.

Media elements have
a current playback position , which must
initially be zero. The current position is a time.

The currentTime attribute
must, on getting, return the current playback
position , expressed in seconds. On setting, the user agent
must seek to the new
value (which might raise an exception).

The start content attribute gives
the offset into the media resource at which
playback is to begin. The default value is the default start
position of the media resource , or 0 if not
enough media data has been obtained yet to
determine the default start position or if the resource doesn't
specify a default start position.

The effective start is the
smaller of the start DOM attribute and the end of the
media resource .

The loopstart content
attribute gives the offset into the media
resource at which playback is to begin when looping a clip. The
default value of the loopstart content attribute is the value of
the start DOM attribute.

The loopend content attribute
gives an offset into the media resource at
which playback is to jump back to the loopstart ,
when looping the clip. The default value of the loopend content
attribute is the value of the end DOM attribute.

The effective loop end is
the greater of the start , loopStart ,
and loopEnd DOM attributes, except if that is
greater than the end of the media resource ,
in which case that's its value.

The end
content attribute gives an offset into the media
resource at which playback is to end. The default value is
infinity.

The effective end is the
greater of the start , loopStart ,
and end DOM attributes, except if that is
greater than the end of the media resource ,
in which case that's its value.

The currentLoop attribute
must initially have the value 0. It gives the index of the current
loop. It is changed during playback as described below.

When any of the start , loopStart ,
loopEnd , end , and playCount
DOM attributes change value (either through content attribute
mutations reflecting into the DOM attribute, or direct mutations of
the DOM attribute), the user agent must apply the following
steps:

If the playCount DOM attribute's value is less
than or equal to the currentLoop DOM attribute's value, then
the currentLoop DOM attribute's value must be
set to playCount -1 (which will make the
current loop the last loop).

3.11.10.6. The ready
states

Media elements have
a ready state , which describes to what degree they are
ready to be rendered at the current playback
position . The possible values are as follows; the ready state
of a media element at any particular time is the greatest value
describing the state of the element:

Data for the immediate current playback
position is available, but not enough data is available that
the user agent could successfully advance the current playback position at all without
immediately reverting to the DATA_UNAVAILABLE state. In video,
this corresponds to the user agent having data from the current
frame, but not the next frame. In audio, this corresponds to the
user agent only having audio up to the current
playback position , but no further.

The readyState DOM attribute
must, on getting, return the value described above that describes
the current ready state of the media element
.

The autoplay attribute is a
boolean attribute . When present, the
algorithm described herein will cause the user agent to
automatically begin playback of the media
resource as soon as it can do so without stopping.

The autoplay DOM attribute must
reflect the content attribute of the same
name.

3.11.10.7. Playing the
media resource

The paused attribute represents
whether the media element is paused or not.
The attribute must initially be true.

Media resources
might be internally scripted or interactive. Thus, a media element could play in a non-linear fashion. If
this happens, the user agent must act as if the algorithm for
seeking was used
whenever the current playback position
changes in a discontinuous fashion (so that the relevant events
fire).

The defaultPlaybackRate
attribute gives the desired speed at which the media resource is to play, as a multiple of its
intrinsic speed. The attribute is mutable, but on setting, if the
new value is 0.0, a NOT_SUPPORTED_ERR exception must
be raised instead of the value being changed. It must initially
have the value 1.0.

The playbackRate attribute
gives the speed at which the media resource
plays, as a multiple of its intrinsic speed. If it is not equal to
the defaultPlaybackRate , then the
implication is that the user is using a feature such as fast
forward or slow motion playback. The attribute is mutable, but on
setting, if the new value is 0.0, a NOT_SUPPORTED_ERR
exception must be raised instead of the value being changed.
Otherwise, the playback must change speed (if the element is
actively playing ). It must initially have
the value 1.0.

When the play() method on a media element is invoked, the user agent must run the
following steps.

If the media element 's networkState attribute has the value
EMPTY , then the user
agent must invoke the load() method and wait for it to return. If that
raises an exception, that exception must be reraised by the
play()
method.

If the fourth step above changed the value of paused , the user
agent must, after any running scripts have finished executing, and
after any other events triggered by this algorithm (specifically
timeupdate and ratechange )
have fired, fire a simple event called
play at the
element.

When the pause() method is invoked, the
user agent must run the following steps:

If the media element 's networkState attribute has the value
EMPTY , then the user
agent must invoke the load() method and wait for it to return. If that
raises an exception, that exception must be reraised by the
pause()
method.

Media elements that
are actively playing while not in a
Document must not play any video, but should
play any audio component. Media elements must not stop playing just
because all references to them have been removed; only once a media
element to which no references exist has reached a point where no
further audio remains to be played for that element (e.g. because
the element is paused or because the end of the clip has been
reached) may the element be garbage collected .

If the media element 's
ownerDocument stops being an
active document, then the playback will stop until the document is active again.

The played attribute must return
a static normalized TimeRanges
object that represents the ranges of the media resource , if any, that the user agent has so
far rendered, at the time the attribute is evaluated.

3.11.10.8. Seeking

The seeking attribute must
initially have the value false.

When the user agent is required to seek to a particular new
playback position in the media
resource , it means that the user agent must run the following
steps:

If the media element 's networkState is less than LOADED_METADATA , then the user agent
must raise an INVALID_STATE_ERR exception (if the seek
was in response to a DOM method call or setting of a DOM
attribute), and abort these steps.

If the (possibly now changed) new playback
position is not in one of the ranges given in the
seekable attribute, then the user agent must
raise an INDEX_SIZE_ERR exception (if the seek was in
response to a DOM method call or setting of a DOM attribute), and
abort these steps.

If, when it reaches this step, the user agent has still not
established whether or not the media data for
the new playback position is available, and, if
it is, decoded enough data to play back that position, the user
agent must fire a simple event called
seeking
at the element.

The user agent must wait until it has established whether or not
the media data for the new
playback position is available, and, if it is, until it has
decoded enough data to play back that position.

If the user agent can seek to anywhere in the
media resource , e.g. because it a simple
movie file and the user agent and the server support HTTP Range
requests, then the attribute would return an object with one range,
whose start is the time of the first frame (typically zero), and
whose end is the same as the time of the first frame plus the
duration attribute's value (which would
equal the time of the last frame).

3.11.10.9. Cue
ranges

Media elements have
a set of cue ranges .
Each cue range is made up of the following information:

A class name

A group of related ranges can be given the same class name so
that they can all be removed at the same time.

A start time

An end time

The actual time range, using the same timeline as the media resource itself.

The addCueRange( className , start , end , pauseOnExit , enterCallback , exitCallback
) method must, when called, add a cue range to the media
element , that cue range having the class name className , the start time start (in
seconds), the end time end (in seconds), the
"pause" boolean with the same value as pauseOnExit , the "enter" callback enterCallback , the "exit" callback exitCallback , and an "active" boolean that is true if the
current playback position is equal to or
greater than the start time and less than the end time, and false
otherwise.

The removeCueRanges( className ) method must, when called, remove
all the cue ranges of
the media element which have the class name
className .

When the current playback position of a
media element changes (e.g. due to playback
or seeking), the user agent must run the following steps. If the
current playback position changes while the
steps are running, then the user agent must wait for the steps to
complete, and then must immediately rerun the steps. (These steps
are thus run as often as possible or needed — if one
iteration takes a long time, this can cause certain ranges to be
skipped over as the user agent rushes ahead to "catch up".)

Let other ranges be an ordered list of
cue ranges ,
initialized to contain all the cue ranges of the media
element that are not present in current
ranges , in the order they were added to the element.

If none of the cue
ranges in current ranges have their
"active" boolean set to "false" (inactive) and none of the cue ranges in other ranges have their "active" boolean set to "true"
(active), then abort these steps.

If the time was reached through the usual monotonic increase of
the current playback position during normal playback, the user
agent must then fire a simple event called
timeupdate at the element. (In the other
cases, such as explicit seeks, relevant events get fired as part of
the overall process of changing the current playback position.)

If the time was reached through the usual monotonic increase of
the current playback position during normal playback, and there are
cue ranges in
other ranges that have both their "active"
boolean and their "pause" boolean set to "true", then immediately
act as if the element's pause() method had been invoked. (In the other
cases, such as explicit seeks, playback is not paused by exiting a
cue range, even if that cue range has its "pause" boolean set to
"true".)

Invoke all the non-null "exit" callbacks for all of the cue ranges in other ranges that have their "active" boolean set to
"true" (active), in list order.

Invoke all the non-null "enter" callbacks for all of the
cue ranges in
current ranges that have their "active" boolean
set to "false" (inactive), in list order.

Set the "active" boolean of all the cue ranges in the current
ranges list to "true" (active), and the "active" boolean of
all the cue ranges in
the other ranges list to "false"
(inactive).

The handleEvent
method of objects implementing the VoidCallback interface is the entry
point for the callback represented by the object.

3.11.10.10. User
interface

The controls attribute is a
boolean attribute . If the attribute is
present, or if the media element is without script , then the user agent should expose a user interface to the user . This user
interface should include features to begin playback, pause
playback, seek to an arbitrary position in the content (if the
content supports arbitrary seeking), change the volume, and show
the media content in manners more suitable to the user (e.g.
full-screen video or in an independent resizable window). Other
controls may also be made available.

If the attribute is absent, then the user agent should avoid
making a user interface available that could conflict with an
author-provided user interface. User agents may make the following
features available, however, even when the attribute is absent:

User agents may provide controls to affect playback of the media
resource (e.g. play, pause, seeking, and volume controls), but such
features should not interfere with the page's normal rendering. For
example, such features could be exposed in the media element 's context menu.

Where possible (specifically, for starting, stopping, pausing,
and unpausing playback, for muting or changing the volume of the
audio, and for seeking), user interface features exposed by the
user agent must be implemented in terms of the DOM API described
above, so that, e.g., all the same events fire.

The controls DOM attribute must
reflect the content attribute of the same
name.

The volume attribute must return
the playback volume of any audio portions of the media element , in the range 0.0 (silent) to 1.0
(loudest). Initially, the volume must be 0.5, but user agents may
remember the last set value across sessions, on a per-site basis or
otherwise, so the volume may start at other values. On setting, if
the new value is in the range 0.0 to 1.0 inclusive, the attribute
must be set to the new value and the playback volume must be
correspondingly adjusted as soon as possible after setting the
attribute, with 0.0 being silent, and 1.0 being the loudest
setting, values in between increasing in loudness. The range need
not be linear. The loudest setting may be lower than the system's
loudest possible setting; for example the user could have set a
maximum volume. If the new value is outside the range 0.0 to 1.0
inclusive, then, on setting, an INDEX_SIZE_ERR
exception must be raised instead.

The muted attribute must return
true if the audio channels are muted and false otherwise. On
setting, the attribute must be set to the new value; if the new
value is true, audio playback for this media
resource must then be muted, and if false, audio playback must
then be enabled.

The length DOM attribute
must return the number of ranges represented by the object.

The start(
index ) method must return the
position of the first byte of the index th
range represented by the object.

The end(
index ) method must return the
position of the byte immediately after the last byte of the
index th range represented by the object. (The
byte position returned by this method is not in the range itself.
If the first byte of the range is the byte at position 0, and the
entire stream of bytes is in the range, then the value of the
position of the byte returned by this method for that range will be
the same as the number of bytes in the stream.)

These methods must raise INDEX_SIZE_ERR exceptions
if called with an index argument greater than
or equal to the number of ranges represented by the object.

When a ByteRanges object
is said to be a normalized
ByteRanges object , the ranges it represents
must obey the following criteria:

The start of a range must be greater than the end of all
earlier ranges.

The start of a range must be less than the end of that same
range.

In other words, the ranges in such an object are ordered, don't
overlap, aren't empty, and don't touch (adjacent ranges are folded
into one bigger range).

3.11.10.13. Event
summary

The following events fire on media elements as part of the processing model
described above:

error is an object with the code MEDIA_ERR_NETWORK_ERROR
or higher. networkState equals either EMPTY or LOADED , depending
on when the download was aborted.

emptied

Event

A media element whose networkState was previously not in the
EMPTY
state has just switched to that state (either because of a fatal
error during load that's about to be reported, or because the
load()
method was reinvoked, in which case it is fired synchronously
during the load() method call).

The user agent can resume playback of the media data , but estimates that if playback were to
be started now, the media resource could not
be rendered at the current playback rate up to its end without
having to stop for further buffering of content.

Either the volume attribute or the muted attribute has
changed. Fired after the relevant attribute's setter has
returned.

3.11.10.14. Security
and privacy considerations

Talk about making sure interactive media files
(e.g. SVG) don't have access to the container DOM (XSS potential);
talk about not exposing any sensitive data like metadata from
tracks in the media files (intranet snooping risk)

The canvas element represents
a resolution-dependent bitmap canvas, which can be used for
rendering graphs, game graphics, or other visual images on the
fly.

Authors should not use the canvas element in a document when a more
suitable element is available. For example, it is inappropriate to
use a canvas element to render a
page heading: if the desired presentation of the heading is
graphically intense, it should be marked up using appropriate
elements (typically h1 ) and then
styled using CSS and supporting technologies such as XBL.

When authors use the canvas
element, they should also provide content that, when presented to
the user, conveys essentially the same function or purpose as the
bitmap canvas. This content may be placed as content of the
canvas element. The contents of
the canvas element, if any, are
the element's fallback content .

In interactive visual media, if the canvas element is with
script , the canvas element
represents an embedded element with a dynamically created
image.

In non-interactive, static, visual media, if the canvas element has been previously painted on
(e.g. if the page was viewed in an interactive visual medium and is
now being printed, or if some script that ran during the page
layout process painted on the element), then the canvas element represents embedded content with the current image and size.
Otherwise, the element represents its fallback
content instead.

The canvas element has two
attributes to control the size of the coordinate space: width and
height . These attributes,
when specified, must have values that are valid non-negative integers . The
rules for parsing non-negative integers must
be used to obtain their numeric values. If an attribute is missing,
or if parsing its value returns an error, then the default value
must be used instead. The width attribute defaults to 300, and the
height attribute defaults to 150.

The intrinsic dimensions of the canvas element equal the size of the
coordinate space, with the numbers interpreted in CSS pixels.
However, the element can be sized arbitrarily by a style sheet.
During rendering, the image is scaled to fit this layout size.

The size of the coordinate space does not necessarily represent
the size of the actual bitmap that the user agent will use
internally or during rendering. On high-definition displays, for
instance, the user agent may internally use a bitmap with two
device pixels per unit in the coordinate space, so that the
rendering remains at high quality throughout.

Whenever the width and height
attributes are set (whether to a new value or to the previous
value), the bitmap and any associated contexts must be cleared back
to their initial state and reinitialized with the newly specified
coordinate space dimensions.

The width and height DOM attributes
must reflect the content attributes of the
same name.

When the canvas is initialized it must be set to fully
transparent black.

To draw on the canvas, authors must first obtain a reference to
a context using the getContext( contextId ) method of the canvas element.

This specification only defines one context, with the name "
2d ". If
getContext() is called with that exact
string for its contextId argument, then the UA
must return a reference to an object implementing CanvasRenderingContext2D .
Other specifications may define their own contexts, which would
return different objects.

When the UA is passed an empty string or a string specifying a
context that it does not support, then it must return null. String
comparisons must be literal and case-sensitive.

Arguments other than the contextId must be
ignored, and must not cause the user agent to raise an exception
(as would normally occur if a method was called with the wrong
number of arguments).

A future version of this specification will
probably define a 3d context (probably based on the
OpenGL ES API).

The toDataURL() method must,
when called with no arguments, return a data:
URI containing a representation of the image as a PNG file.
[PNG] .

If the canvas has no pixels (i.e. either its horizontal
dimension or its vertical dimension is zero) then the method must
return the string " data:, ". (This is the
shortest data: URI; it represents the empty
string in a text/plain resource.)

The toDataURL( type ) method (when called with one or
more arguments) must return a data: URI
containing a representation of the image in the format given by
type . The possible values are MIME types with
no parameters, for example image/png ,
image/jpeg , or even maybe image/svg+xml
if the implementation actually keeps enough information to reliably
render an SVG image from the canvas.

Only support for image/png is required. User agents
may support other types. If the user agent does not support the
requested type, it must return the image using the PNG format.

User agents must convert the provided type to lower case before
establishing if they support that type and before creating the
data: URI.

When trying to use types other than
image/png , authors can check if the image was really
returned in the requested format by checking to see if the returned
string starts with one the exact strings " data:image/png, " or " data:image/png; ". If it does, the image is PNG, and thus
the requested type was not supported. (The one exception to this is
if the canvas has either no height or no width, in which case the
result might simply be " data:, ".)

Arguments other than the type must be
ignored, and must not cause the user agent to raise an exception
(as would normally occur if a method was called with the wrong
number of arguments). A future version of this specification will
probably allow extra parameters to be passed to toDataURL()
to allow authors to more carefully control compression settings,
image metadata, etc.

The 2D context represents a flat Cartesian surface whose origin
(0,0) is at the top left corner, with the coordinate space having
x values increasing when going right, and
y values increasing when going down.

The current path and the current bitmap are not
part of the drawing state. The current path is persistent, and can
only be reset using the beginPath() method. The current bitmap is
a property of the canvas
, not the context.

The save() method must push a
copy of the current drawing state onto the drawing state stack.

The restore() method must
pop the top entry in the drawing state stack, and reset the drawing
state it describes. If there is no saved state, the method must do
nothing.

3.11.11.1.2.Transformations

The transformation matrix is applied to coordinates when
creating shapes and paths.

When the context is created, the transformation matrix must
initially be the identity transform. It may then be adjusted using
the transformation methods.

The transformations must be performed in reverse order. For
instance, if a scale transformation that doubles the width is
applied, followed by a rotation transformation that rotates drawing
operations by a quarter turn, and a rectangle twice as wide as it
is tall is then drawn on the canvas, the actual result will be a
square.

The scale(
x , y ) method
must add the scaling transformation described by the arguments to
the transformation matrix. The x argument
represents the scale factor in the horizontal direction and the
y argument represents the scale factor in the
vertical direction. The factors are multiples.

The rotate(
angle ) method must add the
rotation transformation described by the argument to the
transformation matrix. The angle argument
represents a clockwise rotation angle expressed in radians. If the
angle argument is infinite, the method call
must be ignored.

The translate( x ,
y ) method must add the
translation transformation described by the arguments to the
transformation matrix. The x argument
represents the translation distance in the horizontal direction and
the y argument represents the translation
distance in the vertical direction. The arguments are in coordinate
space units.

3.11.11.1.3.
Compositing

The globalAlpha
attribute gives an alpha value that is applied to shapes and images
before they are composited onto the canvas. The value must be in
the range from 0.0 (fully transparent) to 1.0 (no additional
transparency). If an attempt is made to set the attribute to a
value outside this range, the attribute must retain its previous
value. When the context is created, the globalAlpha attribute must initially have
the value 1.0.

The globalCompositeOperation
attribute sets how shapes and images are drawn onto the existing
bitmap, once they have had globalAlpha and the current
transformation matrix applied. It must be set to a value from the
following list. In the descriptions below, the source image,
A , is the shape or image being rendered, and
the destination image, B , is the current state
of the bitmap.

source-atop

A atop B . Display the
source image wherever both images are opaque. Display the
destination image wherever the destination image is opaque but the
source image is transparent. Display transparency elsewhere.

source-in

A in B . Display the
source image wherever both the source image and destination image
are opaque. Display transparency elsewhere.

source-out

A out B . Display the
source image wherever the source image is opaque and the
destination image is transparent. Display transparency
elsewhere.

source-over (default)

A over B . Display the
source image wherever the source image is opaque. Display the
destination image elsewhere.

destination-atop

B atop A . Same as
source-atop but using the destination
image instead of the source image and vice versa.

destination-in

B in A . Same as
source-in but using the destination image
instead of the source image and vice versa.

destination-out

B out A . Same as
source-out but using the destination image
instead of the source image and vice versa.

destination-over

B over A . Same as
source-over but using the destination
image instead of the source image and vice versa.

lighter

A plus B . Display the
sum of the source image and destination image, with color values
approaching 1 as a limit.

copy

A ( B is ignored).
Display the source image instead of the destination image.

xor

A xor B . Exclusive OR
of the source image and destination image.

vendorName - operationName

Vendor-specific extensions to the list of composition operators
should use this syntax.

These values are all case-sensitive — they must be used
exactly as shown. User agents must not recognize values that do not
exactly match the values given above.

The operators in the above list must be treated as described by
the Porter-Duff operator given at the start of their description
(e.g. A over B ). [PORTERDUFF]

On setting, if the user agent does not recognize the specified
value, it must be ignored, leaving the value of globalCompositeOperation
unaffected.

On getting, if the value is a color, then the serialization of
the color must be returned. Otherwise, if it is not a color but
a CanvasGradient or
CanvasPattern , then the
respective object must be returned. (Such objects are opaque and
therefore only useful for assigning to other attributes or for
comparison to other gradients or patterns.)

The serialization of a color for a
color value is a string, computed as follows: if it has alpha equal
to 1.0, then the string is a lowercase six-digit hex value,
prefixed with a "#" character (U+0023 NUMBER SIGN), with the first
two digits representing the red component, the next two digits
representing the green component, and the last two digits
representing the blue component, the digits being in the range 0-9
a-f (U+0030 to U+0039 and U+0061 to U+0066). Otherwise, the color
value has alpha less than 1.0, and the string is the color value in
the CSS rgba() functional-notation format:
the literal string rgba (U+0072 U+0067 U+0062
U+0061) followed by a U+0028 LEFT PARENTHESIS, a base-ten integer
in the range 0-255 representing the red component (using digits
0-9, U+0030 to U+0039, in the shortest form possible), a literal
U+002C COMMA and U+0020 SPACE, an integer for the green component,
a comma and a space, an integer for the blue component, another
comma and space, a U+0030 DIGIT ZERO, a U+002E FULL STOP
(representing the decimal point), one or more digits in the range
0-9 (U+0030 to U+0039) representing the fractional part of the
alpha value, and finally a U+0029 RIGHT PARENTHESIS.

When the context is created, the strokeStyle and fillStyle attributes must initially have
the string value #000000 .

There are two types of gradients, linear gradients and radial
gradients, both represented by objects implementing the opaque
CanvasGradient
interface.

Once a gradient has been created (see below), stops are placed
along it to define how the colors are distributed along the
gradient. The color of the gradient at each stop is the color
specified for that stop. Between each such stop, the colors and the
alpha component must be linearly interpolated over the RGBA space
without premultiplying the alpha value to find the color to use at
that offset. Before the first stop, the color must be the color of
the first stop. After the last stop, the color must be the color of
the last stop. When there are no stops, the gradient is transparent
black.

The addColorStop( offset , color ) method
on the CanvasGradient
interface adds a new stop to a gradient. If the offset is less than 0, greater than 1, infinite, or NaN,
then an INDEX_SIZE_ERR exception must be raised. If
the color cannot be parsed as a CSS color, then
a SYNTAX_ERR exception must be raised. Otherwise, the
gradient must have a new stop placed, at offset offset relative to the whole gradient, and with the color
obtained by parsing color as a CSS
<color> value. If multiple stops are added at the same offset
on a gradient, they must be placed in the order added, with the
first one closest to the start of the gradient, and each subsequent
one infinitesimally further along towards the end point (in effect
causing all but the first and last stop added at each point to be
ignored).

The createLinearGradient(
x0 , y0 , x1 , y1 ) method takes
four arguments that, after being subjected to the current
transformation matrix , represent the start point ( x0 , y0 ) and end point ( x1 , y1 ) of the gradient. If any of
the arguments to createLinearGradient() are
infinite or NaN, the method must raise an
INDEX_SIZE_ERR exception. Otherwise, the method must
return a linear CanvasGradient initialized with the
specified line.

Linear gradients must be rendered such that at and before the
starting point on the canvas the color at offset 0 is used, that at
and after the ending point the color at offset 1 is used, and that
all points on a line perpendicular to the line that crosses the
start and end points have the color at the point where those two
lines cross (with the colors coming from the interpolation
described above).

The createRadialGradient(
x0 , y0 , r0 , x1 , y1 ,
r1 ) method takes six arguments,
the first three representing the start circle with origin (
x0 , y0 ) and radius
r0 , and the last three representing the end
circle with origin ( x1 , y1 ) and radius r1 . The values are in
coordinate space units. If either of r0 or
r1 are negative, or if any of the arguments are
infinite or NaN, an INDEX_SIZE_ERR exception must be
raised. Otherwise, the method must return a radial CanvasGradient initialized with the
two specified circles, after transforming them according to the
current transformation matrix
.

Let the color at ω be the color of the
gradient at offset 0.0 for all values of ω less than 0.0, the color at offset 1.0 for all
values of ω greater than 1.0, and the
color at the given offset for values of ω
in the range 0.0 ≤ ω
≤ 1.0

For all values of ω where r(
ω ) > 0 , starting
with the value of ω nearest to positive
infinity and ending with the value of ω
nearest to negative infinity, draw the circumference of the circle
with radius r( ω ) at
position ( x( ω ) , y(
ω ) ), with the color at
ω , but only painting on the parts of the
canvas that have not yet been painted on by earlier circles in this
step for this rendering of the gradient.

This effectively creates a cone, touched by the two
circles defined in the creation of the gradient, with the part of
the cone before the start circle (0.0) using the color of the first
offset, the part of the cone after the end circle (1.0) using the
color of the last offset, and areas outside the cone untouched by
the gradient (transparent black).

Gradients must be painted only where the relevant stroking or
filling effects requires that they be drawn.

Patterns are represented by objects implementing the opaque
CanvasPattern
interface.

To create objects of this type, the createPattern(
image , repetition
) method is used. The first argument gives the image
to use as the pattern (either an HTMLImageElement or an
HTMLCanvasElement ).
Modifying this image after calling the createPattern() method must not affect
the pattern. The second argument must be a string with one of the
following values: repeat , repeat-x , repeat-y , no-repeat . If the empty string or null is specified,
repeat must be assumed. If an unrecognized
value is given, then the user agent must raise a
SYNTAX_ERR exception. User agents must recognize the
four values described above exactly (e.g. they must not do case
folding). The method must return a CanvasPattern object suitably
initialized.

The image argument must be an instance of an
HTMLImageElement or
HTMLCanvasElement .
If the image is of the wrong type or null, the
implementation must raise a TYPE_MISMATCH_ERR
exception.

If the image argument is an HTMLImageElement object whose
complete attribute is false, then the
implementation must raise an INVALID_STATE_ERR
exception.

If the image argument is an HTMLCanvasElement object with
either a horizontal dimension or a vertical dimension equal to
zero, then the implementation must raise an
INVALID_STATE_ERR exception.

Patterns must be painted so that the top left of the first image
is anchored at the origin of the coordinate space, and images are
then repeated horizontally to the left and right (if the
repeat-x string was specified) or vertically up and
down (if the repeat-y string was specified) or in all
four directions all over the canvas (if the repeat
string was specified). The images are not scaled by this process;
one CSS pixel of the image must be painted on one coordinate space
unit. Of course, patterns must actually be painted only where the
stroking or filling effect requires that they be drawn, and are
affected by the current transformation matrix.

When the createPattern() method is passed, as
its image argument, an animated image, the
poster frame of the animation, or the first frame of the animation
if there is no poster frame, must be used.

Support for patterns is optional. If the user agent doesn't
support patterns, then createPattern() must return null.

3.11.11.1.5. Line
styles

The lineWidth attribute
gives the width of lines, in coordinate space units. On setting,
zero, negative, infinite, and NaN values must be ignored, leaving
the value unchanged.

When the context is created, the lineWidth attribute must initially have the
value 1.0 .

The lineCap attribute
defines the type of endings that UAs will place on the end of
lines. The three valid values are butt ,
round , and square . The
butt value means that the end of each line is a flat
edge perpendicular to the direction of the line. The
round value means that a semi-circle with the diameter
equal to the width of the line must then be added on to the end of
the line. The square value means that a rectangle with
the length of the line width and the width of half the line width,
placed flat against the edge perpendicular to the direction of the
line, must be added at the end of each line. On setting, any other
value than the literal strings butt ,
round , and square must be ignored,
leaving the value unchanged.

When the context is created, the lineCap
attribute must initially have the value butt .

The lineJoin attribute
defines the type of corners that UAs will place where two lines
meet. The three valid values are bevel ,
round , and miter .

On setting, any other value than the literal strings
bevel , round , and miter
must be ignored, leaving the value unchanged.

When the context is created, the lineJoin
attribute must initially have the value miter .

A join exists at any point in a subpath shared by two
consecutive lines. When a subpath is closed, then a join also
exists at its first point (equivalent to its last point) connecting
the first and last lines in the subpath.

In addition to the point where the join occurs, two additional
points are relevant to each join, one for each line: the two
corners found half the line width away from the join point, one
perpendicular to each line, each on the side furthest from the
other line.

A filled triangle connecting these two opposite corners with a
straight line, with the third point of the triangle being the join
point, must be rendered at all joins. The lineJoin
attribute controls whether anything else is rendered. The three
aforementioned values have the following meanings:

The bevel value means that this is all that is
rendered at joins.

The round value means that a filled arc connecting
the two aforementioned corners of the join, abutting (and not
overlapping) the aforementioned triangle, with the diameter equal
to the line width and the origin at the point of the join, must be
rendered at joins.

The miter value means that a second filled triangle
must (if it can given the miter length) be rendered at the join,
with one line being the line between the two aforementioned
corners, abutting the first triangle, and the other two being
continuations of the outside edges of the two joining lines, as
long as required to intersect without going over the miter
length.

The miter length is the distance from the point where the lines
touch on the inside of the join to the intersection of the line
edges on the outside of the join. The miter limit ratio is the
maximum allowed ratio of the length of the two continuation lines
to the line width. If the miter length would be exceeded, this
second triangle must not be rendered.

The miter limit ratio can be explicitly set using the miterLimit
attribute. On setting, zero, negative, infinite, and NaN values
must be ignored, leaving the value unchanged.

When the context is created, the miterLimit attribute must initially have
the value 10.0 .

3.11.11.1.6.Shadows

All drawing operations are affected by the four global shadow
attributes.

The shadowColor
attribute sets the color of the shadow.

When the context is created, the shadowColor attribute initially must be
fully-transparent black.

On setting, the new value must be parsed as a CSS <color>
value and the color assigned. If the value is not a valid color,
then it must be ignored, and the attribute must retain its previous
value. [CSS3COLOR]

The shadowOffsetX and
shadowOffsetY
attributes specify the distance that the shadow will be offset in
the positive horizontal and positive vertical distance
respectively. Their values are in coordinate space units. They are
not affected by the current transformation matrix.

When the context is created, the shadow offset attributes
initially have the value 0 .

On getting, they must return their current value. On setting,
the attribute being set must be set to the new value, except if the
value is infinite or NaN, in which case the new value must be
ignored.

The shadowBlur attribute
specifies the size of the blurring effect. (The units do not map to
coordinate space units, and are not affected by the current
transformation matrix.)

When the context is created, the shadowBlur attribute must initially have
the value 0 .

On getting, the attribute must return its current value. On
setting the attribute must be set to the new value, except if the
value is negative, infinite or NaN, in which case the new value
must be ignored.

Support for shadows is optional. When they are supported, then,
when shadows are drawn, they must be rendered as follows:

Let A be the source image for which a shadow
is being created.

Let B be an infinite transparent black
bitmap, with a coordinate space and an origin identical to
A .

Copy the alpha channel of A to B , offset by shadowOffsetX in the positive
x direction, and shadowOffsetY in the positive
y direction.

If shadowBlur is less than 8, let σ be half the value of shadowBlur ; otherwise, let σ be the square root of multiplying the value of
shadowBlur by 2.

Perform a 2D Gaussian Blur on B , using
σ as the standard deviation.

User agents may limit values of σ to
an implementation-specific maximum value to avoid exceeding
hardware limitations during the Gaussian blur operation.

Set the red, green, and blue components of every pixel in
B to the red, green, and blue components
(respectively) of the color of shadowColor .

Multiply the alpha component of every pixel in B by the alpha component of the color of shadowColor .

The shadow is in the bitmap B , and is
rendered as part of the drawing model described below.

3.11.11.1.7. Simple
shapes (rectangles)

There are three methods that immediately draw rectangles to the
bitmap. They each take four arguments; the first two give the
x and y coordinates of the
top left of the rectangle, and the second two give the width
w and height h of the
rectangle, respectively.

The current transformation matrix
must be applied to the following four coordinates, which form the
path that must then be closed to get the specified rectangle:
( x , y ) ,
( x + w
, y ) , ( x + w , y + h ) , (
x , y + h ) .

The clearRect( x ,
y , w , h ) method must clear the pixels in the
specified rectangle that also intersect the current clipping region
to a fully transparent black, erasing any previous image. If either
height or width are zero, this method has no effect.

The fillRect( x ,
y , w , h ) method must paint the specified
rectangular area using the fillStyle . If either height or width are
zero, this method has no effect.

The strokeRect( x
, y , w , h ) method must stroke the specified
rectangle's path using the strokeStyle , lineWidth , lineJoin ,
and (if appropriate) miterLimit attributes. If both height and
width are zero, this method has no effect, since there is no path
to stroke (it's a point). If only one of the two is zero, then the
method will draw a line instead (the path for the outline is just a
straight line along the non-zero dimension).

3.11.11.1.8. Complex
shapes (paths)

The context always has a current path. There is only one current
path, it is not part of the drawing
state .

A path has a list of zero or more subpaths.
Each subpath consists of a list of one or more points, connected by
straight or curved lines, and a flag indicating whether the subpath
is closed or not. A closed subpath is one where the last point of
the subpath is connected to the first point of the subpath by a
straight line. Subpaths with fewer than two points are ignored when
painting the path.

The beginPath() method
must empty the list of subpaths so that the context once again has
zero subpaths.

The moveTo(
x , y ) method
must create a new subpath with the specified point as its first
(and only) point.

The closePath() method
must do nothing if the context has no subpaths. Otherwise, it must
mark the last subpath as closed, create a new subpath whose first
point is the same as the previous subpath's first point, and
finally add this new subpath to the path. (If the last subpath had
more than one point in its list of points, then this is equivalent
to adding a straight line connecting the last point back to the
first point, thus "closing" the shape, and then repeating the last
moveTo() call.)

New points and the lines connecting them are added to subpaths
using the methods described below. In all cases, the methods only
modify the last subpath in the context's paths.

The lineTo(
x , y ) method
must do nothing if the context has no subpaths. Otherwise, it must
connect the last point in the subpath to the given point (
x , y ) using a straight
line, and must then add the given point ( x ,
y ) to the subpath.

The quadraticCurveTo(
cpx , cpy , x , y ) method must do
nothing if the context has no subpaths. Otherwise it must connect
the last point in the subpath to the given point ( x , y ) using a quadratic Bézier curve
with control point ( cpx , cpy ), and must then add the given point ( x , y ) to the subpath. [BEZIER]

The bezierCurveTo( cp1x , cp1y , cp2x
, cp2y , x , y ) method must do nothing if the context has
no subpaths. Otherwise, it must connect the last point in the
subpath to the given point ( x , y ) using a cubic Bézier curve with control points (
cp1x , cp1y ) and (
cp2x , cp2y ). Then, it
must add the point ( x , y
) to the subpath. [BEZIER]

The arcTo(
x1 , y1 , x2 , y2 , radius
) method must do nothing if the context has no
subpaths. If the context does have a subpath, then the
behavior depends on the arguments and the last point in the
subpath.

Negative values for radius must cause the
implementation to raise an INDEX_SIZE_ERR
exception.

Let the point ( x0 , y0
) be the last point in the subpath.

If the point ( x0 , y0 )
is equal to the point ( x1 , y1 ), or if the point ( x1 ,
y1 ) is equal to the point ( x2 , y2 ), then the method must add
the point ( x1 , y1 ) to
the subpath, and connect that point to the previous point (
x0 , y0 ) by a straight
line.

Otherwise, if the points ( x0 , y0 ), ( x1 , y1 ),
and ( x2 , y2 ) all lie on
a single straight line, then: if the direction from ( x0 , y0 ) to ( x1
, y1 ) is the same as the direction from (
x1 , y1 ) to ( x2 , y2 ), then method must add the
point ( x1 , y1 ) to the
subpath, and connect that point to the previous point ( x0 , y0 ) by a straight line;
otherwise, the direction from ( x0 ,
y0 ) to ( x1 , y1 ) is the opposite of the direction from ( x1 , y1 ) to ( x2
, y2 ), and the method must add a point (
x ∞ , y
∞ ) to the subpath, and connect that point
to the previous point ( x0 , y0 ) by a straight line, where ( x
∞ , y ∞
) is the point that is infinitely far away from ( x1 , y1 ), that lies on the same line
as ( x0 , y0 ), (
x1 , y1 ), and (
x2 , y2 ), and that is on
the same side of ( x1 , y1
) on that line as ( x2 , y2
).

Otherwise, let The Arc be the shortest arc
given by circumference of the circle that has radius radius , and that has one point tangent to the
half-infinite line that crosses the point ( x0
, y0 ) and ends at the point ( x1 , y1 ), and that has a different
point tangent to the half-infinite line that ends at the point (
x1 , y1 ) and crosses the
point ( x2 , y2 ). The
points at which this circle touches these two lines are called the
start and end tangent points respectively.

The method must connect the point ( x0 ,
y0 ) to the start tangent point by a straight
line, adding the start tangent point to the subpath, and then must
connect the start tangent point to the end tangent point by
The Arc , adding the end tangent point to the
subpath.

The arc(
x , y , radius , startAngle , endAngle , anticlockwise
) method draws an arc. If the context has any
subpaths, then the method must add a straight line from the last
point in the subpath to the start point of the arc. In any case, it
must draw the arc between the start point of the arc and the end
point of the arc, and add the start and end points of the arc to
the subpath. The arc and its start and end points are defined as
follows:

Consider a circle that has its origin at ( x
, y ) and that has radius radius . The points at startAngle and
endAngle along the circle's circumference,
measured in radians clockwise from the positive x-axis, are the
start and end points respectively. The arc is the path along the
circumference of this circle from the start point to the end point,
going anti-clockwise if the anticlockwise
argument is true, and clockwise otherwise. Since the points are on
the circle, as opposed to being simply angles from zero, the arc
can never cover an angle greater than 2π radians. If the two
angles are equal, or if the radius is zero, then the arc is defined
as being of zero length in both directions.

Negative values for radius must cause the
implementation to raise an INDEX_SIZE_ERR
exception.

The rect(
x , y , w , h ) method must
create a new subpath containing just the four points ( x , y ), ( x +
w , y ), ( x + w , y +
h ), ( x , y + h ), with those four points
connected by straight lines, and must then mark the subpath as
closed. It must then create a new subpath with the point (
x , y ) as the only point
in the subpath.

The fill() method must fill
all the subpaths of the current path, using fillStyle , and using the non-zero winding
number rule. Open subpaths must be implicitly closed when being
filled (without affecting the actual subpaths).

Thus, if two overlapping but otherwise independent
subpaths have opposite windings, they cancel out and result in no
fill. If they have the same winding, that area just gets painted
once.

The stroke() method must
calculate the strokes of all the subpaths of the current path,
using the lineWidth , lineCap ,
lineJoin , and (if appropriate) miterLimit attributes, and then fill the
combined stroke area using the strokeStyle , attribute.

Since the subpaths are all stroked as one,
overlapping parts of the paths in one stroke operation are treated
as if their union was what was painted.

Zero-length line segments must be pruned before stroking a path.
Empty subpaths must be ignored.

The clip() method must create
a new clipping region by calculating the
intersection of the current clipping region and the area described
by the current path, using the non-zero winding number rule. Open
subpaths must be implicitly closed when computing the clipping
region, without affecting the actual subpaths. The new clipping
region replaces the current clipping region.

When the context is initialized, the clipping region must be set
to the rectangle with the top left corner at (0,0) and the width
and height of the coordinate space.

The isPointInPath( x , y ) method must
return true if the point given by the x and
y coordinates passed to the method, when
treated as coordinates in the canvas coordinate space unaffected by
the current transformation, is inside the current path; and must
return false otherwise. Points on the path itself are considered to
be inside the path. If either of the arguments is infinite or NaN,
then the method must return false.

3.11.11.1.9. Text

The font DOM attribute, on
setting, must be parsed the same way as the 'font' property of CSS
(but without supporting property-independent stylesheet syntax like
'inherit'), and the resulting font must be assigned to the context,
with the 'line-height' component forced to 'normal'. [CSS]

Font names must be interpreted in the context of the
canvas element's stylesheets;
any fonts embedded using @font-face must
therefore be available. [CSSWEBFONTS]

Only vector fonts should be used by the user agent; if a user
agent were to use bitmap fonts then transformations would likely
make the font look very ugly.

On getting, the font attribute must return the serialized form
of the current font of the context. [CSSOM]

When the context is created, the font of the context must be set
to 10px sans-serif. When the 'font-size' component is set to
lengths using percentages, 'em' or 'ex' units, or the 'larger' or
'smaller' keywords, these must be interpreted relative to the
computed value of the 'font-size' property of the corresponding
canvas element. When the
'font-weight' component is set to the relative values 'bolder' and
'lighter', these must be interpreted relative to the computed value
of the 'font-weight' property of the corresponding canvas element. If the computed values are
undefined for a particular case (e.g. because the canvas element is not in a document), then the
relative keywords must be interpreted relative to the normal-weight
10px sans-serif default.

The textAlign DOM
attribute, on getting, must return the current value. On setting,
if the value is one of start , end , left , right , or center , then the value
must be changed to the new value. Otherwise, the new value must be
ignored. When the context is created, the textAlign attribute must initially have the
value start .

The textBaseline DOM
attribute, on getting, must return the current value. On setting,
if the value is one of top ,
hanging , middle , alphabetic , ideographic , or bottom , then the value must be changed to the
new value. Otherwise, the new value must be ignored. When the
context is created, the textBaseline attribute must initially
have the value alphabetic .

The textBaseline attribute's allowed
keywords correspond to alignment points in the font:

The keywords map to these alignment points as follows:

top

The top of the em square

hanging

The hanging baseline

middle

The middle of the em square

alphabetic

The alphabetic baseline

ideographic

The ideographic baseline

bottom

The bottom of the em square

The fillText() and
strokeText() methods
take three or four arguments, text ,
x , y , and optionally
maxWidth , and render the given text at the given ( x , y ) coordinates ensuring that the text isn't wider than
maxWidth if specified, using the current
font ,
textAlign , and textBaseline values. Specifically, when
the methods are called, the user agent must run the following
steps:

Let font be the current font of the browsing
context, as given by the font attribute.

Form a hypothetical infinitely wide CSS line box containing a
single inline box containing the text text ,
with all the properties at their initial values except the 'font'
property of the inline element set to font and
the 'direction' property of the inline element set to the
'direction' property of the canvas element. [CSS]

If the maxWidth argument was specified and
the hypothetical width of the inline box in the hypothetical line
box is greater than maxWidth CSS pixels, then
change font to have a more condensed font (if
one is available or if a reasonably readable one can be synthesized
by applying a horizontal scale factor to the font) or a smaller
font, and return to the previous step.

Let the anchor point be a point on the
inline box, determined by the textAlign and textBaseline values, as follows:

Let the anchor point 's vertical position
be the bottom of the em box of the first available font of the
inline box.

Paint the hypothetical inline box as the shape given by the
text's glyphs, as transformed by the current transformation
matrix , and anchored and sized so that before applying the
current transformation matrix ,
the anchor point is at ( x
, y ) and each CSS pixel is mapped to one
coordinate space unit.

The measureText()
method takes one argument, text . When the
method is invoked, the user agent must replace all the space characters in
text with U+0020 SPACE characters, and then
must form a hypothetical infinitely wide CSS line box containing a
single inline box containing the text text ,
with all the properties at their initial values except the 'font'
property of the inline element set to the current font of the
browsing context, as given by the font attribute,
and must then return a new TextMetrics object with its width
attribute set to the width of that inline box, in CSS pixels.
[CSS]

Glyphs rendered using fillText()
and strokeText() can spill out of the box
given by the font size (the em square size) and the width returned
by measureText() (the text width). This
version of the specification does not provide a way to obtain the
bounding box dimensions of the text. If the text is to be rendered
and removed, care needs to be taken to replace the entire area of
the canvas that the clipping region covers, not just the box given
by the em square height and measured text width.

A future version of the 2D context API may provide
a way to render fragments of documents, rendered using CSS,
straight to the canvas. This would be provided in preference to a
dedicated way of doing multiline layout.

3.11.11.1.10.
Images

To draw images onto the canvas, the drawImage method can
be used.

This method is overloaded with three variants: drawImage( image , dx ,
dy ) , drawImage(
image , dx , dy , dw , dh
) , and drawImage( image
, sx , sy , sw , sh , dx ,
dy , dw , dh ) . (Actually it is overloaded with six; each of
those three can take either an HTMLImageElement or an
HTMLCanvasElement for
the image argument.) If not specified, the
dw and dh arguments must
default to the values of sw and sh , interpreted such that one CSS pixel in the image is
treated as one unit in the canvas coordinate space. If the
sx , sy , sw , and sh arguments are omitted,
they must default to 0, 0, the image's intrinsic width in image
pixels, and the image's intrinsic height in image pixels,
respectively.

The image argument must be an instance of an
HTMLImageElement or
HTMLCanvasElement .
If the image is of the wrong type or null, the
implementation must raise a TYPE_MISMATCH_ERR
exception.

If the image argument is an HTMLImageElement object whose
complete attribute is false, then the
implementation must raise an INVALID_STATE_ERR
exception.

When drawImage() is invoked, the region of the
image specified by the source rectangle must be painted on the
region of the canvas specified by the destination rectangle, after
applying the current transformation matrix
to the points of the destination rectangle.

When a canvas is drawn onto itself, the drawing
model requires the source to be copied before the image is drawn
back onto the canvas, so it is possible to copy parts of a canvas
onto overlapping parts of itself.

When the drawImage() method is passed, as its
image argument, an animated image, the poster
frame of the animation, or the first frame of the animation if
there is no poster frame, must be used.

3.11.11.1.11.Pixel manipulation

The createImageData( sw , sh ) method must
return an ImageData object
representing a rectangle with a width in CSS pixels equal to the
absolute magnitude of sw and a height in CSS
pixels equal to the absolute magnitude of sh ,
filled with transparent black.

If any of the arguments to createImageData() or getImageData() are infinite or NaN, or
if either the sw or sh
arguments are zero, the method must instead raise an
INDEX_SIZE_ERR exception.

ImageData objects must be
initialized so that their width attribute is set to
w , the number of physical device pixels per
row in the image data, their height attribute is set
to h , the number of rows in the image data,
and their data attribute is
initialized to a CanvasPixelArray object holding the
image data. At least one pixel's worth of image data must be
returned.

The CanvasPixelArray object provides
ordered, indexed access to the color components of each pixel of
the image data. The data must be represented in left-to-right
order, row by row top to bottom, starting with the top left, with
each pixel's red, green, blue, and alpha components being given in
that order for each pixel. Each component of each device pixel
represented in this array must be in the range 0..255, representing
the 8 bit value for that component. The components must be assigned
consecutive indices starting with 0 for the top left pixel's red
component.

The XXX5( index
) method must return the value of the index th component in the array.

The XXX6( index ,
value ) method must set the value
of the index th component in the array to
value . JS undefined values must
be converted to zero. Other values must first be converted to
numbers using JavaScript's ToNumber algorithm, and if the result is
a NaN value, then the value be must converted to zero. If the
result is less than 0, it must be clamped to zero. If the result is
more than 255, it must be clamped to 255. If the number is not an
integer, it must be rounded to the nearest integer using the IEEE
754r roundTiesToEven rounding mode. [ECMA262][IEEE754R]

The width and height ( w and
h ) might be different from the sw and sh arguments to the above
methods, e.g. if the canvas is backed by a high-resolution bitmap,
or if the sw and sh
arguments are negative.

The handling of pixel rounding when the specified coordinates do
not exactly map to the device coordinate space is not defined by
this specification, except that the following must result in no
visible changes to the rendering:

context.putImageData(context.getImageData(x,
y,
w,
h),
x,
y);

...for any value of x and y , and the following two calls:

context.createImageData(w, h);
context.getImageData(0,
0,
w,
h);

...must return ImageData
objects with the same dimensions, for any value of w and h . In other words, while user
agents may round the arguments of these methods so that they map to
device pixel boundaries, any rounding performed must be performed
consistently for all of the createImageData() , getImageData() and putImageData() operations.

The data returned by getImageData() is at the resolution of
the canvas backing store, which is likely to not be one device
pixel to each CSS pixel if the display used is a high resolution
display. Thus, while one could create an ImageData object, one would not necessarily
know what resolution the canvas expected (how many pixels the
canvas wants to paint over one coordinate space unit pixel).

In the following example, the script first obtains the size of
the canvas backing store, and then generates a few new
ImageData objects which can
be used.

3.11.11.1.12. Drawing
model

When a shape or image is painted, user agents must follow these
steps, in the order given (or act as if they do):

Render the shape or image, creating image A
, as described in the previous sections. For shapes, the current
fill, stroke, and line styles must be honored, and the stroke must
itself also be subjected to the current transformation matrix.

If shadows are supported:

Render the shadow from image A , using the
current shadow styles, creating image B .

Within the clipping region, composite A over
the current canvas bitmap using the current composition
operator.

3.11.11.2. Color spaces
and color correction

The canvas APIs must perform
color correction at only two points: when rendering images with
their own gamma correction and color space information onto the
canvas, to convert the image to the color space used by the canvas
(e.g. using the drawImage() method with an HTMLImageElement object), and when
rendering the actual canvas bitmap to the output device.

Thus, in the 2D context, colors used to draw shapes
onto the canvas will exactly match colors obtained through the
getImageData() method.

The toDataURL() method must not include color
space information in the resource returned. Where the output format
allows it, the color of pixels in resources created by toDataURL()
must match those returned by the getImageData() method.

In user agents that support CSS, the color space used by a
canvas element must match the
color space used for processing any colors for that element in
CSS.

The gamma correction and color space information of images must
be handled in such a way that an image rendered directly using an
img element would use the same
colors as one painted on a canvas element that is then itself rendered.
Furthermore, the rendering of images that have no color correction
information (such as those returned by the toDataURL()
method) must be rendered with no color correction.

Thus, in the 2D context, calling the drawImage() method to render the output of
the toDataURL() method to the canvas, given the
appropriate dimensions, has no visible effect.

Information leakage can occur if scripts from
one origin are exposed to images from
another origin (one that isn't the same ).

To mitigate this, canvas
elements are defined to have a flag indicating whether they are
origin-clean . All canvas
elements must start with their origin-clean set to true. The
flag must be set to false if any of the following actions
occur:

The map element, in conjunction
with any area element descendants,
defines an image map .

The name attribute gives the map a
name so that it can be referenced. The attribute must be present
and must have a non-empty value. Whitespace is significant in this
attribute's value. If the id attribute is also specified, both attributes
must have the same value.

The areas attribute must return an
HTMLCollection rooted
at the map element, whose filter
matches only area elements.

The images attribute must return an
HTMLCollection rooted
at the Document node, whose filter matches only
img and object elements that are associated with this
map element according to the
image map processing model.

The DOM attribute name must reflect the content attribute of the same name.

The shape attribute is an enumerated attribute . The following table lists
the keywords defined for this attribute. The states given in the
first cell of the rows with keywords give the states to which those
keywords map. Some of the keywords are non-conforming, as noted in
the last column.

State

Keywords

Notes

Circle state

circ

Non-conforming

circle

Default
state

default

Polygon state

poly

polygon

Non-conforming

Rectangle state

rect

rectangle

Non-conforming

The attribute may be omitted. The missing value default
is the rectangle state.

The coords attribute must, if
specified, contain a valid list of integers .
This attribute gives the coordinates for the shape described by the
shape
attribute. The processing for this attribute is described as part
of the image map processing model.

In the circle
state , area elements must
have a coords attribute present, with three integers,
the last of which must be non-negative. The first integer must be
the distance in CSS pixels from the left edge of the image to the
center of the circle, the second integer must be the distance in
CSS pixels from the top edge of the image to the center of the
circle, and the third integer must be the radius of the circle,
again in CSS pixels.

In the polygon
state , area elements must
have a coords attribute with at least six integers,
and the number of integers must be even. Each pair of integers must
represent a coordinate given as the distances from the left and the
top of the image in CSS pixels respectively, and all the
coordinates together must represent the points of the polygon, in
order.

In the rectangle state , area elements must have a coords attribute
with exactly four integers, the first of which must be less than
the third, and the second of which must be less than the fourth.
The four points must represent, respectively, the distance from the
left edge of the image to the top left side of the rectangle, the
distance from the top edge to the top side, the distance from the
left edge to the right side, and the distance from the top edge to
the bottom side, all in CSS pixels.

When user agents allow users to follow hyperlinks created using the
area element, as described in the
next section, the href , target and
ping
attributes decide how the link is followed. The rel , media ,
hreflang , and type attributes
may be used to indicate to the user the likely nature of the target
resource before the user follows the link.

If the DOMActivate event
in question is not trusted (i.e. a click() method call was
the reason for the event being dispatched), and the area element's target attribute is ... then raise an
INVALID_ACCESS_ERR exception.

One way that a user agent can enable users to
follow hyperlinks is by allowing area elements to be clicked, or focussed and
activated by the keyboard. This will cause the aforementioned
activation behavior to be invoked.

3.11.14 Image
maps

An image map allows geometric areas on an
image to be associated with hyperlinks .

An image, in the form of an img
element or an object element
representing an image, may be associated with an image map (in the
form of a map element) by
specifying a usemap attribute on the
img or object element. The usemap attribute, if specified, must be a
valid hash-name reference to a map element.

If an img element or an
object element representing an
image has a usemap attribute
specified, user agents must process it as follows:

If that returned null, then abort these steps. The image is not
associated with an image map after all.

Otherwise, the user agent must collect all the area elements that are descendants of the
map . Let those be the areas .

Having obtained the list of area elements that form the image map (the
areas ), interactive user agents must process
the list in one of two ways.

If the user agent intends to show the text that the
img element represents, then it
must use the following steps.

In user agents that do not support images, or that
have images disabled, object
elements cannot represent images, and thus this section never
applies (the fallback content is shown
instead). The following steps therefore only apply to
img elements.

Remove all the area elements in
areas that have no alt attribute, or whose
alt
attribute's value is the empty string, if there is another
area element in areas with the same value in the href attribute
and with a non-empty alt attribute.

Each remaining area element in
areas represents a hyperlink . Those hyperlinks should all be made
available to the user in a manner associated with the text of the
img .

In this context, user agents may represent area and img
elements with no specified alt attributes, or
whose alt attributes are the empty string or
some other non-visible text, in a user-agent-defined fashion
intended to indicate the lack of suitable author-provided text.

If the user agent intends to show the image and allow
interaction with the image to select hyperlinks, then the image
must be associated with a set of layered shapes, taken from the
area elements in areas , in reverse tree order (so the last specified
area element in the map is the bottom-most shape, and the first element in the
map , in tree order, is the top-most
shape).

Each area element in
areas must be processed as follows to obtain a
shape to layer onto the image:

Let x1 be the first number in coords , y1 be the second number,
x2 be the third number, and y2 be the fourth number.

The shape is a rectangle whose top-left corner is given by the
coordinate ( x1 , y1 ) and
whose bottom right corner is given by the coordinate ( x2 , y2 ), those coordinates being
interpreted as CSS pixels from the top left corner of the
image.

For historical reasons, the coordinates must be interpreted
relative to the displayed image, even if it stretched
using CSS or the image element's width and
height attributes.

Mouse clicks on an image associated with a set of layered shapes
per the above algorithm must be dispatched to the top-most shape
covering the point that the pointing device indicated (if any), and
then, must be dispatched again (with a new Event
object) to the image element itself. User agents may also allow
individual area elements
representing hyperlinks
to be selected and activated (e.g. using a keyboard); events from
this are not also propagated to the image.

Because a map
element (and its area elements)
can be associated with multiple img
and object elements, it is
possible for an area element to
correspond to multiple focusable areas of the document.

Image maps are live ; if the DOM is
mutated, then the user agent must act as if it had rerun the
algorithms for image maps.

3.11.15 MathML

User agents must handle text other than inter-element whitespace found in MathML
elements whose content models do not allow raw text by pretending
for the purposes of MathML content models, layout, and rendering
that that text is actually wrapped in an mtext element in the MathML
namespace . (Such text is not, however, conforming.)

User agents must act as if any MathML element whose contents
does not match the element's content model was replaced, for the
purposes of MathML layout and rendering, by an merror element in the MathML
namespace containing some appropriate error message.

To enable authors to use MathML tools that only accept MathML in
its XML form, interactive HTML user agents are encouraged to
provide a way to export any MathML fragment as a
namespace-well-formed XML fragment.

3.11.16 SVG

To enable authors to use SVG tools that only accept SVG in its
XML form, interactive HTML user agents are encouraged to provide a
way to export any SVG fragment as a namespace-well-formed XML
fragment.

3.11.17Dimension attributes

The width and height attributes on
img , embed , object , and video elements may be specified to give the
dimensions of the visual content of the element (the width and
height respectively, relative to the nominal direction of the
output medium), in CSS pixels. The attributes, if specified, must
have values that are valid positive non-zero
integers .

The specified dimensions given may differ from the dimensions
specified in the resource itself, since the resource may have a
resolution that differs from the CSS pixel resolution. (On screens,
CSS pixels have a resolution of 96ppi, but in general the CSS pixel
resolution depends on the reading distance.) If both attributes are
specified, then the ratio of the specified width to the specified
height must be the same as the ratio of the logical width to the
logical height in the resource. The two attributes must be omitted
if the resource in question does not have both a logical width and
a logical height.

To parse the attributes, user agents must use the rules for parsing dimension values . This will return
either an integer length, a percentage value, or nothing. The user
agent requirements for processing the values obtained from parsing
these attributes are described in the rendering section . If one
of these attributes, when parsing, returns no value, it must be
treated, for the purposes of those requirements, as if it was not
specified.

The width and height DOM attributes on
the embed , object , and video elements must reflect the content attributes of the same name.

3.12 Tabular data

3.12.1
Introduction

This section is non-normative.

...examples, how to write tables accessibly, a
brief mention of the table model, etc...

3.12.2 The table element

In this order: optionally a caption element, followed by either zero or
more colgroup elements,
followed optionally by a thead
element, followed optionally by a tfoot element, followed by either zero or more
tbody elements or one or
more tr elements, followed
optionally by a tfoot element
(but there can only be one tfoot
element child in total).

The caption DOM attribute must
return, on getting, the first caption element child of the table element, if any, or null otherwise. On
setting, if the new value is a caption element, the first caption element child of the table element, if any, must be removed, and the
new value must be inserted as the first node of the table element. If the new value is not a
caption element, then a
HIERARCHY_REQUEST_ERR DOM exception must be raised
instead.

The createCaption() method
must return the first caption
element child of the table
element, if any; otherwise a new caption element must be created, inserted as
the first node of the table
element, and then returned.

The deleteCaption() method
must remove the first caption
element child of the table
element, if any.

The tHead DOM attribute must
return, on getting, the first thead element child of the table element, if any, or null otherwise. On
setting, if the new value is a thead element, the first thead element child of the table element, if any, must be removed, and the
new value must be inserted immediately before the first element in
the table element that is neither
a caption element nor a
colgroup element, if any, or
at the end of the table otherwise. If the new value is not a
thead element, then a
HIERARCHY_REQUEST_ERR DOM exception must be raised
instead.

The createTHead() method
must return the first thead
element child of the table
element, if any; otherwise a new thead element must be created and inserted
immediately before the first element in the table element that is neither a caption element nor a colgroup element, if any, or at the end of
the table otherwise, and then that new element must be
returned.

The deleteTHead() method
must remove the first thead
element child of the table
element, if any.

The tFoot DOM attribute must
return, on getting, the first tfoot element child of the table element, if any, or null otherwise. On
setting, if the new value is a tfoot element, the first tfoot element child of the table element, if any, must be removed, and the
new value must be inserted immediately before the first element in
the table element that is neither
a caption element, a
colgroup element, nor a
thead element, if any, or at the
end of the table if there are no such elements. If the new value is
not a tfoot element, then a
HIERARCHY_REQUEST_ERR DOM exception must be raised
instead.

The createTFoot() method
must return the first tfoot
element child of the table
element, if any; otherwise a new tfoot element must be created and inserted
immediately before the first element in the table element that is neither a caption element, a colgroup element, nor a thead element, if any, or at the end of the
table if there are no such elements, and then that new element must
be returned.

The deleteTFoot() method
must remove the first tfoot
element child of the table
element, if any.

The tBodies attribute must
return an HTMLCollection rooted at the
table node, whose filter matches
only tbody elements that are
children of the table
element.

The createTBody() method
must create a new tbody element,
insert it immediately after the last tbody element in the table element, if any, or at the end of the
table element if the
table element has no
tbody element children, and then
must return the new tbody
element.

The rows attribute must return an
HTMLCollection rooted
at the table node, whose filter
matches only tr elements that are
either children of the table
element, or children of thead ,
tbody , or tfoot elements that are themselves children of
the table element. The elements
in the collection must be ordered such that those elements whose
parent is a thead are included
first, in tree order, followed by those elements whose parent is
either a table or tbody element, again in tree order, followed
finally by those elements whose parent is a tfoot element, still in tree order.

The behavior of the insertRow( index
) method depends on the state of the table. When it is
called, the method must act as required by the first item in the
following list of conditions that describes the state of the table
and the index argument:

If index is less than −1 or greater
than the number of elements in rows collection:

The method must raise an INDEX_SIZE_ERR
exception.

If the rows collection has zero elements in it, and the
table has no tbody elements in it:

The method must create a tbody element, then create a tr element, then append the tr element to the tbody element, then append the tbody element to the table element, and finally return the
tr element.

If index is less than −1 or greater
than the number of elements in the rows collection, the
method must raise an INDEX_SIZE_ERR exception.

If index is equal to −1 or equal to
the number of items in the rows collection, the method must create a
tr element, append it to the element
table section , and return the newly created
tr element.

Otherwise, the method must create a tr element, insert it as a child of the
table section element, immediately before the
index th tr
element in the rows collection, and finally must return the
newly created tr element.

The deleteRow( index
) method must remove the index th
element in the rows collection from its parent. If index is less than zero or greater than or equal to the
number of elements in the rows collection, the method must instead raise
an INDEX_SIZE_ERR exception.

The rowIndex attribute must, if
the element has a parent table
element, or a parent tbody ,
thead , or tfoot element and a grandparenttable element, return the index
of the tr element in that
table element's rows collection. If
there is no such table element,
then the attribute must return −1.

The sectionRowIndex
attribute must, if the element has a parent table , tbody
, thead , or tfoot element, return the index of the
tr element in the parent element's
rows collection (for tables, that's the
rows
collection; for table sections, that's the rows collection). If
there is no such parent element, then the attribute must return
−1.

The cells attribute must return an
HTMLCollection rooted
at the tr element, whose filter
matches only td and th elements that are children of the
tr element.

The insertCell( index
) method must act as follows:

If index is less than −1 or greater
than the number of elements in the cells collection, the
method must raise an INDEX_SIZE_ERR exception.

If index is equal to −1 or equal to
the number of items in cells collection, the method must create a
td element, append it to the
tr element, and return the newly
created td element.

Otherwise, the method must create a td element, insert it as a child of the
tr element, immediately before the
index th td or
th element in the cells collection, and
finally must return the newly created td element.

The deleteCell( index
) method must remove the index th
element in the cells collection from its parent. If
index is less than zero or greater than or
equal to the number of elements in the cells collection, the
method must instead raise an INDEX_SIZE_ERR
exception.

The cellIndex DOM attribute
must, if the element has a parent tr
element, return the index of the cell's element in the parent
element's cells collection. If there is no such parent
element, then the attribute must return 0.

3.12.13 Processing
model

The various table elements and their content attributes together
define the table model .

A table consists of
cells aligned on a two-dimensional grid of slots with coordinates ( x , y ). The grid is finite, and is
either empty or has one or more slots. If the grid has one or more
slots, then the x coordinates are always in the
range 0 ≤ x
< x width , and the y
coordinates are always in the range 0 ≤
y < y height . If one or both of x
width and y height are zero, then the table is empty (has no
slots). Tables correspond to table elements.

A cell is a set of
slots anchored at a slot ( cell x , cell y
), and with a particular width and height such that the cell covers all the slots with
coordinates ( x , y ) where
cell x
≤ x < cell x + width and cell y ≤ y
< cell y +
height . Cells can either be data
cells or header cells . Data cells correspond to
td elements, and have zero or more
associated header cells. Header cells correspond to th elements.

A row is a complete set
of slots from x =0 to
x = x width -1 , for a particular value of
y . Rows correspond to tr elements.

A column is a
complete set of slots from y =0 to
y = y height -1 , for a particular value of
x . Columns can correspond to col elements, but in the absence of
col elements are implied.

A row group
is a set of rows anchored
at a slot (0, group y )
with a particular height such that the row
group covers all the slots with coordinates ( x
, y ) where 0 ≤ x < x width and group
y ≤ y
< group y +
height . Row groups correspond to
tbody , thead , and tfoot elements. Not every row is necessarily
in a row group.

A column
group is a set of columns anchored at a slot ( group x , 0) with a particular
width such that the column group covers all the
slots with coordinates ( x , y ) where group x ≤ x
< group x +
width and 0 ≤
y < y height . Column groups correspond to
colgroup elements. Not every
column is necessarily in a column group.

A table model error is an error with the
data represented by table
elements and their descendants. Documents must not have table model
errors.

3.12.13.1. Forming a
table

To determine which elements correspond to which slots in a
table associated with a
table element, to determine the
dimensions of the table ( x width and y height ), and to determine if there are any table model errors , user
agents must use the following algorithm:

Let the table be the table represented by the table element. The x width and y height variables give the table
's dimensions. The table is initially
empty.

If the table element has no
children elements, then return the table (which
will be empty), and abort these steps.

Associate the first caption
element child of the table
element with the table . If there are no such
children, then it has no associated caption element.

Let the current element be the first element
child of the table element.

If a step in this algorithm ever requires the current element to be advanced to the next child of the
table when there is no such next child, then the
user agent must jump to the step labeled end , near the end
of this algorithm.

While the current element is not one of the
following elements, advance the current
element to the next child of the table :

If the result of parsing the value is not an error or zero, then
let span be that value.

Otherwise, if the col element
has no span
attribute, or if trying to parse the attribute's value resulted in
an error, then let span be 1.

Increase x width by
span .

Let the last spancolumns in the table
correspond to the current columncol element.

If current column is not the last
col element child of the
colgroup element, then let the
current column be the next col element child of the colgroup element, and return to the step
labeled columns .

Let all the last columns in the table from
x= x start to
x= x width -1
form a new column
group , anchored at the slot ( x start , 0), with width x
width - x start , corresponding to the colgroup element.

If y height
> y start , then let all the last rows in the table from
y= y start to
y= y height -1
form a new row
group , anchored at the slot with coordinate (0, y start ), with height
y height -
y start ,
corresponding to the current element .

Let the slots with coordinates ( x ,
y ) such that x current ≤ x
< x current
+ colspan and y
current ≤ y < y current + rowspan be
covered by a new cellc , anchored at ( x current , y current ), which has width colspan and height rowspan ,
corresponding to the current cell element.

If any of the slots involved already had a cell covering them, then this is a
table model error . Those slots now have two
cells overlapping.

If cell grows downward is true, then add the
tuple { c , x current , colspan } to the
list of downward-growing cells .

Increase x current by
colspan .

If current cell is the last td or th element in
the tr element being processed, then
increase y current by 1,
abort this set of steps, and return to the algorithm above.

Let current cell be the next td or th element in
the tr element being processed.

Return to step 5 (cells).

When the algorithms above require the user agent to run the
algorithm for growing downward-growing
cells , the user agent must, for each { cell , cell x ,
width } tuple in the list of
downward-growing cells , if any, extend the cellcell so that it
also covers the slots with coordinates ( x ,
y current ), where
cell x
≤ x < cell x + width .

3.12.13.2. Forming relationships between data cells
and header cells

Each data cell can be assigned zero or more header cells. The
algorithm for assigning header cells to data
cells is as follows.

For each header cell in the table, in tree
order , run these substeps:

Let ( header x ,
header y ) be the
coordinate of the slot to which the header cell is anchored.

Let header width be the
width of the header cell.

Let header height be the
height of the header cell.

Let data cells be a list of data cells,
initially empty.

Examine the scope attribute of the th element corresponding to the header cell, and,
based on its state, apply the appropriate substep:

Otherwise, let (0, group y ) be the slot at which the row group is anchored,
let height be the number of rows in the row
group, and add all the data cells that cover slots with coordinates
( slot x , slot y ), where header x ≤ slot x < x width and header y ≤ slot y < group y + height , to the data cells
list.

If the header cell is not anchored in a column group , then do
nothing.

Otherwise, let ( group x
, 0) be the slot at which that column group is anchored, let
width be the number of columns in the column
group, and add all the data cells that cover slots with coordinates
( slot x , slot y ), where header x ≤ slot x < group x + width and header y ≤ slot y < y height , to the data
cells list.

The script element allows
authors to include dynamic script and script data in their
documents.

When used to include dynamic scripts, the scripts may either be
embedded inline or may be imported from an external file using the
src
attribute. If the language is not that described by " text/javascript ", then the type of the script's language
must be given using the type attribute.

When used to include script data, the script data must be
embedded inline, the format of the data must be given using the
type
attribute, and the src attribute must not be specified.

The type attribute gives the
language of the script or format of the script data. If the
attribute is present, its value must be a valid MIME type,
optionally with parameters. The charset
parameter must not be specified. (The default, which is used if the
attribute is absent, is " text/javascript ".)
[RFC2046]

The src attribute, if specified,
gives the address of the external script resource to use. The value
of the attribute must be a URI (or IRI) to a script resource of the
type given by the type attribute, if the attribute is present,
or of the type " text/javascript ", if the
attribute is absent.

The charset attribute gives
the character encoding of the external script resource. The
attribute must not be specified if the src attribute is not
present. If the attribute is set, its value must be a valid
character encoding name, and must be the preferred name for that
encoding. [IANACHARSET]

The encoding specified must be the encoding used by the script
resource. If the charset attribute is omitted, the character
encoding of the document will be used. If the script resource uses
a different encoding than the document, then the attribute must be
specified.

The async and defer attributes are
boolean
attributes that indicate how the script should be executed.

There are three possible modes that can be selected using these
attributes. If the async attribute is present, then the script
will be executed asynchronously, as soon as it is available. If the
async
attribute is not present but the defer attribute is
present, then the script is executed when the page has finished
parsing. If neither attribute is present, then the script is
downloaded and executed immediately, before the user agent
continues parsing the page. The exact processing details for these
attributes is described below.

The defer attribute may be specified even if the
async
attribute is specified, to cause legacy Web browsers that only
support defer (and not async ) to fall
back to the defer behavior instead of the synchronous
blocking behavior that is the default.

Changing the src , type , charset ,
async ,
and defer attributes dynamically has no direct
effect; these attribute are only used at specific times described
below (namely, when the element is inserted into the document).

script elements have four
associated pieces of metadata. The first is a flag indicating
whether or not the script block has been "already
executed" . Initially, script elements must have this flag unset
(script blocks, when created, are not "already executed"). When a
script element is cloned, the
"already executed" flag, if set, must be propagated to the clone
when it is created. The second is a flag indicating whether the
element was "parser-inserted" .
This flag is set by the HTML parser and is
used to handle document.write() calls. The third
and fourth pieces of metadata are the
script's type and the
script's character encoding . They are determined when
the script is run, based on the attributes on the element at that
time.

Running a
script : When a script block is inserted into a
document , the user agent must act as follows:

If the script element has a
type
attribute and its value is the empty string, or if the
script element has no
type
attribute but it has a language attribute and that
attribute's value is the empty string, or if the script element has neither a type attribute nor
a language attribute, let
the script's type for this
script element be "
text/javascript ".

For performance reasons, user agents may start loading the
script as soon as the attribute is set, instead, in the hope that
the element will be inserted into the document. Either way, once
the element is inserted into the document, the load must have
started. If the UA performs such prefetching, but the element is
never inserted in the document, or the src attribute is
dynamically changed, then the user agent will not execute the
script, and the load will have been effectively wasted.

Then, the first of the following options that describes the
situation must be followed:

If the document is still being parsed, and the element has a
defer
attribute, and the element does not have an async
attribute

The user agent must immediately execute the script , even if other
scripts are already executing.

When a
script completes loading : If a script whose element was
added to one of the lists mentioned above completes loading while
the document is still being parsed, then the parser handles it.
Otherwise, when a script completes loading, the UA must run the
following steps as soon as as any other scripts that may be
executing have finished executing:

If the script's element was added to the list
of scripts that will execute when the document has finished
parsing :

If the script's element is not the first element in the list,
then do nothing yet. Stop going through these steps.

Otherwise, execute the script (that is, the
script associated with the first element in the list).

Remove the script's element from the list (i.e. shift out the
first entry in the list).

If there are any more entries in the list, and if the script
associated with the element that is now the first in the list is
already loaded, then jump back to step two to execute it.

If the script's element was added to the list of scripts that will execute asynchronously
:

If the script is not the first element in the list, then do
nothing yet. Stop going through these steps.

Remove the script's element from the list (i.e. shift out the
first entry in the list).

If there are any more scripts in the list, and the element now
at the head of the list had no src attribute when it
was added to the list, or had one, but its associated script has
finished loading, then jump back to step two to execute the script
associated with this element.

If the script's element was added to the list of scripts that will execute as soon as
possible :

This means that a UTF-16 document will always
assume external scripts are UTF-16...? This applies, e.g., to
document's created using createDocument()... It also means changing
document.charSet will affect the character encoding used to
interpret scripts, is that really what happens?

If the script is inline

For scripting languages that consist of pure text, user agents
must use the value of the DOM text attribute
(defined below) as the script to execute, and for XML-based
scripting languages, user agents must use all the child nodes of
the script element as the
script to execute.

In any case, the user agent must execute the script according to
the semantics defined by the language associated with the script's type (see the scripting languages section below).

The element's attributes' values might have changed
between when the element was inserted into the document and when
the script has finished loading, as may its other attributes;
similarly, the element itself might have been taken back out of the
DOM, or had other changes made. These changes do not in any way
affect the above steps; only the values of the attributes at the
time the script element is
first inserted into the document matter.

The DOM attributes src , type , charset , async , and
defer
, each must reflect the respective content
attributes of the same name.

The DOM attribute text must return a
concatenation of the contents of all the text nodes that are direct children of the
script element (ignoring any
other nodes such as comments or elements), in tree order. On
setting, it must act the same way as the textContent DOM attribute.

3.14.1.1.
Scripting languages

A user agent is said to support the scripting
language if the script's
type matches the MIME type of a scripting language that
the user agent implements.

The following lists some MIME types and the languages to which
they refer:

The noscript element does
not represent anything. It is used to present different markup to
user agents that support scripting and those that don't support
scripting, by affecting how the document is parsed.

Outside of head elements, if
the noscript element is
with script , then the content model of
a noscript element is text,
except that the text must be such that running the following
algorithm results in a conforming document with no noscript elements and no script elements, and such that no step in the
algorithm causes an HTML parser to flag a
parse error :

Set the innerHTML attribute of the parent element to the value of s .
(This, as a side-effect, causes the noscript element to be removed from the
document.)

Insert the before children at the start of
the parent element , preserving their original
relative order.

Insert the after children at the end of the
parent element , preserving their original
relative order.

The noscript element has no
other requirements. In particular, children of the noscript element are not exempt from form
submission, scripting, and so forth, even when the element is
with script .

All these contortions are required because, for
historical reasons, the noscript element is handled differently by
the HTML parser based on whether scripting was enabled or
not when the parser was invoked. The element is not allowed in
XML, because in XML the parser is not affected by such state, and
thus the element would not have the desired effect.

The event-source
element represents a target for events generated by a remote
server.

The src attribute, if
specified, must give a URI (or IRI) pointing to a resource that
uses the text/event-stream format.

When the element is inserted into the document, if it has the
src
attribute specified, the user agent must act as if the addEventSource() method on the
event-source element had
been invoked with the URI resulting from resolving the src attribute's
value to an absolute URI.

While the element is in a document, if its src attribute
is mutated, the user agent must act as if first the removeEventSource() method on the
event-source element had
been invoked with the URI resulting from resolving the old value of
the attribute to an absolute URI, and then as if the addEventSource() method on the element
had been invoked with the URI resulting from resolving the
new value of the src attribute
to an absolute URI.

When the element is removed from the document, if it has the
src
attribute specified, or, when the src attribute
is about to be removed, the user agent must act as if the
removeEventSource() method on the
event-source element had
been invoked with the URI resulting from resolving the src attribute's
value to an absolute URI.

There can be more than one event-source element per document, but
authors should take care to avoid opening multiple connections to
the same server as HTTP recommends a limit to the number of
simultaneous connections that a user agent can open per server.

The src DOM attribute must
reflect the content attribute of the same
name.

Rendering will be described in the Rendering
section in due course. Basically CSS :open and :closed match the
element, it's a block-level element by default, and when it matches
:closed it renders as if it had an XBL binding attached to it whose
template was just <template> ▶<content
includes="legend:first-child">Details</content>
</template> , and when it's :open it acts as if it had
an XBL binding attached to it whose template was just
<template> ▼<content
includes="legend:first-child">Details</content>
<content/> </template> or some such.

Clicking the legend would make it open/close
(and would change the content attribute). Question: Do we want the
content attribute to reflect the actual state like this? I think we
do, the DOM not reflecting state has been a pain in the neck
before. But is it semantically ok?

One possible thing to be added is a way to
detect when a row/selection has been deleted, activated, etc, by
the user (delete key, enter key, etc).

This element is defined as interactive, which
means it can't contain other interactive elements, despite the fact
that we expect it to work with other interactive elements e.g.
checkboxes and input fields. It should be called something like a
Leaf Interactive Element or something, which counts for ancestors
looking in and not descendants looking out.

The datagrid element
represents an interactive representation of tree, list, or tabular
data.

The data being presented can come either from the content, as
elements given as children of the datagrid element, or from a scripted data
provider given by the data DOM attribute.

In the datagrid data
model, data is structured as a set of rows representing a tree,
each row being split into a number of columns. The columns are
always present in the data model, although individual columns may
be hidden in the presentation.

Each row can have child rows. Child rows may be hidden or shown,
by closing or opening (respectively) the parent row.

Rows are referred to by the path along the tree that one would
take to reach the row, using zero-based indices. Thus, the first
row of a list is row "0", the second row is row "1"; the first
child row of the first row is row "0,0", the second child row of
the first row is row "0,1"; the fourth child of the seventh child
of the third child of the tenth row is "9,2,6,3", etc.

The columns can have captions. Those captions are not considered
a row in their own right, they are obtained separately.

Selection of data in a datagrid operates at the row level. If the
multiple attribute is present, multiple
rows can be selected at once, otherwise the user can only select
one row at a time.

The datagrid element can
be disabled entirely by setting the disabled
attribute.

Columns, rows, and cells can each have specific flags, known as
classes, applied to them by the data provider. These classes
affect the functionality of the
datagrid element, and are
also passed to the style system .
They are similar in concept to the class attribute, except
that they are not specified on elements but are given by scripted
data providers.

3.15.2.2. How rows are
identified

The chains of numbers that give a row's path, or identifier, are
represented by objects that implement the RowSpecification interface.

In ECMAScript, two classes of objects are said to implement this
interface: Numbers representing non-negative integers, and
homogeneous arrays of Numbers representing non-negative integers.
Thus, [1,0,9] is a RowSpecification , as is 1 on
its own. However, [1,0.2,9] is not a RowSpecification object, since its second
value is not an integer.

User agents must always represent RowSpecification s in ECMAScript by
using arrays, even if the path only has one number.

The root of the tree is represented by the empty path; in
ECMAScript, this is the empty array ( [] ). Only the
getRowCount() and GetChildAtPosition() methods ever
get called with the empty path.

3.15.2.3. The data
provider interface

The conformance criteria in this section apply to any
implementation of the DataGridDataProvider , including
(and most commonly) the content author's
implementation(s).

The DataGridDataProvider interface
represents the interface that objects must implement to be used as
custom data views for datagrid elements.

Not all the methods are required. The minimum number of methods
that must be implemented in a useful view is two: the getRowCount() and getCellData() methods.

Once the object is written, it must be hooked up to the
datagrid using the data DOM
attribute.

The following methods may be usefully implemented:

initialize( datagrid )

Called by the datagrid
element (the one given by the datagrid
argument) after it has first populated itself. This would typically
be used to set the initial selection of the datagrid element when it is first loaded.
The data provider could also use this method call to register a
select
event handler on the datagrid
in order to monitor selection changes.

getRowCount( row )

Must return the number of rows that are children of the
specified row , including rows that are
off-screen. If row is empty, then the number of
rows at the top level must be returned. If the value that this
method would return for a given row changes,
the relevant update methods on the datagrid must be called first. Otherwise,
this method must always return the same number. For a list (as
opposed to a tree), this method must return 0 whenever it is called
with a row identifier that is not empty.

getChildAtPosition(
parentRow , position
)

Must return the index of the row that is a child of parentRow and that is to be positioned as the position th row under parentRow when
rendering the children of parentRow . If
parentRow is empty, then position refers to the position th row
at the top level of the data grid. May be omitted if the rows are
always to be sorted in the natural order. (The natural order is the
one where the method always returns position .)
For a given parentRow , this method must never
return the same value for different values of position . The returned value x must
be in the range 0 ≤ x
< n , where n is the value returned by getRowCount(
parentRow ) .

getColumnCount()

Must return the number of columns currently in the data model
(including columns that might be hidden). May be omitted if there
is only one column. If the value that this method would return
changes, the datagrid 's
updateEverything() method must be
called.

getCaptionText( column )

Must return the caption, or label, for column column . May be omitted if the columns have no captions.
If the value that this method would return changes, the
datagrid 's updateColumnChanged() method must
be called with the appropriate column index.

getCaptionClasses(
column , classes
)

Must add the classes that apply to column column to the classes object. May be
omitted if the columns have no special classes. If the classes that
this method would add changes, the datagrid 's updateColumnChanged() method must
be called with the appropriate column index. Some classes have
predefined meanings .

getRowImage( row )

Must return a URI to an image that represents row row , or the empty string if there is no applicable image.
May be omitted if no rows have associated images. If the value that
this method would return changes, the datagrid 's update methods must be called
to update the row in question.

getRowMenu( row
)

Must return an HTMLMenuElement object that is to be
used as a context menu for row row , or null if
there is no particular context menu. May be omitted if none of the
rows have a special context menu. As this method is called
immediately before showing the menu in question, no precautions
need to be taken if the return value of this method changes.

getRowClasses( row , classes )

Must add the classes that apply to row row
to the classes object. May be omitted if the
rows have no special classes. If the classes that this method would
add changes, the datagrid 's
update methods must be called to update the row in question. Some
classes have predefined
meanings .

getCellData( row , column )

Must return the value of the cell on row row in column column . For text cells,
this must be the text to show for that cell. For progress bar
cells , this must be either a floating point number in the
range 0.0 to 1.0 (converted to a string representation ),
indicating the fraction of the progress bar to show as full (1.0
meaning complete), or the empty string, indicating an indeterminate
progress bar. If the value that this method would return changes,
the datagrid 's update
methods must be called to update the rows that changed. If only one
cell changed, the updateCellChanged() method may be
used.

getCellClasses( row , column , classes )

Must add the classes that apply to the cell on row row in column column to the
classes object. May be omitted if the cells
have no special classes. If the classes that this method would add
changes, the datagrid 's
update methods must be called to update the rows or cells in
question. Some classes have predefined meanings .

toggleColumnSortState(
column )

Called by the datagrid
when the user tries to sort the data using a particular column
column . The data provider must update its
state so that the GetChildAtPosition() method
returns the new order, and the classes of the columns returned by
getCaptionClasses() represent the
new sort status. There is no need to tell the datagrid that it the data has changed, as
the datagrid automatically
assumes that the entire data model will need updating.

setCellCheckedState(
row , column , state )

Called by the datagrid
when the user changes the state of a checkbox cell on row
row , column column . The
checkbox should be toggled to the state given by state , which is a positive integer (1) if the checkbox is
to be checked, zero (0) if it is to be unchecked, and a negative
number (−1) if it is to be set to the indeterminate state.
There is no need to tell the datagrid that the cell has changed, as the
datagrid automatically
assumes that the given cell will need updating.

cycleCell( row ,
column )

Called by the datagrid
when the user changes the state of a cyclable cell on row
row , column column . The
data provider should change the state of the cell to the new state,
as appropriate. There is no need to tell the datagrid that the cell has changed, as the
datagrid automatically
assumes that the given cell will need updating.

editCell( row ,
column , data
)

Called by the datagrid
when the user edits the cell on row row ,
column column . The new value of the cell is
given by data . The data provider should update
the cell accordingly. There is no need to tell the datagrid that the cell has changed, as the
datagrid automatically
assumes that the given cell will need updating.

The following classes (for rows, columns, and cells) may be
usefully used in conjunction with this interface:

Class name

Applies to

Description

checked

Cells

The cell has a checkbox and it is checked. (The cyclable and progress classes override this,
though.)

cyclable

Cells

The cell can be cycled through multiple values. (The
progress class overrides this,
though.)

The cell has a checkbox, and it can be set to an indeterminate
state. If neither the checked
nor unchecked classes are present, then the
checkbox is in that state, too. (The cyclable and progress classes override this,
though.)

initially-hidden

Columns

The column will not be shown when the datagrid is initially rendered. If this
class is not present on the column when the datagrid is initially rendered, the column
will be visible if space allows.

initially-closed

Rows

The row will be closed when the datagrid is initially rendered. If neither
this class nor the initially-open class is present on the
row when the datagrid is
initially rendered, the initial state will depend on platform
conventions.

initially-open

Rows

The row will be opened when the datagrid is initially rendered. If neither
this class nor the initially-closed class is present on
the row when the datagrid is
initially rendered, the initial state will depend on platform
conventions.

progress

Cells

The cell is a progress bar.

reversed

Columns

If the cell is sorted, the sort direction is descending,
instead of ascending.

selectable-separator

Rows

The row is a normal, selectable, data row, except that instead
of having data, it only has a separator. (The header
and separator classes override this,
though.)

separator

Rows

The row is a separator row, not a data row. (The header
class overrides this, though.)

sortable

Columns

The data can be sorted by this column.

sorted

Columns

The data is sorted by this column. Unless the reversed class is also present, the sort
direction is ascending.

unchecked

Cells

The cell has a checkbox and, unless the checked
class is present as well, it is unchecked. (The cyclable and progress classes override this,
though.)

3.15.2.4. The
default data provider

The user agent must supply a default data provider for the case
where the datagrid 's
data
attribute is null. It must act as described in this section.

The behavior of the default data provider depends on the nature
of the first element child of the datagrid .

getRowCount( row
) : The number of rows returned by the default
data provider for the root of the tree (when row is empty) must be the total number of tr elements that are children of tbody elements that are children of the
table , if there are any such
child tbody elements. If there
are no such tbody elements then
the number of rows returned for the root must be the number of
tr elements that are children of the
table .

getColumnCount() : The number
of columns returned must be the number of td element children in the first tr element child of the first tbody element child of the table , if there are any such tbody elements. If there are no such
tbody elements, then it must be
the number of td element children in
the first tr element child of the
table , if any, or otherwise 1.
If the number that would be returned by these rules is 0, then 1
must be returned instead.

getCaptionText( i
) : If the table has no thead element child, or if its first
thead element child has no
tr element child, the default data
provider must return the empty string for all captions. Otherwise,
the value of the textContent attribute of the i th th element child of
the first tr element child of the
first thead element child of the
table element must be returned.
If there is no such th element, the
empty string must be returned.

getCaptionClasses( i ,
classes ) : If the
table has no thead element child, or if its first
thead element child has no
tr element child, the default data
provider must not add any classes for any of the captions.
Otherwise, each class in the class attribute of the i th
th element child of the first
tr element child of the first
thead element child of the
table element must be added to
the classes . If there is no such
th element, no classes must be
added. The user agent must then:

If the table element has a
class
attribute that includes the sortable class,
add the sortable class.

If the column is the one currently being used to sort the data,
add the sorted class.

If the column is the one currently being used to sort the data,
and it is sorted in descending order, add the reversed class as well.

The various row- and cell- related methods operate relative to a
particular element, the element of the row or cell specified by
their arguments.

For rows : Since the default data provider for
a table always returns 0 as the
number of children for any row other than the root, the path to the
row passed to these methods will always consist of a single number.
In the prose below, this number is referred to as i .

If the table has
tbody element children, the
element for the i th row is the i th tr element that is a
child of a tbody element that is
a child of the table element. If
the table does not have
tbody element children, then the
element for the i th real row is the
i th tr element
that is a child of the table
element.

For cells : Given a row and its element, the
row's i th cell's element is the i th td element child of
the row element.

getRowImage( i
) : If the row's first cell's element has an
img element child, then the URI of
the row's image is the URI of the first img element child of the row's first cell's
element. Otherwise, the URI of the row's image is the empty
string.

getRowMenu( i
) : If the row's first cell's element has a
menu element child, then the row's
menu is the first menu element
child of the row's first cell's element. Otherwise, the row has no
menu.

toggleColumnSortState( i ) : If the data is already being
sorted on the given column, then the user agent must change the
current sort mapping to be the inverse of the current sort mapping;
if the sort order was ascending before, it is now descending,
otherwise it is now ascending. Otherwise, if the current sort
column is another column, or the data model is currently not
sorted, the user agent must create a new mapping, which maps rows
in the data model to rows in the DOM so that the rows in the data
model are sorted by the specified column, in ascending order.
(Which sort comparison operator to use is left up to the UA to
decide.)

The data provider must call the datagrid 's update methods appropriately
whenever the descendants of the datagrid mutate. For example, if a
tr is removed, then the updateRowsRemoved() methods would
probably need to be invoked, and any change to a cell or its
descendants must cause the cell to be updated. If the
table element stops being the
first child of the datagrid ,
then the data provider must call the updateEverything() method on the
datagrid . Any change to a
cell that is in the column that the data provider is currently
using as its sort column must also cause the sort to be
reperformed, with a call to updateEverything() if the change did
affect the sort order.

While the first element child is a select or
datalist element

The default data provider must return 1 for the column count,
the empty string for the column's caption, and must not add any
classes to the column's classes.

For the rows, assume the existence of a node filter view of the
descendants of the first element child of the datagrid element (the select
or datalist element), that skips all nodes other than
optgroup and option elements, as well as
any descendents of any option elements.

Given a path row , the corresponding element
is the one obtained by drilling into the view, taking the child
given by the path each time.

The path "1,1,2" would select the element with ID "b". In the
filtered view, the text nodes, comment nodes, and bogus elements
are ignored; so for instance, the element with ID "a" (path "1,1")
has only 3 child nodes in the view.

getRowCount( row )
must drill through the view to find the element corresponding to
the method's argument, and return the number of child nodes in the
filtered view that the corresponding element has. (If the
row is empty, the corresponding element is the
select element at the root of the filtered view.)

If the row 's corresponding element
contains other elements that are also in the view, and the
element's class attribute contains the closed class: initially-closed

If the row 's corresponding element
contains other elements that are also in the view, and the
element's class attribute contains the open class: initially-open

The getCellData( row , cell ) method must return the value of the
label attribute if the
row 's corresponding element is an
optgroup element, otherwise, if the row 's corresponding element is an option
element, its label attribute
if it has one, otherwise the value of its textContent DOM attribute.

autoselect some rows when initialized, reflect
the selection in the select, reflect the multiple attribute
somehow.

The data provider must call the datagrid 's update methods appropriately
whenever the descendants of the datagrid mutate.

While the first element child is another element

The default data provider must return 1 for the column count,
the empty string for the column's caption, and must not add any
classes to the column's classes.

For the rows, assume the existence of a node filter view of the
descendants of the datagrid
that skips all nodes other than li ,
h1 – h6 , and hr
elements, and skips any descendants of menu elements.

Given this view, each element in the view represents a row in
the data model. The element corresponding to a path row is the one obtained by drilling into the view, taking
the child given by the path each time. The element of the row of a
particular method call is the element given by drilling into the
view along the path given by the method's arguments.

getRowCount( row )
must return the number of child elements in this view for the given
row, or the number of elements at the root of the view if the
row is empty.

In the following example, the elements are identified by the
paths given by their child text nodes:

getRowImage( i ) must
return the URI of the image given by the first img element descendant (in the real DOM) of the
row's element, that is not also a descendant of another element in
the filtered view that is a descendant of the row's element.

In the following example, the row with path "1,0" returns
"http://example.com/a" as its image URI, and the other rows
(including the row with path "1") return the empty string:

getRowMenu( i ) must
return the first menu element
descendant (in the real DOM) of the row's element, that is not also
a descendant of another element in the filtered view that is a
descendant of the row's element. (This is analogous to the image
case above.)