From dd775b558a7061e0c410535a74c527ab0ebe66cf Mon Sep 17 00:00:00 2001 From: Michael Cheung Date: Tue, 23 May 2017 17:59:31 -0400 Subject: [PATCH 01/23] WIP: Adding HTML Content parsing --- config/files.js | 3 ++ lib/org/chromium/webidl/HTMLParser.js | 20 +++++++++++++ test/any/parsing/HTMLFileContent-test.js | 37 ++++++++++++++++++++++++ 3 files changed, 60 insertions(+) create mode 100644 lib/org/chromium/webidl/HTMLParser.js create mode 100644 test/any/parsing/HTMLFileContent-test.js diff --git a/config/files.js b/config/files.js index 5daf925..7b8d4dd 100644 --- a/config/files.js +++ b/config/files.js @@ -90,6 +90,9 @@ `lib${sep}org${sep}chromium${sep}webidl${sep}ast${sep}Stringifier.js`, `lib${sep}org${sep}chromium${sep}webidl${sep}ast${sep}Float.js`, + // HTML File Content Parser + `lib${sep}org${sep}chromium${sep}webidl${sep}HTMLParser.js`, + // Web IDL parsers `lib${sep}org${sep}chromium${sep}webidl${sep}BaseParser.js`, `lib${sep}org${sep}chromium${sep}webidl${sep}Parser.js`, diff --git a/lib/org/chromium/webidl/HTMLParser.js b/lib/org/chromium/webidl/HTMLParser.js new file mode 100644 index 0000000..ac32f99 --- /dev/null +++ b/lib/org/chromium/webidl/HTMLParser.js @@ -0,0 +1,20 @@ +// Copyright 2017 The Chromium Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +foam.CLASS({ + package: 'org.chromium.webidl', + name: 'HTMLParser', + extends: [ 'foam.parsers.HTMLLexer' ], + + requires: [ + 'foam.parsers.HTMLLexer' + ], + + //properties: [ + //], + + //methods: [ + //] +}); + diff --git a/test/any/parsing/HTMLFileContent-test.js b/test/any/parsing/HTMLFileContent-test.js new file mode 100644 index 0000000..a395ea4 --- /dev/null +++ b/test/any/parsing/HTMLFileContent-test.js @@ -0,0 +1,37 @@ +// Copyright 2017 The Chromium Authors. ALl rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. +'use strict'; + +describe('HTMLFileContent', function() { + var HTMLParser; + //var Outputer; + var Parser; + + beforeEach(function() { + HTMLParser = foam.lookup('org.chromium.webidl.HTMLParser'); + }); + + it('should parse a pre tag with no content', function() { + var content = '
';
+  });
+
+  it('should parse a HTML file with one Web IDL Block', function() {
+    var content = `
+        
+          [Constructor]
+          interface Dahut : Mammal {
+            const unsigned short LEVROGYROUS = 0;
+            const unsigned short DEXTROGYROUS = 1;
+            readonly attribute DOMString chirality;
+            attribute unsigned long age;
+            Dahut turnAround(float angle, boolean fall);
+            unsigned long trip();
+            void yell([AllowAny] unsigned long volume,
+                      [TreatNullAs=EmptyString] DOMString sentence);
+          };
+      

+    `;
+    var ret = HTMLParser.create().parseString(content);
+  });
+});

From 58e5e48bfd8dc478e0c7b5383852d9127d6f2a8d Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Mon, 29 May 2017 16:01:08 -0400
Subject: [PATCH 02/23] Adding preliminary HTMLParsing and corresponding tests

---
 config/files.js                            |    3 +
 lib/org/chromium/webidl/HTMLParser.js      |   76 +
 test/node/parsing/HTMLFileContent-test.js  |   58 +
 test/node/parsing/webSpec/WebUSB/0         |   24 +
 test/node/parsing/webSpec/WebUSB/14        |  192 +
 test/node/parsing/webSpec/WebUSB/3         |   17 +
 test/node/parsing/webSpec/WebUSB/spec.html | 4634 ++++++++++++++++++++
 7 files changed, 5004 insertions(+)
 create mode 100644 lib/org/chromium/webidl/HTMLParser.js
 create mode 100644 test/node/parsing/HTMLFileContent-test.js
 create mode 100644 test/node/parsing/webSpec/WebUSB/0
 create mode 100644 test/node/parsing/webSpec/WebUSB/14
 create mode 100644 test/node/parsing/webSpec/WebUSB/3
 create mode 100644 test/node/parsing/webSpec/WebUSB/spec.html

diff --git a/config/files.js b/config/files.js
index 5daf925..7b8d4dd 100644
--- a/config/files.js
+++ b/config/files.js
@@ -90,6 +90,9 @@
     `lib${sep}org${sep}chromium${sep}webidl${sep}ast${sep}Stringifier.js`,
     `lib${sep}org${sep}chromium${sep}webidl${sep}ast${sep}Float.js`,
 
+    // HTML File Content Parser
+    `lib${sep}org${sep}chromium${sep}webidl${sep}HTMLParser.js`,
+
     // Web IDL parsers
     `lib${sep}org${sep}chromium${sep}webidl${sep}BaseParser.js`,
     `lib${sep}org${sep}chromium${sep}webidl${sep}Parser.js`,
diff --git a/lib/org/chromium/webidl/HTMLParser.js b/lib/org/chromium/webidl/HTMLParser.js
new file mode 100644
index 0000000..5aeca7c
--- /dev/null
+++ b/lib/org/chromium/webidl/HTMLParser.js
@@ -0,0 +1,76 @@
+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+'use strict';
+
+foam.CLASS({
+  package: 'org.chromium.webidl',
+  name: 'HTMLParser',
+
+  requires: [
+    'foam.parsers.HTMLLexer'
+  ],
+
+  methods: [
+      function parse(str) {
+        var self = this;
+        var lexer = self.HTMLLexer.create();
+        var OPEN = lexer.TagType.OPEN.name;
+        var CLOSE = lexer.TagType.CLOSE.name;
+        var OPEN_CLOSE = lexer.TagType.OPEN_CLOSE.name;
+
+        var results = lexer.parseString(str).value;
+
+        // Tag matching
+        // Using a stack to obtain ancestorOf 
 tags
+        var tags = [];
+        var pre = [];
+        results.forEach(function(node, i) {
+          var item = results[i];
+
+          if (foam.core.FObject.isInstance(item)) {
+            var top = tags[tags.length - 1];
+            //var singleTag = self.SELF_CLOSING_ELEMENTS.includes(item.nodeName);
+
+            if (top === undefined || item.type.name === OPEN) {
+              tags.push(item);
+            } else if (item.nodeName === top.nodeName && item.type.name === CLOSE) {
+              // Do we need to do anything with this?
+              var x = tags.pop();
+            } else if (item.type.name === OPEN_CLOSE && item.nodeName === 'pre') {
+              // Process the IDL body
+              var idl = self.flatten(item.content);
+
+              var value = {
+                ancestor: top,
+                idl: idl
+              };
+              pre.push(value);
+            } else {
+              // Currently not doing anything for:
+              //  - Self closing tags (item.type.name === OPEN_CLOSE)
+              //  - Malformed / Mismatched HTML Files
+            }
+          }
+        });
+
+        if (tags.length !== 0) {
+          // We have mismatched tags! :(
+        }
+        return pre;
+      },
+
+    function flatten(obj) {
+      var self = this;
+      return obj.reduce(function(acc, item) {
+        if (foam.String.isInstance(item)) {
+          return acc.concat(item);
+        } else if (foam.core.FObject.isInstance(item)) {
+          return acc.concat(foam.Array.isInstance(item.content) ?
+              item.content[1] || item.content[0] || '' : '');
+        }
+      }, "");
+    }
+  ]
+});
+
diff --git a/test/node/parsing/HTMLFileContent-test.js b/test/node/parsing/HTMLFileContent-test.js
new file mode 100644
index 0000000..9cb8bda
--- /dev/null
+++ b/test/node/parsing/HTMLFileContent-test.js
@@ -0,0 +1,58 @@
+// Copyright 2017 The Chromium Authors. ALl rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+'use strict';
+
+describe('HTMLFileContent', function() {
+  var HTMLParser;
+  //var Outputer;
+  var Parser;
+
+  beforeEach(function() {
+    HTMLParser = foam.lookup('org.chromium.webidl.HTMLParser');
+  });
+
+  it('should parse a pre tag with no content', function() {
+    var content = '
';
+  });
+
+  it('should parse a HTML file with one Web IDL Block', function() {
+    var content = `
+        
+        [Constructor]
+        interface Dahut : Mammal {
+          const unsigned short LEVROGYROUS = 0;
+          const unsigned short DEXTROGYROUS = 1;
+          readonly attribute DOMString chirality;
+          attribute unsigned long age;
+          Dahut turnAround(float angle, boolean fall);
+          unsigned long trip();
+          void yell([AllowAny] unsigned long volume,
+              [TreatNullAs=EmptyString] DOMString sentence);
+        };
+    
`;
+    var ret = HTMLParser.create().parse(content);
+  });
+
+  it('should parse the WebUSB spec HTML file ', function() {
+    var fs = require('fs');
+    var testDirectory = `${__dirname}/webSpec/WebUSB`;
+    var spec = fs.readFileSync(`${testDirectory}/spec.html`).toString();
+    var idlFragments = HTMLParser.create().parse(spec);
+
+    expect(idlFragments.length).toBe(15);
+    fs.readdir(testDirectory, function(err, files) {
+      // Go through each of the expected results in the folder
+      files.forEach(function(filename) {
+        var testNum = Number(filename);
+
+        if (!isNaN(testNum) && testNum < idlFragments.length) {
+          var expectedIDL = fs.readFileSync(`${testDirectory}/${filename}`).toString();
+          expect(idlFragments[testNum].idl).toBe(expectedIDL);
+        } else if (filename !== 'spec.html') {
+          console.warn(`${filename} was not used in WebUSB spec test`);
+        }
+      });
+    });
+  });
+});
diff --git a/test/node/parsing/webSpec/WebUSB/0 b/test/node/parsing/webSpec/WebUSB/0
new file mode 100644
index 0000000..14a6765
--- /dev/null
+++ b/test/node/parsing/webSpec/WebUSB/0
@@ -0,0 +1,24 @@
+dictionary USBDeviceFilter {
+  unsigned short vendorId;
+  unsigned short productId;
+  octet classCode;
+  octet subclassCode;
+  octet protocolCode;
+  DOMString serialNumber;
+};
+
+dictionary USBDeviceRequestOptions {
+  required sequence filters;
+};
+
+interface USB : EventTarget {
+  attribute EventHandler onconnect;
+  attribute EventHandler ondisconnect;
+  Promise> getDevices();
+  Promise requestDevice(USBDeviceRequestOptions options);
+};
+
+[SecureContext]
+partial interface Navigator {
+  [SameObject] readonly attribute USB usb;
+};
diff --git a/test/node/parsing/webSpec/WebUSB/14 b/test/node/parsing/webSpec/WebUSB/14
new file mode 100644
index 0000000..0d73ecf
--- /dev/null
+++ b/test/node/parsing/webSpec/WebUSB/14
@@ -0,0 +1,192 @@
+dictionary USBDeviceFilter {
+  unsigned short vendorId;
+  unsigned short productId;
+  octet classCode;
+  octet subclassCode;
+  octet protocolCode;
+  DOMString serialNumber;
+};
+
+dictionary USBDeviceRequestOptions {
+  required sequence filters;
+};
+
+interface USB : EventTarget {
+  attribute EventHandler onconnect;
+  attribute EventHandler ondisconnect;
+  Promise> getDevices();
+  Promise requestDevice(USBDeviceRequestOptions options);
+};
+
+[SecureContext]
+partial interface Navigator {
+  [SameObject] readonly attribute USB usb;
+};
+
+dictionary USBConnectionEventInit : EventInit {
+    required USBDevice device;
+};
+
+[Constructor(DOMString type, USBConnectionEventInit eventInitDict)]
+interface USBConnectionEvent : Event {
+  [SameObject] readonly attribute USBDevice device;
+};
+
+interface USBDevice {
+  readonly attribute octet usbVersionMajor;
+  readonly attribute octet usbVersionMinor;
+  readonly attribute octet usbVersionSubminor;
+  readonly attribute octet deviceClass;
+  readonly attribute octet deviceSubclass;
+  readonly attribute octet deviceProtocol;
+  readonly attribute unsigned short vendorId;
+  readonly attribute unsigned short productId;
+  readonly attribute octet deviceVersionMajor;
+  readonly attribute octet deviceVersionMinor;
+  readonly attribute octet deviceVersionSubminor;
+  readonly attribute DOMString? manufacturerName;
+  readonly attribute DOMString? productName;
+  readonly attribute DOMString? serialNumber;
+  readonly attribute USBConfiguration? configuration;
+  readonly attribute FrozenArray configurations;
+  readonly attribute boolean opened;
+  Promise open();
+  Promise close();
+  Promise selectConfiguration(octet configurationValue);
+  Promise claimInterface(octet interfaceNumber);
+  Promise releaseInterface(octet interfaceNumber);
+  Promise selectAlternateInterface(octet interfaceNumber, octet alternateSetting);
+  Promise controlTransferIn(USBControlTransferParameters setup, unsigned short length);
+  Promise controlTransferOut(USBControlTransferParameters setup, optional BufferSource data);
+  Promise clearHalt(USBDirection direction, octet endpointNumber);
+  Promise transferIn(octet endpointNumber, unsigned long length);
+  Promise transferOut(octet endpointNumber, BufferSource data);
+  Promise isochronousTransferIn(octet endpointNumber, sequence packetLengths);
+  Promise isochronousTransferOut(octet endpointNumber, BufferSource data, sequence packetLengths);
+  Promise reset();
+};
+
+enum USBRequestType {
+  "standard",
+  "class",
+  "vendor"
+};
+
+enum USBRecipient {
+  "device",
+  "interface",
+  "endpoint",
+  "other"
+};
+
+enum USBTransferStatus {
+  "ok",
+  "stall",
+  "babble"
+};
+
+dictionary USBControlTransferParameters {
+  required USBRequestType requestType;
+  required USBRecipient recipient;
+  required octet request;
+  required unsigned short value;
+  required unsigned short index;
+};
+
+[Constructor(USBTransferStatus status, optional DataView? data)]
+interface USBInTransferResult {
+  readonly attribute DataView? data;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(USBTransferStatus status, optional unsigned long bytesWritten = 0)]
+interface USBOutTransferResult {
+  readonly attribute unsigned long bytesWritten;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(USBTransferStatus status, optional DataView? data)]
+interface USBIsochronousInTransferPacket {
+  readonly attribute DataView? data;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(sequence packets, optional DataView? data)]
+interface USBIsochronousInTransferResult {
+  readonly attribute DataView? data;
+  readonly attribute FrozenArray packets;
+};
+
+[Constructor(USBTransferStatus status, optional unsigned long bytesWritten = 0)]
+interface USBIsochronousOutTransferPacket {
+  readonly attribute unsigned long bytesWritten;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(sequence packets)]
+interface USBIsochronousOutTransferResult {
+  readonly attribute FrozenArray packets;
+};
+
+[Constructor(USBDevice device, octet configurationValue)]
+interface USBConfiguration {
+  readonly attribute octet configurationValue;
+  readonly attribute DOMString? configurationName;
+  readonly attribute FrozenArray interfaces;
+};
+
+[Constructor(USBConfiguration configuration, octet interfaceNumber)]
+interface USBInterface {
+  readonly attribute octet interfaceNumber;
+  readonly attribute USBAlternateInterface alternate;
+  readonly attribute FrozenArray alternates;
+  readonly attribute boolean claimed;
+};
+
+[Constructor(USBInterface deviceInterface, octet alternateSetting)]
+interface USBAlternateInterface {
+  readonly attribute octet alternateSetting;
+  readonly attribute octet interfaceClass;
+  readonly attribute octet interfaceSubclass;
+  readonly attribute octet interfaceProtocol;
+  readonly attribute DOMString? interfaceName;
+  readonly attribute FrozenArray endpoints;
+};
+
+enum USBDirection {
+  "in",
+  "out"
+};
+
+enum USBEndpointType {
+  "bulk",
+  "interrupt",
+  "isochronous"
+};
+
+[Constructor(USBAlternateInterface alternate, octet endpointNumber, USBDirection direction)]
+interface USBEndpoint {
+  readonly attribute octet endpointNumber;
+  readonly attribute USBDirection direction;
+  readonly attribute USBEndpointType type;
+  readonly attribute unsigned long packetSize;
+};
+
+dictionary USBPermissionDescriptor : PermissionDescriptor {
+  sequence filters;
+};
+
+dictionary AllowedUSBDevice {
+  required octet vendorId;
+  required octet productId;
+  DOMString serialNumber;
+};
+
+dictionary USBPermissionStorage {
+  required sequence allowedDevices = [];
+};
+
+interface USBPermissionResult : PermissionStatus {
+  attribute FrozenArray devices;
+};
+
diff --git a/test/node/parsing/webSpec/WebUSB/3 b/test/node/parsing/webSpec/WebUSB/3
new file mode 100644
index 0000000..b13735f
--- /dev/null
+++ b/test/node/parsing/webSpec/WebUSB/3
@@ -0,0 +1,17 @@
+let button = document.getElementById('request-device');
+button.addEventListener('click', async () => {
+  let device;
+  try {
+    device = await navigator.usb.requestDevice({ filters: [{
+        vendorId: 0xABCD,
+        classCode: 0xFF, // vendor-specific
+        protocolCode: 0x01
+    }]});
+  } catch () {
+    // No device was selected.
+  }
+
+  if (device !== undefined) {
+    // Add |device| to the UI.
+  }
+});
diff --git a/test/node/parsing/webSpec/WebUSB/spec.html b/test/node/parsing/webSpec/WebUSB/spec.html
new file mode 100644
index 0000000..5ccacad
--- /dev/null
+++ b/test/node/parsing/webSpec/WebUSB/spec.html
@@ -0,0 +1,4634 @@
+
+
+
+  
+  WebUSB API
+  
+
+  
+  
+
+
+
+
+
+
+
+ 
 Jump to Table of Contents Collapse Sidebar

+  

+   

+   
WebUSB API

+   
Editor’s Draft, 

+   

+    

+     
This version:
+     
https://wicg.github.io/webusb
+     
Issue Tracking:
+     
GitHub
+     
Inline In Spec
+     
Editors:
+     
 (Google Inc.)
+     
 (Google Inc.)
+     
Participate:
+     
Join the W3C Community Group
+     
IRC: #webusb on W3C’s IRC (Stay around for an answer, it make take a while)
+     
Ask questions on StackOverflow
+    

+   

+   

+   
Copyright © 2017 the Contributors to the WebUSB API Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA).
+A human-readable summary is available. 

+   

+  

+  

+   
Abstract

+   
This document describes an API for securely providing access to Universal Serial Bus devices from web pages.

+  

+  

+  
Status of this document

+  

+   
 This specification was published by the Web Platform Incubator Community Group.
+  It is not a W3C Standard nor is it on the W3C Standards Track.
+
+  Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply.
+
+  Learn more about W3C Community and Business Groups. 

+   

+  

+  

+  
+  

+   
1. Introduction

+   
This section is non-normative.

+   
The Universal Serial Bus (USB) is the de-facto standard for wired peripherals.
+Most USB devices implement one of roughly a dozen standard "device classes"
+which specify a way for the device to advertise the features it supports and
+commands and data formats for using those features. Standard device classes
+include keyboard, mice, audio, video and storage devices. Operating systems
+support such devices using the "class driver" provided by the OS vendor. There
+is however a long tail of devices that do not fit into one of the standardized
+device classes.  These devices require hardware vendors to write native drivers
+and SDKs in order for developers to take advantage of them and this native code
+prevents these devices from being used by the web.

+   
The WebUSB API provides a way to safely expose USB device services to the web.
+It provides an API familiar to developers who have used existing native USB
+libraries and exposes the device interfaces defined by existing specifications.
+With this API hardware manufacturers will have the ability to build
+cross-platform JavaScript SDKs for their devices. This will be good for the web
+because, instead of waiting for a new kind of device to be popular enough for
+browsers to provide a specific API, new and innovative hardware can be built
+for the web from day one.

+   
For more information about USB see §9 Appendix: A Brief Introduction to USB.

+   
2. Motivating Applications

+   
This section is non-normative.

+   
2.1. Educational Devices

+   
The software delivery model of the web is a key enabler for educational
+applications because they can be quickly loaded on any computer without
+questions of platform compatibility or administrative credentials. Science
+classes are incorporating computerized measurement and data logging into their
+lessons. These tools require bundled software that may be difficult to install
+on managed computers as every new native application adds overhead to an already
+stressed IT department. Web-based hardware APIs allow support for these devices
+to be built directly into existing online course materials, providing a
+completely seamless experience.

+   
Students learning to code with one of the many microcontroller development kits
+can take advantage of online developer tools to write and upload their code.
+These tools already exist however they require a native component to interface
+between the browser and the hardware. These native extensions add a barrier to
+entry and may expose the user to security vulnerabilities in a way that that
+code running in the sandboxed web environment does not.

+   
2.2. Web Drivers

+   
The composablity of the web allows a new ecosystem of hardware support to be
+built entirely from web technology. Taking 3D printers an example, imagine that
+a site hosting 3D object designs wants to integrate printing directly into their
+page. The web supports 2D printing but there is no API for the 3D variety. If
+manufacturers host embeddable pages that use the WebUSB API to send data to
+their printers, sites can use these pages to integrate support for the hardware
+in the same way that features such as embedded maps are added to many existing
+sites.

+   
2.3. Devices Updates and Diagnostics

+   
While wireless protocols such as Bluetooth are often the more convenient choice
+for consumer devices USB ports continue to proliferate because they are an easy
+solution for power delivery and can serve as the connection of last resort when
+the device isn’t working. By integrating update and diagnostic tools into their
+support site a hardware manufacturer can provide tools for customers on any
+platform and collect better diagnostic data when a customer reaches out for
+support through their website. The landing page provides a way for the
+device manufacturer to direct the user to the right part of their website for
+help with their device.

+   
3. Security and Privacy Considerations

+   
This section is non-normative.

+   
The WebUSB API is a powerful feature and has the possibility to expose users to
+a number of new privacy and security risks. These risks can be broadly divided
+into three categories that will be described in the sections below.

+   
3.1. Abusing Access to a Device

+   
Peripheral devices can serve a number of purposes. They may store data, as a
+flash drive does. They may collect information about the outside world as a
+camera or microphone does. They may manipulate objects in the outside world as
+a printer does. Each of the examples above have high-level APIs in the web
+platform with security features that aim to prevent their abuse by a malicious
+website. Storing data to or from an external drive requires the user to select
+the file manually. Turning on the microphone or camera requires permission from
+the user and may activate an indicator to let the user know data collection is
+in progress. Printing a document requires explicit action as well. This API
+provides a generic mechanism to connect to devices not covered by these
+existing high-level APIs and so it requires a similarly generic mechanism for
+preventing a malicious page from abusing a device.

+   
The first of these protections is the requestDevice() function. The UA
+may display a permission prompt when this function is called. Even for a
+non-malicious page this action also preserves user privacy by preventing a site
+from connecting to a device before the user is aware that such a connection is
+possible. The UA may also display an indicator when a device connection is
+active.

+   
Secondly, this specification requires that only secure contexts as described
+in [powerful-features] can access USB devices. This ensures both the
+authenticity of the code executing on behalf of the origin and that data read
+from the device may not be intercepted in transit.

+   
3.2. Attacking a Device

+   
Historically, unless they were created for high security applications, USB
+devices have been designed to trust the host they are connected to and so the
+host is the traditional guardian of access to the capabilities a device
+provides. In the development of this specification two possibilities were
+considered. First, the UA could notify the device of the origin from which a
+request originated. This would be similar to the Referrer header
+included in HTTP request. The difficulty of this approach is that it places
+the burden of access control on the device. Devices often have very limited
+processing and storage capabilities and so an effort was made to limit the
+amount of work necessary on the part of the device.

+   
The approach initially chosen during drafting of this specification was to
+instead require that the UA control access though a mechanism similiar to [CORS]. The device could provide the UA with a set of static data structures
+defining a set of origins that are allowed to connect to it. To support a
+transition period for existing devices it was proposed that information about
+allowed origins could also be provided out of band through some kind of public
+registry.

+   
A downside of this approach was two-fold. First, it required vendors to build
+new devices with WebUSB in mind or rely on a public registry system that proved
+difficult to specify. Product development cycles are long and as only an
+Editor’s Draft this specification does not have the clout necessary to influence
+product planning. Second, it provided no mechanism for third-party developers to
+use this API with a device. This limited innovation and the number of developers
+who could take advantage of this new capability.

+   
After considering these options the authors have decided that the permission
+prompt encouraged by the requestDevice() method and the integration with §7.1 Feature Policy provide adequate protection against unwanted access to a
+device.

+   
3.3. Attacking the Host

+   
If a device is compromised then in addition to abusing its own capabilities
+the attacker may also use it to in turn attack the host to which it is connected
+or if the exploit is persistent any host it is connected to later. The methods
+above are the ways in which this specification attempts to mitigate this attack
+vector for once the device is under the control of an attacker (for example, by
+uploading a malicious firmware image) there is nothing that can be done by the
+UA to prevent further damage.

+   
This specification recommends device manufacturers practice defense in depth by
+designing their devices to only accept signed firmware updates and/or require
+physical access to the device in order to apply some configuration changes.

+   
4. WebUSB Descriptors and Requests

+   
This specification defines descriptors and commands the UA MAY use to gather
+information about the device specific to implementing this API.

+   
4.1. WebUSB Platform Capability Descriptor

+   
A device announces support for the WebUSB command set by including the
+following Platform Descriptor in its Binary Object
+Store:

+   
+    
+     
+      
+      
+      
+      
+      
+      
+      
+      
+      
Offset
+      Field
+      Size
+      Value
+      Description
+     
0
+      bLength
+      1
+      Number
+      Size of this descriptor. Must be set to 24.
+     
1
+      bDescriptorType
+      1
+      Constant
+      DEVICE CAPABILITY descriptor type ([USB31] Table 9-6).
+     
2
+      bDevCapabilityType
+      1
+      Constant
+      PLATFORM capability type ([USB31] Table 9-14).
+     
3
+      bReserved
+      1
+      Number
+      This field is reserved and shall be set to zero.
+     
4
+      PlatformCapabilityUUID
+      16
+      UUID
+      Must be set to {3408b638-09a9-47a0-8bfd-a0768815b665}.
+     
20
+      bcdVersion
+      2
+      BCD
+      Protocol version supported. Must be set to 0x0100.
+     
22
+      bVendorCode
+      1
+      Number
+      bRequest value used for issuing WebUSB requests.
+     
23
+      iLandingPage
+      1
+      Number
+      URL descriptor index of the device’s landing page.
+   

+   
The iLandingPage field, when non-zero, indicates a landing page which the device manufacturer would like the user to
+visit in order to control their device. The UA MAY suggest the user navigate
+to this URL when the device is connected.

+   
4.2. WebUSB Device Requests

+   
All control transfers defined by this specification are considered to
+be vendor-specific requests. The bVendorCode value found
+in the WebUSB Platform Capability Descriptor provides the UA
+with the bRequest the device expects the host to use when
+issuing control transfers these requests. The request type is then
+specified in the wIndex field.

+   
+    
+    
+     
+      
+      
+      
WebUSB Request Codes
Constant
+      Value
+     
(Reserved)
+      1
+     
GET_URL
+      2
+   

+   
4.2.1. Get URL

+   
This request fetches the URL descriptor with the given index.

+   
The device MUST respond with the URL Descriptor at the given
+index or stall the transfer if the index is invalid.

+   
+    
+     
+      
+      
bmRequestType 
+      bRequest
+      wValue
+      wIndex
+      wLength
+      Data
+     
11000000B
+      bVendorCode
+      Descriptor Index
+      GET_URL
+      Descriptor Length
+      Descriptor
+   

+   
4.3. WebUSB Descriptors

+   
These descriptor types are returned by requests defined in this
+specification.

+   
+    
+    
+     
+      
+      
+      
WebUSB Descriptor Types
Constant
+      Value
+     
(Reserved)
+      0-2
+     
WEBUSB_URL
+      3
+   

+   
4.3.1. URL Descriptor

+   
This descriptor contains a single URL and is returned by the Get URL request.

+   
+    
+     
+      
+      
+      
+      
+      
Offset
+      Field
+      Size
+      Value
+      Description
+     
0
+      bLength
+      1
+      Number
+      Size of this descriptor.
+     
1
+      bDescriptorType
+      1
+      Constant
+      WEBUSB_URL.
+     
2
+      bScheme
+      1
+      Number
+      URL scheme prefix.
+     
3
+      URL
+      Variable
+      String
+      UTF-8 encoded URL (excluding the scheme prefix).
+   

+   
The bScheme field MUST be one of these values:

+   
+    
+    
+     
+      
+      
+      
+      
URL Prefixes
Value
+      Prefix
+     
0
+      "http://"
+     
1
+      "https://"
+     
255
+      ""
+   

+   
The special value 255 indicates that the entire URL, including
+scheme, is encoded in the URL field.

+   
5. Device Enumeration

+
dictionary USBDeviceFilter {
+  unsigned short vendorId;
+  unsigned short productId;
+  octet classCode;
+  octet subclassCode;
+  octet protocolCode;
+  DOMString serialNumber;
+};
+
+dictionary USBDeviceRequestOptions {
+  required sequence<USBDeviceFilter> filters;
+};
+
+interface USB : EventTarget {
+  attribute EventHandler onconnect;
+  attribute EventHandler ondisconnect;
+  Promise<sequence<USBDevice>> getDevices();
+  Promise<USBDevice> requestDevice(USBDeviceRequestOptions options);
+};
+
+[SecureContext]
+partial interface Navigator {
+  [SameObject] readonly attribute USB usb;
+};
+

+   

+     In this example, we retrieve some devices to include in a UI. When the page is
+first loaded, it should check if it already has permission to access any
+connected devices by calling getDevices(), 
+
document.addEventListener('DOMContentLoaded', async () => {
+  let devices = await navigator.usb.getDevices();
+  devices.forEach(device => {
+    // Add |device| to the UI.
+  });
+});
+

+    
After the page is loaded the user may connect or disconnect a
+device from their system so script should also register for these events in
+order to keep the interface up-to-date,

+
navigator.usb.addEventListener('connect', device => {
+  // Add |device| to the UI.
+});
+
+navigator.usb.addEventListener('disconnect', device => {
+  // Remove |device| from the UI.
+});
+

+    
If this is the first time the user has visited the page then it won’t have
+permission to access any devices so the page must first call requestDevice() in response to a user gesture. In this case the page
+supports devices from vendor 0xABCD that carry the vendor-specific
+subclass 0x01,

+
let button = document.getElementById('request-device');
+button.addEventListener('click', async () => {
+  let device;
+  try {
+    device = await navigator.usb.requestDevice({ filters: [{
+        vendorId: 0xABCD,
+        classCode: 0xFF, // vendor-specific
+        protocolCode: 0x01
+    }]});
+  } catch () {
+    // No device was selected.
+  }
+
+  if (device !== undefined) {
+    // Add |device| to the UI.
+  }
+});
+

+   

+   
A USB device device matches a filter filter if the following steps return match:

+   
    
+    
  1. 
+     
    Let deviceDesc be device’s device descriptor.
    
+    
  2. 
+     
    If filter.vendorId is present then, if deviceDesc.idVendor does not equal filter.vendorId, return mismatch.
    
+    
  3. 
+     
    If filter.productId is present then, if deviceDesc.idProduct does not equal filter.productId, return mismatch.
    
+    
  4. 
+     
    If filter.classCode is present then,
+ for each of device’s interface’s interface run the following steps:
    
+     
      
+      
    1. 
+       
      Let desc be interface’s interface descriptor.
      
+      
    2. 
+       
      If filter.classCode is present
+  then, if desc.bInterfaceClass is not equal to filter.classCode, continue to
+  the next interface.
      
+      
    3. 
+       
      If filter.subclassCode is present
+  then, if desc.bInterfaceSubClass is not equal to filter.subclassCode, continue to
+  the next interface.
      
+      
    4. 
+       
      If filter.protocolCode is present
+  then, if desc.bInterfaceProtocol is not equal to filter.protocolCode, continue to
+  the next interface.
      
+      
    5. 
+       
      Return match.
      
+     
    
+    
  5. 
+     
    If filter.classCode is present then, if deviceDesc.bDeviceClass is not equal to filter.classCode, return mismatch.
    
+    
  6. 
+     
    If filter.subclassCode is present then,
+ if deviceDesc.bDeviceSubClass is not equal to filter.subclassCode, return mismatch.
    
+    
  7. 
+     
    If filter.protocolCode is present then,
+ if deviceDesc.bDeviceProtocol is not equal to filter.protocolCode, return mismatch.
    
+    
  8. 
+     
    If filter.serialNumber is present then,
+ let serialNumber be the string descriptor with index deviceDesc.iSerialNumber. If device returns an error when
+ requesting serialNumber or serialNumber is not equal to filter.serialNumber, return mismatch.
    
+    
  9. 
+     
    Return match.
    
+   

+   
A USBDeviceFilter filter is valid if the following steps
+return valid:

+   
    
+    
  1. 
+     
    If filter.protocolCode is present then,
+ if filter.subclassCode is not present,
+ return invalid.
    
+    
  2. 
+     
    If filter.subclassCode is present then,
+ if filter.classCode is not present,
+ return invalid.
    
+    
  3. 
+     
    Return valid.
    
+   

+   
The UA MUST be able to enumerate all devices attached to the system.
+It is, however NOT required to perform this work each time an algorithm
+requests an enumeration. The UA MAY cache the result of the first enumeration
+it performs and then begin monitoring for device connection and disconnection
+events, adding connected devices to its cached enumeration and removing
+disconnected devices. This mode of operation is preferred as it reduces the
+number of operating system calls made and amount of bus traffic generated by
+the getDevices() and requestDevice() methods.

+   
The onconnect attribute is an Event handler IDL attribute for the connect event type.

+   
The ondisconnect attribute is an Event handler IDL attribute for the disconnect event type.

+   
The getDevices() method, when invoked, MUST return a new Promise and
+run the following steps in parallel:

+   
    
+    
  1. 
+     
    Enumerate all devices attached to the system. Let this result be enumerationResult.
    
+    
  2. 
+     
    Let devices be a new empty Array.
    
+    
  3. 
+     
    For each device in enumerationResult:
    
+     
      
+      
    1. 
+       
      If this is the first call to this method, check permissions for device.
      
+      
    2. 
+       
      Search for an element allowedDevice in storage.allowedDevices where device is in allowedDevice@[[devices]]. If no such element
+exists, continue to the next device.
      
+      
    3. 
+       
      Add the USBDevice object representing device to devices.
      
+     
    
+    
  4. 
+     
    Resolve promise with devices.
    
+   

+   
The requestDevice() method, when invoked, MUST run the following steps:

+   
    
+    
  1. 
+     
    Request permission to use the following descriptor,
    
+
    {
+  name: "usb"
+  filters: options.filters
+}
+
    
+     
    Let permissionResult be the resulting Promise.
    
+    
  2. 
+     
    Return the result of transforming permissionResult with a
+ fullfillment handler that takes an argument result and runs the following
+ steps:
    
+     
      
+      
    1. 
+       
      If result.devices is empty,
+  throw a NotFoundError and abort these steps.
      
+      
    2. 
+       
      Return result.devices[0].
      
+     
    
+   

+   
To request the "usb" permission, given a USBPermissionStorage storage, a USBPermissionDescriptor options and a USBPermissionResult status, the UA MUST return a new Promise promise and run the following
+steps in parallel:

+   
    
+    
  1. 
+     
    For each filter in options.filters if filter is not a valid filter reject promise with a TypeError and abort these steps.
    
+    
  2. 
+     
    If the algorithm is not triggered by user activation, reject promise with a SecurityError and abort these steps.
    
+    
  3. 
+     
    Set status.state to `"ask"`.
    
+    
  4. 
+     
    Enumerate all devices attached to the system. Let this result be enumerationResult.
    
+    
  5. 
+     
    Remove devices from enumerationResult if they do not match a
+ filter in options.filters.
    
+    
  6. 
+     
    Display a prompt to the user requesting they select a device from enumerationResult. The UA SHOULD show a human-readable name for each
+ device.
    
+    
  7. 
+     
    Wait for the user to have selected a device or cancelled the
+ prompt.
    
+    
  8. 
+     
    If the user cancels the prompt, set status.devices to an empty FrozenArray, resolve promise with undefined,
+ and abort these steps.
    
+    
  9. 
+     
    Add device to storage.
    
+    
  10. 
+     
    Let deviceObj be the USBDevice object representing device.
    
+    
  11. 
+     
    Set status.devices to a new FrozenArray containing deviceObj as its only element.
    
+    
  12. 
+     
    Resolve promise with undefined.
    
+   

+   
To add an allowed USB device device to USBPermissionStorage storage, the UA MUST run the following
+steps:

+   
    
+    
  1. 
+     
    Search for an element allowedDevice in storage.allowedDevices where device is in allowedDevice@[[devices]]. If one is found, abort
+ these steps.
    
+    
  2. 
+     
    Let vendorId and productId be device’s vendor ID and product ID.
    
+    
  3. 
+     
    Let serialNumber be device’s serial number if it has one,
+ otherwise undefined.
    
+    
  4. 
+     
    Append { vendorId: vendorId, productId: productId, serialNumber: serialNumber },
+ with a [[devices]] internal slot containing a single entry device to storage.allowedDevices.
    
+   

+   
To check permissions for a new USB device device, given a USBPermissionStorage storage,
+the UA MUST run the following steps:

+   
    
+    
  1. 
+     
    Let vendorId and productId be device’s vendor ID and product ID.
    
+    
  2. 
+     
    Let serialNumber be device’s if it has one, otherwise undefined.
    
+    
  3. 
+     
    Search for an element allowedDevice in storage.allowedDevices where:
    
+     
      
+      
    • 
+       
      allowedDevice.vendorId equals vendorId.
      
+      
    • 
+       
      allowedDevice.productId equals productId.
      
+      
    • 
+       
      allowedDevice.serialNumber equals serialNumber.
      
+     
    
+    
  4. 
+     
    If no such element exists, return null.
    
+    
  5. 
+     
    Add device to allowedDevice@[[devices]].
    
+    
  6. 
+     
    Return allowedDevice.
    
+   

+   
5.1. Events

+
dictionary USBConnectionEventInit : EventInit {
+    required USBDevice device;
+};
+
+[Constructor(DOMString type, USBConnectionEventInit eventInitDict)]
+interface USBConnectionEvent : Event {
+  [SameObject] readonly attribute USBDevice device;
+};
+

+   
When the UA detects a new USB device device connected to the host it
+MUST perform the following steps for each script execution environment:

+   
    
+    
  1. 
+     
    Let storage be the USBPermissionStorage object in the current
+ script execution environment.
    
+    
  2. 
+     
    Check permissions for device with storage and let allowedDevice be the result.
    
+    
  3. 
+     
    If allowedDevice is null, abort these steps.
    
+    
  4. 
+     
    Let deviceObj be the USBDevice object representing device.
    
+    
  5. 
+     
    Let event be a new USBConnectionEvent, with the device attribute set to deviceObj.
    
+    
  6. 
+     
    Fire an event named connect on usb, using event as the event object.
    
+   

+   
When the UA detects a USB device device has been disconnected from the
+host it MUST perform the following steps for each script execution environment:

+   
    
+    
  1. 
+     
    Let storage be the USBPermissionStorage object in the current
+ script execution environment.
    
+    
  2. 
+     
    Search for an element allowedDevice in storage.allowedDevices where device is in allowedDevice@[[devices]], if no such element exists,
+ abort these steps.
    
+    
  3. 
+     
    Remove device from allowedDevice@[[devices]].
    
+    
  4. 
+     
    If allowedDevice.serialNumber is undefined and allowedDevice@[[devices]] is empty remove allowedDevice from storage.allowedDevices.
    
+    
  5. 
+     
    Let device be the USBDevice object representing device.
    
+    
  6. 
+     
    Let event be a new USBConnectionEvent, with the device attribute set to device.
    
+    
  7. 
+     
    Fire an event named disconnect on usb, using event as the event object.
    
+   

+   
6. Device Usage

+
interface USBDevice {
+  readonly attribute octet usbVersionMajor;
+  readonly attribute octet usbVersionMinor;
+  readonly attribute octet usbVersionSubminor;
+  readonly attribute octet deviceClass;
+  readonly attribute octet deviceSubclass;
+  readonly attribute octet deviceProtocol;
+  readonly attribute unsigned short vendorId;
+  readonly attribute unsigned short productId;
+  readonly attribute octet deviceVersionMajor;
+  readonly attribute octet deviceVersionMinor;
+  readonly attribute octet deviceVersionSubminor;
+  readonly attribute DOMString? manufacturerName;
+  readonly attribute DOMString? productName;
+  readonly attribute DOMString? serialNumber;
+  readonly attribute USBConfiguration? configuration;
+  readonly attribute FrozenArray<USBConfiguration> configurations;
+  readonly attribute boolean opened;
+  Promise<void> open();
+  Promise<void> close();
+  Promise<void> selectConfiguration(octet configurationValue);
+  Promise<void> claimInterface(octet interfaceNumber);
+  Promise<void> releaseInterface(octet interfaceNumber);
+  Promise<void> selectAlternateInterface(octet interfaceNumber, octet alternateSetting);
+  Promise<USBInTransferResult> controlTransferIn(USBControlTransferParameters setup, unsigned short length);
+  Promise<USBOutTransferResult> controlTransferOut(USBControlTransferParameters setup, optional BufferSource data);
+  Promise<void> clearHalt(USBDirection direction, octet endpointNumber);
+  Promise<USBInTransferResult> transferIn(octet endpointNumber, unsigned long length);
+  Promise<USBOutTransferResult> transferOut(octet endpointNumber, BufferSource data);
+  Promise<USBIsochronousInTransferResult> isochronousTransferIn(octet endpointNumber, sequence<unsigned long> packetLengths);
+  Promise<USBIsochronousOutTransferResult> isochronousTransferOut(octet endpointNumber, BufferSource data, sequence<unsigned long> packetLengths);
+  Promise<void> reset();
+};
+

+   
The usbVersionMajor, usbVersionMinor and usbVersionSubminor attributes declare the USB protocol version
+supported by the device. They SHALL correspond to the value of the bcdUSB field of the device descriptor such that a value of 0xJJMN has major version JJ, minor version M and subminor version N.

+   
The deviceClass, deviceSubclass and deviceProtocol attributes declare the communication interface
+supported by the device. They MUST correspond respectively to the values of the bDeviceClass, bDeviceSubClass and bDeviceProtocol fields of the device descriptor.

+   
The vendorId and productId MUST be equal to the
+device’s vendor ID and product ID.

+   
The deviceVersionMajor, deviceVersionMinor and deviceVersionSubminor attributes declare the device release
+number as defined by the device manufacturer. It SHALL correspond to the value
+of the bcdDevice field of the device descriptor such that a
+value of 0xJJMN has major version JJ, minor version M and subminor version N.

+   
The manufacturerName, productName and serialNumber attributes SHOULD contain the values of the string
+descriptors indexed by the iManufacturer, iProduct and iSerialNumber fields of the device descriptor if each is
+defined.

+   
The configuration attribute contains the currently selected
+configuration for the device and SHALL be one of the configurations listed in configurations. It MAY be null if the device is in
+an unconfigured state and MUST be updated by selectConfiguration().

+   
The configurations attribute contains a list of configurations
+supported by the device. These configurations SHALL be populated from the
+configuration descriptors reported by the device and the number of elements in
+this list SHALL match the value of the bNumConfigurations field of
+the device descriptor.

+   
The opened attribute SHALL be set to true when the
+device is opened by the current execution context and SHALL be set to false otherwise.

+   
The open() method, when invoked, MUST return a new Promise promise and run the following steps in parallel:

+   
    
+    
  1. 
+     
    Let device be the target USBDevice object.
    
+    
  2. 
+     
    If device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
    
+    
  3. 
+     
    If device.opened is true resolve promise and abort these steps.
    
+    
  4. 
+     
    Perform the necessary platform-specific steps to begin a session with the
+ device. If these fail for any reason reject promise with a NetworkError and abort these steps.
    
+    
  5. 
+     
    Set device.opened to true and resolve promise.
    
+   

+   
The close() method, when invoked, MUST return a new Promise promise and run the following steps in parallel:

+   
    
+    
  1. 
+     
    Let device be the target USBDevice object.
    
+    
  2. 
+     
    If device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
    
+    
  3. 
+     
    If device.opened is false resolve promise and abort these steps.
    
+    
  4. 
+     
    Abort all other algorithms currently running against this device and reject their associated promises with an AbortError.
    
+    
  5. 
+     
    Perform the necessary platform-specific steps to release any claimed
+ interfaces as if releaseInterface(interfaceNumber) had been
+ called for each claimed interface.
    
+    
  6. 
+     
    Perform the necessary platform-specific steps to end the session with the
+ device.
    
+    
  7. 
+     
    Set device.opened to false and resolve promise.
    
+   

+   
When no [ECMAScript] code can observe an instance of USBDevice device anymore, the UA SHOULD run device.close().

+   
The selectConfiguration(configurationValue) method, when invoked,
+MUST return a new Promise promise and run the following steps in
+parallel:

+   
    
+    
  1. 
+     
    Let device be the target USBDevice object.
    
+    
  2. 
+     
    If device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
    
+    
  3. 
+     
    Let configuration be the device configuration with bConfigurationValue equal to configurationValue. If no such
+ configuration exists, reject promise with a NotFoundError and
+ abort these steps.
    
+    
  4. 
+     
    If device.opened is not equal to true reject promise with an InvalidStateError and
+ abort these steps.
    
+    
  5. 
+     
    Abort all transfers currently scheduled on endpoints other than the default control pipe and reject their associated promises
+ with a AbortError.
    
+    
  6. 
+     
    Issue a SET_CONFIGURATION control transfer to the device to
+ set configurationValue as its active configuration.  If this step
+ fails reject promise with a NetworkError and abort these
+ steps.
    
+    
  7. 
+     
    Set device.configuration to configuration and resolve promise.
    
+   

+   
The claimInterface(interfaceNumber) method, when invoked, MUST
+return a new Promise and run the following steps in parallel:

+   
    
+    
  1. 
+     
    If the device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
    
+    
  2. 
+     
    Let interface be the interface in the active configuration with bInterfaceNumber equal to interfaceNumber. If no such
+ interface exists, reject promise with a NotFoundError and
+ abort these steps.
    
+    
  3. 
+     
    If device.opened is not true and interface.claimed is not false, reject promise with an InvalidStateError and abort these
+ steps.
    
+    
  4. 
+     
    Perform the necessary platform-specific steps to request exclusive control
+ over interface. If this fails, reject promise with a NetworkError and abort these steps.
    
+    
  5. 
+     
    Set interface.claimed to true and resolve promise.
    
+   

+   
The releaseInterface(interfaceNumber) method, when invoked, MUST
+return a new Promise promise and run the following steps in
+parallel:

+   
    
+    
  1. 
+     
    Let device be the target USBDevice object.
    
+    
  2. 
+     
    If device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
    
+    
  3. 
+     
    Let interface be the interface in the active configuration with bInterfaceNumber equal to interfaceNumber. If no such
+ interface exists, reject promise with a NotFoundError and
+ abort these steps.
    
+    
  4. 
+     
    If device.opened or interface.claimed is not true, reject promise with an InvalidStateError and abort these
+ steps.
    
+    
  5. 
+     
    Perform the necessary platform-specific steps to reliquish exclusive
+ control over interface.
    
+    
  6. 
+     
    Set interface.claimed to false and resolve promise.
    
+   

+   
The selectAlternateInterface(interfaceNumber, alternateSetting) method, when invoked, MUST return a new Promise promise and run the
+following steps in parallel:

+   
    
+    
  1. 
+     
    Let device be the target USBDevice object.
    
+    
  2. 
+     
    If device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
    
+    
  3. 
+     
    Let interface be the interface in the active configuration with bInterfaceNumber equal to interfaceNumber. If no such
+ interface exists, reject promise with a NotFoundError and
+ abort these steps.
    
+    
  4. 
+     
    If device.opened or interface.claimed is not true, reject promise with an InvalidStateError and abort these
+ steps.
    
+    
  5. 
+     
    Abort all transfers currently scheduled on endpoints associated with the
+ previously selected alternate setting of interface and reject their associated promises with a AbortError.
    
+    
  6. 
+     
    Issue a SET_INTERFACE control transfer to the device to set alternateSetting as the current configuration of interface. If this
+ step fails reject promise with a NetworkError and abort these
+ steps.
    
+    
  7. 
+     
    Resolve promise.
    
+   

+   
The controlTransferIn(setup, length) method, when invoked, MUST
+return a new Promise promise and run the following steps in
+parallel:

+   
    
+    
  1. 
+     
    Let device be the target USBDevice object.
    
+    
  2. 
+     
    If device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
    
+    
  3. 
+     
    If device.opened is not equal to true reject promise with an InvalidStateError and abort these steps.
    
+    
  4. 
+     
    Check the validity of the control transfer parameters and abort
+ these steps if promise is rejected.
    
+    
  5. 
+     
    If length is greater than the wMaxPacketSize0 field of the
+ device’s device descriptor, reject promise with a TypeError and abort these steps.
    
+    
  6. 
+     
    Let result be a new USBInTransferResult and let buffer be a new ArrayBuffer of length bytes.
    
+    
  7. 
+     
    Issue a control transfer with the setup packet parameters provided in setup and the data transfer direction in bmRequestType set
+ to "device to host" and wLength set to length.
    
+    
  8. 
+     
    If the device responds with data, store the first length bytes of this
+ data in buffer and set result.data to a new DataView constructed over buffer.
    
+    
  9. 
+     
    If the device responds by stalling the default control pipe set result.status to "stall".
    
+    
  10. 
+     
    If more than length bytes are received set result.status to "babble" and
+  otherwise set it to "ok".
    
+    
  11. 
+     
    If the transfer fails for any other reason reject promise with a NetworkError and abort these steps.
    
+    
  12. 
+     
    Resolve promise with result.
    
+   

+   
The controlTransferOut(setup, data) method, when invoked, must
+return a new Promise promise and run the following steps in
+parallel:

+   
    
+    
  1. 
+     
    If the device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
    
+    
  2. 
+     
    If device.opened is not equal to true reject promise with an InvalidStateError and
+ abort these
+ steps.
    
+    
  3. 
+     
    Check the validity of the control transfer parameters and abort
+ these steps if promise is rejected.
    
+    
  4. 
+     
    If data.length is greater than the wMaxPacketSize0 field of the device’s device
+ descriptor, reject promise with a TypeError and abort
+ these steps.
    
+    
  5. 
+     
    Issue a control transfer with the setup packet populated by setup and the data transfer direction in bmRequestType set to "host
+ to device" and wLength set to data.length.
+ Transmit data in the data stage of the transfer.
    
+    
  6. 
+     
    Let result be a new USBOutTransferResult.
    
+    
  7. 
+     
    If the device responds by stalling the default control pipe set result.status to "stall".
    
+    
  8. 
+     
    If the device acknowledges the transfer set result.status to "ok" and result.{{USBOutTransferResult/bytesWritten to data.length.
    
+    
  9. 
+     
    If the transfer fails for any other reason reject promise with a NetworkError and abort these steps.
    
+    
  10. 
+     
    Resolve promise with result.
    
+   

+   
The clearHalt(direction, endpointNumber) method, when invoked,
+MUST return a new Promise promise and run the following steps in
+parallel:

+   
    
+    
  1. 
+     
    If the device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
    
+    
  2. 
+     
    Let endpoint be the endpoint in the active configuration with bEndpointAddress corresponding to direction and endpointNumber. If no such endpoint exists reject promise and
+ abort these steps.
    
+    
  3. 
+     
    If device.opened or interface.claimed is not true, reject promise with an InvalidStateError and abort these
+ steps.
    
+    
  4. 
+     
    Issue a CLEAR_FEATURE control transfer to the device to clear
+ the stall condition on endpoint.
    
+    
  5. 
+     
    On failure reject promise with a NetworkError, otherwise resolve promise.
    
+   

+   
The transferIn(endpointNumber, length) method, when invoked, MUST
+return a new Promise promise and run the following steps in
+parallel:

+   
    
+    
  1. 
+     
    If the device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
    
+    
  2. 
+     
    Let endpoint be the IN endpoint in the active configuration with bEndpointAddress corresponding to endpointNumber. If there
+ is no such endpoint reject promise with a NotFoundError and
+ abort these steps.
    
+    
  3. 
+     
    If endpoint is not a bulk or interrupt endpoint reject promise with an InvalidAccessError and abort these steps.
    
+    
  4. 
+     
    If device.opened or interface.claimed is not true, reject promise with an InvalidStateError and abort these
+ steps.
    
+    
  5. 
+     
    As appropriate for endpoint enqueue a bulk or interrupt IN transfer on endpoint with a buffer sufficient to receive length bytes of data from
+ the device.
    
+    
  6. 
+     
    Let result be a new USBInTransferResult.
    
+    
  7. 
+     
    If data is returned as part of this transfer let buffer be a new ArrayBuffer of exactly the length of the data received and set result.data to a new DataView constructed over buffer.
    
+    
  8. 
+     
    If the device responds with more than length bytes of data set result.status to "babble".
    
+    
  9. 
+     
    If the transfer ends because endpoint is stalled set result.status to "stall".
    
+    
  10. 
+     
    If the device acknowledges the complete transfer set result.status to "ok".
    
+    
  11. 
+     
    If the transfer fails for any other reason reject promise with a NetworkError and abort these steps.
    
+    
  12. 
+     
    Resolve promise with result.
    
+   

+   
The transferOut(endpointNumber, data) method, when invoked, MUST
+return a new Promise promise and run the following steps in
+parallel:

+   
    
+    
  1. 
+     
    If the device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
    
+    
  2. 
+     
    Let endpoint be the OUT endpoint in the active configuration with bEndpointAddress corresponding to endpointNumber. If there
+ is no such endpoint reject promise with a NotFoundError and
+ abort these steps.
    
+    
  3. 
+     
    If endpoint is not a bulk or interrupt endpoint reject promise with an InvalidAccessError and abort these steps.
    
+    
  4. 
+     
    If device.opened or interface.claimed is not true, reject promise with an InvalidStateError and abort these
+ steps.
    
+    
  5. 
+     
    As appropriate for endpoint enqueue a bulk or interrupt OUT transfer on endpoint to transmit data to the device.
    
+    
  6. 
+     
    Let result be a new USBOutTransferResult.
    
+    
  7. 
+     
    Set result.bytesWritten to the
+ amount of data successfully sent to the device.
    
+    
  8. 
+     
    If the endpoint is stalled set result.status to "stall".
    
+    
  9. 
+     
    If the device acknowledges the complete transfer set result.status to "ok".
    
+    
  10. 
+     
    If the transfer fails for any other reason reject promise with a NetworkError and abort these steps.
    
+    
  11. 
+     
    Resolve promise with result.
    
+   

+   
The isochronousTransferIn(endpointNumber, packetLengths) method,
+when invoked, MUST return a new Promise promise and run the following
+steps in parallel:

+   
    
+    
  1. 
+     
    If the device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
    
+    
  2. 
+     
    Let endpoint be the IN endpoint in the active configuration with bEndpointAddress corresponding to endpointNumber. If there
+ is no such endpoint reject promise with a NotFoundError and
+ abort these steps.
    
+    
  3. 
+     
    If endpoint is not an isochronous endpoint reject promise with
+ an InvalidAccessError and abort these steps.
    
+    
  4. 
+     
    If device.opened or interface.claimed is not true, reject promise with an InvalidStateError and abort these
+ steps.
    
+    
  5. 
+     
    Let length be the sum of the elements of packetLengths.
    
+    
  6. 
+     
    Let buffer be a new ArrayBuffer of length bytes.
    
+    
  7. 
+     
    Let result be a new USBIsochronousInTransferResult and set result.data to a new DataView constructed over buffer.
    
+    
  8. 
+     
    Enqueue an isochronous IN transfer on endpoint that will write up to length bytes of data from the device into buffer.
    
+    
  9. 
+     
    For each packet i from 0 to packetLengths.length -
+ 1:
    
+     
      
+      
    1. 
+       
      Let packet be a new USBIsochronousInTransferPacket and set result.packets[i] to packet.
      
+      
    2. 
+       
      Let view be a new DataView over the portion of buffer containing the data received from the device for this packet and set packet.data to view.
      
+      
    3. 
+       
      If the device responds with more than packetLengths[i] bytes of data set packet.status to "babble".
      
+      
    4. 
+       
      If the transfer ends because endpoint is stalled set packet.status to "stall".
      
+      
    5. 
+       
      If the device acknowledges the complete transfer set packet.status to "ok".
      
+      
    6. 
+       
      If the transfer fails for any other reason reject promise with a NetworkError and abort these steps.
      
+     
    
+    
  10. 
+     
    Resolve promise with result.
    
+   

+   
The isochronousTransferOut(endpointNumber, data, packetLengths) method, when invoked, MUST return a new Promise promise and run the
+following steps in parallel:

+   
    
+    
  1. 
+     
    If the device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
    
+    
  2. 
+     
    Let endpoint be the OUT endpoint in the active configuration with bEndpointAddress corresponding to endpointNumber. If there
+ is no such endpoint reject promise with a NotFoundError and
+ abort these steps.
    
+    
  3. 
+     
    If endpoint is not an isochronous endpoint reject promise with
+ an InvalidAccessError and abort these steps.
    
+    
  4. 
+     
    If device.opened or interface.claimed is not true, reject promise with an InvalidStateError and abort these
+ steps.
    
+    
  5. 
+     
    Let length be the sum of the elements of packetLengths.
    
+    
  6. 
+     
    Let result be a new USBIsochronousOutTransferResult.
    
+    
  7. 
+     
    Enqueue an isochronous OUT transfer on endpoint that will write buffer to the device, divided into packetLength.length packets of packetLength[i] bytes (for packets i from 0 to packetLengths.length - 1).
    
+    
  8. 
+     
    For each packet i from 0 to packetLengths.length -
+ 1 the host attempts to send to the device:
    
+     
      
+      
    1. 
+       
      Let packet be a new USBIsochronousOutTransferPacket and set result.packets[i] to packet.
      
+      
    2. 
+       
      Let packet.bytesWritten be the amount of data successfully sent to the device as part of this
+  packet.
      
+      
    3. 
+       
      If the transfer ends because endpoint is stalled set packet.status to "stall".
      
+      
    4. 
+       
      If the device acknowledges the complete transfer set packet.status to "ok".
      
+      
    5. 
+       
      If the transfer fails for any other reason reject promise with a NetworkError and abort these steps.
      
+     
    
+    
  9. 
+     
    Resolve promise with result.
    
+   

+   
The reset() method, when invoked, MUST return a new Promise promise and run the following steps in parallel:

+   
    
+    
  1. 
+     
    Let device be the target USBDevice object.
    
+    
  2. 
+     
    If device is no longer connected to the system, reject promise with a NotFoundError and abort these steps.
    
+    
  3. 
+     
    If device.opened is not equal to true reject promise with an InvalidStateError and
+ abort these steps.
    
+    
  4. 
+     
    Abort all operations on the device and reject their associated
+ promises with an AbortError.
    
+    
  5. 
+     
    Perform the necessary platform-specific operation to soft reset the device.
    
+    
  6. 
+     
    On failure reject promise with a NetworkError, otherwise resolve promise.
    
+   

+   
 What configuration is the device in after it resets? <https://github.com/WICG/webusb/issues/36>

+   
6.1. Transfers

+
enum USBRequestType {
+  "standard",
+  "class",
+  "vendor"
+};
+
+enum USBRecipient {
+  "device",
+  "interface",
+  "endpoint",
+  "other"
+};
+
+enum USBTransferStatus {
+  "ok",
+  "stall",
+  "babble"
+};
+
+dictionary USBControlTransferParameters {
+  required USBRequestType requestType;
+  required USBRecipient recipient;
+  required octet request;
+  required unsigned short value;
+  required unsigned short index;
+};
+
+[Constructor(USBTransferStatus status, optional DataView? data)]
+interface USBInTransferResult {
+  readonly attribute DataView? data;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(USBTransferStatus status, optional unsigned long bytesWritten = 0)]
+interface USBOutTransferResult {
+  readonly attribute unsigned long bytesWritten;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(USBTransferStatus status, optional DataView? data)]
+interface USBIsochronousInTransferPacket {
+  readonly attribute DataView? data;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(sequence<USBIsochronousInTransferPacket> packets, optional DataView? data)]
+interface USBIsochronousInTransferResult {
+  readonly attribute DataView? data;
+  readonly attribute FrozenArray<USBIsochronousInTransferPacket> packets;
+};
+
+[Constructor(USBTransferStatus status, optional unsigned long bytesWritten = 0)]
+interface USBIsochronousOutTransferPacket {
+  readonly attribute unsigned long bytesWritten;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(sequence<USBIsochronousOutTransferPacket> packets)]
+interface USBIsochronousOutTransferResult {
+  readonly attribute FrozenArray<USBIsochronousOutTransferPacket> packets;
+};
+

+   
A control transfer is a special class of USB traffic most commonly
+used for configuring a device. It consists of three stages: setup, data and
+status. In the setup stage a setup packet is transmitted
+to the device containing request parameters including the transfer direction
+and size of the data to follow. In the data stage that data is
+either sent to or received from the device. In the status stage successful handling of the request is acknowledged or a failure is signaled.

+   
All USB devices MUST have a default control pipe which is endpointNumber 0.

+   
The requestType attribute populates part of
+the bmRequestType field of the setup packet to indicate
+whether this request is part of the USB standard, a particular USB device class
+specification or a vendor-specific protocol.

+   
The recipient attribute populates part of the bmRequestType field of the setup packet to indicate whether
+the control transfer is addressed to the entire device, or a specific interface
+or endpoint.

+   
The request attribute populates the bRequest field of the setup packet. Valid requests are
+defined by the USB standard, USB device class specifications or the device
+vendor.

+   
The value and index attributes populate the wValue and wIndex fields of the setup packet respectively. The meaning of these fields depends on the request being made.

+   
To check the validity of the control transfer parameters perform the following steps:

+   
    
+    
  1. 
+     
    Let setup be the USBControlTransferParameters created for the
+ transfer.
    
+    
  2. 
+     
    Let promise be the promise created for the transfer.
    
+    
  3. 
+     
    Let configuration be the active configuration. If the device is
+ not configured abort these steps.
    
+    
  4. 
+     
    If setup.recipient is "interface", perform the following steps:
    
+     
      
+      
    1. 
+       
      Let interfaceNumber be the lower 8 bits of setup.index.
      
+      
    2. 
+       
      Let interface be the interface in the | configuration| with bInterfaceNumber equal to interfaceNumber. If no such
+  interface exists, reject promise with a NotFoundError and
+  abort these steps.
      
+      
    3. 
+       
      If interface.claimed is not equal to true, reject promise with an InvalidStateError and abort these steps.
      
+     
    
+    
  5. 
+     
    If setup.recipient is "endpoint", run the following steps:
    
+     
      
+      
    1. 
+       
      Let endpointNumber be defined as the lower 4 bits of setup.index.
      
+      
    2. 
+       
      Let direction be defined as "in" if the 8th bit of setup.index is 1 and "out" otherwise.
      
+      
    3. 
+       
      Let endpoint be the endpoint in the active configuration with bEndpointAddress corresponding to direction and endpointNumber. If no such endpoint exists, reject promise with a NotFoundError and abort these steps.
      
+      
    4. 
+       
      Let interface be the interface in which endpoint is defined. If interface.claimed is not equal to true, reject promise with an InvalidStateError.
      
+     
    
+   

+   
6.2. Configurations

+
[Constructor(USBDevice device, octet configurationValue)]
+interface USBConfiguration {
+  readonly attribute octet configurationValue;
+  readonly attribute DOMString? configurationName;
+  readonly attribute FrozenArray<USBInterface> interfaces;
+};
+

+   
Each device configuration SHALL have a unique configurationValue that matches the bConfigurationValue fields of the configuration descriptor that defines it.

+   
The configurationName attribute SHOULD contain the value
+of the string descriptor referenced by the iConfiguration field of the configuration descriptor, if defined.

+   
The interfaces attribute SHALL contain a list of
+interfaces exposed by this device configuration. These interfaces SHALL by
+populated by collecting the interface descriptors contained within this configuration descriptor and organizing them by bInterfaceNumber.

+   
 Include some non-normative information about device configurations. <https://github.com/WICG/webusb/issues/46>

+   
6.3. Interfaces

+
[Constructor(USBConfiguration configuration, octet interfaceNumber)]
+interface USBInterface {
+  readonly attribute octet interfaceNumber;
+  readonly attribute USBAlternateInterface alternate;
+  readonly attribute FrozenArray<USBAlternateInterface> alternates;
+  readonly attribute boolean claimed;
+};
+
+[Constructor(USBInterface deviceInterface, octet alternateSetting)]
+interface USBAlternateInterface {
+  readonly attribute octet alternateSetting;
+  readonly attribute octet interfaceClass;
+  readonly attribute octet interfaceSubclass;
+  readonly attribute octet interfaceProtocol;
+  readonly attribute DOMString? interfaceName;
+  readonly attribute FrozenArray<USBEndpoint> endpoints;
+};
+

+   
Each interface provides a collection of alternates identified
+by a single bInterfaceNumber field found in their interface
+descriptors. The interfaceNumber attribute MUST match this
+field.

+   
The alternate attribute SHALL be set to the USBAlternateInterface that is currently selected for this interface, which
+by default SHALL be the one with bAlternateSetting equal to 0.

+   
The alternates attribute SHALL contain a list of all alternate
+interface configurations available for this interface.

+   
The claimed attribute SHALL be set to true when
+the interface is claimed by the current execution context and SHALL be set to false otherwise.

+   
Each alternative interface configuration SHALL have a unique alternateSetting within a given interface that
+matches the bAlternateSetting field of the interface
+descriptor that defines it.

+   
The interfaceClass, interfaceSubclass and interfaceProtocol attributes declare the
+communication interface supported by the interface. They MUST correspond
+respectively to the values of the bInterfaceClass, bInterfaceSubClass and bInterfaceProtocol fields of
+the interface descriptor.

+   
The interfaceName attribute SHOULD contain the value
+of the string descriptor indexed by the iInterface field of
+the interface descriptor, if defined.

+   
The endpoints attribute SHALL contain a list of
+endpoints exposed by this interface. These endpoints SHALL by populated from
+the endpoint descriptors contained within this interface descriptor and
+the number of elements in this sequence SHALL match the value of the bNumEndpoints field of the interface descriptor.

+   
A device’s active configuration is the combination of the USBConfiguration selected by calling selectConfiguration(configurationValue) and the set of USBAlternateInterfaces selected by calling selectAlternateInterface(interfaceNumber, alternateSetting).  A
+device MAY, by default, be left in an unconfigured state, referred to as
+configuration 0 or may automatically be set to whatever
+configuration has bConfigurationValue equal to 1.
+When a configuration is set all interfaces within that configuration
+automatically have the USBAlternateInterface with bAlternateSetting equal to 0 selected by default. It
+is therefore unnecessary to call selectAlternateInterface(interfaceNumber, alternateSetting) with alternateSetting equal to 0 for each interface when opening a
+device.

+   
6.4. Endpoints

+
enum USBDirection {
+  "in",
+  "out"
+};
+
+enum USBEndpointType {
+  "bulk",
+  "interrupt",
+  "isochronous"
+};
+
+[Constructor(USBAlternateInterface alternate, octet endpointNumber, USBDirection direction)]
+interface USBEndpoint {
+  readonly attribute octet endpointNumber;
+  readonly attribute USBDirection direction;
+  readonly attribute USBEndpointType type;
+  readonly attribute unsigned long packetSize;
+};
+

+   
Each endpoint within a particular device configuration SHALL have a unique
+combination of endpointNumber and direction.
+The endpointNumber MUST equal the 4 least significant bits of
+the bEndpointAddress field of the endpoint descriptor defining the endpoint.

+   
The direction attribute declares the transfer direction
+supported by this endpoint and is equal to "in" if the most
+significant bit of the bEndpointAddress is set and "out" otherwise. An endpoint may either carry data IN from the device to host or OUT from host to device.

+   
The type attribute declares the type of data transfer supported
+by this endpoint.

+   
The packetSize attribute declares the packet size employed by
+this endpoint and MUST be equal to the value of the wMaxPacketSize of the endpoint descriptor defining it. In a High-Speed, High-Bandwidth
+endpoint this value will include the multiplication factor provided by issuing
+multiple transactions per microframe. In a SuperSpeed device this value will
+include the multiplication factor provided by the bMaxBurst field
+of the SuperSpeed Endpoint Companion descriptor.

+   
7. Integrations

+   
7.1. Feature Policy

+   
This specification defines a feature that controls whether the usb attribute is exposed on the Navigator object.

+   
The feature name for this feature is "usb".

+   
The default allowlist for this feature is ["self"].

+   
7.2. Permission API

+   
The [permissions] API provides a uniform way for websites to request
+permissions from users and query which permissions they have.

+   
The "usb" powerful feature is
+defined as follows:

+   

+    
permission descriptor type
+    

+
dictionary USBPermissionDescriptor : PermissionDescriptor {
+  sequence<USBDeviceFilter> filters;
+};
+

+    
extra permission data type
+    

+      USBPermissionStorage, defined as: 
+
dictionary AllowedUSBDevice {
+  required octet vendorId;
+  required octet productId;
+  DOMString serialNumber;
+};
+
+dictionary USBPermissionStorage {
+  required sequence<AllowedUSBDevice> allowedDevices = [];
+};
+

+     
AllowedUSBDevice instances have an internal slot [[devices]] that holds an
+    array of USB devices.

+    
permission result type
+    

+
interface USBPermissionResult : PermissionStatus {
+  attribute FrozenArray<USBDevice> devices;
+};
+

+    
permission query algorithm
+    

+      To query the "usb" permission with a USBPermissionDescriptor desc, a USBPermissionStorage storage, and a USBPermissionResult status, the UA must: 
+     
    
+      
  1. 
+       
    If desc.filters is set then,
+ for each filter in desc.filters if filter is not a valid filter then raise a TypeError and abort these
+ steps.
    
+      
  2. 
+       
    Set status.state to "prompt".
    
+      
  3. 
+       
    Let matchingDevices be a new Array.
    
+      
  4. 
+       
    For each allowedDevice in storage.allowedDevices and
+ for each device in allowedDevice@[[devices]], run
+ the following substeps:
    
+       
      
+        
    1. 
+         
      If desc.filters is set
+  and device does not match a filter in desc.filters, continue
+  to the next device.
      
+        
    2. 
+         
      Get the USBDevice representing device and add it to matchingDevices.
      
+       
    
+      
  5. 
+       
    Set status.devices to a new FrozenArray whose contents are matchingDevices.
    
+     

+    
permission request algorithm
+    
Request the "usb" permission.
+   

+   
8. Terminology

+   
This specification uses several terms taken from [USB31]. While
+reference is made to version 3.1 of the Universal Serial Bus many of
+these concepts exist in previous versions as well. Significant
+differences between USB versions that have bearing on this specification
+will be called out explicitly.

+   
Descriptors are binary data structures that can be read from
+a device and describe its properties and function:

+   
    
+    
  • 
+     
    The device descriptor contains information applicable to
+the entire devices and is described in section 9.6.1 of [USB31].
    
+    
  • 
+     
    A configuration descriptor describes a particular set of
+device interfaces and endpoints that can be selected by the host.
+Its fields are described in section 9.6.3 of [USB31].
    
+    
  • 
+     
    An interface descriptor describes the interface of a particular
+functional component of a device including its protocol and communication
+endpoints. Its fields are described in section 9.6.5 of [USB31].
    
+    
  • 
+     
    An interface association descriptor creates an
+association between multiple interfaces that are part of a single
+functional unit of a device. Its fields are described in section
+9.6.4 of [USB31].
    
+    
  • 
+     
    An endpoint descriptor describes a channel through which
+data is either sent to or received from the device. Its fields are
+described in section 9.6.6 of [USB31].
    
+    
  • 
+     
    A string descriptor contains a single UTF16-LE string and is
+referenced by index by other descriptors. Its fields are described in
+section 9.6.9 of [USB31].
    
+   

+   
The Binary Object Store (BOS) is an additional set of
+descriptors that are more free-form than the standard device
+descriptors. Of note is the Platform Descriptor type which
+allows third parties (such as this specification) to declare their own
+types of descriptors. Each of these is identified by a UUID. The Binary
+Object Store is described in section 9.6.2 of [USB31].

+   
A USB device has a single device descriptor which links to
+one or more configuration descriptors. It’s vendor ID is
+assigned to the device manufacturer by the USB-IF and is stored in the idVendor field of the device descriptor. It’s product
+ID is assigned by the manufacturer and is stored in the idProduct field of the device descriptor. It’s serial
+number is an optional property that is defined if the iSerialNumber field of the device descriptor is not equal
+to 0 and is the string descriptor referred to by that index.

+   
9. Appendix: A Brief Introduction to USB

+   
This section is non-normative.

+   
USB is a network but it’s very different from traditional TCP/IP networks. It is
+really more like an RPC system. All traffic is directed by the host, that is,
+your computer. Though some devices like smartphones can act as both a USB host
+and USB client they can only take on one role at a time.

+   
9.1. Descriptors

+   
USB devices identify themselves to the host by providing a set of binary
+structures known as descriptors. The first one read by the host is the device descriptor which contains basic information such as the vendor and
+product IDs assigned by the USB-IF and the manufacturer. The host may then read
+the device’s configuration descriptor which is a description of the
+device’s capabilities including the interfaces and endpoints it exposes. A class
+can be declared at the device level or for individual interfaces. A device with
+multiple interfaces providing different functions is known as a composite device.

+   
9.2. Transfers

+   
Whether data is traveling from host to device or the other way around the
+transfer is always initiated by the host. OUT transfers carry data
+from host to device and may wait until the device acknowledges the data has been
+received. IN transfers carry data from device to host and may have to
+wait until the device has some data to send. Transfers are executed against one
+of a device’s endpoints and there are different kinds depending on what type of
+traffic is being sent.

+   
    
+    
  • 
+     
    Bulk transfers are good for sending lots of data with whatever
+bandwidth is available. This is what is used to read and write data to USB
+mass storage devices.
    
+    
  • 
+     
    Interrupt transfers offer guaranteed latency (by reserving
+bandwidth so that they can’t be blocked by a large bulk transfers) but with
+limited packet sizes. These are used for signaling and for small packets like
+mouse movements and button presses.
    
+    
  • 
+     
    Isochronous transfers also reserve bandwidth but they don’t
+guarantee delivery. They’re used for streaming data like audio and video.
    
+    
  • 
+     
    Every device also has a special default endpoint. While regular
+endpoints only carry data in one direction or the other control transfers have a small header called the SETUP packet that is always sent to the device and contains request
+parameters in addition to a larger data payload that can be either IN or OUT.
    
+   

+  

+  

+   
 Conformance

+   
 Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology.
+            The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”
+            in the normative parts of this document
+            are to be interpreted as described in RFC 2119.
+            However, for readability,
+            these words do not appear in all uppercase letters in this specification. 

+   
 All of the text of this specification is normative
+            except sections explicitly marked as non-normative, examples, and notes. [RFC2119] 

+   
 Examples in this specification are introduced with the words “for example”
+            or are set apart from the normative text with class="example", like this: 

+   
 This is an example of an informative example. 

+   
 Informative notes begin with the word “Note”
+            and are set apart from the normative text with class="note", like this: 

+   
 Note, this is an informative note. 

+  

+
+  
Index

+  
Terms defined by this specification

+  
+  
Terms defined by reference

+  
+  
References

+  
Normative References

+  

+   
[DOM]
+   
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
+   
[ECMAScript]
+   
ECMAScript Language Specification. URL: https://tc39.github.io/ecma262/
+   
[HTML]
+   
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
+   
[PERMISSIONS]
+   
Mounir Lamouri; Marcos Caceres. The Permissions API. URL: https://www.w3.org/TR/permissions/
+   
[PROMISES-GUIDE]
+   
Domenic Denicola. Writing Promise-Using Specifications. 16 February 2016. Finding of the W3C TAG. URL: https://www.w3.org/2001/tag/doc/promises-guide
+   
[RFC2119]
+   
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
+   
[USB31]
+   
Universal Serial Bus 3.1 Specification. 26 July 2013. URL: http://www.usb.org/developers/docs/
+   
[WebIDL]
+   
Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. URL: https://heycam.github.io/webidl/
+  

+  
Informative References

+  

+   
[CORS]
+   
Anne van Kesteren. Cross-Origin Resource Sharing. 16 January 2014. REC. URL: https://www.w3.org/TR/cors/
+   
[POWERFUL-FEATURES]
+   
Mike West. Secure Contexts. URL: https://www.w3.org/TR/secure-contexts/
+  

+  
IDL Index

+
dictionary USBDeviceFilter {
+  unsigned short vendorId;
+  unsigned short productId;
+  octet classCode;
+  octet subclassCode;
+  octet protocolCode;
+  DOMString serialNumber;
+};
+
+dictionary USBDeviceRequestOptions {
+  required sequence<USBDeviceFilter> filters;
+};
+
+interface USB : EventTarget {
+  attribute EventHandler onconnect;
+  attribute EventHandler ondisconnect;
+  Promise<sequence<USBDevice>> getDevices();
+  Promise<USBDevice> requestDevice(USBDeviceRequestOptions options);
+};
+
+[SecureContext]
+partial interface Navigator {
+  [SameObject] readonly attribute USB usb;
+};
+
+dictionary USBConnectionEventInit : EventInit {
+    required USBDevice device;
+};
+
+[Constructor(DOMString type, USBConnectionEventInit eventInitDict)]
+interface USBConnectionEvent : Event {
+  [SameObject] readonly attribute USBDevice device;
+};
+
+interface USBDevice {
+  readonly attribute octet usbVersionMajor;
+  readonly attribute octet usbVersionMinor;
+  readonly attribute octet usbVersionSubminor;
+  readonly attribute octet deviceClass;
+  readonly attribute octet deviceSubclass;
+  readonly attribute octet deviceProtocol;
+  readonly attribute unsigned short vendorId;
+  readonly attribute unsigned short productId;
+  readonly attribute octet deviceVersionMajor;
+  readonly attribute octet deviceVersionMinor;
+  readonly attribute octet deviceVersionSubminor;
+  readonly attribute DOMString? manufacturerName;
+  readonly attribute DOMString? productName;
+  readonly attribute DOMString? serialNumber;
+  readonly attribute USBConfiguration? configuration;
+  readonly attribute FrozenArray<USBConfiguration> configurations;
+  readonly attribute boolean opened;
+  Promise<void> open();
+  Promise<void> close();
+  Promise<void> selectConfiguration(octet configurationValue);
+  Promise<void> claimInterface(octet interfaceNumber);
+  Promise<void> releaseInterface(octet interfaceNumber);
+  Promise<void> selectAlternateInterface(octet interfaceNumber, octet alternateSetting);
+  Promise<USBInTransferResult> controlTransferIn(USBControlTransferParameters setup, unsigned short length);
+  Promise<USBOutTransferResult> controlTransferOut(USBControlTransferParameters setup, optional BufferSource data);
+  Promise<void> clearHalt(USBDirection direction, octet endpointNumber);
+  Promise<USBInTransferResult> transferIn(octet endpointNumber, unsigned long length);
+  Promise<USBOutTransferResult> transferOut(octet endpointNumber, BufferSource data);
+  Promise<USBIsochronousInTransferResult> isochronousTransferIn(octet endpointNumber, sequence<unsigned long> packetLengths);
+  Promise<USBIsochronousOutTransferResult> isochronousTransferOut(octet endpointNumber, BufferSource data, sequence<unsigned long> packetLengths);
+  Promise<void> reset();
+};
+
+enum USBRequestType {
+  "standard",
+  "class",
+  "vendor"
+};
+
+enum USBRecipient {
+  "device",
+  "interface",
+  "endpoint",
+  "other"
+};
+
+enum USBTransferStatus {
+  "ok",
+  "stall",
+  "babble"
+};
+
+dictionary USBControlTransferParameters {
+  required USBRequestType requestType;
+  required USBRecipient recipient;
+  required octet request;
+  required unsigned short value;
+  required unsigned short index;
+};
+
+[Constructor(USBTransferStatus status, optional DataView? data)]
+interface USBInTransferResult {
+  readonly attribute DataView? data;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(USBTransferStatus status, optional unsigned long bytesWritten = 0)]
+interface USBOutTransferResult {
+  readonly attribute unsigned long bytesWritten;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(USBTransferStatus status, optional DataView? data)]
+interface USBIsochronousInTransferPacket {
+  readonly attribute DataView? data;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(sequence<USBIsochronousInTransferPacket> packets, optional DataView? data)]
+interface USBIsochronousInTransferResult {
+  readonly attribute DataView? data;
+  readonly attribute FrozenArray<USBIsochronousInTransferPacket> packets;
+};
+
+[Constructor(USBTransferStatus status, optional unsigned long bytesWritten = 0)]
+interface USBIsochronousOutTransferPacket {
+  readonly attribute unsigned long bytesWritten;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(sequence<USBIsochronousOutTransferPacket> packets)]
+interface USBIsochronousOutTransferResult {
+  readonly attribute FrozenArray<USBIsochronousOutTransferPacket> packets;
+};
+
+[Constructor(USBDevice device, octet configurationValue)]
+interface USBConfiguration {
+  readonly attribute octet configurationValue;
+  readonly attribute DOMString? configurationName;
+  readonly attribute FrozenArray<USBInterface> interfaces;
+};
+
+[Constructor(USBConfiguration configuration, octet interfaceNumber)]
+interface USBInterface {
+  readonly attribute octet interfaceNumber;
+  readonly attribute USBAlternateInterface alternate;
+  readonly attribute FrozenArray<USBAlternateInterface> alternates;
+  readonly attribute boolean claimed;
+};
+
+[Constructor(USBInterface deviceInterface, octet alternateSetting)]
+interface USBAlternateInterface {
+  readonly attribute octet alternateSetting;
+  readonly attribute octet interfaceClass;
+  readonly attribute octet interfaceSubclass;
+  readonly attribute octet interfaceProtocol;
+  readonly attribute DOMString? interfaceName;
+  readonly attribute FrozenArray<USBEndpoint> endpoints;
+};
+
+enum USBDirection {
+  "in",
+  "out"
+};
+
+enum USBEndpointType {
+  "bulk",
+  "interrupt",
+  "isochronous"
+};
+
+[Constructor(USBAlternateInterface alternate, octet endpointNumber, USBDirection direction)]
+interface USBEndpoint {
+  readonly attribute octet endpointNumber;
+  readonly attribute USBDirection direction;
+  readonly attribute USBEndpointType type;
+  readonly attribute unsigned long packetSize;
+};
+
+dictionary USBPermissionDescriptor : PermissionDescriptor {
+  sequence<USBDeviceFilter> filters;
+};
+
+dictionary AllowedUSBDevice {
+  required octet vendorId;
+  required octet productId;
+  DOMString serialNumber;
+};
+
+dictionary USBPermissionStorage {
+  required sequence<AllowedUSBDevice> allowedDevices = [];
+};
+
+interface USBPermissionResult : PermissionStatus {
+  attribute FrozenArray<USBDevice> devices;
+};
+
+

+  
Issues Index

+  

+   
 What configuration is the device in after it resets? <https://github.com/WICG/webusb/issues/36> ↵ 

+   
 Include some non-normative information about device configurations. <https://github.com/WICG/webusb/issues/46> ↵ 

+  

+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+
\ No newline at end of file

From 6376b3d61f38aafae8019ee431d24275f3d9f907 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Tue, 30 May 2017 13:13:11 -0400
Subject: [PATCH 03/23] Renaming HTMLParser to HTMLFileContent and adding
 additional tests

---
 config/files.js                               |     2 +-
 lib/org/chromium/webidl/HTMLFileContent.js    |    95 +
 lib/org/chromium/webidl/HTMLParser.js         |    75 -
 test/any/parsing/HTMLFileContent-test.js      |    37 -
 test/node/parsing/HTMLFileContent-test.js     |    70 +-
 test/node/parsing/HTMLFileContent-test.js~    |    63 +
 test/node/parsing/UIEvent/1                   |     5 +
 test/node/parsing/UIEvent/2                   |     4 +
 test/node/parsing/UIEvent/23                  |     5 +
 test/node/parsing/UIEvent/27                  |   150 +
 test/node/parsing/UIEvent/spec.html           | 10133 +++++++
 test/node/parsing/{webSpec => }/WebUSB/0      |     0
 test/node/parsing/{webSpec => }/WebUSB/14     |     0
 test/node/parsing/{webSpec => }/WebUSB/3      |     0
 .../parsing/{webSpec => }/WebUSB/spec.html    |     0
 test/node/parsing/whatwg/29                   |     7 +
 test/node/parsing/whatwg/spec.html            | 22849 ++++++++++++++++
 17 files changed, 33360 insertions(+), 135 deletions(-)
 create mode 100644 lib/org/chromium/webidl/HTMLFileContent.js
 delete mode 100644 lib/org/chromium/webidl/HTMLParser.js
 delete mode 100644 test/any/parsing/HTMLFileContent-test.js
 create mode 100644 test/node/parsing/HTMLFileContent-test.js~
 create mode 100644 test/node/parsing/UIEvent/1
 create mode 100644 test/node/parsing/UIEvent/2
 create mode 100644 test/node/parsing/UIEvent/23
 create mode 100644 test/node/parsing/UIEvent/27
 create mode 100644 test/node/parsing/UIEvent/spec.html
 rename test/node/parsing/{webSpec => }/WebUSB/0 (100%)
 rename test/node/parsing/{webSpec => }/WebUSB/14 (100%)
 rename test/node/parsing/{webSpec => }/WebUSB/3 (100%)
 rename test/node/parsing/{webSpec => }/WebUSB/spec.html (100%)
 create mode 100644 test/node/parsing/whatwg/29
 create mode 100644 test/node/parsing/whatwg/spec.html

diff --git a/config/files.js b/config/files.js
index 7b8d4dd..43ffff0 100644
--- a/config/files.js
+++ b/config/files.js
@@ -91,7 +91,7 @@
     `lib${sep}org${sep}chromium${sep}webidl${sep}ast${sep}Float.js`,
 
     // HTML File Content Parser
-    `lib${sep}org${sep}chromium${sep}webidl${sep}HTMLParser.js`,
+    `lib${sep}org${sep}chromium${sep}webidl${sep}HTMLFileContent.js`,
 
     // Web IDL parsers
     `lib${sep}org${sep}chromium${sep}webidl${sep}BaseParser.js`,
diff --git a/lib/org/chromium/webidl/HTMLFileContent.js b/lib/org/chromium/webidl/HTMLFileContent.js
new file mode 100644
index 0000000..1ed9f3c
--- /dev/null
+++ b/lib/org/chromium/webidl/HTMLFileContent.js
@@ -0,0 +1,95 @@
+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+'use strict';
+
+foam.CLASS({
+  package: 'org.chromium.webidl',
+  name: 'HTMLFileContent',
+
+  requires: [
+    'foam.parsers.HTMLLexer'
+  ],
+
+  properties: [
+    {
+      name: 'file',
+      // description: 'content of the HTML file',
+      postSet: function(_, file) {
+        this.pre = this.parse(file);
+      }
+    },
+    {
+      name: 'pre',
+      // description: 'all pre tags found in the parsed HTML file',
+      factory: function() { return new Array; }
+    }
+  ],
+
+  methods: [
+    function parse(str) {
+      var self = this;
+      var lexer = self.HTMLLexer.create();
+      var OPEN = lexer.TagType.OPEN.name;
+      var CLOSE = lexer.TagType.CLOSE.name;
+      var OPEN_CLOSE = lexer.TagType.OPEN_CLOSE.name;
+
+      var results = lexer.parseString(str).value;
+
+      // Tag matching
+      // Using a stack to obtain ancestorOf 
 tags
+      var tags = [];
+      var pre = [];
+      results.forEach(function(node, i) {
+        var item = results[i];
+
+        if (foam.core.FObject.isInstance(item)) {
+          var top = tags[tags.length - 1];
+          if (top === undefined || item.type.name === OPEN) {
+            tags.push(item);
+          } else if (item.nodeName === top.nodeName && item.type.name === CLOSE) {
+            // Do we need to do anything with this?
+            tags.pop();
+          } else if (item.type.name === OPEN_CLOSE && item.nodeName === 'pre') {
+            // Determine if node is of class IDL
+            var isIDL = false;
+            item.attributes.forEach(function(attr) {
+              if (attr.name === 'class' && attr.value.split(' ').includes('idl')) {
+                isIDL = true;
+              }
+            });
+
+            // Add to the list of pre
+            pre.push({
+              ancestor: top,
+              content: self.flatten(item.content),
+              isIDL: isIDL
+            });
+          } else {
+            // Currently not doing anything for:
+            //  - Self closing tags (item.type.name === OPEN_CLOSE)
+            //  - Malformed / Mismatched HTML Files
+          }
+        }
+      });
+
+      if (tags.length !== 0) {
+        // We have mismatched tags! :(
+      }
+      return pre;
+    },
+
+    function flatten(obj) {
+      var self = this;
+      return obj.reduce(function(acc, item) {
+        if (foam.String.isInstance(item)) {
+          return acc.concat(item);
+        } else if (foam.core.FObject.isInstance(item)) {
+          return acc.concat(foam.Array.isInstance(item.content) ?
+              item.content[1] || item.content[0] || '' : '');
+        }
+      }, "");
+    }
+  ]
+});
+
diff --git a/lib/org/chromium/webidl/HTMLParser.js b/lib/org/chromium/webidl/HTMLParser.js
deleted file mode 100644
index ee5a462..0000000
--- a/lib/org/chromium/webidl/HTMLParser.js
+++ /dev/null
@@ -1,75 +0,0 @@
-// Copyright 2017 The Chromium Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style license that can be
-// found in the LICENSE file.
-'use strict';
-
-foam.CLASS({
-  package: 'org.chromium.webidl',
-  name: 'HTMLParser',
-
-  requires: [
-    'foam.parsers.HTMLLexer'
-  ],
-
-  methods: [
-      function parse(str) {
-        var self = this;
-        var lexer = self.HTMLLexer.create();
-        var OPEN = lexer.TagType.OPEN.name;
-        var CLOSE = lexer.TagType.CLOSE.name;
-        var OPEN_CLOSE = lexer.TagType.OPEN_CLOSE.name;
-
-        var results = lexer.parseString(str).value;
-
-        // Tag matching
-        // Using a stack to obtain ancestorOf 
 tags
-        var tags = [];
-        var pre = [];
-        results.forEach(function(node, i) {
-          var item = results[i];
-
-          if (foam.core.FObject.isInstance(item)) {
-            var top = tags[tags.length - 1];
-
-            if (top === undefined || item.type.name === OPEN) {
-              tags.push(item);
-            } else if (item.nodeName === top.nodeName && item.type.name === CLOSE) {
-              // Do we need to do anything with this?
-              var x = tags.pop();
-            } else if (item.type.name === OPEN_CLOSE && item.nodeName === 'pre') {
-              // Process the IDL body
-              var idl = self.flatten(item.content);
-
-              var value = {
-                ancestor: top,
-                idl: idl
-              };
-              pre.push(value);
-            } else {
-              // Currently not doing anything for:
-              //  - Self closing tags (item.type.name === OPEN_CLOSE)
-              //  - Malformed / Mismatched HTML Files
-            }
-          }
-        });
-
-        if (tags.length !== 0) {
-          // We have mismatched tags! :(
-        }
-        return pre;
-      },
-
-    function flatten(obj) {
-      var self = this;
-      return obj.reduce(function(acc, item) {
-        if (foam.String.isInstance(item)) {
-          return acc.concat(item);
-        } else if (foam.core.FObject.isInstance(item)) {
-          return acc.concat(foam.Array.isInstance(item.content) ?
-              item.content[1] || item.content[0] || '' : '');
-        }
-      }, "");
-    }
-  ]
-});
-
diff --git a/test/any/parsing/HTMLFileContent-test.js b/test/any/parsing/HTMLFileContent-test.js
deleted file mode 100644
index a395ea4..0000000
--- a/test/any/parsing/HTMLFileContent-test.js
+++ /dev/null
@@ -1,37 +0,0 @@
-// Copyright 2017 The Chromium Authors. ALl rights reserved.
-// Use of this source code is governed by a BSD-style license that can be
-// found in the LICENSE file.
-'use strict';
-
-describe('HTMLFileContent', function() {
-  var HTMLParser;
-  //var Outputer;
-  var Parser;
-
-  beforeEach(function() {
-    HTMLParser = foam.lookup('org.chromium.webidl.HTMLParser');
-  });
-
-  it('should parse a pre tag with no content', function() {
-    var content = '
';
-  });
-
-  it('should parse a HTML file with one Web IDL Block', function() {
-    var content = `
-        
-          [Constructor]
-          interface Dahut : Mammal {
-            const unsigned short LEVROGYROUS = 0;
-            const unsigned short DEXTROGYROUS = 1;
-            readonly attribute DOMString chirality;
-            attribute unsigned long age;
-            Dahut turnAround(float angle, boolean fall);
-            unsigned long trip();
-            void yell([AllowAny] unsigned long volume,
-                      [TreatNullAs=EmptyString] DOMString sentence);
-          };
-      

-    `;
-    var ret = HTMLParser.create().parseString(content);
-  });
-});
diff --git a/test/node/parsing/HTMLFileContent-test.js b/test/node/parsing/HTMLFileContent-test.js
index 9cb8bda..cb81b96 100644
--- a/test/node/parsing/HTMLFileContent-test.js
+++ b/test/node/parsing/HTMLFileContent-test.js
@@ -4,12 +4,39 @@
 'use strict';
 
 describe('HTMLFileContent', function() {
-  var HTMLParser;
-  //var Outputer;
+  var HTMLFileContent;
   var Parser;
 
+  function cmpTest(testName, testDirectory, expectedPre, expectedIDL) {
+    var fs = require('fs');
+    var spec = fs.readFileSync(`${testDirectory}/spec.html`).toString();
+    var htmlSpec = HTMLFileContent.create({ file: spec });
+    var preBlocks = htmlSpec.pre;
+    var idlFragments = preBlocks.filter(function(block) {
+      return block.isIDL;
+    });
+
+    // Determine the number of fragments that were found
+    expect(preBlocks.length).toBe(expectedPre)
+    expect(idlFragments.length).toBe(expectedIDL);
+
+    fs.readdir(testDirectory, function(err, files) {
+      // Go through each of the expected results in the folder
+      files.forEach(function(filename) {
+        var testNum = Number(filename);
+
+        if (!isNaN(testNum) && testNum < preBlocks.length) {
+          var expectedContent = fs.readFileSync(`${testDirectory}/${filename}`).toString();
+          expect(preBlocks[testNum].content.trim()).toBe(expectedContent.trim());
+        } else if (filename !== 'spec.html') {
+          console.warn(`${filename} was not used in ${testName} spec test`);
+        }
+      });
+    });
+  }
+
   beforeEach(function() {
-    HTMLParser = foam.lookup('org.chromium.webidl.HTMLParser');
+    HTMLFileContent = foam.lookup('org.chromium.webidl.HTMLFileContent');
   });
 
   it('should parse a pre tag with no content', function() {
@@ -31,28 +58,27 @@ describe('HTMLFileContent', function() {
               [TreatNullAs=EmptyString] DOMString sentence);
         };
     
`;
-    var ret = HTMLParser.create().parse(content);
+    var ret = HTMLFileContent.create(content);
   });
 
-  it('should parse the WebUSB spec HTML file ', function() {
-    var fs = require('fs');
-    var testDirectory = `${__dirname}/webSpec/WebUSB`;
-    var spec = fs.readFileSync(`${testDirectory}/spec.html`).toString();
-    var idlFragments = HTMLParser.create().parse(spec);
+  it('should parse the UI Events spec HTML file', function() {
+    var testDirectory = `${__dirname}/UIEvent`;
+    var expectedFragments = 28;
+    var expectedIDLFrags = 18;
+    cmpTest('UI Events', testDirectory, expectedFragments, expectedIDLFrags);
+  });
 
-    expect(idlFragments.length).toBe(15);
-    fs.readdir(testDirectory, function(err, files) {
-      // Go through each of the expected results in the folder
-      files.forEach(function(filename) {
-        var testNum = Number(filename);
+  it('should parse the WebUSB spec HTML file ', function() {
+    var testDirectory = `${__dirname}/WebUSB`;
+    var expectedFragments = 15;
+    var expectedIDLFrags = 11;
+    cmpTest('WebUSB', testDirectory, expectedFragments, expectedIDLFrags);
+  });
 
-        if (!isNaN(testNum) && testNum < idlFragments.length) {
-          var expectedIDL = fs.readFileSync(`${testDirectory}/${filename}`).toString();
-          expect(idlFragments[testNum].idl).toBe(expectedIDL);
-        } else if (filename !== 'spec.html') {
-          console.warn(`${filename} was not used in WebUSB spec test`);
-        }
-      });
-    });
+  it('should parse the whatwg HTML standard', function() {
+    var testDirectory = `${__dirname}/whatwg`;
+    var expectedFragments = 542;
+    var expectedIDLFrags = 45;
+    cmpTest('whatwg HTML', testDirectory, expectedFragments, expectedIDLFrags);
   });
 });
diff --git a/test/node/parsing/HTMLFileContent-test.js~ b/test/node/parsing/HTMLFileContent-test.js~
new file mode 100644
index 0000000..a28195f
--- /dev/null
+++ b/test/node/parsing/HTMLFileContent-test.js~
@@ -0,0 +1,63 @@
+// Copyright 2017 The Chromium Authors. ALl rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+'use strict';
+
+describe('HTMLFileContent', function() {
+  var HTMLParser;
+  //var Outputer;
+  var Parser;
+
+  function cmpTest(testDirectory, idlFragments) {
+		var fs = require('fs');
+		var spec = fs.readFileSync(`${testDirectory}/spec.html`).toString();
+
+    fs.readdir(testDirectory, function(err, files) {
+      // Go through each of the expected results in the folder
+      files.forEach(function(filename) {
+        var testNum = Number(filename);
+
+        if (!isNaN(testNum) && testNum < idlFragments.length) {
+          var expectedIDL = fs.readFileSync(`${testDirectory}/${filename}`).toString();
+          expect(idlFragments[testNum].idl).toBe(expectedIDL);
+        } else if (filename !== 'spec.html') {
+          console.warn(`${filename} was not used in WebUSB spec test`);
+        }
+      });
+    });
+	}
+
+  beforeEach(function() {
+    HTMLParser = foam.lookup('org.chromium.webidl.HTMLParser');
+  });
+
+  it('should parse a pre tag with no content', function() {
+    var content = '
';
+  });
+
+  it('should parse a HTML file with one Web IDL Block', function() {
+    var content = `
+        
+        [Constructor]
+        interface Dahut : Mammal {
+          const unsigned short LEVROGYROUS = 0;
+          const unsigned short DEXTROGYROUS = 1;
+          readonly attribute DOMString chirality;
+          attribute unsigned long age;
+          Dahut turnAround(float angle, boolean fall);
+          unsigned long trip();
+          void yell([AllowAny] unsigned long volume,
+              [TreatNullAs=EmptyString] DOMString sentence);
+        };
+    
`;
+    var ret = HTMLParser.create().parse(content);
+  });
+
+  it('should parse the WebUSB spec HTML file ', function() {
+    var testDirectory = `${__dirname}/webSpec/WebUSB`;
+    var idlFragments = HTMLParser.create().parse(spec);
+
+    expect(idlFragments.length).toBe(15);
+		cmpTest(testDirectory, idlFragments);
+  });
+});
diff --git a/test/node/parsing/UIEvent/1 b/test/node/parsing/UIEvent/1
new file mode 100644
index 0000000..75f5557
--- /dev/null
+++ b/test/node/parsing/UIEvent/1
@@ -0,0 +1,5 @@
+[Constructor(DOMString type, optional UIEventInit eventInitDict)]
+interface UIEvent : Event {
+  readonly attribute Window? view;
+  readonly attribute long detail;
+};
diff --git a/test/node/parsing/UIEvent/2 b/test/node/parsing/UIEvent/2
new file mode 100644
index 0000000..164d8e4
--- /dev/null
+++ b/test/node/parsing/UIEvent/2
@@ -0,0 +1,4 @@
+dictionary UIEventInit : EventInit {
+  Window? view = null;
+  long detail = 0;
+};
diff --git a/test/node/parsing/UIEvent/23 b/test/node/parsing/UIEvent/23
new file mode 100644
index 0000000..36a4673
--- /dev/null
+++ b/test/node/parsing/UIEvent/23
@@ -0,0 +1,5 @@
+partial interface KeyboardEvent {
+  // The following support legacy user agents
+  readonly attribute unsigned long charCode;
+  readonly attribute unsigned long keyCode;
+};
diff --git a/test/node/parsing/UIEvent/27 b/test/node/parsing/UIEvent/27
new file mode 100644
index 0000000..0bc7c0a
--- /dev/null
+++ b/test/node/parsing/UIEvent/27
@@ -0,0 +1,150 @@
+[Constructor(DOMString type, optional UIEventInit eventInitDict)]
+interface UIEvent : Event {
+  readonly attribute Window? view;
+  readonly attribute long detail;
+};
+
+dictionary UIEventInit : EventInit {
+  Window? view = null;
+  long detail = 0;
+};
+
+[Constructor(DOMString type, optional FocusEventInit eventInitDict)]
+interface FocusEvent : UIEvent {
+  readonly attribute EventTarget? relatedTarget;
+};
+
+dictionary FocusEventInit : UIEventInit {
+  EventTarget? relatedTarget = null;
+};
+
+[Constructor(DOMString type, optional MouseEventInit eventInitDict)]
+interface MouseEvent : UIEvent {
+  readonly attribute long screenX;
+  readonly attribute long screenY;
+  readonly attribute long clientX;
+  readonly attribute long clientY;
+
+  readonly attribute boolean ctrlKey;
+  readonly attribute boolean shiftKey;
+  readonly attribute boolean altKey;
+  readonly attribute boolean metaKey;
+
+  readonly attribute short button;
+  readonly attribute unsigned short buttons;
+
+  readonly attribute EventTarget? relatedTarget;
+
+  boolean getModifierState(DOMString keyArg);
+};
+
+dictionary MouseEventInit : EventModifierInit {
+  long screenX = 0;
+  long screenY = 0;
+  long clientX = 0;
+  long clientY = 0;
+
+  short button = 0;
+  unsigned short buttons = 0;
+  EventTarget? relatedTarget = null;
+};
+
+dictionary EventModifierInit : UIEventInit {
+  boolean ctrlKey = false;
+  boolean shiftKey = false;
+  boolean altKey = false;
+  boolean metaKey = false;
+
+  boolean modifierAltGraph = false;
+  boolean modifierCapsLock = false;
+  boolean modifierFn = false;
+  boolean modifierFnLock = false;
+  boolean modifierHyper = false;
+  boolean modifierNumLock = false;
+  boolean modifierScrollLock = false;
+  boolean modifierSuper = false;
+  boolean modifierSymbol = false;
+  boolean modifierSymbolLock = false;
+};
+
+[Constructor(DOMString type, optional WheelEventInit eventInitDict)]
+interface WheelEvent : MouseEvent {
+  // DeltaModeCode
+  const unsigned long DOM_DELTA_PIXEL = 0x00;
+  const unsigned long DOM_DELTA_LINE  = 0x01;
+  const unsigned long DOM_DELTA_PAGE  = 0x02;
+
+  readonly attribute double deltaX;
+  readonly attribute double deltaY;
+  readonly attribute double deltaZ;
+  readonly attribute unsigned long deltaMode;
+};
+
+dictionary WheelEventInit : MouseEventInit {
+  double deltaX = 0.0;
+  double deltaY = 0.0;
+  double deltaZ = 0.0;
+  unsigned long deltaMode = 0;
+};
+
+[Constructor(DOMString type, optional InputEventInit eventInitDict)]
+interface InputEvent : UIEvent {
+  readonly attribute DOMString? data;
+  readonly attribute boolean isComposing;
+};
+
+dictionary InputEventInit : UIEventInit {
+  DOMString? data = "";
+  boolean isComposing = false;
+};
+
+[Constructor(DOMString type, optional KeyboardEventInit eventInitDict)]
+interface KeyboardEvent : UIEvent {
+  // KeyLocationCode
+  const unsigned long DOM_KEY_LOCATION_STANDARD = 0x00;
+  const unsigned long DOM_KEY_LOCATION_LEFT = 0x01;
+  const unsigned long DOM_KEY_LOCATION_RIGHT = 0x02;
+  const unsigned long DOM_KEY_LOCATION_NUMPAD = 0x03;
+
+  readonly attribute DOMString key;
+  readonly attribute DOMString code;
+  readonly attribute unsigned long location;
+
+  readonly attribute boolean ctrlKey;
+  readonly attribute boolean shiftKey;
+  readonly attribute boolean altKey;
+  readonly attribute boolean metaKey;
+
+  readonly attribute boolean repeat;
+  readonly attribute boolean isComposing;
+
+  boolean getModifierState(DOMString keyArg);
+};
+
+dictionary KeyboardEventInit : EventModifierInit {
+  DOMString key = "";
+  DOMString code = "";
+  unsigned long location = 0;
+  boolean repeat = false;
+  boolean isComposing = false;
+};
+
+[Constructor(DOMString type, optional CompositionEventInit eventInitDict)]
+interface CompositionEvent : UIEvent {
+  readonly attribute DOMString data;
+};
+
+dictionary CompositionEventInit : UIEventInit {
+  DOMString data = "";
+};
+
+partial interface UIEvent {
+  // The following support legacy user agents
+  readonly attribute unsigned long which;
+};
+
+partial interface KeyboardEvent {
+  // The following support legacy user agents
+  readonly attribute unsigned long charCode;
+  readonly attribute unsigned long keyCode;
+};
diff --git a/test/node/parsing/UIEvent/spec.html b/test/node/parsing/UIEvent/spec.html
new file mode 100644
index 0000000..14ce781
--- /dev/null
+++ b/test/node/parsing/UIEvent/spec.html
@@ -0,0 +1,10133 @@
+
+
+
+  
+  UI Events 
+  
+  
+  
+  
+  
+  
+  
+
+
+
+
+
+
+ 
 Jump to Table of Contents Collapse Sidebar

+  

+   

+    
W3C

+    
UI Events

+    
W3C Working Draft, 

+   

+   

+    

+     
This version:
+     
https://www.w3.org/TR/2017/WD-uievents-20170427/
+     
Latest published version:
+     
http://www.w3.org/TR/uievents/
+     
Editor's Draft:
+     
https://w3c.github.io/uievents/
+     
Previous Versions:
+     

+     
https://www.w3.org/TR/2015/WD-uievents-20151215/
+     
http://www.w3.org/TR/2015/WD-uievents-20150428/
+     
http://www.w3.org/TR/2015/WD-uievents-20150319/
+     
Issue Tracking:
+     
GitHub
+     
Editors:
+     
 (Google)
+     
 (Microsoft)
+     
Doug Schepers (Mar 2008 - May 2011)
+     
Tests:
+     
web-platform-tests uievents/ (ongoing work)
+    

+   

+   

+   
Copyright © 2017 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply. 

+   

+  

+  
Abstract

+  

+   
This specification defines UI Events which extend the DOM Event objects
+
+defined in [DOM]. UI Events are those typically implemented by visual
+user agents for handling user interaction such as mouse and keyboard input.

+  

+  
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 latest revision of this
+    technical report can be found in the W3C technical
+    reports index at http://www.w3.org/TR/. 

+   
 The management and production of this document follows a relatively complex setup. Details are
+    provided as part of the introduction. 

+   
 This document was published by the Web Platform Working Group as a Working Draft.
+
+    Feedback and comments on this specification are welcome. Please use Github issues Historical discussions can be found in the public-webapps@w3.org archives. 

+   
 Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may
+    be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite
+    this document as other than work in progress. 

+   
 This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any
+    patent disclosures made in connection with the deliverables of the group; that page also
+    includes instructions for disclosing a patent. An individual who has actual knowledge of a
+    patent which the individual believes contains Essential
+    Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy. 

+   
 This document is governed by the 1 September 2015 W3C Process Document. 

+   

+  

+  

+  
+  

+   

+    
1. Introduction

+    
1.1. Overview

+    
UI Events is designed with two main goals. The first goal is the design of
+    an event system which allows registration of event listeners and
+    describes event flow through a tree structure. Additionally, the
+    specification will provide standard modules of events for user interface
+    control and document mutation notifications, including defined contextual
+    information for each of these event modules.

+    
The second goal of UI Events is to provide a common subset of the current
+    event systems used in existing browsers. This is intended to foster
+    interoperability of existing scripts and content. It is not expected that
+    this goal will be met with full backwards compatibility. However, the
+    specification attempts to achieve this when possible.

+    
1.2. Conformance

+    
This section is normative.

+    
Within this specification, the key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in [RFC2119].

+    
This specification is to be understood in the context of the DOM Level 3
+    Core specification [DOM-Level-3-Core] and the general considerations for DOM
+    implementations apply. For example, handling of namespace URIs is
+    discussed in XML Namespaces.
+    For additional information about conformance,
+    please see the DOM Level 3 Core specification [DOM-Level-3-Core]. A user
+    agent is not required to conform to the entirety of another
+    specification in order to conform to this specification, but it MUST conform
+    to the specific parts of any other specification which are called out in
+    this specification (e.g., a conforming UI Events user agent MUST
+    support the DOMString data type as defined in [[Web IDL]], but
+    need not support every method or data type defined in [[Web IDL]] in order
+    to conform to UI Events).

+    
This specification defines several classes of conformance for different user agents, specifications, and content authors:

+    
1.2.1. Web browsers and other dynamic or interactive user agents

+    
A dynamic or interactive user agent, referred to here as a browser (be it a Web browser, AT (Accessibility Technology)
+        application, or other similar program), conforms to UI Events if it
+        supports:

+    
    
+     
  • 
+      
    the Core module defined in [DOM-Level-3-Core]
    
+     
  • 
+      
    the §3.1 Event dispatch and DOM event flow mechanism
    
+     
  • 
+      
    all the interfaces and events with their associated methods,
+attributes, and semantics defined in this specification with the
+exception of those marked as deprecated (a conforming user
+agent MAY implement the deprecated interfaces, events, or APIs for
+backwards compatibility, but is not required to do so in order to be
+conforming)
    
+     
  • 
+      
    the complete set of key and code values defined in [UIEvents-Key] and [UIEvents-Code] (subject to
+platform availability), and
    
+     
  • 
+      
    all other normative requirements defined in this specification.
    
+    

+    
A conforming browser MUST dispatch events appropriate to the
+        given EventTarget when the conditions defined for that event
+        type have been met.

+    
A browser conforms specifically to UI Events if it implements the
+        interfaces and related event types specified in §4 Event Types.

+    
A conforming browser MUST support scripting, declarative interactivity,
+        or some other means of detecting and dispatching events in the manner
+        described by this specification, and MUST support the APIs specified for
+        that event type.

+    
In addition to meeting all other conformance criteria, a conforming
+        browser MAY implement features of this specification marked as deprecated, for backwards compatibility with existing content,
+        but such implementation is discouraged.

+    
A conforming browser MAY also support features not found in this
+        specification, but which use the §3.1 Event dispatch and DOM event flow mechanism, interfaces,
+        events, or other features defined in this specification, and MAY
+        implement additional interfaces and event types appropriate to
+        that implementation. Such features can be later standardized in future
+        specifications.

+    
A browser which does not conform to all required portions of this
+        specification MUST NOT claim conformance to UI Events. Such an
+        implementation which does conform to portions of this specification MAY
+        claim conformance to those specific portions.

+    
A conforming browser MUST also be a conforming implementation of
+        the IDL fragments in this specification, as described in the Web IDL
+        specification [WebIDL].

+    
1.2.2. Authoring tools

+    
A content authoring tool conforms to UI Events if it produces content
+        which uses the event types and §3.1 Event dispatch and DOM event flow model, consistent
+        in a manner as defined in this specification.

+    
A content authoring tool MUST NOT claim conformance to UI Events for
+        content it produces which uses features of this specification marked as deprecated in this specification.

+    
A conforming content authoring tool SHOULD provide to the content author
+        a means to use all event types and interfaces appropriate to all host languages in the content document being produced.

+    
1.2.3. Content authors and content

+    
A content author creates conforming UI Events content if that
+            content uses the event types and §3.1 Event dispatch and DOM event flow model,
+            consistent in a manner as defined in this specification.

+    
A content author SHOULD NOT use features of this specification
+            marked as deprecated, but SHOULD rely instead upon
+            replacement mechanisms defined in this specification and elsewhere.

+    
Conforming content MUST use the semantics of the interfaces and event types as described in this specification.

+    
 Content authors are advised to follow best practices as described in accessibility and internationalization guideline specifications. 

+    
1.2.4. Specifications and host languages

+    
A specification or host language conforms to UI Events if it
+        references and uses the §3.1 Event dispatch and DOM event flow mechanism, interfaces, events,
+        or other features defined in [DOM], and does not extend
+        these features in incompatible ways.

+    
A specification or host language conforms specifically to UI
+        Events if it references and uses the interfaces and related event
+        types specified in §4 Event Types. A conforming specification MAY
+        define additional interfaces and event types appropriate to that
+        specification, or MAY extend the UI Events interfaces and event
+        types in a manner that does not contradict or conflict with the
+        definitions of those interfaces and event types in this
+        specification.

+    
Specifications or host languages which reference UI Events SHOULD
+        NOT use or recommend features of this specification marked as deprecated, but SHOULD use or recommend the indicated replacement
+        for that the feature (if available).

+   

+   

+    
2. Stylistic Conventions

+    
This specification follows the Proposed W3C Specification Conventions,
+with the following supplemental additions:

+    
    
+     
  • 
+      
    The key cap printed on a key is shown as ↓, = or Q. This is used to refer to a    key from the user’s perspective without regard for the key and code values in the
+generated KeyboardEvent.
    
+     
  • 
+      
    Glyphs representing character are shown as: "𣧂".
    
+     
  • 
+      
    Unicode character encodings are shown as: U+003d.
    
+     
  • 
+      
    Names of key values generated by a key press (i.e., the value of KeyboardEvent.key) are shown as: "ArrowDown", "=", "q" or "Q".
    
+     
  • 
+      
    Names of key codes associated with the physical keys (i.e., the
+value of KeyboardEvent.code) are shown as: "ArrowDown", "Equal" or "KeyQ".
    
+    

+    
In addition, certain terms are used in this specification with particular
+meanings.  The term implementation applies to a browser, content
+authoring tool, or other user agent that implements this specification,
+while a content author is a person who writes script or code that takes
+advantage of the interfaces, methods, attributes, events, and other features
+described in this specification in order to make Web applications, and a user is
+the person who uses those Web applications in an implementation.

+    
And finally:

+    
This is a note.

+    

+    
This is an open issue.

+    
This is a warning.

+
interface Example {
+    // This is an IDL definition.
+};
+

+   

+   

+    
3. DOM Event Architecture

+    
This section is non-normative. Refer to [DOM] for a normative description
+of the DOM event architecture

+    
3.1. Event dispatch and DOM event flow

+    
This section gives a brief overview of the event dispatch mechanism
+    and describes how events propagate through the DOM tree. Applications can
+    dispatch event objects using the dispatchEvent() method, and
+    the event object will propagate through the DOM tree as determined by the
+    DOM event flow.

+    

+      Graphical representation of an event dispatched in a DOM tree using the DOM event flow 
+     
Graphical representation of an event dispatched in a DOM tree using the DOM event flow

+    

+    
Event objects are dispatched to an event target. But before dispatch
+    can begin, the event object’s propagation path must first be
+    determined.

+    
The propagation path is an ordered list of current event
+    targets through which the event passes. This propagation path reflects
+    the hierarchical tree structure of the document. The last item in the list
+    is the event target, and the preceding items in the list are referred
+    to as the target’s ancestors, with the immediately preceding item
+    as the target’s parent.

+    
Once the propagation path has been determined, the event object
+    passes through one or more event phases. There are three event
+    phases: capture phase, target phase and bubble phase.
+    Event objects complete these phases as described below. A phase will be
+    skipped if it is not supported, or if the event object’s propagation has
+    been stopped. For example, if the bubbles attribute is set to
+    false, the bubble phase will be skipped, and if stopPropagation() has been called prior to the dispatch, all phases will be skipped.

+    
    
+     
  • 
+      
    The capture phase: The event object propagates
+through the target’s ancestors from the Window to the target’s
+parent. This phase is also known as the capturing phase.
    
+     
  • 
+      
    The target phase: The event object arrives at the event
+object’s event target. This phase is also known as the at-target phase. If the event type indicates that the
+event doesn’t bubble, then the event object will halt after completion
+of this phase.
    
+     
  • 
+      
    The bubble phase: The event object propagates through
+the target’s ancestors in reverse order, starting with the target’s
+parent and ending with the Window. This phase is also known as
+the bubbling phase.
    
+    

+    
3.2. Default actions and cancelable events

+    
Events are typically dispatched by the implementation as a result of a user
+    action, in response to the completion of a task, or to signal progress
+    during asynchronous activity (such as a network request). Some events can be
+    used to control the behavior that the implementation may take next (or undo
+    an action that the implementation already took). Events in this category are
+    said to be cancelable and the behavior they cancel is called their default action. Cancelable event objects can be associated
+    with one or more 'default actions'. To cancel an event, call the preventDefault() method.

+    
 A mousedown event is dispatched immediately after the user presses    down a button on a pointing device (typically a mouse). One possible default action taken by the implementation is to set up a state
+    machine that allows the user to drag images or select text. The default
+    action depends on what happens next — for example, if the user’s
+    pointing device is over text, a text selection might begin. If the user’s
+    pointing device is over an image, then an image-drag action could begin.
+    Preventing the default action of a mousedown event prevents    these actions from occurring. 

+    
Default actions are usually performed after the event dispatch has
+    been completed, but in exceptional cases they may also be performed
+    immediately before the event is dispatched.

+    
 The default action associated with the click event on <input    type="checkbox"> elements toggles the checked IDL
+    attribute value of that element. If the click event’s default action    is cancelled, then the value is restored to its former state. 

+    
When an event is canceled, then the conditional default actions associated with the event is skipped (or as mentioned above, if the default actions are carried out before the dispatch, their effect
+    is undone). Whether an event object is cancelable is indicated by
+    the cancelable attribute. Calling preventDefault() stops all
+    related default actions of an event object. The defaultPrevented attribute indicates whether an event has already
+    been canceled (e.g., by a prior event listener). If the DOM
+    application itself initiated the dispatch, then the return value of the dispatchEvent() method indicates whether the event object
+    was cancelled.

+    
Many implementations additionally interpret an event
+    listener’s return value, such as the value false, to mean that
+    the default action of cancelable events will be cancelled (though window.onerror handlers are cancelled by returning true). 

+    
3.3. Synchronous and asynchronous events

+    
Events may be dispatched either synchronously or asynchronously.

+    
Events which are synchronous (sync events) are treated
+    as if they are in a virtual queue in a first-in-first-out model, ordered by
+    sequence of temporal occurrence with respect to other events, to changes in
+    the DOM, and to user interaction.  Each event in this virtual queue is
+    delayed until the previous event has completed its propagation behavior, or
+    been canceled.  Some sync events are driven by a specific device or process,
+    such as mouse button events. These events are governed by the event
+    order algorithms defined for that set of events, and user agents will
+    dispatch these events in the defined order.

+    
Events which are asynchronous (async events) may be
+    dispatched as the results of the action are completed, with no relation to
+    other events, to other changes in the DOM, nor to user interaction.

+    
 During loading of a document, an inline script element is parsed and
+    executed. The load event is queued to be fired    asynchronously at the script element. However, because it is an async event,
+    its order with relation to other synchronous events fired during document
+    load (such as the DOMContentLoaded event from [HTML5]) is not guaranteed. 

+    
3.4. Trusted events

+    
Events that are generated by the user agent, either as a result of user
+    interaction, or as a direct result of changes to the DOM, are trusted by the user agent with privileges that are not afforded to events generated by
+    script through the createEvent() method, modified
+    using the initEvent() method, or dispatched via the dispatchEvent() method.  The isTrusted attribute
+    of trusted events has a value of true, while untrusted events
+    have a isTrusted attribute value of false.

+    
Most untrusted events will not trigger default actions, with the
+    exception of the click event. This event always    triggers the default action, even if the isTrusted attribute is false (this behavior is retained for
+    backward-compatibility). All other untrusted events behave as if the preventDefault() method had been called on that event.

+    
3.5. Activation triggers and behavior

+    
Certain event targets (such as a link or button element) may have
+    associated activation behavior (such a following a link) that
+    implementations perform in response to an activation
+    trigger (such as clicking a link).

+    
 Both HTML and SVG have an <a> element which indicates a
+    link.  Relevant activation triggers for an <a> element are a click event on the text or image content    of the <a> element, or a keydown event with a key attribute value of "Enter" key when    the <a> element has focus.  The activation behavior for
+    an <a> element is normally to change the content of the
+    window to the content of the new document, in the case of external links,
+    or to reposition the current document relative to the new anchor, in the
+    case of internal links. 

+    
An activation trigger is a user action or an event which indicates
+    to the implementation that an activation behavior should be initiated.
+    User-initiated activation triggers include clicking a mouse button
+    on an activatable element, pressing the Enter key when an activatable    element has focus, or pressing a key that is somehow linked to an
+    activatable element (a hotkey or access key) even when that
+    element does not have focus.  Event-based activation triggers may
+    include timer-based events that activate an element at a certain clock time
+    or after a certain time period has elapsed, progress events after a certain
+    action has been completed, or many other condition-based or state-based
+    events.

+    
3.6. Constructing Mouse and Keyboard Events

+    
Generally, when a constructor of an Event interface, or of an interface
+    inherited from the Event interface, is invoked, the steps described in [DOM] should be followed. However the KeyboardEvent and MouseEvent interfaces provide additional dictionary members for
+    initializing the internal state of the Event object’s key modifiers:
+    specifically, the internal state queried for using the getModifierState() and getModifierState() methods. This section supplements the DOM4 steps for intializing a new Event object with these optional modifier states.

+    
For the purposes of constructing a KeyboardEvent, MouseEvent, or
+    object derived from these objects using the algorithm below, all KeyboardEvent, MouseEvent, and derived objects have internal key modifier state which can be set and
+    retrieved using the key modifier names described in the Modifier Keys table in [UIEvents-Key].

+    
The following steps supplement the algorithm defined for constructing
+    events in DOM4:

+    
+   

+   

+    
4. Event Types

+    
The DOM Event Model allows a DOM implementation to support multiple modules of
+events. The model has been designed to allow addition of new event modules in
+the future. This document does not attempt to define all possible events. For
+purposes of interoperability, the DOM defines a module of user interface events
+including lower level device dependent events and a module of document mutation
+events.

+    
4.1. User Interface Events

+    
The User Interface event module contains basic event types associated with
+	user interfaces and document manipulation.

+    
4.1.1. Interface UIEvent

+    
Introduced in DOM Level 2

+    
The UIEvent interface provides specific contextual information
+		associated with User Interface events.

+    
To create an instance of the UIEvent interface, use the UIEvent
+		constructor, passing an optional UIEventInit dictionary.

+    
4.1.1.1. UIEvent

+
[Constructor(DOMString type, optional UIEventInit eventInitDict)]
+interface UIEvent : Event {
+  readonly attribute Window? view;
+  readonly attribute long detail;
+};
+

+    

+     
UIEvent . view
+     

+       The view attribute identifies the Window from which the event was generated. 
+      
The un-initialized value of this attribute MUST be null.

+     
UIEvent . detail
+     

+       Specifies some detail information about the Event, depending
+					on the type of event. 
+      
The un-initialized value of this attribute MUST be 0.

+    

+    
4.1.1.2. UIEventInit

+
dictionary UIEventInit : EventInit {
+  Window? view = null;
+  long detail = 0;
+};
+

+    

+     
UIEventInit . view
+     
 Should be initialized to the Window object of the global
+					environment in which this event will be dispatched. If this
+					event will be dispatched to an element, the view property should
+					be set to the Window object containing the element’s ownerDocument. 
+     
UIEventInit . detail
+     
 This value is initialized to a number that is
+					application-specific. 
+    

+    
4.1.2. UI Event Types

+    
The User Interface event types are listed below.  Some of these events
+		use the UIEvent interface if generated from a user interface, but
+		the Event interface otherwise, as detailed in each event.

+    
4.1.2.1. load

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       load
+      
Interface
+       UIEvent if generated from a user interface, Event otherwise.
+      
Sync / Async
+       Async
+      
Bubbles
+       No
+      
Trusted Targets
+       Window, Document, Element
+      
Cancelable
+       No
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when the DOM
+			implementation finishes loading the resource (such as the document)
+			and any dependent resources (such as images, style sheets, or
+			scripts). Dependent resources that fail to load MUST NOT prevent
+			this event from firing if the resource that loaded them is still
+			accessible via the DOM. If this event type is dispatched,
+			implementations are REQUIRED to dispatch this event at least on the Document node.

+    

+    
 For legacy reasons, load events for resources inside the			document (e.g., images) do not include the Window in the
+			propagation path in HTML implementations. See [HTML5] for more
+			information. 

+    
4.1.2.2. unload

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       unload
+      
Interface
+       UIEvent if generated from a user interface, Event otherwise.
+      
Sync / Async
+       Sync
+      
Bubbles
+       No
+      
Trusted Targets
+       Window, Document, Element
+      
Cancelable
+       No
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when the DOM
+			Implementation removes from the environment the resource (such as
+			the document) or any dependent resources (such as images, style
+			sheets, scripts). The document MUST be unloaded after the dispatch
+			of this event type. If this event type is dispatched,
+			implementations are REQUIRED to dispatch this event at least on
+			the Document node.

+    
4.1.2.3. abort

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       abort
+      
Interface
+       UIEvent if generated from a user interface, Event otherwise.
+      
Sync / Async
+       Sync
+      
Bubbles
+       No
+      
Trusted Targets
+       Window, Element
+      
Cancelable
+       No
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when the loading of a
+			resource has been aborted, such as by a user canceling the load
+			while it is still in progress.

+    
4.1.2.4. error

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       error
+      
Interface
+       UIEvent if generated from a user interface, Event otherwise.
+      
Sync / Async
+       Async
+      
Bubbles
+       No
+      
Trusted Targets
+       Window, Element
+      
Cancelable
+       No
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a resource failed
+			to load, or has been loaded but cannot be interpreted according to
+			its semantics, such as an invalid image, a script execution error,
+			or non-well-formed XML.

+    
4.1.2.5. select

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       select
+      
Interface
+       UIEvent if generated from a user interface, Event otherwise.
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       No
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a user selects
+			some text.	This event is dispatched after the selection has occurred.

+    
This specification does not provide contextual information to access
+			the selected text.	Where applicable, a host language SHOULD
+			define rules for how a user MAY select content (with consideration
+			for international language conventions), at what point the select event is dispatched, and how a content author MAY			access the user-selected content.

+    
 In order to access to user-selected content, content authors will
+			use native capabilities of the host languages, such as the Document.getSelection() method of the HTML Editing APIs [Editing]. 

+    
 The select event might not be available for all elements in			all languages.	For example, in [HTML5], select events can			be dispatched only on form input and textarea elements.
+			Implementations can dispatch select events in any context			deemed appropriate, including text selections outside of form
+			controls, or image or markup selections such as in SVG. 

+    
4.2. Focus Events

+    
 This interface and its associated event types and §4.2.2 Focus Event Order were designed in accordance to the concepts and guidelines defined in User Agent Accessibility Guidelines 2.0 [UAAG20],
+	with particular attention on the focus mechanism and the terms defined in the glossary entry for focus. 

+    
4.2.1. Interface FocusEvent

+    
Introduced in this specification

+    
The FocusEvent interface provides specific contextual information
+		associated with Focus events.

+    
To create an instance of the FocusEvent interface, use the
+		FocusEvent constructor, passing an optional FocusEventInit dictionary.

+    
4.2.1.1. FocusEvent

+
[Constructor(DOMString type, optional FocusEventInit eventInitDict)]
+interface FocusEvent : UIEvent {
+  readonly attribute EventTarget? relatedTarget;
+};
+

+    

+     
FocusEvent . relatedTarget
+     

+       Used to identify a secondary EventTarget related to a Focus event, depending on the type of event. 
+      
For security reasons with nested browsing contexts, when tabbing
+					into or out of a nested context, the relevant EventTarget SHOULD be null.

+      
The un-initialized value of this attribute MUST be null.

+    

+    
4.2.1.2. FocusEventInit

+
dictionary FocusEventInit : UIEventInit {
+  EventTarget? relatedTarget = null;
+};
+

+    

+     
FocusEventInit . relatedTarget
+     
 The relatedTarget should be initialized to the element
+					losing focus (in the case of a focus or focusin event) or the element gaining focus (in the case of a blur or focusout event). 
+    

+    
4.2.2. Focus Event Order

+    
The focus events defined in this specification occur in a set order
+		relative to one another.  The following is the typical sequence of
+		events when a focus is shifted between elements (this order assumes
+		that no element is initially focused):

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       

+       Event Type
+       Notes
+      

+       
+       User shifts focus
+      
1
+       focusin
+       Sent before first target element receives focus
+      
2
+       focus
+       Sent after first target element receives focus
+      

+       
+       User shifts focus
+      
3
+       focusout
+       Sent before first target element loses focus
+      
4
+       focusin
+       Sent before second target element receives focus
+      
5
+       blur
+       Sent after first target element loses focus
+      
6
+       focus
+       Sent after second target element receives focus
+    

+    
 This specification does not define the behavior of focus events when
+		interacting with methods such as focus() or blur(). See the relevant specifications where those methods
+		are defined for such behavior. 

+    
4.2.3. Document Focus and Focus Context

+    
This event module includes event types for notification of changes in
+		document focus. There are three distinct focus contexts that are
+		relevant to this discussion:

+    
    
+     
  • 
+      
    The operating system focus context which MAY be on one of
+many different applications currently running on the computer. One
+of these applications with focus can be a browser.
    
+     
  • 
+      
    When the browser has focus, the user can switch (such as with the
+tab key) the application focus context among the different
+browser user interface fields (e.g., the Web site location bar, a
+search field, etc.). One of these user interface fields can be the
+document being shown in a tab.
    
+     
  • 
+      
    When the document itself has focus, the document focus
+context can be set to any of the focusable elements in the
+document.
    
+    

+    
The event types defined in this specification deal exclusively with
+		document focus, and the event target identified in the event
+		details MUST only be part of the document or documents in the window,
+		never a part of the browser or operating system, even when switching
+		from one focus context to another.

+    
Normally, a document always has a focused element (even if it is the
+		document element itself) and a persistent focus ring. When
+		switching between focus contexts, the document’s currently focused
+		element and focus ring normally remain in their current state. For
+		example, if a document has three focusable elements, with the second
+		element focused, when a user changes operating system focus to another
+		application and then back to the browser, the second element will still
+		be focused within the document, and tabbing will change the focus to the
+		third element.  A host language MAY define specific elements
+		which might receive focus, the conditions under which an element MAY
+		receive focus, the means by which focus MAY be changed, and the order
+		in which the focus changes.  For example, in some cases an element might
+		be given focus by moving a pointer over it, while other circumstances
+		might require a mouse click. Some elements might not be focusable at
+		all, and some might be focusable only by special means (clicking on the
+		element), but not by tabbing to it.  Documents MAY contain multiple
+		focus rings.  Other specifications MAY define a more complex focus model
+		than is described in this specification, including allowing multiple
+		elements to have the current focus.

+    
4.2.4. Focus Event Types

+    
The Focus event types are listed below.

+    
4.2.4.1. blur

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       blur
+      
Interface
+       FocusEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       No
+      
Trusted Targets
+       Window, Element
+      
Cancelable
+       No
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when an event
+			target loses focus. The focus MUST be taken from the element
+			before the dispatch of this event type.  This event type is similar
+			to focusout, but is dispatched after focus is shifted, and			does not bubble.

+    
4.2.4.2. focus

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       focus
+      
Interface
+       FocusEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       No
+      
Trusted Targets
+       Window, Element
+      
Cancelable
+       No
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when an event
+			target receives focus. The focus MUST be given to the element
+			before the dispatch of this event type.  This event type is similar
+			to focusin, but is dispatched after focus is shifted, and			does not bubble.

+    
4.2.4.3. focusin

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       focusin
+      
Interface
+       FocusEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Window, Element
+      
Cancelable
+       No
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when an event
+			target is about to receive focus. This event type MUST be
+			dispatched before the element is given focus.  The event
+			target MUST be the element which is about to receive focus.
+			This event type is similar to focus, but is dispatched			before focus is shifted, and does bubble.

+    
 When using this event type, the content author can use the event’s relatedTarget attribute (or a host-language-specific
+			method or means) to get the currently focused element before the
+			focus shifts to the next focus event target, thus having
+			access to both the element losing focus and the element gaining
+			focus without the use of the blur or focusout event			types. 

+    
4.2.4.4. focusout

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       focusout
+      
Interface
+       FocusEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Window, Element
+      
Cancelable
+       No
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when an event
+			target is about to lose focus. This event type MUST be
+			dispatched before the element loses focus.  The event target MUST be the element which is about to lose focus.  This event type
+			is similar to blur, but is dispatched before focus is			shifted, and does bubble.

+    
4.3. Mouse Events

+    
The mouse event module originates from the [HTML40] onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, and onmouseout attributes. This event module is specifically
+	designed for use with pointing input devices, such as a mouse or a trackball.

+    
4.3.1. Interface MouseEvent

+    
Introduced in DOM Level 2, modified in this
+		specification 

+    
The MouseEvent interface provides specific contextual information
+		associated with Mouse events.

+    
In the case of nested elements, mouse events are always targeted at the
+		most deeply nested element.

+    
 Ancestors of the targeted element can use event bubbling to obtain
+		notifications of mouse events which occur within their descendent
+		elements. 

+    
To create an instance of the MouseEvent interface, use the MouseEvent constructor, passing an optional MouseEventInit dictionary.

+    
 When initializing MouseEvent objects using initMouseEvent,
+		implementations can use the client coordinates clientX and clientY for calculation of other coordinates (such
+		as target coordinates exposed by DOM Level 0 implementations or
+		other proprietary attributes, e.g., pageX). 

+    
4.3.1.1. MouseEvent

+
[Constructor(DOMString type, optional MouseEventInit eventInitDict)]
+interface MouseEvent : UIEvent {
+  readonly attribute long screenX;
+  readonly attribute long screenY;
+  readonly attribute long clientX;
+  readonly attribute long clientY;
+
+  readonly attribute boolean ctrlKey;
+  readonly attribute boolean shiftKey;
+  readonly attribute boolean altKey;
+  readonly attribute boolean metaKey;
+
+  readonly attribute short button;
+  readonly attribute unsigned short buttons;
+
+  readonly attribute EventTarget? relatedTarget;
+
+  boolean getModifierState(DOMString keyArg);
+};
+

+    

+     
screenX,  of type long, readonly
+     

+       The horizontal coordinate at which the event occurred relative
+					to the origin of the screen coordinate system. 
+      
The un-initialized value of this attribute MUST be 0.

+     
screenY,  of type long, readonly
+     

+       The vertical coordinate at which the event occurred relative to
+					the origin of the screen coordinate system. 
+      
The un-initialized value of this attribute MUST be 0.

+     
clientX,  of type long, readonly
+     

+       The horizontal coordinate at which the event occurred relative
+					to the viewport associated with the event. 
+      
The un-initialized value of this attribute MUST be 0.

+     
clientY,  of type long, readonly
+     

+       The vertical coordinate at which the event occurred relative
+					to the viewport associated with the event. 
+      
The un-initialized value of this attribute MUST be 0.

+     
ctrlKey,  of type boolean, readonly
+     

+       Refer to the KeyboardEvent's ctrlKey attribute. 
+      
The un-initialized value of this attribute MUST be false.

+     
shiftKey,  of type boolean, readonly
+     

+       Refer to the KeyboardEvent's shiftKey attribute. 
+      
The un-initialized value of this attribute MUST be false.

+     
altKey,  of type boolean, readonly
+     

+       Refer to the KeyboardEvent's altKey attribute. 
+      
The un-initialized value of this attribute MUST be false.

+     
metaKey,  of type boolean, readonly
+     

+       Refer to the KeyboardEvent's metaKey attribute. 
+      
The un-initialized value of this attribute MUST be false.

+     
button,  of type short, readonly
+     

+       During mouse events caused by the depression or release of a mouse button, button MUST be used to indicate which pointer device button
+					changed state. 
+      
The value of the button attribute MUST be as follows:

+      
    
+       
  • 
+        
    0 MUST indicate the primary button of the device
+(in general, the left button  or the only button on single-button devices,
+used to activate a user interface control or select text) or the
+un-initialized value.
    
+       
  • 
+        
    1 MUST indicate the auxiliary button
+(in general, the middle button, often combined with a mouse wheel).
    
+       
  • 
+        
    2 MUST indicate the secondary button
+(in general, the right button, often used to display a context menu).
    
+      

+      
Some pointing devices provide or simulate more button states, and values higher than 2 or lower than 0 MAY be used to represent such buttons.

+      
 The value of button is not updated for events not caused by the
+					depression/release of a mouse button.
+					In these scenarios, take care not to interpret the value 0 as the
+					left button, but rather as the un-initialized value. 

+      
 Some default actions related
+					to events such as mousedown and mouseup depend on the specific mouse					button in use. 

+      
The un-initialized value of this attribute MUST be 0.

+     
buttons,  of type unsigned short, readonly
+     

+       During any mouse events, buttons MUST be used to
+					indicate which combination of mouse buttons are currently being
+					pressed, expressed as a bitmask. 
+      
 Though similarly named, the values for the buttons attribute and the button attribute are very different. The value of button is assumed to be valid during mousedown / mouseup event handlers, whereas the buttons attribute
+					reflects the state of the mouse’s buttons for any trusted MouseEvent object (while it is being dispatched), because it
+					can represent the "no button currently active" state (0). 

+      
The value of the buttons attribute MUST be as follows:

+      
    
+       
  • 
+        
    0 MUST indicate no button is currently active.
    
+       
  • 
+        
    1 MUST indicate the primary button of the device
+(in general, the left button or the only button on single-button devices,
+used to activate a user interface control or select text).
    
+       
  • 
+        
    2 MUST indicate the secondary button
+(in general, the right button, often used to display a context menu), if present.
    
+       
  • 
+        
    4 MUST indicate the auxiliary button
+(in general, the middle button, often combined with a mouse wheel).
    
+      

+      
Some pointing devices provide or simulate more buttons. To
+					represent such buttons, the value MUST be doubled for each
+					successive button (in the binary series 8, 16, 32, ... ).

+      
 Because the sum of any set of button values is a unique number,
+					a content author can use a bitwise operation to determine how
+					many buttons are currently being pressed and which buttons they
+					are, for an arbitrary number of mouse buttons on a device. For
+					example, the value 3 indicates that the left and
+					right button are currently both pressed, while the value 5 indicates that the left and middle button are
+					currently both pressed. 

+      
 Some default actions related to events such as mousedown and mouseup depend on the specific mouse					button in use. 

+      
The un-initialized value of this attribute MUST be 0.

+     
relatedTarget,  of type EventTarget, readonly, nullable
+     

+       Used to identify a secondary EventTarget related to a UI event, depending on the type of event. 
+      
The un-initialized value of this attribute MUST be null.

+     
getModifierState(keyArg)
+     

+      
Introduced in this specification

+      
Queries the state of a modifier using a key value.
+					See §5.3.1 Modifier keys for a list of valid (case-sensitive)
+					arguments to this method.

+      
Returns true if it is a modifier key and the
+					modifier is activated, false otherwise.

+      

+       
DOMString keyArg
+       
 Refer to the KeyboardEvent's getModifierState() method for a description of this parameter. 
+      

+    

+    
4.3.1.2. MouseEventInit

+
dictionary MouseEventInit : EventModifierInit {
+  long screenX = 0;
+  long screenY = 0;
+  long clientX = 0;
+  long clientY = 0;
+
+  short button = 0;
+  unsigned short buttons = 0;
+  EventTarget? relatedTarget = null;
+};
+

+    

+     
screenX,  of type long, defaulting to 0
+     

+       Initializes the screenX attribute of the MouseEvent object to the desired horizontal relative position of the mouse
+					pointer on the user’s screen. 
+      
Initializing the event object to the given mouse position must
+					not move the user’s mouse pointer to the initialized position.

+     
screenY,  of type long, defaulting to 0
+     

+       Initializes the screenY attribute of the MouseEvent object to the desired vertical relative position of the mouse
+					pointer on the user’s screen. 
+      
Initializing the event object to the given mouse position must
+					not move the user’s mouse pointer to the initialized position.

+     
clientX,  of type long, defaulting to 0
+     

+       Initializes the clientX attribute of the MouseEvent object to the desired horizontal position of the mouse pointer
+					relative to the client window of the user’s browser. 
+      
Initializing the event object to the given mouse position must
+					not move the user’s mouse pointer to the initialized position.

+     
clientY,  of type long, defaulting to 0
+     

+       Initializes the clientY attribute of the MouseEvent object to the desired vertical position of the mouse pointer
+					relative to the client window of the user’s browser. 
+      
Initializing the event object to the given mouse position must
+					not move the user’s mouse pointer to the initialized position.

+     
button,  of type short, defaulting to 0
+     

+       Initializes the button attribute of the MouseEvent object to a number representing the desired state of the button(s)
+					of the mouse. 
+      
 The value 0 is used to represent
+					the primary mouse button, 1 is used to represent the auxiliary/middle
+					mouse button, and 2 to represent the right mouse button.
+					Numbers greater than 2 are also possible, but are not specified
+					in this document. 

+     
buttons,  of type unsigned short, defaulting to 0
+     

+       Initializes the buttons attribute of the MouseEvent object to a number representing one or more of the button(s) of the mouse
+					that are to be considered active. 
+      
 The buttons attribute is a bit-field. If a mask value of 1 is true when applied to
+					the value of the bit field, then the primary mouse button is down. If a
+					mask value of 2 is true when applied to the value of the bit field, then
+					the right mouse button is down. If a mask value of 4 is true when applied
+					to the value of the bit field, then the auxiliary/middle button is down. 

+      
 In JavaScript, to initialize the buttons attribute as if the right (2) and middle
+					button (4) were being pressed simultaneously, the buttons value
+					can be assigned as either:
   { buttons: 2 | 4 }
 or:
   { buttons: 6 } 

+     
relatedTarget,  of type EventTarget, nullable, defaulting to null
+     
 The relatedTarget should be initialized to the element
+					whose bounds the mouse pointer just left (in the case of a mouseover or mouseenter event) or the element
+					whose bounds the mouse pointer is entering (in the case of a mouseout or mouseleave or focusout event). For other events, this value need not
+					be assigned (and will default to null). 
+    

+    
Implementations MUST maintain the current
+	click count when generating mouse events. This MUST be a non-negative
+	integer indicating the number of consecutive clicks of a pointing device
+	button within a specific time. The delay after which the count resets is
+	specific to the environment configuration. 

+    
4.3.2. Event Modifier Initializers

+    
The MouseEvent and KeyboardEvent interfaces share a set of
+		keyboard modifier attributes and support a mechanism for retrieving
+		additional modifier states. The following dictionary enables authors to
+		initialize keyboard modifier attributes of the MouseEvent and KeyboardEvent interfaces, as well as the additional modifier states
+		queried via getModifierState(). The steps for
+		constructing events using this dictionary are defined in the event constructors section.

+
dictionary EventModifierInit : UIEventInit {
+  boolean ctrlKey = false;
+  boolean shiftKey = false;
+  boolean altKey = false;
+  boolean metaKey = false;
+
+  boolean modifierAltGraph = false;
+  boolean modifierCapsLock = false;
+  boolean modifierFn = false;
+  boolean modifierFnLock = false;
+  boolean modifierHyper = false;
+  boolean modifierNumLock = false;
+  boolean modifierScrollLock = false;
+  boolean modifierSuper = false;
+  boolean modifierSymbol = false;
+  boolean modifierSymbolLock = false;
+};
+

+    

+     
ctrlKey,  of type boolean, defaulting to false
+     

+       Initializes the ctrlKey attribute of the MouseEvent or KeyboardEvent objects to true if the Control key modifier is to be considered active, false otherwise. 
+      
When true, implementations must also initialize the event object’s key modifier
+				state such that calls to the getModifierState() or getModifierState() when provided with the parameter Control must return true.

+     
shiftKey,  of type boolean, defaulting to false
+     

+       Initializes the shiftKey attribute of the MouseEvent or KeyboardEvent objects to true if the Shift key modifier is to be considered active, false otherwise. 
+      
When true, implementations must also initialize the event object’s key modifier
+				state such that calls to the getModifierState() or getModifierState() when provided with the parameter Shift must				return true.

+     
altKey,  of type boolean, defaulting to false
+     

+       Initializes the altKey attribute of the MouseEvent or KeyboardEvent objects to true if the Alt (alternative) (or Option) key modifier				is to be considered active, false otherwise. 
+      
When true, implementations must also initialize the event object’s key modifier
+				state such that calls to the getModifierState() or getModifierState() when provided with the parameter Alt must				return true.

+     
metaKey,  of type boolean, defaulting to false
+     

+       Initializes the metaKey attribute of the MouseEvent or KeyboardEvent objects to true if the Meta key modifier is to be considered active, false otherwise. 
+      
When true, implementations must also initialize the event object’s
+				key modifier state such that calls to the getModifierState() or getModifierState() when provided with either the parameter Meta must return true.

+     
modifierAltGraph,  of type boolean, defaulting to false
+     
 Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter AltGraph must				return true. 
+     
modifierCapsLock,  of type boolean, defaulting to false
+     
 Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter CapsLock must				return true. 
+     
modifierFn,  of type boolean, defaulting to false
+     
 Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Fn must				return true. 
+     
modifierFnLock,  of type boolean, defaulting to false
+     
 Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter FnLock must				return true. 
+     
modifierHyper,  of type boolean, defaulting to false
+     
 Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Hyper must				return true. 
+     
modifierNumLock,  of type boolean, defaulting to false
+     
 Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter NumLock must				return true. 
+     
modifierScrollLock,  of type boolean, defaulting to false
+     
 Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter ScrollLock must				return true. 
+     
modifierSuper,  of type boolean, defaulting to false
+     
 Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Super must				return true. 
+     
modifierSymbol,  of type boolean, defaulting to false
+     
 Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter Symbol must				return true. 
+     
modifierSymbolLock,  of type boolean, defaulting to false
+     
 Initializes the event object’s key modifier state such that calls to the getModifierState() or getModifierState() when provided with the parameter SymbolLock must				return true. 
+    

+    
4.3.3. Mouse Event Order

+    
Certain mouse events defined in this specification MUST occur in a set
+		order relative to one another. The following shows the event sequence
+		that MUST occur when a pointing device’s cursor is moved over an element:

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       

+       Event Type
+       Element
+       Notes
+      
1
+       mousemove
+       
+       
+      

+       
+       
+       Pointing device is moved into element A...
+      
2
+       mouseover
+       A
+       
+      
3
+       mouseenter
+       A
+       
+      
4
+       mousemove
+       A
+       Multiple mousemove events
+      

+       
+       
+       Pointing device is moved out of element A...
+      
5
+       mouseout
+       A
+       
+      
6
+       mouseleave
+       A
+       
+    

+    
When a pointing device is moved into an element A, and then
+		into a nested element B and then back out again, the following
+		sequence of events MUST occur:

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       

+       Event Type
+       Element
+       Notes
+      
1
+       mousemove
+       
+       
+      

+       
+       
+       Pointing device is moved into element A...
+      
2
+       mouseover
+       A
+       
+      
3
+       mouseenter
+       A
+       
+      
4
+       mousemove
+       A
+       Multiple mousemove events
+      

+       
+       
+       Pointing device is moved into nested element B...
+      
5
+       mouseout
+       A
+       
+      
6
+       mouseover
+       B
+       
+      
7
+       mouseenter
+       B
+       
+      
8
+       mousemove
+       B
+       Multiple mousemove events
+      

+       
+       
+       Pointing device is moved from element B into A...
+      
9
+       mouseout
+       B
+       
+      
10
+       mouseleave
+       B
+       
+      
11
+       mouseover
+       A
+       
+      
12
+       mousemove
+       A
+       Multiple mousemove events
+      

+       
+       
+       Pointing device is moved out of element A...
+      
13
+       mouseout
+       A
+       
+      
14
+       mouseleave
+       A
+       
+    

+    
Sometimes elements can be visually overlapped using CSS. In the
+		following example, three elements labeled A, B, and C all have the same
+		dimensions and absolute position on a web page. Element C is a child of
+		B, and B is a child of A in the DOM:

+    

+      Graphical representation of three stacked elements all on top of each other. The bottom element is labeled A and the top element is C 
+     
Graphical representation of three stacked elements all on top of each other, with the pointing device moving over the stack.

+    

+    
When the pointing device is moved from outside the element stack to the
+		element labeled C and then moved out again, the following series of
+		events MUST occur:

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       

+       Event Type
+       Element
+       Notes
+      
1
+       mousemove
+       
+       
+      

+       
+       
+       Pointing device is moved into element C, the topmost element in the stack
+      
2
+       mouseover
+       C
+       
+      
3
+       mouseenter
+       A
+       
+      
4
+       mouseenter
+       B
+       
+      
5
+       mouseenter
+       C
+       
+      
6
+       mousemove
+       C
+       Multiple mousemove events
+      

+       
+       
+       Pointing device is moved out of element C...
+      
7
+       mouseout
+       C
+       
+      
8
+       mouseleave
+       C
+       
+      
9
+       mouseleave
+       B
+       
+      
10
+       mouseleave
+       A
+       
+    

+    
 The mouseover/mouseout events are only fired once, while mouseenter/mouseleave events are fired three times (once		to each element). 

+    
The following is the typical sequence of events when a button associated
+		with a pointing device (e.g., a mouse button or trackpad) is pressed and
+		released over an element:

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       

+       Event Type
+       Notes
+      
1
+       mousedown
+       
+      
2
+       mousemove
+       OPTIONAL, multiple events, some limits
+      
3
+       mouseup
+       
+      
4
+       click
+       
+      
5
+       mousemove
+       OPTIONAL, multiple events, some limits
+      
6
+       mousedown
+       
+      
7
+       mousemove
+       OPTIONAL, multiple events, some limits
+      
8
+       mouseup
+       
+      
9
+       click
+       
+      
10
+       dblclick
+       
+    

+    
 The lag time, degree, distance, and number of mousemove events		allowed between the mousedown and mouseup events while		still firing a click or dblclick event will be		implementation-, device-, and platform-specific. This tolerance can aid
+		users that have physical disabilities like unsteady hands when these
+		users interact with a pointing device. 

+    
Each implementation will determine the appropriate hysteresis tolerance, but in general SHOULD fire click and dblclick events when the event target of the associated mousedown and mouseup events is the same element with no mouseout or mouseleave events intervening, and SHOULD fire click and dblclick events on the nearest common inclusive ancestor when the		associated mousedown and mouseup event targets are		different.

+    
 If a mousedown event was targeted at an HTML document’s body		element, and the corresponding mouseup event was targeted at		the root element, then the click event will be dispatched		to the root element, since it is the nearest common inclusive
+		ancestor. 

+    
If the event target (e.g. the target element) is removed from the
+		DOM during the mouse events sequence, the remaining events of the
+		sequence MUST NOT be fired on that element.

+    
 If the target element is removed from the DOM as the result of a mousedown event, no events for that element will be dispatched		for mouseup, click, or dblclick, nor any default		activation events. However, the mouseup event will still be		dispatched on the element that is exposed to the mouse after the removal
+		of the initial target element. Similarly, if the target element is
+		removed from the DOM during the dispatch of a mouseup event, the click and subsequent events will not be dispatched. 

+    
4.3.4. Mouse Event Types

+    
The Mouse event types are listed below. In the case of nested elements,
+		mouse event types are always targeted at the most deeply nested element.
+		Ancestors of the targeted element MAY use bubbling to obtain
+		notification of mouse events which occur within its descendent elements.

+    
4.3.4.1. auxclick

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       auxclick
+      
Interface
+       MouseEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       Varies
+      
Context
 (trusted events)
+       		
+        
+    

+    
The auxclick event type MUST be dispatched on the topmost			event target indicated by the pointer, when the user presses
+			down and releases the non-primary pointer button, or otherwise activates
+			the pointer in a manner that simulates such an action. The actuation
+			method of the mouse button depends upon the pointer device and the
+			environment configuration, e.g., it MAY depend on the screen
+			location or the delay between the press and release of the pointing
+			device button.

+    
The auxclick event should only be fired for the non-primary pointer			buttons (i.e., when button value is not 0, buttons value is greater than 1). The primary button
+			(like the left button on a standard mouse) MUST NOT fire auxclick events. See click for a corresponding event that			is associated with the primary button.

+    
The auxclick event MAY be preceded by the mousedown and mouseup events on the same element, disregarding changes			between other node types (e.g., text nodes).  Depending upon the
+			environment configuration, the auxclick event MAY be dispatched			if one or more of the event types mouseover, mousemove, and mouseout occur between the press and			release of the pointing device button.

+    
The default action of the auxclick event type varies			based on the event target of the event and the value of the button or buttons attributes. Typical default actions of the auxclick event type are as follows:

+    
+    
 Receiving and handling auxclick for the middle button.
 myLink.addEventListener("auxclick", function(e) {
+  if (e.button === 1) {
+    // This would prevent the default behavior which is for example
+    // opening a new tab when middle clicking on a link.
+    e.preventDefault();
+    // Do something else to handle middle button click like taking
+    // care of opening link or non-link buttons in new tabs in a way
+    // that fits the app. Other actions like closing a tab in a tab-strip
+    // which should be done on the click action can be done here too.
+  }
+});  

+    
 In the case of right button, the auxclick event is dispatched after			any contextmenu event. Note that some user agents swallow all input			events while a context menu is being displayed, so auxclick may not be
+			available to applications in such scenarios.
+			See this example for more clarification. 

+    
 Receiving and handling auxlick for the right button
 myDiv.addEventListener("contextmenu", function(e) {
+  // This call makes sure no context menu is shown
+  // to interfere with page receiving the events.
+  e.preventDefault();
+});
+myDiv.addEventListener("auxclick", function(e) {
+  if (e.button === 2) {
+    // Do something else to handle right button click like opening a
+    // customized context menu inside the app.
+  }
+});  

+    
4.3.4.2. click

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       click
+      
Interface
+       MouseEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       Varies
+      
Context
 (trusted events)
+       		
+        
+    

+    
The click event type MUST be dispatched on the topmost			event target indicated by the pointer, when the user presses
+			down and releases the primary pointer button, or otherwise activates
+			the pointer in a manner that simulates such an action. The actuation
+			method of the mouse button depends upon the pointer device and the
+			environment configuration, e.g., it MAY depend on the screen
+			location or the delay between the press and release of the pointing
+			device button.

+    
The click event should only be fired for the primary pointer			button (i.e., when button value is 0, buttons value is 1). Secondary buttons
+			(like the middle or right button on a standard mouse) MUST NOT fire click events. See auxclick for a corresponding event that			is associated with the non-primary buttons.

+    
The click event MAY be preceded by the mousedown and mouseup events on the same element, disregarding changes			between other node types (e.g., text nodes).  Depending upon the
+			environment configuration, the click event MAY be dispatched			if one or more of the event types mouseover, mousemove, and mouseout occur between the press and			release of the pointing device button.  The click event MAY			also be followed by the dblclick event.

+    
 If a user mouses down on a text node child of a <p> element which has been styled with a large
+			line-height, shifts the mouse slightly such that it is no longer
+			over an area containing text but is still within the containing
+			block of that <p> element (i.e., the pointer is
+			between lines of the same text block, but not over the text node per
+			se), then subsequently mouses up, this will likely still trigger a click event (if it falls within the normal temporal hysteresis for a click), since the user has stayed			within the scope of the same element. Note that user-agent-generated
+			mouse events are not dispatched on text nodes. 

+    
In addition to being associated with pointer devices, the click event type MUST be dispatched as part of an element			activation, as described in §3.5 Activation triggers and behavior.

+    
 For maximum accessibility, content authors are encouraged to use the click event type when defining activation behavior for custom			controls, rather than other pointing-device event types such as mousedown or mouseup, which are more device-specific.			Though the click event type has its origins in pointer			devices (e.g., a mouse), subsequent implementation enhancements have
+			extended it beyond that association, and it can be considered a
+			device-independent event type for element activation. 

+    
The default action of the click event type varies			based on the event target of the event and the value of the button or buttons attributes. Typical default actions of the click event type are as follows:

+    
+    
4.3.4.3. dblclick

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       dblclick
+      
Interface
+       MouseEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when the primary button
+			of a pointing device is clicked twice over an element. The
+			definition of a double click depends on the environment
+			configuration, except that the event target MUST be the same between mousedown, mouseup, and dblclick. This event			type MUST be dispatched after the event type click if a click			and double click occur simultaneously, and after the event type mouseup otherwise.
+			As with the click event, the dblclick event should			only be fired for the primary pointer button. Secondary buttons MUST
+			NOT fire dblclick events.

+    
 Canceling the click event does not affect the firing of a dblclick event. 

+    
As with the click event type, the default action of			the dblclick event type varies based on the event			target of the event and the value of the button or buttons attributes. Normally, the typical default actions of the dblclick event type match those			of the click event type, with the following additional			behavior:

+    
    
+     
  • 
+      
    If the event target is selectable, the default
+action MUST be to select part or all of the selectable
+content. Subsequent clicks MAY select additional selectable
+portions of that content.
    
+    

+    
4.3.4.4. mousedown

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       mousedown
+      
Interface
+       MouseEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       Varies: Start a drag/drop operation; start a text selection; start a scroll/pan interaction (in combination with the middle mouse button, if supported)
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a pointing device
+			button is pressed over an element.

+    
 Many implementations use the mousedown event to begin a			variety of contextually dependent default actions. These
+			default actions can be prevented if this event is canceled. Some of
+			these default actions could include: beginning a drag/drop
+			interaction with an image or link, starting text selection, etc.
+			Additionally, some implementations provide a mouse-driven panning
+			feature that is activated when the middle mouse button is pressed at
+			the time the mousedown event is dispatched. 

+    
4.3.4.5. mouseenter

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       mouseenter
+      
Interface
+       MouseEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       No
+      
Trusted Targets
+       Element
+      
Cancelable
+       No
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a pointing device
+			is moved onto the boundaries of an element or one of its descendent
+			elements.  This event type is similar to mouseover, but			differs in that it does not bubble, and MUST NOT be dispatched when
+			the pointer device moves from an element onto the boundaries of one
+			of its descendent elements.

+    
 There are similarities between this event type and the CSS :hover pseudo-class [CSS2].
+			See also the mouseleave event type. 

+    
4.3.4.6. mouseleave

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       mouseleave
+      
Interface
+       MouseEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       No
+      
Trusted Targets
+       Element
+      
Cancelable
+       No
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a pointing device
+			is moved off of the boundaries of an element and all of its
+			descendent elements.  This event type is similar to mouseout,			but differs in that does not bubble, and that it MUST NOT be
+			dispatched until the pointing device has left the boundaries of the
+			element and the boundaries of all of its children.

+    
 There are similarities between this event type and the CSS :hover pseudo-class [CSS2].
+			See also the mouseenter event type. 

+    
4.3.4.7. mousemove

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       mousemove
+      
Interface
+       MouseEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a pointing device
+			is moved while it is over an element.  The frequency rate of events
+			while the pointing device is moved is implementation-, device-, and
+			platform-specific, but multiple consecutive mousemove events			SHOULD be fired for sustained pointer-device movement, rather than a
+			single event for each instance of mouse movement.  Implementations
+			are encouraged to determine the optimal frequency rate to balance
+			responsiveness with performance.

+    
 In some implementation environments, such as a browser, mousemove events can continue to fire if the user began a			drag operation (e.g., a mouse button is pressed) and the pointing
+			device has left the boundary of the user agent. 

+    
 This event was formerly specified to be non-cancelable in DOM Level
+			2 Events [DOM-Level-2-Events], but was changed to reflect existing
+			interoperability between user agents. 

+    
4.3.4.8. mouseout

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       mouseout
+      
Interface
+       MouseEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a pointing device
+			is moved off of the boundaries of an element.  This event type is
+			similar to mouseleave, but differs in that does bubble, and			that it MUST be dispatched when the pointer device moves from an
+			element onto the boundaries of one of its descendent elements.

+    
 See also the mouseover event type. 

+    
4.3.4.9. mouseover

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       mouseover
+      
Interface
+       MouseEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a pointing device
+			is moved onto the boundaries of an element.  This event type is
+			similar to mouseenter, but differs in that it bubbles, and			that it MUST be dispatched when the pointer device moves onto the
+			boundaries of an element whose ancestor element is the event
+			target for the same event listener instance.

+    
 See also the mouseout event type. 

+    
4.3.4.10. mouseup

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       mouseup
+      
Interface
+       MouseEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       Invoke a context menu (in combination with the right mouse button, if supported)
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a pointing device
+			button is released over an element.

+    
 Many implementations will invoke a context menu as the default
+			action of this event if the right mouse button is being released. 

+    
 In some implementation environments, such as a browser, a mouseup event can be dispatched even if the pointing device			has left the boundary of the user agent, e.g., if the user began a
+			drag operation with a mouse button pressed. 

+    
4.4. Wheel Events

+    
Wheels are devices that can be rotated in one or more spatial dimensions, and which can be associated with a pointer device. The coordinate system depends on the
+	environment configuration.

+    
 The user’s environment might be configured to associate vertical scrolling
+	with rotation along the y-axis, horizontal scrolling with rotation along the
+	x-axis, and zooming with rotation along the z-axis. 

+    
The deltaX, deltaY, and deltaZ attributes of WheelEvent objects indicate
+	a measurement along their respective axes in units of pixels, lines, or
+	pages. The reported measurements are provided after an environment-specific
+	algorithm translates the actual rotation/movement of the wheel device into
+	the appropriate values and units.

+    
 A user’s environment settings can be customized to interpret actual rotation/movement
+	of a wheel device in different ways.
+	One movement of a common dented mouse wheel can produce a measurement of 162 pixels
+	(162 is just an example value, actual values can depend on the current screen
+	dimensions of the user-agent).
+	But a user can change their default environment settings to speed-up their mouse wheel,
+	increasing this number.
+	Furthermore, some mouse wheel software can support acceleration (the faster the wheel
+	is rotated/moved, the greater the delta of each measurement) or even sub-pixel rotation measurements.
+	Because of this, authors can not assume a given rotation amount in one user agent will
+	produce the same delta value in all user agents. 

+    
The sign (positive or negative) of the values of the deltaX, deltaY, and deltaZ attributes
+	MUST be consistent between multiple dispatches of the wheel event while the	motion of the actual wheel device is rotating/moving in the same direction.
+	If a user agent scrolls as the default action of the wheel event then the sign	of the delta SHOULD be given by a right-hand coordinate system where positive X,
+	Y, and Z axes are directed towards the right-most edge, bottom-most edge, and farthest
+	depth (away from the user) of the document, respectively.

+    
 Individual user agents can (depending on their environment and hardware configuration)
+	interpret the same physical user interaction on the wheel differently.
+	For example, a vertical swipe on the edge of a trackpad from top to bottom can be
+	interpreted as a wheel action intended to either scroll the
+	page down or to pan the page up (i.e., resulting in either a positive or negative
+	deltaY value respectively). 

+    
4.4.1. Interface WheelEvent

+    
Introduced in this specification

+    
The WheelEvent interface provides specific contextual information
+		associated with wheel events.
+		To create an instance of the WheelEvent interface, use the WheelEvent constructor,
+		passing an optional WheelEventInit dictionary.

+    
4.4.1.1. WheelEvent

+
[Constructor(DOMString type, optional WheelEventInit eventInitDict)]
+interface WheelEvent : MouseEvent {
+  // DeltaModeCode
+  const unsigned long DOM_DELTA_PIXEL = 0x00;
+  const unsigned long DOM_DELTA_LINE  = 0x01;
+  const unsigned long DOM_DELTA_PAGE  = 0x02;
+
+  readonly attribute double deltaX;
+  readonly attribute double deltaY;
+  readonly attribute double deltaZ;
+  readonly attribute unsigned long deltaMode;
+};
+

+    

+     
DOM_DELTA_PIXEL
+     
 The units of measurement for the delta MUST be pixels.
+					This is the most typical case in most operating system and
+					implementation configurations. 
+     
DOM_DELTA_LINE
+     
 The units of measurement for the delta MUST be individual
+					lines of text.  This is the case for many form controls. 
+     
DOM_DELTA_PAGE
+     
 The units of measurement for the delta MUST be pages,
+					either defined as a single screen or as a demarcated page. 
+     
deltaX,  of type double, readonly
+     

+       In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the
+					x-axis (in pixels, lines, or pages) to be scrolled in the case
+					where the event is not cancelled. Otherwise, this is an
+					implementation-specific measurement (in pixels, lines, or pages)
+					of the movement of a wheel device around the x-axis. 
+      
The un-initialized value of this attribute MUST be 0.0.

+     
deltaY,  of type double, readonly
+     

+       In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the
+					y-axis (in pixels, lines, or pages) to be scrolled in the case
+					where the event is not cancelled. Otherwise, this is an
+					implementation-specific measurement (in pixels, lines, or pages)
+					of the movement of a wheel device around the y-axis. 
+      
The un-initialized value of this attribute MUST be 0.0.

+     
deltaZ,  of type double, readonly
+     

+       In user agents where the default action of the wheel event is to scroll, the value MUST be the measurement along the
+					z-axis (in pixels, lines, or pages) to be scrolled in the case
+					where the event is not cancelled. Otherwise, this is an
+					implementation-specific measurement (in pixels, lines, or pages)
+					of the movement of a wheel device around the z-axis. 
+      
The un-initialized value of this attribute MUST be 0.0.

+     
deltaMode,  of type unsigned long, readonly
+     

+       The deltaMode attribute contains an indication of
+					the units of measurement for the delta values. The
+					default value is DOM_DELTA_PIXEL (pixels). 
+      
This attribute MUST be set to one of the DOM_DELTA constants to
+					indicate the units of measurement for the delta values.
+					The precise measurement is specific to device, operating system,
+					and application configurations.

+      
The un-initialized value of this attribute MUST be 0.

+    

+    
4.4.1.2. WheelEventInit

+
dictionary WheelEventInit : MouseEventInit {
+  double deltaX = 0.0;
+  double deltaY = 0.0;
+  double deltaZ = 0.0;
+  unsigned long deltaMode = 0;
+};
+

+    

+     
deltaX,  of type double, defaulting to 0.0
+     
See deltaZ attribute.
+     
deltaY,  of type double, defaulting to 0.0
+     
See deltaZ attribute.
+     
deltaZ,  of type double, defaulting to 0.0
+     
 Initializes the deltaZ attribute of the WheelEvent object. Relative positive values for this attribute (as well as
+					the deltaX and deltaY attributes) are
+					given by a right-hand coordinate system where the X, Y, and Z
+					axes are directed towards the right-most edge, bottom-most edge,
+					and farthest depth (away from the user) of the document,
+					respectively. Negative relative values are in the respective
+					opposite directions. 
+     
deltaMode,  of type unsigned long, defaulting to 0
+     
 Initializes the deltaMode attribute on the WheelEvent object to the enumerated values 0, 1, or 2, which
+					represent the amount of pixels scrolled
+					(DOM_DELTA_PIXEL), lines scrolled
+					(DOM_DELTA_LINE), or pages scrolled
+					(DOM_DELTA_PAGE) if the rotation of the
+					wheel would have resulted in scrolling. 
+    

+    
4.4.2. Wheel Event Types

+    
4.4.2.1. wheel

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       wheel
+      
Interface
+       WheelEvent
+      
Sync / Async
+       Async
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       Scroll (or zoom) the document
+      
Context
 (trusted events)
+       		
+        
    
+         
  • Event.target : topmost event target
+         
  • UIEvent.view : Window
+         
  • UIEvent.detail : 0
+         
  • MouseEvent.screenX : if the wheel is associated with a pointing device, the value based on the pointer position on the screen, otherwise 0
+         
  • MouseEvent.screenY : if the wheel is associated with a pointing device, the value based on the pointer position on the screen, otherwise 0
+         
  • MouseEvent.clientX : if the wheel is associated with a pointing device, the value based on the pointer position within the viewport, otherwise 0
+         
  • MouseEvent.clientY : if the wheel is associated with a pointing device, the value based on the pointer position within the viewport, otherwise 0
+         
  • MouseEvent.altKey : true if Alt modifier was active, otherwise false
+         
  • MouseEvent.ctrlKey : true if Control modifier was active, otherwise false
+         
  • MouseEvent.shiftKey : true if Shift modifier was active, otherwise false
+         
  • MouseEvent.metaKey : true if Meta modifier was active, otherwise false
+         
  • MouseEvent.button : if wheel is associated with a pointing device, value based on current button pressed, otherwise 0
+         
  • MouseEvent.buttons : if wheel is associated with a pointing device, value based on all buttons current depressed, 0 if no buttons pressed
+         
  • MouseEvent.relatedTarget : indicates the event target the pointing device is pointing at, if any
+         
  • WheelEvent.deltaX : expected amount that the page will scroll along the x-axis according to the deltaMode units; or an implemenation-specific value of movement of a wheel around the x-axis
+         
  • WheelEvent.deltaY : expected amount that the page will scroll along the y-axis according to the deltaMode units; or an implemenation-specific value of movement of a wheel around the y-axis
+         
  • WheelEvent.deltaZ : expected amount that the page will scroll along the z-axis according to the deltaMode units; or an implemenation-specific value of movement of a wheel around the z-axis
+         
  • WheelEvent.deltaMode : unit indicator (pixels, lines, or pages) for the deltaX, deltaY, and deltaZ attributes
+        

+    

+    
A user agent MUST dispatch this event when a mouse wheel has
+			been rotated around any axis, or when an equivalent input device
+			(such as a mouse-ball, certain tablets or touchpads, etc.) has
+			emulated such an action. Depending on the platform and input device,
+			diagonal wheel deltas MAY be delivered either as a single wheel event with multiple non-zero axes or as separate wheel events for each non-zero axis.
+			The typical default action of the wheel event type is			to scroll (or in some cases, zoom) the document by the indicated
+			amount.  If this event is canceled, the implementation MUST NOT
+			scroll or zoom the document (or perform whatever other
+			implementation-specific default action is associated with this event
+			type).

+    
 In some user agents, or with some input devices, the speed
+			that the wheel has been turned can affect the delta values,
+			with a faster speed producing a higher delta value. 

+    
4.5. Input Events

+    
Input events are sent as notifications whenever the DOM is being updated.

+    
4.5.1. Interface InputEvent

+    
4.5.1.1. InputEvent

+    
Introduced in DOM Level 3

+
[Constructor(DOMString type, optional InputEventInit eventInitDict)]
+interface InputEvent : UIEvent {
+  readonly attribute DOMString? data;
+  readonly attribute boolean isComposing;
+};
+

+    

+     
data,  of type DOMString, readonly, nullable
+     

+       data holds the value of the characters generated by
+					an input method. This MAY be a single Unicode character or a
+					non-empty sequence of Unicode characters [Unicode]. Characters
+					SHOULD be normalized as defined by the Unicode normalization
+					form NFC, defined in [UAX15].
+					This attribute MAY contain the empty string. 
+      
The un-initialized value of this attribute MUST be null.

+     
isComposing,  of type boolean, readonly
+     
 true if the input event occurs as part of a
+					composition session, i.e., after a compositionstart event					and before the corresponding compositionend event.
+					The un-initialized value of this attribute MUST be false. 
+    

+    
4.5.1.2. InputEventInit

+
dictionary InputEventInit : UIEventInit {
+  DOMString? data = "";
+  boolean isComposing = false;
+};
+

+    

+     
data,  of type DOMString, nullable, defaulting to ""
+     
 Initializes the data attribute of the InputEvent object. 
+     
isComposing,  of type boolean, defaulting to false
+     
 Initializes the isComposing attribute of the InputEvent object. 
+    

+    
4.5.2. Input Event Order

+    
The input events defined in this specification MUST occur in a set order
+		relative to one another.

+    
+     
+      
+       
+       
+       
+       

+       Event Type
+       Notes
+      
1
+       beforeinput
+       
+      

+       
+       DOM element is updated
+      
2
+       input
+       
+    

+    
4.5.3. Input Event Types

+    
4.5.3.1. beforeinput

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       beforeinput
+      
Interface
+       InputEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element (specifically: control types such as HTMLInputElement, etc.) or any Element with contenteditable attribute enabled
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       Update the DOM element
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when the DOM is about
+			to be updated.

+    
4.5.3.2. input

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       input
+      
Interface
+       InputEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element (specifically: control types such as HTMLInputElement, etc.) or any Element with contenteditable attribute enabled
+      
Cancelable
+       No
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event immediately after the
+			DOM has been updated.

+    
4.6. Keyboard Events

+    
Keyboard events are device dependent, i.e., they rely on the capabilities of
+	the input devices and how they are mapped in the operating systems. Refer to Keyboard events and key values for more details,
+	including examples on how Keyboard Events are used in combination with
+	Composition Events. Depending on the character generation device, keyboard
+	events might not be generated.

+    
 Keyboard events are only one modality of providing textual input. For
+	editing scenarios, consider also using the InputEvent as an alternate to
+	(or in addition to) keyboard events. 

+    
4.6.1. Interface KeyboardEvent

+    
Introduced in this specification

+    
The KeyboardEvent interface provides specific contextual information
+		associated with keyboard devices. Each keyboard event references a key
+		using a value. Keyboard events are commonly directed at the element that
+		has the focus.

+    
The KeyboardEvent interface provides convenient attributes for some
+		common modifiers keys: ctrlKey, shiftKey, altKey, metaKey. These attributes are equivalent to using the
+		method getModifierState() with Control, Shift, Alt, or Meta respectively.
+		To create an instance of the KeyboardEvent interface, use the KeyboardEvent constructor, passing an optional KeyboardEventInit dictionary.

+    
4.6.1.1. KeyboardEvent

+
[Constructor(DOMString type, optional KeyboardEventInit eventInitDict)]
+interface KeyboardEvent : UIEvent {
+  // KeyLocationCode
+  const unsigned long DOM_KEY_LOCATION_STANDARD = 0x00;
+  const unsigned long DOM_KEY_LOCATION_LEFT = 0x01;
+  const unsigned long DOM_KEY_LOCATION_RIGHT = 0x02;
+  const unsigned long DOM_KEY_LOCATION_NUMPAD = 0x03;
+
+  readonly attribute DOMString key;
+  readonly attribute DOMString code;
+  readonly attribute unsigned long location;
+
+  readonly attribute boolean ctrlKey;
+  readonly attribute boolean shiftKey;
+  readonly attribute boolean altKey;
+  readonly attribute boolean metaKey;
+
+  readonly attribute boolean repeat;
+  readonly attribute boolean isComposing;
+
+  boolean getModifierState(DOMString keyArg);
+};
+

+    

+     
DOM_KEY_LOCATION_STANDARD
+     

+       The key activation MUST NOT be distinguished as the left or
+					right version of the key, and (other than the NumLock key) did not originate from the numeric keypad (or did not
+					originate with a virtual key corresponding to the numeric
+					keypad). 
+      
 The Q key on a PC 101 Key US keyboard.
 The NumLock key on a PC 101 Key US keyboard.
 The 1 key on a PC 101 Key US keyboard located in the					main section of the keyboard. 

+     
DOM_KEY_LOCATION_LEFT
+     

+       The key activated originated from the left key location (when
+					there is more than one possible location for this key). 
+      
 The left Control key on a PC 101 Key US keyboard. 

+     
DOM_KEY_LOCATION_RIGHT
+     

+       The key activation originated from the right key location (when
+					there is more than one possible location for this key). 
+      
 The right Shift key on a PC 101 Key US keyboard. 

+     
DOM_KEY_LOCATION_NUMPAD
+     

+       The key activation originated on the numeric keypad or with a
+					virtual key corresponding to the numeric keypad (when there is
+					more than one possible location for this key). Note that the NumLock key should always be encoded with a location of DOM_KEY_LOCATION_STANDARD. 
+      
 The 1 key on a PC 101 Key US keyboard located on the					numeric pad. 

+     
key,  of type DOMString, readonly
+     

+       key holds a key attribute value corresponding to
+					the key pressed. 
+      
 The key attribute is not related to the legacy keyCode attribute and does not have the same set of
+					values. 

+      
The un-initialized value of this attribute MUST be "" (the empty string).

+     
code,  of type DOMString, readonly
+     

+       code holds a string that identifies the physical
+					key being pressed. The value is not affected by the current
+					keyboard layout or modifier state, so a particular key will
+					always return the same value. 
+      
The un-initialized value of this attribute MUST be "" (the empty string).

+     
location,  of type unsigned long, readonly
+     

+       The location attribute contains an indication
+					of the logical location of the key on the device. 
+      
This attribute MUST be set to one of the DOM_KEY_LOCATION
+					constants to indicate the location of a key on the device.

+      
If a user agent allows keys to be remapped, then the location value for a remapped key MUST be set
+					to a value which is appropriate for the new key. For example, if
+					the "ControlLeft" key is mapped to the "KeyQ" key, then					the location attribute MUST be set to DOM_KEY_LOCATION_STANDARD. Conversely, if the "KeyQ" key is remapped to one of the Control keys,					then the location attribute MUST be set to
+					either DOM_KEY_LOCATION_LEFT or DOM_KEY_LOCATION_RIGHT.

+      
The un-initialized value of this attribute MUST be 0.

+     
ctrlKey,  of type boolean, readonly
+     

+       true if the Control (control) key modifier					was active. 
+      
The un-initialized value of this attribute MUST be false.

+     
shiftKey,  of type boolean, readonly
+     

+       true if the shift (Shift) key modifier was					active. 
+      
The un-initialized value of this attribute MUST be false.

+     
altKey,  of type boolean, readonly
+     
 true if the Alt (alternative) (or "Option") key modifier was active.
+					The un-initialized value of this attribute MUST be false. 
+     
metaKey,  of type boolean, readonly
+     

+       true if the meta (Meta) key modifier was					active. 
+      
 The "Command" ("⌘") key modifier on Macintosh					systems is represented using this key modifier. 

+      
The un-initialized value of this attribute MUST be false.

+     
repeat,  of type boolean, readonly
+     

+       true if the key has been pressed in a sustained
+					manner.  Holding down a key MUST result in the repeating the
+					events keydown, beforeinput, input in this					order, at a rate determined by the system configuration. For
+					mobile devices which have long-key-press behavior, the
+					first key event with a repeat attribute value
+					of true MUST serve as an indication of a long-key-press. The length of time that the key MUST be
+					pressed in order to begin repeating is configuration-dependent. 
+      
The un-initialized value of this attribute MUST be false.

+     
isComposing,  of type boolean, readonly
+     
 true if the key event occurs as part of a
+					composition session, i.e., after a compositionstart event					and before the corresponding compositionend event.
+					The un-initialized value of this attribute MUST be false. 
+     
getModifierState(keyArg)
+     

+       Queries the state of a modifier using a key value. See Modifier keys for a list of valid
+					(case-sensitive) arguments to this method. 
+      

+       
DOMString keyArg
+       

+         A modifier key value.  Valid modifier keys are defined
+							in the Modifier
+							Keys table in [UIEvents-Key]. 
+        
Returns true if it is a modifier key and
+							the modifier is activated, false otherwise.

+        
 If an application wishes to distinguish between right
+							and left modifiers, this information could be deduced
+							using keyboard events and location. 

+      

+    

+    
4.6.1.2. KeyboardEventInit

+
dictionary KeyboardEventInit : EventModifierInit {
+  DOMString key = "";
+  DOMString code = "";
+  unsigned long location = 0;
+  boolean repeat = false;
+  boolean isComposing = false;
+};
+

+    

+     
key,  of type DOMString, defaulting to ""
+     
 Initializes the key attribute of the KeyboardEvent
+					object to the unicode character string representing the meaning
+					of a key after taking into account all keyboard modifiers
+					(such as shift-state). This value is the final effective value
+					of the key. If the key is not a printable character, then it
+					should be one of the key values defined in [UIEvents-Key]. 
+     
code,  of type DOMString, defaulting to ""
+     
 Initializes the code attribute of the KeyboardEvent
+					object to the unicode character string representing the key that
+					was pressed, ignoring any keyboard modifications such as
+					keyboard layout. This value should be one of the code values
+					defined in [UIEvents-Code]]. 
+     
location,  of type unsigned long, defaulting to 0
+     

+       Initializes the location attribute of the
+					KeyboardEvent object to one of the following location numerical
+					constants: 
+      
+     
repeat,  of type boolean, defaulting to false
+     
 Initializes the repeat attribute of the
+					KeyboardEvent object. This attribute should be set to true if the the current KeyboardEvent is considered
+					part of a repeating sequence of similar events caused by the
+					long depression of any single key, false otherwise. 
+     
isComposing,  of type boolean, defaulting to false
+     
 Initializes the isComposing attribute of the
+					KeyboardEvent object. This attribute should be set to true if the event being constructed occurs as part
+					of a composition sequence, false otherwise. 
+    

+    

+      Legacy keyboard event implementations include three additional attributes, keyCode, charCode, and which. The keyCode attribute indicates a numeric value associated with a
+	particular key on a computer keyboard, while the charCode attribute indicates the 
+     ASCII
+      value of the character associated
+	with that key (which might be the same as the keyCode value)
+	and is applicable only to keys that produce a character value. 
+     
In practice, keyCode and charCode are inconsistent
+	across platforms and even the same implementation on different operating
+	systems or using different localizations. This specification does not define
+	values for either keyCode or charCode, or behavior
+	for charCode. In conforming UI Events implementations, content
+	authors can instead use key and code.

+     
For more information, see the informative appendix on Legacy key attributes.

+    

+    
 For compatibility with existing content, virtual keyboards, such as software
+	keyboards on screen-based input devices, are expected to produce the normal
+	range of keyboard events, even though they do not possess physical keys. 

+    
 In some implementations or system configurations, some key events, or their
+	values, might be suppressed by the IME in use. 

+    
4.6.2. Keyboard Event Key Location

+    
The location attribute can be used to disambiguate
+		between key values that can be generated by different
+		physical keys on the keyboard, for example, the left and right Shift key or the physical arrow keys vs. the numpad arrow keys		(when NumLock is off).
+		The following table defines the valid location values
+		for the special keys that have more than one location on the keyboard:

+    
+     
+      
+       
+       
+       
+       
+       
KeyboardEvent . key
+       Valid location values
+      
"Shift", "Control", "Alt", "Meta"
+       DOM_KEY_LOCATION_LEFT, DOM_KEY_LOCATION_RIGHT
+      
"ArrowDown", "ArrowLeft", "ArrowRight", "ArrowUp"
+       DOM_KEY_LOCATION_STANDARD, DOM_KEY_LOCATION_NUMPAD
+      
"End", "Home", "PageDown", "PageUp"
+       DOM_KEY_LOCATION_STANDARD, DOM_KEY_LOCATION_NUMPAD
+      
"0", "1", "2", "2", "4", "5", "6", "7", "8", "9", ".", "Enter", "+", "-", "*", "/"
+       DOM_KEY_LOCATION_STANDARD, DOM_KEY_LOCATION_NUMPAD
+    

+    
For all other keys not listed in this table, the location attribute MUST always be set to DOM_KEY_LOCATION_STANDARD.

+    
4.6.3. Keyboard Event Order

+    
The keyboard events defined in this specification occur in a set order
+		relative to one another, for any given key:

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       

+       Event Type
+       Notes
+      
1
+       keydown
+       
+      
2
+       beforeinput
+       (only for keys which produce a character value)
+      

+       
+       Any default actions related to this key, such as inserting a character in to the DOM.
+      
3
+       input
+       (only for keys which have updated the DOM)
+      

+       
+       Any events as a result of the key being held for a sustained period (see below).
+      
4
+       keyup
+       
+    

+    
If the key is depressed for a sustained period, the following events MAY
+		repeat at an environment-dependent rate: 

+    
+     
+      
+       
+       
+       
+       
+       

+       Event Type
+       Notes
+      
1
+       keydown
+       (with repeat attribute set to true)
+      
2
+       beforeinput
+       (only for keys which produce a character value)
+      

+       
+       Any default actions related to this key, such as inserting a character in to the DOM.
+      
3
+       input
+       (only for keys which have updated the DOM)
+    

+    
 Typically, any default actions associated with any particular key
+		are completed before the keyup event is dispatched. This might		delay the keyup event slightly (though this is not likely to be a		perceptible delay). 

+    
The event target of a key event is the currently focused element
+		which is processing the keyboard activity. This is often an HTML input element or a textual element which is editable, but
+		MAY be an element defined by the host language to accept keyboard
+		input for non-text purposes, such as the activation of an accelerator
+		key or trigger of some other behavior. If no suitable element is in
+		focus, the event target will be the HTML body element if
+		available, otherwise the root element.

+    
 The event target might change between different key events. For
+		example, a keydown event for the Tab key will likely have		a different event target than the keyup event on the same		keystroke. 

+    
4.6.4. Keyboard Event Types

+    
4.6.4.1. keydown

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       keydown
+      
Interface
+       KeyboardEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       Varies: beforeinput and input events; launch text composition system; blur and focus events; keypress event (if supported); activation behavior; other event
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a key is pressed
+			down. The keydown event type is device dependent and relies			on the capabilities of the input devices and how they are mapped in
+			the operating system. This event type MUST be generated after the key mapping. This event type MUST be dispatched before the beforeinput, input, and keyup events associated			with the same key.

+    
The default action of the keydown event depends upon the key:

+    
    
+     
  • 
+      
    If the key is associated with a character, the default action
+MUST be to dispatch a beforeinput event followed by an input event. In the case where the key which is				associated with multiple characters (such as with a macro or
+certain sequences of dead keys), the default action MUST be to
+dispatch one set of beforeinput / input events for				each character
    
+     
  • 
+      
    If the key is associated with a text composition system,
+the default action MUST be to launch that system
    
+     
  • 
+      
    If the key is the Tab key, the default action MUST be				to shift the document focus from the currently focused element
+(if any) to the new focused element, as described in Focus Event Types
    
+     
  • 
+      
    If the key is the Enter or   key and the				current focus is on a state-changing element, the default action
+MUST be to dispatch a click event, and a DOMActivate event if that event type is supported by the user agent (refer to §3.5 Activation triggers and behavior for more
+details)
    
+    

+    
If this event is canceled, the associated event types MUST NOT be
+			dispatched, and the associated actions MUST NOT be performed.

+    
 The keydown and keyup events are traditionally			associated with detecting any key, not just those which produce a character value. 

+    
4.6.4.2. keyup

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       keyup
+      
Interface
+       KeyboardEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a key is released.
+			The keyup event type is device dependent and relies on the			capabilities of the input devices and how they are mapped in the
+			operating system. This event type MUST be generated after the key
+			mapping. This event type MUST be dispatched after the keydown, beforeinput, and input events			associated with the same key.

+    
 The keydown and keyup events are traditionally			associated with detecting any key, not just those which produce a character value. 

+    
4.7. Composition Events

+    
Composition Events provide a means for inputing text in a supplementary or
+	alternate manner than by Keyboard Events, in order to allow the use of
+	characters that might not be commonly available on keyboard. For example,
+	Composition Events might be used to add accents to characters despite their
+	absence from standard US keyboards, to build up logograms of many Asian
+	languages from their base components or categories, to select word choices
+	from a combination of key presses on a mobile device keyboard, or to convert
+	voice commands into text using a speech recognition processor. Refer to §5 Keyboard events and key values for examples on how Composition Events are used in combination
+	with keyboard events.

+    
Conceptually, a composition session consists of one compositionstart event, one or more compositionupdate events, and one compositionend event, with the value of the data attribute persisting between each stage of this event chain during
+	each session.

+    
Note: While a composition session is active, keyboard events can be dispatched to
+	the DOM if the keyboard is the input device used with the composition
+	session. See the compositionstart event details and IME section for relevent event ordering. 

+    
Not all IME systems or devices expose the necessary data to the DOM,
+	so the active composition string (the Reading Window or candidate
+	selection menu option) might not be available through this interface, in
+	which case the selection MAY be represented by the empty string.

+    
4.7.1. Interface CompositionEvent

+    
Introduced in this specification

+    
The CompositionEvent interface provides specific contextual
+		information associated with Composition Events.

+    
To create an instance of the CompositionEvent interface,
+		use the CompositionEvent constructor, passing an optional CompositionEventInit dictionary.

+    
4.7.1.1. CompositionEvent

+
[Constructor(DOMString type, optional CompositionEventInit eventInitDict)]
+interface CompositionEvent : UIEvent {
+  readonly attribute DOMString data;
+};
+

+    

+     
data,  of type DOMString, readonly
+     

+       data holds the value of the characters generated by
+					an input method. This MAY be a single Unicode character or a
+					non-empty sequence of Unicode characters [Unicode]. Characters
+					SHOULD be normalized as defined by the Unicode normalization
+					form NFC, defined in [UAX15]. This
+					attribute MAY be the empty string. 
+      
The un-initialized value of this attribute MUST be "" (the empty string).

+    

+    
4.7.1.2. CompositionEventInit

+
dictionary CompositionEventInit : UIEventInit {
+  DOMString data = "";
+};
+

+    

+     
data,  of type DOMString, defaulting to ""
+     
 Initializes the data attribute of the
+					CompositionEvent object to the characters generated by the IME
+					composition. 
+    

+    
4.7.2. Composition Event Order

+    
The Composition Events defined in this specification MUST occur in the following set order relative to one another:

+    
+     
+      
+       
+       
+       
+       

+       Event Type
+       Notes
+      
1
+       compositionstart
+       
+      
2
+       compositionupdate
+       Multiple events
+      
3
+       compositionend
+       
+    

+    
4.7.3. Handwriting Recognition Systems

+    
The following example describes a possible sequence of events when
+		composing a text passage text with a handwriting recognition
+		system, such as on a pen tablet, as modeled using Composition Events.

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       

+       Event Type
+       CompositionEvent
 data
+       		Notes
+      
1
+       compositionstart
+       ""
+       
+      

+       
+       
+       User writes word on tablet surface
+      
2
+       compositionupdate
+       "test"
+       
+      

+       
+       
+       User rejects first word-match suggestion, selects different match
+      
3
+       compositionupdate
+       "text"
+       
+      
4
+       compositionend
+       "text"
+       
+    

+    
4.7.4. Canceling Composition Events

+    
If a keydown event is canceled then any Composition Events that		would have fired as a result of that keydown SHOULD not be		dispatched:

+    
+     
+      
+       
+       
+       
+       

+       Event Type
+       Notes
+      
1
+       keydown
+       The default action is prevented, e.g., by invoking preventDefault().
+      

+       
+       No Composition Events are dispatched
+      
2
+       keyup
+       
+    

+    
If the initial compositionstart event is canceled then the text		composition session SHOULD be terminated. Regardless of whether or not
+		the composition session is terminated, the compositionend event		MUST be sent.

+    
+     
+      
+       
+       
+       
+       
+       
+       

+       Event Type
+       Notes
+      
1
+       keydown
+       
+      
2
+       compositionstart
+       The default action is prevented, e.g., by invoking preventDefault().
+      

+       
+       No Composition Events are dispatched
+      
3
+       compositionend
+       
+      
4
+       keyup
+       
+    

+    
4.7.5. Key Events During Composition

+    
During the composition session, keydown and keyup events		MUST still be sent, and these events MUST have the isComposing attribute set to true.

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       

+       Event Type
+       KeyboardEvent
 isComposing
+       		Notes
+      
1
+       keydown
+       false
+       This is the key event that initiates the composition.
+      
2
+       compositionstart
+       
+       
+      
3
+       compositionupdate
+       
+       
+      
4
+       keyup
+       true
+       
+      

+       ...
+       
+       Any key events sent during the composition session MUST have isComposing set to true.
+      
5
+       keydown
+       true
+       This is the key event that exits the composition.
+      
6
+       compositionend
+       
+       
+      
7
+       keyup
+       false
+       
+    

+    
4.7.6. Input Events During Composition

+    
During the composition session, the compositionupdate MUST be		dispatched after the beforeinput is sent, but before the input event is sent.

+    
+     
+      
+       
+       
+       
+       
+       

+       Event Type
+       Notes
+      
1
+       beforeinput
+       
+      
2
+       compositionupdate
+       
+      

+       
+       Any DOM updates occur at this point.
+      
3
+       input
+       
+    

+    
 Most IMEs do not support canceling updates during a composition session. 

+    
The beforeinput and input events are sent along with the compositionupdate event whenever the DOM is updated as part of		the composition. Since there are no DOM updates associated with the compositionend event, beforeinput and input events		should not be sent at that time.

+    
+     
+      
+       
+       
+       
+       
+       
+       

+       Event Type
+       Notes
+      
1
+       beforeinput
+        Canceling this will prevent the DOM update and the input event.
+      
2
+       compositionupdate
+       
+      

+       
+       Any DOM updates occur at this point.
+      
3
+       input
+       Sent only if the DOM was updated.
+      
4
+       compositionend
+       
+    

+    
4.7.7. Composition Event Types

+    
4.7.7.1. compositionstart

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       compositionstart
+      
Interface
+       CompositionEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       Start a new composition session when a text composition system is enabled
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a text
+			composition system is enabled and a new composition session is
+			about to begin (or has begun, depending on the text composition
+			system) in preparation for composing a passage of text. This
+			event type is device-dependent, and MAY rely upon the capabilities
+			of the text conversion system and how it is mapped into the
+			operating system. When a keyboard is used to feed an input method
+			editor, this event type is generated after a keydown event,			but speech or handwriting recognition systems MAY send this event
+			type without keyboard events.  Some implementations MAY populate the data attribute of the compositionstart event with the text currently selected in the document (for editing
+			and replacement). Otherwise, the value of the data attribute MUST be  the empty string.

+    
This event MUST be dispatched immediately before a text
+			composition system begins a new composition session, and before
+			the DOM is modified due to the composition process. The default
+			action of this event is for the text composition system to
+			start a new composition session. If this event is canceled, the text composition system SHOULD discard the current
+			composition session.

+    
 Canceling the compositionstart event type is			distinct from canceling the text composition system itself
+			(e.g., by hitting a cancel button or closing an IME window). 

+    
 Some IMEs do not support cancelling an in-progress composition
+			session (e.g., such as GTK which doesn’t presently have such an
+			API). In these cases, calling preventDefault() will not
+			stop this event’s default action. 

+    
4.7.7.2. compositionupdate

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       compositionupdate
+      
Interface
+       CompositionEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       No
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent SHOULD dispatch this event during a composition
+			session when a text composition system updates its active
+			text passage with a new character, which is reflected in the string
+			in data.

+    
In text composition systems which keep the ongoing
+			composition in sync with the input control, the compositionupdate event MUST be dispatched before the control			is updated.

+    
Some text composition systems might not expose this
+			information to the DOM, in which case this event will not fire
+			during the composition process.

+    
If the composition session is canceled, this event will be fired
+			immediately before the compositionend event, and the data attribute will be set to the empty
+			string.

+    
4.7.7.3. compositionend

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       compositionend
+      
Interface
+       CompositionEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       No
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
 (trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a text
+			composition system completes or cancels the current composition
+			session, and the compositionend event MUST be dispatched			after the control is updated.

+    
This event is dispatched immediately after the text composition
+			system completes the composition session (e.g., the IME is closed, minimized, switched out of focus, or otherwise dismissed,
+			and the focus switched back to the user agent).

+   

+   

+    
5. Keyboard events and key values

+    
This section contains necessary information regarding keyboard events:

+    
    
+     
  • 
+      
    Explanation of keyboard layout, mapping, and key values.
    
+     
  • 
+      
    Relations between keys, such as dead keys or modifiers keys.
    
+     
  • 
+      
    Relations between keyboard events and their default actions.
    
+     
  • 
+      
    The set of key values, and guidelines on how to extend this set.
    
+    

+    
 This section uses Serbian and Kanji characters which could be misrepresented or
+unavailable in the PDF version or printed version of this specification. 

+    
5.1. Keyboard Input

+    
This section is non-normative

+    
The relationship of each key to the complete keyboard has three separate
+	aspects, each of which vary among different models and configurations of
+	keyboards, particularly for locale-specific reasons:

+    
    
+     
  • 
+      
    Mechanical layout: the dimensions, size, and placement
+of the physical keys on the keyboard
    
+     
  • 
+      
    Visual markings: the labels (or legends) that
+mark each key
    
+     
  • 
+      
    Functional mapping: the abstract key-value association
+of each key.
    
+    

+    
This specification only defines the functional mapping, in terms of key values and code values,
+	but briefly describes key legends for background.

+    
5.1.1. Key Legends

+    
This section is informative

+    
The key legend is the visual marking that is printed or embossed on the key cap (the rectangular "cap" that covers the mechanical
+		switch for the key). These markings normally consist of one or more
+		characters that a keystroke on that key will produce (such as "G", "8", or "ш"), or names or symbols which indicate that key’s		function (such as an upward-pointing arrow "⇧" indicating Shift, or the string "Enter"). Keys are often		referred to by this marking (e.g., Press the "Shift" and "G" keys.). Note, however, that the visual appearance
+		of the key has no bearing on its digital representation, and in many
+		configurations may be completely inaccurate. Even the control and
+		function keys, such as Enter, may be mapped to different		functionality, or even mapped as character keys.

+    
 Many keyboards contain keys that do not normally produce any characters,
+		even though the symbol might have a Unicode equivalent. For example, the Shift key might bear the symbol "⇧", which has the		Unicode code point U+21E7, but		pressing the Shift key will not produce this character value,		and there is no Unicode code point for Shift. 

+    
5.2. Key codes

+    
A key code is an attribute of a keyboard event that can be
+	used to identify the physical key associated with the keyboard event. It is
+	similar to USB Usage IDs in that it provides a low-level value (similar to a
+	scancode) that is vendor-neutral.

+    
The primary purpose of the code attribute is to provide a
+	consistent and coherent way to identify keys based on their physical
+	location. In addition, it also provides a stable name (unaffected by the
+	current keyboard state) that uniquely identifies each key on the keyboard.

+    
The list of valid code values is defined in the [UIEvents-Code].

+    
5.2.1. Motivation for the code Attribute

+    
The standard PC keyboard has a set of keys (which we refer to as writing system keys) that generate different key values based on the current keyboard layout
+		selected by the user. This situation makes it difficult to write code
+		that detects keys based on their physical location since the code would
+		need to know which layout is in effect in order to know which key values to check for. A real-world example of this
+		is a game that wants to use the "W", "A", "S" and "D" keys to control player movement. The code attribute solves this problem by providing a stable value to check that
+		is not affected by the current keyboard layout.

+    
In addition, the values in the key attribute depend as
+		well on the current keyboard state. Because of this, the order in which
+		keys are pressed and released in relation to modifier keys can affect
+		the values stored in the key attribute. The code attribute solves this problem by providing a
+		stable value that is not affected by the current keyboard state.

+    
5.2.2. The Relationship Between key and code

+    

+     
key
+     
The key attribute is intended for users who
+				are interested in the meaning of the key being pressed, taking
+				into account the current keyboard layout (and IME; dead keys are given a unique key value). Example use case: Detecting
+				modified keys or bare modifier keys (e.g., to perform an action
+				in response to a keyboard shortcut). 
+     
code
+     
The code attribute is intended for users who
+				are interested in the key that was pressed by the user, without
+				any layout modifications applied. Example use case: Detecting
+				WASD keys (e.g., for movement controls in a game) or trapping
+				all keys (e.g., in a remote desktop client to send all keys to
+				the remote host). 
+    

+    
5.2.3. code Examples

+    

+      Handling the Left and Right Alt Keys 
+     
+      
+       
+        
+        
+        
+        
+        
Keyboard Layout
+        KeyboardEvent
 key
+        		KeyboardEvent
 code
+        		Notes
+       
US
+        "Alt"
+        "AltLeft"
+        DOM_KEY_LOCATION_LEFT
+       
French
+        "Alt"
+        "AltLeft"
+        DOM_KEY_LOCATION_LEFT
+       
US
+        "Alt"
+        "AltRight"
+        DOM_KEY_LOCATION_RIGHT
+       
French
+        "AltGr"
+        "AltRight"
+        DOM_KEY_LOCATION_RIGHT
+     

+     
In this example, checking the key attribute permits
+			matching Alt without worrying about which Alt key (left or			right) was pressed. Checking the code attribute
+			permits matching the right Alt key ("AltRight") without worrying			about which layout is currently in effect.

+     
Note that, in the French example, the Alt and AltGr keys			retain their left and right location, even though there is only one of
+			each key.

+    

+    

+      Handling the Single Quote Key 
+     
+      
+       
+        
+        
+        
+        
Keyboard Layout
+        KeyboardEvent
 key
+        		KeyboardEvent
 code
+        		Notes
+       
US
+        "'"
+        "Quote"
+        
+       
Japanese
+        ":"
+        "Quote"
+        
+       
US Intl
+        "Dead"
+        "Quote"
+        
+     

+     
This example shows how dead key values are encoded in the
+			attributes. The key values vary based on the
+			current locale, whereas the code attribute returns
+			a consistent value.

+    

+    

+      Handling the "2" Key (with and without Shift pressed) on			various keyboard layouts. 
+     
+      
+       
+        
+        
+        
+        
+        
+        
+        
Keyboard Layout
+        KeyboardEvent
 key
+        		KeyboardEvent
 code
+        		Notes
+       
US
+        "2"
+        "Digit2"
+        
+       
US
+        "@"
+        "Digit2"
+        shiftKey
+       
UK
+        "2"
+        "Digit2"
+        
+       
UK
+        """
+        "Digit2"
+        shiftKey
+       
French
+        "é"
+        "Digit2"
+        
+       
French
+        "2"
+        "Digit2"
+        shiftKey
+     

+     
Regardless of the current locale or the modifier key state, pressing
+			the key labelled "2" on a US keyboard always results in "Digit2" in the code attribute.

+    

+    

+      Sequence of Keyboard Events : Shift and 2 
+     
Compare the attribute values in the following two key event
+			sequences. They both produce the "@" character on a US			keyboard, but differ in the order in which the keys are released. In
+			the first sequence, the order is: Shift (down), 2 (down), 2 (up), Shift (up).

+     
+      
+       
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		KeyboardEvent
 code
+        		Notes
+       
1
+        keydown
+        "Shift"
+        "ShiftLeft"
+        DOM_KEY_LOCATION_LEFT
+       
2
+        keydown
+        "@"
+        "Digit2"
+        shiftKey
+       
3
+        keypress
+        "@"
+        ""
+        (if supported)
+       
4
+        keyup
+        "@"
+        "Digit2"
+        shiftKey
+       
5
+        keyup
+        "Shift"
+        "ShiftLeft"
+        DOM_KEY_LOCATION_LEFT
+     

+     
In the second sequence, the Shift is released before the 2,
+			resulting in the following event order: Shift (down), 2 (down), Shift (up), 2 (up).

+     
+      
+       
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		KeyboardEvent
 code
+        		Notes
+       
1
+        keydown
+        "Shift"
+        "ShiftLeft"
+        DOM_KEY_LOCATION_LEFT
+       
2
+        keydown
+        "@"
+        "Digit2"
+        shiftKey
+       
3
+        keypress
+        "@"
+        ""
+        (if supported)
+       
4
+        keyup
+        "Shift"
+        "ShiftLeft"
+        DOM_KEY_LOCATION_LEFT
+       
5
+        keyup
+        "2"
+        "Digit2"
+        
+     

+     
Note that the values contained in the key attribute does not match between the keydown and keyup events for
+			the "2" key. The code attribute provides a			consistent value that is not affected by the current modifier state.

+    

+    
5.2.4. code and Virtual Keyboards

+    
The usefulness of the code attribute is less obvious
+		for virtual keyboards (and also for remote controls and chording
+		keyboards). In general, if a virtual (or remote control) keyboard is
+		mimicking the layout and functionality of a standard keyboard, then it
+		MUST also set the code attribute as appropriate. For
+		keyboards which are not mimicking the layout of a standard keyboard,
+		then the code attribute MAY be set to the closest
+		match on a standard keyboard or it MAY be left undefined.

+    
For virtual keyboards with keys that produce different values based on
+		some modifier state, the code value should be the key value generated when the button is pressed while
+		the device is in its factory-reset state.

+    
5.3. Keyboard Event key Values

+    
A key value is a DOMString that can be used to indicate any
+	given key on a keyboard, regardless of position or state, by the value it
+	produces.  These key values MAY be used as return values for keyboard events
+	generated by the implementation, or as input values by the content author to
+	specify desired input (such as for keyboard shortcuts).

+    
The list of valid key values is defined in [UIEvents-Key].

+    
Key values can be used to detect the value of a key which has been pressed,
+	using the key attribute.  Content authors can retrieve the character value of upper- or lower-case letters, number, symbols, or
+	other character-producing keys, and also the key value of control
+	keys, modifier keys, function keys, or other keys that do not generate
+	characters. These values can be used for monitoring particular input
+	strings, for detecting and acting on modifier key input in combination with
+	other inputs (such as a mouse), for creating virtual keyboards, or for any
+	number of other purposes.

+    
Key values can also be used by content authors in string comparisons, as
+	values for markup attributes (such as the HTML accesskey) in
+	conforming host languages, or for other related purposes.   A
+	conforming host language SHOULD allow content authors to use either
+	of the two equivalent string values for a key value: the character
+	value, or the key value.

+    
 While implementations will use the most relevant value for a key
+	independently of the platform or keyboard layout mappings, content authors
+	can not make assumptions on the ability of keyboard devices to generate
+	them.  When using keyboard events and key values for shortcut-key
+	combinations, content authors can consider using numbers and function
+	keys (F4, F5, and so on) instead of letters ([DWW95])	given that most keyboard layouts will provide keys for those. 

+    
A key value does not indicate a specific key on the physical keyboard, nor
+	does it reflect the character printed on the key. A key value indicates the
+	current value of the event with consideration to the current state of all
+	active keys and key input modes (including shift modes), as reflected in the
+	operating-system mapping of the keyboard and reported to the implementation.
+	In other words, the key value for the key labeled O on a QWERTY keyboard has the key value "o" in an unshifted state and "O" in a shifted state. Because a user can map their keyboard to an	arbitrary custom configuration, the content author is encouraged not to
+	assume that a relationship exists between the shifted and unshifted states
+	of a key and the majuscule form (uppercase or capital letters) and minuscule
+	form (lowercase or small letters) of a character representation, but is
+	encouraged instead to use the value of the key attribute.
+	For example, the Standard "102" Keyboard layout depicted in [UIEvents-Code] illustrates one possible set of key mappings on one possible keyboard
+	layout. Many others exist, both standard and idiosyncratic.

+    
 To simplify dead key support, when the operating-system mapping of
+	the keyboard is handling a dead key state, the current state of the
+	dead key sequence is not reported via the key attribute.
+	Rather, a key value of "Dead" is reported. Instead, implementations	generate composition events which
+	contain the intermediate state of the dead key sequence reported via the data attribute. As in the previous example, the key
+	value for the key marked O on a QWERTY keyboard has a data value of 'ö' in an
+	unshifted state during a dead-key operation to add an umlaut diacritic, and 'Ö' in a shifted state during a dead-key
+	operation to add an umlaut diacritic. 

+    
It is also important to note that there is not a one-to-one relationship
+	between key event states and key values.  A particular key value might be
+	associated with multiple keys. For example, many standard keyboards contain
+	more than one key with the Shift key value (normally distinguished	by the location values DOM_KEY_LOCATION_LEFT and DOM_KEY_LOCATION_RIGHT) or 8 key value (normally	distinguished by the location values DOM_KEY_LOCATION_STANDARD and DOM_KEY_LOCATION_NUMPAD), and user-configured custom
+	keyboard layouts MAY duplicate any key value in multiple key-state scenarios
+	(note that location is intended for standard keyboard
+	layouts, and cannot always indicate a meaningful distinction).

+    
Finally, the meaning of any given character representation is
+	context-dependent and complex.  For example, in some contexts, the asterisk
+	(star) glyph ("*") represents a footnote or	emphasis (when bracketing a passage of text). However, in some documents or
+	executable programs it is equivalent to the mathematical multiplication
+	operation, while in other documents or executable programs, that function is
+	reserved for the multiplication symbol ("×", Unicode value U+00D7) or the Latin small letter x (due to the lack of a multiplication key on many keyboards and the
+	superficial resemblance of the glyphs "×" and "x").  Thus,	the semantic meaning or function of character representations is outside the
+	scope of this specification.

+    
5.3.1. Modifier keys

+    
Keyboard input uses modifier keys to change the normal behavior of a
+		key. Like other keys, modifier keys generate keydown and keyup events, as shown in the example below. Some modifiers are		activated while the key is being pressed down or maintained pressed such
+		as Alt, Control, Shift, AltGraph, or Meta. Other modifiers are activated depending on their state		such as CapsLock, NumLock, or ScrollLock. Change		in the state happens when the modifier key is being pressed down. The KeyboardEvent interface provides convenient attributes for some
+		common modifiers keys: ctrlKey, shiftKey, altKey, metaKey. Some operating systems simulate the AltGraph modifier key with the combination of the Alt and Control modifier keys. Implementations are encouraged to use		the AltGraph modifier key.

+    

+      This example describes a possible sequence of events
+			associated with the generation of the Unicode character Q (Latin
+			Capital Letter Q, Unicode code point U+0051) on a US			keyboard using a US mapping: 
+     
+      
+       
+        
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		Modifiers
+        Notes
+       
1
+        keydown
+        "Shift"
+        shiftKey
+        
+       
2
+        keydown
+        "Q"
+        shiftKey
+        Latin Capital Letter Q
+       
3
+        beforeinput
+        
+        
+        
+       
4
+        input
+        
+        
+        
+       
5
+        keyup
+        "Q"
+        shiftKey
+        
+       
6
+        keyup
+        "Shift"
+        
+        
+     

+    

+    

+      Th example describes an alternate sequence of keys to the
+			example above, where the Shift key is released before the Q key.  The key value for the Q key will revert to its			unshifted value for the keyup event: 
+     
+      
+       
+        
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		Modifiers
+        Notes
+       
1
+        keydown
+        "Shift"
+        shiftKey
+        
+       
2
+        keydown
+        "Q"
+        shiftKey
+        Latin Capital Letter Q
+       
3
+        beforeinput
+        
+        
+        
+       
4
+        input
+        
+        
+        
+       
5
+        keyup
+        "Shift"
+        
+        
+       
6
+        keyup
+        "q"
+        
+        Latin Small Letter Q
+     

+    

+    

+      The following example describes a possible sequence of keys that
+			does not generate a Unicode character (using the same configuration
+			as the previous example): 
+     
+      
+       
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		Modifiers
+        Notes
+       
1
+        keydown
+        "Control"
+        ctrlKey
+        
+       
2
+        keydown
+        "v"
+        ctrlKey
+        Latin Small Letter V
+       

+        
+        
+        
+        No beforeinput or input events are generated.
+       
3
+        keyup
+        "v"
+        ctrlKey
+        Latin Small Letter V
+       
4
+        keyup
+        "Control"
+        
+        
+     

+    

+    

+      The following example shows the sequence of events when both Shift and Control are pressed: 
+     
+      
+       
+        
+        
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		Modifiers
+        Notes
+       
1
+        keydown
+        "Control"
+        ctrlKey
+        
+       
2
+        keydown
+        "Shift"
+        ctrlKey, shiftKey
+        
+       
3
+        keydown
+        "V"
+        ctrlKey, shiftKey
+        Latin Capital Letter V
+       

+        
+        
+        
+        No beforeinput or input events are generated.
+       
4
+        keyup
+        "V"
+        ctrlKey, shiftKey
+        Latin Capital Letter V
+       
5
+        keyup
+        "Shift"
+        ctrlKey
+        
+       
6
+        keyup
+        "Control"
+        
+        
+     

+    

+    

+      For non-US keyboard layouts, the sequence of events is the same, but
+			the value of the key is based on the current keyboard layout. This
+			example shows a sequence of events when an Arabic keyboard layout is
+			used: 
+     
+      
+       
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		Modifiers
+        Notes
+       
1
+        keydown
+        "Control"
+        ctrlKey
+        
+       
2
+        keydown
+        "ر"
+        ctrlKey
+        Arabic Letter Reh
+       

+        
+        
+        
+        No beforeinput or input events are generated.
+       
3
+        keyup
+        "ر"
+        ctrlKey
+        Arabic Letter Reh
+       
4
+        keyup
+        "Control"
+        
+        
+     

+    

+    
 The value in the keydown and keyup events varies based on		the current keyboard layout in effect when the key is pressed. This
+		means that the v key on a US layout and the ر key on an		Arabic layout will generate different events even though they are the
+		same physical key. To identify these events as coming from the same
+		physical key, you will need to make use of the code attribute. 

+    
In some cases, modifier keys change the key value for a key event. For example, on some MacOS keyboards, the  key
+		labeled "delete" functions the same as the Backspace key on the		Windows OS when unmodified, but when modified by the Fn key,		acts as the Delete key, and the value of key will match the most appropriate function of the key in its current
+		modified state.

+    
5.3.2. Dead keys

+    
Some keyboard input uses dead keys for the input of composed
+		character sequences. Unlike the handwriting sequence, in which users
+		enter the base character first, keyboard input requires to enter a
+		special state when a dead key is pressed and emit the
+		character(s) only when one of a limited number of legal base
+		character is entered.

+    
 The MacOS and Linux operating systems use input methods to process dead keys. 

+    
The dead keys (across all keyboard layouts and mappings) are
+		represented by the key value Dead. In response to any dead key		press,  composition events must
+		be dispatched by the user agent and the compositionupdate event’s data value must be the character value of the
+		current state of the dead key combining sequence.

+    
While Unicode combining characters always follow the handwriting
+		sequence, with the combining character trailing the corresponding
+		letter, typical dead key input MAY reverse the sequence, with the
+		combining character before the corresponding letter. For example, the
+		word naïve, using the combining diacritic ¨, would be
+		represented sequentially in Unicode as nai¨ve, but MAY be typed na¨ive. The sequence of keystrokes U+0302 (Combining		Circumflex Accent key) and U+0065 (key marked with the Latin Small		Letter E) will likely produce (on a French keyboard using a french
+		mapping and without any modifier activated) the Unicode character "ê" (Latin Small Letter E With Circumflex), as preferred by		the Unicode Normalization Form NFC.

+    

+      
+     
+      
+       
+        
+        
+        
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		KeyboardEvent
 isComposing
+        		CompositionEvent
 data
+        		Notes
+       
1
+        keydown
+        "Dead"
+        false
+        
+        Combining Circumflex Accent (Dead Key)
+       
2
+        compositionstart
+        
+        
+        ""
+        
+       
3
+        compositionupdate
+        
+        
+        U+0302
+        
+       
4
+        keyup
+        "Dead"
+        true
+        
+        
+       
5
+        keydown
+        "ê"
+        true
+        
+        
+       
6
+        compositionupdate
+        
+        
+        "ê"
+        
+       
7
+        compositionend
+        
+        
+        "ê"
+        
+       
8
+        keyup
+        "e"
+        false
+        
+        Latin Small Letter E
+     

+    

+    
 In the second keydown event (step 5), the key value (assuming the		event is not suppressed) will not be "e" (Latin Small		Letter E key) under normal circumstances because the value delivered to
+		the user agent will already be modified by the dead key operation. 

+    
This process might be aborted when a user types an unsupported base
+		character (that is, a base character for which the active
+		diacritical mark is not available) after pressing a dead key:

+    

+      
+     
+      
+       
+        
+        
+        
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		KeyboardEvent
 isComposing
+        		CompositionEvent
 data
+        		Notes
+       
1
+        keydown
+        "Dead"
+        false
+        
+        Combining Circumflex Accent (Dead Key)
+       
2
+        compositionstart
+        
+        
+        ""
+        
+       
3
+        compositionupdate
+        
+        
+        U+0302
+        
+       
4
+        keyup
+        "Dead"
+        true
+        
+        
+       
5
+        keydown
+        "q"
+        true
+        
+        Latin Small Letter Q
+       
6
+        compositionupdate
+        
+        
+        ""
+        
+       
7
+        compositionend
+        
+        
+        ""
+        
+       
8
+        keyup
+        "q"
+        false
+        
+        
+     

+    

+    
5.3.3. Input Method Editors

+    
This specification includes a model for input method editors (IMEs), through the CompositionEvent interface and events.
+		However, Composition Events and Keyboard Events do not necessarily map
+		as a one-to-one relationship.  As an example, receiving a keydown for the Accept key value does not necessarily imply that the		text currently selected in the IME is being accepted, but
+		indicates only that a keystroke happened, disconnected from the IME Accept functionality (which would normally result in a compositionend event in most IME systems).  Keyboard		events cannot be used to determine the current state of the input method
+		editor, which can be obtained through the data attribute of the CompositionEvent interface.  Additionally, IME systems and devices vary in their functionality, and in which
+		keys are used for activating that functionality, such that the Convert and Accept keys MAY be represented by other		available keys. Keyboard events correspond to the events generated by
+		the input device after the keyboard layout mapping.

+    
 In some implementations or system configurations, some key events, or
+		their values, might be suppressed by the IME in use. 

+    
The following example describes a possible sequence of keys to generate
+		the Unicode character "市" (Kanji character, part of CJK		Unified Ideographs) using Japanese input methods. This example assumes
+		that the input method editor is activated and in the Japanese-Romaji
+		input mode. The keys Convert and Accept MAY be replaced		by others depending on the input device in use and the configuration of
+		the IME, e.g., it can be respectively U+0020 (Space key) and Enter.

+    
 "詩" (poem) and "市" (city) are		homophones, both pronounced し (shi/si), so the user
+		needs to use the Convert key to select the proper option. 

+    

+      
+     
+      
+       
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		KeyboardEvent
 isComposing
+        		CompositionEvent
 data
+        		Notes
+       
1
+        keydown
+        "s"
+        false
+        
+        Latin Small Letter S
+       
2
+        compositionstart
+        
+        
+        ""
+        
+       
3
+        beforeinput
+        
+        
+        
+        
+       
4
+        compositionupdate
+        
+        
+        "s"
+        
+       

+        
+        
+        
+        
+        DOM is updated
+       
5
+        input
+        
+        
+        
+        
+       
6
+        keyup
+        "s"
+        true
+        
+        
+       
7
+        keydown
+        "i"
+        true
+        
+        Latin Small Letter I
+       
8
+        beforeinput
+        
+        
+        
+        
+       
9
+        compositionupdate
+        
+        
+        "し"
+        shi
+       

+        
+        
+        
+        
+        DOM is updated
+       
10
+        input
+        
+        
+        
+        
+       
11
+        keyup
+        "i"
+        true
+        
+        
+       
12
+        keydown
+        "Convert"
+        true
+        
+        Convert
+       
13
+        beforeinput
+        
+        
+        
+        
+       
14
+        compositionupdate
+        
+        
+        "詩"
+        "poem"
+       

+        
+        
+        
+        
+        DOM is updated
+       
15
+        input
+        
+        
+        
+        
+       
16
+        keyup
+        "Convert"
+        true
+        
+        
+       
17
+        keydown
+        "Convert"
+        true
+        
+        Convert
+       
18
+        beforeinput
+        
+        
+        
+        
+       
19
+        compositionupdate
+        
+        
+        "市"
+        "city"
+       

+        
+        
+        
+        
+        DOM is updated
+       
20
+        input
+        
+        
+        
+        
+       
21
+        keyup
+        "Convert"
+        true
+        
+        
+       
22
+        keydown
+        "Accept"
+        true
+        
+        Accept
+       
23
+        compositionend
+        
+        
+        "市"
+        
+       
24
+        keyup
+        "Accept"
+        false
+        
+        
+     

+    

+    
IME composition can also be canceled as in the following example, with
+		conditions identical to the previous example. The key Cancel might also be replaced by others depending on the input device in use
+		and the configuration of the IME, e.g., it could be U+001B (Escape		key).

+    

+      
+     
+      
+       
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		KeyboardEvent
 isComposing
+        		CompositionEvent
 data
+        		Notes
+       
1
+        keydown
+        "s"
+        false
+        
+        Latin Small Letter S
+       
2
+        compositionstart
+        
+        
+        ""
+        
+       
3
+        compositionupdate
+        
+        
+        "s"
+        
+       
4
+        keyup
+        "s"
+        true
+        
+        
+       
5
+        keydown
+        "i"
+        true
+        
+        Latin Small Letter I
+       
6
+        compositionupdate
+        
+        
+        "し"
+        shi
+       
7
+        keyup
+        "i"
+        true
+        
+        
+       
8
+        keydown
+        "Convert"
+        true
+        
+        Convert
+       
9
+        compositionupdate
+        
+        
+        "詩"
+        "poem"
+       
10
+        keyup
+        "Convert"
+        true
+        
+        
+       
11
+        keydown
+        "Convert"
+        true
+        
+        Convert
+       
12
+        compositionupdate
+        
+        
+        "市"
+        "city"
+       
13
+        keyup
+        "Convert"
+        true
+        
+        
+       
14
+        keydown
+        "Cancel"
+        true
+        
+        Cancel
+       
15
+        compositionupdate
+        
+        
+        ""
+        
+       
16
+        compositionend
+        
+        
+        ""
+        
+       
17
+        keyup
+        "Cancel"
+        false
+        
+        
+     

+    

+    
 Some input method editors (such as on the MacOS operating system)
+		might set an empty string to the composition data attribute
+		before canceling a composition. 

+    
5.3.3.1. Input Method Editor mode keys

+    
Some keys on certain devices are intended to activate input
+			method editor functionality, or to change the mode of an active input method editor.  Custom keys for this purpose can be
+			defined for different devices or language modes. The keys defined in
+			this specification for this purpose are: "Alphanumeric", "CodeInput", "FinalMode", "HangulMode", "HanjaMode", "Hiragana", "JunjaMode", "KanaMode", "KanjiMode", "Katakana", and "RomanCharacters".  When one of these keys is			pressed, and no IME is currently active, the appropriate IME is expected to be activated in the mode indicated by the
+			key (if available). If an IME is already active when the key
+			is pressed, the active IME might change to the indicated
+			mode, or a different IME might be launched, or the might MAY
+			be ignored, on a device- and application-specific basis.

+    
This specification also defines other keys which are intended for
+			operation specifically with input method editors: "Accept", "AllCandidates", "Cancel", "Convert", "Compose", "FullWidth", "HalfWidth", "NextCandidate", "Nonconvert", and "PreviousCandidate".  The functions of these			keys are not defined in this specification — refer to other
+			resources for details on input method editor functionality.

+    
 Keys with input method editor functions are not restricted to
+			that purpose, and can have other device- or implementation-specific
+			purposes. 

+    
5.3.4. Default actions and cancelable keyboard events

+    
Canceling the default action of a keydown event MUST NOT		affect its respective keyup event, but it MUST prevent the		respective beforeinput and input (and keypress if		supported) events from being generated. The following example describes
+		a possible sequence of keys to generate the Unicode character Q (Latin
+		Capital Letter Q) on a US keyboard using a US mapping:

+    

+      
+     
+      
+       
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		InputEvent
 data
+        		Modifiers
+        Notes
+       
1
+        keydown
+        "Shift"
+        
+        shiftKey
+        
+       
2
+        keydown
+        "Q"
+        
+        shiftKey
+        The default action is prevented, e.g., by invoking preventDefault().
+       

+        
+        
+        
+        
+        No beforeinput or input (or keypress, if supported) events are generated
+       
3
+        keyup
+        "Q"
+        
+        shiftKey
+        
+       
4
+        keyup
+        "Shift"
+        
+        
+        
+     

+    

+    
If the key is a modifier key, the keystroke MUST still be taken into
+		account for the modifiers states. The following example describes a
+		possible sequence of keys to generate the Unicode character Q (Latin
+		Capital Letter Q) on a US keyboard using a US mapping:

+    

+      
+     
+      
+       
+        
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		InputEvent
 data
+        		Modifiers
+        Notes
+       
1
+        keydown
+        "Shift"
+        
+        shiftKey
+        The default action is prevented, e.g., by invoking preventDefault().
+       
2
+        keydown
+        "Q"
+        
+        shiftKey
+        
+       
3
+        beforeinput
+        
+        "Q"
+        
+        
+       
4
+        input
+        
+        
+        
+        
+       
5
+        keyup
+        "Q"
+        
+        shiftKey
+        
+       
6
+        keyup
+        "Shift"
+        
+        
+        
+     

+    

+    
If the key is part of a sequence of several keystrokes, whether it is a dead key or it is contributing to an Input Method Editor
+		sequence, the keystroke MUST be ignored (not taken into account) only if
+		the default action is canceled on the keydown event.		Canceling a dead key on a keyup event has no effect on beforeinput or input events. The following example uses		the dead key "Dead" (U+0302 Combining Circumflex Accent key) and "e" (U+0065, Latin Small Letter E key) on a French		keyboard using a French mapping and without any modifier activated:

+    

+      
+     
+      
+       
+        
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		InputEvent
 data
+        		Notes
+       
1
+        keydown
+        "Dead"
+        
+        The default action is prevented, e.g., by invoking preventDefault().
+       
2
+        keyup
+        "Dead"
+        
+        
+       
3
+        keydown
+        "e"
+        
+        
+       
4
+        beforeinput
+        
+        "e"
+        
+       
5
+        input
+        
+        
+        
+       
6
+        keyup
+        "e"
+        
+        
+     

+    

+   

+   

+    
6. Legacy Event Initializers

+    
This section is normative.
+The following features are obsolete and should only be implemented by user agents that require compatibility with legacy software.

+    
Early versions of this specification included an initialization method on
+the interface (for example initMouseEvent) that required a long
+list of parameters that, in most cases, did not fully initialize all
+attributes of the event object. Because of this, event interfaces which were
+derived from the basic Event interface required that the initializer of each of the derived interfaces be called explicitly in order to
+fully initialize an event.

+    
 Initializing all the attributes of a MutationEvent requires calls to two
+initializer methods: initEvent and initMutationEvent. 

+    
Due in part to the length of time in the development of this standard, some
+implementations MAY have taken a dependency on these (now deprecated)
+initializer methods. For completeness, these legacy event initializers are
+described in this Appendix.

+    
6.1. Legacy Event Initializer Interfaces

+    
This section is informative

+    
This section documents legacy initializer methods that were introduced
+	in earlier versions of this specification.

+    
6.1.1. Initializers for interface UIEvent

+
partial interface UIEvent {
+  // Deprecated in this specification
+  void initUIEvent();
+};
+

+    

+     
initUIEvent()
+     

+       Initializes attributes of an UIEvent object.
+				This method has the same behavior as initEvent(). 
+      
 The initUIEvent method is deprecated, but
+				supported for backwards-compatibility with widely-deployed
+				implementations. 

+      

+       
DOMString typeArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
boolean bubblesArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
boolean cancelableArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
Window? viewArg
+       
 Specifies view. This value MAY be null. 
+       
long detailArg
+       
 Specifies detail. 
+      

+    

+    
6.1.2. Initializers for interface MouseEvent

+
partial interface MouseEvent {
+  // Deprecated in this specification
+  void initMouseEvent();
+};
+

+    

+     
initMouseEvent()
+     

+       Initializes attributes of a MouseEvent object. This
+				method has the same behavior as UIEvent.initUIEvent(). 
+      
 The initMouseEvent method is deprecated, but
+				supported for backwards-compatibility with widely-deployed
+				implementations. 

+      

+       
DOMString typeArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
boolean bubblesArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
boolean cancelableArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
Window? viewArg
+       
 Specifies view. This value MAY be null. 
+       
long detailArg
+       
 Specifies detail. 
+       
long screenXArg
+       
 Specifies screenX. 
+       
long screenYArg
+       
 Specifies screenY. 
+       
long clientXArg
+       
 Specifies clientX. 
+       
long clientYArg
+       
 Specifies clientY. 
+       
boolean ctrlKeyArg
+       
 Specifies ctrlKey. 
+       
boolean altKeyArg
+       
 Specifies altKey. 
+       
boolean shiftKeyArg
+       
 Specifies shiftKey. 
+       
boolean metaKeyArg
+       
 Specifies metaKey. 
+       
short buttonArg
+       
 Specifies button. 
+       
EventTarget? relatedTargetArg
+       
 Specifies relatedTarget. This value MAY
+						be null. 
+      

+    

+    
6.1.3. Initializers for interface WheelEvent

+
partial interface WheelEvent {
+  // Originally introduced (and deprecated) in this specification
+  void initWheelEvent();
+};
+

+    

+     
initWheelEvent()
+     

+       Initializes attributes of a WheelEvent object. This
+				method has the same behavior as MouseEvent.initMouseEvent(). 
+      
 The initWheelEvent method is deprecated. 

+      

+       
DOMString typeArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
boolean bubblesArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
boolean cancelableArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
Window? viewArg
+       
 Specifies view. This value MAY be null. 
+       
long detailArg
+       
 Specifies detail. 
+       
long screenXArg
+       
 Specifies screenX. 
+       
long screenYArg
+       
 Specifies screenY. 
+       
long clientXArg
+       
 Specifies clientX. 
+       
long clientYArg
+       
 Specifies clientY. 
+       
short buttonArg
+       
 Specifies button. 
+       
EventTarget? relatedTargetArg
+       
 Specifies relatedTarget. This value MAY
+						be null. 
+       
DOMString modifiersListArg
+       
 A  white space separated list of modifier key
+						values to be activated on this object. As an example, "Control Shift" marks the control and shift
+						modifiers as activated (the ctrlKey and shiftKey inherited attributes will be true on the initialized WheelEvent object). 
+       
double deltaXArg
+       
 Specifies deltaX. 
+       
double deltaYArg
+       
 Specifies deltaY. 
+       
double deltaZArg
+       
 Specifies deltaZ. 
+       
unsigned long deltaMode
+       
 Specifies deltaMode. 
+      

+    

+    
6.1.4. Initializers for interface KeyboardEvent

+    
 The argument list to this legacy KeyboardEvent initializer does not
+		include the detailArg (present in other initializers) and
+		adds the locale argument (see §11.2 Changes between different drafts of UI Events); it is
+		necessary to preserve this inconsistency for compatibility with existing
+		implementations. 

+
partial interface KeyboardEvent {
+  // Originally introduced (and deprecated) in this specification
+  void initKeyboardEvent();
+};
+

+    

+     
initKeyboardEvent()
+     

+       Initializes attributes of a KeyboardEvent object. This
+				method has the same behavior as UIEvent.initUIEvent().
+				The value of detail remains undefined. 
+      
 The initKeyboardEvent method is deprecated. 

+      

+       
DOMString typeArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
boolean bubblesArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
boolean cancelableArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
Window? viewArg
+       
 Specifies view. This value MAY be null. 
+       
DOMString keyArg
+       
 Specifies key. 
+       
unsigned long locationArg
+       
 Specifies location. 
+       
DOMString modifiersListArg
+       
 A white space separated list of modifier
+						key values to be activated on this object. As an
+						example, "Control Alt" marks the Control and Alt modifiers as activated. 
+       
boolean repeat
+       
 Specifies whether the key event is repeating. See repeat. 
+       
DOMString locale
+       
 Specifies the locale attribute of the KeyboardEvent. 
+      

+    

+    
6.1.5. Initializers for interface CompositionEvent

+    
 The argument list to this legacy CompositionEvent initializer does not
+		include the detailArg (present in other initializers) and
+		adds the locale argument (see §11.2 Changes between different drafts of UI Events); it is
+		necessary to preserve this inconsistency for compatibility with existing
+		implementations. 

+
partial interface CompositionEvent {
+  // Originally introduced (and deprecated) in this specification
+  void initCompositionEvent();
+};
+

+    

+     
initCompositionEvent()
+     

+       Initializes attributes of a CompositionEvent object. This method has the same behavior as UIEvent.initUIEvent(). The value of detail remains undefined. 
+      
 The initCompositionEvent method is deprecated. 

+      

+       
DOMString typeArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
boolean bubblesArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
boolean cancelableArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
Window? viewArg
+       
 Specifies view. This value MAY be null. 
+       
DOMString dataArg
+       
 Specifies data. 
+       
DOMString locale
+       
 Specifies the locale attribute of the CompositionEvent. 
+      

+    

+   

+   

+    
7. Legacy Key & Mouse Event Attributes

+    
This section is non-normative. The following attributes are obsolete and should
+only be implemented by user agents that require compatibility with legacy
+software that requires these keyboard events.

+    
These features were never formally specified and the current browser
+implementations vary in significant ways. The large amount of legacy content,
+including script libraries, that relies upon detecting the user agent and
+acting accordingly means that any attempt to formalize these legacy attributes
+and events would risk breaking as much content as it would fix or enable.
+Additionally, these attributes are not suitable for international usage, nor do
+they address accessibility concerns.

+    
Therefore, this specification does not normatively define the events and
+attributes commonly employed for handling keyboard input, though they MAY be
+present in user agents for compatibility with legacy content. Authors
+SHOULD use the key attribute instead of the charCode and keyCode attributes.

+    
However, for the purpose of documenting the current state of these features and
+their relation to normative events and attributes, this section provides an
+informative description. For implementations which do support these attributes
+and events, it is suggested that the definitions provided in this section be
+used.

+    
7.1. Legacy UIEvent supplemental interface

+    
This section is non-normative

+    
User agents have traditionally included a which attribute so that KeyboardEvents and MouseEvents could record supplemental event info.

+    
 Previous versions of this specification defined separate which attributes
+	directly on KeyboardEvent and MouseEvent rather than having a shared which attribute defined on UIEvent. 

+    
7.1.1. Interface UIEvent (supplemental)

+    
The partial UIEvent interface is an informative extension of the UIEvent interface, which adds the which attribute.

+
partial interface UIEvent {
+  // The following support legacy user agents
+  readonly attribute unsigned long which;
+};
+

+    

+     
which,  of type unsigned long, readonly
+     
 For MouseEvents, this contains a value equal to the value stored in button+1.
+				For KeyboardEvents, this holds a system- and implementation-dependent
+				numerical code signifying the unmodified identifier associated
+				with the key pressed. In most cases, the value is identical to keyCode. 
+    

+    
7.1.2. Interface UIEventInit (supplemental)

+    
Browsers that include support for which in UIEvent should also add the following members to the UIEventInit dictionary.

+    
The partial UIEventInit dictionary is an informative extension
+		of the UIEventInit dictionary, which adds the which member to initialize the corresponding UIEvent attributes.

+
partial dictionary UIEventInit {
+  unsigned long which = 0;
+};
+

+    

+     
which
+     
 Initializes the which attribute of the UIEvent. 
+    

+    
7.2. Legacy KeyboardEvent supplemental interface

+    
This section is non-normative

+    
Browser support for keyboards has traditionally relied on three ad-hoc
+	attributes, keyCode, charCode, and UIEvent's which.

+    
All three of these attributes return a numerical code that represents some
+	aspect of the key pressed: keyCode is an index of the key
+	itself. charCode is the ASCII value of the character keys. which is the character value where available and otherwise
+	the key index. The values for these attributes, and the availability of the
+	attribute, is inconsistent across platforms, keyboard languages and layouts, user agents, versions, and even event types.

+    
7.2.1. Interface KeyboardEvent (supplemental)

+    
The partial KeyboardEvent interface is an informative extension of
+		the KeyboardEvent interface, which adds the charCode and keyCode attributes.

+    
The partial KeyboardEvent interface can be obtained by using the createEvent() method call in
+		implementations that support this extension.

+
partial interface KeyboardEvent {
+  // The following support legacy user agents
+  readonly attribute unsigned long charCode;
+  readonly attribute unsigned long keyCode;
+};
+

+    

+     
charCode,  of type unsigned long, readonly
+     
 charCode holds a character value, for keypress events which generate character input. The value				is the Unicode reference number (code point) of that character
+				(e.g. event.charCode = event.key.charCodeAt(0) for
+				printable characters). For keydown or keyup events, the value of charCode is 0. 
+     
keyCode,  of type unsigned long, readonly
+     
 keyCode holds a system- and
+				implementation-dependent numerical code signifying the
+				unmodified identifier associated with the key pressed. Unlike
+				the key attribute, the set of possible values
+				are not normatively defined in this specification. Typically,
+				these value of the keyCode SHOULD represent
+				the decimal codepoint in ASCII [RFC20][US-ASCII] or Windows
+				1252 [WIN1252], but MAY be drawn from a different appropriate
+				character set. Implementations that are unable to identify a key
+				use the key value 0.
+				See §7.3 Legacy key models for more details on how to determine
+				the values for keyCode. 
+    

+    
7.2.2. Interface KeyboardEventInit (supplemental)

+    
Browsers that include support for keyCode, charCode, and which in KeyboardEvent should also add the following members to the KeyboardEventInit dictionary.

+    
The partial KeyboardEventInit dictionary is an informative extension
+		of the KeyboardEventInit dictionary, which adds charCode, keyCode, and which members to initialize the corresponding KeyboardEvent attributes.

+
partial dictionary KeyboardEventInit {
+  // The following support legacy user agents
+  unsigned long charCode = 0;
+  unsigned long keyCode = 0;
+};
+

+    

+     
charCode
+     
 Initializes the charCode attribute of the KeyboardEvent to the Unicode code point for the event’s
+				character. 
+     
keyCode
+     
 Initializes the keyCode attribute of the KeyboardEvent to the system- and implementation-dependent
+				numerical code signifying the unmodified identifier associated
+				with the key pressed. 
+    

+    
7.3. Legacy key models

+    
This section is non-normative

+    
Implementations differ on which values are exposed on these attributes for
+	different event types. An implementation MAY choose to expose both virtual
+	key codes and character codes in the keyCode property
+	(conflated model), or report separate keyCode and charCode properties (split model).

+    
7.3.1. How to determine keyCode for keydown and keyup events

+     The keyCode for keydown or keyup events		is calculated as follows: 
+    
    
+     
  • 
+      
    Read the virtual key code from the operating system’s event
+information, if such information is available.
    
+     
  • 
+      
    If an Input Method Editor is processing key input and the event is keydown, return 229.
    
+     
  • 
+      
    If input key when pressed without modifiers would insert a numerical
+character (0-9), return the ASCII code of that numerical character.
    
+     
  • 
+      
    If input key when pressed without modifiers would insert a lower
+case character in the a-z alphabetical range, return the ASCII code
+of the upper case equivalent.
    
+     
  • 
+      
    If the implementation supports a key code conversion table for the
+operating system and platform, look up the value. If the conversion
+table specifies an alternate virtual key value for the given input,
+return the specified value.
    
+     
  • 
+      
    If the key’s function, as determined in an implementation-specific
+way, corresponds to one of the keys in the §7.3.3 Fixed virtual key codes table, return the corresponding key
+code.
    
+     
  • 
+      
    Return the virtual key code from the operating system.
    
+     
  • 
+      
    If no key code was found, return 0.
    
+    

+    
7.3.2. How to determine keyCode for keypress events

+     The keyCode for keypress events is calculated		as follows: 
+    
    
+     
  • 
+      
    If the implementation supports a conflated model, set keyCode to the Unicode code point of the character
+being entered.
    
+     
  • 
+      
    If the implementation supports a split model, set keyCode to 0.
    
+    

+    
7.3.3. Fixed virtual key codes

+    
The virtual key codes for the following keys do not usually change with
+		keyboard layouts on desktop systems:

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
Key
+       Virtual Key 
Code
+       		Notes
+      
Backspace
+       8
+       
+      
Tab
+       9
+       
+      
Enter
+       13
+       
+      
Shift
+       16
+       
+      
Control
+       17
+       
+      
Alt
+       18
+       
+      
CapsLock
+       20
+       
+      
Escape
+       27
+       Esc
+      
Space
+       32
+       
+      
PageUp
+       33
+       
+      
PageDown
+       34
+       
+      
End
+       35
+       
+      
Home
+       36
+       
+      
ArrowLeft
+       37
+       
+      
ArrowUp
+       38
+       
+      
ArrowRight
+       39
+       
+      
ArrowDown
+       40
+       
+      
Delete
+       46
+       Del
+    

+    
7.3.4. Optionally fixed virtual key codes

+    
The following punctuation characters MAY change virtual codes between
+		keyboard layouts, but reporting these values will likely be more
+		compatible with legacy content expecting US-English keyboard layout:

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
Key
+       Character
+       Virtual Key 
Code
+      
Semicolon
+       ";"
+       186
+      
Colon
+       ":"
+       186
+      
Equals sign
+       "="
+       187
+      
Plus
+       "+"
+       187
+      
Comma
+       ","
+       188
+      
Less than sign
+       "<"
+       188
+      
Minus
+       "-"
+       189
+      
Underscore
+       "_"
+       189
+      
Period
+       "."
+       190
+      
Greater than sign
+       ">"
+       190
+      
Forward slash
+       "/"
+       191
+      
Question mark
+       "?"
+       191
+      
Backtick
+       "`"
+       192
+      
Tilde
+       "~"
+       192
+      
Opening squace bracket
+       "["
+       219
+      
Opening curly brace
+       "{"
+       219
+      
Backslash
+       "\"
+       220
+      
Pipe
+       "|"
+       220
+      
Closing square bracket
+       "]"
+       221
+      
Closing curly brace
+       "}"
+       221
+      
Single quote
+       "'"
+       222
+      
Double quote
+       """
+       222
+    

+   

+   

+    
8. Legacy Event Types

+    
This section is normative. The following event types are obsolete and should
+only be implemented by user agents that require compatibility with legacy
+software.

+    
The purpose of this section is to document the current state of these features
+and their relation to normative events. For implementations which do support
+these events, it is suggested that the definitions provided in this section be
+used.

+    
The following table provides an informative summary of the event types which are
+deprecated in this specification. They are included here for reference and
+completeness.

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
Event Type
+       Sync / Async
+       Bubbling Phase
+       Trusted event target types
+       DOM Interface
+       Cancelable
+       Composed
+       Default Action
+      
DOMActivate
+       Sync
+       Yes
+       Element
+       UIEvent
+       Yes
+       Yes
+       None
+      
DOMAttrModified
+       Sync
+       Yes
+       Element
+       MutationEvent
+       No
+       No
+       None
+      
DOMCharacterDataModified
+       Sync
+       Yes
+       Text, Comment, ProcessingInstruction
+       MutationEvent
+       No
+       No
+       None
+      
DOMFocusIn
+       Sync
+       Yes
+       Window, Element
+       FocusEvent
+       No
+       Yes
+       None
+      
DOMFocusOut
+       Sync
+       Yes
+       Window, Element
+       FocusEvent
+       No
+       Yes
+       None
+      
DOMNodeInserted
+       Sync
+       Yes
+       Element, Attr, Text, Comment, DocumentType, ProcessingInstruction
+       MutationEvent
+       No
+       No
+       None
+      
DOMNodeInsertedIntoDocument
+       Sync
+       No
+       Element, Attr, Text, Comment, DocumentType, ProcessingInstruction
+       MutationEvent
+       No
+       No
+       None
+      
DOMNodeRemoved
+       Sync
+       Yes
+       Element, Attr, Text, Comment, DocumentType, ProcessingInstruction
+       MutationEvent
+       No
+       No
+       None
+      
DOMNodeRemovedFromDocument
+       Sync
+       No
+       Element, Attr, Text, Comment, DocumentType, ProcessingInstruction
+       MutationEvent
+       No
+       No
+       None
+      
DOMSubtreeModified
+       Sync
+       Yes
+       Window, Document, DocumentFragment, Element, Attr
+       MutationEvent
+       No
+       No
+       None
+      
keypress
+       Sync
+       Yes
+       Element
+       KeyboardEvent
+       Yes
+       Yes
+       Varies: launch text composition system; blur and focus events; DOMActivate event; other event
+    

+    
8.1. Legacy UIEvent events

+    
8.1.1. Legacy UIEvent event types

+    
8.1.1.1. DOMActivate

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       DOMActivate
+      
Interface
+       UIEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
(trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a button, link, or
+			other state-changing element is activated.  Refer to §3.5 Activation triggers and behavior for more details.

+    
 The DOMActivate event type is defined in this			specification for reference and completeness, but this specification deprecates the use of this event type in favor of the related event type click.  Other specifications MAY define and			maintain their own DOMActivate event type for backwards			compatibility. 

+    
 While DOMActivate and click are not completely equivalent,			implemented behavior for the click event type has			developed to encompass the most critical accessibility aspects for which
+			the DOMActivate event type was designed, and is more			widely implemented.  Content authors are encouraged to use the click event type rather than the related mousedown or mouseup event type to ensure maximum accessibility. 

+    
Implementations which support the DOMActivate event type SHOULD also dispatch a DOMActivate event as a default		action of a click event which is associated with an activation trigger. However, such implementations SHOULD only
+		initiate the associated activation behavior once for any given
+		occurrence of an activation trigger.

+    

+      
+     
 The DOMActivate event type is REQUIRED to be supported for		XForms [XFORMS], which is intended for implementation within a host
+		language. In a scenario where a plugin or script-based
+		implementation of XForms is intended for installation in a native
+		implementation of this specification which does not support the DOMActivate event type, the XForms user agent has		to synthesize and dispatch its own DOMActivate events based on		the appropriate activation triggers. 

+     
 Thus, when a click event is dispatched by a user agent conforming to UI Events, the XForms user agent has to determine
+		whether to synthesize a DOMActivate event with the same relevant		properties as a default action of that click event.		Appropriate cues might be whether the click event is trusted, or whether its event target has a DOMActivate event listener registered. 

+    

+    
 Don’t rely upon the interoperable support of DOMActivate in many user agents. Instead, the click event type should		be used since it will provide more accessible behavior due to broader
+		implementation support. 

+    
 The DOMActivate event type is deprecated in this		specification. 

+    
8.1.2. Activation event order

+    
If the DOMActivate event is supported by the user
+		agent, then the events MUST be dispatched in a set order relative to
+		each other: (with only pertinent events listed):

+    
+     
+      
+       
+       
+       
+       

+       Event Type
+       Notes
+      
1
+       click
+       
+      
2
+       DOMActivate
+       default action, if supported by the user agent; synthesized; isTrusted="true"
+      
3
+       
+       All other default actions, including the activation behavior
+    

+    
If the focused element is activated by a key event, then the following
+		shows the typical sequence of events (with only pertinent events listed):

+    
+     
+      
+       
+       
+       
+       
+       

+       Event Type
+       Notes
+      
1
+       keydown
+       MUST be a key which can activate the element, such as the Enter or    (spacebar) key, or the element is not activated
+      
2
+       click
+       default action; synthesized; isTrusted="true"
+      
3
+       DOMActivate
+       default action, if supported by the user agent; synthesized; isTrusted="true"
+      
4
+       
+       All other default actions, including the activation behavior
+    

+    
8.2. Legacy FocusEvent events

+    
8.2.1. Legacy FocusEvent event types

+    
8.2.1.1. DOMFocusIn

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       DOMFocusIn
+      
Interface
+       FocusEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Window, Element
+      
Cancelable
+       No
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
(trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when an event
+			target receives focus. The focus MUST be given to the
+			element before the dispatch of this event type. This event type
+			MUST be dispatched after the event type focus.

+    
 The DOMFocusIn event type is defined in this			specification for reference and completeness, but this
+			specification deprecates the use of this event type in
+			favor of the related event types focus and focusin. 

+    
8.2.1.2. DOMFocusOut

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       DOMFocusOut
+      
Interface
+       FocusEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Window, Element
+      
Cancelable
+       No
+      
Composed
+       Yes
+      
Default action
+       None
+      
Context
(trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when an event
+			target loses focus. The focus MUST be taken from the element
+			before the dispatch of this event type. This event type MUST be
+			dispatched after the event type blur.

+    
 The DOMFocusOut event type is defined in this			specification for reference and completeness, but this
+			specification deprecates the use of this event type in
+			favor of the related event types blur and focusout. 

+    
8.2.2. Legacy FocusEvent event order

+    
The following is the typical sequence of events when a focus is shifted
+		between elements, including the deprecated DOMFocusIn and DOMFocusOut events. The order shown assumes that no element is		initially focused.

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       
+       

+       Event Type
+       Notes
+      

+       
+       User shifts focus
+      
1
+       focusin
+       Sent before first target element receives focus
+      
2
+       focus
+       Sent after first target element receives focus
+      
3
+       DOMFocusIn
+       If supported
+      

+       
+       User shifts focus
+      
4
+       focusout
+       Sent before first target element loses focus
+      
5
+       focusin
+       Sent before second target element receives focus
+      
6
+       blur
+       Sent after first target element loses focus
+      
7
+       DOMFocusOut
+       If supported
+      
8
+       focus
+       Sent after second target element receives focus
+      
9
+       DOMFocusIn
+       If supported
+    

+    
8.3. Legacy KeyboardEvent events

+    
The keypress event is the traditional method for capturing key events	and processing them before the DOM is updated with the effects of the key
+	press. Code that makes use of the keypress event typically relies on	the legacy charCode, keyCode, and which attributes.

+    
Note that the keypress event is specific to key events, and has been	replaced by the more general event sequence of beforeinput and input events. These new input events are not specific to	keyboard actions and can be used to capture user input regardless of the
+	original source.

+    
8.3.1. Legacy KeyboardEvent event types

+    
8.3.1.1. keypress

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       keypress
+      
Interface
+       KeyboardEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       Yes
+      
Composed
+       Yes
+      
Default action
+       Varies:
+						launch text composition system; blur and focus events; DOMActivate event;						other event
+      
Context
(trusted events)
+       		
+        
+    

+    
If supported by a user agent, this event MUST be dispatched
+			when a key is pressed down, if and only if that key normally
+			produces a character value. The keypress event type is			device dependent and relies on the capabilities of the input devices
+			and how they are mapped in the operating system.

+    
This event type MUST be generated after the key mapping. It
+			MUST NOT be fired when using an input method editor.

+    
If this event is canceled, it should prevent the input event			from firing, in addition to canceling the default action.

+    
Authors SHOULD use the beforeinput event instead of the keypress event.

+    
 The keypress event is traditionally associated with detecting			a character value rather than a physical key, and might not
+			be available on all keys in some configurations. 

+    
 The keypress event type is defined in this specification for			reference and completeness, but this specification deprecates the use of this event type. When in editing contexts, authors can
+			subscribe to the beforeinput event instead. 

+    
8.3.2. keypress event order

+     The keypress event type MUST be dispatched after the keydown event and before the keyup event associated with		the same key. 
+    
The keypress event type MUST be dispatched after the beforeinput event and before the input event associated		with the same key.

+    
The sequence of key events for user-agents the support the keypress event is demonstrated in the following example:

+    

+      
+     
+      
+       
+        
+        
+        
+        
+        
+        
+        

+        Event Type
+        KeyboardEvent
 key
+        		InputEvent
 data
+        		Notes
+       
1
+        keydown
+        "a"
+        
+        
+       
2
+        beforeinput
+        
+        "a"
+        
+       
3
+        keypress
+        "a"
+        
+        
+       

+        
+        
+        
+        Any default actions related to this key, such as inserting a character in to the DOM.
+       
4
+        input
+        
+        
+        
+       
5
+        keyup
+        "a"
+        
+        
+     

+    

+    
8.4. Legacy MutationEvent events

+    
The mutation and mutation name event modules are designed to allow
+	notification of any changes to the structure of a document, including
+	attribute, text, or name modifications.

+    
 None of the event types associated with the MutationEvent interface are
+	designated as cancelable. This stems from the fact that it is very difficult
+	to make use of existing DOM interfaces which cause document modifications if
+	any change to the document might or might not take place due to cancelation
+	of the resulting event. Although this is still a desired capability, it was
+	decided that it would be better left until the addition of transactions into
+	the DOM. 

+    
Many single modifications of the tree can cause multiple mutation events to
+	be dispatched. Rather than attempt to specify the ordering of mutation
+	events due to every possible modification of the tree, the ordering of these
+	events is left to the implementation.

+    

+     
 The MutationEvent interface was introduced in DOM Level 2 Events, but
+	has not yet been completely and interoperably implemented across user
+	agents. In addition, there have been critiques that the interface, as
+	designed, introduces a performance and implementation challenge. 

+     
 DOM4 [DOM] provides a new mechanism using a MutationObserver interface which addresses the use cases that
+	mutation events solve, but in a more performant manner. Thus, this
+	specification describes mutation events for reference and completeness of
+	legacy behavior, but deprecates the use of the MutationEvent interface. 

+    

+    
8.4.1. Interface MutationEvent

+    
Introduced in DOM Level 2, deprecated in this
+		specification

+    
The MutationEvent interface provides specific contextual
+		information associated with Mutation events.

+    
To create an instance of the MutationEvent interface, use
+		the createEvent() method call.

+
interface MutationEvent : Event {
+  // attrChangeType
+  const unsigned short MODIFICATION = 1;
+  const unsigned short ADDITION = 2;
+  const unsigned short REMOVAL = 3;
+
+  readonly attribute Node? relatedNode;
+  readonly attribute DOMString prevValue;
+  readonly attribute DOMString newValue;
+  readonly attribute DOMString attrName;
+  readonly attribute unsigned short attrChange;
+
+  void initMutationEvent();
+};
+

+    

+     
MODIFICATION
+     
 The Attr was modified in place. 
+     
ADDITION
+     
 The Attr was just added. 
+     
REMOVAL
+     
 The Attr was just removed. 
+     
relatedNode
+     

+       relatedNode MUST be used to identify a secondary
+				node related to a mutation event. For example, if a mutation
+				event is dispatched to a node indicating that its parent has
+				changed, the relatedNode will be the changed
+				parent. If an event is instead dispatched to a subtree
+				indicating a node was changed within it, the relatedNode MUST be the changed node. In the case
+				of the DOMAttrModified event, it indicates the Attr node which was modified, added, or removed. 
+      
The un-initialized value of this attribute MUST be null.

+     
prevValue
+     
 prevValue indicates the previous value of the Attr node in DOMAttrModified events, and of				the CharacterData node in DOMCharacterDataModified events.
+				The un-initialized value of this attribute MUST be "" (the empty string). 
+     
newValue
+     
 newValue indicates the new value of the Attr node in DOMAttrModified events, and of				the CharacterData node in DOMCharacterDataModified events.
+				The un-initialized value of this attribute MUST be "" (the empty string). 
+     
attrName
+     
 attrName indicates the name of the changed Attr node in a DOMAttrModified event.
+				The un-initialized value of this attribute MUST be "" (the empty string). 
+     
attrChange
+     

+       attrChange indicates the type of change which
+				triggered the DOMAttrModified event. The values can be MODIFICATION, ADDITION, or REMOVAL. 
+      
The un-initialized value of this attribute MUST be 0.

+      
 There is no defined constant for the attrChange value of 0 (the
+				un-initialized value). 

+     
initMutationEvent()
+     

+       Initializes attributes of a MutationEvent object.
+				This method has the same behavior as initEvent(). 
+      

+       
DOMString typeArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
boolean bubblesArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
boolean cancelableArg
+       
 Refer to the initEvent() method for a description of this parameter. 
+       
Node? relatedNodeArg
+       
 Specifies MutationEvent.relatedNode. 
+       
DOMString prevValueArg
+       
 Specifies MutationEvent.prevValue. This value MAY be the empty string. 
+       
DOMString newValueArg
+       
 Specifies MutationEvent.newValue.
+						This value MAY be the empty string. 
+       
DOMString attrNameArg
+       
 Specifies MutationEvent.attrName.
+						This value MAY be the empty string. 
+       
unsigned short attrChangeArg
+       
 Specifies MutationEvent.attrChange.
+						This value MAY be 0. 
+      

+    

+    
8.4.2. Legacy MutationEvent event types

+    
The mutation event types are listed below.

+    
8.4.2.1. DOMAttrModified

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       DOMAttrModified
+      
Interface
+       MutationEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element
+      
Cancelable
+       No
+      
Composed
+       No
+      
Default action
+       None
+      
Context
(trusted events)
+       		
+        
    
+         
  • Event.target :
+								element whose attribute is being modified
+         
  • MutationEvent.attrName :
+								the name of the changed Attr node
+         
  • MutationEvent.attrChange :
+								the numerical code corresponding to the most applicable attrChangeType
+         
  • MutationEvent.relatedNode :
+								the Attr node that has been modified, added, or removed.
+         
  • MutationEvent.newValue :
+								new value of the attribute, if the Attr node has been added or modified
+         
  • MutationEvent.prevValue :
+								previous value of the attribute, if the Attr node has been removed or modified
+        

+    

+    
A user agent MUST dispatch this event after an Attr.value has been modified and after an Attr node has been added to or removed from an Element. The event target of this event MUST be
+			the Element node where the change occurred. It is
+			implementation dependent whether this event type occurs when the
+			children of the Attr node are changed in ways that do
+			not affect the value of Attr.value.

+    
 The DOMAttrModified event type is defined in this			specification for reference and completeness, but this specification deprecates the use of this event type. 

+    
8.4.2.2. DOMCharacterDataModified

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       DOMCharacterDataModified
+      
Interface
+       MutationEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Text, Comment, ProcessingInstruction
+      
Cancelable
+       No
+      
Composed
+       No
+      
Default action
+       None
+      
Context
(trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event after CharacterData.data or ProcessingInstruction.data have been modified, but the
+			node itself has not been inserted or deleted. The event
+			target of this event MUST be the CharacterData node
+			or the ProcessingInstruction node.

+    
 The DOMCharacterDataModified event type is defined in this			specification for reference and completeness, but this specification deprecates the use of this event type. 

+    
8.4.2.3. DOMNodeInserted

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       DOMNodeInserted
+      
Interface
+       MutationEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element, Attr, Text, Comment, DocumentType, ProcessingInstruction
+      
Cancelable
+       No
+      
Composed
+       No
+      
Default action
+       None
+      
Context
(trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event type when a node other
+			than an Attr node has been added as a child of another
+			node. A user agent MAY dispatch this event when an Attr node has been added to an Element node (see note below). This
+			event MUST be dispatched after the insertion has taken place. The event target of this event MUST be the node being inserted.

+    
 For detecting attribute insertion, use the DOMAttrModified event type instead. 

+    
 The DOMNodeInserted event type is defined in this			specification for reference and completeness, but this specification deprecates the use of this event type. 

+    
8.4.2.4. DOMNodeInsertedIntoDocument

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       DOMNodeInsertedIntoDocument
+      
Interface
+       MutationEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       No
+      
Trusted Targets
+       Element, Attr, Text, Comment, DocumentType, ProcessingInstruction
+      
Cancelable
+       No
+      
Composed
+       No
+      
Default action
+       None
+      
Context
(trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a node has been
+			inserted into a document, either through direct insertion of the
+			node or insertion of a subtree in which it is contained. A user
+			agent MAY  treat an Attr node as part of an Element’s subtree. This event MUST be dispatched after
+			the insertion has taken place. The event target of this event
+			MUST be the node being inserted. If the node is being directly
+			inserted, the event type DOMNodeInserted MUST occur before			this event type.

+    
 The DOMNodeInsertedIntoDocument event type is defined in this			specification for reference and completeness, but this specification deprecates the use of this event type. 

+    
8.4.2.5. DOMNodeRemoved

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       DOMNodeRemoved
+      
Interface
+       MutationEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Element, Attr, Text, Comment, DocumentType, ProcessingInstruction
+      
Cancelable
+       No
+      
Composed
+       No
+      
Default action
+       None
+      
Context
(trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a node other than
+			an Attr node is being removed from its parent node. A user agent MAY dispatch this event when an Attr node is being removed from its ownerElement (see note below). This event MUST be
+			dispatched before the removal takes place. The event target of this event MUST be the node being removed.

+    
 For reliably detecting attribute removal, use the DOMAttrModified event type instead. 

+    
 The DOMNodeRemoved event type is defined in this			specification for reference and completeness, but this specification deprecates the use of this event type. 

+    
8.4.2.6. DOMNodeRemovedFromDocument

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       DOMNodeRemovedFromDocument
+      
Interface
+       MutationEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       No
+      
Trusted Targets
+       Element, Attr, Text, Comment, DocumentType, ProcessingInstruction
+      
Cancelable
+       No
+      
Composed
+       No
+      
Default action
+       None
+      
Context
(trusted events)
+       		
+        
+    

+    
A user agent MUST dispatch this event when a node is being
+			removed from a document, either through direct removal of the node
+			or removal of a subtree in which it is contained. A user
+			agent MAY treat an Attr node as part of an Element’s subtree. This event MUST be dispatched before
+			the removal takes place. The event target of this event type
+			MUST be the node being removed. If the node is being directly
+			removed, the event type DOMNodeRemoved MUST occur before this			event type.

+    
 For reliably detecting attribute removal, use the DOMAttrModified event type instead. 

+    
 The DOMNodeRemovedFromDocument event type is defined in this			specification for reference and completeness, but this specification deprecates the use of this event type. 

+    
8.4.2.7. DOMSubtreeModified

+    
+     
+      
+       
+       
+       
+       
+       
+       
+       
+       
+       
Type
+       DOMSubtreeModified
+      
Interface
+       MutationEvent
+      
Sync / Async
+       Sync
+      
Bubbles
+       Yes
+      
Trusted Targets
+       Window, Document, DocumentFragment, Element, Attr 
+      
Cancelable
+       No
+      
Composed
+       No
+      
Default action
+       None
+      
Context
(trusted events)
+       		
+        
+    

+    
This is a general event for notification of all changes to the
+			document. It can be used instead of the more specific mutation and
+			mutation name events. It MAY be dispatched after a single
+			modification to the document or, at the implementation’s discretion,
+			after multiple changes have occurred. The latter case SHOULD
+			generally be used to accommodate multiple changes which occur either
+			simultaneously or in rapid succession. The target of this event MUST
+			be the lowest common parent of the changes which have taken place.
+			This event MUST be dispatched after any other events caused by the
+			mutation(s) have occurred.

+    
 The DOMSubtreeModified event type is defined in this			specification for reference and completeness, but this specification deprecates the use of this event type. 

+   

+   

+    
9. Extending Events

+    
This section is non-normative

+    
9.1. Introduction

+    
This specification defines several interfaces and many events, however, this
+	is not an exhaustive set of events for all purposes. To allow content
+	authors and implementers to add desired functionality, this specification
+	provides two mechanisms for extend this set of interfaces and events without
+	creating conflicts: custom
+	events and implementation-specific
+	extensions.

+    
9.2. Custom Events

+    
A script author MAY wish to define an application in terms of functional
+	components, with event types that are meaningful to the application
+	architecture. The content author can use the CustomEvent interface to
+	create their own events appropriate to the level of abstraction they are
+	using.

+    

+      A content author might have created an application which features a
+		dynamically generated bar chart. This bar chart is meant to be updated every
+		5 minutes, or when a feed shows new information, or when the user refreshes
+		it manually by clicking a button. There are several handlers that have to be
+		called when the chart needs to be updated: the application has to fetch the
+		most recent data, show an icon to the user that the event is being updated,
+		and rebuild the chart. To manage this, the content author can choose to
+		create a custom updateChart event, which is fired whenever one of the
+		trigger conditions is met: 
+
var chartData = ...;
+var evt = document.createEvent("CustomEvent");
+evt.initCustomEvent( "updateChart", true, false, { data: chartData });
+document.documentElement.dispatchEvent(evt);
+

+    

+    
9.3. Implementation-Specific Extensions

+    
While a new event is being designed and prototyped, or when an event is
+	intended for implementation-specific functionality, it is desirable to
+	distinguish it from standardized events. Implementors SHOULD prefix event
+	types specific to their implementations with a short string to distinguish
+	it from the same event in other implementations and from standardized
+	events. This is similar to the vendor-specific keyword prefixes in CSS, though without the dashes ("-") used in CSS, since that
+	can cause problems when used as an attribute name in Javascript.

+    

+      A particular browser vendor, FooCorp, might wish to introduce a
+		new event, jump. This vendor implements fooJump in their browser, using their
+		vendor-specific prefix: "foo". Early adopters start
+		experimenting with the event, using someElement.addEventListener("fooJump", doJump, false ),
+		and provide feedback to FooCorp, who change the behavior of fooJump accordingly. 
+     
After some time, another vendor, BarOrg, decides they also want
+		the functionality, but implement it slightly differently, so they use
+		their own vendor-specific prefix, "bar" in their event type
+		name: barJump. Content authors
+		experimenting with this version of the jump event type register events with BarOrg’s
+		event type name. Content authors who wish to write code that accounts
+		for both browsers can either register each event type separately with
+		specific handlers, or use the same handler and switch on the name of the
+		event type. Thus, early experiments in different codebases do not
+		conflict, and the early adopter is able to write easily-maintained code
+		for multiple implementations.

+     
Eventually, as the feature matures, the behavior of both browsers
+		stabilizes and might converge due to content author and user feedback or
+		through formal standardization. As this stabilization occurs, and risk
+		of conflicts decrease, content authors can remove the forked code, and
+		use the jump event type name (even before
+		it is formally standardized) using the same event handler and the more
+		generic registration method someElement.addEventListener( "jump",
+		doJump, false).

+    

+    
9.3.1. Known Implementation-Specific Prefixes

+    
At the time of writing, the following event-type name prefixes are known to exist:

+    
+     
+      
+       
+       
+       
+       
+       
Prefix
+       Web Engine
+       Organization
+      
moz, Moz
+       Gecko
+       Mozilla
+      
ms, MS
+       Trident
+       Microsoft
+      
o, O
+       Presto
+       Opera Software
+      
webkit
+       WebKit
+       Apple, Google, others
+    

+   

+   

+    
10. Security Considerations

+    
This appendix discusses security considerations for UI Events implementations.
+The discussion is limited to security issues that arise directly from
+implementation of the event model, APIs and events defined in this
+specification. Implementations typically support other features like scripting
+languages, other APIs and additional events not defined in this document. These
+features constitute an unknown factor and are out of scope of this document.
+Implementers SHOULD consult the specifications of such features for their
+respective security considerations.

+    
Many of the event types defined in this specification are dispatched in response
+to user actions. This allows malicious event listeners to gain access to
+information users would typically consider confidential, e.g., typos they might
+have made when filling out a form, if they reconsider their answer to a multiple
+choice question shortly before submitting a form, their typing rate or primary
+input mechanism. In the worst case, malicious event listeners could capture all
+user interactions and submit them to a third party through means (not defined in
+this specification) that are generally available in DOM implementations, such as
+the XMLHttpRequest interface.

+    
In DOM implementations that support facilities to load external data, events
+like the error event can provide access to sensitive information aboutthe environment of the computer system or network. An example would be a
+malicious HTML document that attempts to embed a resource on the local network
+or the localhost on different ports. An embedded DOM application could
+then listen for error and load events to determine which othercomputers in a network are accessible from the local system or which ports are
+open on the system to prepare further attacks.

+    
An implementation of UI Events alone is generally insufficient to perform
+attacks of this kind and the security considerations of the facilities that
+possibly support such attacks apply. For conformance with this specification,
+DOM implementations MAY take reasonable steps to ensure that DOM
+applications do not get access to confidential or sensitive information. For
+example, they might choose not to dispatch load events to nodes thatattempt to embed resources on the local network.

+   

+   

+    
11. Changes

+    
11.1. Changes between DOM Level 2 Events and UI Events

+    
Numerous clarifications to the interfaces and event types have been made.
+    The HTMLEvents module is no longer defined in this document.
+    The focus and blur events have been added to the UIEvent module, and the dblclick event has been added to the MouseEvent module. This new specification provides a better separation between the DOM
+    event flow, the event types, and the DOM interfaces.

+    
11.1.1. Changes to DOM Level 2 event flow

+    
This new specification introduced the following new concepts in the
+        event flow:

+    
    
+     
  • 
+      
    Event listeners are now ordered. In DOM Level 2, the event ordering
+was unspecified.
    
+     
  • 
+      
    The event flow now includes the Window, to
+reflect existing implementations.
    
+    

+    
11.1.2. Changes to DOM Level 2 event types

+    
Many clarifications have been made on the event types. The conformance
+		is now explicitly defined against the event types, and not only in terms
+		of interfaces used by the event types.

+    
"MutationEvents" have been deprecated. Support for
+		namespaced events, present in early drafts of this specification, has
+		also been removed.

+    
For user agents which support the DOMNodeInserted and DOMNodeRemoved event types, this specification no longer requires		that the event type be fired for Attr nodes.

+    
The resize event type no longer bubbles and the mousemove event is now cancelable, reflecting existing implementations.

+    
11.1.3. Changes to DOM Level 2 Events interfaces

+    

+     
Interface Event
+     

+      
+     
Interface EventTarget
+     

+      
+     
Interface MouseEvent
+     

+      
+     
Exception EventException
+     

+      
    
+       
  • 
+        
    The exception EventException is removed in this
+specification. The prior DISPATCH_REQUEST_ERR code is re-mapped to a DOMException of type InvalidStateError.
    
+      

+    

+    
11.1.4. New Interfaces

+    
The interfaces CustomEvent, FocusEvent, KeyboardEvent, CompositionEvent, and WheelEvent were added to the Events module.

+    
11.2. Changes between different drafts of UI Events

+    
The DOM Level 3 Events document was originally developed between 2000 and
+	2003, and published as a W3C Note, pending further feedback and interest
+	from implementers. In 2006, it was picked up for revision and progress on
+	the Recommendation Track, and was then revised to reflect the current state
+	of implementation and the needs of script authors.

+    
Despite its status only as a W3C Note, rather than an official
+	Recommendation, DOM 3 Events saw some implementation, and was also
+	referenced by other specifications, so care is being taken to cause minimal
+	disruption, while still adapting the specification to the current
+	environment.

+    
The current specification has been reordered significantly from the earlier
+	W3C Note form, and also from the structure of DOM2 Events, in order to
+	clarify the material. New diagrams have been put in place to represent
+	hierarchies and events flows more clearly. Here are some of the more
+	important changes between drafts:

+    
    
+     
  • 
+      
    The key identifier feature has been renamed key value to
+disambiguate them from unique identifiers for keys.
    
+     
  • 
+      
    The KeyboardEvent interface was briefly (from 2003-2010) defined to
+have keyIdentifier and keyLocation attributes,
+but these were removed in favor of the current key and location attributes. These attributes were not widely
+implemented.
    
+     
  • 
+      
    The KeyboardEvent and CompositionEvent interfaces defined a locale attribute. This attribute was underspecified and
+moved into a technical note until it can be specified adequately.
+Refer to this old version of UI Events (before the DOM3Events spec was renamed "UI Events") for details.
    
+     
  • 
+      
    The KeyboardEvent also had a char attribute that
+was only used by the keypress event. Since the keypress event has		been deprecated, this attribute was no longer useful and was removed.
    
+     
  • 
+      
    The change, submit, and reset events were removed, since they were specific to HTML forms, and are
+specified in [HTML5].
    
+     
  • 
+      
    The textInput event, originally proposed as a replacement
+for keypress, was removed in favor of the current beforeinput and input events.
    
+     
  • 
+      
    Namespaced events have been removed.
    
+     
  • 
+      
    Updated to use [WebIDL].
    
+     
  • 
+      
    EventException has been removed.
    
+    

+   

+   

+    
12. Acknowledgements

+    
Many people contributed to the DOM specifications (Level 1, 2 or 3),
+including participants of the DOM Working Group, the DOM Interest Group,
+the WebAPI Working Group, and the WebApps Working Group.
+We especially thank the following:

+    
Andrew Watson (Object Management Group),
+Andy Heninger (IBM),
+Angel Diaz (IBM),
+Anne van Kesteren (Opera Software),
+Arnaud Le Hors (W3C and IBM),
+Arun Ranganathan (AOL),
+Ashok Malhotra (IBM and Microsoft),
+Ben Chang (Oracle),
+Bill Shea (Merrill Lynch),
+Bill Smith (Sun),
+Björn Höhrmann,
+Bob Sutor (IBM),
+Charles McCathie-Nevile (Opera Software, Co-Chair),
+Chris Lovett (Microsoft),
+Chris Wilson (Microsoft),
+Christophe Jolif (ILOG),
+David Brownell (Sun),
+David Ezell (Hewlett-Packard Company),
+David Singer (IBM),
+Dean Jackson (W3C, W3C Team Contact),
+Dimitris Dimitriadis (Improve AB and invited expert),
+Don Park (invited),
+Doug Schepers (Vectoreal),
+Elena Litani (IBM),
+Eric Vasilik (Microsoft),
+Gavin Nicol (INSO),
+Gorm Haug Eriksen (Opera Software),
+Ian Davis (Talis Information Limited),
+Ian Hickson (Google),
+Ian Jacobs (W3C),
+James Clark (invited),
+James Davidson (Sun),
+Jared Sorensen (Novell),
+Jeroen van Rotterdam (X-Hive Corporation),
+Joe Kesselman (IBM),
+Joe Lapp (webMethods),
+Joe Marini (Macromedia),
+John Robinson (AOL),
+Johnny Stenback (Netscape/AOL),
+Jon Ferraiolo (Adobe),
+Jonas Sicking (Mozilla Foundation),
+Jonathan Marsh (Microsoft),
+Jonathan Robie (Texcel Research and Software AG),
+Kim Adamson-Sharpe (SoftQuad Software Inc.),
+Lauren Wood (SoftQuad Software Inc., former Chair),
+Laurence Cable (Sun),
+Luca Mascaro (HTML Writers Guild),
+Maciej Stachowiak (Apple Computer),
+Marc Hadley (Sun Microsystems),
+Mark Davis (IBM),
+Mark Scardina (Oracle),
+Martin Dürst (W3C),
+Mary Brady (NIST),
+Michael Shenfield (Research In Motion),
+Mick Goulish (Software AG),
+Mike Champion (Arbortext and Software AG),
+Miles Sabin (Cromwell Media),
+Patti Lutsky (Arbortext),
+Paul Grosso (Arbortext),
+Peter Sharpe (SoftQuad Software Inc.),
+Phil Karlton (Netscape),
+Philippe Le Hégaret (W3C, W3C Team Contact and former Chair),
+Ramesh Lekshmynarayanan (Merrill Lynch),
+Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair),
+Rezaur Rahman (Intel),
+Rich Rollman (Microsoft),
+Rick Gessner (Netscape),
+Rick Jelliffe (invited),
+Rob Relyea (Microsoft),
+Robin Berjon (Expway, Co-Chair),
+Scott Hayman (Research In Motion),
+Scott Isaacs (Microsoft),
+Sharon Adler (INSO),
+Stéphane Sire (IntuiLab),
+Steve Byrne (JavaSoft),
+Tim Bray (invited),
+Tim Yu (Oracle),
+Tom Pixley (Netscape/AOL),
+T.V. Raman (Google).
+Vidur Apparao (Netscape) and
+Vinod Anupam (Lucent).

+    
Former editors: Tom Pixley (Netscape Communications Corporation) until July 2002;
+Philippe Le Hégaret (W3C) until November 2003;
+Björn Höhrmann (Invited Expert) until January 2008;
+and Jacob Rossi (Microsoft) from March 2011 to October 2011.

+    
Contributors: In the WebApps Working Group, the following people made substantial
+material contributions in the process of refining and revising this
+specification:
+Bob Lund (Cable Laboratories),
+Cameron McCormack (Invited Expert / Mozilla),
+Daniel Danilatos (Google),
+Gary Kacmarcik (Google),
+Glenn Adams (Samsung),
+Hallvord R. M. Steen (Opera),
+Hironori Bono (Google),
+Mark Vickers (Comcast),
+Masayuki Nakano (Mozilla),
+Olli Pettay (Mozilla),
+Takayoshi Kochi (Google) and
+Travis Leithead (Microsoft).

+    
Glossary contributors: Arnaud Le Hors (W3C) and
+Robert S. Sutor (IBM Research).

+    
Test suite contributors: Carmelo Montanez (NIST),
+Fred Drake,
+Mary Brady (NIST),
+Neil Delima (IBM),
+Rick Rivello (NIST),
+Robert Clary (Netscape),
+with a special mention to Curt Arnold.

+    
Thanks to all those who have helped to improve this specification by
+sending suggestions and corrections (please, keep bugging us with your
+issues!), or writing informative books or Web sites:
+Al Gilman,
+Alex Russell,
+Alexander J. Vincent,
+Alexey Proskuryakov,
+Arkadiusz Michalski,
+Brad Pettit,
+Cameron McCormack,
+Chris Rebert,
+Curt Arnold,
+David Flanagan,
+Dylan Schiemann,
+Erik Arvidsson,
+Garrett Smith,
+Giuseppe Pascale,
+James Su,
+Jan Goyvaerts (regular-expressions.info),
+Jorge Chamorro,
+Kazuyuki Ashimura,
+Ken Rehor,
+Magnus Kristiansen,
+Martijn Wargers,
+Martin Dürst,
+Michael B. Allen,
+Mike Taylor,
+Misha Wolf,
+Ojan Vafai,
+Oliver Hunt,
+Paul Irish,
+Peter-Paul Koch,
+Richard Ishida,
+Sean Hogan,
+Sergey Ilinsky,
+Sigurd Lerstad,
+Steven Pemberton,
+Tony Chang,
+William Edney and
+Øistein E. Andersen.

+   

+   

+    
13. Glossary

+    
Some of the following term definitions have been borrowed or modified from
+similar definitions in other W3C or standards documents. See the links within
+the definitions for more information.

+    

+     

+      
activation behavior

+     

+      
The action taken when an event, typically initiated by users through
+an input device, causes an element to fulfill a defined task.  The task MAY
+be defined for that element by the host language, or by
+author-defined variables, or both.  The default task for any given element
+MAY be a generic action, or MAY be unique to that element.  For example, the
+activation behavior of an HTML or SVG <a> element is to
+cause the user agent to traverse the link specified in the href attribute, with the further optional parameter of
+specifying the browsing context for the traversal (such as the current
+window or tab, a named window, or a new window). The activation behavior of
+an HTML <input> element with the type attribute value submit is be to send the values of the form
+elements to an author-defined IRI by the author-defined HTTP method.  See §3.5 Activation triggers and behavior for more details.

+     

+      
activation trigger

+     

+      
An event which is defined to initiate an activation behavior.  Refer
+to §3.5 Activation triggers and behavior for more details.

+     

+      
author

+     

+      
In the context of this specification, an author, content
+author, or script author is a person who writes script or
+other executable content that uses the interfaces, events, and event flow
+defined in this specification. See §1.2.3 Content authors and content conformance category
+for more details.

+     

+      
body element

+     

+      
In HTML or XHTML documents, the body element represents the contents of the
+document. In a well-formed HTML document, the body element is a first
+descendant of the root element.

+     

+      
bubbling phase

+     

+      
The process by which an event can be handled by one of the target’s
+ancestors after being handled by the event target. See the
+description of the bubble phase in the context of event flow for more
+details.

+     

+      
capture phase

+     

+      
The process by which an event can be handled by one of the target’s
+ancestors before being handled by the event target. See the
+description of the capture phase in the context
+of event flow for more details.

+     

+      
candidate event handlers

+     

+      
candidate event listeners

+     

+      
The list of all event listeners that have been registered on the
+target object in their order of registration. When an event is about to be
+dispatched to a target object, the list of current listeners is captured
+before any event listeners are dispatched on the target. Listeners which
+are newly added after the event dispatch begins will not affect the order of
+listeners in the captured list, although listeners which are removed after
+dispatch begins will be removed.

+      
 Initially capturing the candidate event handlers and not allowing new
+listeners to be added prevents infinite loops of event listener dispatch on
+a given target object. 

+     

+      
character value

+     

+      
In the context of key values, a character value is a string representing one
+or more Unicode characters, such as a letter or symbol, or a set of letters.
+In this specification, character values are denoted as a unicode string
+(e.g., U+0020) or a glyph representation of the same code point (e.g., " "), and are color coded to help distinguish these two representations.

+      
 In source code, some key values, such as non-graphic characters, can be
+represented using the character escape syntax of the programming language in
+use. 

+     

+      
current event target

+     

+      
In an event flow, the current event target is the object associated with the event handler that is currently being dispatched. This object MAY be
+the event target itself or one of its ancestors. The current event
+target changes as the event propagates from object to object through
+the various phases of the event flow. The current event target is the
+value of the currentTarget attribute.

+     

+      
dead key

+     

+      
A dead key is a key or combination of keys which produces no character by
+itself, but which in combination or sequence with another key produces a
+modified character, such as a character with diacritical marks (e.g., "ö", "é", "â").

+     

+      
default action

+     

+      
A default action is an OPTIONAL supplementary behavior that an
+implementation MUST perform in combination with the dispatch of the event
+object.  Each event type definition, and each specification, defines the default action for that event type, if it has one.  An instance of an
+event MAY have more than one default action under some circumstances,
+such as when associated with an activation trigger.  A default
+action MAY be cancelled through the invocation of the preventDefault() method. For more details, see §3.2 Default actions and cancelable events.

+     

+      
delta

+     

+      
The estimated scroll amount (in pixels, lines, or pages) that the user agent
+will scroll or zoom the page in response to the physical movement of an
+input device that supports the WheelEvent interface (such as a mouse
+wheel or touch pad). The value of a delta (e.g., the deltaX, deltaY, or deltaZ attributes) is to be interpreted in the context of the current deltaMode property. The relationship between the physical
+movement of a wheel (or other device) and whether the delta is
+positive or negative is environment and device dependent. However, if a user
+agent scrolls as the default action then the sign of the delta is given by a right-hand coordinate system where positive X,Y, and Z axes
+are directed towards the right-most edge, bottom-most edge, and farthest
+depth (away from the user) of the document, respectively.

+     

+      
deprecated

+     

+      
Features marked as deprecated are included in the specification as reference
+to older implementations or specifications, but are OPTIONAL and
+discouraged.  Only features which have existing or in-progress replacements
+MUST be deprecated in this specification.  Implementations which do not
+already include support for the feature MAY implement deprecated features
+for reasons of backwards compatibility with existing content, but content
+authors creating content SHOULD NOT use deprecated features, unless there is
+no other way to solve a use case. Other specifications which reference this
+specification SHOULD NOT use deprecated features, but SHOULD point instead
+to the replacements of which the feature is deprecated in favor.  Features
+marked as deprecated in this specification are expected to be dropped from
+future specifications.

+     

+      
dispatch

+     

+      
To create an event with attributes and methods appropriate to its type and
+context, and propagate it through the DOM tree in the specified manner.
+Interchangeable with the term fire, e.g., fire a click event or dispatch a load event.

+     

+      
document

+     

+      
An object instantiating the Document interface [DOM-Level-3-Core],
+representing the entire HTML or XML text document.  Conceptually, it is the
+root of the document tree, and provides the primary access to the document’s
+data.

+     

+      
DOM application

+     

+      
A DOM application is script or code, written by a content author or
+automatically generated, which takes advantage of the interfaces, methods,
+attributes, events, and other features described in this specification in
+order to make dynamic or interactive content, such as Web applications,
+exposed to users in a user agent.

+     

+      
DOM Level 0

+     

+      
The term DOM Level 0 refers to a mix of HTML document functionalities,
+often not formally specified but traditionally supported as de facto
+standards, implemented originally by Netscape Navigator version 3.0 or
+Microsoft Internet Explorer version 3.0.  In many cases, attributes or
+methods have been included for reasons of backward compatibility with DOM
+Level 0.

+     

+      
empty string

+     

+      
The empty string is a value of type DOMString of length 0, i.e., a string which contains no characters (neither
+printing nor control characters).

+     

+      
event

+     

+      
An event is the representation of some occurrence (such as a mouse click on
+the presentation of an element, the removal of child node from an element,
+or any number of other possibilities) which is associated with its event
+target. Each event is an instantiation of one specific event
+type.

+     

+      
event focus

+     

+      
Event focus is a special state of receptivity and concentration on a
+particular element or other event target within a document.  Each
+element has different behavior when focused, depending on its functionality,
+such as priming the element for activation (as for a button or hyperlink) or
+toggling state (as for a checkbox), receiving text input (as for a text form
+field), or copying selected text.  For more details, see §4.2.3 Document Focus and Focus Context.

+     

+      
event focus ring

+     

+      
An event focus ring is an ordered set of event focus targets within a
+document.  A host language MAY define one or more ways to determine
+the order of targets, such as document order, a numerical index defined per
+focus target, explicit pointers between focus targets, or a hybrid of
+different models.  Each document MAY contain multiple focus rings, or
+conditional focus rings.  Typically, for document-order or indexed focus
+rings, focus wraps around from the last focus target to the
+first.

+     

+      
event handler

+     

+      
event listener

+     

+      
An object that implements the EventListener interface and provides an handleEvent() callback method. Event handlers are
+language-specific. Event handlers are invoked in the context of a particular
+object (the current event target) and are provided with the event
+object itself.

+      
 In JavaScript, user-defined functions are considered to implement the EventListener interface. Thus the event object will be provided as the
+first parameter to the user-defined function when it is invoked.
+Additionally, JavaScript objects can also implement the EventListener interface when they define a handleEvent method. 

+     

+      
event order

+     

+      
The sequence in which events from the same event source or process occur,
+using the same or related event interfaces. For example, in an environment
+with a mouse, a track pad, and a keyboard, each of those input devices would
+constitute a separate event source, and each would follow its own event
+order. A mousedown event from the trackpad followed by a mouseup event from the mouse would not result in a click event.

+      
 There can be interactions between different event orders. For example, a click event might be modified by a concurrent keydown event	(e.g., via Shift+click). However, the event	orders of these different event sources would be distinct. 

+      
The event order of some interfaces are device-independent. For example, a
+user might change focus using the Tab key, or by clicking the new	focused element with the mouse.  The event order in such cases depends on
+the state of the process, not on the state of the device that initiates the
+state change.

+     

+      
event phase

+     

+      
See phase.

+     

+      
event target

+     

+      
The object to which an event is targeted using the §3.1 Event dispatch and DOM event flow.
+The event target is the value of the target attribute.

+     

+      
event type

+     

+      
An event type is an event object with a particular name and
+which defines particular trigger conditions, properties, and other
+characteristics which distinguish it from other event types.  For example,
+the click event type has different characteristics than the mouseover or load event types. The event type is exposed as	the type attribute on the event object.  See §4 Event Types for
+more details.  Also loosely referred to as "event", such as the click event.

+     

+      
fire

+     

+      
A synonym for dispatch.

+     

+      
host language

+     

+      
Any language which integrates the features of another language or API
+specification, while normatively referencing the origin specification rather
+than redefining those features, and extending those features only in ways
+defined by the origin specification.  An origin specification typically is
+only intended to be implemented in the context of one or more host
+languages, not as a standalone language.  For example, XHTML, HTML, and SVG
+are host languages for UI Events, and they integrate and extend the objects
+and models defined in this specification.

+     

+      
hysteresis

+     

+      
A feature of human interface design to accept input values within a certain
+range of location or time, in order to improve the user experience.  For
+example, allowing for small deviation in the time it takes for a user to
+double-click a mouse button is temporal hysteresis, and not immediately
+closing a nested menu if the user mouses out from the parent window when
+transitioning to the child menu is locative hysteresis.

+     

+      
IME

+     

+      
input method editor

+     

+      
An input method editor (IME), also known as a front end
+processor, is an application that performs the conversion between
+keystrokes and ideographs or other characters, usually by user-guided
+dictionary lookup, often used in East Asian languages (e.g., Chinese,
+Japanese, Korean).  An IME MAY also be used for dictionary-based word
+completion, such as on mobile devices.  See §5.3.3 Input Method Editors for treatment of
+IMEs in this specification.  See also text composition system.

+     

+      
key mapping

+     

+      
Key mapping is the process of assigning a key value to a particular key, and
+is the result of a combination of several factors, including the operating
+system and the keyboard layout (e.g., QWERTY, Dvorak, Spanish,
+InScript, Chinese, etc.), and after taking into account all modifier
+key (Shift, Alt, et al.) and dead key states.

+     

+      
key value

+     

+      
A key value is a character value or multi-character string (such as "Enter", "Tab", or "MediaTrackNext") associated with a key in a	particular state. Every key has a key value, whether or not it has a character value. This includes control keys, function keys, modifier keys, dead keys, and any other key. The key value of
+any given key at any given time depends upon the key mapping.

+     

+      
local name

+     

+      
See local name in [XML-Names11].

+     

+      
modifier key

+     

+      
A modifier key changes the normal behavior of a key, such as to produce a
+character of a different case (as with the Shift key), or to alter	what functionality the key triggers (as with the Fn or Alt keys). Refer to §5.3.1 Modifier keys for a list of modifier keys.

+     

+      
namespace URI

+     

+      
A namespace URI is a URI that identifies an XML namespace. This is
+called the namespace name in [XML-Names11]. See also sections 1.3.2 DOM URIs and 1.3.3 XML Namespaces regarding URIs and namespace URIs handling and comparison in the DOM APIs.

+     

+      
phase

+     

+      
In the context of events, a phase is set of logical traversals from
+node to node along the DOM tree, from the Window to the Document object, root element, and down to the event target (capture
+phase), at the event target itself (target phase), and
+back up the same chain (bubbling phase).

+     

+      
propagation path

+     

+      
The ordered set of current event targets though which an event object will pass sequentially on the way to and back from the event
+target.  As the event propagates, each current event target in
+the propagation path is in turn set as the currentTarget. The
+propagation path is initially composed of one or more event phases as
+defined by the event type, but MAY be interrupted.  Also known as an event target chain.

+     

+      
QWERTY

+     

+      
QWERTY (pronounced ˈkwɜrti) is a common keyboard layout,
+so named because the first five character keys on the top row of letter keys
+are Q, W, E, R, T, and Y.  There are many other popular keyboard layouts
+(including the Dvorak and Colemak layouts), most designed for localization
+or ergonomics.

+     

+      
root element

+     

+      
The first element node of a document, of which all other elements are
+children. The document element.

+     

+      
rotation

+     

+      
An indication of incremental change on an input device using the WheelEvent interface. On some devices this MAY be a literal rotation of
+a wheel, while on others, it MAY be movement along a flat surface, or
+pressure on a particular button.

+     

+      
target phase

+     

+      
The process by which an event can be handled by the event
+target. See the description of the target phase in the context of
+event flow for more details.

+     

+      
text composition system

+     

+      
A software component that interprets some form of alternate input (such as a input method editor, a speech processor, or a handwriting recognition
+system) and converts it to text.

+     

+      
topmost event target

+     

+      
The topmost event target MUST be the element highest in the rendering
+order which is capable of being an event target. In graphical user
+interfaces this is the element under the user’s pointing device. A user
+interface’s hit testing facility is used to determine the target. For
+specific details regarding hit testing and stacking order, refer to the host language.

+     

+      
tree

+     

+      
A data structure that represents a document as a hierarchical set of nodes
+with child-parent-sibling relationships, i.e., each node having one or more
+possible ancestors (nodes higher in the hierarchy in a direct lineage), one
+or more possible descendants (nodes lower in the hierarchy in a direct
+lineage), and one or more possible peers (nodes of the same level in the
+hierarchy, with the same immediate ancestor).

+     

+      
Unicode character categories

+     

+      
A subset of the General Category values that are defined for each Unicode
+code point. This subset contains all the
+Letter (Ll, Lm, Lo, Lt, Lu),
+Number (Nd, Nl, No),
+Punctuation (Pc, Pd, Pe, Pf, Pi, Po, Ps)
+and Symbol (Sc, Sk, Sm, So)
+category values.

+     

+      
un-initialized value

+     

+      
The value of any event attribute (such as bubbles or currentTarget) before the event has been initialized with initEvent(). The un-initialized values of an event apply
+immediately after a new event has been created using the method createEvent().

+     

+      
user agent

+     

+      
A program, such as a browser or content authoring tool, normally running on
+a client machine, which acts on a user’s behalf in retrieving, interpreting,
+executing, presenting, or creating content.  Users MAY act on the content
+using different user agents at different times, for different purposes.  See
+the §1.2.1 Web browsers and other dynamic or interactive user agents and §1.2.2 Authoring tools for details on the
+requirements for a conforming user agent.

+     

+      
Window

+     

+      
The Window is the object referred to by the current document’s
+browsing context’s Window Proxy object as defined in HTML5 [HTML5].

+    

+   

+  

+
+  
Index

+  
Terms defined by this specification

+  
+  
Terms defined by reference

+  
+  
References

+  
Normative References

+  

+   
[DOM]
+   
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
+   
[DOM-Level-2-Events]
+   
Tom Pixley. Document Object Model (DOM) Level 2 Events Specification. 13 November 2000. REC. URL: https://www.w3.org/TR/DOM-Level-2-Events/
+   
[DOM-Level-3-Core]
+   
Arnaud Le Hors; et al. Document Object Model (DOM) Level 3 Core Specification. 7 April 2004. REC. URL: https://www.w3.org/TR/DOM-Level-3-Core/
+   
[HTML]
+   
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
+   
[HTML5]
+   
Ian Hickson; et al. HTML5. 28 October 2014. REC. URL: https://www.w3.org/TR/html5/
+   
[RFC2119]
+   
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
+   
[SVG2]
+   
Nikos Andronikos; et al. Scalable Vector Graphics (SVG) 2. 15 September 2016. CR. URL: https://www.w3.org/TR/SVG2/
+   
[UIEVENTS]
+   
Gary Kacmarcik; Travis Leithead. UI Events. 4 August 2016. WD. URL: https://www.w3.org/TR/uievents/
+   
[UIEvents-Code]
+   
Gary Kacmarcik; Travis Leithead. UI Events KeyboardEvent code Values. 24 October 2016. WD. URL: https://www.w3.org/TR/uievents-code/
+   
[UIEvents-Key]
+   
Gary Kacmarcik; Travis Leithead. UI Events KeyboardEvent key Values. 24 October 2016. WD. URL: https://www.w3.org/TR/uievents-key/
+   
[WebIDL]
+   
Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. 15 December 2016. WD. URL: https://www.w3.org/TR/WebIDL-1/
+  

+  
Informative References

+  

+   
[CSS2]
+   
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. REC. URL: https://www.w3.org/TR/CSS2
+   
[DWW95]
+   
N. Kano. Developing International Software for Windows 95 and Windows NT: A Handbook for International Software Design. 1995. 
+   
[Editing]
+   
A. Gregor. HTML Editing APIs. URL: https://dvcs.w3.org/hg/editing/raw-file/tip/editing.html
+   
[HTML40]
+   
Dave Raggett; Arnaud Le Hors; Ian Jacobs. HTML 4.0 Recommendation. 24 April 1998. REC. URL: https://www.w3.org/TR/html40
+   
[RFC20]
+   
V.G. Cerf. ASCII format for network interchange. October 1969. Internet Standard. URL: https://tools.ietf.org/html/rfc20
+   
[UAAG20]
+   
James Allan; et al. User Agent Accessibility Guidelines (UAAG) 2.0. 15 December 2015. NOTE. URL: https://www.w3.org/TR/UAAG20/
+   
[UAX15]
+   
Mark Davis; Ken Whistler. Unicode Normalization Forms. 31 August 2012. Unicode Standard Annex #15. URL: http://www.unicode.org/reports/tr15
+   
[Unicode]
+   
The Unicode Standard. URL: http://www.unicode.org/versions/latest/
+   
[US-ASCII]
+   
Coded Character Set - 7-Bit American Standard Code for Information Interchange. 1986. 
+   
[WIN1252]
+   
Windows 1252 a Coded Character Set - 8-Bit. URL: http://www.microsoft.com/globaldev/reference/sbcs/1252.htm
+   
[XFORMS]
+   
John Boyer. XForms 1.0 (Third Edition). 29 October 2007. REC. URL: https://www.w3.org/TR/xforms/
+   
[XML-Names11]
+   
Tim Bray; et al. Namespaces in XML 1.1 (Second Edition). 16 August 2006. REC. URL: https://www.w3.org/TR/xml-names11/
+  

+  
IDL Index

+
[Constructor(DOMString type, optional UIEventInit eventInitDict)]
+interface UIEvent : Event {
+  readonly attribute Window? view;
+  readonly attribute long detail;
+};
+
+dictionary UIEventInit : EventInit {
+  Window? view = null;
+  long detail = 0;
+};
+
+[Constructor(DOMString type, optional FocusEventInit eventInitDict)]
+interface FocusEvent : UIEvent {
+  readonly attribute EventTarget? relatedTarget;
+};
+
+dictionary FocusEventInit : UIEventInit {
+  EventTarget? relatedTarget = null;
+};
+
+[Constructor(DOMString type, optional MouseEventInit eventInitDict)]
+interface MouseEvent : UIEvent {
+  readonly attribute long screenX;
+  readonly attribute long screenY;
+  readonly attribute long clientX;
+  readonly attribute long clientY;
+
+  readonly attribute boolean ctrlKey;
+  readonly attribute boolean shiftKey;
+  readonly attribute boolean altKey;
+  readonly attribute boolean metaKey;
+
+  readonly attribute short button;
+  readonly attribute unsigned short buttons;
+
+  readonly attribute EventTarget? relatedTarget;
+
+  boolean getModifierState(DOMString keyArg);
+};
+
+dictionary MouseEventInit : EventModifierInit {
+  long screenX = 0;
+  long screenY = 0;
+  long clientX = 0;
+  long clientY = 0;
+
+  short button = 0;
+  unsigned short buttons = 0;
+  EventTarget? relatedTarget = null;
+};
+
+dictionary EventModifierInit : UIEventInit {
+  boolean ctrlKey = false;
+  boolean shiftKey = false;
+  boolean altKey = false;
+  boolean metaKey = false;
+
+  boolean modifierAltGraph = false;
+  boolean modifierCapsLock = false;
+  boolean modifierFn = false;
+  boolean modifierFnLock = false;
+  boolean modifierHyper = false;
+  boolean modifierNumLock = false;
+  boolean modifierScrollLock = false;
+  boolean modifierSuper = false;
+  boolean modifierSymbol = false;
+  boolean modifierSymbolLock = false;
+};
+
+[Constructor(DOMString type, optional WheelEventInit eventInitDict)]
+interface WheelEvent : MouseEvent {
+  // DeltaModeCode
+  const unsigned long DOM_DELTA_PIXEL = 0x00;
+  const unsigned long DOM_DELTA_LINE  = 0x01;
+  const unsigned long DOM_DELTA_PAGE  = 0x02;
+
+  readonly attribute double deltaX;
+  readonly attribute double deltaY;
+  readonly attribute double deltaZ;
+  readonly attribute unsigned long deltaMode;
+};
+
+dictionary WheelEventInit : MouseEventInit {
+  double deltaX = 0.0;
+  double deltaY = 0.0;
+  double deltaZ = 0.0;
+  unsigned long deltaMode = 0;
+};
+
+[Constructor(DOMString type, optional InputEventInit eventInitDict)]
+interface InputEvent : UIEvent {
+  readonly attribute DOMString? data;
+  readonly attribute boolean isComposing;
+};
+
+dictionary InputEventInit : UIEventInit {
+  DOMString? data = "";
+  boolean isComposing = false;
+};
+
+[Constructor(DOMString type, optional KeyboardEventInit eventInitDict)]
+interface KeyboardEvent : UIEvent {
+  // KeyLocationCode
+  const unsigned long DOM_KEY_LOCATION_STANDARD = 0x00;
+  const unsigned long DOM_KEY_LOCATION_LEFT = 0x01;
+  const unsigned long DOM_KEY_LOCATION_RIGHT = 0x02;
+  const unsigned long DOM_KEY_LOCATION_NUMPAD = 0x03;
+
+  readonly attribute DOMString key;
+  readonly attribute DOMString code;
+  readonly attribute unsigned long location;
+
+  readonly attribute boolean ctrlKey;
+  readonly attribute boolean shiftKey;
+  readonly attribute boolean altKey;
+  readonly attribute boolean metaKey;
+
+  readonly attribute boolean repeat;
+  readonly attribute boolean isComposing;
+
+  boolean getModifierState(DOMString keyArg);
+};
+
+dictionary KeyboardEventInit : EventModifierInit {
+  DOMString key = "";
+  DOMString code = "";
+  unsigned long location = 0;
+  boolean repeat = false;
+  boolean isComposing = false;
+};
+
+[Constructor(DOMString type, optional CompositionEventInit eventInitDict)]
+interface CompositionEvent : UIEvent {
+  readonly attribute DOMString data;
+};
+
+dictionary CompositionEventInit : UIEventInit {
+  DOMString data = "";
+};
+
+partial interface UIEvent {
+  // The following support legacy user agents
+  readonly attribute unsigned long which;
+};
+
+partial interface KeyboardEvent {
+  // The following support legacy user agents
+  readonly attribute unsigned long charCode;
+  readonly attribute unsigned long keyCode;
+};
+
+

+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+
\ No newline at end of file
diff --git a/test/node/parsing/webSpec/WebUSB/0 b/test/node/parsing/WebUSB/0
similarity index 100%
rename from test/node/parsing/webSpec/WebUSB/0
rename to test/node/parsing/WebUSB/0
diff --git a/test/node/parsing/webSpec/WebUSB/14 b/test/node/parsing/WebUSB/14
similarity index 100%
rename from test/node/parsing/webSpec/WebUSB/14
rename to test/node/parsing/WebUSB/14
diff --git a/test/node/parsing/webSpec/WebUSB/3 b/test/node/parsing/WebUSB/3
similarity index 100%
rename from test/node/parsing/webSpec/WebUSB/3
rename to test/node/parsing/WebUSB/3
diff --git a/test/node/parsing/webSpec/WebUSB/spec.html b/test/node/parsing/WebUSB/spec.html
similarity index 100%
rename from test/node/parsing/webSpec/WebUSB/spec.html
rename to test/node/parsing/WebUSB/spec.html
diff --git a/test/node/parsing/whatwg/29 b/test/node/parsing/whatwg/29
new file mode 100644
index 0000000..f2b223e
--- /dev/null
+++ b/test/node/parsing/whatwg/29
@@ -0,0 +1,7 @@
+[LegacyUnenumerableNamedProperties]
+interface HTMLAllCollection {
+  readonly attribute unsigned long length;
+  getter Element? (unsigned long index);
+  getter (HTMLCollection or Element)? namedItem(DOMString name);
+  legacycaller (HTMLCollection or Element)? item(optional DOMString nameOrIndex);
+};
diff --git a/test/node/parsing/whatwg/spec.html b/test/node/parsing/whatwg/spec.html
new file mode 100644
index 0000000..2fee154
--- /dev/null
+++ b/test/node/parsing/whatwg/spec.html
@@ -0,0 +1,22849 @@
+
+
+HTML Standard
+  
+  File an issue about the selected text
+
+  

+
+  

+
+  
Table of contents

+  
  1. 1 Introduction
  2. 2 Common infrastructure
  3. 3 Semantics, structure, and APIs of HTML documents
  4. 4 The elements of HTML
  5. 5 Microdata
  6. 6 User interaction
  7. 7 Loading Web pages
  8. 8 Web application APIs
  9. 9 Communication
  10. 10 Web workers
  11. 11 Web storage
  12. 12 The HTML syntax
  13. 13 The XML syntax
  14. 14 Rendering
  15. 15 Obsolete features
  16. 16 IANA considerations
  17. Index
  18. References
  19. Acknowledgments

+
+  
Full table of contents

+  
  1. 1 Introduction
    1. 1.1 Where does this specification fit?
    2. 1.2 Is this HTML5?
    3. 1.3 Background
    4. 1.4 Audience
    5. 1.5 Scope
    6. 1.6 History
    7. 1.7 Design notes
      1. 1.7.1 Serializability of script execution
      2. 1.7.2 Compliance with other specifications
      3. 1.7.3 Extensibility
    8. 1.8 HTML vs XML syntax
    9. 1.9 Structure of this specification
      1. 1.9.1 How to read this specification
      2. 1.9.2 Typographic conventions
    10. 1.10 Privacy concerns
      1. 1.10.1 Cross-site communication
    11. 1.11 A quick introduction to HTML
      1. 1.11.1 Writing secure applications with HTML
      2. 1.11.2 Common pitfalls to avoid when using the scripting APIs
      3. 1.11.3 How to catch mistakes when writing HTML: validators and conformance checkers
    12. 1.12 Conformance requirements for authors
      1. 1.12.1 Presentational markup
      2. 1.12.2 Syntax errors
      3. 1.12.3 Restrictions on content models and on attribute values
    13. 1.13 Suggested reading
  2. 2 Common infrastructure
    1. 2.1 Terminology
      1. 2.1.1 Resources
      2. 2.1.2 XML compatibility
      3. 2.1.3 DOM trees
      4. 2.1.4 Scripting
      5. 2.1.5 Plugins
      6. 2.1.6 Character encodings
      7. 2.1.7 Conformance classes
      8. 2.1.8 Dependencies
      9. 2.1.9 Extensibility
      10. 2.1.10 Interactions with XPath and XSLT
    2. 2.2 Case-sensitivity and string comparison
    3. 2.3 Common microsyntaxes
      1. 2.3.1 Common parser idioms
      2. 2.3.2 Boolean attributes
      3. 2.3.3 Keywords and enumerated attributes
      4. 2.3.4 Numbers
        1. 2.3.4.1 Signed integers
        2. 2.3.4.2 Non-negative integers
        3. 2.3.4.3 Floating-point numbers
        4. 2.3.4.4 Percentages and lengths
        5. 2.3.4.5 Non-zero percentages and lengths
        6. 2.3.4.6 Lists of floating-point numbers
        7. 2.3.4.7 Lists of dimensions
      5. 2.3.5 Dates and times
        1. 2.3.5.1 Months
        2. 2.3.5.2 Dates
        3. 2.3.5.3 Yearless dates
        4. 2.3.5.4 Times
        5. 2.3.5.5 Local dates and times
        6. 2.3.5.6 Time zones
        7. 2.3.5.7 Global dates and times
        8. 2.3.5.8 Weeks
        9. 2.3.5.9 Durations
        10. 2.3.5.10 Vaguer moments in time
      6. 2.3.6 Colors
      7. 2.3.7 Space-separated tokens
      8. 2.3.8 Comma-separated tokens
      9. 2.3.9 References
      10. 2.3.10 Media queries
    4. 2.4 URLs
      1. 2.4.1 Terminology
      2. 2.4.2 Parsing URLs
      3. 2.4.3 Dynamic changes to base URLs
    5. 2.5 Fetching resources
      1. 2.5.1 Terminology
      2. 2.5.2 Determining the type of a resource
      3. 2.5.3 Extracting character encodings from meta elements
      4. 2.5.4 CORS settings attributes
      5. 2.5.5 Referrer policy attributes
    6. 2.6 Common DOM interfaces
      1. 2.6.1 Reflecting content attributes in IDL attributes
      2. 2.6.2 Collections
        1. 2.6.2.1 The HTMLAllCollection interface
        2. 2.6.2.2 The HTMLFormControlsCollection interface
        3. 2.6.2.3 The HTMLOptionsCollection interface
      3. 2.6.3 The DOMStringList interface
      4. 2.6.4 Garbage collection
    7. 2.7 Safe passing of structured data
      1. 2.7.1 Serializable objects
      2. 2.7.2 Transferable objects
      3. 2.7.3 StructuredSerializeInternal ( value,
+  forStorage [ , memory ] )
      4. 2.7.4 StructuredSerialize ( value )
      5. 2.7.5 StructuredSerializeForStorage ( value )
      6. 2.7.6 StructuredDeserialize ( serialized,
+  targetRealm [ , memory ] )
      7. 2.7.7 StructuredSerializeWithTransfer ( value,
+  transferList )
      8. 2.7.8 StructuredDeserializeWithTransfer (
+  serializeWithTransferResult, targetRealm )
      9. 2.7.9 Performing serialization and
+  transferring from other specifications
      10. 2.7.10 Monkey patch for Blob and FileList objects
  3. 3 Semantics, structure, and APIs of HTML documents
    1. 3.1 Documents
      1. 3.1.1 The Document object
      2. 3.1.2 Resource metadata management
      3. 3.1.3 DOM tree accessors
    2. 3.2 Elements
      1. 3.2.1 Semantics
      2. 3.2.2 Elements in the DOM
      3. 3.2.3 HTML element constructors
      4. 3.2.4 Element definitions
        1. 3.2.4.1 Attributes
      5. 3.2.5 Content models
        1. 3.2.5.1 The "nothing" content model
        2. 3.2.5.2 Kinds of content
          1. 3.2.5.2.1 Metadata content
          2. 3.2.5.2.2 Flow content
          3. 3.2.5.2.3 Sectioning content
          4. 3.2.5.2.4 Heading content
          5. 3.2.5.2.5 Phrasing content
          6. 3.2.5.2.6 Embedded content
          7. 3.2.5.2.7 Interactive content
          8. 3.2.5.2.8 Palpable content
          9. 3.2.5.2.9 Script-supporting elements
        3. 3.2.5.3 Transparent content models
        4. 3.2.5.4 Paragraphs
      6. 3.2.6 Global attributes
        1. 3.2.6.1 The title attribute
        2. 3.2.6.2 The lang and xml:lang attributes
        3. 3.2.6.3 The translate attribute
        4. 3.2.6.4 The dir attribute
        5. 3.2.6.5 The style attribute
        6. 3.2.6.6 Embedding custom non-visible data with the data-* attributes
      7. 3.2.7 The innerText IDL attribute
      8. 3.2.8 Requirements relating to the bidirectional algorithm
        1. 3.2.8.1 Authoring conformance criteria for bidirectional-algorithm formatting characters
        2. 3.2.8.2 User agent conformance criteria
      9. 3.2.9 Requirements related to ARIA and to platform accessibility APIs
  4. 4 The elements of HTML
    1. 4.1 The document element
      1. 4.1.1 The html element
    2. 4.2 Document metadata
      1. 4.2.1 The head element
      2. 4.2.2 The title element
      3. 4.2.3 The base element
      4. 4.2.4 The link element
        1. 4.2.4.1 Processing the media attribute
        2. 4.2.4.2 Processing the type attribute
        3. 4.2.4.3 Obtaining a resource from a link element
        4. 4.2.4.4 Processing `Link` headers
        5. 4.2.4.5 Providing users with a means to follow hyperlinks created using the link
+  element
      5. 4.2.5 The meta element
        1. 4.2.5.1 Standard metadata names
        2. 4.2.5.2 Other metadata names
        3. 4.2.5.3 Pragma directives
        4. 4.2.5.4 Other pragma directives
        5. 4.2.5.5 Specifying the document's character encoding
      6. 4.2.6 The style element
      7. 4.2.7 Interactions of styling and scripting
    3. 4.3 Sections
      1. 4.3.1 The body element
      2. 4.3.2 The article element
      3. 4.3.3 The section element
      4. 4.3.4 The nav element
      5. 4.3.5 The aside element
      6. 4.3.6 The h1, h2, h3, h4, h5, and
+  h6 elements
      7. 4.3.7 The hgroup element
      8. 4.3.8 The header element
      9. 4.3.9 The footer element
      10. 4.3.10 The address element
      11. 4.3.11 Headings and sections
        1. 4.3.11.1 Creating an outline
        2. 4.3.11.2 Sample outlines
        3. 4.3.11.3 Exposing outlines to users
      12. 4.3.12 Usage summary
        1. 4.3.12.1 Article or section?
    4. 4.4 Grouping content
      1. 4.4.1 The p element
      2. 4.4.2 The hr element
      3. 4.4.3 The pre element
      4. 4.4.4 The blockquote element
      5. 4.4.5 The ol element
      6. 4.4.6 The ul element
      7. 4.4.7 The li element
      8. 4.4.8 The dl element
      9. 4.4.9 The dt element
      10. 4.4.10 The dd element
      11. 4.4.11 The figure element
      12. 4.4.12 The figcaption element
      13. 4.4.13 The main element
      14. 4.4.14 The div element
    5. 4.5 Text-level semantics
      1. 4.5.1 The a element
      2. 4.5.2 The em element
      3. 4.5.3 The strong element
      4. 4.5.4 The small element
      5. 4.5.5 The s element
      6. 4.5.6 The cite element
      7. 4.5.7 The q element
      8. 4.5.8 The dfn element
      9. 4.5.9 The abbr element
      10. 4.5.10 The ruby element
      11. 4.5.11 The rt element
      12. 4.5.12 The rp element
      13. 4.5.13 The data element
      14. 4.5.14 The time element
      15. 4.5.15 The code element
      16. 4.5.16 The var element
      17. 4.5.17 The samp element
      18. 4.5.18 The kbd element
      19. 4.5.19 The sub and sup elements
      20. 4.5.20 The i element
      21. 4.5.21 The b element
      22. 4.5.22 The u element
      23. 4.5.23 The mark element
      24. 4.5.24 The bdi element
      25. 4.5.25 The bdo element
      26. 4.5.26 The span element
      27. 4.5.27 The br element
      28. 4.5.28 The wbr element
      29. 4.5.29 Usage summary
    6. 4.6 Links
      1. 4.6.1 Introduction
      2. 4.6.2 Links created by a and area elements
      3. 4.6.3 API for a and area elements
      4. 4.6.4 Following hyperlinks
      5. 4.6.5 Downloading resources
        1. 4.6.5.1 Hyperlink auditing
      6. 4.6.6 Link types
        1. 4.6.6.1 Link type "alternate"
        2. 4.6.6.2 Link type "author"
        3. 4.6.6.3 Link type "bookmark"
        4. 4.6.6.4 Link type "canonical"
        5. 4.6.6.5 Link type "dns-prefetch"
        6. 4.6.6.6 Link type "external"
        7. 4.6.6.7 Link type "help"
        8. 4.6.6.8 Link type "icon"
        9. 4.6.6.9 Link type "license"
        10. 4.6.6.10 Link type "nofollow"
        11. 4.6.6.11 Link type "noopener"
        12. 4.6.6.12 Link type "noreferrer"
        13. 4.6.6.13 Link type "pingback"
        14. 4.6.6.14 Link type "preconnect"
        15. 4.6.6.15 Link type "prefetch"
        16. 4.6.6.16 Link type "preload"
        17. 4.6.6.17 Link type "prerender"
        18. 4.6.6.18 Link type "search"
        19. 4.6.6.19 Link
+  type "serviceworker"
        20. 4.6.6.20 Link type "stylesheet"
        21. 4.6.6.21 Link type "tag"
        22. 4.6.6.22 Sequential link types
          1. 4.6.6.22.1 Link type "next"
          2. 4.6.6.22.2 Link type "prev"
        23. 4.6.6.23 Other link types
    7. 4.7 Edits
      1. 4.7.1 The ins element
      2. 4.7.2 The del element
      3. 4.7.3 Attributes common to ins and del elements
      4. 4.7.4 Edits and paragraphs
      5. 4.7.5 Edits and lists
      6. 4.7.6 Edits and tables
    8. 4.8 Embedded content
      1. 4.8.1 The picture element
      2. 4.8.2 The source element
      3. 4.8.3 The img element
      4. 4.8.4 Images
        1. 4.8.4.1 Introduction
          1. 4.8.4.1.1 Adaptive images
        2. 4.8.4.2 Attributes common to source and img elements
          1. 4.8.4.2.1 Srcset attributes
          2. 4.8.4.2.2 Sizes attributes
        3. 4.8.4.3 Processing model
          1. 4.8.4.3.1 When to obtain images
          2. 4.8.4.3.2 Reacting to DOM mutations
          3. 4.8.4.3.3 The list of available images
          4. 4.8.4.3.4 Updating the image data
          5. 4.8.4.3.5 Selecting an image source
          6. 4.8.4.3.6 Updating the source set
          7. 4.8.4.3.7 Parsing a srcset attribute
          8. 4.8.4.3.8 Parsing a sizes attribute
          9. 4.8.4.3.9 Normalizing the source densities
          10. 4.8.4.3.10 Reacting to environment changes
        4. 4.8.4.4 Requirements for providing text to act as an alternative for images
          1. 4.8.4.4.1 General guidelines
          2. 4.8.4.4.2 A link or button containing nothing but the image
          3. 4.8.4.4.3 A phrase or paragraph with an alternative graphical representation: charts, diagrams, graphs, maps, illustrations
          4. 4.8.4.4.4 A short phrase or label with an alternative graphical representation: icons, logos
          5. 4.8.4.4.5 Text that has been rendered to a graphic for typographical effect
          6. 4.8.4.4.6 A graphical representation of some of the surrounding text
          7. 4.8.4.4.7 Ancillary images
          8. 4.8.4.4.8 A purely decorative image that doesn't add any information
          9. 4.8.4.4.9 A group of images that form a single larger picture with no links
          10. 4.8.4.4.10 A group of images that form a single larger picture with links
          11. 4.8.4.4.11 A key part of the content
          12. 4.8.4.4.12 An image not intended for the user
          13. 4.8.4.4.13 An image in an e-mail or private document intended for a specific person who is known to be able to view images
          14. 4.8.4.4.14 Guidance for markup generators
          15. 4.8.4.4.15 Guidance for conformance checkers
      5. 4.8.5 The iframe element
      6. 4.8.6 The embed element
      7. 4.8.7 The object element
      8. 4.8.8 The param element
      9. 4.8.9 The video element
      10. 4.8.10 The audio element
      11. 4.8.11 The track element
      12. 4.8.12 Media elements
        1. 4.8.12.1 Error codes
        2. 4.8.12.2 Location of the media resource
        3. 4.8.12.3 MIME types
        4. 4.8.12.4 Network states
        5. 4.8.12.5 Loading the media resource
        6. 4.8.12.6 Offsets into the media resource
        7. 4.8.12.7 Ready states
        8. 4.8.12.8 Playing the media resource
        9. 4.8.12.9 Seeking
        10. 4.8.12.10 Media resources with multiple media tracks
          1. 4.8.12.10.1 AudioTrackList and VideoTrackList objects
          2. 4.8.12.10.2 Selecting specific audio and video tracks declaratively
        11. 4.8.12.11 Timed text tracks
          1. 4.8.12.11.1 Text track model
          2. 4.8.12.11.2 Sourcing in-band text tracks
          3. 4.8.12.11.3 Sourcing out-of-band text tracks
          4. 4.8.12.11.4 Guidelines for exposing cues in various formats as text track cues
          5. 4.8.12.11.5 Text track API
          6. 4.8.12.11.6 Text tracks describing chapters
          7. 4.8.12.11.7 Event handlers for objects of the text track APIs
          8. 4.8.12.11.8 Best practices for metadata text tracks
        12. 4.8.12.12 Identifying a track kind through a URL
        13. 4.8.12.13 User interface
        14. 4.8.12.14 Time ranges
        15. 4.8.12.15 The TrackEvent interface
        16. 4.8.12.16 Event summary
        17. 4.8.12.17 Security and privacy considerations
        18. 4.8.12.18 Best practices for authors using media elements
        19. 4.8.12.19 Best practices for implementors of media elements
      13. 4.8.13 The map element
      14. 4.8.14 The area element
      15. 4.8.15 Image maps
        1. 4.8.15.1 Authoring
        2. 4.8.15.2 Processing model
      16. 4.8.16 MathML
      17. 4.8.17 SVG
      18. 4.8.18 Dimension attributes
    9. 4.9 Tabular data
      1. 4.9.1 The table element
        1. 4.9.1.1 Techniques for describing tables
        2. 4.9.1.2 Techniques for table design
      2. 4.9.2 The caption element
      3. 4.9.3 The colgroup element
      4. 4.9.4 The col element
      5. 4.9.5 The tbody element
      6. 4.9.6 The thead element
      7. 4.9.7 The tfoot element
      8. 4.9.8 The tr element
      9. 4.9.9 The td element
      10. 4.9.10 The th element
      11. 4.9.11 Attributes common to td and th elements
      12. 4.9.12 Processing model
        1. 4.9.12.1 Forming a table
        2. 4.9.12.2 Forming relationships between data cells and header cells
      13. 4.9.13 Examples
    10. 4.10 Forms
      1. 4.10.1 Introduction
        1. 4.10.1.1 Writing a form's user interface
        2. 4.10.1.2 Implementing the server-side processing for a form
        3. 4.10.1.3 Configuring a form to communicate with a server
        4. 4.10.1.4 Client-side form validation
        5. 4.10.1.5 Enabling client-side automatic filling of form controls
        6. 4.10.1.6 Improving the user experience on mobile devices
        7. 4.10.1.7 The difference between the field type, the autofill field name, and the input modality
        8. 4.10.1.8 Date, time, and number formats
      2. 4.10.2 Categories
      3. 4.10.3 The form element
      4. 4.10.4 The label element
      5. 4.10.5 The input element
        1. 4.10.5.1 States of the type attribute
          1. 4.10.5.1.1 Hidden state (type=hidden)
          2. 4.10.5.1.2 Text (type=text) state and Search state (type=search)
          3. 4.10.5.1.3 Telephone state (type=tel)
          4. 4.10.5.1.4 URL state (type=url)
          5. 4.10.5.1.5 E-mail state (type=email)
          6. 4.10.5.1.6 Password state (type=password)
          7. 4.10.5.1.7 Date state (type=date)
          8. 4.10.5.1.8 Month state (type=month)
          9. 4.10.5.1.9 Week state (type=week)
          10. 4.10.5.1.10 Time state (type=time)
          11. 4.10.5.1.11 Local Date and Time state (type=datetime-local)
          12. 4.10.5.1.12 Number state (type=number)
          13. 4.10.5.1.13 Range state (type=range)
          14. 4.10.5.1.14 Color state (type=color)
          15. 4.10.5.1.15 Checkbox state (type=checkbox)
          16. 4.10.5.1.16 Radio Button state (type=radio)
          17. 4.10.5.1.17 File Upload state (type=file)
          18. 4.10.5.1.18 Submit Button state (type=submit)
          19. 4.10.5.1.19 Image Button state (type=image)
          20. 4.10.5.1.20 Reset Button state (type=reset)
          21. 4.10.5.1.21 Button state (type=button)
        2. 4.10.5.2 Implementation notes regarding localization of form controls
        3. 4.10.5.3 Common input element attributes
          1. 4.10.5.3.1 The maxlength and minlength attributes
          2. 4.10.5.3.2 The size attribute
          3. 4.10.5.3.3 The readonly attribute
          4. 4.10.5.3.4 The required attribute
          5. 4.10.5.3.5 The multiple attribute
          6. 4.10.5.3.6 The pattern attribute
          7. 4.10.5.3.7 The min and max attributes
          8. 4.10.5.3.8 The step attribute
          9. 4.10.5.3.9 The list attribute
          10. 4.10.5.3.10 The placeholder attribute
        4. 4.10.5.4 Common input element APIs
        5. 4.10.5.5 Common event behaviors
      6. 4.10.6 The button element
      7. 4.10.7 The select element
      8. 4.10.8 The datalist element
      9. 4.10.9 The optgroup element
      10. 4.10.10 The option element
      11. 4.10.11 The textarea element
      12. 4.10.12 The output element
      13. 4.10.13 The progress element
      14. 4.10.14 The meter element
      15. 4.10.15 The fieldset element
      16. 4.10.16 The legend element
      17. 4.10.17 Form control infrastructure
        1. 4.10.17.1 A form control's value
        2. 4.10.17.2 Mutability
        3. 4.10.17.3 Association of controls and forms
      18. 4.10.18 Attributes common to form controls
        1. 4.10.18.1 Naming form controls: the name attribute
        2. 4.10.18.2 Submitting element directionality: the dirname attribute
        3. 4.10.18.3 Limiting user input length: the maxlength attribute
        4. 4.10.18.4 Setting minimum input length requirements: the minlength attribute
        5. 4.10.18.5 Enabling and disabling form controls: the disabled attribute
        6. 4.10.18.6 Form submission
          1. 4.10.18.6.1 Autofocusing a form control: the autofocus attribute
        7. 4.10.18.7 Input modalities: the inputmode attribute
        8. 4.10.18.8 Autofill
          1. 4.10.18.8.1 Autofilling form controls: the autocomplete attribute
          2. 4.10.18.8.2 Processing model
      19. 4.10.19 APIs for the text control selections
      20. 4.10.20 Constraints
        1. 4.10.20.1 Definitions
        2. 4.10.20.2 Constraint validation
        3. 4.10.20.3 The constraint validation API
        4. 4.10.20.4 Security
      21. 4.10.21 Form submission
        1. 4.10.21.1 Introduction
        2. 4.10.21.2 Implicit submission
        3. 4.10.21.3 Form submission algorithm
        4. 4.10.21.4 Constructing the form data set
        5. 4.10.21.5 Selecting a form submission encoding
        6. 4.10.21.6 URL-encoded form data
        7. 4.10.21.7 Multipart form data
        8. 4.10.21.8 Plain text form data
      22. 4.10.22 Resetting a form
    11. 4.11 Interactive elements
      1. 4.11.1 The details element
      2. 4.11.2 The summary element
      3. 4.11.3 The menu element
      4. 4.11.4 The menuitem element
      5. 4.11.5 Context menus
        1. 4.11.5.1 Declaring a context menu
        2. 4.11.5.2 Processing model
        3. 4.11.5.3 The RelatedEvent interfaces
      6. 4.11.6 Commands
        1. 4.11.6.1 Facets
        2. 4.11.6.2 Using the a element to define a command
        3. 4.11.6.3 Using the button element to define a command
        4. 4.11.6.4 Using the input element to define a command
        5. 4.11.6.5 Using the option element to define a command
        6. 4.11.6.6 Using the menuitem element to define a
+  command
        7. 4.11.6.7 Using the accesskey attribute
+  on a label element to define a command
        8. 4.11.6.8 Using the accesskey attribute
+  on a legend element to define a command
        9. 4.11.6.9 Using the accesskey
+  attribute to define a command on other elements
      7. 4.11.7 The dialog element
    12. 4.12 Scripting
      1. 4.12.1 The script element
        1. 4.12.1.1 Processing model
        2. 4.12.1.2 Scripting languages
        3. 4.12.1.3 Restrictions for contents of script elements
        4. 4.12.1.4 Inline documentation for external scripts
        5. 4.12.1.5 Interaction of script elements and XSLT
      2. 4.12.2 The noscript element
      3. 4.12.3 The template element
        1. 4.12.3.1 Interaction of template elements with XSLT and XPath
      4. 4.12.4 The slot element
      5. 4.12.5 The canvas element
        1. 4.12.5.1 The 2D rendering context
          1. 4.12.5.1.1 Implementation notes
          2. 4.12.5.1.2 The canvas state
          3. 4.12.5.1.3 Line styles
          4. 4.12.5.1.4 Text styles
          5. 4.12.5.1.5 Building paths
          6. 4.12.5.1.6 Path2D objects
          7. 4.12.5.1.7 Transformations
          8. 4.12.5.1.8 Image sources for 2D rendering contexts
          9. 4.12.5.1.9 Fill and stroke styles
          10. 4.12.5.1.10 Drawing rectangles to the bitmap
          11. 4.12.5.1.11 Drawing text to the bitmap
          12. 4.12.5.1.12 Drawing paths to the canvas
          13. 4.12.5.1.13 Drawing focus rings and scrolling paths into view
          14. 4.12.5.1.14 Drawing images
          15. 4.12.5.1.15 Pixel manipulation
          16. 4.12.5.1.16 Compositing
          17. 4.12.5.1.17 Image smoothing
          18. 4.12.5.1.18 Shadows
          19. 4.12.5.1.19 Filters
          20. 4.12.5.1.20 Working with externally-defined SVG filters
          21. 4.12.5.1.21 Drawing model
          22. 4.12.5.1.22 Best practices
          23. 4.12.5.1.23 Examples
        2. 4.12.5.2 The ImageBitmap rendering context
          1. 4.12.5.2.1 Introduction
          2. 4.12.5.2.2 The ImageBitmapRenderingContext interface
        3. 4.12.5.3 The OffscreenCanvas interface
          1. 4.12.5.3.1 The offscreen 2D rendering context
        4. 4.12.5.4 Color spaces and color correction
        5. 4.12.5.5 Serializing bitmaps to a file
        6. 4.12.5.6 Security with canvas elements
    13. 4.13 Custom elements
      1. 4.13.1 Introduction
        1. 4.13.1.1 Creating an autonomous custom element
        2. 4.13.1.2 Creating a customized built-in element
        3. 4.13.1.3 Drawbacks of autonomous custom elements
        4. 4.13.1.4 Upgrading elements after their creation
      2. 4.13.2 Requirements for custom element constructors
      3. 4.13.3 Core concepts
      4. 4.13.4 The CustomElementRegistry interface
      5. 4.13.5 Upgrades
      6. 4.13.6 Custom element reactions
    14. 4.14 Common idioms without dedicated elements
      1. 4.14.1 The main part of the content
      2. 4.14.2 Bread crumb navigation
      3. 4.14.3 Tag clouds
      4. 4.14.4 Conversations
      5. 4.14.5 Footnotes
    15. 4.15 Disabled elements
    16. 4.16 Matching HTML elements using selectors and CSS
      1. 4.16.1 Case-sensitivity of the CSS 'attr()' function
      2. 4.16.2 Case-sensitivity of selectors
      3. 4.16.3 Pseudo-classes
  5. 5 Microdata
    1. 5.1 Introduction
      1. 5.1.1 Overview
      2. 5.1.2 The basic syntax
      3. 5.1.3 Typed items
      4. 5.1.4 Global identifiers for items
      5. 5.1.5 Selecting names when defining vocabularies
    2. 5.2 Encoding microdata
      1. 5.2.1 The microdata model
      2. 5.2.2 Items
      3. 5.2.3 Names: the itemprop attribute
      4. 5.2.4 Values
      5. 5.2.5 Associating names with items
      6. 5.2.6 Microdata and other namespaces
    3. 5.3 Sample microdata vocabularies
      1. 5.3.1 vCard
        1. 5.3.1.1 Conversion to vCard
        2. 5.3.1.2 Examples
      2. 5.3.2 vEvent
        1. 5.3.2.1 Conversion to iCalendar
        2. 5.3.2.2 Examples
      3. 5.3.3 Licensing works
        1. 5.3.3.1 Examples
    4. 5.4 Converting HTML to other formats
      1. 5.4.1 JSON
  6. 6 User interaction
    1. 6.1 The hidden attribute
    2. 6.2 Inert subtrees
    3. 6.3 Activation
    4. 6.4 Focus
      1. 6.4.1 Introduction
      2. 6.4.2 Data model
      3. 6.4.3 The tabindex attribute
      4. 6.4.4 Processing model
      5. 6.4.5 Sequential focus navigation
      6. 6.4.6 Focus management APIs
    5. 6.5 Assigning keyboard shortcuts
      1. 6.5.1 Introduction
      2. 6.5.2 The accesskey attribute
      3. 6.5.3 Processing
+  model
    6. 6.6 Editing
      1. 6.6.1 Making document regions editable: The contenteditable content attribute
      2. 6.6.2 Making entire documents editable: the designMode
+  IDL attribute
      3. 6.6.3 Best practices for in-page editors
      4. 6.6.4 Editing APIs
      5. 6.6.5 Spelling and grammar checking
    7. 6.7 Drag and drop
      1. 6.7.1 Introduction
      2. 6.7.2 The drag data store
      3. 6.7.3 The DataTransfer interface
        1. 6.7.3.1 The DataTransferItemList interface
        2. 6.7.3.2 The DataTransferItem interface
      4. 6.7.4 The DragEvent interface
      5. 6.7.5 Processing model
      6. 6.7.6 Events summary
      7. 6.7.7 The draggable attribute
      8. 6.7.8 Security risks in the drag-and-drop model
  7. 7 Loading Web pages
    1. 7.1 Browsing contexts
      1. 7.1.1 Nested browsing contexts
        1. 7.1.1.1 Navigating nested browsing contexts in the DOM
      2. 7.1.2 Auxiliary browsing contexts
        1. 7.1.2.1 Navigating auxiliary browsing contexts in the DOM
      3. 7.1.3 Security
      4. 7.1.4 Groupings of browsing contexts
      5. 7.1.5 Browsing context names
    2. 7.2 Security infrastructure for Window,
+  WindowProxy, and Location objects
      1. 7.2.1 Integration with IDL
      2. 7.2.2 Shared internal slot: [[CrossOriginPropertyDescriptorMap]]
      3. 7.2.3 Shared abstract operations
        1. 7.2.3.1 CrossOriginProperties ( O )
        2. 7.2.3.2 IsPlatformObjectSameOrigin ( O )
        3. 7.2.3.3 CrossOriginGetOwnPropertyHelper ( O, P )
        4. 7.2.3.4 CrossOriginGet ( O, P, Receiver )
        5. 7.2.3.5 CrossOriginSet ( O, P, V,
+  Receiver )
        6. 7.2.3.6 CrossOriginOwnPropertyKeys ( O )
    3. 7.3 The Window object
      1. 7.3.1 APIs for creating and navigating browsing contexts by name
      2. 7.3.2 Accessing other browsing contexts
      3. 7.3.3 Named access on the Window object
      4. 7.3.4 Garbage collection and browsing contexts
      5. 7.3.5 Closing browsing contexts
      6. 7.3.6 Browser interface elements
      7. 7.3.7 Script settings for Window objects
    4. 7.4 The WindowProxy exotic object
      1. 7.4.1 [[GetPrototypeOf]] ( )
      2. 7.4.2 [[SetPrototypeOf]] ( V )
      3. 7.4.3 [[IsExtensible]] ( )
      4. 7.4.4 [[PreventExtensions]] ( )
      5. 7.4.5 [[GetOwnProperty]] ( P )
      6. 7.4.6 [[DefineOwnProperty]] ( P, Desc
+  )
      7. 7.4.7 [[Get]] ( P, Receiver )
      8. 7.4.8 [[Set]] ( P, V, Receiver )
      9. 7.4.9 [[Delete]] ( P )
      10. 7.4.10 [[OwnPropertyKeys]] ( )
    5. 7.5 Origin
      1. 7.5.1 Relaxing the same-origin restriction
    6. 7.6 Sandboxing
    7. 7.7 Session history and navigation
      1. 7.7.1 The session history of browsing contexts
      2. 7.7.2 The History interface
      3. 7.7.3 Implementation notes for session history
      4. 7.7.4 The Location interface
        1. 7.7.4.1 [[GetPrototypeOf]] ( )
        2. 7.7.4.2 [[SetPrototypeOf]] ( V )
        3. 7.7.4.3 [[IsExtensible]] ( )
        4. 7.7.4.4 [[PreventExtensions]] ( )
        5. 7.7.4.5 [[GetOwnProperty]] ( P )
        6. 7.7.4.6 [[DefineOwnProperty]] ( P, Desc )
        7. 7.7.4.7 [[Get]] ( P, Receiver )
        8. 7.7.4.8 [[Set]] ( P, V, Receiver )
        9. 7.7.4.9 [[Delete]] ( P )
        10. 7.7.4.10 [[OwnPropertyKeys]] ( )
    8. 7.8 Browsing the Web
      1. 7.8.1 Navigating across documents
      2. 7.8.2 Page load processing model for HTML files
      3. 7.8.3 Page load processing model for XML files
      4. 7.8.4 Page load processing model for text files
      5. 7.8.5 Page load processing model for multipart/x-mixed-replace resources
      6. 7.8.6 Page load processing model for media
      7. 7.8.7 Page load processing model for content that uses plugins
      8. 7.8.8 Page load processing model for inline
+  content that doesn't have a DOM
      9. 7.8.9 Navigating to a fragment
      10. 7.8.10 History traversal
        1. 7.8.10.1 Persisted user state restoration
        2. 7.8.10.2 The PopStateEvent interface
        3. 7.8.10.3 The HashChangeEvent interface
        4. 7.8.10.4 The PageTransitionEvent interface
      11. 7.8.11 Unloading documents
        1. 7.8.11.1 The BeforeUnloadEvent interface
      12. 7.8.12 Aborting a document load
    9. 7.9 Offline Web applications
      1. 7.9.1 Introduction
        1. 7.9.1.1 Supporting offline caching for legacy applications
        2. 7.9.1.2 Event summary
      2. 7.9.2 Application caches
      3. 7.9.3 The cache manifest syntax
        1. 7.9.3.1 Some sample manifests
        2. 7.9.3.2 Writing cache manifests
        3. 7.9.3.3 Parsing cache manifests
      4. 7.9.4 Downloading or updating an application cache
      5. 7.9.5 The application cache selection algorithm
      6. 7.9.6 Changes to the networking model
      7. 7.9.7 Expiring application caches
      8. 7.9.8 Disk space
      9. 7.9.9 Security concerns with offline applications caches
      10. 7.9.10 Application cache API
      11. 7.9.11 Browser state
  8. 8 Web application APIs
    1. 8.1 Scripting
      1. 8.1.1 Introduction
      2. 8.1.2 Enabling and disabling scripting
      3. 8.1.3 Processing model
        1. 8.1.3.1 Definitions
        2. 8.1.3.2 Fetching scripts
        3. 8.1.3.3 Creating scripts
        4. 8.1.3.4 Calling scripts
        5. 8.1.3.5 Realms, settings objects, and global objects
          1. 8.1.3.5.1 Entry
          2. 8.1.3.5.2 Incumbent
          3. 8.1.3.5.3 Current
          4. 8.1.3.5.4 Relevant
        6. 8.1.3.6 Killing scripts
        7. 8.1.3.7 Integration with the JavaScript job queue
          1. 8.1.3.7.1 EnqueueJob(queueName, job, arguments)
        8. 8.1.3.8 Integration with the JavaScript module system
          1. 8.1.3.8.1 HostResolveImportedModule(referencingModule, specifier)
        9. 8.1.3.9 Integration with the JavaScript agent formalism
        10. 8.1.3.10 Integration with the JavaScript agent cluster formalism
        11. 8.1.3.11 Runtime script errors
          1. 8.1.3.11.1 Runtime script errors in documents
          2. 8.1.3.11.2 The ErrorEvent interface
        12. 8.1.3.12 Unhandled promise rejections
          1. 8.1.3.12.1 HostPromiseRejectionTracker(promise, operation)
          2. 8.1.3.12.2 The PromiseRejectionEvent interface
        13. 8.1.3.13 HostEnsureCanCompileStrings(callerRealm, calleeRealm)
      4. 8.1.4 Event loops
        1. 8.1.4.1 Definitions
        2. 8.1.4.2 Processing model
        3. 8.1.4.3 Generic task sources
      5. 8.1.5 Events
        1. 8.1.5.1 Event handlers
        2. 8.1.5.2 Event handlers on elements, Document objects, and Window objects
          1. 8.1.5.2.1 IDL definitions
        3. 8.1.5.3 Event firing
    2. 8.2 The WindowOrWorkerGlobalScope mixin
    3. 8.3 Base64 utility methods
    4. 8.4 Dynamic markup insertion
      1. 8.4.1 Opening the input stream
      2. 8.4.2 Closing the input stream
      3. 8.4.3 document.write()
      4. 8.4.4 document.writeln()
    5. 8.5 Timers
    6. 8.6 User prompts
      1. 8.6.1 Simple dialogs
      2. 8.6.2 Printing
    7. 8.7 System state and capabilities
      1. 8.7.1 The Navigator object
        1. 8.7.1.1 Client identification
        2. 8.7.1.2 Language preferences
        3. 8.7.1.3 Custom scheme and content handlers: the registerProtocolHandler() and registerContentHandler() methods
          1. 8.7.1.3.1 Security and privacy
          2. 8.7.1.3.2 Sample user interface
        4. 8.7.1.4 Cookies
        5. 8.7.1.5 Plugins
    8. 8.8 Images
    9. 8.9 Animation Frames
  9. 9 Communication
    1. 9.1 The MessageEvent interfaces
    2. 9.2 Server-sent events
      1. 9.2.1 Introduction
      2. 9.2.2 The EventSource interface
      3. 9.2.3 Processing model
      4. 9.2.4 Parsing an event stream
      5. 9.2.5 Interpreting an event stream
      6. 9.2.6 Authoring notes
      7. 9.2.7 Connectionless push and other features
      8. 9.2.8 Garbage collection
      9. 9.2.9 Implementation advice
    3. 9.3 Web sockets
      1. 9.3.1 Introduction
      2. 9.3.2 The WebSocket interface
      3. 9.3.3 Feedback from the protocol
      4. 9.3.4 Ping and Pong frames
      5. 9.3.5 The CloseEvent interfaces
      6. 9.3.6 Garbage collection
    4. 9.4 Cross-document messaging
      1. 9.4.1 Introduction
      2. 9.4.2 Security
        1. 9.4.2.1 Authors
        2. 9.4.2.2 User agents
      3. 9.4.3 Posting messages
    5. 9.5 Channel messaging
      1. 9.5.1 Introduction
        1. 9.5.1.1 Examples
        2. 9.5.1.2 Ports as the basis of an object-capability model on the Web
        3. 9.5.1.3 Ports as the basis of abstracting out service implementations
      2. 9.5.2 Message channels
      3. 9.5.3 Message ports
      4. 9.5.4 Broadcasting to many ports
      5. 9.5.5 Ports and garbage collection
    6. 9.6 Broadcasting to other browsing contexts
  10. 10 Web workers
    1. 10.1 Introduction
      1. 10.1.1 Scope
      2. 10.1.2 Examples
        1. 10.1.2.1 A background number-crunching worker
        2. 10.1.2.2 Worker used for background I/O
        3. 10.1.2.3 Using a JavaScript module as a worker
        4. 10.1.2.4 Shared workers introduction
        5. 10.1.2.5 Shared state using a shared worker
        6. 10.1.2.6 Delegation
        7. 10.1.2.7 Providing libraries
      3. 10.1.3 Tutorials
        1. 10.1.3.1 Creating a dedicated worker
        2. 10.1.3.2 Communicating with a dedicated worker
        3. 10.1.3.3 Shared workers
    2. 10.2 Infrastructure
      1. 10.2.1 The global scope
        1. 10.2.1.1 The WorkerGlobalScope common interface
        2. 10.2.1.2 Dedicated workers and the DedicatedWorkerGlobalScope interface
        3. 10.2.1.3 Shared workers and the SharedWorkerGlobalScope interface
      2. 10.2.2 The event loop
      3. 10.2.3 The worker's lifetime
      4. 10.2.4 Processing model
      5. 10.2.5 Runtime script errors
      6. 10.2.6 Creating workers
        1. 10.2.6.1 The AbstractWorker abstract interface
        2. 10.2.6.2 Script settings for workers
        3. 10.2.6.3 Dedicated workers and the Worker interface
        4. 10.2.6.4 Shared workers and the SharedWorker interface
      7. 10.2.7 Concurrent hardware capabilities
    3. 10.3 APIs available to workers
      1. 10.3.1 Importing scripts and libraries
      2. 10.3.2 The WorkerNavigator object
      3. 10.3.3 Worker locations
  11. 11 Web storage
    1. 11.1 Introduction
    2. 11.2 The API
      1. 11.2.1 The Storage interface
      2. 11.2.2 The sessionStorage attribute
      3. 11.2.3 The localStorage attribute
      4. 11.2.4 The storage event
        1. 11.2.4.1 The StorageEvent interface
    3. 11.3 Disk space
    4. 11.4 Privacy
      1. 11.4.1 User tracking
      2. 11.4.2 Sensitivity of data
    5. 11.5 Security
      1. 11.5.1 DNS spoofing attacks
      2. 11.5.2 Cross-directory attacks
      3. 11.5.3 Implementation risks
  12. 12 The HTML syntax
    1. 12.1 Writing HTML documents
      1. 12.1.1 The DOCTYPE
      2. 12.1.2 Elements
        1. 12.1.2.1 Start tags
        2. 12.1.2.2 End tags
        3. 12.1.2.3 Attributes
        4. 12.1.2.4 Optional tags
        5. 12.1.2.5 Restrictions on content models
        6. 12.1.2.6 Restrictions on the contents of raw text and escapable raw text elements
      3. 12.1.3 Text
        1. 12.1.3.1 Newlines
      4. 12.1.4 Character references
      5. 12.1.5 CDATA sections
      6. 12.1.6 Comments
    2. 12.2 Parsing HTML documents
      1. 12.2.1 Overview of the parsing model
      2. 12.2.2 The input byte stream
        1. 12.2.2.1 Parsing with a known character encoding
        2. 12.2.2.2 Determining the character encoding
        3. 12.2.2.3 Character encodings
        4. 12.2.2.4 Changing the encoding while parsing
        5. 12.2.2.5 Preprocessing the input stream
      3. 12.2.3 Parse state
        1. 12.2.3.1 The insertion mode
        2. 12.2.3.2 The stack of open elements
        3. 12.2.3.3 The list of active formatting elements
        4. 12.2.3.4 The element pointers
        5. 12.2.3.5 Other parsing state flags
      4. 12.2.4 Tokenization
        1. 12.2.4.1 Data state
        2. 12.2.4.2 RCDATA state
        3. 12.2.4.3 RAWTEXT state
        4. 12.2.4.4 Script data state
        5. 12.2.4.5 PLAINTEXT state
        6. 12.2.4.6 Tag open state
        7. 12.2.4.7 End tag open state
        8. 12.2.4.8 Tag name state
        9. 12.2.4.9 RCDATA less-than sign state
        10. 12.2.4.10 RCDATA end tag open state
        11. 12.2.4.11 RCDATA end tag name state
        12. 12.2.4.12 RAWTEXT less-than sign state
        13. 12.2.4.13 RAWTEXT end tag open state
        14. 12.2.4.14 RAWTEXT end tag name state
        15. 12.2.4.15 Script data less-than sign state
        16. 12.2.4.16 Script data end tag open state
        17. 12.2.4.17 Script data end tag name state
        18. 12.2.4.18 Script data escape start state
        19. 12.2.4.19 Script data escape start dash state
        20. 12.2.4.20 Script data escaped state
        21. 12.2.4.21 Script data escaped dash state
        22. 12.2.4.22 Script data escaped dash dash state
        23. 12.2.4.23 Script data escaped less-than sign state
        24. 12.2.4.24 Script data escaped end tag open state
        25. 12.2.4.25 Script data escaped end tag name state
        26. 12.2.4.26 Script data double escape start state
        27. 12.2.4.27 Script data double escaped state
        28. 12.2.4.28 Script data double escaped dash state
        29. 12.2.4.29 Script data double escaped dash dash state
        30. 12.2.4.30 Script data double escaped less-than sign state
        31. 12.2.4.31 Script data double escape end state
        32. 12.2.4.32 Before attribute name state
        33. 12.2.4.33 Attribute name state
        34. 12.2.4.34 After attribute name state
        35. 12.2.4.35 Before attribute value state
        36. 12.2.4.36 Attribute value (double-quoted) state
        37. 12.2.4.37 Attribute value (single-quoted) state
        38. 12.2.4.38 Attribute value (unquoted) state
        39. 12.2.4.39 After attribute value (quoted) state
        40. 12.2.4.40 Self-closing start tag state
        41. 12.2.4.41 Bogus comment state
        42. 12.2.4.42 Markup declaration open state
        43. 12.2.4.43 Comment start state
        44. 12.2.4.44 Comment start dash state
        45. 12.2.4.45 Comment state
        46. 12.2.4.46 Comment less-than sign state
        47. 12.2.4.47 Comment less-than sign bang state
        48. 12.2.4.48 Comment less-than sign bang dash state
        49. 12.2.4.49 Comment less-than sign bang dash dash state
        50. 12.2.4.50 Comment end dash state
        51. 12.2.4.51 Comment end state
        52. 12.2.4.52 Comment end bang state
        53. 12.2.4.53 DOCTYPE state
        54. 12.2.4.54 Before DOCTYPE name state
        55. 12.2.4.55 DOCTYPE name state
        56. 12.2.4.56 After DOCTYPE name state
        57. 12.2.4.57 After DOCTYPE public keyword state
        58. 12.2.4.58 Before DOCTYPE public identifier state
        59. 12.2.4.59 DOCTYPE public identifier (double-quoted) state
        60. 12.2.4.60 DOCTYPE public identifier (single-quoted) state
        61. 12.2.4.61 After DOCTYPE public identifier state
        62. 12.2.4.62 Between DOCTYPE public and system identifiers state
        63. 12.2.4.63 After DOCTYPE system keyword state
        64. 12.2.4.64 Before DOCTYPE system identifier state
        65. 12.2.4.65 DOCTYPE system identifier (double-quoted) state
        66. 12.2.4.66 DOCTYPE system identifier (single-quoted) state
        67. 12.2.4.67 After DOCTYPE system identifier state
        68. 12.2.4.68 Bogus DOCTYPE state
        69. 12.2.4.69 CDATA section state
        70. 12.2.4.70 CDATA section bracket state
        71. 12.2.4.71 CDATA section end state
        72. 12.2.4.72 Character reference state
        73. 12.2.4.73 Named character reference state
        74. 12.2.4.74 Numeric character reference state
        75. 12.2.4.75 Hexademical character reference start state
        76. 12.2.4.76 Decimal character reference start state
        77. 12.2.4.77 Hexademical character reference state
        78. 12.2.4.78 Decimal character reference state
        79. 12.2.4.79 Numeric character reference end state
        80. 12.2.4.80 Character reference end state
      5. 12.2.5 Tree construction
        1. 12.2.5.1 Creating and inserting nodes
        2. 12.2.5.2 Parsing elements that contain only text
        3. 12.2.5.3 Closing elements that have implied end tags
        4. 12.2.5.4 The rules for parsing tokens in HTML content
          1. 12.2.5.4.1 The "initial" insertion mode
          2. 12.2.5.4.2 The "before html" insertion mode
          3. 12.2.5.4.3 The "before head" insertion mode
          4. 12.2.5.4.4 The "in head" insertion mode
          5. 12.2.5.4.5 The "in head noscript" insertion mode
          6. 12.2.5.4.6 The "after head" insertion mode
          7. 12.2.5.4.7 The "in body" insertion mode
          8. 12.2.5.4.8 The "text" insertion mode
          9. 12.2.5.4.9 The "in table" insertion mode
          10. 12.2.5.4.10 The "in table text" insertion mode
          11. 12.2.5.4.11 The "in caption" insertion mode
          12. 12.2.5.4.12 The "in column group" insertion mode
          13. 12.2.5.4.13 The "in table body" insertion mode
          14. 12.2.5.4.14 The "in row" insertion mode
          15. 12.2.5.4.15 The "in cell" insertion mode
          16. 12.2.5.4.16 The "in select" insertion mode
          17. 12.2.5.4.17 The "in select in table" insertion mode
          18. 12.2.5.4.18 The "in template" insertion mode
          19. 12.2.5.4.19 The "after body" insertion mode
          20. 12.2.5.4.20 The "in frameset" insertion mode
          21. 12.2.5.4.21 The "after frameset" insertion mode
          22. 12.2.5.4.22 The "after after body" insertion mode
          23. 12.2.5.4.23 The "after after frameset" insertion mode
        5. 12.2.5.5 The rules for parsing tokens in foreign content
      6. 12.2.6 The end
      7. 12.2.7 Coercing an HTML DOM into an infoset
      8. 12.2.8 An introduction to error handling and strange cases in the parser
        1. 12.2.8.1 Misnested tags: <b><i></b></i>
        2. 12.2.8.2 Misnested tags: <b><p></b></p>
        3. 12.2.8.3 Unexpected markup in tables
        4. 12.2.8.4 Scripts that modify the page as it is being parsed
        5. 12.2.8.5 The execution of scripts that are moving across multiple documents
        6. 12.2.8.6 Unclosed formatting elements
    3. 12.3 Serializing HTML fragments
    4. 12.4 Parsing HTML fragments
    5. 12.5 Named character references
  13. 13 The XML syntax
    1. 13.1 Writing documents in the XML syntax
    2. 13.2 Parsing XML documents
    3. 13.3 Serializing XML fragments
    4. 13.4 Parsing XML fragments
  14. 14 Rendering
    1. 14.1 Introduction
    2. 14.2 The CSS user agent style sheet and presentational hints
    3. 14.3 Non-replaced elements
      1. 14.3.1 Hidden elements
      2. 14.3.2 The page
      3. 14.3.3 Flow content
      4. 14.3.4 Phrasing content
      5. 14.3.5 Bidirectional text
      6. 14.3.6 Quotes
      7. 14.3.7 Sections and headings
      8. 14.3.8 Lists
      9. 14.3.9 Tables
      10. 14.3.10 Margin collapsing quirks
      11. 14.3.11 Form controls
      12. 14.3.12 The hr element
      13. 14.3.13 The fieldset and legend elements
    4. 14.4 Replaced elements
      1. 14.4.1 Embedded content
      2. 14.4.2 Images
      3. 14.4.3 Attributes for embedded content and images
      4. 14.4.4 Image maps
    5. 14.5 Widgets
      1. 14.5.1 Introduction
      2. 14.5.2 The button element
      3. 14.5.3 The details and summary elements
      4. 14.5.4 The input element as a text entry widget
      5. 14.5.5 The input element as domain-specific widgets
      6. 14.5.6 The input element as a range control
      7. 14.5.7 The input element as a color
+  well
      8. 14.5.8 The input element as a checkbox and radio button widgets
      9. 14.5.9 The input element as a file upload control
      10. 14.5.10 The input element as a button
      11. 14.5.11 The marquee element
      12. 14.5.12 The meter element
      13. 14.5.13 The progress element
      14. 14.5.14 The select element
      15. 14.5.15 The textarea element
    6. 14.6 Frames and framesets
    7. 14.7 Interactive media
      1. 14.7.1 Links, forms, and navigation
      2. 14.7.2 The title attribute
      3. 14.7.3 Editing hosts
      4. 14.7.4 Text rendered in native user interfaces
    8. 14.8 Print media
    9. 14.9 Unstyled XML documents
  15. 15 Obsolete features
    1. 15.1 Obsolete but conforming features
      1. 15.1.1 Warnings for obsolete but conforming features
    2. 15.2 Non-conforming features
    3. 15.3 Requirements for implementations
      1. 15.3.1 The applet element
      2. 15.3.2 The marquee element
      3. 15.3.3 Frames
      4. 15.3.4 Other elements, attributes and APIs
  16. 16 IANA considerations
    1. 16.1 text/html
    2. 16.2 multipart/x-mixed-replace
    3. 16.3 application/xhtml+xml
    4. 16.4 text/cache-manifest
    5. 16.5 text/ping
    6. 16.6 application/microdata+json
    7. 16.7 text/event-stream
    8. 16.8 `Ping-From`
    9. 16.9 `Ping-To`
    10. 16.10 `Last-Event-ID`
    11. 16.11 web+ scheme prefix
  17. Index
    1. Elements
    2. Element content categories
    3. Attributes
    4. Element Interfaces
    5. All Interfaces
    6. Events
    7. MIME Types
  18. References
  19. Acknowledgments

+
+  
+
+  
1 Introduction
Spec bugs: 23036

+
+  
+
+  
1.1 Where does this specification fit?

+
+  
This specification defines a big part of the Web platform, in lots of detail. Its place in the
+  Web platform specification stack relative to other specifications can be best summed up as
+  follows:

+
+  
+   
+   CSS SVG MathML NPAPI
+   
+   Geo Fetch CSP
+   JPEG GIF PNG
+   
+   
+   THIS SPECIFICATION
+   
+   HTTP TLS MQ DOM Unicode Web IDL
+   MIME URL XML JavaScript Encodings
+  
+
+  
+
+
+  
1.2 Is this HTML5?

+
+  
This section is non-normative.

+
+  
In short: Yes.

+
+  
In more length: the term "HTML5" is widely used as a buzzword to refer to modern Web
+  technologies, many of which (though by no means all) are developed at the WHATWG. This document is
+  one such; others are available from the WHATWG
+  specification index.

+
+  
Although we have asked them to stop doing so, the W3C also republishes some parts
+  of this specification as separate documents.

+
+
+  
1.3 Background

+
+  
This section is non-normative.

+
+  
HTML is the World Wide Web's core markup language. Originally, HTML was primarily designed as a
+  language for semantically describing scientific documents. Its general design, however, has
+  enabled it to be adapted, over the subsequent years, to describe a number of other types of
+  documents and even applications.

+
+
+  
1.4 Audience

+
+  
This section is non-normative.

+
+  
This specification is intended for authors of documents and scripts that use the features
+  defined in this specification, implementors of tools that operate on pages that
+  use the features defined in this specification, and individuals wishing to establish the
+  correctness of documents or implementations with respect to the requirements of this
+  specification.

+
+  
This document is probably not suited to readers who do not already have at least a passing
+  familiarity with Web technologies, as in places it sacrifices clarity for precision, and brevity
+  for completeness. More approachable tutorials and authoring guides can provide a gentler
+  introduction to the topic.

+
+  
In particular, familiarity with the basics of DOM is necessary for a complete understanding of
+  some of the more technical parts of this specification. An understanding of Web IDL, HTTP, XML,
+  Unicode, character encodings, JavaScript, and CSS will also be helpful in places but is not
+  essential.

+
+
+  
1.5 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 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. Examples of such applications include 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.

+
+
+  
1.6 History

+
+  
This section is non-normative.

+
+  
For its first five years (1990-1995), HTML went through a number of revisions and experienced a
+  number of extensions, primarily hosted first at CERN, and then at the IETF.

+
+  
With the creation of the W3C, HTML's development changed venue again. A first abortive attempt
+  at extending HTML in 1995 known as HTML 3.0 then made way to a more pragmatic approach known as
+  HTML 3.2, which was completed in 1997. HTML4 quickly followed later that same year.

+
+  
The following year, the W3C membership decided to stop evolving HTML and instead begin work on
+  an XML-based equivalent, called XHTML.  This
+  effort started with a reformulation of HTML4 in XML, known as XHTML 1.0, which added no new
+  features except the new serialization, and which was completed in 2000. After XHTML 1.0, the W3C's
+  focus turned to making it easier for other working groups to extend XHTML, under the banner of
+  XHTML Modularization. In parallel with this, the W3C also worked on a new language that was not
+  compatible with the earlier HTML and XHTML languages, calling it XHTML2.

+
+  
Around the time that HTML's evolution was stopped in 1998, parts of the API for HTML developed
+  by browser vendors were specified and published under the name DOM Level 1 (in 1998) and DOM Level
+  2 Core and DOM Level 2 HTML (starting in 2000 and culminating in 2003). These efforts then petered
+  out, with some DOM Level 3 specifications published in 2004 but the working group being closed
+  before all the Level 3 drafts were completed.

+
+  
In 2003, the publication of XForms, a technology which was positioned as the next generation of
+  Web forms, sparked a renewed interest in evolving HTML itself, rather than finding replacements
+  for it. This interest was borne from the realization that XML's deployment as a Web technology was
+  limited to entirely new technologies (like RSS and later Atom), rather than as a replacement for
+  existing deployed technologies (like HTML).

+
+  
A proof of concept to show that it was possible to extend HTML4's forms to provide many of the
+  features that XForms 1.0 introduced, without requiring browsers to implement rendering engines
+  that were incompatible with existing HTML Web pages, was the first result of this renewed
+  interest. At this early stage, while the draft was already publicly available, and input was
+  already being solicited from all sources, the specification was only under Opera Software's
+  copyright.

+
+  
The idea that HTML's evolution should be reopened was tested at a W3C workshop in 2004, where
+  some of the principles that underlie the HTML5 work (described below), as well as the
+  aforementioned early draft proposal covering just forms-related features, were presented to the
+  W3C jointly by Mozilla and Opera. The proposal was rejected on the grounds that the proposal
+  conflicted with the previously chosen direction for the Web's evolution; the W3C staff and
+  membership voted to continue developing XML-based replacements instead.

+
+  
Shortly thereafter, Apple, Mozilla, and Opera jointly announced their intent to continue
+  working on the effort under the umbrella of a new venue called the WHATWG. A public mailing list
+  was created, and the draft was moved to the WHATWG site. The copyright was subsequently amended to
+  be jointly owned by all three vendors, and to allow reuse of the specification.

+
+  
The WHATWG was based on several core principles, in particular that technologies need to be
+  backwards compatible, that specifications and implementations need to match even if this means
+  changing the specification rather than the implementations, and that specifications need to be
+  detailed enough that implementations can achieve complete interoperability without
+  reverse-engineering each other.

+
+  
The latter requirement in particular required that the scope of the HTML5 specification include
+  what had previously been specified in three separate documents: HTML4, XHTML1, and DOM2 HTML. It
+  also meant including significantly more detail than had previously been considered the norm.

+
+  
In 2006, the W3C indicated an interest to participate in the development of HTML5 after all,
+  and in 2007 formed a working group chartered to work with the WHATWG on the development of the
+  HTML5 specification. Apple, Mozilla, and Opera allowed the W3C to publish the specification under
+  the W3C copyright, while keeping a version with the less restrictive license on the WHATWG
+  site.

+
+  
For a number of years, both groups then worked together. In 2011, however, the groups came to
+  the conclusion that they had different goals: the W3C wanted to publish a "finished" version of
+  "HTML5", while the WHATWG wanted to continue working on a Living Standard for HTML, continuously
+  maintaining the specification rather than freezing it in a state with known problems, and adding
+  new features as needed to evolve the platform.

+
+  
Since then, the WHATWG has been working on this specification (amongst others), and the W3C has
+  been copying fixes made by the WHATWG into their fork of the document (which also has other
+  changes).

+
+
+
+  
1.7 Design notes

+
+  
This section is non-normative.

+
+  
It must be admitted that many aspects of HTML appear at first glance to be nonsensical and
+  inconsistent.

+
+  
HTML, its supporting DOM APIs, as well as many of its supporting technologies, have been
+  developed over a period of several decades by a wide array of people with different priorities
+  who, in many cases, did not know of each other's existence.

+
+  
Features have thus arisen from many sources, and have not always been designed in especially
+  consistent ways. Furthermore, because of the unique characteristics of the Web, implementation
+  bugs have often become de-facto, and now de-jure, standards, as content is often unintentionally
+  written in ways that rely on them before they can be fixed.

+
+  
Despite all this, efforts have been made to adhere to certain design goals. These are described
+  in the next few subsections.

+
+
+  
+
+  
1.7.1 Serializability of script execution

+
+  
This section is non-normative.

+
+  
To avoid exposing Web authors to the complexities of multithreading, the HTML and DOM APIs are
+  designed such that no script can ever detect the simultaneous execution of other scripts. Even
+  with workers, the intent is that the behavior of implementations can
+  be thought of as completely serializing the execution of all scripts in all browsing contexts.

+
+  
The exception to this general design principle is the JavaScript SharedArrayBuffer
+  class. Using SharedArrayBuffer objects, it can in fact be observed that scripts in
+  other agents are executing simultaneously. Furthermore, due to the
+  JavaScript memory model, there are situations which not only are un-representable via serialized
+  script execution, but also un-representable via serialized statement execution
+  among those scripts.

+
+  
+
+
+
+  
1.7.2 Compliance with other specifications

+
+  
This section is non-normative.

+
+  
This specification interacts with and relies on a wide variety of other specifications. In
+  certain circumstances, unfortunately, conflicting needs have led to this specification violating
+  the requirements of these other specifications. Whenever this has occurred, the transgressions
+  have each been noted as a "willful violation", and the reason for the violation has
+  been noted.

+
+
+
+  
1.7.3 Extensibility

+
+  
This section is non-normative.

+
+  
HTML has a wide array of extensibility mechanisms that can be used for adding semantics in a
+  safe manner:

+
+  
  • Authors can use the class attribute to extend elements,
+   effectively creating their own elements, while using the most applicable existing "real" HTML
+   element, so that browsers and other tools that don't know of the extension can still support it
+   somewhat well. This is the tack used by microformats, for example.
  • Authors can include data for inline client-side scripts or server-side site-wide scripts
+   to process using the data-*="" attributes. These are guaranteed
+   to never be touched by browsers, and allow scripts to include data on HTML elements that scripts
+   can then look for and process.
  • Authors can use the <meta name="" content=""> mechanism to
+   include page-wide metadata.
  • Authors can use the rel="" mechanism to annotate
+   links with specific meanings by registering extensions to
+   the predefined set of link types. This is also used by microformats.
  • Authors can embed raw data using the <script type="">
+   mechanism with a custom type, for further handling by inline or server-side scripts.
  • Authors can create plugins and invoke them using the
+   embed element. This is how Flash works.
  • Authors can extend APIs using the JavaScript prototyping mechanism. This is widely used by
+   script libraries, for instance.
  • Authors can use the microdata feature (the itemscope="" and itemprop=""
+   attributes) to embed nested name-value pairs of data to be shared with other applications and
+   sites.

+
+
+
+
+  
1.8 HTML vs XML syntax

+
+  
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 "DOM 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 the HTML syntax. This is the format suggested for most
+  authors. It is compatible with most legacy Web browsers. If a document is transmitted with the
+  text/html MIME type, then it will be processed as an HTML document by
+  Web browsers. This specification defines the latest HTML syntax, known simply as "HTML".

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

+
+  
The XML syntax for HTML was formerly referred to as "XHTML", but this
+  specification does not use that term (among other reasons, because no such term is used for the
+  HTML syntaxes of MathML and SVG).

+
+  
The DOM, the HTML syntax, and the XML syntax cannot all represent the same content. For
+  example, namespaces cannot be represented using the HTML syntax, but they are supported in the DOM
+  and in the XML syntax. Similarly, documents that use the noscript feature can be
+  represented using the HTML syntax, but cannot be represented with the DOM or in the XML syntax.
+  Comments that contain the string "-->" can only be represented in the
+  DOM, not in the HTML and XML syntaxes.

+
+
+  
1.9 Structure of this specification

+
+  
This section is non-normative.

+
+  
This specification is divided into the following major sections:

+
+  
Introduction
Non-normative materials providing a context for the HTML standard.
Common infrastructure
The conformance classes, algorithms, definitions, and the common underpinnings of the rest of
+   the specification.
Semantics, structure, and APIs of HTML documents
Documents are built from elements. These elements form a tree using the DOM. This section
+   defines the features of this DOM, as well as introducing the features common to all elements, and
+   the concepts used in defining elements.
The elements of HTML
Each element has a predefined meaning, which is explained in this section. Rules for authors
+   on how to use the element, along with user agent requirements for how to
+   handle each element, are also given. This includes large signature features of HTML such
+   as video playback and subtitles, form controls and form submission, and a 2D graphics API known
+   as the HTML canvas.
Microdata
This specification introduces a mechanism for adding machine-readable annotations to
+   documents, so that tools can extract trees of name-value pairs from the document. This section
+   describes this mechanism and some algorithms that can be used to convert HTML
+   documents into other formats. This section also defines some sample Microdata vocabularies
+   for contact information, calendar events, and licensing works.
User interaction
HTML documents can provide a number of mechanisms for users to interact with and modify
+   content, which are described in this section, such as how focus works, and drag-and-drop.
Loading Web pages
HTML documents do not exist in a vacuum — this section defines many of the features
+   that affect environments that deal with multiple pages, such as Web browsers and offline
+   caching of Web applications.
Web application APIs
This section introduces basic features for scripting of applications in HTML.
Web workers
This section defines an API for background threads in JavaScript.
The communication APIs
This section describes some mechanisms that applications written in HTML can use to
+   communicate with other applications from different domains running on the same client. It also
+   introduces a server-push event stream mechanism known as Server Sent Events or
+   EventSource, and a two-way full-duplex socket protocol for scripts known as Web
+   Sockets.
+
+   
Web storage
This section defines a client-side storage mechanism based on name-value pairs.
The HTML syntax
The XML syntax
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 these sections define the syntaxes of HTML and XML, along with rules for how to parse content using those syntaxes.
Rendering
This section defines the default rendering rules for Web browsers.

+
+  
There are also some appendices, listing obsolete features and IANA considerations, and several indices.

+
+
+  
+
+  
1.9.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.

+
+  
As described in the conformance requirements section below, this specification describes
+  conformance criteria for a variety of conformance classes. In particular, there are conformance
+  requirements that apply to producers, for example authors and the documents they create,
+  and there are conformance requirements that apply to consumers, for example Web browsers.
+  They can be distinguished by what they are requiring: a requirement on a producer states what is
+  allowed, while a requirement on a consumer states how software is to act.

+
+  

+
+   
For example, "the foo attribute's value must be a valid
+   integer" is a requirement on producers, as it lays out the allowed values; in contrast,
+   the requirement "the foo attribute's value must be parsed using the
+   rules for parsing integers" is a requirement on consumers, as it describes how to
+   process the content.

+
+  

+
+  
Requirements on producers have no bearing whatsoever on consumers.

+
+  

+
+   
Continuing the above example, a requirement stating that a particular attribute's value is
+   constrained to being a valid integer emphatically does not imply anything
+   about the requirements on consumers. It might be that the consumers are in fact required to treat
+   the attribute as an opaque string, completely unaffected by whether the value conforms to the
+   requirements or not. It might be (as in the previous example) that the consumers are required to
+   parse the value using specific rules that define how invalid (non-numeric in this case) values
+   are to be processed.

+
+  

+
+  
+
+
+
+  
1.9.2 Typographic conventions

+
+  
This is a definition, requirement, or explanation.

+
+  
This is a note.

+
+  
This is an example.

+
+  
This is an open issue.

+
+  
This is a warning.

+
+  
interface Example {
+  // this is an IDL definition
+};

+
+  
variable = object . method( [ optionalArgument ] )

+
+    
This is a note to authors describing the usage of an interface.

+
+   

+
+  
/* this is a CSS fragment */

+
+  
The defining instance of a term is marked up like this. Uses of that
+  term are marked up like this or like this.

+
+  
The defining instance of an element, attribute, or API is marked up like this. References to that element, attribute, or API are marked up
+  like this.

+
+  
Other code fragments are marked up like this.

+
+  
Variables are marked up like this.

+
+  
In an algorithm, steps in synchronous
+  sections are marked with ⌛.

+
+  
In some cases, requirements are given in the form of lists with conditions and corresponding
+  requirements. In such cases, the requirements that apply to a condition are always the first set
+  of requirements that follow the condition, even in the case of there being multiple sets of
+  conditions for those requirements. Such cases are presented as follows:

+
+  
This is a condition
+   
This is another condition
+   
This is the requirement that applies to the conditions above.
+
+   
This is a third condition
+   
This is the requirement that applies to the third condition.
+
+  

+
+
+
+  
1.10 Privacy concerns

+
+  
This section is non-normative.

+
+  
Some features of HTML trade user convenience for a measure of user privacy.

+
+  
In general, due to the Internet's architecture, a user can be distinguished from another by the
+  user's IP address. IP addresses do not perfectly match to a user; as a user moves from device to
+  device, or from network to network, their IP address will change; similarly, NAT routing, proxy
+  servers, and shared computers enable packets that appear to all come from a single IP address to
+  actually map to multiple users. Technologies such as onion routing can be used to further
+  anonymize requests so that requests from a single user at one node on the Internet appear to come
+  from many disparate parts of the network.

+
+  
However, the IP address used for a user's requests is not the only mechanism by which a user's
+  requests could be related to each other. Cookies, for example, are designed specifically to enable
+  this, and are the basis of most of the Web's session features that enable you to log into a site
+  with which you have an account.

+
+  
There are other mechanisms that are more subtle. Certain characteristics of a user's system can
+  be used to distinguish groups of users from each other; by collecting enough such information, an
+  individual user's browser's "digital fingerprint" can be computed, which can be as good, if not
+  better, as an IP address in ascertaining which requests are from the same user.

+
+  
Grouping requests in this manner, especially across multiple sites, can be used for both benign
+  (and even arguably positive) purposes, as well as for malevolent purposes. An example of a
+  reasonably benign purpose would be determining whether a particular person seems to prefer sites
+  with dog illustrations as opposed to sites with cat illustrations (based on how often they visit
+  the sites in question) and then automatically using the preferred illustrations on subsequent
+  visits to participating sites. Malevolent purposes, however, could include governments combining
+  information such as the person's home address (determined from the addresses they use when getting
+  driving directions on one site) with their apparent political affiliations (determined by
+  examining the forum sites that they participate in) to determine whether the person should be
+  prevented from voting in an election.

+
+  
Since the malevolent purposes can be remarkably evil, user agent implementors are encouraged to
+  consider how to provide their users with tools to minimize leaking information that could be used
+  to fingerprint a user.

+
+  
Unfortunately, as the first paragraph in this section implies, sometimes there is great benefit
+  to be derived from exposing the very information that can also be used for fingerprinting
+  purposes, so it's not as easy as simply blocking all possible leaks. For instance, the ability to
+  log into a site to post under a specific identity requires that the user's requests be
+  identifiable as all being from the same user, more or less by definition. More subtly, though,
+  information such as how wide text is, which is necessary for many effects that involve drawing
+  text onto a canvas (e.g. any effect that involves drawing a border around the text) also leaks
+  information that can be used to group a user's requests. (In this case, by potentially exposing,
+  via a brute force search, which fonts a user has installed, information which can vary
+  considerably from user to user.)

+
+  
Features in this specification which can be used to
+  fingerprint the user are marked as this paragraph is.
+  (This is a fingerprinting vector.)
+  

+
+  
Other features in the platform can be used for the same purpose, though, including, though not
+  limited to:

+
+  
  • The exact list of which features a user agents supports.
  • The maximum allowed stack depth for recursion in script.
  • Features that describe the user's environment, like Media Queries and the Screen
+   object. [MQ] [CSSOMVIEW]
  • The user's time zone.

+
+
+  
1.10.1 Cross-site communication

+
+  
The postMessage() API provides a mechanism by
+  which two sites can communicate directly. At first glance, this might appear to open a new way by
+  which the problems described above can occur. However, in practice, multiple mechanisms exist by
+  which two sites can communicate that predate this API: a site embedding another can send data via
+  an iframe element's dimensions; a site can use a cross-site image request with a
+  unique identifier known to the server to initiate a server-side data exchange; or indeed the
+  fingerprinting techniques described above can be used by two sites to uniquely identify a visitor
+  such that information can then be exchanged on the server side.

+
+  
Fundamentally, users that do not trust a site to treat their information with respect have to
+  avoid visiting that site at all.

+
+
+
+
+  
1.11 A quick introduction to HTML

+
+  
This section is non-normative.

+
+  
A basic HTML document looks like this:

+
+  
<!DOCTYPE html>
+<html lang="en">
+ <head>
+  <title>Sample page</title>
+ </head>
+ <body>
+  <h1>Sample page</h1>
+  <p>This is a <a href="demo.html">simple</a> sample.</p>
+  <!-- this is a comment -->
+ </body>
+</html>

+
+  
HTML documents consist of a tree of elements and text. Each element is denoted in the source by
+  a start tag, such as "<body>", and
+  an end tag, such as "</body>".
+  (Certain start tags and end tags can in certain cases be omitted and are implied by other tags.)

+
+  
Tags have to be nested such that elements are all completely within each other, without
+  overlapping:

+
+  
<p>This is <em>very <strong>wrong</em>!</strong></p>

+  
<p>This <em>is <strong>correct</strong>.</em></p>

+
+  
This specification defines a set of elements that can be used in HTML, along with rules about
+  the ways in which the elements can be nested.

+
+  
Elements can have attributes, which control how the elements work. In the example below, there
+  is a hyperlink, formed using the a element and its href attribute:

+
+  
<a href="demo.html">simple</a>

+
+  
Attributes are placed inside the start tag, and consist
+  of a name and a value, separated by an "=" character.
+  The attribute value can remain unquoted if it doesn't contain ASCII
+  whitespace or any of " ' ` = < or >. Otherwise, it has to be quoted using either single or double quotes. The
+  value, along with the "=" character, can be omitted altogether if the value
+  is the empty string.

+
+  
<!-- empty attributes -->
+<input name=address disabled>
+<input name=address disabled="">
+
+<!-- attributes with a value -->
+<input name=address maxlength=200>
+<input name=address maxlength='200'>
+<input name=address maxlength="200">

+
+  
HTML user agents (e.g. Web browsers) then parse this markup, turning it into a DOM
+  (Document Object Model) tree. A DOM tree is an in-memory representation of a document.

+
+  
DOM trees contain several kinds of nodes, in particular a DocumentType node,
+  Element nodes, Text nodes, Comment nodes, and in some cases
+  ProcessingInstruction nodes.

+
+  
The markup snippet at the top of this section would be
+  turned into the following DOM tree:

+
+  
+
+  
The document element of this tree is the html element, which is the
+  element always found in that position in HTML documents. It contains two elements,
+  head and body, as well as a Text node between them.

+
+  
There are many more Text nodes in the DOM tree than one would initially expect,
+  because the source contains a number of spaces (represented here by "␣") and line breaks
+  ("⏎") that all end up as Text nodes in the DOM. However, for historical
+  reasons not all of the spaces and line breaks in the original markup appear in the DOM. In
+  particular, all the whitespace before head start tag ends up being dropped silently,
+  and all the whitespace after the body end tag ends up placed at the end of the
+  body.

+
+  
The head element contains a title element, which itself contains a
+  Text node with the text "Sample page". Similarly, the body element
+  contains an h1 element, a p element, and a comment.

+
+  

+
+  
This DOM tree can be manipulated from scripts in the page. Scripts (typically in JavaScript)
+  are small programs that can be embedded using the script element or using event
+  handler content attributes. For example, here is a form with a script that sets the value
+  of the form's output element to say "Hello World":

+
+  
<form name="main">
+ Result: <output name="result"></output>
+ <script>
+  document.forms.main.elements.result.value = 'Hello World';
+ </script>
+</form>

+
+  
Each element in the DOM tree is represented by an object, and these objects have APIs so that
+  they can be manipulated. For instance, a link (e.g. the a element in the tree above)
+  can have its "href" attribute changed in several
+  ways:

+
+  
var a = document.links[0]; // obtain the first link in the document
+a.href = 'sample.html'; // change the destination URL of the link
+a.protocol = 'https'; // change just the scheme part of the URL
+a.setAttribute('href', 'https://example.com/'); // change the content attribute directly

+
+  
Since DOM trees are used as the way to represent HTML documents when they are processed and
+  presented by implementations (especially interactive implementations like Web browsers), this
+  specification is mostly phrased in terms of DOM trees, instead of the markup described above.

+
+  

+
+  
HTML documents represent a media-independent description of interactive content. HTML documents
+  might be rendered to a screen, or through a speech synthesizer, or on a braille display. To
+  influence exactly how such rendering takes place, authors can use a styling language such as
+  CSS.

+
+  
In the following example, the page has been made yellow-on-blue using CSS.

+
+  
<!DOCTYPE html>
+<html lang="en">
+ <head>
+  <title>Sample styled page</title>
+  <style>
+   body { background: navy; color: yellow; }
+  </style>
+ </head>
+ <body>
+  <h1>Sample styled page</h1>
+  <p>This page is just a demo.</p>
+ </body>
+</html>

+
+  
For more details on how to use HTML, authors are encouraged to consult tutorials and guides.
+  Some of the examples included in this specification might also be of use, but the novice author is
+  cautioned that this specification, by necessity, defines the language with a level of detail that
+  might be difficult to understand at first.

+
+
+
+
+  
1.11.1 Writing secure applications with HTML

+
+  
This section is non-normative.

+
+  
When HTML is used to create interactive sites, care needs to be taken to avoid introducing
+  vulnerabilities through which attackers can compromise the integrity of the site itself or of the
+  site's users.

+
+  
A comprehensive study of this matter is beyond the scope of this document, and authors are
+  strongly encouraged to study the matter in more detail. However, this section attempts to provide
+  a quick introduction to some common pitfalls in HTML application development.

+
+  
The security model of the Web is based on the concept of "origins", and correspondingly many of
+  the potential attacks on the Web involve cross-origin actions. [ORIGIN]

+
+  
Not validating user input
Cross-site scripting (XSS)
SQL injection

+
+    
When accepting untrusted input, e.g. user-generated content such as text comments, values in
+    URL parameters, messages from third-party sites, etc, it is imperative that the data be
+    validated before use, and properly escaped when displayed. Failing to do this can allow a
+    hostile user to perform a variety of attacks, ranging from the potentially benign, such as
+    providing bogus user information like a negative age, to the serious, such as running scripts
+    every time a user looks at a page that includes the information, potentially propagating the
+    attack in the process, to the catastrophic, such as deleting all data in the server.

+
+    
When writing filters to validate user input, it is imperative that filters always be
+    safelist-based, allowing known-safe constructs and disallowing all other input. Blocklist-based
+    filters that disallow known-bad inputs and allow everything else are not secure, as not
+    everything that is bad is yet known (for example, because it might be invented in the
+    future).

+
+    

+
+     
For example, suppose a page looked at its URL's query string to determine what to display,
+     and the site then redirected the user to that page to display a message, as in:

+
+     
<ul>
+ <li><a href="message.cgi?say=Hello">Say Hello</a>
+ <li><a href="message.cgi?say=Welcome">Say Welcome</a>
+ <li><a href="message.cgi?say=Kittens">Say Kittens</a>
+</ul>

+
+     
If the message was just displayed to the user without escaping, a hostile attacker could
+     then craft a URL that contained a script element:

+
+     
https://example.com/message.cgi?say=%3Cscript%3Ealert%28%27Oh%20no%21%27%29%3C/script%3E

+
+     
If the attacker then convinced a victim user to visit this page, a script of the attacker's
+     choosing would run on the page. Such a script could do any number of hostile actions, limited
+     only by what the site offers: if the site is an e-commerce shop, for instance, such a script
+     could cause the user to unknowingly make arbitrarily many unwanted purchases.

+
+     
This is called a cross-site scripting attack.

+
+    

+
+    
There are many constructs that can be used to try to trick a site into executing code. Here
+    are some that authors are encouraged to consider when writing safelist filters:

+
+    
  • When allowing harmless-seeming elements like img, it is important to safelist
+     any provided attributes as well. If one allowed all attributes then an attacker could, for
+     instance, use the onload attribute to run arbitrary
+     script.
  • When allowing URLs to be provided (e.g. for links), the scheme of each URL also needs to be
+     explicitly safelisted, as there are many schemes that can be abused. The most prominent
+     example is "javascript:", but user agents can
+     implement (and indeed, have historically implemented) others.
  • Allowing a base element to be inserted means any script elements
+     in the page with relative links can be hijacked, and similarly that any form submissions can
+     get redirected to a hostile site.

+
+   
Cross-site request forgery (CSRF)

+
+    
If a site allows a user to make form submissions with user-specific side-effects, for example
+    posting messages on a forum under the user's name, making purchases, or applying for a passport,
+    it is important to verify that the request was made by the user intentionally, rather than by
+    another site tricking the user into making the request unknowingly.

+
+    
This problem exists because HTML forms can be submitted to other origins.

+
+    
Sites can prevent such attacks by populating forms with user-specific hidden tokens, or by
+    checking `Origin` headers on all requests.

+
+   
Clickjacking

+
+    
A page that provides users with an interface to perform actions that the user might not wish
+    to perform needs to be designed so as to avoid the possibility that users can be tricked into
+    activating the interface.

+
+    
One way that a user could be so tricked is if a hostile site places the victim site in a
+    small iframe and then convinces the user to click, for instance by having the user
+    play a reaction game. Once the user is playing the game, the hostile site can quickly position
+    the iframe under the mouse cursor just as the user is about to click, thus tricking the user
+    into clicking the victim site's interface.

+
+    
To avoid this, sites that do not expect to be used in frames are encouraged to only enable
+    their interface if they detect that they are not in a frame (e.g. by comparing the window object to the value of the top
+    attribute).

+
+   

+
+
+
+  
1.11.2 Common pitfalls to avoid when using the scripting APIs

+
+  
This section is non-normative.

+
+  
Scripts in HTML have "run-to-completion" semantics, meaning that the browser will generally run
+  the script uninterrupted before doing anything else, such as firing further events or continuing
+  to parse the document.

+
+  
On the other hand, parsing of HTML files happens incrementally, meaning that
+  the parser can pause at any point to let scripts run. This is generally a good thing, but it does
+  mean that authors need to be careful to avoid hooking event handlers after the events could have
+  possibly fired.

+
+  
There are two techniques for doing this reliably: use event handler content
+  attributes, or create the element and add the event handlers in the same script. The latter
+  is safe because, as mentioned earlier, scripts are run to completion before further events can
+  fire.

+
+  

+
+   
One way this could manifest itself is with img elements and the load event. The event could fire as soon as the element has been
+   parsed, especially if the image has already been cached (which is common).

+
+   
Here, the author uses the onload handler on an
+   img element to catch the load event:

+
+   
<img src="games.png" alt="Games" onload="gamesLogoHasLoaded(event)">

+
+   
If the element is being added by script, then so long as the event handlers are added in the
+   same script, the event will still not be missed:

+
+   
<script>
+ var img = new Image();
+ img.src = 'games.png';
+ img.alt = 'Games';
+ img.onload = gamesLogoHasLoaded;
+ // img.addEventListener('load', gamesLogoHasLoaded, false); // would work also
+</script>

+
+   
However, if the author first created the img element and then in a separate
+   script added the event listeners, there's a chance that the load
+   event would be fired in between, leading it to be missed:

+
+   
<!-- Do not use this style, it has a race condition! -->
+ <img id="games" src="games.png" alt="Games">
+ <!-- the 'load' event might fire here while the parser is taking a
+      break, in which case you will not see it! -->
+ <script>
+  var img = document.getElementById('games');
+  img.onload = gamesLogoHasLoaded; // might never fire!
+ </script>

+
+  

+
+
+
+  
1.11.3 How to catch mistakes when writing HTML: validators and conformance checkers

+
+  
This section is non-normative.

+
+  
Authors are encouraged to make use of conformance checkers (also known as validators) to
+  catch common mistakes. The WHATWG maintains a list of such tools at: https://validator.whatwg.org/

+
+
+
+  
1.12 Conformance requirements for authors

+
+  
This section is non-normative.

+
+  
Unlike previous versions of the HTML specification, this specification defines in some detail
+  the required processing for invalid documents as well as valid documents.
 
+
+  
However, even though the processing of invalid content is in most cases well-defined,
+  conformance requirements for documents are still important: in practice, interoperability (the
+  situation in which all implementations process particular content in a reliable and identical or
+  equivalent way) is not the only goal of document conformance requirements. This section details
+  some of the more common reasons for still distinguishing between a conforming document and one
+  with errors.

+
+
+  
1.12.1 Presentational markup

+
+  
This section is non-normative.

+
+  
The majority of presentational features from previous versions of HTML are no longer allowed.
+  Presentational markup in general has been found to have a number of problems:

+
+  
The use of presentational elements leads to poorer accessibility

+
+    
While it is possible to use presentational markup in a way that provides users of assistive
+    technologies (ATs) with an acceptable experience (e.g. using ARIA), doing so is significantly
+    more difficult than doing so when using semantically-appropriate markup. Furthermore, even using
+    such techniques doesn't help make pages accessible for non-AT non-graphical users, such as users
+    of text-mode browsers.

+
+    
Using media-independent markup, on the other hand, provides an easy way for documents to be
+    authored in such a way that they work for more users (e.g. users of text browsers).

+
+   
Higher cost of maintenance

+
+    
It is significantly easier to maintain a site written in such a way that the markup is
+    style-independent. For example, changing the color of a site that uses <font color=""> throughout requires changes across the entire site,
+    whereas a similar change to a site based on CSS can be done by changing a single file.

+
+   
Larger document sizes

+
+    
Presentational markup tends to be much more redundant, and thus results in larger document
+    sizes.

+
+   

+
+  
For those reasons, presentational markup has been removed from HTML in this version. This
+  change should not come as a surprise; HTML4 deprecated presentational markup many years ago and
+  provided a mode (HTML4 Transitional) to help authors move away from presentational markup; later,
+  XHTML 1.1 went further and obsoleted those features altogether.

+
+  
The only remaining presentational markup features in HTML are the style attribute and the style element. Use of the style attribute is somewhat discouraged in production environments, but
+  it can be useful for rapid prototyping (where its rules can be directly moved into a separate
+  style sheet later) and for providing specific styles in unusual cases where a separate style sheet
+  would be inconvenient. Similarly, the style element can be useful in syndication or
+  for page-specific styles, but in general an external style sheet is likely to be more convenient
+  when the styles apply to multiple pages.

+
+  
It is also worth noting that some elements that were previously presentational have been
+  redefined in this specification to be media-independent: b, i,
+  hr, s, small, and u.

+
+
+  
1.12.2 Syntax errors

+
+  
This section is non-normative.

+
+  
The syntax of HTML is constrained to avoid a wide variety of problems.

+
+  
Unintuitive error-handling behavior

+
+    
Certain invalid syntax constructs, when parsed, result in DOM trees that are highly
+    unintuitive.

+
+    

+
+     
For example, the following markup fragment results in a DOM with an hr element
+     that is an earlier sibling of the corresponding table element:

+
+     
<table><hr>...

+
+    

+
+   
Errors with optional error recovery

+
+    
To allow user agents to be used in controlled environments without having to implement the
+    more bizarre and convoluted error handling rules, user agents are permitted to fail whenever
+    encountering a parse error.

+
+   
Errors where the error-handling behavior is not compatible with streaming user agents

+
+    
Some error-handling behavior, such as the behavior for the <table><hr>... example mentioned above, are incompatible with streaming
+    user agents (user agents that process HTML files in one pass, without storing state). To avoid
+    interoperability problems with such user agents, any syntax resulting in such behavior is
+    considered invalid.

+
+   
Errors that can result in infoset coercion

+
+    
When a user agent based on XML is connected to an HTML parser, it is possible that certain
+    invariants that XML enforces, such as element or attribute names never contain multiple colons,
+    will be violated by an HTML file. Handling this can require that the parser coerce the HTML DOM
+    into an XML-compatible infoset. Most syntax constructs that require such handling are considered
+    invalid. (Comments containing two consecutive hyphens, or ending with a hyphen, are exceptions
+    that are allowed in the HTML syntax.)

+
+   
Errors that result in disproportionately poor performance

+
+    
Certain syntax constructs can result in disproportionately poor performance. To discourage the
+    use of such constructs, they are typically made non-conforming.

+
+    

+
+     
For example, the following markup results in poor performance, since all the unclosed
+     i elements have to be reconstructed in each paragraph, resulting in progressively
+     more elements in each paragraph:

+
+     
<p><i>She dreamt.
+<p><i>She dreamt that she ate breakfast.
+<p><i>Then lunch.
+<p><i>And finally dinner.

+
+     
The resulting DOM for this fragment would be:

+
+     
+
+    

+
+   
Errors involving fragile syntax constructs

+
+    
There are syntax constructs that, for historical reasons, are relatively fragile. To help
+    reduce the number of users who accidentally run into such problems, they are made
+    non-conforming.

+
+    

+
+     
For example, the parsing of certain named character references in attributes happens even
+     with the closing semicolon being omitted. It is safe to include an ampersand followed by
+     letters that do not form a named character reference, but if the letters are changed to a
+     string that does form a named character reference, they will be interpreted as that
+     character instead.

+
+     
In this fragment, the attribute's value is "?bill&ted":

+
+     
<a href="?bill&ted">Bill and Ted</a>

+
+     
In the following fragment, however, the attribute's value is actually "?art©", not the intended "?art&copy",
+     because even without the final semicolon, "&copy" is handled the same
+     as "&copy;" and thus gets interpreted as "©":

+
+     
<a href="?art&copy">Art and Copy</a>

+
+     
To avoid this problem, all named character references are required to end with a semicolon,
+     and uses of named character references without a semicolon are flagged as errors.

+
+     
Thus, the correct way to express the above cases is as
+     follows:

+
+     
<a href="?bill&ted">Bill and Ted</a> <!-- &ted is ok, since it's not a named character reference -->

+     
<a href="?art&amp;copy">Art and Copy</a> <!-- the & has to be escaped, since &copy is a named character reference -->

+
+    

+
+   
Errors involving known interoperability problems in legacy user agents

+
+    
Certain syntax constructs are known to cause especially subtle or serious problems in legacy
+    user agents, and are therefore marked as non-conforming to help authors avoid them.

+
+    

+
+     
For example, this is why the U+0060 GRAVE ACCENT character (`) is not allowed in unquoted
+     attributes. In certain legacy user agents,  it is sometimes treated as a
+     quote character.

+
+    

+
+    

+
+     
Another example of this is the DOCTYPE, which is required to trigger no-quirks
+     mode, because the behavior of legacy user agents in quirks mode is often
+     largely undocumented.

+
+    

+
+   
Errors that risk exposing authors to security attacks

+
+    
Certain restrictions exist purely to avoid known security problems.

+
+    

+
+     
For example, the restriction on using UTF-7 exists purely to avoid authors falling prey to a
+     known cross-site-scripting attack using UTF-7. [UTF7]

+
+    

+
+   
Cases where the author's intent is unclear

+
+    
Markup where the author's intent is very unclear is often made non-conforming. Correcting
+    these errors early makes later maintenance easier.

+
+    

+
+     
For example, it is unclear whether the author intended the following to be an
+     h1 heading or an h2 heading:

+
+     
<h1>Contact details</h2>

+
+    

+
+   
Cases that are likely to be typos

+
+    
When a user makes a simple typo, it is helpful if the error can be caught early, as this can
+    save the author a lot of debugging time. This specification therefore usually considers it an
+    error to use element names, attribute names, and so forth, that do not match the names defined
+    in this specification.

+
+    

+
+     
For example, if the author typed <capton> instead of <caption>, this would be flagged as an error and the author could correct
+     the typo immediately.

+
+    

+
+   
Errors that could interfere with new syntax in the future

+
+    
In order to allow the language syntax to be extended in the future, certain otherwise
+    harmless features are disallowed.

+
+    

+
+     
For example, "attributes" in end tags are ignored currently, but they are invalid, in case a
+     future change to the language makes use of that syntax feature without conflicting with
+     already-deployed (and valid!) content.

+
+    

+
+   

+
+  
Some authors find it helpful to be in the practice of always quoting all attributes and always
+  including all optional tags, preferring the consistency derived from such custom over the minor
+  benefits of terseness afforded by making use of the flexibility of the HTML syntax. To aid such
+  authors, conformance checkers can provide modes of operation wherein such conventions are
+  enforced.

+
+
+
+  
1.12.3 Restrictions on content models and on attribute values

+
+  
This section is non-normative.

+
+  
Beyond the syntax of the language, this specification also places restrictions on how elements
+  and attributes can be specified. These restrictions are present for similar reasons:

+
+  
Errors involving content with dubious semantics

+
+    
To avoid misuse of elements with defined meanings, content models are defined that restrict
+    how elements can be nested when such nestings would be of dubious value.

+
+    
For example, this specification disallows nesting a section
+    element inside a kbd element, since it is highly unlikely for an author to indicate
+    that an entire section should be keyed in.

+
+   
Errors that involve a conflict in expressed semantics

+
+    
Similarly, to draw the author's attention to mistakes in the use of elements, clear
+    contradictions in the semantics expressed are also considered conformance errors.

+
+    

+
+     
In the fragments below, for example, the semantics are nonsensical: a separator cannot
+     simultaneously be a cell, nor can a radio button be a progress bar.

+
+     
<hr role="cell">

+     
<input type=radio role=progressbar>

+
+    

+
+    
Another example is the restrictions on the content models of the
+    ul element, which only allows li element children. Lists by definition
+    consist just of zero or more list items, so if a ul element contains something
+    other than an li element, it's not clear what was meant.

+
+   
Cases where the default styles are likely to lead to confusion

+
+    
Certain elements have default styles or behaviors that make certain combinations likely to
+    lead to confusion. Where these have equivalent alternatives without this problem, the confusing
+    combinations are disallowed.

+
+    
For example, div elements are rendered as block boxes, and span elements as inline boxes. Putting a block box in an
+    inline box is unnecessarily confusing; since either nesting just div
+    elements, or nesting just span elements, or nesting span elements
+    inside div elements all serve the same purpose as nesting a div
+    element in a span element, but only the latter involves a block box in
+    an inline box, the latter combination is disallowed.

+
+    
Another example would be the way interactive content cannot be
+    nested. For example, a button element cannot contain a textarea
+    element. This is because the default behavior of such nesting interactive elements would be
+    highly confusing to users. Instead of nesting these elements, they can be placed side by
+    side.

+
+   
Errors that indicate a likely misunderstanding of the specification

+
+    
Sometimes, something is disallowed because allowing it would likely cause author
+    confusion.

+
+    
For example, setting the disabled
+    attribute to the value "false" is disallowed, because despite the
+    appearance of meaning that the element is enabled, it in fact means that the element is
+    disabled (what matters for implementations is the presence of the attribute, not its
+    value).

+
+   
Errors involving limits that have been imposed merely to simplify the language

+
+    
Some conformance errors simplify the language that authors need to learn.

+
+    
For example, the area element's shape attribute, despite accepting both circ and circle values in practice as synonyms, disallows
+    the use of the circ value, so as to simplify
+    tutorials and other learning aids. There would be no benefit to allowing both, but it would
+    cause extra confusion when teaching the language.

+
+   
Errors that involve peculiarities of the parser

+
+    
Certain elements are parsed in somewhat eccentric ways (typically for historical reasons),
+    and their content model restrictions are intended to avoid exposing the author to these
+    issues.

+
+    

+
+     
For example, a form element isn't allowed inside phrasing content,
+     because when parsed as HTML, a form element's start tag will imply a
+     p element's end tag. Thus, the following markup results in two paragraphs, not one:

+
+     
<p>Welcome. <form><label>Name:</label> <input></form>

+
+     
It is parsed exactly like the following:

+
+     
<p>Welcome. </p><form><label>Name:</label> <input></form>

+
+    

+
+   
Errors that would likely result in scripts failing in hard-to-debug ways

+
+    
Some errors are intended to help prevent script problems that would be hard to debug.

+
+    
This is why, for instance, it is non-conforming to have two id attributes with the same value. Duplicate IDs lead to the wrong
+    element being selected, with sometimes disastrous effects whose cause is hard to determine.

+
+   
Errors that waste authoring time

+
+    
Some constructs are disallowed because historically they have been the cause of a lot of
+    wasted authoring time, and by encouraging authors to avoid making them, authors can save time in
+    future efforts.

+
+    
For example, a script element's src attribute causes the element's contents to be ignored.
+    However, this isn't obvious, especially if the element's contents appear to be executable script
+    — which can lead to authors spending a lot of time trying to debug the inline script
+    without realizing that it is not executing. To reduce this problem, this specification makes it
+    non-conforming to have executable script in a script element when the src attribute is present. This means that authors who are
+    validating their documents are less likely to waste time with this kind of mistake.

+
+   
Errors that involve areas that affect authors migrating between the HTML and XML
+   syntaxes

+
+    
Some authors like to write files that can be interpreted as both XML and HTML with similar
+    results. Though this practice is discouraged in general due to the myriad of subtle
+    complications involved (especially when involving scripting, styling, or any kind of automated
+    serialization), this specification has a few restrictions intended to at least somewhat mitigate
+    the difficulties. This makes it easier for authors to use this as a transitionary step when
+    migrating between the HTML and XML syntaxes.

+
+    
For example, there are somewhat complicated rules surrounding the lang and xml:lang attributes
+    intended to keep the two synchronized.

+
+    
Another example would be the restrictions on the values of xmlns attributes in the HTML serialization, which are intended to ensure that
+    elements in conforming documents end up in the same namespaces whether processed as HTML or
+    XML.

+
+   
Errors that involve areas reserved for future expansion

+
+    
As with the restrictions on the syntax intended to allow for new syntax in future revisions
+    of the language, some restrictions on the content models of elements and values of attributes
+    are intended to allow for future expansion of the HTML vocabulary.

+
+    
For example, limiting the values of the target attribute that start with an U+005F LOW LINE
+    character (_) to only specific predefined values allows new predefined values to be introduced
+    at a future time without conflicting with author-defined values.

+
+   
Errors that indicate a mis-use of other specifications

+
+    
Certain restrictions are intended to support the restrictions made by other
+    specifications.

+
+    
For example, requiring that attributes that take media query lists use only
+    valid media query lists reinforces the importance of following the conformance rules of
+    that specification.

+
+   

+
+
+
+  
1.13 Suggested reading

+
+  
This section is non-normative.

+
+  
The following documents might be of interest to readers of this specification.

+
+  
Character Model for the World Wide Web 1.0: Fundamentals [CHARMOD]
This Architectural Specification provides authors of specifications, software
+   developers, and content developers with a common reference for interoperable text manipulation on
+   the World Wide Web, building on the Universal Character Set, defined jointly by the Unicode
+   Standard and ISO/IEC 10646. Topics addressed include use of the terms 'character', 'encoding' and
+   'string', a reference processing model, choice and identification of character encodings,
+   character escaping, and string indexing.
Unicode Security Considerations [UTR36]
Because Unicode contains such a large number of characters and incorporates
+   the varied writing systems of the world, incorrect usage can expose programs or systems to
+   possible security attacks. This is especially important as more and more products are
+   internationalized. This document describes some of the security considerations that programmers,
+   system analysts, standards developers, and users should take into account, and provides specific
+   recommendations to reduce the risk of problems.
Web Content Accessibility Guidelines (WCAG) 2.0 [WCAG]
Web Content Accessibility Guidelines (WCAG) 2.0 covers a wide range of
+   recommendations for making Web content more accessible. Following these guidelines will make
+   content accessible to a wider range of people with disabilities, including blindness and low
+   vision, deafness and hearing loss, learning disabilities, cognitive limitations, limited
+   movement, speech disabilities, photosensitivity and combinations of these. Following these
+   guidelines will also often make your Web content more usable to users in
+   general.
Authoring Tool Accessibility Guidelines (ATAG) 2.0 [ATAG]
This specification provides guidelines for designing Web content
+   authoring tools that are more accessible for people with disabilities. An authoring tool that
+   conforms to these guidelines will promote accessibility by providing an accessible user interface
+   to authors with disabilities as well as by enabling, supporting, and promoting the production of
+   accessible Web content by all authors.
User Agent Accessibility Guidelines (UAAG) 2.0 [UAAG]
This document provides guidelines for designing user agents that
+   lower barriers to Web accessibility for people with disabilities. User agents include browsers
+   and other types of software that retrieve and render Web content. A user agent that conforms to
+   these guidelines will promote accessibility through its own user interface and through other
+   internal facilities, including its ability to communicate with other technologies (especially
+   assistive technologies). Furthermore, all users, not just users with disabilities, should find
+   conforming user agents to be more usable.

+
+
+
+  
2 Common infrastructure

+
+  
This specification depends on the WHATWG Infra standard. [INFRA]

+
+  
2.1 Terminology

+
+  
This specification refers to both HTML and XML attributes and IDL 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 IDL
+  attributes for those defined on IDL interfaces. Similarly, the term "properties" is used for
+  both JavaScript object properties and CSS properties. When these are ambiguous they are qualified
+  as object properties and CSS properties respectively.

+
+  
Generally, when the specification states that a feature applies to the HTML syntax
+  or the XML syntax, 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 XML)".

+
+  
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. The term is used to refer both to Document
+  objects and their descendant DOM trees, and to serialized byte streams using the HTML syntax or the XML syntax, depending
+  on context.

+
+  
In the context of the DOM structures, the terms HTML
+  document and XML document are used as defined in the DOM
+  specification, and refer specifically to two different modes that Document objects
+  can find themselves in. [DOM] (Such uses are always hyperlinked to their
+  definition.)

+
+  
In the context of byte streams, the term HTML document refers to resources labeled as
+  text/html, and the term XML document refers to resources labeled with an XML
+  MIME type.

+
+  

+
+  
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.

+
+  
+
+  
When an algorithm B says to return to another algorithm A, it implies that A called B. Upon
+  returning to A, the implementation must continue from where it left off in calling B. Some
+  algorithms run in parallel; this means that the algorithm's subsequent
+  steps are to be run, one after another, at the same time as other logic in the specification (e.g.
+  at the same time as the event loop). This specification does not define the precise
+  mechanism by which this is achieved, be it time-sharing cooperative multitasking, fibers, threads,
+  processes, using different hyperthreads, cores, CPUs, machines, etc. By contrast, an operation
+  that is to run immediately must interrupt the currently running task, run itself, and
+  then resume the previously running task.

+
+  
+
+  
+  
The term "transparent black" refers to the color with red, green, blue, and alpha channels all
+  set to zero.

+
+
+  
2.1.1 Resources

+
+  
The specification uses the term supported when referring to whether a user
+  agent has an implementation capable of decoding the semantics of an external resource. A format or
+  type is said to be supported if the implementation can process an external resource of that
+  format or type without critical aspects of the resource being ignored. Whether a specific resource
+  is supported can depend on what features of the resource's format are in use.

+
+  
For example, a PNG image would be considered to be in a supported format if its
+  pixel data could be decoded and rendered, even if, unbeknownst to the implementation, the image
+  also contained animation data.

+
+  
An MPEG-4 video file would not be considered to be in a supported format if the
+  compression format used was not supported, even if the implementation could determine the
+  dimensions of the movie from the file's metadata.

+
+  
What some specifications, in particular the HTTP specification, refer to as a
+  representation is referred to in this specification as a resource.
+  [HTTP]

+
+  
A resource's critical subresources are those that the resource needs to have
+  available to be correctly processed. Which resources are considered critical or not is defined by
+  the specification that defines the resource's format.

+
+
+  
2.1.2 XML compatibility

+
+  
To ease migration from HTML to XML, 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 "HTML elements" refers to any element in that namespace,
+  even in XML documents.

+
+  
Except where otherwise stated, all elements defined or mentioned in this specification are in
+  the HTML namespace ("http://www.w3.org/1999/xhtml"), and all
+  attributes defined or mentioned in this specification have no namespace.

+
+  
The term element type is used to refer to the set of elements that have a given
+  local name and namespace. For example, button elements are elements with the element
+  type button, meaning they have the local name "button" and
+  (implicitly as defined above) the HTML namespace.

+
+  
Attribute names are said to be XML-compatible if they match the Name production defined in XML and they contain no U+003A COLON
+  characters (:). [XML]

+
+
+  
2.1.3 DOM trees

+
+  
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.

+
+  
A content attribute is said to change value only if its new value is
+  different than its previous value; setting an attribute to a value it already has does not change
+  it.

+
+  
The term empty, when used for an attribute value, Text node,
+  or string, means that the length of the text is zero (i.e., not even containing controls or U+0020 SPACE).

+
+  
An element's child text content is the concatenation of the data of all the Text nodes that are children of the
+  element (ignoring any other nodes such as comments or elements), in tree order.

+
+  
A node A is inserted into a node B
+  when the insertion steps are invoked with
+  A as the argument and A's new parent is B. Similarly, a node A is removed from a node B when the
+  removing steps are invoked with A as the
+  removedNode argument and B as the oldParent argument.

+
+  
A node is
+  inserted into a document when the insertion
+  steps are invoked with it as the argument and it is now in a document tree.
+  Analogously, a node is
+  removed from a document when the removing
+  steps are invoked with it as the argument and it is now no longer in a document
+  tree.

+
+  
A node becomes connected when the insertion steps are invoked with it as the argument and it
+  is now connected. Analogously, a node becomes disconnected when the removing
+  steps are invoked with it as the argument and it is now no longer
+  connected.

+
+  
A node is browsing-context connected when it is
+  connected and its shadow-including root
+  has a browsing context. A node becomes browsing-context connected when the insertion steps are invoked with it as the argument and it
+  is now browsing-context connected. A node becomes browsing-context disconnected either when the removing steps are invoked with it as the argument and it
+  is now no longer browsing-context connected, or when its shadow-including
+  root no longer has a browsing context.
+
+
+  
2.1.4 Scripting

+
+  
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".

+
+  
An IDL 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 the attributes and methods on that object
+  must operate on the actual underlying data, not a snapshot of the
+  data.

+
+
+  
2.1.5 Plugins

+
+  
The term plugin refers to a user-agent defined set of content handlers used by the
+  user agent that can take part in the user agent's rendering of a Document object, but
+  that neither act as child browsing contexts of the
+  Document nor introduce any Node objects to the Document's
+  DOM.

+
+  
Typically such content handlers are provided by third parties, though a user agent can also
+  designate built-in content handlers as plugins.

+
+  
+
+  
A user agent must not consider the types text/plain and
+  application/octet-stream as having a registered plugin.
 
+
+  
+
+  
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. Indeed, this specification doesn't require user agents to
+  support plugins at all. [NPAPI]

+
+  
A plugin can be secured if it honors the semantics of
+  the sandbox attribute.

+
+  
For example, a secured plugin would prevent its contents from creating pop-up
+  windows when the plugin is instantiated inside a sandboxed iframe.

+
+  
+
+  
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.

+
+  
Since different users having different sets of plugins provides a
+  fingerprinting vector that increases the chances of users being uniquely identified, user agents
+  are encouraged to support the exact same set of plugins for each
+  user.
+  (This is a fingerprinting vector.)
+  

+
+  
+
+
+
+  
2.1.6 Character encodings

+
+  
A character
+  encoding, or just encoding where that is not ambiguous, is a defined way to convert
+  between byte streams and Unicode strings, as defined in the WHATWG Encoding standard. An
+  encoding has an encoding
+  name and one or more encoding labels, referred to as the
+  encoding's name and labels in the Encoding standard. [ENCODING]

+
+  
A UTF-16 encoding is UTF-16BE or UTF-16LE. [ENCODING]

+
+  
An ASCII-compatible encoding is any encoding that is not a
+  UTF-16 encoding. [ENCODING]

+
+  
Since support for encodings that are not defined in the WHATWG Encoding standard
+  is prohibited, UTF-16 encodings are the only encodings that
+  this specification needs to treat as not being ASCII-compatible encodings.
+
+
+
+  

+
+  
2.1.7 Conformance classes

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

+
+  
Conforming documents are those that comply with all the conformance criteria for
+  documents. For readability, some of these conformance requirements are phrased as conformance
+  requirements on authors; such requirements are implicitly requirements on documents: by
+  definition, all documents are assumed to have had an author. (In some cases, that author may
+  itself be a user agent — such user agents are subject to additional rules, as explained
+  below.)

+
+  
For example, if a requirement states that "authors must not
+  use the foobar element", it would imply that documents are not allowed to
+  contain elements named foobar.

+
+  
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 the XML syntax 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 Web browser would, upon finding a script element in
+    an XML document, execute the script contained in that element. However, if the element is found
+    within a transformation expressed in XSLT (assuming the user agent 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 the HTML syntax must process documents labeled with an
+    HTML MIME type as described in this specification, so that users can interact with
+    them.

+
+    
User agents that support scripting must also be conforming implementations of the IDL
+    fragments in this specification, as described in the Web IDL specification. [WEBIDL]

+
+    
Unless explicitly stated, specifications that override the semantics of HTML
+    elements do not override the requirements on DOM objects representing those elements. For
+    example, the script element in the example above would still implement the
+    HTMLScriptElement interface.

+
+   
Non-interactive presentation user agents

+
+    
User agents that process HTML and XML 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.

+
+   
Visual user agents that support the suggested default rendering

+
+    
User agents, whether interactive or not, may be designated (possibly as a user option) as
+    supporting the suggested default rendering defined by this specification.

+
+    
This is not required. In particular, even user agents that do implement the suggested default
+    rendering are encouraged to offer settings that override this default to improve the experience
+    for the user, e.g. changing the color contrast, using different focus styles, or otherwise
+    making the experience more accessible and usable to the user.

+
+    
User agents that are designated as supporting the suggested default rendering must, while so
+    designated, implement the rules the rendering section defines as the
+    behavior that user agents are expected to implement.

+
+   
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. [COMPUTABLE])

+
+    
The term "HTML 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:

+
+     
  1. Criteria that can be expressed in a DTD.
  2. Criteria that cannot be expressed by a DTD, but can still be checked by a machine.
  3. 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 XML documents for reasons other than to either
+    render the documents or check them for conformance should act in accordance with 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. However, authoring tools must not automatically misuse elements or encourage
+    their users to do so.

+
+    
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. This does not mean,
+    though, that authoring tools can use address elements for any block of italics text
+    (for instance); it just means that the authoring tool doesn't have to verify that when the user
+    uses a tool for inserting contact information for a section, that the user really is doing that
+    and not inserting something else instead.

+
+    
In terms of conformance checking, an editor has 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.

+
+   

+
+  
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.
+  (This is a fingerprinting vector.)
+  

+
+  
For compatibility with existing content and prior specifications, this specification describes
+  two authoring formats: one based on XML, and one using a custom format inspired by SGML (referred to as the HTML syntax).
+  Implementations must support at least one of these two formats, although supporting both is
+  encouraged.

+
+  
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. Those in the former category are requirements on
+  documents and authoring tools. Those in the second category are requirements on user agents.
+  Similarly, some conformance requirements are phrased as requirements on authors; such requirements
+  are to be interpreted as conformance requirements on the documents that authors produce. (In other
+  words, this specification does not distinguish between conformance criteria on authors and
+  conformance criteria on documents.)

+
+  
+
+
+  
2.1.8 Dependencies

+
+  

+
+  
This specification relies on several other underlying specifications.

+
+  
Infra

+    
The following terms are defined in the WHATWG Infra standard: [INFRA]

+
+    
+
+   
Unicode and Encoding

+
+    
The Unicode character set is used to represent textual data, and the WHATWG Encoding standard
+    defines requirements around character encodings. [UNICODE]

+
+    
This specification introduces terminology
+    based on the terms defined in those specifications, as described earlier.

+
+    
The following terms are used as defined in the WHATWG Encoding standard: [ENCODING]

+
+    
+
+   
XML and related specifications

+
+    
Implementations that support the XML syntax for HTML must support some version
+    of XML, as well as its corresponding namespaces specification, because that syntax uses an XML
+    serialization with namespaces. [XML] [XMLNS]

+
+    
Data mining tools and other user agents that perform operations on content without running
+    scripts, evaluating CSS or XPath expressions, or otherwise exposing the resulting DOM to
+    arbitrary content, may "support namespaces" by just asserting that their DOM node analogues are
+    in certain namespaces, without actually exposing the namespace strings.

+
+    
In the HTML syntax, namespace prefixes and namespace declarations
+    do not have the same effect as in XML. For instance, the colon has no special meaning in HTML
+    element names.

+
+    

+
+    
The attribute with the tag name xml:space in
+    the XML namespace is defined by the XML specification. [XML]

+
+    
The Name production is defined in the XML specification. [XML]

+
+    
This specification also references the <?xml-stylesheet?>
+    processing instruction, defined in the Associating Style Sheets with XML documents
+    specification. [XMLSSPI]

+
+    
This specification also non-normatively mentions the XSLTProcessor
+    interface and its transformToFragment() and transformToDocument() methods. [XSLTP]

+
+   
URLs

+
+    
The following terms are defined in the WHATWG URL standard: [URL]

+
+    
+
+    
A number of schemes and protocols are referenced by this specification also:

+
+    
+
+    
Media fragment
+    syntax is defined in the Media Fragments URI specification. [MEDIAFRAG]

+   
HTTP and related specifications

+
+    
The following terms are defined in the HTTP specifications: [HTTP]

+
+    
+
+    
The following terms are defined in the Cookie specification: [COOKIES]

+
+    
  • cookie-string
  • receives a set-cookie-string
  • `Cookie` header

+
+    
The following term is defined in the Web Linking specification: [WEBLINK]

+
+    
+
+    
The following terms are defined in the WHATWG MIME Sniffing standard: [MIMESNIFF]

+
+    
+
+   
Fetch

+
+    
The following terms are defined in the WHATWG Fetch standard: [FETCH]

+
+    
+
+    
The following terms are defined in Referrer Policy: [REFERRERPOLICY]

+
+    
+
+    
The following terms are defined in Mixed Content: [MIX]

+
+    
+
+   
Web IDL

+
+    
The IDL fragments in this specification must be interpreted as required for conforming IDL
+    fragments, as described in the Web IDL specification. [WEBIDL]

+
+    
The following terms are defined in the Web IDL specification:

+
+    
+
+    
The Web IDL specification also defines the following types that are used in Web IDL fragments
+    in this specification:

+
+    
+
+    
The term throw in this
+    specification is used as defined in the Web IDL specification. The DOMException
+    type and the following exception names are defined by Web IDL and used by this
+    specification:

+
+    
+
+    
When this specification requires a user agent to create a Date object
+    representing a particular time (which could be the special value Not-a-Number), the milliseconds
+    component of that time, if any, must be truncated to an integer, and the time value of the newly
+    created Date object must represent the resulting truncated time.

+
+    
For instance, given the time 23045 millionths of a second after 01:00 UTC on
+    January 1st 2000, i.e. the time 2000-01-01T00:00:00.023045Z, then the Date object
+    created representing that time would represent the same time as that created representing the
+    time 2000-01-01T00:00:00.023Z, 45 millionths earlier. If the given time is NaN, then the result
+    is a Date object that represents a time value NaN (indicating that the object does
+    not represent a specific instant of time).

+
+   
JavaScript

+
+    
Some parts of the language described by this specification only support JavaScript as the
+    underlying scripting language. [JAVASCRIPT]

+
+    
Users agents that support JavaScript must also implement the ECMAScript
+    Internationalization API Specification. [JSINTL]

+
+    
The term "JavaScript" is used to refer to ECMA-262, rather than the official
+    term ECMAScript, since the term JavaScript is more widely known. Similarly, the MIME
+    type used to refer to JavaScript in this specification is text/javascript, since that is the most commonly used type, despite it being an officially obsoleted type according to RFC
+    4329. [RFC4329]

+
+    
The following terms are defined in the JavaScript specification and used in this
+    specification:

+
+    
+
+   
DOM

+
+    
The Document Object Model (DOM) is a representation — a model — of a document and
+    its content. 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. [DOM]

+
+    
Implementations must support DOM and the events defined in UI Events, because this
+    specification is defined in terms of the DOM, and some of the features are defined as extensions
+    to the DOM interfaces. [DOM] [UIEVENTS]

+
+    
In particular, the following features are defined in the WHATWG DOM standard: [DOM]

+
+    
+
+    
The following features are defined in the UI Events specification: [UIEVENTS]

+
+    
+
+    
The following features are defined in the Touch Events specification: [TOUCH]

+
+    
+
+    
The following features are defined in the Pointer Events specification: [POINTEREVENTS]

+
+    
+
+    
The following features are defined in the auxclick specification: [AUXCLICK]

+
+    
+
+    
This specification sometimes uses the term name to refer to the event's
+    type; as in, "an event named click" or "if the event name is keypress". The terms
+    "name" and "type" for events are synonymous.

+
+    
The following features are defined in the DOM Parsing and Serialization
+    specification: [DOMPARSING]

+
+    
+
+    
The Selection
+    interface is defined in the Selection API specification. [SELECTION]

+
+    
User agents are encouraged to implement the features described in the
+    execCommand specification. [EXECCOMMAND]

+
+    
The following parts of the WHATWG Fullscreen API standard are referenced from this
+    specification, in part to define the rendering of dialog elements, and also to
+    define how the Fullscreen API interacts with HTML: [FULLSCREEN]

+
+    
+
+    
The High Resolution Time specification provides the DOMHighResTimeStamp
+    typedef and the Performance
+    interface's now()
+    method. [HRT]

+
+   
File API

+
+    
This specification uses the following features defined in the File API specification: [FILEAPI]

+
+    
+
+   
Indexed Database API
This specification uses cleanup
+   Indexed Database transactions defined by the Indexed Database API specification. [INDEXEDDB]

+
+
+
+   
Media Source Extensions

+
+    
The following terms are defined in the Media Source Extensions specification: [MEDIASOURCE]

+
+    
+
+   
Media Capture and Streams

+
+    
The following terms are defined in the Media Capture and Streams specification: [MEDIASTREAM]

+
+    
+
+   
XMLHttpRequest

+
+    
This specification references the XMLHttpRequest specification to describe how the two
+    specifications interact and to use its ProgressEvent features. The following
+    features and terms are defined in the XMLHttpRequest specification: [XHR]

+
+    
+
+   
Battery Status

+
+    
The following features are defined in the Battery Status API specification: [BATTERY]

+
+    
+
+   
Media Queries

+
+    
Implementations must support Media Queries. The <media-condition>
+    feature is defined therein. [MQ]

+
+   
CSS modules

+
+    
While support for CSS as a whole is not required of implementations of this specification
+    (though it is encouraged, at least for Web browsers), some features are defined in terms of
+    specific CSS requirements.

+
+    
When this specification requires that something be parsed
+    according to a particular CSS grammar, the relevant algorithm in the CSS Syntax
+    specification must be followed. [CSSSYNTAX]

+
+    
In particular, some features require that a string be parsed as a CSS <color>
+    value. When parsing a CSS value, user agents are required by the CSS specifications to
+    apply some error handling rules. These apply to this specification also. [CSSCOLOR]
+    [CSS]

+
+    
For example, user agents are required to close all open constructs upon
+    finding the end of a style sheet unexpectedly. Thus, when parsing the string "rgb(0,0,0" (with a missing close-parenthesis) for a color value, the close
+    parenthesis is implied by this error handling rule, and a value is obtained (the color 'black').
+    However, the similar construct "rgb(0,0," (with both a missing
+    parenthesis and a missing "blue" value) cannot be parsed, as closing the open construct does not
+    result in a viable value.

+
+    
The following terms and features are defined in the CSS specification: [CSS]

+
+    
+
+    
The CSS specification also defines the following border properties: [CSS]

+
+    
Border properties
+     

+       Top
+       Bottom
+       Left
+       Right
+      
Width
+       'border-top-width'
+       'border-bottom-width'
+       'border-left-width'
+       'border-right-width'
+      
Style
+       'border-top-style'
+       'border-bottom-style'
+       'border-left-style'
+       'border-right-style'
+      
Color
+       'border-top-color'
+       'border-bottom-color'
+       'border-left-color'
+       'border-right-color'
+    

+
+    
The terms intrinsic width and intrinsic height refer to the width dimension and the height
+    dimension, respectively, of intrinsic dimensions.

+
+    
The basic version of the 'display' property
+    is defined in the CSS specification, and the property is extended by other CSS
+    modules. [CSS] [CSSRUBY] [CSSTABLE]

+
+    
The following terms and features are defined in the CSS Logical Properties
+    specification: [CSSLOGICAL]

+
+    
+
+    
The following terms and features are defined in the CSS Color specification:
+    [CSSCOLOR]

+
+    
+
+    
The term paint
+    source is used as defined in the CSS Image Values and Replaced Content
+    specification to define the interaction of certain HTML elements with the CSS 'element()'
+    function. [CSSIMAGES]

+
+    
The term default
+    object size and the 'object-fit' property
+    are also defined in the CSS Image Values and Replaced Content specification. [CSSIMAGES]

+
+    
The following features are defined in the CSS Backgrounds and Borders
+    specification: [CSSBG]

+
+    
+
+    
The term block-level is defined in
+    the CSS Display specification. [CSSDISPLAY]

+
+    
The following features are defined in the CSS Fonts specification: [CSSFONTS]

+
+    
+
+    
The 'list-style-type'
+    property is defined in the CSS Lists and Counters specification. [CSSLISTS]

+
+    
The 'overflow' property
+    and its 'hidden' value
+    are defined in the CSS Overflow specification. [CSSOVERFLOW]

+
+    
The following features are defined in the CSS Positioned Layout specification:
+    [CSSPOSITION]

+
+    
+
+    
The 'ruby-base'
+    value of the 'display' property is defined in the CSS Ruby Layout
+    specification. [CSSRUBY]

+
+    
The following features are defined in the CSS Table specification: [CSSTABLE]

+
+    
+
+    
The following features are defined in the CSS Text specification: [CSSTEXT]

+
+    
+
+    
The following features are defined in the CSS Writing Modes specification: [CSSWM]

+
+    
+
+    
The following features are defined in the CSS Basic User Interface
+    specification: [CSSUI]

+
+    
+
+    
Implementations that support scripting must support the CSS Object Model. The following
+    features and terms are defined in the CSSOM specifications: [CSSOM] [CSSOMVIEW]
+
+    

+
+    
The following features and terms are defined in the CSS Syntax specifications:
+    [CSSSYNTAX]

+
+    
+
+    
The following terms are defined in the Selectors specification: [SELECTORS]

+
+    
+
+    
The following features are defined in the CSS Values and Units specification:
+    [CSSVALUES]

+
+    
+
+    
The term style attribute is
+    defined in the CSS Style Attributes specification. [CSSATTR]

+
+    
The following terms are defined in the CSS Cascading and Inheritance
+    specification: [CSSCASCADE]

+
+    
+
+    
The CanvasRenderingContext2D object's use of fonts depends on the features
+    described in the CSS Fonts and Font Loading specifications, including
+    in particular FontFace objects and the font source concept.
+    [CSSFONTS] [CSSFONTLOAD]

+
+    
The following interfaces and terms are defined in the Geometry Interfaces Module specification: [GEOMETRY]

+
+    
+
+   
Intersection Observer

+
+    
The following term is defined in the Intersection Observer specification: [INTERSECTIONOBSERVER]

+
+    
+
+   
WebGL

+
+    
The following interface is defined in the WebGL specification: [WEBGL]

+
+    
+
+   
WebVTT

+
+    
Implementations may support WebVTT as a text track format for subtitles, captions, chapter
+    titles, metadata, etc, for media resources. [WEBVTT]

+
+    
The following terms, used in this specification, are defined in the WebVTT specification:

+
+    
+
+   
The WebSocket protocol

+    
The following terms are defined in the WHATWG Fetch standard: [FETCH]

+
+    
+
+    
The following terms are defined in the WebSocket protocol specification: [WSP]

+
+    
  • the WebSocket connection is established
  • extensions in use
  • subprotocol in use
  • a WebSocket message has been received
  • send a WebSocket Message
  • fail the WebSocket connection
  • close the WebSocket connection
  • start the WebSocket closing handshake
  • the WebSocket closing handshake is started
  • the WebSocket connection is closed (possibly cleanly)
  • the WebSocket connection close code
  • the WebSocket connection close reason
  • Sec-WebSocket-Protocol field

+
+   
ARIA

+
+    
The role attribute is defined in the ARIA
+    specification, as are the following roles: [ARIA]

+
+    
+
+    
In addition, the following aria-* content
+    attributes are defined in the ARIA specification: [ARIA]

+
+    
+
+    
Finally, the following terms are defined in the ARIA specification: [ARIA]

+
+    
+
+   
Content Security Policy

+
+    
The following terms are defined in Content Security Policy: [CSP]

+
+    
+
+   
Service Workers

+
+    
The following terms are defined in Service Workers: [SW]

+
+    
+
+   
Secure Contexts

+
+    
The following terms are defined in Secure Contexts: [SECURE-CONTEXTS]

+
+    
+
+   
Payment Request API

+    
The following feature is defined in the Payment Request API specification:
+    [PAYMENTREQUEST]

+
+    
+   
MathML

+    
While support for MathML as a whole is not required by this specification (though it is
+    encouraged, at least for Web browsers), certain features depend upon small parts of MathML being
+    implemented. [MATHML]

+
+    
The following features are defined in the MathML specification:

+
+    
+   
SVG

+    
While support for SVG as a whole is not required by this specification (though it is
+    encouraged, at least for Web browsers), certain features depend upon parts of SVG being
+    implemented.

+
+    
Also, the SVG specifications do not reflect implementation reality. Implementations implement
+    subsets of SVG 1.1 and SVG Tiny 1.2. Although it is hoped that the in-progress SVG 2
+    specification is a more realistic target for implementations, until that specification is ready,
+    user agents that implement SVG must do so with the following willful violations and additions. [SVG] [SVGTINY12] [SVG2]

+
+    
User agents that implement SVG must not implement the following features from SVG 1.1:

+
+    
  • The tref element
  • The cursor element (use CSS's cursor property
+     instead)
  • The font-defining SVG elements: font, glyph,
+     missing-glyph, hkern, vkern, font-face, font-face-src,
+     font-face-uri, font-face-format, and font-face-name (use CSS's @font-face instead)
  • The externalResourcesRequired attribute
  • The enable-background property
  • The contentScriptType and contentStyleType
+     attributes (use the type attribute on the SVG
+     script and style elements instead)

+
+    
User agents that implement SVG must implement the following features from SVG Tiny 1.2:

+
+    
  • The non-scaling-stroke value for the vector-effect property
  • The class attribute is allowed on all SVG elements
  • The tabindex attribute is allowed on visible SVG elements
  • The ARIA accessibility attributes are allowed on all SVG elements

+
+    
The following features are defined in the SVG specifications:

+
+    
+   
Filter Effects

+    
The following feature is defined in the Filter Effects specification:
+    [FILTERS]

+
+    
+   
Worklets

+    
The following feature is defined in the Worklets specification: [WORKLETS]

+
+    
+   

+
+  

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

+
+  
A user agent that implements the HTTP protocol must implement HTTP State Management
+  Mechanism (Cookies) as well. [HTTP] [COOKIES]

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

+
+  

+
+
+
+
+  
2.1.9 Extensibility

+
+  
Vendor-specific proprietary user agent extensions to this specification are strongly
+  discouraged. Documents must not use such extensions, as doing so reduces interoperability and
+  fragments the user base, allowing only users of specific user agents to access the content in
+  question.

+
+  
+
+  
All extensions must be defined so that the use of extensions neither contradicts nor causes the
+  non-conformance of functionality defined in the specification.
 
+
+  

+
+   
For example, while strongly discouraged from doing so, an implementation could add a new IDL
+   attribute "typeTime" to a control that returned the time it took the user
+   to select the current value of a control (say). On the other hand, defining a new control that
+   appears in a form's elements array would be in violation
+   of the above requirement, as it would violate the definition of elements given in this specification.

+
+  

+
+  
+
+  

+
+  
When vendor-neutral extensions to this specification are needed, either this specification can
+  be updated accordingly, or an extension specification can be written that overrides the
+  requirements in this specification. When someone applying this specification to their activities
+  decides that they will recognize the requirements of such an extension specification, it becomes
+  an applicable specification for the purposes
+  of conformance requirements in this specification.

+
+  
Someone could write a specification that defines any arbitrary byte stream as
+  conforming, and then claim that their random junk is conforming. However, that does not mean that
+  their random junk actually is conforming for everyone's purposes: if someone else decides that
+  that specification does not apply to their work, then they can quite legitimately say that the
+  aforementioned random junk is just that, junk, and not conforming at all. As far as conformance
+  goes, what matters in a particular community is what that community agrees is
+  applicable.

+
+  
+
+  

+
+  
User agents must treat elements and attributes that they do not understand as semantically
+  neutral; leaving them in the DOM (for DOM processors), and styling them according to CSS (for CSS
+  processors), but not inferring any meaning from them.

+
+
+  
When support for a feature is disabled (e.g. as an emergency measure to mitigate a security
+  problem, or to aid in development, or for performance reasons), user agents must act as if they
+  had no support for the feature whatsoever, and as if the feature was not mentioned in this
+  specification. For example, if a particular feature is accessed via an attribute in a Web IDL
+  interface, the attribute itself would be omitted from the objects that implement that interface
+  — leaving the attribute on the object but making it return null or throw an exception is
+  insufficient.

+
+
+  
+
+
+  
+
+  
2.1.10 Interactions with XPath and XSLT
Spec bugs: 18460

+
+  
Implementations of XPath 1.0 that operate on HTML
+  documents parsed or created in the manners described in this specification (e.g. as part of
+  the document.evaluate() API) must act as if the following edit was applied
+  to the XPath 1.0 specification.

+
+  
First, remove this paragraph:

+
+  

+
+   
A QName in the node test is expanded
+   into an expanded-name
+   using the namespace declarations from the expression context. This is the same way expansion is
+   done for element type names in start and end-tags except that the default namespace declared with
+   xmlns is not used: if the QName does not have a prefix, then the
+   namespace URI is null (this is the same way attribute names are expanded). It is an error if the
+   QName has a prefix for which there is
+   no namespace declaration in the expression context.

+
+  

+
+  
Then, insert in its place the following:

+
+  

+
+   
A QName in the node test is expanded into an expanded-name using the namespace declarations
+   from the expression context. If the QName has a prefix, then there must be a namespace declaration for this prefix in
+   the expression context, and the corresponding namespace URI is the one that is
+   associated with this prefix. It is an error if the QName has a prefix for which there is no
+   namespace declaration in the expression context. 

+
+   
If the QName has no prefix and the principal node type of the axis is element, then the
+   default element namespace is used. Otherwise if the QName has no prefix, the namespace URI is
+   null. The default element namespace is a member of the context for the XPath expression. The
+   value of the default element namespace when executing an XPath expression through the DOM3 XPath
+   API is determined in the following way:

+
+   
  1. If the context node is from an HTML DOM, the default element namespace is
+    "http://www.w3.org/1999/xhtml".
  2. Otherwise, the default element namespace URI is null.

+
+   
This is equivalent to adding the default element namespace feature of XPath 2.0
+   to XPath 1.0, and using the HTML namespace as the default element namespace for HTML documents.
+   It is motivated by the desire to have implementations be compatible with legacy HTML content
+   while still supporting the changes that this specification introduces to HTML regarding the
+   namespace used for HTML elements, and by the desire to use XPath 1.0 rather than XPath 2.0.

+
+  

+
+  
This change is a willful violation of the XPath 1.0 specification,
+  motivated by desire to have implementations be compatible with legacy content while still
+  supporting the changes that this specification introduces to HTML regarding which namespace is
+  used for HTML elements. [XPATH10]
 
+
+  

+
+  
XSLT 1.0 processors outputting to a DOM when the output
+  method is "html" (either explicitly or via the defaulting rule in XSLT 1.0) are affected as
+  follows:

+
+  
If the transformation program outputs an element in no namespace, the processor must, prior to
+  constructing the corresponding DOM element node, change the namespace of the element to the
+  HTML namespace, ASCII-lowercase the
+  element's local name, and ASCII-lowercase the
+  names of any non-namespaced attributes on the element.

+
+  
This requirement is a willful violation of the XSLT 1.0
+  specification, required because this specification changes the namespaces and case-sensitivity
+  rules of HTML in a manner that would otherwise be incompatible with DOM-based XSLT
+  transformations. (Processors that serialize the output are unaffected.) [XSLT10]
 
+
+  

+
+  
This specification does not specify precisely how XSLT processing interacts with the HTML
+  parser infrastructure (for example, whether an XSLT processor acts as if it puts any
+  elements into a stack of open elements). However, XSLT processors must stop
+  parsing if they successfully complete, and must set the current document
+  readiness first to "interactive" and then to "complete" if they are aborted.

+
+  

+
+  
This specification does not specify how XSLT interacts with the navigation algorithm, how it fits in with the event loop, nor
+  how error pages are to be handled (e.g. whether XSLT errors are to replace an incremental XSLT
+  output, or are rendered inline, etc).

+
+  
There are also additional non-normative comments regarding the interaction of XSLT
+  and HTML in the script element section, and of
+  XSLT, XPath, and HTML in the template element
+  section.

+
+  
+
+
+
+
+  
2.2 Case-sensitivity and string comparison

+
+  
Comparing two strings in a case-sensitive manner means comparing them
+  exactly, code point for code point.

+
+  
Except where otherwise stated, string comparisons must be performed in a
+  case-sensitive manner.

+
+  
A string pattern is a prefix match for a string s when
+  pattern is not longer than s and truncating s to
+  pattern's length leaves the two strings as matches of each other.

+
+
+
+  
2.3 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.

+
+  
+
+  
Implementors are strongly urged to carefully examine any third-party libraries
+  they might consider using to implement the parsing of syntaxes described below. For example, date
+  libraries are likely to implement error handling behavior that differs from what is required in
+  this specification, since error-handling behavior is often not defined in specifications that
+  describe date syntaxes similar to those used in this specification, and thus implementations tend
+  to vary greatly in how they handle errors.

+
+  
+
+
+  
+
+  
2.3.1 Common parser idioms

+
+  
+
+  
The White_Space characters are those that have the Unicode
+  property "White_Space" in the Unicode PropList.txt data file. [UNICODE]

+
+  
This is not to be confused with the "White_Space" value (abbreviated "WS") of the
+  "Bidi_Class" property in the Unicode.txt data file.

+
+  
+
+  
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.

+
+  
+
+
+
+  
2.3.2 Boolean attributes

+
+  
A number of attributes 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 an
+  ASCII case-insensitive match for the attribute's canonical name, with no leading or
+  trailing whitespace.

+
+  
The values "true" and "false" are not allowed on boolean attributes. To represent
+  a false value, the attribute has to be omitted altogether.

+
+  

+
+   
Here is an example of a checkbox that is checked and disabled. The checked and disabled
+   attributes are the boolean attributes.

+
+   
<label><input type=checkbox checked name=cheese disabled> Cheese</label>

+
+   
This could be equivalently written as this:
+
+   
<label><input type=checkbox checked=checked name=cheese disabled=disabled> Cheese</label>

+
+   
You can also mix styles; the following is still equivalent:

+
+   
<label><input type='checkbox' checked name=cheese disabled=""> Cheese</label>

+
+  

+
+
+
+  
2.3.3 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 an ASCII
+  case-insensitive match for one of the given keywords that are not said to be
+  non-conforming, with no leading or trailing whitespace.

+
+  
When the attribute is specified, if its value is an ASCII case-insensitive match
+  for 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 mean that there is no state represented.

+
+  
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 a valid keyword.

+
+
+  
2.3.4 Numbers

+
+  
2.3.4.1 Signed integers

+
+  
A string is a valid integer if it consists of one or more ASCII digits,
+  optionally prefixed with a U+002D HYPHEN-MINUS character (-).

+
+  
A valid integer without a U+002D HYPHEN-MINUS (-) prefix represents the number
+  that is represented in base ten by that string of digits. A valid integer
+  with a U+002D HYPHEN-MINUS (-) prefix represents the number represented in base ten by
+  the string of digits that follows the U+002D HYPHEN-MINUS, subtracted from zero.

+
+  
+
+  
The rules for parsing 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 return either an integer or an error.

+
+  
  1. Let input be the string being parsed.
  2. Let position be a pointer into input, initially pointing at the
+   start of the string.
  3. Let sign have the value "positive".
  4. Skip ASCII whitespace within input given
+   position.
  5. If position is past the end of input, return an error.
  6. 
+
+    
    If the character indicated by position (the first character) is a U+002D
+    HYPHEN-MINUS character (-):
    
+
+    
    1. Let sign be "negative".
    2. Advance position to the next character.
    3. If position is past the end of input, return an error.
    
+
+    
    Otherwise, if the character indicated by position (the first character) is a
+    U+002B PLUS SIGN character (+):
    
+
+    
    1. Advance position to the next character. (The "+" is
+     ignored, but it is not conforming.)
    2. If position is past the end of input, return an error.
    
+
+   
  7. If the character indicated by position is not an ASCII digit, then return an error.
  8. Collect a sequence of code points that are ASCII digits from
+   input given position, and interpret the resulting sequence as a base-ten
+   integer. Let value be that integer.
  9. If sign is "positive", return value, otherwise return the result of
+   subtracting value from zero.

+
+  
+
+
+  
2.3.4.2 Non-negative integers

+
+  
A string is a valid non-negative integer if it consists of one or more ASCII
+  digits.

+
+  
A valid non-negative integer represents the number that is represented in base ten
+  by that string of digits.

+
+  
+
+  
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 return either zero, a positive integer, or an error.

+
+  
  1. Let input be the string being parsed.
  2. Let value be the result of parsing input using the
+   rules for parsing integers.
  3. If value is an error, return an error.
  4. If value is less than zero, return an error.
  5. Return value.

+
+  
+
+  
+
+
+  
2.3.4.3 Floating-point numbers

+
+  
A string is a valid floating-point number if it consists of:

+
+  
  1. Optionally, a U+002D HYPHEN-MINUS character (-).
  2. One or both of the following, in the given order:
+
+    
    1. A series of one or more ASCII digits.
    2. Both of the following, in the given order:
+
+      
      1. A single U+002E FULL STOP character (.).
      2. A series of one or more ASCII digits.
      
+
+     
    
+
+   
  3. Optionally:
+
+    
    1. Either a U+0065 LATIN SMALL LETTER E character (e) or a U+0045 LATIN CAPITAL LETTER E
+     character (E).
    2. Optionally, a U+002D HYPHEN-MINUS character (-) or U+002B PLUS SIGN character (+).
    3. A series of one or more ASCII digits.
    
+
+   

+
+  
A valid floating-point number represents the number obtained by multiplying the
+  significand by ten raised to the power of the exponent, where the significand is the first number,
+  interpreted as base ten (including the decimal point and the number after the decimal point, if
+  any, and interpreting the significand as a negative number if the whole string starts with a
+  U+002D HYPHEN-MINUS character (-) and the number is not zero), and where the exponent is the
+  number after the E, if any (interpreted as a negative number if there is a U+002D HYPHEN-MINUS
+  character (-) between the E and the number and the number is not zero, or else ignoring a U+002B
+  PLUS SIGN character (+) between the E and the number if there is one). If there is no E, then the
+  exponent is treated as zero.

+
+  
The Infinity and Not-a-Number (NaN) values are not valid floating-point numbers.

+
+  
+
+  
The valid floating-point number concept is typically only used to
+  restrict what is allowed for authors, while the user agent requirements use the rules for
+  parsing floating-point number values below (e.g., the max attribute of the progress element). However, in
+  some cases the user agent requirements include checking if a string is a valid
+  floating-point number (e.g., the value sanitization algorithm for the Number state of the input element, or the
+  parse a srcset attribute algorithm).

+
+  
The best
+  representation of the number n as a floating-point number is the string
+  obtained from running ToString(n). The abstract operation
+  ToString is not uniquely determined. When there are multiple possible strings that
+  could be obtained from ToString for a particular value, the user agent must always
+  return the same string for that value (though it may differ from the value used by other user
+  agents).

+
+  
The rules for parsing floating-point number values are as given in
+  the following algorithm. This algorithm must be aborted at the first step that returns something.
+  This algorithm will return either a number or an error.

+
+  
  1. Let input be the string being parsed.
  2. Let position be a pointer into input, initially pointing at the
+   start of the string.
  3. Let value have the value 1.
  4. Let divisor have the value 1.
  5. Let exponent have the value 1.
  6. Skip ASCII whitespace within input given
+   position.
  7. If position is past the end of input, return an error.
  8. 
+
+    
    If the character indicated by position is a U+002D HYPHEN-MINUS character (-):
    
+
+    
    1. Change value and divisor to −1.
    2. Advance position to the next character.
    3. If position is past the end of input, return an error.
    
+
+    
    Otherwise, if the character indicated by position (the first character) is a
+    U+002B PLUS SIGN character (+):
    
+
+    
    1. Advance position to the next character. (The "+"
+     is ignored, but it is not conforming.)
    2. If position is past the end of input, return an error.
    
+
+   
  9. If the character indicated by position is a U+002E FULL STOP (.), and that is
+   not the last character in input, and the character after the character indicated by
+   position is an ASCII digit, then set
+   value to zero and jump to the step labeled fraction.
     
+
+   
  10. If the character indicated by position is not an ASCII digit, then return an error.
  11. Collect a sequence of code points that are ASCII digits from
+   input given position, and interpret the resulting sequence as a base-ten
+   integer. Multiply value by that integer.
  12. If position is past the end of input, jump to the step labeled
+   conversion.
  13. Fraction: If the character indicated by position is a U+002E
+   FULL STOP (.), run these substeps:
    
+
+    
    1. Advance position to the next character.
    2. If position is past the end of input, or if the character
+     indicated by position is not an ASCII digit,
+     U+0065 LATIN SMALL LETTER E (e), or U+0045 LATIN CAPITAL LETTER E (E), then jump to the step
+     labeled conversion.
    3. If the character indicated by position is a U+0065 LATIN SMALL
+     LETTER E character (e) or a U+0045 LATIN CAPITAL LETTER E character (E), skip the remainder of
+     these substeps.
      
+
+     
    4. Fraction loop: Multiply divisor by ten.
    5. Add the value of the character indicated by position, interpreted as a
+     base-ten digit (0..9) and divided by divisor, to value.
    6. Advance position to the next character.
    7. If position is past the end of input, then jump to the step
+     labeled conversion.
    8. If the character indicated by position is an ASCII digit, jump back to the step labeled fraction loop in these
+     substeps.
    
+
+   
  14. If the character indicated by position is U+0065 (e) or a U+0045 (E), then:
    
+
+    
    1. Advance position to the next character.
    2. If position is past the end of input, then jump to the step
+     labeled conversion.
    3. 
+
+      
      If the character indicated by position is a U+002D HYPHEN-MINUS character
+      (-):
      
+
+      
      1. Change exponent to −1.
      2. Advance position to the next character.
      3. If position is past the end of input, then jump to the step
+       labeled conversion.
      
+
+      
      Otherwise, if the character indicated by position is a U+002B PLUS SIGN
+      character (+):
      
+
+      
      1. Advance position to the next character.
      2. If position is past the end of input, then jump to the step
+       labeled conversion.
      
+
+     
    4. If the character indicated by position is not an ASCII digit, then jump to the step labeled conversion.
    5. Collect a sequence of code points that are ASCII digits from
+     input given position, and interpret the resulting sequence as a base-ten
+     integer. Multiply exponent by that integer.
    6. Multiply value by ten raised to the exponentth power.
    
+
+   
  15. Conversion: Let S be the set of finite IEEE 754 double-precision
+   floating-point values except −0, but with two special values added: 21024 and −21024.
  16. Let rounded-value be the number in S that is closest to
+   value, selecting the number with an even significand if there are two equally close
+   values. (The two special values 21024 and −21024
+   are considered to have even significands for this purpose.)
  17. If rounded-value is 21024 or −21024, return an error.
  18. Return rounded-value.

+
+  
+
+
+
+  
2.3.4.4 Percentages and lengths

+
+  
The rules for parsing dimension values 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 return either a number greater than or equal to 0.0, or an error; if a
+  number is returned, then it is further categorized as either a percentage or a length.

+
+  
  1. Let input be the string being parsed.
  2. Let position be a pointer into input, initially pointing at the
+   start of the string.
  3. Skip ASCII whitespace within input given
+   position.
  4. If position is past the end of input, return an error.
  5. If the character indicated by position is a U+002B PLUS SIGN character (+),
+   advance position to the next character.
  6. If position is past the end of input, return an error.
  7. If the character indicated by position is not an ASCII digit, then return an error.
  8. Collect a sequence of code points that are ASCII digits from
+   input given position, and interpret the resulting sequence as a base-ten
+   integer. Let value be that number.
  9. If position is past the end of input, return value as a
+   length.
  10. 
+
+    
    If the character indicated by position is a U+002E FULL STOP character (.):
    
+
+    
    1. Advance position to the next character.
    2. If position is past the end of input, or if the character
+     indicated by position is not an ASCII digit, then
+     return value as a length.
    3. Let divisor have the value 1.
    4. Fraction loop: Multiply divisor by ten.
    5. Add the value of the character indicated by position, interpreted as a base-ten
+     digit (0..9) and divided by divisor, to value.
    6. Advance position to the next character.
    7. If position is past the end of input, then return value
+     as a length.
    8. If the character indicated by position is an ASCII digit, return to the step labeled fraction loop in these
+     substeps.
    
+
+   
  11. If position is past the end of input, return value as a
+   length.
  12. If the character indicated by position is a U+0025 PERCENT SIGN character (%),
+   return value as a percentage.
  13. Return value as a length.

+
+  
2.3.4.5 Non-zero percentages and lengths

+
+  
The rules for parsing non-zero dimension values 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 return either a number greater than 0.0, or an error; if
+  a number is returned, then it is further categorized as either a percentage or a length.

+
+  
  1. Let input be the string being parsed.
  2. Let value be the result of parsing input using the rules for
+   parsing dimension values.
  3. If value is an error, return an error.
  4. If value is zero, return an error.
  5. If value is a percentage, return value as a percentage.
  6. Return value as a length.

+
+  
+
+
+  
2.3.4.6 Lists of floating-point numbers

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

+
+  
+
+  
The rules for parsing a list of floating-point numbers are as follows:

+
+  
  1. Let input be the string being parsed.
  2. Let position be a pointer into input, initially pointing at the
+   start of the string.
  3. Let numbers be an initially empty list of floating-point numbers. This list
+   will be the result of this algorithm.
  4. Collect a sequence of code points that are ASCII whitespace,
+   U+002C COMMA, or U+003B SEMICOLON characters from input given position.
+   This skips past any leading delimiters.
  5. While position is not past the end of input:
    
+
+    
    1. Collect a sequence of code points that are not ASCII
+     whitespace, U+002C COMMA, U+003B SEMICOLON, ASCII digits, U+002E FULL STOP,
+     or U+002D HYPHEN-MINUS characters from input given position. This skips
+     past leading garbage.
    2. Collect a sequence of code points that are not ASCII
+     whitespace, U+002C COMMA, or U+003B SEMICOLON characters from input given
+     position, and let unparsed number be the result.
    3. Let number be the result of parsing unparsed number using the
+     rules for parsing floating-point number values.
    4. If number is an error, set number to zero.
    5. Append number to numbers.
    6. Collect a sequence of code points that are ASCII whitespace,
+     U+002C COMMA, or U+003B SEMICOLON characters from input given position.
+     This skips past the delimiter.
    
+
+   
  6. Return numbers.

+
+  
+
+  
+
+  
2.3.4.7 Lists of dimensions

+
+  
+
+  
The rules for parsing a list of dimensions are as follows. These rules return a list
+  of zero or more pairs consisting of a number and a unit, the unit being one of percentage,
+  relative, and absolute.

+
+  
  1. Let raw input be the string being parsed.
  2. If the last character in raw input is a U+002C COMMA character (,),
+   then remove that character from raw input.
  3. Split the string raw input on
+   commas. Let raw tokens be the resulting list of tokens.
  4. Let result be an empty list of number/unit pairs.
  5. 
+
+    
    For each token in raw tokens, run the following substeps:
    
+
+    
    1. Let input be the token.
    2. Let position be a pointer into input,
+     initially pointing at the start of the string.
    3. Let value be the number 0.
    4. Let unit be absolute.
    5. If position is past the end of input, set unit to relative and jump to the last substep.
    6. If the character at position is an ASCII digit, collect a sequence of code points that are ASCII
+     digits from input given position, interpret the resulting sequence
+     as an integer in base ten, and increment value by that integer.
    7. 
+
+      
      If the character at position is U+002E (.), then:
      
+
+      
      1. Collect a sequence of code points consisting of ASCII
+       whitespace and ASCII digits from input given
+       position. Let s be the resulting sequence.
      2. Remove all ASCII whitespace in s.
      3. 
+
+        
        If s is not the empty string, then:
        
+
+        
        1. Let length be the number of characters in s (after the spaces were removed).
        2. Let fraction be the result of interpreting s as a base-ten integer, and then dividing that number by 10length.
        3. Increment value by fraction.
        
+
+       
      
+
+     
    8. Skip ASCII whitespace within input given
+     position.
    9. 
+
+      
      If the character at position is a U+0025 PERCENT SIGN character (%),
+      then set unit to percentage.
      
+
+      
      Otherwise, if the character at position is a U+002A ASTERISK character
+      (*), then set unit to relative.
      
+
+     
    10. Add an entry to result consisting of the number given by value and the unit given by unit.
    
+
+   
  6. Return the list result.

+
+  
+
+
+  
2.3.5 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]

+
+  
When ASCII digits are used in the date and time syntaxes defined in this section,
+  they express numbers in base ten.

+
+  
+
+  
While the formats described here are intended to be subsets of the corresponding
+  ISO8601 formats, this specification defines parsing rules in much more detail than ISO8601.
+  Implementors are therefore encouraged to carefully examine any date parsing libraries before using
+  them to implement the parsing rules described below; ISO8601 libraries might not parse dates and
+  times in exactly the same manner. [ISO8601]

+
+  
+
+  
Where this specification refers to the proleptic Gregorian calendar, it means the
+  modern Gregorian calendar, extrapolated backwards to year 1. A date in the proleptic
+  Gregorian calendar, sometimes explicitly referred to as a proleptic-Gregorian
+  date, is one that is described using that calendar even if that calendar was not in use at
+  the time (or place) in question. [GREGORIAN]

+
+  
The use of the Gregorian calendar as the wire format in this specification is an
+  arbitrary choice resulting from the cultural biases of those involved in the decision. See also
+  the section discussing date, time, and number formats in forms
+  (for authors), implementation notes regarding
+  localization of form controls, and the time element.

+
+
+  
2.3.5.1 Months

+
+  
A month consists of a specific proleptic-Gregorian
+  date with no time-zone information and no date information beyond a year and a month. [GREGORIAN]

+
+  
A string is a valid month string representing a year year and
+  month month if it consists of the following components in the given order:

+
+  
  1. Four or more ASCII digits, representing year, where year > 0
  2. A U+002D HYPHEN-MINUS character (-)
  3. Two ASCII digits, representing the month month, in the range
+   1 ≤ month ≤ 12

+
+  
+
+  
The rules to parse a month string are as follows. This will return either a year and
+  month, or nothing. If at any point the algorithm says that it "fails", this means that it is
+  aborted at that point and returns nothing.

+
+  
  1. Let input be the string being parsed.
  2. Let position be a pointer into input, initially
+   pointing at the start of the string.
  3. Parse a month component to obtain year and month. If this returns nothing, then fail.
    
+
+   
  4. If position is not beyond the
+   end of input, then fail.
  5. Return year and month.

+
+  
The rules to parse a month component, given an input string and
+  a position, are as follows. This will return either a year and a month, or
+  nothing. If at any point the algorithm says that it "fails", this means that it is aborted at that
+  point and returns nothing.

+
+  
  1. Collect a sequence of code points that are ASCII digits from
+   input given position. If the collected sequence is not at least four
+   characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer.
+   Let that number be the year.
  2. If year is not a number greater than zero, then fail.
  3. 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.
  4. Collect a sequence of code points that are ASCII digits from
+   input given position. 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.
  5. If month is not a number in the range 1 ≤ month ≤ 12, then fail.
  6. Return year and month.

+
+  
+
+
+  
2.3.5.2 Dates

+
+  
A date consists of a specific proleptic-Gregorian
+  date with no time-zone information, consisting of a year, a month, and a day. [GREGORIAN]

+
+  
A string is a valid date string representing a year year, month
+  month, and day day if it consists of the following
+  components in the given order:

+
+  
  1. A valid month string, representing year and month
  2. A U+002D HYPHEN-MINUS character (-)
  3. Two ASCII digits, representing day, in the range
+   1 ≤ day ≤ maxday where maxday is the number of
+   days in the month month and year year

+
+  
+
+  
The rules to parse a date string are as follows. This will return either a date, or
+  nothing. If at any point the algorithm says that it "fails", this means that it is aborted at that
+  point and returns nothing.

+
+  
  1. Let input be the string being parsed.
  2. Let position be a pointer into input, initially
+   pointing at the start of the string.
  3. Parse a date component to obtain year, month, and day. If this returns nothing, then fail.
    
+
+   
  4. If position is not beyond the end of input, then fail.
  5. Let date be the date with year year, month month, and day day.
  6. Return date.

+
+  
The rules to parse a date component, given an input string and a
+  position, are as follows. This will return either a year, a month, and a day,
+  or nothing. If at any point the algorithm says that it "fails", this means that it is aborted at
+  that point and returns nothing.

+
+  
  1. Parse a month component to obtain year and month. If this returns nothing, then fail.
  2. Let maxday be the number of days in month month of year year.
  3. 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.
  4. Collect a sequence of code points that are ASCII digits from
+   input given position. 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.
  5. If day is not a number in the range 1 ≤ day ≤ maxday, then fail.
  6. Return year, month, and day.

+
+  
+
+
+  
2.3.5.3 Yearless dates

+
+  
A yearless date consists of a Gregorian month and a
+  day within that month, but with no associated year. [GREGORIAN]

+
+  
A string is a valid yearless date string representing a month month and a day day if it consists of the following components
+  in the given order:

+
+  
  1. Optionally, two U+002D HYPHEN-MINUS characters (-)
  2. Two ASCII digits, representing the month month, in the range
+   1 ≤ month ≤ 12
  3. A U+002D HYPHEN-MINUS character (-)
  4. Two ASCII digits, representing day, in the range
+   1 ≤ day ≤ maxday where maxday is the number of
+   days in the month month and any arbitrary leap year (e.g. 4 or
+   2000)

+
+  
In other words, if the month is "02",
+  meaning February, then the day can be 29, as if the year was a leap year.

+
+  
+
+  
The rules to parse a yearless date string are as follows. This will return either a
+  month and a day, or nothing. If at any point the algorithm says that it "fails", this means that
+  it is aborted at that point and returns nothing.

+
+  
  1. Let input be the string being parsed.
  2. Let position be a pointer into input, initially
+   pointing at the start of the string.
  3. Parse a yearless date component to obtain month and day. If this returns nothing, then fail.
    
+
+   
  4. If position is not beyond the end of input, then fail.
  5. Return month and day.

+
+  
The rules to parse a yearless date component, given an input
+  string and a position, are as follows. This will return either a month and a
+  day, or nothing. If at any point the algorithm says that it "fails", this means that it is aborted
+  at that point and returns nothing.

+
+  
  1. Collect a sequence of code points that are U+002D HYPHEN-MINUS characters (-)
+   from input given position. If the collected sequence is not exactly zero or
+   two characters long, then fail.
  2. Collect a sequence of code points that are ASCII digits from
+   input given position. 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.
  3. If month is not a number in the range 1 ≤ month ≤ 12, then fail.
  4. Let maxday be the number of days in month month of any arbitrary leap year (e.g. 4
+   or 2000).
  5. 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.
  6. Collect a sequence of code points that are ASCII digits from
+   input given position. 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.
  7. If day is not a number in the range 1 ≤ day ≤ maxday, then fail.
  8. Return month and day.

+
+  
+
+
+  
2.3.5.4 Times

+
+  
A time consists of a specific time with no time-zone
+  information, consisting of an hour, a minute, a second, and a fraction of a second.

+
+  
A string is a valid time string representing an hour hour, a
+  minute minute, and a second second if it consists of the
+  following components in the given order:

+
+  
  1. Two ASCII digits, representing hour, in the range
+   0 ≤ hour ≤ 23
  2. A U+003A COLON character (:)
  3. Two ASCII digits, representing minute, in the range
+   0 ≤ minute ≤ 59
  4. If second is non-zero, or optionally if second is
+   zero:
+
+    
    1. A U+003A COLON character (:)
    2. Two ASCII digits, representing the integer part of second,
+     in the range 0 ≤ s ≤ 59
    3. If second is not an integer, or optionally if second is an integer:
+
+      
      1. A U+002E FULL STOP character (.)
      2. One, two, or three ASCII digits, representing the fractional part of second
      
+
+     
    
+
+   

+
+  
The second component cannot be 60 or 61; leap seconds cannot
+  be represented.

+
+  
+
+  
The rules to parse a time string are as follows. This will return either a time, or
+  nothing. If at any point the algorithm says that it "fails", this means that it is aborted at that
+  point and returns nothing.

+
+  
  1. Let input be the string being parsed.
  2. Let position be a pointer into input, initially
+   pointing at the start of the string.
  3. Parse a time component to obtain hour, minute, and second. If this returns nothing, then fail.
    
+
+   
  4. If position is not beyond the end of input, then fail.
  5. Let time be the time with hour hour, minute minute, and second second.
  6. Return time.

+
+  
The rules to parse a time component, given an input string and a
+  position, are as follows. This will return either an hour, a minute, and a
+  second, or nothing. If at any point the algorithm says that it "fails", this means that it is
+  aborted at that point and returns nothing.

+
+  
  1. Collect a sequence of code points that are ASCII digits from
+   input given position. 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.
  2. If hour is not a number in the range 0 ≤ hour ≤ 23, then fail.
  3. 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.
  4. Collect a sequence of code points that are ASCII digits from
+   input given position. 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.
  5. If minute is not a number in the range 0 ≤ minute ≤ 59, then fail.
  6. Let second be 0.
  7. 
+
+    
    If position is not beyond the end of input and the character at
+    position is U+003A (:), then:
    
+
+    
    1. Advance position to the next character in input.
    2. 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 both ASCII
+     digits, then fail.
    3. Collect a sequence of code points that are either ASCII digits
+     or U+002E FULL STOP characters from input given position. If the
+     collected sequence is three characters long, or if it is longer than three characters long and
+     the third character is not a U+002E FULL STOP character, or if it has more than one U+002E FULL
+     STOP character, then fail. Otherwise, interpret the resulting sequence as a base-ten number
+     (possibly with a fractional part). Set second to that number.
    4. If second is not a number in the range
+     0 ≤ second < 60, then fail.
    
+
+   
  8. Return hour, minute, and second.

+
+  
+
+
+  
2.3.5.5 Local dates and times

+
+  
A local date and time consists of a specific
+  proleptic-Gregorian date, consisting of a year, a month, and a day, and a time,
+  consisting of an hour, a minute, a second, and a fraction of a second, but expressed without a
+  time zone. [GREGORIAN]

+
+  
A string is a valid local date and time string representing a date and time if it
+  consists of the following components in the given order:

+
+  
  1. A valid date string representing the date
  2. A U+0054 LATIN CAPITAL LETTER T character (T) or a U+0020 SPACE character
  3. A valid time string representing the time

+
+  
A string is a valid
+  normalized local date and time string representing a date and time if it consists of the
+  following components in the given order:

+
+  
  1. A valid date string representing the date
  2. A U+0054 LATIN CAPITAL LETTER T character (T)
  3. A valid time string representing the time, expressed as the shortest possible
+   string for the given time (e.g. omitting the seconds component entirely if the given time is zero
+   seconds past the minute)

+
+  
+
+  
The rules to parse a local date and time string are as follows. This will return
+  either a date and time, or nothing. If at any point the algorithm says that it "fails", this means
+  that it is aborted at that point and returns nothing.

+
+  
  1. Let input be the string being parsed.
  2. Let position be a pointer into input, initially
+   pointing at the start of the string.
  3. Parse a date component to obtain year, month, and day. If this returns nothing, then fail.
    
+
+   
  4. If position is beyond the end of input or if the
+   character at position is neither a U+0054 LATIN CAPITAL LETTER T character
+   (T) nor a U+0020 SPACE character, then fail. Otherwise, move position
+   forwards one character.
  5. Parse a time component to obtain hour, minute, and second. If this returns nothing, then fail.
    
+
+   
  6. If position is not beyond the end of input, then fail.
  7. Let date be the date with year year, month month, and day day.
  8. Let time be the time with hour hour, minute minute, and second second.
  9. Return date and time.

+
+  
+
+
+  
2.3.5.6 Time zones

+
+  
A time-zone offset consists of a signed number of hours and
+  minutes.

+
+  
A string is a valid time-zone offset string representing a time-zone offset if it
+  consists of either:

+
+
+  
  • A U+005A LATIN CAPITAL LETTER Z character (Z), allowed only if the time zone is
+   UTC
  • 
+
+    
    Or, the following components, in the given order:
    
+
+    
    1. Either a U+002B PLUS SIGN character (+) or, if the time-zone offset is not zero, a U+002D
+     HYPHEN-MINUS character (-), representing the sign of the time-zone offset
    2. Two ASCII digits, representing the hours component hour of
+     the time-zone offset, in the range 0 ≤ hour ≤ 23
    3. Optionally, a U+003A COLON character (:)
    4. Two ASCII digits, representing the minutes component minute of the time-zone offset, in the range 0 ≤ minute ≤ 59
    
+
+   

+
+  
This format allows for time-zone offsets from -23:59 to +23:59. Right now, in
+  practice, the range of offsets of actual time zones is -12:00 to +14:00, and the minutes component
+  of offsets of actual time zones is always either 00, 30, or 45. There is no guarantee that this
+  will remain so forever, however, since time zones are used as political footballs and are thus
+  subject to very whimsical policy decisions.

+
+  
See also the usage notes and examples in the global
+  date and time section below for details on using time-zone offsets with historical times
+  that predate the formation of formal time zones.

+
+  
+
+  
The rules to parse a time-zone offset string are as follows. This will return either
+  a time-zone offset, or nothing. If at any point the algorithm says that it "fails", this means
+  that it is aborted at that point and returns nothing.

+
+  
  1. Let input be the string being parsed.
  2. Let position be a pointer into input, initially
+   pointing at the start of the string.
  3. Parse a time-zone offset component to obtain timezonehours and timezoneminutes. If this
+   returns nothing, then fail.
    
+
+   
  4. If position is not beyond the end of input, then fail.
  5. Return the time-zone offset that is timezonehours
+   hours and timezoneminutes minutes from UTC.

+
+  
The rules to parse a time-zone offset component, given an input
+  string and a position, are as follows. This will return either time-zone hours
+  and time-zone minutes, or nothing. If at any point the algorithm says that it "fails", this means
+  that it is aborted at that point and returns nothing.

+
+  
  1. 
+
+    
    If the character at position is a U+005A LATIN CAPITAL LETTER Z character
+    (Z), then:
    
+
+    
    1. Let timezonehours be 0.
    2. Let timezoneminutes be 0.
    3. 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:
    
+
+    
    1. 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".
    2. Advance position to the next character in input.
    3. Collect a sequence of code points that are ASCII digits from
+     input given position. Let s be the collected
+     sequence.
    4. 
+
+      
      If s is exactly two characters long, then:
      
+
+      
      1. Interpret s as a base-ten integer. Let that number be the timezonehours.
      2. 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.
      3. Collect a sequence of code points that are ASCII digits from
+       input given position. 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 timezoneminutes.
      
+
+      
      If s is exactly four characters long, then:
      
+
+      
      1. Interpret the first two characters of s as a base-ten integer. Let
+       that number be the timezonehours.
      2. Interpret the last two characters of s as a base-ten integer. Let
+       that number be the timezoneminutes.
      
+
+      
      Otherwise, fail.
      
+
+     
    5. If timezonehours is not a number in the range
+     0 ≤ timezonehours ≤ 23, then
+     fail.
    6. If sign is "negative", then negate timezonehours.
    7. If timezoneminutes is not a number in the range
+     0 ≤ timezoneminutes ≤ 59,
+     then fail.
    8. If sign is "negative", then negate timezoneminutes.
    
+
+    
    Otherwise, fail.
    
+
+   
  2. Return timezonehours and timezoneminutes.

+
+  
+
+
+  
2.3.5.7 Global dates and times

+
+  
A global date and time consists of a specific
+  proleptic-Gregorian date, consisting of a year, a month, and a day, and a time,
+  consisting of an hour, a minute, a second, and a fraction of a second, expressed with a time-zone
+  offset, consisting of a signed number of hours and minutes. [GREGORIAN]

+
+  
A string is a valid global date and time string representing a date, time, and a
+  time-zone offset if it consists of the following components in the given order:

+
+  
  1. A valid date string representing the date
  2. A U+0054 LATIN CAPITAL LETTER T character (T) or a U+0020 SPACE character
  3. A valid time string representing the time
  4. A valid time-zone offset string representing the time-zone offset

+
+  
Times in dates before the formation of UTC in the mid twentieth century must be expressed and
+  interpreted in terms of UT1 (contemporary Earth solar time at the 0° longitude), not UTC (the
+  approximation of UT1 that ticks in SI seconds). Time before the formation of time zones must be
+  expressed and interpreted as UT1 times with explicit time zones that approximate the contemporary
+  difference between the appropriate local time and the time observed at the location of Greenwich,
+  London.

+
+  

+
+   
The following are some examples of dates written as valid global date and time strings.

+
+   
"0037-12-13 00:00Z"
Midnight in areas using London time on the birthday of Nero (the Roman Emperor). See below
+    for further discussion on which date this actually corresponds to.
"1979-10-14T12:00:00.001-04:00"
One millisecond after noon on October 14th 1979, in the time zone in use on the east coast
+    of the USA during daylight saving time.
"8592-01-01T02: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, which is not currently a real time zone, but is nonetheless
+    allowed.

+
+   
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.
  • If the "T" is replaced by a space, it must be a single space
+    character. The string "2001-12-21  12:00Z" (with two spaces
+    between the components) would not be parsed successfully.
  • To unambiguously identify a moment in time prior to the introduction of the Gregorian
+    calendar (insofar as moments in time before the formation of UTC can be unambiguously
+    identified), 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 proleptic
+    Gregorian calendar.
  • The time and time-zone offset components are not optional.
  • Dates before the year one can't be represented as a datetime in this version of HTML.
  • Times of specific events in ancient times are, at best, approximations, since time was not
+    well coordinated or measured until relatively recent decades.
  • Time-zone offsets differ based on daylight savings time.

+
+  

+
+  
+
+  
The rules to parse a global date and time string are as follows. This will return
+  either a time in UTC, with associated time-zone offset information for round-tripping or display
+  purposes, or nothing. If at any point the algorithm says that it "fails", this means that it is
+  aborted at that point and returns nothing.

+
+  
  1. Let input be the string being parsed.
  2. Let position be a pointer into input, initially
+   pointing at the start of the string.
  3. Parse a date component to obtain year, month, and day. If this returns nothing, then fail.
    
+
+   
  4. If position is beyond the end of input or if the
+   character at position is neither a U+0054 LATIN CAPITAL LETTER T character
+   (T) nor a U+0020 SPACE character, then fail. Otherwise, move position
+   forwards one character.
  5. Parse a time component to obtain hour, minute, and second. If this returns nothing, then fail.
    
+
+   
  6. If position is beyond the end of input, then
+   fail.
  7. Parse a time-zone offset component to obtain timezonehours and timezoneminutes. If this
+   returns nothing, then fail.
    
+
+   
  8. If position is not beyond the end of input, then fail.
  9. Let time be the moment in time at year year, month
+   month, day day, hours hour, minute
+   minute, second second, subtracting timezonehours hours and timezoneminutes minutes. That moment in time is a moment in the UTC time
+   zone.
  10. Let timezone be timezonehours
+   hours and timezoneminutes minutes from UTC.
  11. Return time and timezone.

+
+  
+
+
+  
2.3.5.8 Weeks

+
+  
A week consists of a week-year number and a week number
+  representing a seven-day period starting on a Monday. Each week-year in this calendaring system
+  has either 52 or 53 such seven-day periods, as defined below. The seven-day period starting on the
+  Gregorian date Monday December 29th 1969 (1969-12-29) is defined as week number 1 in week-year
+  1970. Consecutive weeks are numbered sequentially. The week before the number 1 week in a
+  week-year is the last week in the previous week-year, and vice versa. [GREGORIAN]

+
+  
A week-year with a number year has 53 weeks if it corresponds to either a
+  year year in the proleptic Gregorian calendar that has a Thursday
+  as its first day (January 1st), or a year year in the proleptic
+  Gregorian calendar that has a Wednesday as its first day (January 1st) and where year is a number divisible by 400, or a number divisible by 4 but not by 100. All
+  other week-years have 52 weeks.

+
+  
The week number of the last day of a week-year with 53 weeks is 53; the week number
+  of the last day of a week-year with 52 weeks is 52.

+
+  
The week-year number of a particular day can be different than the number of the
+  year that contains that day in the proleptic Gregorian calendar. The first week in a
+  week-year y is the week that contains the first Thursday of the Gregorian year
+  y.

+
+  
For modern purposes, a week as defined here is
+  equivalent to ISO weeks as defined in ISO 8601. [ISO8601]

+
+  
A string is a valid week string representing a week-year year
+  and week week if it consists of the following components in the given
+  order:

+
+  
  1. Four or more ASCII digits, representing year, where year > 0
  2. A U+002D HYPHEN-MINUS character (-)
  3. A U+0057 LATIN CAPITAL LETTER W character (W)
  4. Two ASCII digits, representing the week week, in the range
+   1 ≤ week ≤ maxweek, where maxweek is the week number of the last day of week-year year

+
+  
+
+  
The rules to parse a week string are as follows. This will return either a week-year
+  number and week number, or nothing. If at any point the algorithm says that it "fails", this means
+  that it is aborted at that point and returns nothing.

+
+  
  1. Let input be the string being parsed.
  2. Let position be a pointer into input, initially
+   pointing at the start of the string.
  3. Collect a sequence of code points that are ASCII digits from
+   input given position. If the collected sequence is not at least four
+   characters long, then fail. Otherwise, interpret the resulting sequence as a base-ten integer.
+   Let that number be the year.
  4. If year is not a number greater than zero, then fail.
  5. 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.
  6. If position is beyond the end of input or if the
+   character at position is not a U+0057 LATIN CAPITAL LETTER W character (W),
+   then fail. Otherwise, move position forwards one character.
  7. Collect a sequence of code points that are ASCII digits from
+   input given position. 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 week.
  8. Let maxweek be the week number of the last day of year
+   year.
  9. If week is not a number in the range 1 ≤ week ≤ maxweek, then fail.
  10. If position is not beyond the end of input, then fail.
  11. Return the week-year number year and the week number week.

+
+  
+
+
+  
2.3.5.9 Durations

+
+  
+
+  
A duration consists of  a number of seconds.

+
+  
Since months and seconds are not comparable (a month is not a precise number of
+  seconds, but is instead a period whose exact length depends on the precise day from which it is
+  measured) a duration as defined in this specification cannot
+   include months (or years, which are equivalent to
+  twelve months). Only durations that describe a specific number of seconds can be described.

+
+  
A string is a valid duration string representing a duration t if it consists of either of the
+  following:

+
+  
  • 
+
+    
+
+    
+
+    
    A literal U+0050 LATIN CAPITAL LETTER P character followed by one or more of the following
+    subcomponents, in the order given, where the number of days, hours, minutes, and
+    seconds corresponds to the same number of seconds as in t:
    
+
+    
    1. One or more ASCII digits followed by a U+0044 LATIN CAPITAL LETTER D
+     character, representing a number of days.
    2. 
+
+      
      A U+0054 LATIN CAPITAL LETTER T character followed by one or more of the following
+      subcomponents, in the order given:
      
+
+      
      1. One or more ASCII digits followed by a U+0048 LATIN CAPITAL LETTER H
+       character, representing a number of hours.
      2. One or more ASCII digits followed by a U+004D LATIN CAPITAL LETTER M
+       character, representing a number of minutes.
      3. 
+
+        
        The following components:
        
+
+        
        1. One or more ASCII digits, representing a number of seconds.
        2. Optionally, a U+002E FULL STOP character (.) followed by one, two, or three
+         ASCII digits, representing a fraction of a second.
        3. A U+0053 LATIN CAPITAL LETTER S character.
        
+
+       
      
+
+     
    
+
+    
    This, as with a number of other date- and time-related microsyntaxes defined in
+    this specification, is based on one of the formats defined in ISO 8601. [ISO8601]
    
+
+   
  • 
+
+    
    One or more duration time components, each with
+    a different duration time component scale, in any order; the sum of the represented
+    seconds being equal to the number of seconds in t.
    
+
+    
    A duration time component is a string consisting of the following components:
    
+
+    
    1. Zero or more ASCII whitespace.
    2. One or more ASCII digits, representing a number of time units, scaled by
+     the duration time component scale specified (see below) to represent a number of
+     seconds.
    3. If the duration time component scale specified is 1 (i.e. the units are
+     seconds), then, optionally, a U+002E FULL STOP character (.) followed by one, two, or three
+     ASCII digits, representing a fraction of a second.
    4. Zero or more ASCII whitespace.
    5. 
+
+      
      One of the following characters, representing the duration time component scale
+      of the time unit used in the numeric part of the duration time component:
      
+
+      
      U+0057 LATIN CAPITAL LETTER W character
      U+0077 LATIN SMALL LETTER W character
      Weeks. The scale is 604800.
      U+0044 LATIN CAPITAL LETTER D character
      U+0064 LATIN SMALL LETTER D character
      Days. The scale is 86400.
      U+0048 LATIN CAPITAL LETTER H character
      U+0068 LATIN SMALL LETTER H character
      Hours. The scale is 3600.
      U+004D LATIN CAPITAL LETTER M character
      U+006D LATIN SMALL LETTER M character
      Minutes. The scale is 60.
      U+0053 LATIN CAPITAL LETTER S character
      U+0073 LATIN SMALL LETTER S character
      Seconds. The scale is 1.
      
+
+     
    6. Zero or more ASCII whitespace.
    
+
+    
    This is not based on any of the formats in ISO 8601. It is intended to be a more
+    human-readable alternative to the ISO 8601 duration format.
    
+
+   

+
+  
+
+  
The rules to parse a duration string are as follows. This will return either a duration or nothing. If at any point the algorithm says that it
+  "fails", this means that it is aborted at that point and returns nothing.

+
+  
  1. Let input be the string being parsed.
  2. Let position be a pointer into input, initially
+   pointing at the start of the string.
  3. Let months, seconds, and component
+   count all be zero.
  4. 
+
+    
    Let M-disambiguator be minutes.
    
+
+    
+    
    This flag's other value is months. It is used to disambiguate the "M"
+    unit in ISO8601 durations, which use the same unit for months and minutes. Months are not
+    allowed, but are parsed for future compatibility and to avoid misinterpreting ISO8601 durations
+    that would be valid in other contexts.
    
+
+   
  5. Skip ASCII whitespace within input given
+   position.
  6. If position is past the end of input, then
+   fail.
  7. If the character in input pointed to by position is a U+0050 LATIN
+   CAPITAL LETTER P character, then advance position to the next character, set
+   M-disambiguator to months, and skip ASCII whitespace within
+   input given position.
  8. 
+
+    
    While true:
    
+
+    
    1. Let units be undefined. It will be assigned one of the following
+     values: years, months, weeks, days, hours, minutes,
+     and seconds.
    2. Let next character be undefined. It is used to process characters
+     from the input.
    3. If position is past the end of input, then break.
    4. If the character in input pointed to by position is a U+0054 LATIN
+     CAPITAL LETTER T character, then advance position to the next character, set
+     M-disambiguator to minutes, skip ASCII whitespace within
+     input given position, and continue.
    5. Set next character to the character in input
+     pointed to by position.
    6. 
+
+      
      If next character is a U+002E FULL STOP character (.), then let N equal zero. (Do not advance position. That is taken care
+      of below.)
      
+
+      
      Otherwise, if next character is an ASCII
+      digit, then collect a sequence of code points that are ASCII
+      digits from input given position, interpret the resulting
+      sequence as a base-ten integer, and let N be that number.
      
+
+      
      Otherwise next character is not part of a number; fail.
      
+
+     
    7. If position is past the end of input, then
+     fail.
    8. Set next character to the character in input
+     pointed to by position, and this time advance position
+     to the next character. (If next character was a U+002E FULL STOP character
+     (.) before, it will still be that character this time.)
    9. 
+
+      
      If next character is U+002E (.), then:
      
+
+      
      1. Collect a sequence of code points that are ASCII digits from
+       input given position. Let s be the resulting
+       sequence.
      2. If s is the empty string, then fail.
      3. Let length be the number of characters in s.
      4. Let fraction be the result of interpreting s
+       as a base-ten integer, and then dividing that number by 10length.
      5. Increment N by fraction.
      6. Skip ASCII whitespace within input given
+       position.
      7. If position is past the end of input, then
+       fail.
      8. Set next character to the character in input
+       pointed to by position, and advance position to the
+       next character.
      9. If next character is neither a U+0053 LATIN CAPITAL LETTER S
+       character nor a U+0073 LATIN SMALL LETTER S character, then fail.
      10. Set units to seconds.
      
+
+      
      Otherwise:
      
+
+      
      1. If next character is ASCII whitespace, then skip ASCII
+       whitespace within input given position, set next
+       character to the character in input pointed to by position, and
+       advance position to the next character.
      2. 
+
+        
+
+        
        If next character is a U+0059 LATIN CAPITAL LETTER Y character, or a
+        U+0079 LATIN SMALL LETTER Y character, set units to years and set
+        M-disambiguator to months.
        
+
+        
        If next character is a U+004D LATIN CAPITAL LETTER M character or a
+        U+006D LATIN SMALL LETTER M character, and M-disambiguator is
+        months, then set units to months.
        
+
+        
        If next character is a U+0057 LATIN CAPITAL LETTER W character or a
+        U+0077 LATIN SMALL LETTER W character, set units to weeks and set
+        M-disambiguator to minutes.
        
+
+        
        If next character is a U+0044 LATIN CAPITAL LETTER D character or a
+        U+0064 LATIN SMALL LETTER D character, set units to days and set
+        M-disambiguator to minutes.
        
+
+        
        If next character is a U+0048 LATIN CAPITAL LETTER H character or a
+        U+0068 LATIN SMALL LETTER H character, set units to hours and set
+        M-disambiguator to minutes.
        
+
+        
        If next character is a U+004D LATIN CAPITAL LETTER M character or a
+        U+006D LATIN SMALL LETTER M character, and M-disambiguator is
+        minutes, then set units to minutes.
        
+
+        
        If next character is a U+0053 LATIN CAPITAL LETTER S character or a
+        U+0073 LATIN SMALL LETTER S character, set units to seconds and
+        set M-disambiguator to minutes.
        
+
+        
        Otherwise if next character is none of the above characters, then
+        fail.
        
+
+       
      
+
+     
    10. Increment component count.
    11. Let multiplier be 1.
    12. If units is years, multiply multiplier by
+     12 and set units to months.
    13. 
+
+      
      If units is months, add the product of N and
+      multiplier to months.
      
+
+      
      Otherwise:
      
+
+      
      1. If units is weeks, multiply multiplier
+       by 7 and set units to days.
      2. If units is days, multiply multiplier
+       by 24 and set units to hours.
      3. If units is hours, multiply multiplier
+       by 60 and set units to minutes.
      4. If units is minutes, multiply multiplier by 60 and set units to seconds.
      5. Forcibly, units is now seconds. Add the product of N and multiplier to seconds.
      
+
+     
    14. Skip ASCII whitespace within input given
+     position.
    
+
+   
  9. If component count is zero,
+   fail.
  10. If months is not zero, fail.
  11. Return the duration consisting of seconds seconds.

+
+  
+
+
+  
2.3.5.10 Vaguer moments in time

+
+  
A string is a valid date string with optional time if
+  it is also one of the following:

+
+  
+
+  
+
+  

+
+  
The rules to parse a date or time string are as follows. The algorithm will return
+  either a date, a time, a global date and time, or nothing. If at any point the algorithm
+  says that it "fails", this means that it is aborted at that point and returns nothing.

+
+  
  1. Let input be the string being parsed.
  2. Let position be a pointer into input, initially
+   pointing at the start of the string.
  3. Set start position to the same position as position.
  4. Set the date present and time present flags to
+   true.
  5. Parse a date component to obtain year, month, and day. If this fails, then set the date
+   present flag to false.
    
+
+   
  6. 
+
+    
    If date present is true, and position is not beyond
+    the end of input, and the character at position is
+    either a U+0054 LATIN CAPITAL LETTER T character (T) or a U+0020 SPACE character, then advance
+    position to the next character in input.
    
+
+    
    Otherwise, if date present is true, and either position is beyond the end of input or the character at position is neither a U+0054 LATIN CAPITAL LETTER T character (T) nor a U+0020
+    SPACE character, then set time present to false.
    
+
+    
    Otherwise, if date present is false, set position
+    back to the same position as start position.
    
+
+   
  7. If the time present flag is true, then parse a time
+   component to obtain hour, minute, and second. If this returns nothing, then fail.
  8. If the date present and time present flags are
+   both true, but position is beyond the end of input, then
+   fail.
  9. If the date present and time present flags are
+   both true, parse a time-zone offset component to obtain timezonehours and timezoneminutes. If this
+   returns nothing, then fail.
    
+
+   
  10. If position is not beyond the end of input, then fail.
  11. 
+
+    
    If the date present flag is true and the time present
+    flag is false, then let date be the date with year year,
+    month month, and day day, and return date.
    
+
+    
    Otherwise, if the time present flag is true and the date
+    present flag is false, then let time be the time with hour hour, minute minute, and second second,
+    and return time.
    
+
+    
    Otherwise, let time be the moment in time at year year, month month, day day, hours hour, minute minute, second second,
+    subtracting timezonehours hours and timezoneminutes minutes, that moment in time being a moment
+    in the UTC time zone; let timezone be timezonehours hours and timezoneminutes
+    minutes from UTC; and return time and timezone.
    
+
+   

+
+  
+
+
+  
2.3.6 Colors

+
+  
A simple color consists of three 8-bit numbers in the
+  range 0..255, representing the red, green, and blue components of the color respectively, in the
+  sRGB color space. [SRGB]

+
+  
A string is a valid simple color if it is
+  exactly seven characters long, and the first character is a U+0023 NUMBER SIGN character (#), and
+  the remaining six characters are all ASCII hex digits, with the first two digits
+  representing the red component, the middle two digits representing the green component, and the
+  last two digits representing the blue component, in hexadecimal.

+
+  
A string is a valid lowercase simple
+  color if it is a valid simple color and doesn't use any characters in the range
+  U+0041 LATIN CAPITAL LETTER A to U+0046 LATIN CAPITAL LETTER F.

+
+  
+
+  
The rules for parsing simple color
+  values 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 return
+  either a simple color or an error.

+
+  
  1. Let input be the string being parsed.
  2. If input is not exactly seven characters long, then return an
+   error.
  3. If the first character in input is not a U+0023 NUMBER SIGN character
+   (#), then return an error.
  4. If the last six characters of input are not all ASCII hex
+   digits, then return an error.
  5. Let result be a simple color.
    
+
+   
  6. Interpret the second and third characters as a hexadecimal number and let the result be
+   the red component of result.
    
+
+   
  7. Interpret the fourth and fifth characters as a hexadecimal number and let the result be
+   the green component of result.
    
+
+   
  8. Interpret the sixth and seventh characters as a hexadecimal number and let the result be
+   the blue component of result.
    
+
+   
  9. Return result.
    
+
+  

+
+  
The rules for serializing
+  simple color values given a simple color are as given in the following
+  algorithm:

+
+  
  1. Let result be a string consisting of a single U+0023 NUMBER SIGN
+   character (#).
  2. Convert the red, green, and blue components in turn to two-digit hexadecimal numbers using
+   ASCII lower hex digits, zero-padding if necessary,
+   and append these numbers to result, in the order red, green, blue.
    
+
+   
  3. Return result, which will be a valid lowercase simple
+   color.

+
+  

+
+  
Some obsolete legacy attributes parse colors in a more complicated manner, using the
+  rules for parsing a legacy color
+  value, which are 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 return
+  either a simple color or an error.

+
+  
  1. Let input be the string being parsed.
  2. If input is the empty string, then return an error.
  3. Strip leading and trailing ASCII whitespace from input.
  4. If input is an ASCII case-insensitive match for the
+   string "transparent", then return an error.
  5. 
+
+    
    If input is an ASCII case-insensitive match for one of the
+    named colors, then return the simple
+    color corresponding to that keyword. [CSSCOLOR]
    
+
+    
    CSS2 System
+    Colors are not recognized.
    
+
+   
  6. 
+
+    
    If input is four characters long, and the first character in input is
+    U+0023 (#), and the last three characters of input are all ASCII hex
+    digits, then:
    
+
+    
    1. Let result be a simple color.
      
+
+     
    2. Interpret the second character of input as a hexadecimal digit; let
+     the red component of result be the resulting number multiplied by 17.
      
+
+     
    3. Interpret the third character of input as a hexadecimal digit; let
+     the green component of result be the resulting number multiplied by 17.
      
+
+     
    4. Interpret the fourth character of input as a hexadecimal digit; let
+     the blue component of result be the resulting number multiplied by 17.
      
+
+     
    5. Return result.
      
+
+    
    
+
+   
  7. Replace any characters in input that have a code point greater than U+FFFF
+   (i.e., any characters that are not in the basic multilingual plane) with the two-character string
+   "00".
  8. If input is longer than 128 characters, truncate input, leaving only the first 128 characters.
  9. If the first character in input is a U+0023 NUMBER SIGN character (#),
+   remove it.
  10. Replace any character in input that is not an ASCII hex digit with the character U+0030 DIGIT ZERO (0).
  11. While input's length is zero or not a multiple of three, append a
+   U+0030 DIGIT ZERO (0) character to input.
  12. Split input into three strings of equal length, to obtain three
+   components. Let length be the length of those components (one third the
+   length of input).
  13. If length is greater than 8, then remove the leading length-8 characters in each component, and let length be 8.
  14. While length is greater than two and the first character in each
+   component is a U+0030 DIGIT ZERO (0) character, remove that character and reduce length by one.
  15. If length is still greater than two, truncate each component,
+   leaving only the first two characters in each.
  16. Let result be a simple color.
    
+
+   
  17. Interpret the first component as a hexadecimal number; let the red component of result be the resulting number.
  18. Interpret the second component as a hexadecimal number; let the green component of result be the resulting number.
  19. Interpret the third component as a hexadecimal number; let the blue component of result be the resulting number.
  20. Return result.
    
+
+  

+
+  
+
+  

+
+  
The 2D graphics context has a separate
+  color syntax that also handles opacity.

+
+
+
+  
2.3.7 Space-separated tokens

+
+  
A set of space-separated tokens is a string containing zero or more words (known as
+  tokens) separated by one or more ASCII whitespace, where words consist of any string
+  of one or more characters, none of which are ASCII whitespace.

+
+  
A string containing a set of space-separated tokens may have leading or trailing
+  ASCII whitespace.

+
+  
An unordered set of unique space-separated tokens is a set of space-separated
+  tokens where none of the tokens are duplicated.

+
+  
An ordered set of unique space-separated tokens is a set of space-separated
+  tokens where none of the tokens 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.

+
+  
How tokens in a set of space-separated tokens are to be compared
+  (e.g. case-sensitively or not) is defined on a per-set basis.

+
+
+
+  
2.3.8 Comma-separated tokens

+
+  
A set of comma-separated tokens is a string containing zero or more tokens each
+  separated from the next by a single U+002C COMMA character (,), where tokens consist of any string
+  of zero or more characters, neither beginning nor ending with ASCII whitespace, nor
+  containing any U+002C COMMA characters (,), and optionally surrounded by ASCII
+  whitespace.

+
+  
For instance, the string " a ,b,,d d " consists of four tokens: "a", "b", the empty
+  string, and "d d". Leading and trailing whitespace around each token doesn't count as part of
+  the token, and the empty string can be a token.

+
+  
Sets of comma-separated tokens sometimes
+  have further restrictions on what consists a valid token. When such restrictions are defined, the
+  tokens must all fit within those restrictions; other values are non-conforming. If no such
+  restrictions are specified, then all values are conforming.

+
+
+
+  
2.3.9 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 with type type in
+  the same tree.

+
+  
+
+  
The rules for parsing a hash-name reference to an element of type type,
+  given a context node scope, are as follows:

+
+  
  1. 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.
  2. 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.
  3. 
+    
    Return the first element of type type in scope's tree, in
+    tree order, that has an id or name attribute whose value is s, or null if there is no such
+    element.
    
+
+    
    Although id attributes are accounted for when
+    parsing, they are not used in determining whether a value is a valid hash-name
+    reference. That is, a hash-name reference that refers to an element based on id is a conformance error (unless that element also has a name attribute with the same value).
    
+   

+
+  
+
+
+  
2.3.10 Media queries

+
+  
A string is a valid media query list if it matches the <media-query-list> production of the Media Queries specification. [MQ]

+
+  
A string matches the environment of the user if it is the empty string, a string
+  consisting of only ASCII whitespace, or is a media query list that matches the user's
+  environment according to the definitions given in the Media Queries specification. [MQ]

+
+
+
+
+  
2.4 URLs

+
+  
2.4.1 Terminology

+
+  
A string is a valid non-empty URL if it is a valid URL string but it is
+  not the empty string.

+
+  
A string is a valid URL potentially surrounded by spaces if, after stripping leading and trailing ASCII
+  whitespace from it, it is a valid URL string.

+
+  
A string is a valid non-empty URL potentially surrounded by spaces if, after stripping leading and trailing ASCII
+  whitespace from it, it is a valid non-empty URL.

+
+  
This specification defines the URL about:legacy-compat as a reserved,
+  though unresolvable, about: URL, for use in DOCTYPEs in HTML documents when needed for
+  compatibility with XML tools. [ABOUT]

+
+  
This specification defines the URL about:html-kind as a reserved,
+  though unresolvable, about: URL, that is used as an
+  identifier for kinds of media tracks. [ABOUT]

+
+  
This specification defines the URL about:srcdoc as a reserved, though
+  unresolvable, about: URL, that is used as the URL of iframe srcdoc documents.
+  [ABOUT]

+
+  
The fallback base URL of a Document object document is the
+  URL record obtained by running these steps:

+
+  
  1. If document is an iframe srcdoc document, then return the document base
+   URL of document's browsing context's
+   browsing context container's node document.
  2. 
+
+    
+
+    
+
+    
    If document's URL is
+    about:blank, and document's browsing
+    context has a creator browsing context, then return the creator base
+    URL.
    
+
+   
  3. Return document's URL.

+
+  
The document base URL of a Document object is the
+  absolute URL obtained by running these steps:

+
+  
  1. If there is no base element that has an href attribute in the Document, then the
+   document base URL is the Document's fallback base URL;
+   abort these steps.
  2. Otherwise, the document base URL is the frozen base URL of the
+   first base element in the Document that has an href attribute, in tree order.

+
+
+  
+
+  
2.4.2 Parsing URLs

+
+  
Parsing a URL is the process of taking a string and obtaining the URL record that
+  it represents. While this process is defined in the WHATWG URL standard, the HTML standard defines
+  a wrapper for convenience. [URL]

+
+  
This wrapper is only useful when the character encoding for the URL parser has to
+  match that of the document or environment settings object for legacy reasons. When that is not the
+  case the URL parser can be used directly.

+
+  
To parse a URL url, relative to either a
+  document or environment settings object, the user agent must use the
+  following steps. Parsing a URL either results in failure or a resulting URL string
+  and resulting URL record.

+
+  
  1. Let encoding be document's character encoding, if document was given, and environment
+   settings object's API URL character encoding otherwise.
  2. Let baseURL be document's base
+   URL, if document was given, and environment settings object's
+   API base URL otherwise.
  3. Let urlRecord be the result of applying the URL parser to
+   url, with baseURL and encoding.
  4. If urlRecord is failure, then abort these steps with an error.
  5. Let urlString be the result of applying the URL serializer to urlRecord.
  6. Return urlString as the resulting URL string and
+   urlRecord as the resulting URL record.

+
+  
+
+
+
+  
+
+  
2.4.3 Dynamic changes to base URLs

+
+  
When a document's document base URL changes, all elements in that document are
+  affected by a base URL change.

+
+  
The following are base URL change steps, which run when an element is
+  affected by a base URL change (as defined by the DOM specification):

+
+  
If the element creates a hyperlink

+
+    
If the URL identified by the hyperlink is being shown to the user, or if any
+    data derived from that URL is affecting the display, then the href attribute should be reparsed relative to the element's node document and the UI updated
+    appropriately.

+
+    
For example, the CSS :link/:visited pseudo-classes
+    might have been affected.

+
+    
If the hyperlink has a ping attribute and its
+    URL(s) are being shown to the user, then the ping attribute's tokens should be reparsed relative to the element's node document and the UI updated
+    appropriately.

+
+   
If the element is a q, blockquote, ins, or
+   del element with a cite attribute

+
+    
If the URL identified by the cite attribute is being
+    shown to the user, or if any data derived from that URL is affecting the display,
+    then the URL should be reparsed relative to the
+    element's node document and the UI updated appropriately.

+
+   
Otherwise

+
+    
The element is not directly affected.

+
+    
For instance, changing the base URL doesn't affect the image displayed by
+    img elements, although subsequent accesses of the src IDL attribute from script will return a new absolute
+    URL that might no longer correspond to the image being shown.

+
+   

+
+  
+
+
+  
+
+  
2.5 Fetching resources
Spec bugs: 11235

+
+  
2.5.1 Terminology

+
+  
A response whose type is "basic", "cors", or "default" is CORS-same-origin. [FETCH]

+
+  
A response whose type is "opaque" or "opaqueredirect" is CORS-cross-origin.

+
+  
A response's unsafe response
+  is its internal response if it has one, and the
+  response itself otherwise.

+
+  
To create a potential-CORS request, given a url, destination,
+  corsAttributeState, and an optional same-origin fallback flag, run these
+  steps:

+
+  
  1. Let mode be "no-cors" if corsAttributeState
+   is No CORS, and "cors"
+   otherwise.
  2. If same-origin fallback flag is set and mode is "no-cors", set mode to "same-origin".
  3. Let credentialsMode be "include".
  4. If corsAttributeState is Anonymous, set credentialsMode to "same-origin".
  5. Let request be a new request whose
+   url is url, destination is destination,
+   mode is mode, credentials mode is
+   credentialsMode, and whose use-URL-credentials flag is set.

+
+
+  
2.5.2 Determining the type of a resource

+
+  
The Content-Type metadata of a resource must be obtained and
+  interpreted in a manner consistent with the requirements of the WHATWG MIME Sniffing standard.
+  [MIMESNIFF]

+
+  
The computed MIME type of a
+  resource must be found in a manner consistent with the requirements given in the WHATWG MIME
+  Sniffing standard. [MIMESNIFF]

+
+  
The rules for
+  sniffing images specifically, the rules for distinguishing
+  if a resource is text or binary, and the rules
+  for sniffing audio and video specifically are also defined in the WHATWG MIME Sniffing
+  standard. These rules return a MIME type as their result. [MIMESNIFF]

+
+  
It is imperative that the rules in the WHATWG MIME Sniffing standard be
+  followed exactly. When a user agent uses different heuristics for content type detection than the
+  server expects, security problems can occur. For more details, see the WHATWG MIME Sniffing
+  standard. [MIMESNIFF]

+
+
+  
2.5.3 Extracting character encodings from meta elements

+
+  
The algorithm for extracting a character encoding from a meta element,
+  given a string s, is as follows. It either returns a character encoding or
+  nothing.

+
+  
  1. Let position be a pointer into s, initially
+   pointing at the start of the string.
  2. Loop: Find the first seven characters in s after position that are an ASCII case-insensitive match for the word "charset". If no such match is found, return nothing and abort these
+   steps.
  3. Skip any ASCII whitespace that immediately follow the word "charset" (there might not be any).
  4. If the next character is not a U+003D EQUALS SIGN (=), then move position to point just before that next character, and jump back to the step
+   labeled loop.
  5. Skip any ASCII whitespace that immediately follow the equals sign (there
+   might not be any).
  6. 
+
+    
    Process the next character as follows:
    
+
+    
    If it is a U+0022 QUOTATION MARK character (") and there is a later U+0022 QUOTATION MARK character (") in s
    If it is a U+0027 APOSTROPHE character (') and there is a later U+0027 APOSTROPHE character (') in s
    Return the result of getting an encoding from the substring that is between
+     this character and the next earliest occurrence of this character.
    If it is an unmatched U+0022 QUOTATION MARK character (")
    If it is an unmatched U+0027 APOSTROPHE character (')
    If there is no next character
    Return nothing.
    Otherwise
    Return the result of getting an encoding from the substring that consists of
+     this character up to but not including the first ASCII whitespace or U+003B
+     SEMICOLON character (;), or the end of s, whichever comes first.
    
+
+   

+
+  
This algorithm is distinct from those in the HTTP specification (for example, HTTP
+  doesn't allow the use of single quotes and requires supporting a backslash-escape mechanism that
+  is not supported by this algorithm). While the algorithm is used in
+  contexts that, historically, were related to HTTP, the syntax as supported by implementations
+  diverged some time ago. [HTTP]

+
+  
+
+
+  
2.5.4 CORS settings attributes

+
+  
A CORS settings attribute is an enumerated attribute. The following
+  table lists the keywords and states for the attribute — the keywords in the left column map
+  to the states in the cell in the second column on the same row as the keyword.

+
+  
 Keyword
+      State
+      Brief description
+   
anonymous
+     Anonymous
+     Requests for the element will have their mode set to "cors" and their credentials mode set to "same-origin".
+    
use-credentials
+     Use Credentials
+     Requests for the element will have their mode set to "cors" and their credentials mode set to "include".
+  

+
+  
The empty string is also a valid keyword, and maps to the Anonymous state. The attribute's invalid value default is the Anonymous state. For the
+  purposes of reflection, the canonical case for the Anonymous state is the anonymous keyword. The missing value default, used when the attribute is omitted, is the No
+  CORS state.

+
+
+  
2.5.5 Referrer policy attributes

+
+  
A referrer policy attribute is an enumerated attribute.
+  Each referrer policy, including the empty string, is a keyword for this attribute,
+  mapping to a state of the same name.

+
+  
The attribute's invalid value default and missing value default are both the empty string state.

+
+  
The impact of these states on the processing model of various fetches is defined in more detail throughout this specification, in
+  the WHATWG Fetch standard, and in Referrer Policy. [FETCH] [REFERRERPOLICY]

+
+  

+   
Several signals can contribute to which processing model is used for a given fetch; a referrer policy attribute is only one of
+   them. In general, the order in which these signals are processed are:

+
+   
  1. First, the presence of a noreferrer link
+    type;
  2. Then, the value of a referrer policy attribute;
  3. Then, the presence of any meta element with name attribute set to referrer.
  4. Finally, the `Referrer-Policy` HTTP
+    header.

+  

+
+
+  
2.6 Common DOM interfaces

+
+  
2.6.1 Reflecting content attributes in IDL attributes

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

+
+  
+
+  
In general, on getting, if the content attribute is not present, the IDL attribute must act as
+  if the content attribute's value is the empty string; and on setting, if the content attribute is
+  not present, it must first be added.

+
+  
If a reflecting IDL attribute is a USVString attribute
+  whose content attribute is defined to contain a URL, then on getting, if the
+  content attribute is absent, the IDL attribute must return the empty string. Otherwise, the IDL
+  attribute must parse the value of the content attribute relative
+  to the element's node document and if that is successful, return the resulting
+  URL string. If parsing fails, then the value of the content attribute must be returned
+  instead, converted to a USVString. On setting, the content attribute must be set to the
+  specified new value.

+
+  
If a reflecting IDL attribute is a DOMString attribute
+  whose content attribute is an enumerated attribute, and the IDL attribute is
+  limited to only known values, then, on getting, the IDL attribute must return the
+  conforming value associated with the state the attribute is in (in its canonical case), if any, or
+  the empty string if the attribute is in a state that has no associated keyword value or if the
+  attribute is not in a defined state (e.g. the attribute is missing and there is no missing value default). On setting, the content attribute must
+  be set to the specified new value.

+
+  
If a reflecting IDL attribute is a nullable DOMString
+  attribute whose content attribute is an enumerated attribute, then, on getting, if
+  the corresponding content attribute is in its missing value default then the IDL attribute
+  must return null, otherwise, the IDL attribute must return the conforming value associated with
+  the state the attribute is in (in its canonical case). On setting, if the new value is null, the
+  content attribute must be removed, and otherwise, the content attribute must be set to the
+  specified new value.

+
+  
If a reflecting IDL attribute is a DOMString or USVString attribute 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 IDL attribute is a boolean attribute, then on
+  getting the IDL attribute must return true if the content attribute is set, and false if it is
+  absent. On setting, the content attribute must be removed if the IDL attribute is set to false,
+  and must be set to the empty string if the IDL attribute is set to true. (This corresponds to the
+  rules for boolean content attributes.)

+
+  
If a reflecting IDL attribute has 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, and the
+  value is in the range of the IDL attribute's type, the resulting value must be returned. If, on
+  the other hand, it fails or returns an out of range value, 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 and then that string must be used as the new content attribute value.

+
+  
If a reflecting IDL attribute has a signed integer type (long)
+  that is limited to only non-negative numbers then, on getting, the content attribute
+  must be parsed according to the rules for parsing non-negative integers, and if that
+  is successful, and the value is in the range of the IDL attribute's type, the resulting value must
+  be returned. If, on the other hand, it fails or returns an out of range value, 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 negative, the user agent must throw an
+  "IndexSizeError" DOMException. Otherwise, the given value
+  must be converted to the shortest possible string representing the number as a valid
+  non-negative integer and then that string must be used as the new content attribute
+  value.

+
+  
If a reflecting IDL attribute has an unsigned integer type (unsigned long) then, on getting, the content attribute must be
+  parsed according to the rules for parsing non-negative integers, and if that is
+  successful, and the value is in the range 0 to 2147483647 inclusive, the resulting value must be
+  returned. If, on the other hand, it fails or returns an out of range value, or if the attribute is
+  absent, the default value must be returned instead, or 0 if there is no default value. On setting,
+  first, if the new value is in the range 0 to 2147483647, then let n be the new value,
+  otherwise let n be the default value, or 0 if there is no default value; then,
+  n must be converted to the shortest possible string representing the number as a
+  valid non-negative integer and that string must be used as the new content attribute
+  value.

+  
+
+  
If a reflecting IDL attribute has an unsigned integer type (unsigned long) that is limited to only non-negative numbers
+  greater than zero, 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 non-negative integers, and if that is successful, and the value is in the range 1
+  to 2147483647 inclusive, the resulting value must be returned. If, on the other hand, it fails or
+  returns an out of range value, 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
+  throw an "IndexSizeError" DOMException. Otherwise, first,
+  if the new value is in the range 1 to 2147483647, then let n be the new value,
+  otherwise let n be the default value, or 1 if there is no default value; then,
+  n must be converted to the shortest possible string representing the number as a
+  valid non-negative integer and that string must be used as the new content attribute
+  value.
 
+
+  
If a reflecting IDL attribute has an unsigned integer type (unsigned long) that is limited to only non-negative numbers
+  greater than zero with fallback, then the behavior is similar to the previous case, but
+  disallowed values are converted to the default value. On getting, the content attribute must first
+  be parsed according to the rules for parsing non-negative integers, and if that is
+  successful, and the value is in the range 1 to 2147483647 inclusive, the resulting value must be
+  returned. If, on the other hand, it fails or returns an out of range value, or if the attribute is
+  absent, the default value must be returned instead. On setting, first, if the new value is in the
+  range 1 to 2147483647, then let n be the new value, otherwise let n be the
+  default value; then, n must be converted to the shortest possible string representing
+  the number as a valid non-negative integer and that string must be used as the new
+  content attribute value.
 
+
+  
If a reflecting IDL attribute has an unsigned integer type (unsigned long) that is clamped to the range
+  [min, max], then on getting, the content attribute must first be parsed
+  according to the rules for parsing non-negative integers, and if that is successful,
+  and the value is between min and max inclusive, the resulting value must be
+  returned. If it fails, the default value must be returned. If it succeeds but the value is less
+  than min, min must be returned. If it succeeds but the value is greater than
+  max, max must be returned. On setting, it behaves the same as setting a
+  regular reflected unsigned integer.

+
+  
If a reflecting IDL attribute has a floating-point number type (double or unrestricted
+  double), 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 best representation of the number as a floating-point
+  number and then that string must be used as the new content attribute value.

+
+  
If a reflecting IDL attribute has a floating-point number type (double or unrestricted
+  double) that is limited to numbers greater than zero, then the behavior is
+  similar to the previous case, but zero and negative values are not allowed. On getting, the
+  content attribute must be parsed according to the rules for parsing floating-point number
+  values, and if that is successful and the value is greater than 0.0, the resulting value
+  must be returned. If, on the other hand, it fails or returns an out of range value, or if the
+  attribute is absent, the default value must be returned instead, or 0.0 if there is no default
+  value. On setting, if the value is less than or equal to zero, then the value must be ignored.
+  Otherwise, the given value must be converted to the best representation of the number as a
+  floating-point number and then that string must be used as the new content attribute
+  value.

+
+  
The values Infinity and Not-a-Number (NaN) values throw an exception on setting,
+  as defined in the Web IDL specification. [WEBIDL]

+
+  
If a reflecting IDL attribute has the type DOMTokenList, then on getting it must
+  return a DOMTokenList object whose associated element is the element in question and
+  whose associated attribute's local name is the name of the attribute in question.

+
+  
If a reflecting IDL 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):

+
+  
  1. If the corresponding content attribute is absent, then the IDL attribute must return
+   null.
  2. Let candidate be the element that the document.getElementById() method would find when
+   called on the content attribute's element's node document if it were passed as its argument the current value of
+   the corresponding content attribute.
  3. If candidate is null, or if it is not type-compatible with the IDL
+   attribute, then the IDL attribute must return null.
  4. Otherwise, it must return candidate.

+
+  
On setting, if the given element has an id attribute, and has the
+  same tree as the element of the attribute being set, and the given element is the
+  first element in that tree whose ID is the value of
+  that id attribute, then the content attribute must be set to the
+  value of that id attribute. Otherwise, the content attribute must be
+  set to the empty string.

+
+  
+
+
+  
2.6.2 Collections

+
+  
The HTMLFormControlsCollection and HTMLOptionsCollection interfaces
+  are collections derived from the
+  HTMLCollection interface. The HTMLAllCollection interface is a collection, but is not so derived.

+
+
+  
2.6.2.1 The HTMLAllCollection interface

+
+  
The HTMLAllCollection interface is used for the legacy document.all attribute. It operates similarly to
+  HTMLCollection; the main differences are that it allows a staggering variety of
+  different (ab)uses of its methods to all end up returning something, and that it can be called as
+  a function as an alternative to property access.

+
+  
All HTMLAllCollection objects are rooted at a Document
+  and have a filter that matches all elements, so the elements represented by the
+  collection of an HTMLAllCollection object consist of all the descendant
+  elements of the root Document.

+
+  
[LegacyUnenumerableNamedProperties]
+interface HTMLAllCollection {
+  readonly attribute unsigned long length;
+  getter Element? (unsigned long index);
+  getter (HTMLCollection or Element)? namedItem(DOMString name);
+  legacycaller (HTMLCollection or Element)? item(optional DOMString nameOrIndex);
+};

+
+  
collection . length

+    
Returns the number of elements in the collection.

+   
element = collection . item(index)
element = collection(index)
element = collection[index]

+    
Returns the item with index index from the collection (determined by tree order).

+   
element = collection . item(name)
collection = collection . item(name)
element = collection . namedItem(name)
collection = collection . namedItem(name)
element = collection(name)
collection = collection(name)
element = collection[name]
collection = collection[name]

+    
Returns the item with ID or name name from the collection.

+    
If there are multiple matching items, then an HTMLCollection object containing all those elements is returned.

+    
+    
Only button, form, iframe,
+    input, map, meta, object,
+    select, and textarea elements can have a name for the purpose of this
+    method; their name is given by the value of their name attribute.

+   

+
+  
+
+  
The object's supported property indices are as defined for
+  HTMLCollection objects.

+
+  
The supported property names consist of the non-empty values of all the id attributes of all the elements represented by the
+  collection, and the non-empty values of all the name attributes of
+  all the "all"-named elements represented by the collection, in
+  tree order, ignoring later duplicates, with the id of
+  an element preceding its name if it contributes both, they differ from each
+  other, and neither is the duplicate of an earlier entry.

+
+  
On getting, the length
+  attribute must return the number of nodes represented by the collection.

+
+  
The indexed property getter must return the result of getting the "all"-indexed element from this
+  HTMLAllCollection given the passed index.

+
+  
The namedItem(name)
+  method must return the result of getting the "all"-named
+  element(s) from this HTMLAllCollection given name.

+
+  
The item(nameOrIndex)
+  method (and the legacycaller behavior) must run the following steps:

+
+  
  1. If nameOrIndex was not provided, return null.
  2. If nameOrIndex, converted to a
+   JavaScript string value, is an array index property name, return the result of getting the "all"-indexed element from this
+   HTMLAllCollection given the number represented by nameOrIndex.
  3. Return the result of getting the "all"-named
+   element(s) from this HTMLAllCollection given
+   nameOrIndex.

+
+  

+
+  
+  
The following elements are "all"-named elements:
+   a, 
+   applet,
+   button, 
+   embed,
+   form,
+   frame,
+   frameset,
+   iframe, 
+   img,
+   input,
+   
+   map, 
+   meta, 
+   object,
+   select, and
+   textarea 
+  

+
+  
To get the "all"-indexed element from an
+  HTMLAllCollection collection given an index index, return the
+  indexth element in collection, or null if there is no such
+  indexth element.

+
+  
To get the "all"-named element(s) from an
+  HTMLAllCollection collection given a name name, perform the
+  following steps:

+
+  
  1. If name is the empty string, return null.
  2. 
+    
    Let subCollection be an HTMLCollection object rooted at the same
+    Document as collection, whose filter matches only elements that are
+    either:
    
+
+    
+   
  3. If there is exactly one element in subCollection, then return that
+   element.
  4. Otherwise, if subCollection is empty, return null.
  5. Otherwise, return subCollection.

+
+  
+
+
+  
2.6.2.2 The HTMLFormControlsCollection interface

+
+  
The HTMLFormControlsCollection interface is used for
+  collections of listed
+  elements in form elements.

+
+  
interface HTMLFormControlsCollection : HTMLCollection {
+  // inherits length and item()
+  getter (RadioNodeList or Element)? namedItem(DOMString name); // shadows inherited namedItem()
+};
+
+interface RadioNodeList : NodeList {
+  attribute DOMString value;
+};

+
+  
collection . length

+    
Returns the number of elements in the collection.

+   
element = collection . item(index)
element = collection[index]

+    
Returns the item with index index from the collection. The items are sorted in tree order.

+   
element = collection . namedItem(name)
radioNodeList = collection . namedItem(name)
element = collection[name]
radioNodeList = collection[name]

+    
Returns the item with ID or name name from the collection.

+    
If there are multiple matching items, then a RadioNodeList object containing all those elements is returned.

+   
radioNodeList . value [ = value ]

+    
Returns the value of the first checked radio button represented by the object.

+    
Can be set, to check the first radio button with the given value represented by the object.

+   

+
+  
+
+  
The object's supported property indices are as defined for
+  HTMLCollection objects.

+
+  
The supported property names consist of the non-empty values of all the id and name attributes of all the
+  elements represented by the collection, in tree order, ignoring later
+  duplicates, with the id of an element preceding its name if it contributes both, they differ from each other, and neither is the
+  duplicate of an earlier entry.

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

+
+  
  1. If name is the empty string, return null and stop the algorithm.
  2. 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 name, then return that node and stop the algorithm.
  3. Otherwise, if there are no nodes in the collection that have either an id attribute or a name attribute equal
+   to name, then return null and stop the algorithm.
  4. Otherwise, create a new RadioNodeList object representing a live
+   view of the HTMLFormControlsCollection object, further filtered so that the only
+   nodes in the RadioNodeList object are those that have either an id attribute or a name attribute equal
+   to name. The nodes in the RadioNodeList object must be sorted in
+   tree order.
  5. Return that RadioNodeList object.

+
+  

+
+  
Members of the RadioNodeList interface inherited from the NodeList
+  interface must behave as they would on a NodeList object.

+
+  
The value IDL attribute on the
+  RadioNodeList object, on getting, must return the value returned by running the
+  following steps:

+
+  
  1. Let element be the first element in tree order
+   represented by the RadioNodeList object that is an input element whose
+   type attribute is in the Radio Button state and whose checkedness is true. Otherwise, let it be null.
  2. If element is null, return the empty string.
  3. If element is an element with no value attribute, return the string "on".
  4. Otherwise, return the value of element's value attribute.

+
+  
On setting, the value IDL attribute must run the
+  following steps:

+
+  
  1. If the new value is the string "on": let element be the first element in tree order
+   represented by the RadioNodeList object that is an input element whose
+   type attribute is in the Radio Button state and whose value content attribute is either absent, or present and equal to the new value, if any. If no such element exists, then instead let element be null.
    
+
+   
    Otherwise: let element be the first element in tree order
+   represented by the RadioNodeList object that is an input element whose
+   type attribute is in the Radio Button state and whose value content attribute is present and equal to the new value, if
+   any. If no such element exists, then instead let element be null.
  2. If element is not null, then set its checkedness to true.
    
+
+  

+
+
+
+  
+
+
+  
2.6.2.3 The HTMLOptionsCollection interface

+
+  
The HTMLOptionsCollection interface is used for collections of option elements. It is always
+  rooted on a select element and has attributes and methods that manipulate that
+  element's descendants.

+
+  
interface HTMLOptionsCollection : HTMLCollection {
+  // inherits item(), namedItem()
+  [CEReactions] attribute unsigned long length; // shadows inherited length
+  [CEReactions] setter void (unsigned long index, HTMLOptionElement? option);
+  [CEReactions] void add((HTMLOptionElement or HTMLOptGroupElement) element, optional (HTMLElement or long)? before = null);
+  [CEReactions] void remove(long index);
+  attribute long selectedIndex;
+};

+
+  
collection . length [ = value ]

+    
Returns the number of elements in the collection.

+    
When set to a smaller number, truncates the number of option elements in the corresponding container.

+    
When set to a greater number, adds new blank option elements to that container.

+   
element = collection . item(index)
element = collection[index]

+    
Returns the item with index index from the collection. The items are sorted in tree order.

+   
collection[index] = element

+    
When index is a greater number than the number of items in the collection, adds
+    new blank option elements in the corresponding container.
+    
When set to null, removes the item at index index from the collection.

+    
When set to an option element, adds or replaces it at index index
+    from the collection.

+   
element = collection . namedItem(name)
element = collection[name]

+    
Returns the item with ID or name name from the collection.

+    
If there are multiple matching items, then the first is returned.

+   
collection . add(element [, before ] )

+    
Inserts element before the node given by before.

+    
The before argument can be a number, in which case element is inserted before the item with that number, or an element from the
+    collection, in which case element is inserted before that element.

+    
If before is omitted, null, or a number out of range, then element will be added at the end of the list.

+    
This method will throw a "HierarchyRequestError" DOMException if
+    element is an ancestor of the element into which it is to be inserted.

+   
collection . remove(index)

+    
Removes the item with index index from the collection.

+   
collection . selectedIndex [ = value ]

+
+    
Returns the index of the first selected item, if any, or −1 if there is no selected
+    item.

+
+    
Can be set, to change the selection.

+
+   

+
+  
+
+  
The object's supported property indices are as defined for
+  HTMLCollection objects.

+
+  
On getting, the length
+  attribute must return the number of nodes represented by the collection.

+
+  
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). Mutation events must be fired as if a DocumentFragment containing the new
+  option elements had been inserted. 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 supported property names consist of the non-empty values of all the id and name attributes of all the
+  elements represented by the collection, in tree order, ignoring later
+  duplicates, with the id of an element preceding its name if it contributes both, they differ from each other, and neither is
+  the duplicate of an earlier entry.

+
+  
When the user agent is to set the value of a new
+  indexed property or set the value of an existing indexed property for a given
+  property index index to a new value value, it must run the following
+  algorithm:

+
+  
  1. If value is null, invoke the steps for the remove method with index as
+   the argument, and abort these steps.
  2. Let length be the number of nodes represented by the
+   collection.
  3. Let n be index minus length.
  4. If n is greater than zero, then append a DocumentFragment consisting of n-1 new option elements with no attributes and
+   no child nodes to the select element on which the HTMLOptionsCollection
+   is rooted.
  5. If n is greater than or equal to zero, append value to the select
+   element. Otherwise, replace the indexth element in the collection by value.

+
+  
The add(element, before) method must act according to the following algorithm:

+
+  
  1. If element is an ancestor of the select element on which
+   the HTMLOptionsCollection is rooted, then throw a
+   "HierarchyRequestError" DOMException and abort these
+   steps.
  2. If before is an element, but that element isn't a descendant of the
+   select element on which the HTMLOptionsCollection is rooted, then throw
+   a "NotFoundError" DOMException and abort these
+   steps.
  3. If element and before are the same element, then
+   return and abort these steps.
  4. If before is a node, then let reference be that
+   node. Otherwise, if before is an integer, and there is a beforeth node in the collection, let reference be that node.
+   Otherwise, let reference be null.
  5. If reference is not null, let parent be the parent
+   node of reference. Otherwise, let parent be the
+   select element on which the HTMLOptionsCollection is rooted.
  6. Pre-insert element into parent node before
+   reference.
    
+
+  

+
+  
The remove(index) method must act according to the following algorithm:

+
+  
  1. If the number of nodes represented by the collection is zero, abort these
+   steps.
  2. If index is not a number greater than or equal to 0 and less than the
+   number of nodes represented by the collection, abort these steps.
  3. Let element be the indexth element in the
+   collection.
  4. Remove element from its parent node.

+
+  
The selectedIndex IDL
+  attribute must act like the identically named attribute on the select element on
+  which the HTMLOptionsCollection is rooted

+
+  
+
+  
+
+
+  
2.6.3 The DOMStringList interface

+
+  
The DOMStringList interface is a non-fashionable retro way of representing a list
+  of strings.

+
+  
[Exposed=(Window,Worker)]
+interface DOMStringList {
+  readonly attribute unsigned long length;
+  getter DOMString? item(unsigned long index);
+  boolean contains(DOMString string);
+};

+
+  
New APIs must use sequence<DOMString> or
+  equivalent rather than DOMStringList.

+
+  
strings . length
Returns the number of strings in strings.
strings[index]
strings . item(index)
Returns the string with index index from strings.
strings . contains(string)
Returns true if strings contains string, and false
+   otherwise.

+
+  
+
+  
Each DOMStringList object has an associated list.

+
+  
The supported property indices for a DOMStringList object are the
+  numbers zero to the associated list's size minus one. If its
+  associated list is empty, it has no supported property
+  indices.

+
+  
The length attribute's getter must
+  this DOMStringList object's associated list's size.

+
+  
The item(index) method, when
+  invoked, must return the indexth item in this DOMStringList object's
+  associated list, or null if index plus one is less than this DOMStringList
+  object's associated list's size.

+
+  
The contains(string)
+  method, when invoked, must return true if this DOMStringList object's associated list
+  contains string, and false otherwise.

+
+  
+
+
+  
+
+  
2.6.4 Garbage collection

+
+  
There is an implied strong reference from any IDL attribute that returns a
+  pre-existing object to that object.

+
+  

+
+   
For example, the window.document attribute means that there
+   is a strong reference from a Window object to its Document object.
+   Similarly, there is always a strong reference from a Document to any
+   descendant nodes, and from any node to its node document.

+
+  

+
+  
+
+
+  
+
+  
2.7 Safe passing of structured data

+
+  
This section uses the terminology and typographic conventions from the JavaScript
+  specification. [JAVASCRIPT]

+
+  
2.7.1 Serializable objects

+
+  
Serializable objects support being serialized, and later deserialized, in a way
+  that is independent of any given JavaScript Realm. This allows them to be stored on
+  disk and later restored, or cloned across document and worker boundaries (including across
+  documents of different origins or in different event loops).

+
+  
Not all objects are serializable objects, and not all aspects of objects that are
+  serializable objects are necessarily preserved when they are serialized.

+
+  
Platform objects can be serializable objects
+  if they implement only interfaces decorated with the [Serializable] IDL extended attribute. Such
+  interfaces must also define the following algorithms:

+
+  
serialization steps, taking a platform object
+   value, a Record serialized, and a boolean
+   forStorage

+    
A set of steps that serializes the data in value into fields of
+    serialized. The resulting data serialized into serialized must be
+    independent of any JavaScript Realm.

+
+    
These steps may throw an exception if serialization is not possible.

+
+    
These steps may perform a sub-serialization to serialize nested data
+    structures. They should not call StructuredSerialize directly, as doing so will
+    omit the important memory argument.

+
+    
The introduction of these steps should omit mention of the forStorage argument if
+    it is not relevant to the algorithm.

+   
deserialization steps, taking a Record
+   serialized and a platform object value

+    
A set of steps that deserializes the data in serialized, using it to set up
+    value as appropriate. value will be a newly-created instance of the
+    platform object type in question, with none of its internal data set up; setting
+    that up is the job of these steps.

+
+    
These steps may throw an exception if deserialization is not possible.

+
+    
These steps may perform a sub-deserialization to deserialize nested data
+    structures. They should not call StructuredDeserialize directly, as doing so will
+    omit the important targetRealm and memory arguments.

+   

+
+  
It is up to the definition of individual platform objects to determine what data is serialized
+  and deserialized by these steps. Typically the steps are very symmetric.

+
+  
The [Serializable] extended attribute must take no
+  arguments, and must not appear on anything other than an interface. It must appear only once on an
+  interface. It must not be used on a callback interface. If it appears on a partial interface or an
+  interface that is really a mixin, then it must also appear on the original or mixed-in-to
+  interface, and any supplied serialization steps and deserialization
+  steps for the partial interface or mixin should be understood as being appended to those of
+  the original or mixed-in-to interface.

+
+  

+   
Let's say we were defining a platform object Person, which had
+   associated with it two pieces of associated data:

+
+   
  • a name value, which is a string;
  • and a best friend value, which is either another Person instance or
+    null

+
+   
We could then define Person instances to be serializable
+   objects by annotating the Person interface with the [Serializable] extended attribute, and defining the
+   following accompanying algorithms:

+
+   
serialization steps

+     
  1. Set serialized.[[Name]] to value's associated name
+      value.
  2. Let serializedBestFriend be the sub-serialization of
+      value's associated best friend value.
  3. Set serialized.[[BestFriend]] to serializedBestFriend.

+    
deserialization steps

+     
  1. Set value's associated name value to
+      serialized.[[Name]].
  2. Let deserializedBestFriend be the sub-deserialization of
+      serialized.[[BestFriend]].
  3. Set value's associated best friend value to
+      deserializedBestFriend.

+    

+  

+
+  
Objects defined in the JavaScript specification are handled by the
+  StructuredSerialize abstract operation directly.

+
+  
Originally, this specification defined the concept of
+  "cloneable objects", which could be cloned from one JavaScript Realm to another.
+  However, to better specify the behavior of certain more complex situations, the model was updated
+  to make the serialization and deserialization explicit.

+
+  
2.7.2 Transferable objects

+
+  
Transferable objects support being transferred across event loops. Transferring is effectively recreating the object while sharing a
+  reference to the underlying data and then detaching the object being transferred. This is useful
+  to transfer ownership of expensive resources. Not all objects are transferable
+  objects and not all aspects of objects that are transferable objects are
+  necessarily preserved when transferred.

+
+  
Transferring is an irreversible and non-idempotent operation. Once an object has
+  been transferred, it cannot be transferred, or indeed used, again.

+
+  
Platform objects can be transferable objects
+  if they implement only interfaces decorated with the [Transferable] IDL extended attribute. Such
+  interfaces must also define the following algorithms:

+
+  
transfer steps, taking a platform object
+   value and a Record dataHolder

+    
A set of steps that transfers the data in value into fields of
+    dataHolder. The resulting data held in dataHolder must be
+    independent of any JavaScript Realm.

+
+    
These steps may throw an exception if transferral is not possible.

+   
transfer-receiving steps, taking a Record
+   dataHolder and a platform object value

+    
A set of steps that receives the data in dataHolder, using it to set up
+    value as appropriate. value will be a newly-created instance of the
+    platform object type in question, with none of its internal data set up; setting
+    that up is the job of these steps.

+
+    
These steps may throw an exception if it is not possible to receive the transfer.

+   

+
+  
It is up to the definition of individual platform objects to determine what data is transferred
+  by these steps. Typically the steps are very symmetric.

+
+  
The [Transferable] extended attribute must take no
+  arguments, and must not appear on anything other than an interface. It must appear only once on an
+  interface. It must not be used on a callback interface. If it appears on a partial interface or an
+  interface that is really a mixin, then it must also appear on the original or mixed-in-to
+  interface, and any supplied serialization steps and deserialization
+  steps for the partial interface or mixin should be understood as being appended to those of
+  the original or mixed-in-to interface.

+
+  
Platform objects that are transferable
+  objects have a [[Detached]] internal slot. This is used to ensure that once a
+  platform object has been transferred, it cannot be transferred again.

+
+  
Objects defined in the JavaScript specification are handled by the
+  StructuredSerializeWithTransfer abstract operation directly.

+
+  
2.7.3 StructuredSerializeInternal ( value,
+  forStorage [ , memory ] )

+
+  
The StructuredSerializeInternal abstract operation takes as input a JavaScript
+  value value and serializes it to a Realm-independent form, represented here as a Record. This serialized
+  form has all the information necessary to later deserialize into a new JavaScript value in a
+  different Realm.

+
+  
This process can throw an exception, for example when trying to serialize un-serializable
+  objects.

+
+  
  1. 
+    
    If memory was not supplied, let memory be an empty map.
    
+
+    
    The purpose of the memory map is to avoid serializing objects twice.
+    This ends up preserving cycles and the identity of duplicate objects in graphs.
    
+   
  2. If memory[value] exists, then
+   return memory[value].
  3. Let deep be false.
  4. If Type(value) is Undefined, Null, Boolean,
+   String, or Number, then return { [[Type]]: "primitive", [[Value]]: value }.
  5. If Type(value) is Symbol, then throw a
+   "DataCloneError" DOMException.
  6. Let serialized be an uninitialized value.
  7. If value has a [[BooleanData]] internal slot, then set serialized to
+   { [[Type]]: "Boolean", [[BooleanData]]: value.[[BooleanData]] }.
  8. Otherwise, if value has a [[NumberData]] internal slot, then set
+   serialized to { [[Type]]: "Number", [[NumberData]]: value.[[NumberData]]
+   }.
  9. Otherwise, if value has a [[StringData]] internal slot, then set
+   serialized to { [[Type]]: "String", [[StringData]]: value.[[StringData]]
+   }.
  10. Otherwise, if value has a [[DateValue]] internal slot, then set
+   serialized to { [[Type]]: "Date", [[DateValue]]: value.[[DateValue]]
+   }.
  11. Otherwise, if value has a [[RegExpMatcher]] internal slot, then set
+   serialized to { [[Type]]: "RegExp", [[RegExpMatcher]]:
+   value.[[RegExpMatcher]], [[OriginalSource]]: value.[[OriginalSource]],
+   [[OriginalFlags]]: value.[[OriginalFlags]] }.
  12. 
+    
    Otherwise, if value has an [[ArrayBufferData]] internal slot, then:
    
+
+    
    1. Let size be value.[[ArrayBufferByteLength]].
    2. 
+      
      If ! IsSharedArrayBuffer(value) is true, then:
+
+      
      1. If forStorage is true, then throw a
+       "DataCloneError" DOMException.
      2. Set serialized to { [[Type]]: "SharedArrayBuffer", [[ArrayBufferData]]:
+       value.[[ArrayBufferData]], [[ArrayBufferByteLength]]: size,
+       [[AgentCluster]]: the current Realm Record's corresponding agent
+       cluster }.
      
+     
    3. 
+      
      Otherwise:
      
+
+      
      1. If ! IsDetachedBuffer(value) is true, then throw a
+       "DataCloneError" DOMException.
      2. 
+        
        Let dataCopy be ? CreateByteDataBlock(size).
        
+
+        
        This can throw a RangeError exception
+        upon allocation failure.
        
+       
      3. Perform ! CopyDataBlockBytes(dataCopy, 0,
+       value.[[ArrayBufferData]], 0, size).
      4. Set serialized to { [[Type]]: "ArrayBuffer", [[ArrayBufferData]]:
+       dataCopy, [[ArrayBufferByteLength]]: size }.
      
+     
    
+   
  13. 
+    
    Otherwise, if value has a [[ViewedArrayBuffer]] internal slot, then:
    
+
+    
    1. Let buffer be the value of value's [[ViewedArrayBuffer]] internal
+     slot.
    2. Let bufferSerialized be ?
+     StructuredSerializeInternal(buffer, forStorage,
+     memory).
    3. Assert: bufferSerialized.[[Type]] is "ArrayBuffer".
    4. If value has a [[DataView]] internal slot, then set serialized to
+     { [[Type]]: "ArrayBufferView", [[Constructor]]: "DataView", [[ArrayBufferSerialized]]:
+     bufferSerialized, [[ByteLength]]: value.[[ByteLength]], [[ByteOffset]]:
+     value.[[ByteOffset]] }.
    5. 
+      
      Otherwise:
      
+
+      
      1. Assert: value has a [[TypedArrayName]] internal slot.
      2. Set serialized to { [[Type]]: "ArrayBufferView", [[Constructor]]:
+       value.[[TypedArrayName]], [[ArrayBufferSerialized]]: bufferSerialized,
+       [[ByteLength]]: value.[[ByteLength]], [[ByteOffset]]:
+       value.[[ByteOffset]], [[ArrayLength]]: value.[[ArrayLength]] }.
      
+     
    
+   
  14. 
+    
    Otherwise, if value has [[MapData]] internal slot, then:
    
+
+    
    1. Set serialized to { [[Type]]: "Map", [[MapData]]: a new empty List }.
    2. Set deep to true.
    
+   
  15. 
+    
    Otherwise, if value has [[SetData]] internal slot, then:
    
+
+    
    1. Set serialized to { [[Type]]: "Set", [[SetData]]: a new empty List }.
    2. Set deep to true.
    
+   
  16. 
+    
    Otherwise, if value is an Array exotic object, then:
    
+    
+
+    
    1. Let valueLenDescriptor be ?
+     OrdinaryGetOwnProperty(value, "length").
    2. Let valueLen be valueLenDescriptor.[[Value]].
    3. Set serialized to { [[Type]]: "Array", [[Length]]: valueLen,
+     [[Properties]]: a new empty List }.
    4. Set deep to true.
    
+   
  17. 
+    
    Otherwise, if value is a platform object that is a serializable object:
    
+
+    
    1. If value has a [[Detached]] internal slot whose value is true,
+     then throw a "DataCloneError" DOMException.
    2. Let typeString be the identifier of the primary interface of
+     value.
    3. Set serialized to { [[Type]]: typeString }.
    4. Set deep to true.
    
+   
  18. Otherwise, if value is a platform object, then throw a
+   "DataCloneError" DOMException.
  19. Otherwise, if IsCallable(value) is true, then throw a
+   "DataCloneError" DOMException.
  20. 
+    
    Otherwise, if value has any internal slot other than [[Prototype]] or
+    [[Extensible]], then throw a "DataCloneError"
+    DOMException.
    
+
+    
    For instance, a [[PromiseState]] or [[WeakMapData]] internal slot.
    
+   
  21. 
+    
    Otherwise, if value is an exotic object, then throw a
+    "DataCloneError" DOMException.
    
+
+    
    For instance, a proxy object.
    
+   
  22. 
+    
    Otherwise:
    
+
+    
    1. Set serialized to { [[Type]]: "Object", [[Properties]]: a new empty List }.
    2. Set deep to true.
    
+   
  23. Set memory[value] to
+   serialized.
  24. 
+    
    If deep is true, then:
    
+
+    
    1. 
+      
      If value has a [[MapData]] internal slot, then:
+
+      
      1. Let copiedList be a new empty List.
+
+       
      2. 
+        
        For each Record { [[Key]], [[Value]] }
+        entry of value.[[MapData]]:
        
+
+        
        1. Let copiedEntry be a new Record { [[Key]]:
+         entry.[[Key]], [[Value]]: entry.[[Value]] }.
        2. If copiedEntry.[[Key]] is not the special value empty, append copiedEntry to copiedList.
        
+       
      3. 
+        
        For each Record { [[Key]], [[Value]] }
+        entry of copiedList:
        
+
+        
        1. Let serializedKey be ?
+         StructuredSerializeInternal(entry.[[Key]], forStorage,
+         memory).
        2. Let serializedValue be ?
+         StructuredSerializeInternal(entry.[[Value]], forStorage,
+         memory).
        3. Append { [[Key]]: serializedKey,
+         [[Value]]: serializedValue } to serialized.[[MapData]].
        
+       
      
+     
    2. 
+      
      Otherwise, if value has a [[SetData]] internal slot, then:
      
+
+      
      1. Let copiedList be a new empty List.
+
+       
      2. 
+        
        For each entry of value.[[SetData]]:
        
+
+        
        1. If entry is not the special value empty, append entry to copiedList.
        
+       
      3. 
+        
        For each entry of copiedList:
        
+
+        
        1. Let serializedEntry be ?
+         StructuredSerializeInternal(entry, forStorage,
+         memory).
        2. Append serializedEntry to
+         serialized.[[SetData]].
        
+       
      
+     
    3. 
+      
      Otherwise, if value is a platform object that is a serializable object, then perform the appropriate
+      serialization steps given value, serialized, and
+      forStorage.
      
+
+      
      The serialization steps may need to perform a sub-serialization. This is an operation which takes as input a value
+      subValue, and returns StructuredSerializeInternal(subValue,
+      forStorage, memory). (In other words, a sub-serialization
+      is a specialization of StructuredSerializeInternal to be consistent within this
+      invocation.)
      
+     
    4. 
+      
      Otherwise:
+
+      
      1. Let enumerableKeys be a new empty List.
      2. 
+        
        For each key in ! value.[[OwnPropertyKeys]]():
        
+
+        
        1. 
+          
          If Type(key) is String, then:
          
+
+          
          1. Let valueDesc be !
+           value.[[GetOwnProperty]](key).
          2. If valueDesc.[[Enumerable]] is true, then append key to enumerableKeys.
          
+         
        
+       
      3. 
+        
        For each key in enumerableKeys:
        
+
+        
        1. 
+          
          If ! HasOwnProperty(value, key) is true, then:
          
+
+          
          1. Let inputValue be ? value.[[Get]](key,
+           value).
          2. Let outputValue be ?
+           StructuredSerializeInternal(inputValue, forStorage,
+           memory).
          3. Append { [[Key]]: key, [[Value]]:
+           outputValue } to serialized.[[Properties]].
          
+         
        
+       
      
+
+      
      The key collection performed above is very similar to the JavaScript
+      specification's EnumerableOwnProperties operation, but crucially it uses the
+      deterministic ordering provided by the [[OwnPropertyKeys]] internal method, instead of
+      reordering the keys in an unspecified manner as EnumerableOwnProperties does.
+      [JAVASCRIPT]
      
+     
    
+   
  25. Return serialized.

+
+  

+   
It's important to realize that the Records
+   produced by StructuredSerializeInternal might contain "pointers" to other records
+   that create circular references. For example, when we pass the following JavaScript object into
+   StructuredSerializeInternal:

+
+  
const o = {};
+o.myself = o;

+
+  
it produces the following result:

+
+  
{
+  [[Type]]: "Object",
+  [[Properties]]: «
+    {
+      [[Key]]: "myself",
+      [[Value]]: <a pointer to this whole structure>
+    }
+  »
+}

+  

+
+
+  
2.7.4 StructuredSerialize ( value )

+
+  
  1. Return ? StructuredSerializeInternal(value, false).

+
+
+  
2.7.5 StructuredSerializeForStorage ( value )

+
+  
  1. Return ? StructuredSerializeInternal(value, true).

+
+
+  
2.7.6 StructuredDeserialize ( serialized,
+  targetRealm [ , memory ] )

+
+  
The StructuredDeserialize abstract operation takes as input a Record
+  serialized, which was previously produced by StructuredSerialize or
+  StructuredSerializeForStorage, and deserializes it into a new JavaScript value,
+  created in targetRealm.

+
+  
This process can throw an exception, for example when trying to allocate memory for the new
+  objects (especially ArrayBuffer objects).

+
+  
  1. 
+    
    If memory was not supplied, let memory be an empty map.
    
+
+    
    The purpose of the memory map is to avoid deserializing objects
+    twice. This ends up preserving cycles and the identity of duplicate objects in graphs.
    
+   
  2. If memory[serialized] exists, then
+   return memory[serialized].
  3. Let deep be false.
  4. Let value be an uninitialized value.
  5. 
+    
    If serialized contains a [[TransferConsumed]] field, then:
    
+
+    
    1. Assert: serialized.[[TransferConsumed]] is false. (It must be impossible to
+     get in a situation where StructuredDeserialize is being called multiple times on
+     the same serialization, if that serialization contains transfer data holders.)
    2. Set serialized.[[TransferConsumed]] to true.
    3. 
+      
      If serialized.[[Type]] is "ArrayBuffer", then set value to a new
+      ArrayBuffer object in targetRealm whose [[ArrayBufferData]] internal slot value is
+      serialized.[[ArrayBufferData]], and whose [[ArrayBufferByteLength]] internal slot
+      value is serialized.[[ArrayBufferByteLength]].
      
+
+      
      In cases where the original memory occupied by [[ArrayBufferData]] is
+      accessible during the deserialization, this step is unlikely to throw an exception, as no new
+      memory needs to be allocated: the memory occupied by [[ArrayBufferData]] is instead just
+      getting transferred into the new ArrayBuffer. This could be true, for example, when both the
+      source and target Realms are in the same process.
      
+     
    4. 
+      
      Otherwise:
      
+
+      
      1. Let interfaceName be serialized.[[Type]].
      2. If the interface identified by interfaceName is not exposed in
+       targetRealm, then throw a "DataCloneError"
+       DOMException.
      3. Set value to a new instance of the interface identified by
+       interfaceName, created in targetRealm.
      4. Perform the appropriate transfer-receiving steps for the interface
+       identified by interfaceName given serialized and
+       value.
      
+     
    
+   
  6. Otherwise, if serialized.[[Type]] is "primitive", then set value to
+   serialized.[[Value]].
    
+
+   
  7. Otherwise, if serialized.[[Type]] is "Boolean", then set value to a new Boolean object in
+   targetRealm whose [[BooleanData]] internal slot value is
+   serialized.[[BooleanData]].
  8. Otherwise, if serialized.[[Type]] is "Number", then set value to a new Number object in
+   targetRealm whose [[NumberData]] internal slot value is
+   serialized.[[NumberData]].
  9. Otherwise, if serialized.[[Type]] is "String", then set value to a new String object in
+   targetRealm whose [[StringData]] internal slot value is
+   serialized.[[StringData]].
  10. Otherwise, if serialized.[[Type]] is "Date", then set value to a new Date object in
+   targetRealm whose [[DateValue]] internal slot value is
+   serialized.[[DateValue]].
  11. Otherwise, if serialized.[[Type]] is "RegExp", then set value to a new RegExp object in
+   targetRealm whose [[RegExpMatcher]] internal slot value is
+   serialized.[[RegExpMatcher]], whose [[OriginalSource]] internal slot value is
+   serialized.[[OriginalSource]], and whose [[OriginalFlags]] internal slot value is
+   serialized.[[OriginalFlags]].
  12. 
+    
    Otherwise, if serialized.[[Type]] is "SharedArrayBuffer", then:
    
+
+    
    1. If targetRealm's corresponding agent cluster is not
+     serialized.[[AgentCluster]], then then throw a
+     "DataCloneError" DOMException.
    2. Otherwise, set value to a new SharedArrayBuffer object in
+     targetRealm whose [[ArrayBufferData]] internal slot value is
+     serialized.[[ArrayBufferData]] and whose [[ArrayBufferByteLength]] internal slot
+     value is serialized.[[ArrayBufferByteLength]].
    
+   
  13. 
+    
    Otherwise, if serialized.[[Type]] is "ArrayBuffer", then set value to a
+    new ArrayBuffer object in targetRealm whose [[ArrayBufferData]] internal slot value
+    is serialized.[[ArrayBufferData]], and whose [[ArrayBufferByteLength]] internal slot
+    value is serialized.[[ArrayBufferByteLength]].
    
+
+    
    If this throws an exception, then throw a "DataCloneError"
+    DOMException.
    
+
+    
    This step might throw an exception if there is not enough memory available to
+    create such an ArrayBuffer object.
    
+   
  14. 
+    
    Otherwise, if serialized.[[Type]] is "ArrayBufferView", then:
    
+
+    
    1. Let deserializedArrayBuffer be ?
+     StructuredDeserialize(serialized.[[ArrayBufferSerialized]],
+     targetRealm, memory).
    2. If serialized.[[Constructor]] is "DataView", then set value to a
+     new DataView object in targetRealm whose [[ViewedArrayBuffer]] internal slot value
+     is deserializedArrayBuffer, whose [[ByteLength]] internal slot value is
+     serialized.[[ByteLength]], and whose [[ByteOffset]] internal slot value is
+     serialized.[[ByteOffset]].
    3. Otherwise, set value to a new typed array object in targetRealm,
+     using the constructor given by serialized.[[Constructor]], whose
+     [[ViewedArrayBuffer]] internal slot value is deserializedArrayBuffer, whose
+     [[TypedArrayName]] internal slot value is serialized.[[Constructor]], whose
+     [[ByteLength]] internal slot value is serialized.[[ByteLength]], whose
+     [[ByteOffset]] internal slot value is serialized.[[ByteOffset]], and whose
+     [[ArrayLength]] internal slot value is serialized.[[ArrayLength]].
    
+   
  15. 
+    
    Otherwise, if serialized.[[Type]] is "Map", then:
    
+
+    
    1. Set value to a new Map object in targetRealm whose [[MapData]]
+     internal slot value is a new empty List.
    2. Set deep to true.
    
+   
  16. 
+    
    Otherwise, if serialized.[[Type]] is "Set", then:
    
+
+    
    1. Set value to a new Set object in targetRealm whose [[SetData]]
+     internal slot value is a new empty List.
    2. Set deep to true.
    
+   
  17. 
+    
    Otherwise, if serialized.[[Type]] is "Array", then:
    
+
+    
    1. Let outputProto be the %ArrayPrototype% intrinsic object in
+     targetRealm.
    2. Set value to ! ArrayCreate(serialized.[[Length]],
+     outputProto).
    3. Set deep to true.
    
+   
  18. 
+    
    Otherwise, if serialized.[[Type]] is "Object", then:
    
+
+    
    1. Set value to a new Object in targetRealm.
    2. Set deep to true.
    
+   
  19. 
+    
    Otherwise:
    
+
+    
    1. Let interfaceName be serialized.[[Type]].
    2. If the interface identified by interfaceName is not exposed in
+     targetRealm, then throw a "DataCloneError"
+     DOMException.
    3. Set value to a new instance of the interface identified by
+     interfaceName, created in targetRealm.
      
+
+     
    4. Set deep to true.
    
+   
  20. Set memory[serialized] to
+   value.
  21. 
+    
    If deep is true, then:
    
+
+    
    1. 
+      
      If serialized.[[Type]] is "Map", then:
      
+
+      
      1. 
+        
        For each Record { [[Key]], [[Value]] }
+        entry of serialized.[[MapData]]:
        
+
+        
        1. Let deserializedKey be ?
+         StructuredDeserialize(entry.[[Key]], targetRealm,
+         memory).
        2. Let deserializedValue be ?
+         StructuredDeserialize(entry.[[Value]], targetRealm,
+         memory).
        3. Append { [[Key]]: deserializedKey,
+         [[Value]]: deserializedValue } to value.[[MapData]].
        
+       
      
+     
    2. 
+      
      Otherwise, if serialized.[[Type]] is "Set", then:
      
+
+      
      1. 
+        
        For each entry of
+        serialized.[[SetData]]:
        
+
+        
        1. Let deserializedEntry be ?
+         StructuredDeserialize(entry, targetRealm,
+         memory).
        2. Append deserializedEntry to
+         value.[[SetData]].
        
+       
      
+     
    3. 
+      
      Otherwise, if serialized.[[Type]] is "Array" or "Object", then:
      
+
+      
      1. 
+        
        For each Record { [[Key]], [[Value]] }
+        entry of serialized.[[Properties]]:
        
+
+        
        1. Let deserializedValue be ?
+         StructuredDeserialize(entry.[[Value]], targetRealm,
+         memory).
        2. Let result be ! CreateDataProperty(value,
+         entry.[[Key]], deserializedValue).
        3. Assert: result is true.
        
+       
      
+     
    4. 
+      
      Otherwise:
      
+
+      
      1. 
+        
        Perform the appropriate deserialization steps for the interface identified
+        by serialized.[[Type]], given serialized and value.
        
+
+        
        The deserialization steps may need to perform a sub-deserialization. This is an operation which takes as input a
+        previously-serialized Record subSerialized, and returns
+        StructuredDeserialize(subSerialized, targetRealm,
+        memory). (In other words, a sub-deserialization is a specialization
+        of StructuredDeserialize to be consistent within this invocation.)
        
+       
      
+    
    
+   
  22. Return value.

+
+  
2.7.7 StructuredSerializeWithTransfer ( value,
+  transferList )

+
+  
  1. 
+    
    Let memory be an empty map.
    
+
+    
    In addition to how it is used normally by
+    StructuredSerializeInternal, in this algorithm memory is also used to
+    ensure that StructuredSerializeInternal ignores items in transferList,
+    and let us do our own handling instead.
    
+   
  2. 
+    
    For each transferable of
+    transferList:
    
+
+    
    1. If transferable has neither an [[ArrayBufferData]] internal slot nor a
+     [[Detached]] internal slot, then throw a
+     "DataCloneError" DOMException.
    2. If transferable has an [[ArrayBufferData]] internal slot and either !
+     IsSharedArrayBuffer(transferable) is true or !
+     IsDetachedBuffer(transferable) is true, then throw a
+     "DataCloneError" DOMException.
    3. If transferable has a [[Detached]] internal slot and
+     transferable.[[Detached]] is true, then throw a
+     "DataCloneError" DOMException.
    4. Let placeholder be a user-agent-defined placeholder object.
    5. Set memory[transferable] to
+     placeholder.
    
+   
  3. Let serialized be ? StructuredSerializeInternal(value,
+   false, memory).
  4. Let transferDataHolders be a new empty List.
  5. 
+    
    For each transferable of
+    transferList:
    
+
+    
    1. Let placeholder be memory[transferable].
    2. Let dataHolder be an uninitialized value.
    3. 
+      
      If transferable has an [[ArrayBufferData]] internal slot, then:
      
+
+      
      1. Set dataHolder to { [[TransferConsumed]]: false, [[Type]]: "ArrayBuffer",
+       [[ArrayBufferData]]: transferable.[[ArrayBufferData]], [[ArrayBufferByteLength]]:
+       transferable.[[ArrayBufferByteLength]] }.
      2. Perform ! DetachArrayBuffer(transferable).
      
+     
    4. 
+      
      Otherwise:
      
+
+      
      1. Assert: transferable is a platform object that is a transferable object.
      2. Let interfaceName be the identifier of the primary interface
+       of transferable.
      3. Set dataHolder to { [[TransferConsumed]]: false, [[Type]]:
+       interfaceName }.
      4. Perform the appropriate transfer steps for the interface identified by
+       interfaceName, given transferable and dataHolder.
      5. Set transferable.[[Detached]] to true.
      
+     
    5. Within serialized, replace all instances of placeholder with
+     dataHolder.
    6. Append dataHolder to
+     transferDataHolders.
    
+   
  6. Return { [[Serialized]]: serialized, [[TransferDataHolders]]:
+   transferDataHolders }.

+
+  
2.7.8 StructuredDeserializeWithTransfer (
+  serializeWithTransferResult, targetRealm )

+
+  
  1. 
+    
    Let memory be an empty map.
    
+
+    
    In addition to how it is used normally by StructuredDeserialize, in
+    this algorithm memory is also used to help us determine the list of transferred
+    values.
    
+   
  2. Let deserialized be ?
+   StructuredDeserialize(serializeWithTransferResult.[[Serialized]],
+   targetRealm, memory).
  3. Let transferredValues be a new empty List.
  4. 
+    
    For each transferDataHolder of
+    serializeWithTransferResult.[[TransferDataHolders]]:
    
+
+    
    1. Append
+     memory[transferDataHolder] to transferredValues.
    
+   
  5. Return { [[Deserialized]]: deserialized, [[TransferredValues]]:
+   transferredValues }.

+
+
+  
2.7.9 Performing serialization and
+  transferring from other specifications

+
+  
Other specifications may use the abstract operations defined here. The following provides
+  some guidance on when each abstract operation is typically useful, with examples.

+
+  
StructuredSerializeWithTransfer
StructuredDeserializeWithTransfer

+    
Cloning a value to another JavaScript Realm, with a transfer list, but where the
+    target Realm is not known ahead of time. In this case the serialization step can be performed
+    immediately, with the deserialization step delayed until the target Realm becomes known.

+
+    
messagePort.postMessage()
+    uses this pair of abstract operations, as the destination Realm is not known until the
+    MessagePort has been shipped.

+   
StructuredSerialize
StructuredSerializeForStorage
StructuredDeserialize

+    
Creating a JavaScript Realm-independent snapshot of a given value which can be
+    saved for an indefinite amount of time, and then reified back into a JavaScript value later,
+    possibly multiple times.

+
+    
StructuredSerializeForStorage can be used for situations where the serialization
+    is anticipated to be stored in a persistent manner, instead of passed between Realms. It throws
+    when attempting to serialize SharedArrayBuffer objects, since storing shared memory
+    does not make sense. Similarly, it can throw or possibly have different behavior when given a
+    platform object with custom serialization steps when the
+    forStorage argument is true.

+
+    
history.pushState() and history.replaceState() use
+    StructuredSerializeForStorage on author-supplied state objects, storing them as
+    serialized state in the appropriate session history entry. Then,
+    StructuredDeserialize is used so that the history.state property can return a clone of the
+    originally-supplied state object.

+
+    
broadcastChannel.postMessage() uses
+    StructuredSerialize on its input, then uses StructuredDeserialize
+    multiple times on the result to produce a fresh clone for each destination being broadcast
+    to. Note that transferring does not make sense in multi-destination situations.

+
+    
Any API for persisting JavaScript values to the filesystem would also use
+    StructuredSerializeForStorage on its input and StructuredDeserialize
+    on its output.

+   

+
+  
In general, call sites may pass in Web IDL values instead of JavaScript values; this is to be
+  understood to perform an implicit conversion to the
+  JavaScript value before invoking these algorithms.

+
+  
This specification used
+  to define a "structured clone" algorithm, and more recently a StructuredClone abstract operation.
+  However, in practice all known uses of it were better served by separate serialization and
+  deserialization steps, so it was removed.

+
+  

+
+  
Call sites that are not invoked as a result of author code synchronously calling into a user
+  agent method must take care to properly prepare to run script and prepare to
+  run a callback before invoking StructuredSerialize,
+  StructuredSerializeForStorage, or StructuredSerializeWithTransfer
+  abstract operations, if they are being performed on arbitrary objects. This is necessary because
+  the serialization process can invoke author-defined accessors as part of its final
+  deep-serialization steps, and these accessors could call into operations that rely on the entry and incumbent concepts being properly set up.

+
+  
window.postMessage() performs
+  StructuredSerializeWithTransfer on its arguments, but is careful to do so
+  immediately, inside the synchronous portion of its algorithm. Thus it is able to use the
+  algorithms without needing to prepare to run script and prepare to run a
+  callback.

+
+  
In contrast, a hypothetical API that used StructuredSerialize to
+  serialize some author-supplied object periodically, directly from a task on the event loop, would need to ensure it performs
+  the appropriate preparations beforehand. As of this time, we know of no such APIs on the platform;
+  usually it is simpler to perform the serialization ahead of time, as a synchronous consequence of
+  author code.

+
+  
2.7.10 Monkey patch for Blob and FileList objects

+
+  
This monkey patch will be moved in due course. See w3c/FileAPI issue 32.

+
+  
Blob objects are serializable objects. The Blob
+  interface must be annotated with the [Serializable]
+  extended attribute. Their serialization steps, given value
+  and serialized, are:

+
+  
  1. Set serialized.[[SnapshotState]] to value's snapshot
+   state.
  2. Set serialized.[[ByteSequence]] to value's underlying byte
+   sequence.

+
+  
Their deserialization steps, given serialized and value,
+  are:

+
+  
  1. Set value's snapshot state to
+   serialized.[[SnapshotState]].
  2. Set value's underlying byte sequence to
+   serialized.[[ByteSequence]].

+
+  

+
+  
File objects are serializable objects. The File
+  interface must be annotated with the [Serializable]
+  extended attribute. Their serialization steps, given value
+  and serialized, are:

+
+  
  1. Set serialized.[[SnapshotState]] to value's snapshot
+   state.
  2. Set serialized.[[ByteSequence]] to value's underlying byte
+   sequence.
  3. Set serialized.[[Name]] to the value of value's name attribute.
  4. Set serialized.[[LastModified]] to the value of value's lastModified attribute.

+
+  
Their deserialization steps, given serialized and value,
+  are:

+
+  
  1. Set value's snapshot state to
+   serialized.[[SnapshotState]].
  2. Set value's underlying byte sequence to
+   serialized.[[ByteSequence]].
  3. Initialize the value of value's name
+   attribute to serialized.[[Name]].
  4. Initialize the value of value's lastModified attribute to
+   serialized.[[LastModified]].

+
+  

+
+  
FileList objects are serializable objects. The FileList
+  interface must be annotated with the [Serializable]
+  extended attribute. Their serialization steps, given value
+  and serialized, are:

+
+  
  1. Set serialized.[[Files]] to an empty list.
  2. For each file in value, append
+   the sub-serialization of file to
+   serialized.[[Files]].

+
+  
Their deserialization steps, given serialized and value,
+  are:

+
+  
  1. For each file of
+   serialized.[[Files]], add the sub-deserialization of file to
+   value.

+
+  
+
+
+  
3 Semantics, structure, and APIs of HTML documents

+
+  
3.1 Documents

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

+
+  
The Document object's URL is defined in the WHATWG DOM standard. It is initially set when
+  the Document object is created, but can change during the lifetime of the
+  Document object; for example, it changes when the user navigates to a fragment on the page
+  and when the pushState() method is called with a new
+  URL. [DOM]

+  
+
+  
Interactive user agents typically expose the Document object's
+  URL in their user interface. This is the primary
+  mechanism by which a user can tell if a site is attempting to impersonate another.

+
+  
When a Document is created by a script using
+  the createDocument() or createHTMLDocument() the
+  Document is both ready for post-load tasks and completely
+  loaded immediately.

+
+  
The document's referrer is a string (representing a URL)
+  that can be set when the Document is created. If it is not explicitly set, then its
+  value is the empty string.

+
+  
Each Document object has a reload override flag that is originally
+  unset. The flag is set by the document.open() and document.write() methods in certain situations. When the flag is
+  set, the Document also has a reload override buffer which is a Unicode
+  string that is used as the source of the document when it is reloaded.

+
+  
When the user agent is to perform an overridden reload, given a source
+  browsing context, it must act as follows:

+
+  
  1. Let source be the value of the browsing context's
+   active document's reload override buffer.
  2. Let address be the browsing context's active
+   document's URL.
  3. Let HTTPS state be the HTTPS
+   state of the browsing context's active document.
  4. Let referrer policy be the referrer policy of the browsing
+   context's active document.
  5. Let CSP list be the CSP list
+   of the browsing context's active document.
  6. 
+
+    
    Navigate the browsing context to
+    a new response whose body is source, header list is `Referrer-Policy`/referrer policy, CSP list is CSP list and HTTPS state is HTTPS state, with the
+    exceptions enabled flag set and replacement enabled. The
+    source browsing context is that given to the overridden reload algorithm. When the navigate algorithm creates a
+    Document object for this purpose, set that Document's reload
+    override flag and set its reload override buffer to source.
+    Rethrow any exceptions.
    
+
+    
    When it comes time to set the document's address in the navigation algorithm, use address as the
+    override URL.
    
+
+   

+
+
+
+  
3.1.1 The Document object

+
+  
The WHATWG DOM standard defines a Document interface, which
+  this specification extends significantly:

+
+  
enum DocumentReadyState { "loading", "interactive", "complete" };
+typedef (HTMLScriptElement or SVGScriptElement) HTMLOrSVGScriptElement;
+
+[OverrideBuiltins]
+partial interface Document {
+  // resource metadata management
+  [PutForwards=href, Unforgeable] readonly attribute Location? location;
+  attribute USVString domain;
+  readonly attribute USVString referrer;
+  attribute USVString cookie;
+  readonly attribute DOMString lastModified;
+  readonly attribute DocumentReadyState readyState;
+
+  // DOM tree accessors
+  getter object (DOMString name);
+  [CEReactions] attribute DOMString title;
+  [CEReactions] attribute DOMString dir;
+  [CEReactions] attribute HTMLElement? body;
+  readonly attribute HTMLHeadElement? head;
+  [SameObject] readonly attribute HTMLCollection images;
+  [SameObject] readonly attribute HTMLCollection embeds;
+  [SameObject] readonly attribute HTMLCollection plugins;
+  [SameObject] readonly attribute HTMLCollection links;
+  [SameObject] readonly attribute HTMLCollection forms;
+  [SameObject] readonly attribute HTMLCollection scripts;
+  NodeList getElementsByName(DOMString elementName);
+  readonly attribute HTMLOrSVGScriptElement? currentScript; // classic scripts in a document tree only
+
+  // dynamic markup insertion
+  [CEReactions] Document open(optional DOMString type = "text/html", optional DOMString replace = "");
+  WindowProxy open(USVString url, DOMString name, DOMString features);
+  [CEReactions] void close();
+  [CEReactions] void write(DOMString... text);
+  [CEReactions] void writeln(DOMString... text);
+
+  // user interaction
+  readonly attribute WindowProxy? defaultView;
+  readonly attribute Element? activeElement;
+  boolean hasFocus();
+  [CEReactions] attribute DOMString designMode;
+  [CEReactions] boolean execCommand(DOMString commandId, optional boolean showUI = false, optional DOMString value = "");
+  boolean queryCommandEnabled(DOMString commandId);
+  boolean queryCommandIndeterm(DOMString commandId);
+  boolean queryCommandState(DOMString commandId);
+  boolean queryCommandSupported(DOMString commandId);
+  DOMString queryCommandValue(DOMString commandId);
+
+  // special event handler IDL attributes that only apply to Document objects
+  [LenientThis] attribute EventHandler onreadystatechange;
+};
+Document implements GlobalEventHandlers;
+Document implements DocumentAndElementEventHandlers;

+
+  
The Document has an HTTPS state (an HTTPS state value), initially "none", which represents the security properties of the network channel used to
+  deliver the Document's data.

+
+  
The Document has a referrer policy (a referrer policy), initially the
+  empty string, which represents the default referrer policy used by fetches initiated by the Document.

+
+  
The Document has a CSP list, which is a list of Content Security Policy
+  objects active in this context. The list is empty unless otherwise specified.

+
+  
The Document has a module map, which is a module map,
+  initially empty.

+
+
+  
3.1.2 Resource metadata management

+
+  
document . referrer

+
+    
Returns the URL of the Document
+    from which the user navigated to this one, unless it was blocked or there was no such document,
+    in which case it returns the empty string.

+
+    
The noreferrer link type can be used to block the
+    referrer.

+
+   

+
+  
+
+  
The referrer attribute must return
+  the document's referrer.

+
+  
+
+  

+
+  
document . cookie [ = value ]

+
+    
Returns the HTTP cookies that apply to the Document. If there are no cookies or
+    cookies can't be applied to this resource, the empty string will be returned.

+
+    
Can be set, to add a new cookie to the element's set of HTTP cookies.

+
+    
If the contents are sandboxed into a
+    unique origin (e.g. in an iframe with the sandbox attribute), a
+    "SecurityError" DOMException will be thrown on getting
+    and setting.

+
+   

+
+  
+
+  
The cookie attribute represents the
+  cookies of the resource identified by the document's URL.

+
+  
A Document object that falls into one of the following conditions is a
+  cookie-averse Document object:

+
+  
+
+  
+
+  
On getting, if the document is a cookie-averse Document
+  object, then the user agent must return the empty string. Otherwise, if the
+  Document's origin is an opaque
+  origin, the user agent must throw a "SecurityError"
+  DOMException. Otherwise, the user agent must return the cookie-string
+  for the document's URL for a "non-HTTP" API, decoded
+  using UTF-8 decode without BOM. [COOKIES](This is a fingerprinting vector.)

+
+  
On setting, if the document is a cookie-averse Document object, then
+  the user agent must do nothing. Otherwise, if the Document's origin is
+  an opaque origin, the user agent must throw a
+  "SecurityError" DOMException. Otherwise, the user agent
+  must act as it would when receiving a
+  set-cookie-string for the document's URL via a
+  "non-HTTP" API, consisting of the new value encoded as UTF-8.
+  [COOKIES] [ENCODING]

+
+  
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 cookie attribute's getter and
+  setter synchronously access shared state. Since there is no locking mechanism, other browsing
+  contexts in a multiprocess user agent can modify cookies while scripts are running. A site could,
+  for instance, try to read a cookie, increment its value, then write it back out, using the new
+  value of the cookie as a unique identifier for the session; if the site does this twice in two
+  different browser windows at the same time, it might end up using the same "unique" identifier for
+  both sessions, with potentially disastrous effects.

+
+  

+
+  
+
+  
document . lastModified

+    
Returns the date of the last modification to the document, as reported by the server, in the
+    form "MM/DD/YYYY hh:mm:ss", in the user's local time zone.

+    
If the last modification date is not known, the current time is returned instead.

+   

+
+  
+
+  
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 time zone, in the following format:

+
+  
  1.  The month component of the date. 
  2.  A U+002F SOLIDUS character (/). 
  3.  The day component of the date. 
  4.  A U+002F SOLIDUS character (/). 
  5.  The year component of the date. 
  6.  A U+0020 SPACE character. 
  7.  The hours component of the time. 
  8.  A U+003A COLON character (:). 
  9.  The minutes component of the time. 
  10.  A U+003A COLON character (:). 
  11.  The seconds component of the time. 

+
+  
All the numeric components above, other than the year, must be given as two ASCII
+  digits representing the number in base ten, zero-padded if necessary. The year must be
+  given as the shortest possible string of four or more ASCII digits 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 current date and time in the above format.

+
+  

+
+  
+
+  
document . readyState

+    
Returns "loading" while the Document is loading, "interactive" once it is finished parsing but still loading sub-resources, and
+    "complete" once it has loaded.

+    
The readystatechange event fires on the
+    Document object when this value changes.

+   

+
+  
+
+  
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" if the document is associated with an HTML parser, an
+  XML parser, or an XSLT processor, and to the string "complete"
+  otherwise. Various algorithms during page loading affect this value. When the value is set, the
+  user agent must fire an event named readystatechange at the Document object.

+
+  
A Document is said to have an active parser if it is associated with an
+  HTML parser or an XML parser that has not yet been stopped or aborted.

+
+  
The readyState IDL attribute must, on
+  getting, return the current document readiness.

+
+  
+
+
+
+  
3.1.3 DOM tree accessors

+
+  
The html element of a document is its document element,
+  if it's an html element, and null otherwise.

+
+  

+
+  
document . head

+    
Returns the head element.

+   

+
+  
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 head attribute, on getting, must return
+  the head element of the document (a head element or
+  null).
Support: documentheadChrome for Android 57+Chrome 4+UC Browser for Android 11.4+iOS Safari 4.0+Firefox 4+IE 9+Samsung Internet 4+Opera Mini all+Android Browser 2.3+Edge 12+Safari 5.1+Opera 11+
Source: caniuse.com

+
+  
+
+  

+
+  
document . title [ = value ]

+
+    
Returns the document's title, as given by the title element for
+    HTML and as given by the SVG title element for SVG.

+
+    
Can be set, to update the document's title. If there is no appropriate element to update, the
+    new value is ignored.

+
+   

+
+  
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:

+
+  
  1. If the document element is an SVG svg element, then
+   let value be the child text content of the first SVG
+   title element that is a child of the document element.
  2. Otherwise, let value be the child text content of the
+   title element, or the empty string if the title
+   element is null.
  3. Strip and collapse ASCII whitespace in value.
  4. Return value.

+
+  
On setting, the steps corresponding to the first matching condition in the following list must
+  be run:

+
+  
If the document element is an SVG svg element

+
+    
  1. If there is an SVG title element that is a child of the
+     document element, let element be the first such element.
  2. 
+      
    Otherwise:
    
+
+      
    1. Let element be the result of creating an
+       element given the document element's node document, title, and the SVG namespace.
      
+
+       
    2. Insert element as the first child of the document
+       element.
    
+     
  3. Act as if the textContent IDL attribute of element was
+     set to the new value being assigned.

+
+   
If the document element is in the HTML namespace

+
+    
  1. If the title element is null and the head
+     element is null, then abort these steps.
  2. If the title element is non-null, let element be
+     the title element.
  3. 
+      
    Otherwise:
    
+
+      
    1. Let element be the result of creating an
+       element given the document element's node document,
+       title, and the HTML namespace.
      
+
+       
    2. Append element to the
+       head element.
    
+     
  4. Act as if the textContent IDL attribute of element was
+     set to the new value being assigned.

+
+   
Otherwise

+
+    
Do nothing.

+
+   

+
+  
+
+  

+
+  
document . body [ = value ]

+
+    
Returns the body element.

+
+    
Can be set, to replace the body element.

+
+    
If the new value is not a body or frameset element, this will throw
+    a "HierarchyRequestError" DOMException.

+
+   

+
+  
The body element of a document is the first of the html
+  element's children that is either a body element or a frameset
+  element, or null if there is no such element.

+
+  
+
+  
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:

+
+  
  1. If the new value is not a body or frameset element, then throw a
+   "HierarchyRequestError" DOMException and abort these
+   steps.
  2. Otherwise, if the new value is the same as the body element, do nothing. Abort
+   these steps.
  3. Otherwise, if the body element is not null, then replace the body element with the new value
+   within the body element's parent and abort these steps.
  4. Otherwise, if there is no document element, throw a
+   "HierarchyRequestError" DOMException and abort these
+   steps.
  5. Otherwise, the body element is null, but there's a
+   document element. Append the new value to
+   the document element.

+
+  
+
+  

+
+  
document . images

+    
Returns an HTMLCollection of the img elements in the Document.

+   
document . embeds
document . plugins

+    
Return an HTMLCollection of the embed elements in the Document.

+   
document . links

+    
Returns an HTMLCollection of the a and area elements
+    in the Document that have href
+    attributes.

+   
document . forms

+    
Return an HTMLCollection of the form elements in the Document.

+   
document . scripts

+    
Return an HTMLCollection of the script elements in the Document.

+   

+
+  
+
+  
+
+  
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 scripts attribute must return an
+  HTMLCollection rooted at the Document node, whose filter matches only
+  script elements.

+
+  

+
+  
+
+  
collection = document . getElementsByName(name)

+
+    
Returns a NodeList of elements in the Document that have a name attribute with the value name.

+
+   

+
+  
+
+  
The getElementsByName(name) method takes a string name, and must
+  return a live NodeList containing all the HTML elements in
+  that document that have a name attribute whose value is equal to the name argument (in a case-sensitive manner), in tree
+  order. When the method is invoked on a Document object again with the same
+  argument, the user agent may return the same as the object returned by the earlier call. In other
+  cases, a new NodeList object must be returned.

+
+  
+
+  

+
+  
document . currentScript

+
+    
Returns the script element, or the SVG script element,
+    that is currently executing, as long as the element represents a classic script.
+    In the case of reentrant script execution, returns the one that most recently started executing
+    amongst those that have not yet finished executing.

+
+    
Returns null if the Document is not currently executing a script
+    or SVG script element (e.g., because the running script is an event
+    handler, or a timeout), or if the currently executing script or SVG
+    script element represents a module script.

+
+   

+
+  
+
+  
The currentScript attribute, on
+  getting, must return the value to which it was most recently set. When the Document
+  is created, the currentScript must be
+  initialized to null.
Support: document-currentscriptChrome for Android 57+Chrome 29+UC Browser for Android 11.4+iOS Safari 8+Firefox 4+IE NoneSamsung Internet 4+Opera Mini NoneAndroid Browser 4.4+Edge 12+Safari 8+Opera 16+
Source: caniuse.com

+
+  
+
+  
This API has fallen out of favor in the implementor and standards community, as
+  it globally exposes script or SVG script elements. As such,
+  it is not available in newer contexts, such as when running module
+  scripts or when running scripts in a shadow tree. We are looking into creating
+  a new solution for identifying the running script in such contexts, which does not make it
+  globally available: see issue #1013.

+
+  
+
+  

+
+  
The Document interface supports named properties. The supported property names of a
+  Document object document at any moment consist of the following, in
+  tree order according to the element that contributed them, ignoring later duplicates,
+  and with values from id attributes coming before values from name attributes when the same element contributes both:

+
+  
+
+  
To determine the value of a named property
+  name for a Document, the user agent must return the value obtained using
+  the following steps:

+
+  
  1. 
+
+    
    Let elements be the list of named
+    elements with the name name that are in a document tree with the
+    Document as their root.
    
+
+    
    There will be at least one such element, by definition.
    
+
+   
  2. 
+
+    
    If elements has only one element, and that element is an iframe
+    element, and that iframe element's nested browsing context is not
+    null, then return the WindowProxy object of the element's nested browsing
+    context.
    
+
+   
  3. 
+
+    
    Otherwise, if elements has only one element, return that element.
    
+
+   
  4. 
+
+    
    Otherwise return an HTMLCollection rooted at the Document node,
+    whose filter matches only named elements with
+    the name name.
     
+
+   

+
+  
Named elements with the name name, for the purposes of the above algorithm, are those that are either:

+
+  
  • applet, exposed embed, form,
+   iframe, img, or exposed object elements that
+   have a name content attribute whose value is name, or
  • applet or exposed object elements that have an id content attribute whose value is name, or
  • img elements that have an id content attribute
+   whose value is name, and that have a non-empty name
+   content attribute present also.

+
+  
An embed or object element is said to be exposed if it has
+  no exposed object ancestor, and, for object elements, is
+  additionally either not showing its fallback content or has no object or
+  embed descendants.

+
+  
+
+  

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

+
+
+
+  
3.2 Elements

+
+  
3.2.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.

+
+  
These definitions allow HTML processors, such as Web browsers or search engines, to present and
+  use documents and applications in a wide variety of contexts that the author might not have
+  considered.

+
+  

+
+   
As a simple example, consider a Web page written by an author who only considered desktop
+   computer Web browsers:

+
+   
<!DOCTYPE HTML>
+<html lang="en">
+ <head>
+  <title>My Page</title>
+ </head>
+ <body>
+  <h1>Welcome to my page</h1>
+  <p>I like cars and lorries and have a big Jeep!</p>
+  <h2>Where I live</h2>
+  <p>I live in a small hut on a mountain!</p>
+ </body>
+</html>

+
+   
Because HTML conveys meaning, rather than presentation, the same
+   page can also be used by a small browser on a mobile phone, without any change to the page.
+   Instead of headings being in large letters as on the desktop, for example, the browser on the
+   mobile phone might use the same size text for the whole the page, but with the headings in
+   bold.

+
+   
But it goes further than just differences in screen size: the same page could equally be used
+   by a blind user using a browser based around speech synthesis, which instead of displaying the
+   page on a screen, reads the page to the user, e.g. using headphones. Instead of large text for
+   the headings, the speech browser might use a different volume or a slower voice.

+
+   
That's not all, either. Since the browsers know which parts of the page are the headings, they
+   can create a document outline that the user can use to quickly navigate around the document,
+   using keys for "jump to next heading" or "jump to previous heading". Such features are especially
+   common with speech browsers, where users would otherwise find quickly navigating a page quite
+   difficult.

+
+   
Even beyond browsers, software can make use of this information. Search engines can use the
+   headings to more effectively index a page, or to provide quick links to subsections of the page
+   from their results. Tools can use the headings to create a table of contents (that is in fact how
+   this very specification's table of contents is generated).

+
+   
This example has focused on headings, but the same principle applies to all of the semantics
+   in HTML.

+
+  

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

+
+  

+
+   
For example, the following snippet, intended to represent the heading of a
+   corporate site, is 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>ACME Corporation</h1>
+ <h2>The leaders in arbitrary fast delivery since 1920</h2>
+ ...

+
+   
The hgroup element is intended for these kinds of situations:

+
+   
<body>
+ <hgroup>
+  <h1>ACME Corporation</h1>
+  <h2>The leaders in arbitrary fast delivery since 1920</h2>
+ </hgroup>
+ ...

+
+  

+
+  

+
+   
The document in this next example is similarly non-conforming, despite
+   being syntactically correct, because the data placed in the cells is clearly
+   not tabular data, and the cite element mis-used:

+
+   
<!DOCTYPE HTML>
+<html lang="en-GB">
+ <head> <title> Demonstration </title> </head>
+ <body>
+  <table>
+   <tr> <td> My favourite animal is the cat. </td> </tr>
+   <tr>
+    <td>
+     —<a href="https://example.org/~ernest/"><cite>Ernest</cite></a>,
+     in an essay from 1992
+    </td>
+   </tr>
+  </table>
+ </body>
+</html>

+
+   
This would make software that relies on these semantics fail: for example,
+   a speech browser that allowed a blind user to navigate tables in the document
+   would report the quote above as a table, confusing the user; similarly, a
+   tool that extracted titles of works from pages would extract "Ernest" as the
+   title of a work, even though it's actually a person's name, not a title.

+
+   
A corrected version of this document might be:

+
+   
<!DOCTYPE HTML>
+<html lang="en-GB">
+ <head> <title> Demonstration </title> </head>
+ <body>
+  <blockquote>
+   <p> My favourite animal is the cat. </p>
+  </blockquote>
+  <p>
+   —<a href="https://example.org/~ernest/">Ernest</a>,
+   in an essay from 1992
+  </p>
+ </body>
+</html>

+
+  

+
+  
Authors must not use elements, attributes, or attribute values that are not permitted by this
+  specification or other applicable specifications, as doing so makes it significantly
+  harder for the language to be extended in the future.

+
+  

+
+   
In the next example, there is a non-conforming attribute value ("carpet") and a non-conforming
+   attribute ("texture"), which is not permitted by this specification:

+
+   
<label>Carpet: <input type="carpet" name="c" texture="deep pile"></label>

+
+   
Here would be an alternative and correct way to mark this up:

+
+   
<label>Carpet: <input type="text" class="carpet" name="c" data-texture="deep pile"></label>

+
+  

+
+  
DOM nodes whose node document does not have a
+  browsing context are exempt from all document conformance requirements other than the
+  HTML syntax requirements and XML
+  syntax requirements.

+
+  

+
+   
In particular, the template element's template contents's node
+   document does not have a browsing context. For example, the content model requirements and attribute value
+   microsyntax requirements do not apply to a template element's template
+   contents. In this example an img element has attribute values that are
+   placeholders that would be invalid outside a template element.

+
+   
<template>
+ <article>
+  <img src="{{src}}" alt="{{alt}}">
+  <h1></h1>
+ </article>
+</template>

+
+   
However, if the above markup were to omit the </h1> end tag, that
+   would be a violation of the HTML syntax, and would thus be flagged as an
+   error by conformance checkers.

+
+  

+
+  
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.2.2 Elements in the DOM

+
+  
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 HTML elements in XML documents, even when
+  those documents are in another context (e.g. inside an XSLT transform).

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

+
+  
For example, an ol element represents an ordered list.

+
+  
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.

+
+  
[HTMLConstructor]
+interface HTMLElement : Element {
+  // metadata attributes
+  [CEReactions] attribute DOMString title;
+  [CEReactions] attribute DOMString lang;
+  [CEReactions] attribute boolean translate;
+  [CEReactions] attribute DOMString dir;
+  [SameObject] readonly attribute DOMStringMap dataset;
+
+  // user interaction
+  [CEReactions] attribute boolean hidden;
+  void click();
+  [CEReactions] attribute long tabIndex;
+  void focus();
+  void blur();
+  [CEReactions] attribute DOMString accessKey;
+  readonly attribute DOMString accessKeyLabel;
+  [CEReactions] attribute boolean draggable;
+  [CEReactions] attribute HTMLMenuElement? contextMenu;
+  [CEReactions] attribute boolean spellcheck;
+  void forceSpellCheck();
+
+  [CEReactions] attribute [TreatNullAs=EmptyString] DOMString innerText;
+};
+HTMLElement implements GlobalEventHandlers;
+HTMLElement implements DocumentAndElementEventHandlers;
+HTMLElement implements ElementContentEditable;
+
+// Note: intentionally not [HTMLConstructor]
+interface HTMLUnknownElement : HTMLElement { };

+
+  
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.

+
+  
+
+  

+
+  
The element interface for an element with name name in the
+  HTML namespace is determined as follows:

+
+  
  1. If name is bgsound, blink, isindex,
+   keygen, multicol, nextid, or spacer, then
+   return HTMLUnknownElement.
  2. If name is acronym, basefont, big,
+   center, nobr, noembed, noframes,
+   plaintext, rb, rtc, strike, or
+   tt, then return HTMLElement.
  3. If name is listing or xmp, then return
+   HTMLPreElement.
  4. Otherwise, if this specification defines an interface appropriate for the element
+   type corresponding to the local name name, then return that interface.
  5. If other applicable specifications define an appropriate interface for
+   name, then return the interface they define.
  6. If name is a valid custom element name, then return
+   HTMLElement.
    
+
+   
  7. Return HTMLUnknownElement.

+
+  
The use of HTMLElement instead of HTMLUnknownElement in
+  the case of valid custom element names is done to
+  ensure that any potential future upgrades only cause
+  a linear transition of the element's prototype chain, from HTMLElement to a subclass,
+  instead of a lateral one, from HTMLUnknownElement to an unrelated subclass.

+
+  
+
+  
+
+  
3.2.3 HTML element constructors

+
+  
To support the custom elements feature, all HTML elements have
+  special constructor behavior. This is indicated via the [HTMLConstructor] IDL extended attribute.
+  It indicates that the interface object for the given interface will have a specific behavior when
+  called, as defined in detail below.

+
+  
The [HTMLConstructor] extended attribute must take no
+  arguments, and must not appear on anything other than an interface. It must appear only once on an
+  interface, and the interface must not be annotated with the [Constructor]
+  or [NoInterfaceObject] extended attributes. (However, the interface may be
+  annotated with [NamedConstructor]; there is no conflict there.) It must not
+  be used on a callback interface.

+
+  
Interface objects for interfaces annotated with the
+  [HTMLConstructor] extended attribute must run the following
+  steps as the function body behavior for both [[Call]] and [[Construct]] invocations of the
+  corresponding JavaScript function object. When invoked with [[Call]], the NewTarget value is
+  undefined, and so the algorithm below will immediately throw. When invoked with [[Construct]], the
+  [[Construct]] newTarget parameter provides the NewTarget value.

+
+  
  1. Let registry be the current global object's
+   CustomElementRegistry object.
  2. 
+    
    If NewTarget is equal to the active function object, then throw a
+    TypeError and abort these steps.
    
+
+    
    
+     
    This can occur when a custom element is defined using an element interface as
+     its constructor:
    
+
+     
    customElements.define("bad-1", HTMLButtonElement);
+new HTMLButtonElement();          // (1)
+document.createElement("bad-1");  // (2)
    
+
+     
    In this case, during the execution of HTMLButtonElement (either explicitly, as
+     in (1), or implicitly, as in (2)), both the active function object and NewTarget
+     are HTMLButtonElement. If this check was not present, it would be possible to
+     create an instance of HTMLButtonElement whose local name was bad-1.
    
+    
    
+   
  3. 
+    
    Let definition be the entry in registry with constructor equal to NewTarget. If
+    there is no such definition, then throw a TypeError and abort these steps.
    
+
+    
    Since there can be no entry in registry with a constructor of undefined, this
+    step also prevents HTML element constructors from being called as functions (since in that case
+    NewTarget will be undefined).
    
+   
  4. 
+    
    If definition's local
+    name is equal to definition's name (i.e., definition is for
+    an autonomous custom element), then:
    
+
+    
    1. 
+      
      If the active function object is not HTMLElement, then throw a
+      TypeError and abort these steps.
      
+
+      
      
+       
      This can occur when a custom element is defined to not extend any local names, but
+       inherits from a non-HTMLElement class:
      
+
+       
      customElements.define("bad-2", class Bad2 extends HTMLParagraphElement {});
      
+
+       
      In this case, during the (implicit) super() call that occurs when
+       constructing an instance of Bad2, the active function
+       object is HTMLParagraphElement, not HTMLElement.
      
+      
      
+     
    
+   
  5. 
+    
    Otherwise (i.e., if definition is for a customized built-in
+    element):
    
+
+    
    1. Let valid local names be the list of local names for elements defined in this
+     specification or in other applicable specifications that use the active
+     function object as their element interface.
    2. 
+      
      If valid local names does not contain definition's local name, then throw a
+      TypeError and abort these steps.
      
+
+      
      
+       
      This can occur when a custom element is defined to extend a given local name but inherits
+       from the wrong class:
      
+
+       
      customElements.define("bad-3", class Bad3 extends HTMLQuoteElement {}, { extends: "p" });
      
+
+       
      In this case, during the (implicit) super() call that occurs when
+       constructing an instance of Bad3, valid local names is the
+       list containing q and blockquote, but definition's local name is p,
+       which is not in that list.
      
+      
      
+     
    
+   
  6. Let prototype be Get(NewTarget, "prototype").
+   Rethrow any exceptions.
  7. 
+    
    If Type(prototype) is not Object, then:
    
+
+    
    1. Let realm be GetFunctionRealm(NewTarget).
    2. Set prototype to the interface prototype object of
+     realm whose interface is the same as the interface of the active function
+     object.
    
+
+    
    The realm of the active function object might not be
+    realm, so we are using the more general concept of "the same interface" across
+    realms; we are not looking for equality of interface
+    objects. This fallback behavior, including using the realm of NewTarget and looking up
+    the appropriate prototype there, is designed to match analogous behavior for the JavaScript
+    built-ins.
    
+   
  8. 
+    
    If definition's construction stack is
+    empty, then:
    
+
+    
    1. Let element be a new element that implements the interface to which the
+     active function object corresponds, with no attributes, namespace set to the
+     HTML namespace, local name set to definition's local name, and node
+     document set to the current global object's associated Document.
    2. Perform element.[[SetPrototypeOf]](prototype). Rethrow any
+     exceptions.
    3. Set element's custom element state to "custom".
    4. Set element's custom
+     element definition to definition.
    5. Return element.
    
+
+    
    This occurs when author script constructs a new custom element directly, e.g.
+    via new MyCustomElement().
    
+   
  9. Let element be the last entry in definition's construction stack.
  10. 
+    
    If element is an already
+    constructed marker, then throw an "InvalidStateError"
+    DOMException and abort these steps.
    
+
+    
    
+     
    This can occur when the author code inside the custom element
+     constructor non-conformantly creates another
+     instance of the class being constructed, before calling super():
    
+
+     
    let doSillyThing = false;
+
+class DontDoThis extends HTMLElement {
+  constructor() {
+    if (doSillyThing) {
+      doSillyThing = false;
+      new DontDoThis();
+      // Now the construction stack will contain an already constructed marker.
+    }
+
+    // This will then fail with an "InvalidStateError" DOMException:
+    super();
+  }
+}
    
+    
    
+
+    
    
+     
    This can also occur when author code inside the custom element constructor non-conformantly calls super()
+     twice, since per the JavaScript specification, this actually executes the superclass
+     constructor (i.e. this algorithm) twice, before throwing an error:
+
+     
    class DontDoThisEither extends HTMLElement {
+  constructor() {
+    super();
+
+    // This will throw, but not until it has already called into the HTMLElement constructor
+    super();
+  }
+}
    
+    
    
+   
  11. Perform element.[[SetPrototypeOf]](prototype). Rethrow any
+   exceptions.
  12. Replace the last entry in definition's construction stack with an
+   already constructed
+   marker.
  13. 
+    
    Return element.
    
+
+    
    This step is normally reached when upgrading a custom element; the existing element is
+    returned, so that the super() call inside the custom element
+    constructor assigns that existing element to this.
    
+   

+
+  

+
+  
In addition to the constructor behavior implied by [HTMLConstructor], some elements also have named constructors (which are really factory functions with a modified prototype property).
+
+  

+   
Named constructors for HTML elements can also be used in an extends
+   clause when defining a custom element constructor:

+
+   
class AutoEmbiggenedImage extends Image {
+  constructor(width, height) {
+    super(width * 10, height * 10);
+  }
+}
+
+customElements.define("auto-embiggened", AutoEmbiggenedImage, { extends: "img" });
+
+const image = new AutoEmbiggenedImage(15, 20);
+console.assert(image.width === 150);
+console.assert(image.height === 200);

+  

+
+  
+
+
+
+  
3.2.4 Element definitions

+
+  
Each element in this specification has a definition that includes the following
+  information:

+
+  
Categories
A list of categories to which the element belongs.
+   These are used when defining the content models for each element.
Contexts in which this element can be used

+
+    
A non-normative description of where the element can be used. This information is
+    redundant with the content models of elements that allow this one as a child, and is provided
+    only as a convenience.

+
+    
For simplicity, only the most specific expectations are listed. For example, an
+    element that is both flow content and phrasing content can be used
+    anywhere that either flow content or phrasing content is expected, but
+    since anywhere that flow content is expected, phrasing content is also
+    expected (since all phrasing content is flow content), only "where
+    phrasing content is expected" will be listed.

+
+   
Content model
A normative description of what content must be included as children and descendants of
+   the element.
Tag omission in text/html
A non-normative description of whether, in the text/html syntax, the
+   start and end tags can
+   be omitted. This information is redundant with the normative requirements given in the optional tags section, and is provided in the element
+   definitions only as a convenience.
Content attributes
A normative list of attributes that may be specified on the element (except where
+   otherwise disallowed), along with non-normative descriptions of those attributes. (The content to
+   the left of the dash is normative, the content to the right of the dash is not.)
DOM interface
A normative definition of a DOM interface that such elements must implement.

+
+  
This is then followed by a description of what the element represents, along with
+  any additional normative conformance criteria that may apply to authors and implementations. Examples are sometimes also included.

+
+
+  
3.2.4.1 Attributes

+
+  
An attribute value is a string. Except where otherwise specified,
+  attribute values on HTML elements may be any string value, including the empty
+  string, and there is no restriction on what text can be specified in such attribute values.

+
+
+
+  
3.2.5 Content models

+
+  
Each element defined in this specification has a content model: a description of the element's
+  expected contents. An HTML
+  element must have contents that match the requirements described in the element's content
+  model. The contents of an element are its children in the
+  DOM.

+
+  
ASCII whitespace is 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's contents match the element's content model or not,
+  and must be ignored when following algorithms that define document and element semantics.

+
+  
Thus, 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. Similarly, a node is the only child of
+  an element if that element contains no other nodes other than inter-element
+  whitespace, comment nodes, and processing instruction nodes.

+
+  
Authors must not use HTML elements 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.

+
+  

+   
For example, the Atom specification defines a content element. When its
+   type attribute has the value xhtml, the Atom
+   specification requires that it contain 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]

+  

+
+  
In addition, HTML elements may be orphan nodes (i.e. without a parent node).

+
+  

+
+   
For example, creating a td element and storing it in a global variable in a
+   script is conforming, even though td elements are otherwise only supposed to be used
+   inside tr elements.

+
+   
var data = {
+  name: "Banana",
+  cell: document.createElement('td'),
+};

+
+  

+
+
+  
3.2.5.1 The "nothing" content model

+
+  
When an element's content model is nothing, the
+  element must contain no Text nodes (other than inter-element whitespace)
+  and no element nodes.

+
+  
Most HTML elements whose content model is "nothing" are also, for convenience,
+  void elements (elements that have no end tag in
+  the HTML syntax). However, these are entirely separate concepts.

+
+
+  
3.2.5.2 Kinds of content

+
+  
Each element in HTML falls into zero or more categories
+  that group elements with similar characteristics together. The following broad categories are used
+  in this specification:

+
+  
+
+  
Some elements also fall into other categories, which are defined in other parts of
+  this specification.

+
+  
These categories are related as follows:

+
+  

+
+  
Sectioning content, heading content, phrasing content, embedded content, and interactive
+  content are all types of flow content. Metadata is sometimes flow content. Metadata and
+  interactive content are sometimes phrasing content. Embedded content is also a type of phrasing
+  content, and sometimes is interactive content.

+
+  
Other categories are also used for specific purposes, e.g. form controls are specified using a
+  number of categories to define common requirements. Some elements have unique requirements and do
+  not fit into any particular category.

+
+
+  
3.2.5.2.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.

+
+  

+
+   
Thus, in the XML serialization, one can use RDF, like this:

+
+   
<html xmlns="http://www.w3.org/1999/xhtml"
+      xmlns:r="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xml:lang="en">
+ <head>
+  <title>Hedral's Home Page</title>
+  <r:RDF>
+   <Person xmlns="http://www.w3.org/2000/10/swap/pim/contact#"
+           r:about="https://hedral.example.com/#">
+    <fullName>Cat Hedral</fullName>
+    <mailbox r:resource="mailto:hedral@damowmow.com"/>
+    <personalTitle>Sir</personalTitle>
+   </Person>
+  </r:RDF>
+ </head>
+ <body>
+  <h1>My home page</h1>
+  <p>I like playing with string, I guess. Sister says squirrels are fun
+  too so sometimes I follow her to play with them.</p>
+ </body>
+</html>

+
+   
This isn't possible in the HTML serialization, however.

+
+  

+
+
+  
3.2.5.2.2 Flow content

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

+
+  
+  
+
+
+  
3.2.5.2.3 Sectioning content

+
+  
Sectioning content is content that defines the scope of headings and footers.

+
+  
+  
+
+  
Each sectioning content element potentially has a heading and an
+  outline. See the section on headings and sections for further
+  details.

+
+  
There are also certain elements that are sectioning
+  roots. These are distinct from sectioning content, but they can also have an
+  outline.

+
+
+  
3.2.5.2.4 Heading content

+
+  
Heading content defines the header of a section (whether explicitly marked up using
+  sectioning content elements, or implied by the heading content itself).

+
+  
+  
+
+
+  
3.2.5.2.5 Phrasing content
Spec bugs: 25493

+
+  
Phrasing content is the text of the document, as well as elements that mark up that
+  text at the intra-paragraph level. Runs of phrasing content form paragraphs.

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

+
+  
Text, in the context of content models, means either nothing,
+  or Text nodes. Text is sometimes used as a content
+  model on its own, but is also phrasing content, and can be inter-element
+  whitespace (if the Text nodes are empty or contain just ASCII
+  whitespace).

+
+  
Text nodes and attribute values must consist of scalar
+  values, excluding noncharacters, and controls other than ASCII whitespace.
+
+   
+  
+
+  This specification includes extra constraints on the exact value of Text nodes and
+  attribute values depending on their precise context.
+
+  
+
+  

+
+
+
+  
3.2.5.2.6 Embedded content

+
+  
Embedded content is content that imports another
+  resource into the document, or content from another vocabulary that
+  is inserted into the document.

+
+  
+  
+
+  
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.2.5.2.7 Interactive content

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

+
+  
+  
+
+  
The tabindex attribute can also make any element into
+  interactive content.

+
+
+
+  
3.2.5.2.8 Palpable content

+
+  
As a general rule, elements whose content model allows any flow content or
+  phrasing content should have at least one node in its contents that is palpable content and that does
+  not have the hidden attribute specified.

+
+  
Palpable content makes an element non-empty by providing either
+  some descendant non-empty text, or else something users can
+  hear (audio elements) or view (video or img or
+  canvas elements) or otherwise interact with (for example, interactive form
+  controls).

+
+  
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.

+
+  
Conformance checkers are encouraged to provide a mechanism for authors to find elements that
+  fail to fulfill this requirement, as an authoring aid.

+
+  
The following elements are palpable content:

+
+  
+  
+
+
+  
3.2.5.2.9 Script-supporting elements

+
+  
Script-supporting elements are those that do not represent anything themselves (i.e. they are not rendered), but are
+  used to support scripts, e.g. to provide functionality for the user.

+
+  
The following elements are script-supporting elements:

+
+  
+  
+
+
+
+  
3.2.5.3 Transparent content models

+
+  
Some elements are described as transparent; they have "transparent" in the
+  description of their content model. The content model of a transparent element is
+  derived from the content model of its parent element: the elements required in the part of the
+  content model that is "transparent" are the same elements as required in the part of the content
+  model of the parent of the transparent element in which the transparent element finds itself.

+
+  

+
+   
For instance, an ins element inside a ruby element cannot contain an
+   rt element, because the part of the ruby element's content model that
+   allows ins elements is the part that allows phrasing content, and the
+   rt element is not phrasing content.

+
+  

+
+
+
+  
In some cases, where transparent elements are nested in each other, the process
+  has to be applied iteratively.

+
+  

+
+   
Consider the following markup fragment:

+
+   
<p><object><param><ins><map><a href="/">Apples</a></map></ins></object></p>

+
+   
To check whether "Apples" is allowed inside the a element, the content models are
+   examined. The a element's content model is transparent, as is the map
+   element's, as is the ins element's, as is the part of the object
+   element's in which the ins element is found. The object element is
+   found in the p element, whose content model is phrasing content. Thus,
+   "Apples" is allowed, as text is phrasing content.

+
+  

+
+  
When a 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.2.5.4 Paragraphs

+
+  
The term paragraph as defined in this section is used for more than
+  just the definition of the p element. The paragraph concept defined here
+  is used to describe how to interpret documents. The p element is merely one of
+  several ways of marking up a paragraph.

+
+  
+  
A paragraph is typically a run of phrasing content that forms 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.

+
+  

+
+   
In the following example, there are two paragraphs in a section. There is also a heading,
+   which contains phrasing content that is not a paragraph. Note how the comments and
+   inter-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>

+
+  

+
+  
Paragraphs in flow content are defined relative to what the document looks like
+  without the a, ins, del, and map elements
+  complicating matters, since those elements, with their hybrid content models, can straddle
+  paragraph boundaries, as shown in the first two examples below.

+
+  
Generally, having elements straddle paragraph boundaries is best avoided.
+  Maintaining such markup can be difficult.

+
+  

+
+   
The following example takes the markup from the earlier example and puts ins and
+   del elements around some of the markup to show that the text was changed (though in
+   this case, the changes admittedly don't make much sense). Notice how this example has exactly the
+   same paragraphs as the previous one, despite the ins and del elements
+   — the ins element straddles the heading and the first paragraph, and the
+   del element straddles the boundary between the two paragraphs.

+
+   
<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>

+
+  

+
+  
+
+  
Let view be a view of the DOM that replaces all a,
+  ins, del, and map elements in the document with their contents. Then, in view, for each run
+  of sibling phrasing content nodes uninterrupted by other types of content, in an
+  element that accepts content other than phrasing content as well as phrasing
+  content, let first be the first node of the run, and let last be the last node of the run. For each such run that consists of at least one
+  node that is neither embedded content nor inter-element whitespace, a
+  paragraph exists in the original DOM from immediately before first to
+  immediately after last. (Paragraphs can thus span across a,
+  ins, del, and map elements.)

+
+  
Conformance checkers may warn authors of cases where they have paragraphs that overlap each
+  other (this can happen with object, video, audio, and
+  canvas elements, and indirectly through elements in other namespaces that allow HTML
+  to be further embedded therein, like SVG svg or MathML
+  math).

+  
+
+  
+
+  
A paragraph is also formed explicitly by p 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, the link spans half of the first paragraph, all of the heading
+   separating the two paragraphs, and half of the second paragraph. It straddles the paragraphs and
+   the heading.

+
+   
<header>
+ Welcome!
+ <a href="about.html">
+  This is home of...
+  <h1>The Falcons!</h1>
+  The Lockheed Martin multirole jet fighter aircraft!
+ </a>
+ This page discusses the F-16 Fighting Falcon's innermost secrets.
+</header>

+
+   
Here is another way of marking this up, this time showing the paragraphs explicitly, and
+   splitting the one link element into three:

+
+   
<header>
+ <p>Welcome! <a href="about.html">This is home of...</a></p>
+ <h1><a href="about.html">The Falcons!</a></h1>
+ <p><a href="about.html">The Lockheed Martin multirole jet
+ fighter aircraft!</a> This page discusses the F-16 Fighting
+ Falcon's innermost secrets.</p>
+</header>

+
+  

+
+  

+
+   
+
+   
It is possible for paragraphs to overlap when using certain elements that define fallback
+   content. For example, in the following section:

+
+   
<section>
+ <h1>My Cats</h1>
+ You can play with my cat simulator.
+ <object data="cats.sim">
+  To see the cat simulator, use one of the following links:
+  <ul>
+   <li><a href="cats.sim">Download simulator file</a>
+   <li><a href="https://sims.example.com/watch?v=LYds5xY4INU">Use online simulator</a>
+  </ul>
+  Alternatively, upgrade to the Mellblom Browser.
+ </object>
+ I'm quite proud of it.
+</section>

+
+   
There are five paragraphs:

+
+   
  1. The paragraph that says "You can play with my cat simulator. object I'm
+    quite proud of it.", where object is the object element.
  2. The paragraph that says "To see the cat simulator, use one of the following links:".
  3. The paragraph that says "Download simulator file".
  4. The paragraph that says "Use online simulator".
  5. The paragraph that says "Alternatively, upgrade to the Mellblom Browser.".

+
+   
The first paragraph is overlapped by the other four. A user agent that supports the "cats.sim"
+   resource will only show the first one, but a user agent that shows the fallback will confusingly
+   show the first sentence of the first paragraph as if it was in the same paragraph as the second
+   one, and will show the last paragraph as if it was at the start of the second sentence of the
+   first paragraph.

+
+   
To avoid this confusion, explicit p elements can be used. For example:

+
+   
+   
<section>
+ <h1>My Cats</h1>
+ <p>You can play with my cat simulator.</p>
+ <object data="cats.sim">
+  <p>To see the cat simulator, use one of the following links:</p>
+  <ul>
+   <li><a href="cats.sim">Download simulator file</a>
+   <li><a href="https://sims.example.com/watch?v=LYds5xY4INU">Use online simulator</a>
+  </ul>
+  <p>Alternatively, upgrade to the Mellblom Browser.</p>
+ </object>
+ <p>I'm quite proud of it.</p>
+</section>

+
+  

+
+
+  
3.2.6 Global attributes

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

+
+  
+
+  
+
+  
These attributes are only defined by this specification as attributes for HTML
+  elements. When this specification refers to elements having these attributes, elements from
+  namespaces that are not defined as having these attributes must not be considered as being
+  elements with these attributes.

+
+  

+
+   
For example, in the following XML fragment, the "bogus" element does not
+   have a dir attribute as defined in this specification, despite
+   having an attribute with the literal name "dir". Thus, the
+   directionality of the inner-most span element is 'rtl', inherited from the div element indirectly through
+   the "bogus" element.

+
+   
<div xmlns="http://www.w3.org/1999/xhtml" dir="rtl">
+ <bogus xmlns="https://example.net/ns" dir="ltr">
+  <span xmlns="http://www.w3.org/1999/xhtml">
+  </span>
+ </bogus>
+</div>

+
+  

+
+  
+
+  

+
+  
The WHATWG DOM standard defines the user agent requirements for the class, id, and slot
+  attributes for any element in any namespace. [DOM]

+
+  
The class, id, and slot attributes may be specified on all HTML elements.

+
+  
When specified on HTML elements, the class
+  attribute must have a value that is a set of space-separated tokens representing the
+  various classes that the element belongs to.

+
+  

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

+
+  
There are no additional restrictions on the tokens authors can use in the class attribute, but authors are encouraged to use values that describe
+  the nature of the content, rather than values that describe the desired presentation of the
+  content.

+
+  

+
+  
When specified on HTML elements, the id attribute
+  value must be unique amongst all the IDs in the element's
+  tree and must contain at least one character. The value must not contain any
+  ASCII whitespace.

+
+  
+
+  

+
+  
The id attribute specifies its element's unique identifier (ID).

+
+  
There are no other restrictions on what form an ID can take; in particular, IDs can consist of
+  just digits, start with a digit, start with an underscore, consist of just punctuation, etc.

+
+  
An element's unique identifier can be used for a variety of
+  purposes, most notably as a way to link to specific parts of a document using fragments, as a way to target an element when scripting, and
+  as a way to style a specific element from CSS.

+
+  

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

+
+  
+
+  
There are no conformance requirements for the slot attribute
+  specific to HTML elements.

+
+  
The slot attribute is used to assign a
+  slot to an element: an element with a slot attribute is
+  assigned to the slot
+  created by the slot element whose name
+  attribute's value matches that slot attribute's value — but only
+  if that slot element finds itself in the shadow tree whose
+  root's host has the corresponding
+  slot attribute value.

+
+  

+
+  
To enable assistive technology products to expose a more fine-grained interface than is
+  otherwise possible with HTML elements and attributes, a set of annotations
+  for assistive technology products can be specified (the ARIA role and aria-* attributes). [ARIA]

+
+  

+
+  
The following event handler content attributes may be specified on any HTML element:

+
+  
+
+  
The attributes marked with an asterisk have a different meaning when specified on
+  body elements as those elements expose event handlers of the
+  Window object with the same names.

+
+  
While these attributes apply to all elements, they are not useful on all elements.
+  For example, only media elements will ever receive a volumechange event fired by the user agent.

+
+  

+
+  
Custom data attributes (e.g. data-foldername or data-msgid) can be specified on any
+  HTML element, to store custom data, state, annotations, and
+  similar, specific to the page.

+
+  

+
+  
In HTML documents, elements in the HTML namespace may have an xmlns attribute specified, if, and only if, it has the exact value "http://www.w3.org/1999/xhtml". This does not apply to XML
+  documents.

+
+  
In HTML, the xmlns attribute has absolutely no effect. It
+  is basically a talisman. It is allowed merely to make migration to and from XML 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.

+
+  

+
+  
The XML specification also allows the use of the xml:space
+  attribute in the XML namespace on any element in an XML
+  document. This attribute has no effect on HTML elements, as the default
+  behavior in HTML is to preserve whitespace. [XML]

+
+  
There is no way to serialize the xml:space
+  attribute on HTML elements in the text/html syntax.

+
+
+
+  
3.2.6.1 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; on interactive content,
+  it could be a label for, or instructions for, use of the element; and so forth. The value is
+  text.

+
+  
+  
Relying on the title attribute is currently
+  discouraged as many user agents do not expose the attribute in an accessible manner as required by
+  this specification (e.g. requiring a pointing device such as a mouse to cause a tooltip to appear,
+  which excludes keyboard-only users and touch-only users, such as anyone with a modern phone or
+  tablet).

+
+  
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.

+
+  

+
+   
Caution is advised with respect to the use of newlines in title attributes.

+
+   
For instance, the following snippet actually defines an abbreviation's expansion with a
+   line break in it:

+
+   
<p>My logs show that there was some interest in <abbr title="Hypertext
+Transport Protocol">HTTP</abbr> today.</p>
 
+
+  

+
+  
Some elements, such as link, abbr, and input, define
+  additional semantics for the title attribute beyond the semantics
+  described above.
 
+
+  
+
+  
The advisory information of an element is the value that the following algorithm
+  returns, with the algorithm being aborted once a value is returned. When the algorithm returns the
+  empty string, then there is no advisory information.

+
+  
  1. If the element is a link, style, dfn,
+   abbr, or menuitem element, then: if the element has a title attribute,  return the value of that attribute,
+   otherwise, return the empty string.
  2. Otherwise, if the element has a title attribute, then
+   return its value.
  3. Otherwise, if the element has a parent element, then return the parent element's
+   advisory information.
  4. Otherwise, return the empty string.

+
+  
User agents should inform the user when elements have advisory information,
+  otherwise the information would not be discoverable.

+
+  

+
+  
The title IDL attribute must reflect the
+  title content attribute.

+
+  
+
+
+
+  
3.2.6.2 The lang and xml:lang attributes

+
+  
The lang attribute (in no namespace) 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 BCP 47 language tag, or the empty string. Setting the attribute to
+  the empty string indicates that the primary language is unknown. [BCP47]

+
+  
The lang attribute in the XML
+  namespace is defined in XML. [XML]

+
+  
If these attributes are omitted from an element, then the language of this element is the same
+  as the language of its parent element, if any.

+
+  
The lang attribute in no namespace may be used on any HTML element.

+
+  
The lang attribute in the XML
+  namespace may be used on HTML elements in XML documents,
+  as well as elements in other namespaces if the relevant specifications allow it (in particular,
+  MathML and SVG allow lang attributes in the
+  XML namespace to be specified on their elements). If both the lang attribute in no namespace and the lang attribute in the XML namespace are specified on the same
+  element, they must have exactly the same value when compared in an ASCII
+  case-insensitive manner.

+
+  
Authors must not use the lang attribute in
+  the XML namespace on HTML elements in HTML
+  documents. To ease migration to and from XML, authors may specify an attribute in no
+  namespace with no prefix and with the literal localname "xml:lang" on
+  HTML elements in HTML documents, but such attributes must only be
+  specified if a lang attribute in no namespace is also specified,
+  and both attributes must have the same value when compared in an ASCII
+  case-insensitive manner.

+
+  
The attribute in no namespace with no prefix and with the literal localname "xml:lang" has no effect on language processing.

+
+  
+
+  

+
+  
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 a lang attribute in the XML
+  namespace set or is an HTML element and has a
+  lang in no namespace attribute set. That attribute specifies the
+  language of the node (regardless of its value).

+
+  
If both the lang attribute in no namespace and the lang attribute in the XML
+  namespace are set on an element, user agents must use the lang attribute in the XML
+  namespace, and the lang attribute in no namespace
+  must be ignored for the purposes of determining the element's
+  language.

+
+  
If node's inclusive ancestors do not have either
+  attribute set, but there is a pragma-set default language set, then that is the
+  language of the node. If there is no pragma-set default language set, then language
+  information from a higher-level protocol (such as HTTP), if any, must be used as the final
+  fallback language instead. In the absence of any such language information, and in cases where the
+  higher-level protocol reports multiple languages, the language of the node is unknown, and the
+  corresponding language tag is the empty string.

+
+  
If the resulting value is not a recognized language tag, then it must be treated as an unknown
+  language having the given language tag, distinct from all other languages. For the purposes of
+  round-tripping or communicating with other services that expect language tags, user agents should
+  pass unknown language tags through unmodified, and tagged as being BCP 47 language tags, so that
+  subsequent services do not interpret the data as another type of language description. [BCP47]

+
+  
Thus, for instance, an element with lang="xyzzy" would be
+  matched by the selector :lang(xyzzy) (e.g. in CSS), but it would not be
+  matched by :lang(abcde), even though both are equally invalid. Similarly, if
+  a Web browser and screen reader working in unison communicated about the language of the element,
+  the browser would tell the screen reader that the language was "xyzzy", even if it knew it was
+  invalid, just in case the screen reader actually supported a language with that tag after all.
+  Even if the screen reader supported both BCP 47 and another syntax for encoding language names,
+  and in that other syntax the string "xyzzy" was a way to denote the Belarusian language, it would
+  be incorrect for the screen reader to then start treating text as Belarusian, because
+  "xyzzy" is not how Belarusian is described in BCP 47 codes (BCP 47 uses the code "be" for
+  Belarusian).

+
+  
If the resulting value is the empty string, then it must be interpreted as meaning that the
+  language of the node is explicitly unknown.

+
+  

+
+  
User agents may use the element's language to determine proper processing or rendering (e.g. in
+  the selection of appropriate fonts or pronunciations, for dictionary selection, or for the user
+  interfaces of form controls such as date pickers). 

+
+  
+
+  

+
+  
The lang IDL attribute must reflect the
+  lang content attribute in no namespace.

+
+  
+
+
+
+  
3.2.6.3 The translate attribute

+
+  
+
+  
The translate attribute is an enumerated
+  attribute that is used to specify whether an element's attribute values and the values of
+  its Text node children are to be translated when the page is localized, or whether to
+  leave them unchanged.

+
+  
The attribute's keywords are the empty string, yes, and no. The empty string and the yes keyword map to the
+  yes state. The no keyword maps to the no state. In addition,
+  there is a third state, the inherit state, which is the missing value default (and
+  the invalid value default).

+
+  
Each element (even non-HTML elements) has a translation mode, which is in either the
+  translate-enabled state or the no-translate state. If an HTML element's translate
+  attribute is in the yes state, then the element's translation mode is in the
+  translate-enabled state; otherwise, if the element's translate attribute is in the no state, then the element's
+  translation mode is in the no-translate state. Otherwise, either the
+  element's translate attribute is in the inherit state,
+  or the element is not an HTML element and thus does not have a
+  translate attribute; in either case, the element's
+  translation mode is in the same state as its parent element's, if any, or in the
+  translate-enabled state, if the element is a document element.

+
+  
When an element is in the translate-enabled state, the element's translatable
+  attributes and the values of its Text node children are to be translated when
+  the page is localized.

+
+  
When an element is in the no-translate state, the element's attribute values and the
+  values of its Text node children are to be left as-is when the page is localized,
+  e.g. because the element contains a person's name or a name of a computer program.

+
+  
The following attributes are translatable attributes:

+
+  
+
+  
Other specifications may define other attributes that are also translatable
+  attributes. For example, ARIA would define the aria-label attribute as translatable.

+
+  
+
+  

+
+  
The translate IDL attribute must, on getting,
+  return true if the element's translation mode is translate-enabled, and
+  false otherwise. On setting, it must set the content attribute's value to "yes" if the new value is true, and set the content attribute's value to "no" otherwise.

+
+  
+
+  

+
+   
In this example, everything in the document is to be translated when the page is localized,
+   except the sample keyboard input and sample program output:

+
+   
<!DOCTYPE HTML>
+<html lang=en> <!-- default on the document element is translate=yes -->
+ <head>
+  <title>The Bee Game</title> <!-- implied translate=yes inherited from ancestors -->
+ </head>
+ <body>
+  <p>The Bee Game is a text adventure game in English.</p>
+  <p>When the game launches, the first thing you should do is type
+  <kbd translate=no>eat honey</kbd>. The game will respond with:</p>
+  <pre><samp translate=no>Yum yum! That was some good honey!</samp></pre>
+ </body>
+</html>

+
+  

+
+
+
+  
3.2.6.4 The dir attribute

+
+  
The dir attribute specifies the element's text directionality.
+  The attribute is an enumerated attribute with the following keywords and states:

+
+  
The ltr keyword, which maps to the ltr state

+
+    
Indicates that the contents of the element are explicitly directionally isolated
+    left-to-right text.

+
+   
The rtl keyword, which maps to the rtl state

+
+    
Indicates that the contents of the element are explicitly directionally isolated
+    right-to-left text.

+
+   
The auto keyword, which maps to the auto state

+
+    
Indicates that the contents of the element are explicitly directionally isolated text, but
+    that the direction is to be determined programmatically using the contents of the element (as
+    described below).

+
+    
The heuristic used by this state is very crude (it just looks at the first
+    character with a strong directionality, in a manner analogous to the Paragraph Level
+    determination in the bidirectional algorithm). Authors are urged to only use this value as a
+    last resort when the direction of the text is truly unknown and no better server-side heuristic
+    can be applied. [BIDI]

+
+    
For textarea and pre elements, the heuristic is
+    applied on a per-paragraph level.

+
+   

+
+  
The attribute has no invalid value default and no missing value default.

+
+  

+
+  
The directionality of an element (any element, not just an HTML element) is either 'ltr' or 'rtl', and is determined as per the first appropriate set of steps from
+  the following list:

+
+  
If the element's dir attribute is in the ltr state
If the element is a document element and the dir
+   attribute is not in a defined state (i.e. it is not present or has an invalid value)
If the element is an input element whose type attribute is in the Telephone state, and the dir
+   attribute is not in a defined state (i.e. it is not present or has an invalid value)
The directionality of the element is 'ltr'.
If the element's dir attribute is in the rtl state
The directionality of the element is 'rtl'.
If the element is an input element whose type attribute is in the Text, Search,
+   Telephone, URL, or E-mail
+   state, and the dir attribute is in the auto state
If the element is a textarea element and the dir
+   attribute is in the auto state

+
+    
If the element's value contains a character of
+    bidirectional character type AL or R, and there is no character of bidirectional character type
+    L anywhere before it in the element's value, then
+    the directionality of the element is 'rtl'. [BIDI]

+
+    
Otherwise, if the element's value is not the empty
+    string, or if the element is a document element, the directionality of
+    the element is 'ltr'.

+
+    
Otherwise, the directionality of the element is the same as the element's parent
+    element's directionality.

+
+   
If the element's dir attribute is in the auto state
If the element is a bdi element and the dir
+   attribute is not in a defined state (i.e. it is not present or has an invalid value)

+
+    
Find the first character in tree order that matches the following criteria:

+
+    
  • The character is from a Text node that is a descendant of the element whose
+     directionality is being determined.
  • The character is of bidirectional character type L, AL, or R. [BIDI]
  • 
+
+      
    The character is not in a Text node that has an ancestor element that is a
+      descendant of the element whose directionality is
+      being determined and that is either:
    
+
+      
    • A bdi element.
+       
    • A script element.
+       
    • A style element.
+       
    • A textarea element.
+       
    • An element with a dir attribute in a defined state.
+      
    
+
+     

+
+    
If such a character is found and it is of bidirectional character type AL or R, the
+    directionality of the element is 'rtl'.

+
+    
If such a character is found and it is of bidirectional character type L, the
+    directionality of the element is 'ltr'.

+
+    
Otherwise, if the element is a document element, the directionality
+    of the element is 'ltr'.

+
+    
Otherwise, the directionality of the element is the same as the element's parent
+    element's directionality.

+
+   
If the element has a parent element and the dir attribute is
+   not in a defined state (i.e. it is not present or has an invalid value)
The directionality of the element is the same as the element's parent
+   element's directionality.

+
+  
Since the dir attribute is only defined for
+  HTML elements, it cannot be present on elements from other namespaces. Thus, elements
+  from other namespaces always just inherit their directionality from their parent element, or, if they don't have one,
+  default to 'ltr'.

+
+  
+
+  
This attribute has rendering requirements involving the
+  bidirectional algorithm.

+
+  
+
+  

+
+  
The directionality of an attribute of an
+  HTML element, which is used when the text of that attribute is
+  to be included in the rendering in some manner, is determined as per the first appropriate set of
+  steps from the following list:

+
+  
If the attribute is a directionality-capable attribute and the element's dir attribute is in the auto
+   state

+
+    
Find the first character (in logical order) of the attribute's value that is of bidirectional
+    character type L, AL, or R. [BIDI]

+
+    
If such a character is found and it is of bidirectional character type AL or R, the
+    directionality of the attribute is 'rtl'.

+
+    
Otherwise, the directionality of the attribute is 'ltr'.

+
+   
Otherwise
The directionality of the attribute is the same as the element's directionality.

+
+  
The following attributes are directionality-capable attributes:

+
+  
+
+  

+
+  
document . dir [ = value ]

+    
Returns the html element's dir attribute's value, if any.

+    
Can be set, to either "ltr", "rtl", or "auto" to replace the html element's dir attribute's value.

+    
If there is no html element, returns the empty string and ignores new values.

+   

+
+  
+
+  
The dir IDL attribute on an element must
+  reflect the dir content attribute of that element,
+  limited to only known values.

+
+  
The dir IDL attribute on Document
+  objects must reflect the dir content attribute of
+  the html element, if any, limited to only known values. If
+  there is no such element, then the attribute must return the empty string and do nothing on
+  setting.

+
+  
+
+  
Authors are strongly encouraged to use the dir
+  attribute to indicate text direction rather than using CSS, since that way their documents will
+  continue to render correctly even in the absence of CSS (e.g. as interpreted by search
+  engines).

+
+  

+
+   
This markup fragment is of an IM conversation.

+
+   
<p dir=auto class="u1"><b><bdi>Student</bdi>:</b> How do you write "What's your name?" in Arabic?</p>
+<p dir=auto class="u2"><b><bdi>Teacher</bdi>:</b> ما اسمك؟</p>
+<p dir=auto class="u1"><b><bdi>Student</bdi>:</b> Thanks.</p>
+<p dir=auto class="u2"><b><bdi>Teacher</bdi>:</b> That's written "شكرًا".</p>
+<p dir=auto class="u2"><b><bdi>Teacher</bdi>:</b> Do you know how to write "Please"?</p>
+<p dir=auto class="u1"><b><bdi>Student</bdi>:</b> "من فضلك", right?</p>

+
+
+
+   
Given a suitable style sheet and the default alignment styles for the p element,
+   namely to align the text to the start edge of the paragraph, the resulting rendering could
+   be as follows:

+
+   
Each paragraph rendered as a separate block, with the paragraphs left-aligned except the second paragraph and the last one, which would  be right aligned, with the usernames ('Student' and 'Teacher' in this example) flush right, with a colon to their left, and the text first to the left of that.

+
+   
As noted earlier, the auto value is not a panacea. The
+   final paragraph in this example is misinterpreted as being right-to-left text, since it begins
+   with an Arabic character, which causes the "right?" to be to the left of the Arabic text.

+
+  

+
+
+
+  
3.2.6.5 The style attribute

+
+  
All HTML elements may have the style content
+  attribute set. This is a style attribute as defined by
+  the CSS Style Attributes specification. [CSSATTR]

+
+  
+
+  
In user agents that support CSS, the attribute's value must be parsed when the attribute is
+  added or has its value changed,
+  according to the rules given for style attributes.
+  [CSSATTR]

+
+  
However, if the Should element's inline behavior be blocked by Content Security
+  Policy? algorithm returns "Blocked" when executed upon the
+  attribute's element, "style attribute", and the attribute's
+  value, then the style rules defined in the attribute's value must not be applied to the
+  element. [CSP]

+
+  
+
+  
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. (To hide and show content, use the hidden
+  attribute.)

+
+  

+
+  
element . style

+    
Returns a CSSStyleDeclaration object for the element's style attribute.

+   

+
+  
+
+  
The style IDL attribute is defined in the CSS Object
+  Model (CSSOM) specification. [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.

+
+   
<p>My sweat suit is <span style="color: green; background:
+transparent">green</span> and my eyes are <span style="color: blue;
+background: transparent">blue</span>.</p>

+
+  

+
+
+
+  
3.2.6.6 Embedding custom non-visible data with the data-* attributes
Support: datasetChrome for Android 57+Chrome 7+UC Browser for Android 11.4+iOS Safari 5.0+Firefox 6+IE 11+Samsung Internet 4+Opera Mini (limited) all+Android Browser 3+Edge 12+Safari 5.1+Opera 11.1+
Source: caniuse.com

+
+  
A custom data attribute is an attribute in no namespace whose name starts with the
+  string "data-", has at least one character after the
+  hyphen, is XML-compatible, and contains no ASCII
+  upper alphas.

+
+  
All attribute names on HTML elements in HTML documents
+  get ASCII-lowercased automatically, so the restriction on ASCII uppercase letters doesn't affect
+  such documents.

+
+  
Custom data attributes are intended to store custom
+  data, state, annotations, and similar, private to the page or application, for which there are no
+  more appropriate attributes or elements.

+
+  
These attributes are not intended for use by software that is not known to the administrators
+  of the site that uses the attributes. For generic extensions that are to be used by multiple
+  independent tools, either this specification should be extended to provide the feature explicitly,
+  or a technology like microdata should be used (with a standardized vocabulary).

+
+  

+
+   
For instance, a site about music could annotate list items representing tracks in an album
+   with custom data attributes containing the length of each track. This information could then be
+   used by the site itself to allow the user to sort the list by track length, or to filter the list
+   for tracks of certain lengths.

+
+   
<ol>
+ <li data-length="2m11s">Beyond The Sea</li>
+ ...
+</ol>

+
+   
It would be inappropriate, however, for the user to use generic software not associated with
+   that music site to search for tracks of a certain length by looking at this data.

+
+   
This is because these attributes are intended for use by the site's own scripts, and are not a
+   generic extension mechanism for publicly-usable metadata.

+
+  

+
+  

+
+   
Similarly, a page author could write markup that provides information for a translation tool
+   that they are intending to use:

+
+   
<p>The third <span data-mytrans-de="Anspruch">claim</span> covers the case of <span
+translate="no">HTML</span> markup.</p>

+
+   
In this example, the "data-mytrans-de" attribute gives specific text
+   for the MyTrans product to use when translating the phrase "claim" to German. However, the
+   standard translate attribute is used to tell it that in all
+   languages, "HTML" is to remain unchanged. When a standard attribute is available, there is no
+   need for a custom data attribute to be used.

+
+  

+
+  

+
+   
In this example, custom data attributes are used to store the result of a feature detection
+   for PaymentRequest, which could be used in CSS to style a checkout page
+   differently.

+
+   
<script>
+ if ('PaymentRequest' in window) {
+   document.documentElement.dataset.hasPaymentRequest = '';
+ }
+</script>

+
+   
Here, the data-has-payment-request attribute is effectively being used
+   as a boolean attribute; it is enough to check the presence of the attribute.
+   However, if the author so wishes, it could later be populated with some value, maybe to indicate
+   limited functionality of the feature.

+
+  

+
+  
Every HTML element may have any number of custom data attributes specified, with any value.

+
+  
Authors should carefully design such extensions so that when the attributes are ignored and any
+  associated CSS dropped, the page is still usable.

+
+  
+
+  
User agents must not derive any implementation behavior from these attributes or values.
+  Specifications intended for user agents must not define these attributes to have any meaningful
+  values.

+
+  
+
+  
JavaScript libraries may use the custom data
+  attributes, as they are considered to be part of the page on which they are used. Authors
+  of libraries that are reused by many authors are encouraged to include their name in the attribute
+  names, to reduce the risk of clashes. Where it makes sense, library authors are also encouraged to
+  make the exact name used in the attribute names customizable, so that libraries whose authors
+  unknowingly picked the same name can be used on the same page, and so that multiple versions of a
+  particular library can be used on the same page even when those versions are not mutually
+  compatible.

+
+  

+
+   
For example, a library called "DoQuery" could use attribute names like data-doquery-range, and a library called "jJo" could use attributes names like
+   data-jjo-range. The jJo library could also provide an API to set which
+   prefix to use (e.g. J.setDataPrefix('j2'), making the attributes have names
+   like data-j2-range).

+
+  

+
+  

+
+  
element . dataset

+
+    
Returns a DOMStringMap object for the element's data-* attributes.

+
+    
Hyphenated names become camel-cased. For example, data-foo-bar=""
+    becomes element.dataset.fooBar.

+
+   

+
+  
+
+  
The dataset IDL attribute provides convenient
+  accessors for all the data-* attributes on an element. On
+  getting, the dataset IDL attribute must return a
+  DOMStringMap whose associated element is this element.

+
+  
+
+  
The DOMStringMap interface is used for the dataset attribute. Each DOMStringMap has an associated element.

+
+  
[OverrideBuiltins]
+interface DOMStringMap {
+  getter DOMString (DOMString name);
+  [CEReactions] setter void (DOMString name, DOMString value);
+  [CEReactions] deleter void (DOMString name);
+};

+
+  
+
+  
To get a DOMStringMap's name-value
+  pairs, run the following algorithm:

+
+  
  1. Let list be an empty list of name-value pairs.
  2. For each content attribute on the DOMStringMap's associated element whose first five characters are
+   the string "data-" and whose remaining characters (if any) do not include
+   any ASCII upper alphas, in the order that those
+   attributes are listed in the element's attribute list, add a name-value pair to
+   list whose name is the attribute's name with the first five characters removed and
+   whose value is the attribute's value.
  3. For each name in list, for each U+002D HYPHEN-MINUS character (-) in the name
+   that is followed by an ASCII lower alpha, remove the U+002D HYPHEN-MINUS character
+   (-) and replace the character that followed it by the same character converted to ASCII
+   uppercase.
  4. Return list.

+
+  
The supported property names on a DOMStringMap object at any instant
+  are the names of each pair returned from getting the
+  DOMStringMap's name-value pairs at that instant, in the order returned.

+
+  
To determine the value of a named property
+  name for a DOMStringMap, return the value component of the name-value pair
+  whose name component is name in the list returned from getting the DOMStringMap's name-value
+  pairs.

+
+  
To set the value of a new named property or
+  set the value of an existing named property for a DOMStringMap, given a
+  property name name and a new value value, run the following steps:

+
+  
  1. If name contains a U+002D HYPHEN-MINUS character (-) followed by an ASCII
+   lower alpha, then throw a "SyntaxError"
+   DOMException and abort these steps.
  2. For each ASCII upper alpha in name, insert a U+002D HYPHEN-MINUS
+   character (-) before the character and replace the character with the same character
+   converted to ASCII lowercase.
  3. Insert the string data- at the front of name.
  4. If name does not match the XML Name production,
+   throw an "InvalidCharacterError" DOMException and abort
+   these steps.
  5. Set an attribute value for the
+   DOMStringMap's associated element
+   using name and value.

+
+  
To delete an existing named property
+  name for a DOMStringMap, run the following steps:

+
+  
  1. For each ASCII upper alpha in name, insert a U+002D HYPHEN-MINUS
+   character (-) before the character and replace the character with the same character
+   converted to ASCII lowercase.
  2. Insert the string data- at the front of name.
  3. Remove an attribute by name given
+   name and the DOMStringMap's associated element.

+
+  
This algorithm will only get invoked by the Web IDL specification for names that
+  are given by the earlier algorithm for getting the
+  DOMStringMap's name-value pairs. [WEBIDL]

+
+  
+
+  

+
+   
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:

+
+   
<div class="spaceship" data-ship-id="92432"
+     data-weapons="laser 2" data-shields="50%"
+     data-x="30" data-y="10" data-z="90">
+ <button class="fire"
+         onclick="spaceships[this.parentNode.dataset.shipId].fire()">
+  Fire
+ </button>
+</div>

+
+   
Notice how the hyphenated attribute name becomes camel-cased in the API.

+
+  

+
+  

+
+   
Given the following fragment and elements with similar constructions:

+
+   
<img class="tower" id="tower5" data-x="12" data-y="5"
+     data-ai="robotarget" data-hp="46" data-ability="flames"
+     src="towers/rocket.png" alt="Rocket Tower">

+
+   
...one could imagine a function splashDamage() that takes some arguments, the first
+   of which is the element to process:

+
+   
function splashDamage(node, x, y, damage) {
+  if (node.classList.contains('tower') && // checking the 'class' attribute
+      node.dataset.x == x && // reading the 'data-x' attribute
+      node.dataset.y == y) { // reading the 'data-y' attribute
+    var hp = parseInt(node.dataset.hp); // reading the 'data-hp' attribute
+    hp = hp - damage;
+    if (hp < 0) {
+      hp = 0;
+      node.dataset.ai = 'dead'; // setting the 'data-ai' attribute
+      delete node.dataset.ability; // removing the 'data-ability' attribute
+    }
+    node.dataset.hp = hp; // setting the 'data-hp' attribute
+  }
+}

+
+  

+
+
+  
3.2.7 The innerText IDL attribute
Support: innertextChrome for Android 57+Chrome 4+UC Browser for Android 11.4+iOS Safari 4.0+Firefox 45+IE 6+Samsung Internet 4+Opera Mini all+Android Browser 2.3+Edge 12+Safari 3.2+Opera 9.5+
Source: caniuse.com

+
+  
element . innerText [ = value ]

+
+    
Returns the element's text content "as rendered".

+
+    
Can be set, to replace the element's children with the given value, but with line breaks
+    converted to br elements.

+
+  

+
+  
+
+  
On getting, the innerText attribute must follow
+  these steps:

+
+  
  1. If this element is not being rendered, or if the user agent is a non-CSS user
+   agent, then return the same value as the textContent IDL attribute on this
+   element.
  2. 
+    
    Compute a list of items each of which is a string or a positive integer (a required line
+    break count), by applying the following recursive procedure to each child node
+    node of this element in tree order, and then concatenating the results
+    to a single list of items.
    
+
+    
    Intuitively, a required line break count item means that a certain number
+    of line breaks appear at that point, but they can be collapsed with the line breaks induced by
+    adjacent required line break count items, reminiscent to CSS margin-collapsing.
    
+
+    
    1. Let items be the result of recursively applying this procedure to each child
+     of node in tree order, and then concatenating the results to a single
+     list of items.
    2. If node's computed value of 'visibility' is not
+     'visible', then let the result of these substeps be items and abort these
+     substeps.
    3. 
+      
      If node has no associated CSS box, then let the result of these substeps be
+      items and abort these substeps. For the purpose of this step, the following
+      elements must act as described if the computed value of the
+      'display' property is not 'none':
      
+
+      
      • select elements have an associated non-replaced inline CSS box whose child
+       boxes include only those of optgroup and option element child
+       nodes;
      • optgroup elements have an associated non-replaced block-level CSS box whose
+       child boxes include only those of option element child nodes; and
      • option element have an associated non-replaced block-level CSS box whose
+       child boxes are as normal for non-replaced block-level CSS boxes.
      
+
+      
      items can be non-empty due to 'display:contents'.
      
+     
    4. If node is a Text node, then for each CSS text box produced by
+     node, in content order, compute the text of the box after application of the CSS
+     'white-space' processing rules and 'text-transform' rules, let the
+     result of these substeps be a list of the resulting strings, and abort these substeps. The CSS
+     'white-space' processing rules are slightly modified: collapsible spaces at the
+     end of lines are always collapsed, but they are only removed if the line is the last line of
+     the block, or it ends with a br element. Soft hyphens should be preserved. [CSSTEXT]
    5. If node is a br element, then append a string containing a
+     single U+000A LINE FEED (LF) character to items.
    6. If node's computed value of 'display' is
+     'table-cell', and node's CSS box is not the last
+     'table-cell' box of its enclosing 'table-row' box, then append a
+     string containing a single U+0009 CHARACTER TABULATION (tab) character to
+     items.
    7. If node's computed value of 'display' is
+     'table-row', and node's CSS box is not the last
+     'table-row' box of the nearest ancestor 'table' box, then append a
+     string containing a single U+000A LINE FEED (LF) character to items.
    8. If node is a p element, then add 2 (a required line break
+     count) at the beginning and end of items.
    9. 
+      
      If node's used value of 'display' is
+      block-level or 'table-caption', then add 1 (a required line break
+      count) at the beginning and end of items. [CSSDISPLAY]
      
+
+      
      Floats and absolutely-positioned elements fall into this category.
      
+     
    10. Let the result of these substeps be items.
    
+   
  3. Delete any string items whose strings are empty.
  4. Delete any runs of consecutive required line break count items at the start or end
+   of the list.
  5. Replace each remaining run of consecutive required line break count items with a
+   string consisting of as many U+000A LINE FEED (LF) characters as the maximum of the values in the
+   required line break count items.
  6. Return the concatenation of the string items.

+
+  
Note that descendant nodes of most replaced elements (e.g., textarea,
+  input, and video — but not button) are not rendered
+  by CSS, strictly speaking, and therefore have no CSS boxes for the purposes of this algorithm.

+
+  
This algorithm is amenable to being generalized to work on ranges. Then we can use it as the basis for Selection's
+  stringifier and maybe expose it directly on ranges. See Bugzilla bug 10583.

+
+  
On setting, the innerText attribute must follow these
+  steps:

+
+  
  1. Let document be this element's node document.
  2. Let fragment be a new DocumentFragment object whose node
+   document is document.
  3. Let input be the given value.
  4. Let position be a pointer into input, initially pointing at the start
+   of the string.
  5. Let text be the empty string.
  6. 
+    
    While position is not past the end of input:
    
+
+    
    1. Collect a sequence of code points that are not U+000A LINE FEED (LF) or
+     U+000D CARRIAGE RETURN (CR) characters from input given position. Set
+     text to the collected characters.
    2. If text is not the empty string, then append a new Text node whose data is text and node document is
+     document to fragment.
    3. 
+      
      While position is not past the end of input, and the character at
+      position is either a U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR)
+      character:
      
+
+      
      1. If the character at position is a U+000D CARRIAGE RETURN (CR) character and
+       the next character is a U+000A LINE FEED (LF) character, then advance position to
+       the next character in input.
      2. Advance position to the next character in input.
      3. Append the result of creating an element given document,
+       br, and the HTML namespace to fragment.
      
+     
    
+   
  7. Replace all with fragment within
+   this element.

+
+  
+
+  
3.2.8 Requirements relating to the bidirectional algorithm

+
+  
+  
3.2.8.1 Authoring conformance criteria for bidirectional-algorithm formatting characters

+  
+
+  
Text content in HTML elements with Text nodes in their
+  contents, and text in attributes of HTML
+  elements that allow free-form text, may contain characters in the ranges U+202A to U+202E
+  and U+2066 to U+2069 (the bidirectional-algorithm formatting characters). [BIDI]

+
+  
Authors are encouraged to use the dir attribute, the
+  bdo element, and the bdi element, rather than maintaining the
+  bidirectional-algorithm formatting characters manually. The bidirectional-algorithm formatting
+  characters interact poorly with CSS.

+
+
+  
+
+  
3.2.8.2 User agent conformance criteria

+
+  
User agents must implement the Unicode bidirectional algorithm to determine the proper ordering
+  of characters when rendering documents and parts of documents. [BIDI]

+
+  
The mapping of HTML to the Unicode bidirectional algorithm must be done in one of three ways.
+  Either the user agent must implement CSS, including in particular the CSS
+  'unicode-bidi', 'direction', and 'content' properties, and
+  must have, in its user agent style sheet, the rules using those properties given in this
+  specification's rendering section, or, alternatively, the user agent must
+  act as if it implemented just the aforementioned properties and had a user agent style sheet that
+  included all the aforementioned rules, but without letting style sheets specified in documents
+  override them, or, alternatively, the user agent must implement another styling language with
+  equivalent semantics. [CSSGC]

+
+  
The following elements and attributes have requirements defined by the rendering section that, due to the requirements in this section, are
+  requirements on all user agents (not just those that support the suggested
+  default rendering):

+
+  
+
+  
+
+  
+
+  
3.2.9 Requirements related to ARIA and to platform accessibility APIs

+
+  
User agent requirements for implementing Accessibility API semantics on HTML
+  elements are defined in HTML Accessibility API Mappings. [HTMLAAM]

+
+  
Conformance checker requirements for checking use of ARIA role and aria-* attributes on
+  HTML elements are defined in ARIA in HTML. [ARIAHTML]

+
+  
+
+
+
+  
4 The elements of HTML

+
+  
4.1 The document element

+
+  
4.1.1 The html element

+
+  
Categories:
None.
Contexts in which this element can be used:
As document's document element.
Wherever a subdocument fragment is allowed in a compound document.
Content model:
A head element followed by a body element.
Tag omission in text/html:
An html element's start tag can be omitted
+   if the first thing inside the html element is not a comment.
An html element's end tag can be omitted if
+   the html element is not immediately followed by a comment.
Content attributes:
Global attributes
manifest — Application cache manifest
DOM interface:

+    
[HTMLConstructor]
+interface HTMLHtmlElement : HTMLElement {
+  // also has obsolete members
+};

+   

+
+  
The html element represents the root of an HTML document.

+
+  
Authors are encouraged to specify a lang attribute on the root
+  html element, giving the document's language. This aids speech synthesis tools to
+  determine what pronunciations to use, translation tools to determine what rules to use, and so
+  forth.

+
+  
The manifest attribute gives the address of
+  the document's application cache manifest, if there is one. If the attribute is present,
+  the attribute's value must be a valid non-empty URL potentially surrounded by
+  spaces.

+
+  
The manifest attribute is part of the
+  legacy "offline Web applications" feature, which is in the process of being
+  removed from the Web platform. (This is a long process that takes many years.) Using the manifest attribute at this time is highly discouraged. Use
+  service workers instead. [SW]

+
+  
The manifest attribute only has an effect during the early stages of document load.
+  Changing the attribute dynamically thus has no effect (and thus, no DOM API is provided for this
+  attribute).

+
+  
For the purposes of application cache
+  selection, later base elements cannot affect the parsing of URLs in manifest attributes, as
+  the attributes are processed before those elements are seen.

+
+  
The window.applicationCache IDL
+  attribute provides scripted access to the offline application cache mechanism.

+
+
+  

+
+   
The html element in the following example declares that the document's language
+   is English.

+
+   
<!DOCTYPE html>
+<html lang="en">
+<head>
+<title>Swapping Songs</title>
+</head>
+<body>
+<h1>Swapping Songs</h1>
+<p>Tonight I swapped some of the songs I wrote with some friends, who
+gave me some of the songs they wrote. I love sharing my music.</p>
+</body>
+</html>

+
+  

+
+
+
+
+  
4.2 Document metadata

+
+  
4.2.1 The head element

+
+  
Categories:
None.
Contexts in which this element can be used:
As the first element in an html element.
Content model:
If the document is an iframe srcdoc document or if title information is available from a higher-level protocol: Zero or more elements of metadata content, of which no more than one is a title element and no more than one is a base element.
Otherwise: One or more elements of metadata content, of which exactly one is a title element and no more than one is a base element.
Tag omission in text/html:
A head element's start tag can be omitted if
+   the element is empty, or if the first thing inside the head element is an
+   element.
A head element's end tag can be omitted if
+   the head element is not immediately followed by ASCII whitespace or a
+   comment.
Content attributes:
Global attributes
DOM interface:

+    
[HTMLConstructor]
+interface HTMLHeadElement : HTMLElement {};

+   

+
+  
The head element represents a collection of metadata for the
+  Document.

+
+  

+
+   
The collection of metadata in a head element can be large or small. Here is an
+   example of a very short one:

+
+   
<!doctype html>
+<html lang=en>
+ <head>
+  <title>A document with a short head</title>
+ </head>
+ <body>
+ ...

+
+   
Here is an example of a longer one:

+
+   
<!DOCTYPE HTML>
+<HTML LANG="EN">
+ <HEAD>
+  <META CHARSET="UTF-8">
+  <BASE HREF="https://www.example.com/">
+  <TITLE>An application with a long head</TITLE>
+  <LINK REL="STYLESHEET" HREF="default.css">
+  <LINK REL="STYLESHEET ALTERNATE" HREF="big.css" TITLE="Big Text">
+  <SCRIPT SRC="support.js"></SCRIPT>
+  <META NAME="APPLICATION-NAME" CONTENT="Long headed application">
+ </HEAD>
+ <BODY>
+ ...

+
+  

+
+  
The title element is a required child in most situations, but when a
+  higher-level protocol provides title information, e.g. in the Subject line of an e-mail when HTML
+  is used as an e-mail authoring format, the title element can be omitted.

+
+
+
+  
4.2.2 The title element

+
+  
Categories:
Metadata content.
Contexts in which this element can be used:
In a head element containing no other title elements.
Content model:
Text that is not inter-element whitespace.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:

+    
[HTMLConstructor]
+interface HTMLTitleElement : HTMLElement {
+  [CEReactions] attribute DOMString text;
+};

+   

+
+  
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 heading, since the first heading does not have to stand alone when taken
+  out of context.

+
+  
There must be no more than one title element per document.

+
+  
If it's reasonable for the Document to have no title, then the
+  title element is probably not required. See the head element's content
+  model for a description of when the element is required.

+
+  
title . text [ = value ]

+
+    
Returns the child text content of the element.

+
+    
Can be set, to replace the element's children with the given value.

+
+   

+
+  
+
+  
The IDL attribute text must return the
+  child text content of the title element. On setting, it must act the
+  same way as the textContent IDL attribute.

+
+  
+
+  

+
+   
Here are some examples of appropriate titles, contrasted with the top-level headings 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 heading assumes the reader knows 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 IDL attribute.

+
+  
+
+  
User agents should use the document's title when referring to the document in their user
+  interface. When the contents of a title element are used in this way, the
+  directionality of that title element should be used to set the directionality
+  of the document's title in the user interface.

+
+  
+
+
+  
4.2.3 The base element

+
+  
Categories:
Metadata content.
Contexts in which this element can be used:
In a head element containing no other base elements.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
href — Document base URL
target — Default browsing context for hyperlink navigation and form submission
DOM interface:

+
[HTMLConstructor]
+interface HTMLBaseElement : HTMLElement {
+  [CEReactions] attribute USVString href;
+  [CEReactions] attribute DOMString target;
+};

+   

+
+  
The base element allows authors to specify the document base URL for
+  the purposes of parsing URLs, and the name of the default
+  browsing context for the purposes of following hyperlinks. The element
+  does not represent any content beyond this information.

+
+  
There must be no more than one base element per document.

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

+
+  
The href content attribute, if specified, must
+  contain a valid URL potentially surrounded by spaces.

+
+  
A base element, if it has an href attribute,
+  must come before any other elements in the tree that have attributes defined as taking URLs, except the html element (its manifest attribute isn't affected by base
+  elements).

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

+
+  
+
+  
The target attribute, if specified, must
+  contain a valid browsing context name or keyword, which specifies which
+  browsing context is to be used as the default when hyperlinks and forms in the
+  Document cause navigation.

+
+  
A base element, if it has a target
+  attribute, must come before any elements in the tree that represent hyperlinks.

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

+
+  
A base element that is the first base element with an href content attribute in a document tree has a
+  frozen base URL. The frozen base URL must be immediately
+  set for an element whenever any of the following
+  situations occur:

+
+  
+
+  
To set the frozen base URL for an element element:

+
+  
  1. Let document be element's node document.
+
+   
  2. Let urlRecord be the result of parsing the
+   value of element's href content attribute with
+   document's fallback base URL, and document's character encoding. (Thus, the base
+   element isn't affected by itself.)
  3. Set element's frozen base URL to document's
+   fallback base URL, if urlRecord is failure or running Is base
+   allowed for Document? on the resulting URL record and document
+   returns "Blocked", and to urlRecord otherwise.

+
+  
The href IDL attribute, on getting, must return
+  the result of running the following algorithm:
+  
+
+  
  1. Let document be element's node document.
+
+   
  2. Let url be the value of the href
+   attribute of this element, if it has one, and the empty string otherwise.
  3. Let urlRecord be the result of parsing
+   url with document's fallback base URL, and
+   document's character encoding.
+   (Thus, the base element isn't affected by other base elements or
+   itself.)
  4. If urlRecord is failure, return url.
  5. Return the serialization of
+   urlRecord.

+
+  
The href IDL attribute, on setting, must set the href content attribute to the given new value.

+
+  
The target IDL attribute must
+  reflect the content attribute of the same name.

+
+  
+
+  

+
+   
In this example, a base element is used to set the document base
+   URL:

+
+   
<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <title>This is an example for the &lt;base&gt; element</title>
+        <base href="https://www.example.com/news/index.html">
+    </head>
+    <body>
+        <p>Visit the <a href="archives.html">archives</a>.</p>
+    </body>
+</html>

+
+   
The link in the above example would be a link to "https://www.example.com/news/archives.html".

+
+  

+
+
+
+
+  
Spec bugs: 21622

+
+  
Categories:
Metadata content.
If the element is allowed in the body: flow content.
If the element is allowed in the body: phrasing content.
Contexts in which this element can be used:
Where metadata content is expected.
In a noscript element that is a child of a head element.
If the element is allowed in the body: where phrasing content is expected.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
href — Address of the hyperlink
crossorigin — How the element handles crossorigin requests
rel — Relationship between the document containing the hyperlink and the destination resource
media — Applicable media
nonce — Cryptographic nonce used in Content Security Policy checks [CSP]
integrity — Integrity metadata used in Subresource Integrity checks [SRI]
hreflang — Language of the linked resource
type — Hint for the type of the referenced resource
referrerpolicy — Referrer policy for fetches initiated by the element
sizes — Sizes of the icons (for rel="icon")
as — Destination for a preload request (for rel="preload")
scope — Scope url for a service worker registration (for rel="serviceworker")
usecache — Whether to set use cache to true for a service worker registration (for rel="serviceworker")
workertype — Service worker type for a service worker registration (for rel="serviceworker")
color — Color to use when customizing a site's icon (for rel="mask-icon")
Also, the title attribute has special semantics on this element: Title of the link; CSS style sheet set name.
DOM interface:

+
[HTMLConstructor]
+interface HTMLLinkElement : HTMLElement {
+  [CEReactions] attribute USVString href;
+  [CEReactions] attribute DOMString? crossOrigin;
+  [CEReactions] attribute DOMString rel;
+  [CEReactions] attribute DOMString as; // (default "")
+  [SameObject, PutForwards=value] readonly attribute DOMTokenList relList;
+  [CEReactions] attribute DOMString media;
+  [CEReactions] attribute DOMString nonce;
+  [CEReactions] attribute DOMString integrity;
+  [CEReactions] attribute DOMString hreflang;
+  [CEReactions] attribute DOMString type;
+  [SameObject, PutForwards=value] readonly attribute DOMTokenList sizes;
+  [CEReactions] attribute DOMString referrerPolicy;
+  [CEReactions] attribute USVString scope;
+  [CEReactions] attribute WorkerType workerType;
+  [CEReactions] attribute boolean useCache;
+
+  // also has obsolete members
+};
+HTMLLinkElement implements LinkStyle;

+   

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

+
+  
The destination of the link(s) is given by the href attribute, which must be present and must contain a
+  valid non-empty URL potentially surrounded by spaces. If the href attribute is absent, then the element does not define a
+  link.

+
+  
The crossorigin attribute is a
+  CORS settings attribute. It is intended for use with external resource links.

+
+  
The types of link indicated (the relationships) are given by the value of the rel attribute, which, if present, must have a value that is a
+  set of space-separated tokens. The allowed keywords and their
+  meanings are defined in a later section. If the rel attribute is absent, has no keywords, or if none of the keywords
+  used are allowed according to the definitions in this specification, then the element does not
+  create any links.

+
+  
+
+  
rel's
+  supported tokens are the keywords defined in
+  HTML link types which are allowed on link elements, impact
+  the processing model, and are supported by the user agent. The possible supported tokens are
+  alternate,
+  dns-prefetch,
+  icon,
+  next,
+  pingback,
+  preconnect,
+  prefetch,
+  preload,
+  prerender,
+  search,
+  serviceworker, and
+  stylesheet.
+  rel's supported
+  tokens must only include the tokens from this list that the user agent implements the
+  processing model for.

+
+  
Theoretically a user agent could support the processing model for the canonical keyword — if it were a search engine that executed
+  JavaScript. But in practice that's quite unlikely. So in most cases, canonical ought not be included in rel's supported
+  tokens.

+
+  
+
+  
A link element must have either a rel
+  attribute or an itemprop attribute, but not both.

+
+  
If a link element has an itemprop attribute,
+  or has a rel attribute that contains only keywords that are
+  body-ok, then the element is said to be allowed in the body. This means
+  that the element can be used where phrasing content is expected.

+
+  
If the rel attribute is used, the element can
+  only sometimes be used in the body of the page. When used with the itemprop attribute, the element can be used both in the
+  head element and in the body of the page, subject to the constraints of
+  the microdata model.

+
+  
Two categories of links can be created using the link element: Links to external resources and hyperlinks. The link types section defines
+  whether a particular link type is an external resource or a hyperlink. One link
+  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.

+
+  
Each link created for a link element is handled separately. For
+  instance, if there are two link elements with rel="stylesheet",
+  they each count as a separate external resource, and each is affected by its own attributes
+  independently. Similarly, if a single link element has a rel attribute with the value next stylesheet,
+  it creates both a hyperlink (for the next keyword) and
+  an external resource link (for the stylesheet
+  keyword), and they are affected by other attributes (such as media or title)
+  differently.

+
+  

+
+   
For example, the following link element creates two hyperlinks (to the same page):

+
+   
<link rel="author license" href="/about">

+
+   
The two links created by this element are one whose semantic is that the target page has
+   information about the current page's author, and one whose semantic is that the target page has
+   information regarding the license under which the current page is provided.

+
+  

+
+  
Hyperlinks created with the link
+  element and its rel attribute apply to the whole document.
+  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 exact behavior for links to external resources
+  depends on the exact relationship, as defined for the relevant link
+  type.

+
+  
The media attribute says which media the
+  resource applies to. The value must be a valid media query list.

+
+  
The nonce attribute represents a cryptographic
+  nonce ("number used once") which can be used by Content Security Policy to determine
+  whether or not an external resource specified by the
+  link will be loaded and applied to the document. The value is text. [CSP]

+
+  
The integrity attribute represents the integrity metadata for requests which this
+  element is responsible for. The value is text. The attribute must not be specified on
+  link elements that do not have a rel attribute
+  that contains the stylesheet keyword. [SRI]

+
+  
The hreflang attribute on the
+  link element has the same semantics as the hreflang attribute on the a
+  element.

+
+  
The type attribute gives the MIME
+  type of the linked resource. It is purely advisory. The value must be a valid MIME
+  type.

+
+  
For external resource links, the type attribute is used as a hint to user agents so that they can
+  avoid fetching resources they do not support.

+
+  
The referrerpolicy attribute is a
+  referrer policy attribute. It is intended for use with external resource links, where it helps set the referrer policy
+  used when obtaining the external resource. [REFERRERPOLICY].

+
+  
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 that are in a document tree, for which the title attribute defines CSS
+  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 gives the sizes of icons
+  for visual media. Its value, if present, is merely advisory. User agents may use the
+  value to decide which icon(s) to use if multiple icons are available. If specified, the
+  attribute must have a value that is an unordered set of unique space-separated tokens
+  which are ASCII case-insensitive. Each value must be either an ASCII
+  case-insensitive match for the string "any", or a
+  value that consists of two valid non-negative
+  integers that do not have a leading U+0030 DIGIT ZERO (0) character and that are separated
+  by a single U+0078 LATIN SMALL LETTER X or U+0058 LATIN CAPITAL LETTER X character. The attribute
+  must not be specified on link elements that do not have a rel attribute that specifies the icon
+  keyword or the apple-touch-icon keyword.

+
+  
The apple-touch-icon keyword is a registered extension to the predefined set of link types, but user
+  agents are not required to support it in any way.

+
+  

+
+  
The as attribute specifies the destination for a preload request for the resource
+  given by the href attribute. It is an enumerated
+  attribute. Each request destination,
+  including the empty string, is a keyword for this attribute, mapping to a state of the same name.
+  The attribute's missing value default and invalid value default are both the empty string state. The attribute may be
+  omitted. The attribute must not be specified on link elements that do not have a
+  rel attribute that contains the
+  preload keyword. User agents must implement the
+  processing model of the as attribute described in
+  Preload. [FETCH] [PRELOAD]

+
+  

+
+  
The scope attribute specifies the scope
+  url for a service worker registration. If the attribute is present, the value
+  must be a valid URL potentially surrounded by spaces. The attribute must not be
+  specified on link elements that do not have a rel
+  attribute that contains the serviceworker keyword.

+
+  
The usecache attribute is a boolean
+  attribute which sets use cache to true for a service worker
+  registration. The attribute must not be specified on link elements that do not
+  have a rel attribute that contains the serviceworker keyword.

+
+  
The workertype attribute is an
+  enumerated attribute that specifies the service worker type for a
+  service worker registration. The attribute's keywords are classic and module, which map to the respective states
+  classic and module. The missing value default is the classic
+  state. The attribute must not be specified on link elements that do not have a rel attribute that contains the serviceworker keyword.

+
+  

+
+  
The color attribute is used with the mask-icon link type. The attribute must not be specified on link
+  elements that do not have a rel attribute that contains the
+  mask-icon keyword. The value must be a string that matches the CSS
+  <color> production, defining a suggested color that user agents can use to
+  customize the display of the icon that the user sees when they pin your site.

+
+  
This specification does not have any user agent requirements for the color attribute.

+
+  
The mask-icon keyword is a registered extension to the predefined set of link types, but user
+  agents are not required to support it in any way.

+
+  
+  

+
+  
The IDL attributes
+  href,
+  hreflang,
+  integrity,
+  media,
+  nonce,
+  rel,
+  scope,
+  sizes, and
+  type
+  each must reflect the respective content attributes of the same name.

+
+  
There is no reflecting IDL attribute for the color attribute, but this might be added later.

+
+  
The as IDL attribute must reflect the
+  as content attribute, limited to only known
+  values.

+
+  
The crossOrigin IDL attribute must
+  reflect the crossorigin content
+  attribute.

+
+  
The referrerPolicy IDL attribute must
+  reflect the referrerpolicy
+  content attribute, limited to only known values.

+
+  
The relList IDL attribute must reflect the rel content attribute.

+
+  
The useCache IDL attribute must
+  reflect the usecache content attribute.

+
+  
The workerType IDL attribute must
+  reflect the workertype content
+  attribute.

+
+  
4.2.4.1 Processing the media attribute

+
+  
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 when the media attribute's value
+  matches the environment and the other relevant conditions apply, and must not apply
+  it otherwise.

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

+
+  
The external resource might have further restrictions defined within that limit
+  its applicability. For example, a CSS style sheet might have some @media
+  blocks. This specification does not override such further restrictions or requirements.

+
+  
4.2.4.2 Processing the type attribute

+
+  
If type attribute is present, then the user agent must
+  assume that the resource is of the given type (even if that is not a valid MIME type,
+  e.g. the empty string). If the attribute is omitted, but the external resource link
+  type has a default type defined, then the user agent must assume that the resource is of that
+  type. If the UA does not support the given MIME type for the given link relationship,
+  then the UA should not obtain the resource; if the UA
+  does support the given MIME type for the given link relationship, then the UA should
+  obtain the resource at the appropriate time as specified
+  for the external resource link's particular type.  If the attribute is omitted, and
+  the external resource link type does not have a default type defined, but the user
+  agent would obtain the resource if the type was known
+  and supported, then the user agent should obtain the
+  resource under the assumption that it will be supported.

+
+  
User agents must not consider the type attribute
+  authoritative — upon fetching the resource, user agents must not use the type attribute to determine its actual type. Only the actual type
+  (as defined in the next paragraph) is used to determine whether to apply the resource,
+  not the aforementioned assumed type.

+
+  
+
+  
The stylesheet link type defines rules for
+  processing the resource's Content-Type metadata.

+
+  
Once the user agent has established the type of the resource, the user agent must apply the
+  resource if it is of a supported type and the other relevant conditions apply, and must ignore the
+  resource otherwise.

+
+  

+
+   
If a document contains style sheet links labeled as follows:

+
+   
<link rel="stylesheet" href="A" type="text/plain">
+<link rel="stylesheet" href="B" type="text/css">
+<link rel="stylesheet" href="C">

+
+   
...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 of 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.

+
+  

+
+  
+
+  
For external resources that are represented in the DOM (for example, style sheets), the DOM
+  representation must be made available (modulo cross-origin restrictions) even if the resource is
+  not applied. To obtain the resource, the user agent must
+  run the following steps:

+
+  
  1. If the href attribute's value is the empty string,
+   then abort these steps.
  2. Parse the URL given by the href attribute, relative to the element's node
+   document. If that fails, then abort these steps. Otherwise, let url be the
+   resulting URL record.
  3. Let corsAttributeState be the current state of the element's crossorigin content attribute.
  4. Let request be the result of creating a potential-CORS request given
+   url, the empty string, and corsAttributeState.
+
+   
  5. Set request's client to the
+   link element's node document's Window object's
+   environment settings object.
+
+   
  6. Set request's cryptographic
+   nonce metadata to the current value of the link element's nonce content attribute.
  7. Set request's integrity
+   metadata to the current value of the link element's integrity content attribute.
  8. Set request's
+   referrer policy to the current state of the
+   link element's referrerpolicy
+   attribute.
  9. Fetch request.

+
+  
User agents may opt to only try to obtain such resources when they are needed, instead of
+  pro-actively fetching all the external resources that are not applied.

+
+  
The semantics of the protocol used (e.g. HTTP) must be followed when fetching external
+  resources. (For example, redirects will be followed and 404 responses will cause the external
+  resource to not be applied.)

+
+  
+  
Once the attempts to obtain the resource and its critical subresources are
+  complete, the user agent must, if the loads were successful, queue a task to
+  fire an event named load
+  at the link element, or, if the resource or one of its critical
+  subresources failed to completely load for any reason (e.g. DNS error, HTTP 404 response, a
+  connection being prematurely closed, unsupported Content-Type), queue a task to fire an event named error at
+  the link element. Non-network errors in processing the resource or its subresources
+  (e.g. CSS parse errors, PNG decoding errors) are not failures for the purposes of this
+  paragraph.

+
+  
The task source for these tasks is the
+  DOM manipulation task source.

+
+  
The element must delay the load event of the element's node document
+  until all the attempts to obtain the resource and its critical subresources are
+  complete.  (Resources that the user agent has not yet attempted to obtain, e.g. because it is
+  waiting for the resource to be needed, do not delay the load event.)

+
+  
+
+  
HTTP `Link` headers, if supported, must be assumed to come
+  before any links in the document, in the order that they were given in the HTTP message. These
+  headers are to be processed according to the rules given in the relevant specifications. [HTTP] [WEBLINK]
 
+
+  
Registration of relation types in HTTP `Link`
+  headers is distinct from HTML link types, and thus their semantics can be
+  different from same-named HTML types.

+
+  
+
+  
+
+  
Interactive user agents may 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
+  could 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)
  • The title of the resource (given by the title
+   attribute).
  • The address of the resource (given by the href
+   attribute).
  • The language of the resource (given by the hreflang
+   attribute).
  • The optimum media for the resource (given by the media
+   attribute).

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

+
+  
The activation behavior of link elements that create hyperlinks is to run the following steps:

+
+  
  1. If the link element's node document is not fully
+   active, then abort these steps.
  2. Follow the hyperlink created by the
+   link element.

+
+
+
+
+
+  
4.2.5 The meta element

+
+  
Categories:
Metadata content.
If the itemprop attribute is present: flow content.
If the itemprop attribute is present: phrasing content.
Contexts in which this element can be used:
If the charset attribute is present, or if the element's http-equiv attribute is in the Encoding declaration state: in a head element.
If the http-equiv attribute is present but not in the Encoding declaration state: in a head element.
If the http-equiv attribute is present but not in the Encoding declaration state: in a noscript element that is a child of a head element.
If the name attribute is present: where metadata content is expected.
If the itemprop attribute is present: where metadata content is expected.
If the itemprop attribute is present: where phrasing content is expected.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
name — Metadata name
http-equiv — Pragma directive
content — Value of the element
charset — Character encoding declaration
DOM interface:

+
[HTMLConstructor]
+interface HTMLMetaElement : HTMLElement {
+  [CEReactions] attribute DOMString name;
+  [CEReactions] attribute DOMString httpEquiv;
+  [CEReactions] attribute DOMString content;
+
+  // also has obsolete members
+};

+   

+
+  
The meta element represents various kinds of metadata that cannot be
+  expressed using the title, base, link, style,
+  and script elements.

+
+  
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.

+
+  
Exactly one of the name, http-equiv, charset,
+  and itemprop attributes must be specified.

+
+  
If either name, http-equiv, or itemprop is
+  specified, then the content attribute must also be
+  specified. Otherwise, it must be omitted.

+
+  
The charset attribute specifies the character
+  encoding used by the document. This is a character encoding declaration. If the
+  attribute is present in an XML document, its value must be an
+  ASCII case-insensitive match for the string "utf-8" (and the
+  document is therefore forced to use UTF-8 as its encoding).

+
+  
The charset attribute on the
+  meta element has no effect in XML documents, and is only allowed in order to
+  facilitate migration to and from XML.

+
+  
There must not be more than one meta element with a charset attribute per document.

+
+  
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.

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

+
+  
+
+
+  
4.2.5.1 Standard metadata names

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

+
+  
Names are case-insensitive, and must be compared in an ASCII
+  case-insensitive manner.

+
+  
application-name

+
+    
The value must be a short free-form string 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.
+    Translations of the Web application's name may be given, using the lang attribute to specify the language of each name.

+
+    
There must not be more than one meta element with a given language
+    and with its name attribute set to the value application-name per document.

+
+    
+
+    
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.

+
+    
To find the application name to use given an ordered list of languages (e.g. British English,
+    American English, and English), user agents must run the following steps:

+
+    
  1. Let languages be the list of languages.
  2. Let default language be the language of the
+     Document's document element, if any, and if that language is not
+     unknown.
    
+
+     
  3. If there is a default language, and if it is not the same language
+     as any of the languages in languages, append it to languages.
  4. 
+
+      
    Let winning language be the first language in languages for which there is a meta element in the
+      Document that has its name attribute set to
+      the value application-name and whose
+      language is the language in question.
    
+
+      
    If none of the languages have such a meta element, then abort these steps;
+      there's no given application name.
    
+
+     
  5. 
+
+      
    Return the value of the content attribute of the
+      first meta element in the Document in tree order that
+      has its name attribute set to the value application-name and whose language is winning language.
    
+
+     

+
+    
This algorithm would be used by a browser when it needs a name for the page, for
+    instance, to label a bookmark. The languages it would provide to the algorithm would be the
+    user's preferred languages.

+
+    
+
+   
author
The value must be a free-form string giving the name of one of the page's
+   authors.
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. There must not be more than
+   one meta element with its name attribute set to
+   the value description per document.
generator

+
+    
The value must be a free-form string that identifies one of the software packages used to
+    generate the document. This value must not be used on pages whose markup is not generated by
+    software, e.g. pages whose markup was written by a user in a text editor.

+
+    

+
+     
Here is what a tool called "Frontweaver" could include in its output, in the page's
+     head element, to identify itself as the tool used to generate the page:

+
+     
<meta name=generator content="Frontweaver 8.2">

+
+    

+
+   
keywords

+
+    
The value must be a set of comma-separated tokens, each of which is a keyword
+    relevant to the page.

+
+    

+
+     
This page about typefaces on British motorways uses a meta element to specify
+     some keywords that users might use to look for the page:

+
+     
<!DOCTYPE HTML>
+<html lang="en-GB">
+ <head>
+  <title>Typefaces on UK motorways</title>
+  <meta name="keywords" content="british,type face,font,fonts,highway,highways">
+ </head>
+ <body>
+  ...

+
+    

+
+    
Many search engines do not consider such keywords, because this feature has
+    historically been used unreliably and even misleadingly as a way to spam search engine results
+    in a way that is not helpful for users.

+
+    
+
+    
To obtain the list of keywords that the author has specified as applicable to the page, the
+    user agent must run the following steps:

+
+    
  1. Let keywords be an empty list.
  2. 
+
+      
    For each meta element with a name
+      attribute and a content attribute and whose name attribute's value is keywords:
    
+
+      
    1. Split the value of the element's content attribute on commas.
    2. Add the resulting tokens, if any, to keywords.
    
+
+     
  3. Remove any duplicates from keywords.
  4. Return keywords. This is the list of keywords that the author has
+     specified as applicable to the page.

+
+    
User agents should not use this information when there is insufficient confidence in the
+    reliability of the value.

+
+    
For instance, it would be reasonable for a content management system to use
+    the keyword information of pages within the system to populate the index of a site-specific
+    search engine, but a large-scale content aggregator that used this information would likely find
+    that certain users would try to game its ranking mechanism through the use of inappropriate
+    keywords.

+
+    
+
+   
referrer

+    
The value must be a referrer policy, which defines the default referrer
+    policy for the Document. [REFERRERPOLICY]

+
+    
+
+    
If any meta elements are inserted into the document or removed from the document, or existing
+    meta elements have their name or content attributes changed, user agents must run the
+    following algorithm:

+
+    
  1. 
+      
    Let candidate elements be the list of all meta elements that
+      meet the following criteria, in tree order:
    
+
+      
+     
  2. 
+      
    For each element in candidate elements:
    
+
+      
    1. Let value be the value of element's content attribute, converted to ASCII
+       lowercase.
    2. 
+        
      If value is one of the values given in the first column of the following
+        table, then set value to the value given in the second column:
      
+
+        
      Legacy value
+           Referrer policy
+         
      never
+           no-referrer
+          
      default
+           no-referrer-when-downgrade
+          
      always
+           unsafe-url
+          
      origin-when-crossorigin
+           origin-when-cross-origin
+        
      
+       
    3. If value is a referrer policy, then set element's
+       node document's referrer
+       policy to policy.
    
+
+      
    The fact that these steps are applied for each element enables deployment of
+      fallback values for older user agents. [REFERRERPOLICY]
    
+     

+
+    
+   
theme-color

+
+    
The value must be a string that matches the CSS <color> production, defining
+    a suggested color that user agents should use to customize the display of the page or of the
+    surrounding user interface. For example, a browser might color the page's title bar with the
+    specified value, or use it as a color highlight in a tab bar or task switcher.

+
+    
There must not be more than one meta element with its name attribute set to the value theme-color per document.

+
+    

+
+     
This standard itself uses "WHATWG green" as its theme color:

+
+     
<!DOCTYPE HTML>
+<title>HTML Standard</title>
+<meta name="theme-color" content="#3c790a">
+...

+
+    

+
+    
+
+     
To obtain a page's theme color, user agents must run the following steps:

+
+     
  1. 
+       
    Let candidate elements be the list of all meta elements that
+       meet the following criteria, in tree order:
    
+
+       
+      
  2. 
+       
    For each element in candidate elements:
    
+
+       
    1. Let value be the result of stripping leading and trailing ASCII whitespace from the value of
+        element's content attribute.
    2. If value can be parsed as a CSS <color> value, return
+        the parsed color.
    
+      
  3. If this step is reached, the page has no theme color.

+
+     
If any meta elements are inserted into the document or removed from the document, or existing meta elements have their
+     name or content
+     attributes changed, user agents must re-run the above algorithm and apply the result to any
+     affected UI.

+
+    
+
+    
When using the theme color in UI, user agents may adjust it in implementation-specific ways
+    to make it more suitable for the UI in question. For example, if a user agent intends to use
+    the theme color as a background and display white text over it, it might use a darker variant of
+    the theme color in that part of the UI, to ensure adequate contrast.

+
+   

+
+
+
+  
4.2.5.2 Other metadata names

+
+  
Anyone can create and use their own extensions to the
+  predefined set of metadata names. There is no requirement to register such extensions.

+
+  
However, a new metadata name should not be created in any of the following cases:

+
+  
  • If either the name is a URL, or the value of its accompanying content attribute is a URL; in those cases,
+   registering it as an extension to the predefined set of
+   link types is encouraged (rather than creating a new metadata name).
  • If the name is for something expected to have processing requirements in user agents; in
+   that case it ought to be standardized.

+
+  
Also, before creating and using a new metadata name, consulting the WHATWG Wiki MetaExtensions page is
+  encouraged — to avoid choosing a metadata name that's already in use, and to avoid duplicating the
+  purpose of any metadata names that are already in use, and to avoid new standardized names
+  clashing with your chosen name. [WHATWGWIKI]

+
+  
Anyone is free to edit the WHATWG Wiki MetaExtensions page at any time to add a metadata name.
+  New metadata names can 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 non-normative description of what the metadata name's meaning is, including the
+   format the value is required to be in.
Specification
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). Anyone may remove synonyms that are not used in practice; only names that need to
+   be processed as synonyms for compatibility with legacy content are to be registered in this
+   way.
Status

+
+    
One of the following:

+
+    
Proposed
The name has not received wide peer review and approval. Someone has proposed it and is, or
+     soon will be, using it.
Ratified
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.
Discontinued
The metadata name has received wide peer review and it has been found wanting. Existing
+     pages are using this metadata name, but new pages should avoid it. The "brief description" and
+     "specification" entries will give details of what authors should use instead, if anything.

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

+
+    
If a metadata name is added in the "proposed" state for a period of a month or more without
+    being used or specified, then it may be removed from the WHATWG Wiki MetaExtensions page.

+
+    
If a metadata name is added with the "proposed" status and found to be redundant with
+    existing values, it should be removed and listed as a synonym for the existing value. If a
+    metadata name is added with the "proposed" status and found to be harmful, then it should be
+    changed to "discontinued" status.

+
+    
Anyone can change the status at any time, but should only do so in accordance with the
+    definitions above.

+
+   

+
+
+
+  
4.2.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.
+  Some of the keywords are non-conforming, as noted in the last
+  column.

+
+
+  
State
+     Keyword
+     Notes
+   
Content Language
+     content-language
+     Non-conforming
+    
Encoding declaration
+     content-type
+     
+
+    
Default style
+     default-style
+     
+    
Refresh
+     refresh
+     
+    
Cookie setter
+     set-cookie
+     Non-conforming
+    
X-UA-Compatible
+     x-ua-compatible
+     
+    
Content security policy
+     Content-Security-Policy
+     
+  

+
+
+
+  
+
+  
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:

+
+  
+
+  
Content language state
+   (http-equiv="content-language")
+
+   

+
+    
This feature is non-conforming. Authors are encouraged to use the lang attribute instead.

+
+    
This pragma sets the pragma-set default language. Until such a pragma is
+    successfully processed, there is no pragma-set default language.

+
+    
+
+    
  1. If the meta element has no content
+     attribute, then abort these steps.
  2. If the element's content attribute contains a
+     U+002C COMMA character (,) then abort these steps.
  3. Let input be the value of the element's content attribute.
  4. Let position point at the first character of input.
  5. Skip ASCII whitespace within input given
+     position.
  6. Collect a sequence of code points that are not ASCII
+     whitespace from input given position.
  7. Let candidate be the string that resulted from the previous
+     step.
  8. If candidate is the empty string, abort these steps.
  9. 
+
+      
    Set the pragma-set default language to candidate.
    
+
+      
    If the value consists of multiple space-separated tokens, tokens after the
+      first are ignored.
    
+
+     

+
+    
This pragma is almost, but not quite, entirely unlike the HTTP `Content-Language` header of the same name. [HTTP]

+
+   
Encoding declaration state (http-equiv="content-type")
+
+   

+
+    
The Encoding declaration state is
+    just an alternative form of setting the charset
+    attribute: it is a character encoding declaration. This state's user
+    agent requirements are all handled by the parsing section of the specification.

+
+    
For meta elements with an http-equiv
+    attribute in the Encoding declaration
+    state, the content attribute must have a value
+    that is an ASCII case-insensitive match for a string that consists of: the literal
+    string "text/html;", optionally followed by any number of ASCII
+    whitespace, followed by the literal string "charset=", followed by
+    one of the labels of the character
+    encoding of the character encoding declaration.

+
+    
A document must not contain both a meta element with an http-equiv attribute in the Encoding declaration state and a
+    meta element with the charset attribute
+    present.

+
+    
The Encoding declaration state may be
+    used in HTML documents, but elements with an http-equiv attribute in that state must not be used in
+    XML documents.

+
+   
Default style state (http-equiv="default-style")
+
+   

+
+    
This pragma sets the name of the default
+    CSS style sheet set.

+
+    
+
+    
  1. If the meta element has no content
+     attribute, or if that attribute's value is the empty string, then abort these steps.
  2. Change the preferred CSS style sheet set name with the name being the value
+     of the element's content attribute. [CSSOM]

+
+    
+
+   
Refresh state (http-equiv="refresh")
+
+   

+
+    
This pragma acts as timed redirect.

+
+    
+
+    
  1. If another meta element with an http-equiv attribute in the Refresh state has already been successfully
+     processed (i.e. when it was inserted the user agent processed it and reached the step labeled
+     end), then abort these steps.
  2. If the meta element has no content
+     attribute, or if that attribute's value is the empty string, then abort these steps.
  3. Let document be the meta element's node
+     document.
  4. Let input be the value of the element's content attribute.
  5. Let position point at the first character of input.
  6. Skip ASCII whitespace within input given
+     position.
  7. Collect a sequence of code points that are ASCII digits from
+     input given position, and parse the resulting string using the
+     rules for parsing non-negative integers. If the sequence of characters collected
+     is the empty string, then no number will have been parsed; abort these steps. Otherwise, let
+     time be the parsed number.
  8. Collect a sequence of code points that are ASCII digits and
+     U+002E FULL STOP characters (.) from input given position. Ignore any
+     collected characters.
  9. Let url be document's URL.
  10. If position is past the end of input, jump to the step labeled
+     end.
  11. If the character in input pointed to by position is not a U+003B
+     SEMICOLON character (;), a U+002C COMMA character (,), or ASCII whitespace, then
+     abort these steps.
  12. Skip ASCII whitespace within input given
+     position.
  13. If the character in input pointed to by position is a U+003B
+     SEMICOLON character (;), a U+002C COMMA character (,), then advance position to the
+     next character.
  14. Skip ASCII whitespace within input given
+     position.
  15. If position is past the end of input, jump to the step labeled
+     end.
  16. Let url be equal to the substring of input from
+     the character at position to the end of the string.
  17. If the character in input pointed to by position
+     is a U+0055 LATIN CAPITAL LETTER U character (U) or a U+0075 LATIN SMALL LETTER U character
+     (u), then advance position to the next character. Otherwise, jump to the step
+     labeled skip quotes.
  18. If the character in input pointed to by position
+     is a U+0052 LATIN CAPITAL LETTER R character (R) or a U+0072 LATIN SMALL LETTER R character
+     (r), then advance position to the next character. Otherwise, jump to the step
+     labeled parse.
  19. If the character in input pointed to by position
+     is s U+004C LATIN CAPITAL LETTER L character (L) or a U+006C LATIN SMALL LETTER L character
+     (l), then advance position to the next character. Otherwise, jump to the step
+     labeled parse.
  20. Skip ASCII whitespace within input given
+     position.
  21. If the character in input pointed to by position
+     is a U+003D EQUALS SIGN (=), then advance position to the next character. Otherwise,
+     jump to the step labeled parse.
  22. Skip ASCII whitespace within input given
+     position.
  23. Skip quotes: If the character in input pointed to by
+     position is either a U+0027 APOSTROPHE character (') or U+0022 QUOTATION MARK
+     character ("), then let quote be that character, and advance position to
+     the next character. Otherwise, let quote be the empty string.
  24. Let url be equal to the substring of input from
+     the character at position to the end of the string.
  25. If quote is not the empty string, and there is a character in url
+     equal to quote, then truncate url at that character, so that it and all
+     subsequent characters are removed.
    
+
+     
  26. Parse: Parse url relative to
+     document. If that fails, abort these steps. Otherwise, let urlRecord be
+     the resulting URL record.
  27. 
+
+      
    End: Perform one or more of the following steps:
    
+
+      
+
+      
    In addition, the user agent may, as with anything, inform the user of any and all aspects
+      of its operation, including the state of any timers, the destinations of any timed redirects,
+      and so forth.
    
+
+     

+
+    
+
+    
For meta elements with an http-equiv
+    attribute in the Refresh state, the content attribute must have a value consisting either of:

+
+    
+
+    
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 URL.

+
+    

+
+     
A news organization's front page could include the following markup in the page's
+     head element, to ensure that the page automatically reloads from the server every
+     five minutes:

+
+     
<meta http-equiv="Refresh" content="300">

+
+    

+
+    

+
+     
A sequence of pages could be used as an automated slide show by making each page refresh to
+     the next page in the sequence, using markup such as the following:

+
+     
<meta http-equiv="Refresh" content="20; URL=page4.html">

+
+    

+
+   
Cookie setter (http-equiv="set-cookie")
+
+   

+
+    
This pragma sets an HTTP cookie. [COOKIES]

+
+    
It is non-conforming. Real HTTP headers should be used instead.

+
+    
  1. If the meta element has no content
+     attribute, or if that attribute's value is the empty string, then abort these steps.
  2. Act as if receiving a
+     set-cookie-string for the document's URL via
+     a "non-HTTP" API, consisting of the value of the element's content attribute encoded as
+     UTF-8. [COOKIES] [ENCODING]

+
+   
X-UA-Compatible state (http-equiv="x-ua-compatible")
+
+   

+
+    
In practice, this pragma encourages Internet Explorer to more closely follow the
+    specifications.

+
+    
For meta elements with an http-equiv
+    attribute in the X-UA-Compatible state, the
+    content attribute must have a value that is an
+    ASCII case-insensitive match for the string "IE=edge".

+
+    
User agents are required to ignore this pragma.

+
+   
Content security policy state (http-equiv="content-security-policy")
+
+   

+
+    
This pragma enforces a Content Security
+    Policy on a Document. [CSP]

+
+    
+
+    
  1. If the meta element is not a child of a head element,
+     abort these steps.
  2. If the meta element has no content
+     attribute, or if that attribute's value is the empty string, then abort these steps.
  3. Let policy be the result of executing Content Security Policy's parse
+     a serialized Content Security Policy algorithm on the meta element's
+     content attribute's value.
  4. Remove all occurrences of the report-uri, frame-ancestors, and sandbox directives from policy.
  5. Enforce the policy policy.

+
+    
+
+    
For meta elements with an http-equiv
+    attribute in the Content security
+    policy state, the content attribute must have a
+    value consisting of a valid Content Security
+    Policy, but must not contain any report-uri,
+    frame-ancestors, or sandbox directives.
+    The Content Security Policy given in the content attribute will be enforced upon the current document. [CSP]

+
+    

+
+     
A page might choose to mitigate the risk of cross-site scripting attacks by preventing the
+     execution of inline JavaScript, as well as blocking all plugin content, using a policy such
+     as the following:
+
+     
<meta http-equiv="Content-Security-Policy" content="script-src 'self'; object-src 'none'">

+
+    

+   
Spec bugs: 28339, 28563

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

+
+
+  
4.2.5.4 Other pragma directives

+
+  
Extensions to the predefined set of pragma
+  directives may, under certain conditions, be registered in the WHATWG Wiki PragmaExtensions page. [WHATWGWIKI]

+
+  
Such extensions must use a name that is identical to an HTTP header registered in the Permanent
+  Message Header Field Registry, and must have behavior identical to that described for the HTTP
+  header. [IANAPERMHEADERS]

+
+  
Pragma directives corresponding to headers describing metadata, or not requiring specific user
+  agent processing, must not be registered; instead, use metadata names. Pragma directives corresponding to headers
+  that affect the HTTP processing model (e.g. caching) must not be registered, as they would result
+  in HTTP-level behavior being different for user agents that implement HTML than for user agents
+  that do not.

+
+  
Anyone is free to edit the WHATWG Wiki PragmaExtensions page at any time to add a pragma
+  directive satisfying these conditions. Such registrations must specify the following
+  information:

+
+  
Keyword
The actual name being defined. The name must match a previously-registered HTTP name with
+   the same requirements.
Brief description
A short non-normative description of the purpose of the pragma directive.
Specification
A link to the specification defining the corresponding HTTP header.

+
+  
+
+  
Conformance checkers must use the information given on the WHATWG Wiki PragmaExtensions page to
+  establish if a value is allowed or not: values defined in this specification or listed on the
+  aforementioned page must be accepted, whereas values not listed in either this specification or on
+  the aforementioned page must be rejected as invalid. Conformance checkers may cache this
+  information (e.g. for performance reasons or to avoid the use of unreliable network
+  connectivity).

+
+  
+
+
+
+
+  
4.2.5.5 Specifying the document's character encoding
Spec bugs: 18338

+
+  
+
+  
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 an ASCII case-insensitive match for
+   one of the labels of the character
+   encoding used to serialize the file. [ENCODING]
  • The character encoding declaration must be serialized without the use of character references or character escapes of any kind.
  • The element containing the character encoding
+   declaration must be serialized completely within the first 1024 bytes of the
+   document.

+
+  
In addition, due to a number of restrictions on meta elements, there can only be
+  one meta-based character encoding declaration per document.
 
+
+  
If an HTML document does not start with a BOM, and its
+  encoding is not explicitly given by Content-Type
+  metadata, and the document is not an iframe srcdoc document, then the character encoding used must be
+  an ASCII-compatible encoding, and the encoding must be specified using a
+  meta element with a charset attribute or a
+  meta element with an http-equiv attribute
+  in the Encoding declaration state.

+
+  
A character encoding declaration is required (either in the Content-Type metadata or explicitly in the file) even when all
+  characters are in the ASCII range, because a character encoding is needed to process non-ASCII
+  characters entered by the user in forms, in URLs generated by scripts, and so forth.

+
+  
If the document is an iframe srcdoc
+  document, the document must not have a character encoding declaration. (In
+  this case, the source is already decoded, since it is part of the document that contained the
+  iframe.)

+
+  
If an HTML document contains a meta element
+  with a charset attribute or a meta element
+  with an http-equiv attribute in the Encoding declaration state, then the character
+  encoding used must be an ASCII-compatible encoding.

+
+  
Authors should use UTF-8. Conformance checkers may advise authors against using
+  legacy encodings. [ENCODING]

+
+  
+
+  
Authoring tools should default to using UTF-8 for newly-created documents. [ENCODING]

+
+  
+
+  
Authors must not use encodings that are not defined in the WHATWG Encoding standard.
+  Additionally, authors should not use ISO-2022-JP. [ENCODING]

+
+  
Some encodings that are not defined in the WHATWG Encoding standard use bytes in
+  the range 0x20 to 0x7E, inclusive, to encode characters other than the corresponding characters in
+  the range U+0020 to U+007E, inclusive, and represent a potential security vulnerability: a user
+  agent might end up interpreting supposedly benign plain text content as HTML tags and
+  JavaScript.

+
+  
Using non-UTF-8 encodings can have unexpected results on form submission and URL
+  encodings, which use the document's character encoding by default.

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

+
+  

+
+   
In HTML, to declare that the character encoding is UTF-8, the author could
+   include the following markup near the top of the document (in the head element):

+
+   
<meta charset="utf-8">

+
+   
In XML, the XML declaration would be used instead, at the very top of the markup:

+
+   
<?xml version="1.0" encoding="utf-8"?>

+
+  

+
+
+
+  
4.2.6 The style element

+
+  
Categories:
Metadata content.
Contexts in which this element can be used:
Where metadata content is expected.
In a noscript element that is a child of a head element.
Content model:
Depends on the value of the type attribute, but must match requirements described in prose below.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
media — Applicable media
nonce — Cryptographic nonce used in Content Security Policy checks [CSP]
type — Type of embedded resource
Also, the title attribute has special semantics on this element: CSS style sheet set name.
DOM interface:

+
[HTMLConstructor]
+interface HTMLStyleElement : HTMLElement {
+  [CEReactions] attribute DOMString media;
+  [CEReactions] attribute DOMString nonce;
+  [CEReactions] attribute DOMString type;
+};
+HTMLStyleElement implements LinkStyle;

+   

+
+  
The style element allows authors to embed style information in their documents.
+  The style element is one of several inputs to the styling processing
+  model. The element does not represent content for the
+  user.

+
+  
The type attribute gives the styling language.
+  If the attribute is present, its value must be a valid MIME type that designates a
+  styling language. The charset parameter must not be specified. The default
+  value for the type attribute, which is used if the attribute
+  is absent, is "text/css". [RFC2318]

+
+  
+
+   
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 charset parameter must be treated as an unknown parameter for the purpose of
+  comparing MIME types here.

+
+  
+
+  
The media attribute says which media the
+  styles apply to. The value must be a valid media query list. The user
+  agent must apply the styles when the media attribute's
+  value matches the environment and the other relevant conditions apply, and must not
+  apply them otherwise.

+
+  
+
+  
The styles might be further limited in scope, e.g. in CSS with the use of @media blocks. This specification does not override such further restrictions or
+  requirements.

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

+
+  
The nonce attribute represents a
+  cryptographic nonce ("number used once") which can be used by Content Security Policy
+  to determine whether or not the style specified by an element will be applied to the document. The
+  value is text. [CSP]

+
+  
The title attribute on
+  style elements defines CSS style sheet
+  sets. If the style element has no title
+  attribute, then it has no title; the title attribute of ancestors
+  does not apply to the style element. If the style element is not
+  in a document tree, then the title attribute
+  is ignored. [CSSOM]

+
+  
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.

+
+  
The textContent of a style element must match the style production in the following ABNF, the character set for which is Unicode. [ABNF]

+
+  
style         = no-c-start *( c-start no-c-end c-end no-c-start )
+no-c-start    = < any string that doesn't contain a substring that matches c-start >
+c-start       = "<!--"
+no-c-end      = < any string that doesn't contain a substring that matches c-end >
+c-end         = "-->"

+
+  
+
+  

+
+  
+
+  
The user agent must run the update a style block
+  algorithm that applies for the style sheet language specified by the style
+  element's type attribute, passing it the element's
+  style data, whenever one of the following conditions occur:

+  
+
+  
+
+  
For styling languages that consist of pure text (as opposed to XML), a style
+  element's style data is the child text content of the style
+  element. For XML-based styling languages, the style data consists of all the child
+  nodes of the style element.

+
+  
The update a style block algorithm for CSS (text/css) is
+  as follows:

+
+  
  1. Let element be the style element.
  2. If element has an associated CSS style sheet, remove the CSS style sheet in question.
  3. If element's root is neither a shadow root nor a
+   document, then abort these steps.
  4. If the Should element's inline behavior be blocked by Content Security
+   Policy? algorithm returns "Blocked" when executed upon the
+   style element, "style", and the style
+   element's style data, then abort these steps. [CSP]
  5. 
+
+    
    Create a CSS style sheet with the following properties:
    
+
+    
    type
    text/css
    owner node
    element
    media
    
+
+      
    The media attribute of element.
    
+
+      
    This is a reference to the (possibly absent at this time) attribute, rather
+      than a copy of the attribute's current value. The CSSOM specification defines what happens
+      when the attribute is dynamically set, changed, or removed.
    
+
+     
    title
    
+
+      
    The title attribute of element, if
+      element is in a document tree, or the empty string otherwise.
    
+
+      
    Again, this is a reference to the attribute.
    
+
+     
    alternate flag
    Unset.
    origin-clean flag
    Set.
    location
    parent CSS style sheet
    owner CSS rule
    null
    disabled flag
    Left at its default value.
    CSS rules
    Left uninitialized.
    
+
+    
+
+   

+
+  
This specification does not define any other styling language's update a style block algorithm.

+
+  
+  
Once the attempts to obtain the style sheet's critical subresources, if any, are
+  complete, or, if the style sheet has no critical subresources, once the style sheet
+  has been parsed and processed, the user agent must, if the loads were successful or there were
+  none, queue a task to fire an event named
+  load at the style element, or, if one of the style
+  sheet's critical subresources failed to completely load for any reason (e.g. DNS
+  error, HTTP 404 response, a connection being prematurely closed, unsupported Content-Type),
+  queue a task to fire an event named error at the style element. Non-network errors in
+  processing the style sheet or its subresources (e.g. CSS parse errors, PNG decoding errors) are
+  not failures for the purposes of this paragraph.

+
+  
The task source for these tasks is the DOM
+  manipulation task source.

+
+  
The element must delay the load event of the element's node document until all the
+  attempts to obtain the style sheet's critical subresources, if any, are complete.

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

+
+  
+
+  
The media, nonce, and type IDL attributes must reflect the respective
+  content attributes of the same name.

+
+  
+
+  
The LinkStyle interface is also implemented by this element. [CSSOM]

+
+  

+
+   
The following document has its stress emphasis styled as bright red text rather than italics
+   text, while leaving titles of works and Latin words in their default italics. It shows how using
+   appropriate elements enables easier restyling of documents.

+
+   
<!DOCTYPE html>
+<html lang="en-US">
+ <head>
+  <title>My favorite book</title>
+  <style>
+   body { color: black; background: white; }
+   em { font-style: normal; color: red; }
+  </style>
+ </head>
+ <body>
+  <p>My <em>favorite</em> book of all time has <em>got</em> to be
+  <cite>A Cat's Life</cite>. It is a book by P. Rahmel that talks
+  about the <i lang="la">Felis Catus</i> in modern human society.</p>
+ </body>
+</html>

+
+  

+
+
+
+  
+
+  
4.2.7 Interactions of styling and scripting

+
+  
Style sheets, whether added by a link element, a style element, an
+  <?xml-stylesheet?> PI, an HTTP `Link` header, or
+  some other mechanism, have a style sheet ready flag, which is initially unset.

+
+  
When a style sheet is ready to be applied, its style sheet ready flag must be set.
+  If the style sheet referenced no other resources (e.g. it was an internal style sheet given by a
+  style element with no @import rules), then the style rules must
+  be immediately made available to script; otherwise, the style rules must only be made available
+  to script once the event loop reaches its update the rendering step.

+
+  
A style sheet in the context of the Document of an HTML parser or
+  XML parser is said to be a style sheet that is blocking scripts if the
+  element was created by that Document's parser, and the element is either a
+  style element or a link element that was an external resource link that contributes to the styling processing
+  model when the element was created by the parser, and the element's style sheet was enabled
+  when the element was created by the parser, and the element's style sheet ready flag
+  is not yet set, and, the last time the event loop reached step 1,
+  the element's root was that Document, and the user agent hasn't given up
+  on that particular style sheet yet. A user agent may give up on a style sheet at any time.

+
+  
Giving up on a style sheet before the style sheet loads, if the style sheet
+  eventually does still load, means that the script might end up operating with incorrect
+  information. For example, if a style sheet sets the color of an element to green, but a script
+  that inspects the resulting style is executed before the sheet is loaded, the script will find
+  that the element is black (or whatever the default color is), and might thus make poor choices
+  (e.g. deciding to use black as the color elsewhere on the page, instead of green). Implementors
+  have to balance the likelihood of a script using incorrect information with the performance impact
+  of doing nothing while waiting for a slow network request to finish.

+
+  
A Document has a style sheet that is blocking scripts if there is
+  either a style sheet that is blocking scripts in the context of that
+  Document, or if that Document has a browsing context that has a parent browsing
+  context, and the active document of that parent browsing context
+  itself has a style sheet that is blocking scripts.

+
+  
A Document has no style sheet that is blocking scripts if it does not
+  have a style sheet that is blocking
+  scripts as defined in the previous paragraph.

+
+  
+
+
+
+
+  
4.3 Sections
Support: html5semanticChrome for Android 57+Chrome 26+UC Browser for Android (limited) 11.4+iOS Safari 7.0+Firefox 21+IE (limited) 9+Samsung Internet 4+Opera Mini (limited) all+Android Browser 4.4+Edge 12+Safari 6.1+Opera 15+
Source: caniuse.com

+
+  
4.3.1 The body element

+
+  
Categories:
Sectioning root.
Contexts in which this element can be used:
As the second element in an html element.
Content model:
Flow content.
Tag omission in text/html:
A body element's start tag can be omitted
+   if the element is empty, or if the first thing inside the body element is not
+   ASCII whitespace or a comment, except if the
+   first thing inside the body element is a meta, link,
+   script, style, or template element. 
A body element's end tag can be omitted if the
+   body element is not immediately followed by a comment.
Content attributes:
Global attributes
onafterprint
onbeforeprint
onbeforeunload
onhashchange
onlanguagechange
onmessage
onmessageerror
onoffline
ononline
onpagehide
onpageshow
onpopstate
onrejectionhandled
onstorage
onunhandledrejection
onunload
DOM interface:

+
[HTMLConstructor]
+interface HTMLBodyElement : HTMLElement {
+  // also has obsolete members
+};
+
+HTMLBodyElement implements WindowEventHandlers;

+

+
+  
The body element represents the main content of the document.

+
+  
In conforming documents, there is only one body element. The document.body IDL 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 body element exposes as event handler content attributes a number
+  of the event handlers of the Window object. It also mirrors their
+  event handler IDL attributes.

+
+  
The onblur, onerror,
+  onfocus, onload, onresize, and onscroll
+  event handlers of the Window object, exposed on the body
+  element, replace the generic event handlers with the same names normally supported by
+  HTML elements.

+
+  
Thus, for example, a bubbling error event
+  dispatched on a child of the body element of a Document would first
+  trigger the onerror event handler content
+  attributes of that element, then that of the root html element, and only
+  then would it trigger the onerror event handler content attribute on the
+  body element. This is because the event would bubble from the target, to the
+  body, to the html, to the Document, to the
+  Window, and the event handler on the
+  body is watching the Window not the body. A regular event
+  listener attached to the body using addEventListener(),
+  however, would be run when the event bubbled through the body and not when it reaches
+  the Window object.

+
+  

+
+   
This page updates an indicator to show whether or not the user is online:

+
+   
<!DOCTYPE HTML>
+<html lang="en">
+ <head>
+  <title>Online or offline?</title>
+  <script>
+   function update(online) {
+     document.getElementById('status').textContent =
+       online ? 'Online' : 'Offline';
+   }
+  </script>
+ </head>
+ <body ononline="update(true)"
+       onoffline="update(false)"
+       onload="update(navigator.onLine)">
+  <p>You are: <span id="status">(Unknown)</span></p>
+ </body>
+</html>

+
+  

+
+
+
+  
4.3.2 The article element

+
+  
Categories:
Flow content.
Sectioning content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Flow content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The article element represents a complete, or self-contained,
+  composition in a document, page, application, or site and that is, in principle, independently
+  distributable or reusable, e.g. in syndication. This could be a forum post, a magazine or
+  newspaper article, a blog entry, a user-submitted comment, an interactive widget or gadget, or any
+  other independent item of content.

+
+  
+
+  
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 blog entry on a site that accepts user-submitted comments could represent the comments
+  as article elements nested within the article element for the blog
+  entry.

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

+
+  
When used specifically with content to be redistributed in syndication, the
+  article element is similar in purpose to the entry element in
+  Atom. [ATOM]
+
+  
The schema.org microdata vocabulary can be used to provide the publication date
+  for an article element, using one of the CreativeWork subtypes.

+
+  
When the main content of the page (i.e. excluding footers, headers, navigation blocks, and
+  sidebars) is all one single self-contained composition, that content may be marked with an
+  article, but it is technically redundant in that case (since it's self-evident that
+  the page is a single composition, as it is a single document).

+
+  

+
+   
This example shows a blog post using the article element, with some schema.org
+   annotations:

+
+   
<article itemscope itemtype="http://schema.org/BlogPosting">
+ <header>
+  <h1 itemprop="headline">The Very First Rule of Life</h1>
+  <p><time itemprop="datePublished" datetime="2009-10-09">3 days ago</time></p>
+  <link itemprop="url" href="?comments=0">
+ </header>
+ <p>If there's a microphone anywhere near you, assume it's hot and
+ sending whatever you're saying to the world. Seriously.</p>
+ <p>...</p>
+ <footer>
+  <a itemprop="discussionUrl" href="?comments=1">Show comments...</a>
+ </footer>
+</article>

+
+   
Here is that same blog post, but showing some of the comments:

+
+   
<article itemscope itemtype="http://schema.org/BlogPosting">
+ <header>
+  <h1 itemprop="headline">The Very First Rule of Life</h1>
+  <p><time itemprop="datePublished" datetime="2009-10-09">3 days ago</time></p>
+  <link itemprop="url" href="?comments=0">
+ </header>
+ <p>If there's a microphone anywhere near you, assume it's hot and
+ sending whatever you're saying to the world. Seriously.</p>
+ <p>...</p>
+ <section>
+  <h1>Comments</h1>
+  <article itemprop="comment" itemscope itemtype="http://schema.org/UserComments" id="c1">
+   <link itemprop="url" href="#c1">
+   <footer>
+    <p>Posted by: <span itemprop="creator" itemscope itemtype="http://schema.org/Person">
+     <span itemprop="name">George Washington</span>
+    </span></p>
+    <p><time itemprop="commentTime" datetime="2009-10-10">15 minutes ago</time></p>
+   </footer>
+   <p>Yeah! Especially when talking about your lobbyist friends!</p>
+  </article>
+  <article itemprop="comment" itemscope itemtype="http://schema.org/UserComments" id="c2">
+   <link itemprop="url" href="#c2">
+   <footer>
+    <p>Posted by: <span itemprop="creator" itemscope itemtype="http://schema.org/Person">
+     <span itemprop="name">George Hammond</span>
+    </span></p>
+    <p><time itemprop="commentTime" datetime="2009-10-10">5 minutes ago</time></p>
+   </footer>
+   <p>Hey, you have the same first name as me.</p>
+  </article>
+ </section>
+</article>

+
+   
Notice the use of footer to give the information for each comment (such as who
+   wrote it and when): the footer element can appear at the start of its
+   section when appropriate, such as in this case. (Using header in this case wouldn't
+   be wrong either; it's mostly a matter of authoring preference.)

+
+  

+
+  

+
+   
In this example, article elements are used to host widgets on a portal page. The
+   widgets are implemented as customized built-in
+   elements in order to get specific styling and scripted behavior.

+
+   
<!DOCTYPE HTML>
+<html lang=en>
+<title>eHome Portal</title>
+<script src="/scripts/widgets.js">
+<link rel=stylesheet href="/styles/main.css">
+<article is="stock-widget">
+ <h1>Stocks</h1>
+ <table>
+  <thead> <tr> <th> Stock <th> Value <th> Delta
+  <tbody> <template> <tr> <td> <td> <td> </template>
+ </table>
+ <p> <input type=button value="Refresh" onclick="this.parentElement.refresh()">
+</article>
+<article is="news-widget">
+ <h1>News</h1>
+ <ul>
+  <template>
+   <li>
+    <p><img> <strong></strong>
+    <p>
+  </template>
+ </ul>
+ <p> <input type=button value="Refresh" onclick="this.parentElement.refresh()">
+</article>

+
+  

+
+
+
+  
4.3.3 The section element

+
+  
Categories:
Flow content.
Sectioning content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Flow content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

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

+
+  
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, and contact information.

+
+  
Authors are encouraged to use the article element instead of the
+  section element when it would make sense to syndicate the contents of the
+  element.

+
+  
The section element is not a generic
+  container element. When an element is needed only for styling purposes or as a convenience for
+  scripting, authors are encouraged to use the div element instead. A general rule is
+  that the section element is appropriate only if the element's contents would be
+  listed explicitly in the document's outline.

+
+  

+
+   
In the following example, we see an article (part of a larger Web page) about apples,
+   containing two short sections.

+
+   
<article>
+ <hgroup>
+  <h1>Apples</h1>
+  <h2>Tasty, delicious fruit!</h2>
+ </hgroup>
+ <p>The apple is the pomaceous fruit of the apple tree.</p>
+ <section>
+  <h1>Red Delicious</h1>
+  <p>These bright red apples are the most common found in many
+  supermarkets.</p>
+ </section>
+ <section>
+  <h1>Granny Smith</h1>
+  <p>These juicy, green apples make a great filling for
+  apple pies.</p>
+ </section>
+</article>

+
+   
Notice how the use of section means that the author can use h1
+   elements throughout, without having to worry about whether a particular section is at the top
+   level, the second level, the third level, and so on.

+
+  

+
+  

+
+   
Here is a graduation programme with two sections, one for the list of people graduating, and
+   one for the description of the ceremony. (The markup in this example features an uncommon style
+   sometimes used to minimize the amount of inter-element whitespace.)

+
+   
<!DOCTYPE Html>
+<Html Lang=En
+ ><Head
+   ><Title
+     >Graduation Ceremony Summer 2022</Title
+   ></Head
+ ><Body
+   ><H1
+     >Graduation</H1
+   ><Section
+     ><H1
+       >Ceremony</H1
+     ><P
+       >Opening Procession</P
+     ><P
+       >Speech by Validactorian</P
+     ><P
+       >Speech by Class President</P
+     ><P
+       >Presentation of Diplomas</P
+     ><P
+       >Closing Speech by Headmaster</P
+   ></Section
+   ><Section
+     ><H1
+       >Graduates</H1
+     ><Ul
+       ><Li
+         >Molly Carpenter</Li
+       ><Li
+         >Anastasia Luccio</Li
+       ><Li
+         >Ebenezar McCoy</Li
+       ><Li
+         >Karrin Murphy</Li
+       ><Li
+         >Thomas Raith</Li
+       ><Li
+         >Susan Rodriguez</Li
+     ></Ul
+   ></Section
+ ></Body
+></Html>

+
+  

+
+  

+
+   
In this example, a book author has marked up some sections as chapters and some as appendices,
+   and uses CSS to style the headers in these two classes of section differently.

+
+   
<style>
+ section { border: double medium; margin: 2em; }
+ section.chapter h1 { font: 2em Roboto, Helvetica Neue, sans-serif; }
+ section.appendix h1 { font: small-caps 2em Roboto, Helvetica Neue, sans-serif; }
+</style>
+<header>
+ <hgroup>
+  <h1>My Book</h1>
+  <h2>A sample with not much content</h2>
+ </hgroup>
+ <p><small>Published by Dummy Publicorp Ltd.</small></p>
+</header>
+<section class="chapter">
+ <h1>My First Chapter</h1>
+ <p>This is the first of my chapters. It doesn't say much.</p>
+ <p>But it has two paragraphs!</p>
+</section>
+<section class="chapter">
+ <h1>It Continues: The Second Chapter</h1>
+ <p>Bla dee bla, dee bla dee bla. Boom.</p>
+</section>
+<section class="chapter">
+ <h1>Chapter Three: A Further Example</h1>
+ <p>It's not like a battle between brightness and earthtones would go
+ unnoticed.</p>
+ <p>But it might ruin my story.</p>
+</section>
+<section class="appendix">
+ <h1>Appendix A: Overview of Examples</h1>
+ <p>These are demonstrations.</p>
+</section>
+<section class="appendix">
+ <h1>Appendix B: Some Closing Remarks</h1>
+ <p>Hopefully this long example shows that you <em>can</em> style
+ sections, so long as they are used to indicate actual sections.</p>
+</section>

+
+  

+
+
+
+  
4.3.4 The nav element

+
+  
Categories:
Flow content.
Sectioning content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Flow content, but with no main element descendants.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
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 —
+  the element is primarily intended for sections that consist of major navigation blocks. In
+  particular, it is common for footers to have a short list of links to various pages of a site,
+  such as the terms of service, the home page, and a copyright page. The footer element
+  alone is sufficient for such cases; while a nav element can be used in such cases, it
+  is usually unnecessary.

+
+  
User agents (such as screen readers) that are targeted at users who can benefit
+  from navigation information being omitted in the initial rendering, or who can benefit from
+  navigation information being immediately available, can use this element as a way to determine
+  what content on the page to initially skip or provide on request (or both).

+
+  

+
+   
In the following example, there are two nav elements, one for primary navigation
+   around the site, and one for secondary navigation around the page itself.

+
+   
<body>
+ <h1>The Wiki Center Of Exampland</h1>
+ <nav>
+  <ul>
+   <li><a href="/">Home</a></li>
+   <li><a href="/events">Current Events</a></li>
+   ...more...
+  </ul>
+ </nav>
+ <article>
+  <header>
+   <h1>Demos in Exampland</h1>
+   <p>Written by A. N. Other.</p>
+  </header>
+  <nav>
+   <ul>
+    <li><a href="#public">Public demonstrations</a></li>
+    <li><a href="#destroy">Demolitions</a></li>
+    ...more...
+   </ul>
+  </nav>
+  <div>
+   <section id="public">
+    <h1>Public demonstrations</h1>
+    <p>...more...</p>
+   </section>
+   <section id="destroy">
+    <h1>Demolitions</h1>
+    <p>...more...</p>
+   </section>
+   ...more...
+  </div>
+  <footer>
+   <p><a href="?edit">Edit</a> | <a href="?delete">Delete</a> | <a href="?Rename">Rename</a></p>
+  </footer>
+ </article>
+ <footer>
+  <p><small>© copyright 1998 Exampland Emperor</small></p>
+ </footer>
+</body>

+
+  

+
+  

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

+
+   
<body itemscope itemtype="http://schema.org/Blog">
+ <header>
+  <h1>Wake up sheeple!</h1>
+  <p><a href="news.html">News</a> -
+     <a href="blog.html">Blog</a> -
+     <a href="forums.html">Forums</a></p>
+  <p>Last Modified: <span itemprop="dateModified">2009-04-01</span></p>
+  <nav>
+   <h1>Navigation</h1>
+   <ul>
+    <li><a href="articles.html">Index of all articles</a></li>
+    <li><a href="today.html">Things sheeple need to wake up for today</a></li>
+    <li><a href="successes.html">Sheeple we have managed to wake</a></li>
+   </ul>
+  </nav>
+ </header>
+ <main>
+  <article itemprop="blogPosts" itemscope itemtype="http://schema.org/BlogPosting">
+   <header>
+    <h1 itemprop="headline">My Day at the Beach</h1>
+   </header>
+   <main itemprop="articleBody">
+    <p>Today I went to the beach and had a lot of fun.</p>
+    ...more content...
+   </main>
+   <footer>
+    <p>Posted <time itemprop="datePublished" datetime="2009-10-10">Thursday</time>.</p>
+   </footer>
+  </article>
+  ...more blog posts...
+ </main>
+ <footer>
+  <p>Copyright ©
+   <span itemprop="copyrightYear">2010</span>
+   <span itemprop="copyrightHolder">The Example Company</span>
+  </p>
+  <p><a href="about.html">About</a> -
+     <a href="policy.html">Privacy Policy</a> -
+     <a href="contact.html">Contact Us</a></p>
+ </footer>
+</body>

+
+   
Notice the main elements being used to wrap all the contents of the page other
+   than the header and footer, and all the contents of the blog entry other than its header and
+   footer.

+
+   
You can also see microdata annotations in the above example that use the schema.org vocabulary
+   to provide the publication date and other metadata about the blog post.

+
+  

+
+  

+
+   
A nav element doesn't have to contain a list, it can contain other kinds of
+   content as well. In this navigation block, links are provided in prose:

+
+   
<nav>
+ <h1>Navigation</h1>
+ <p>You are on my home page. To the north lies <a href="/blog">my
+ blog</a>, from whence the sounds of battle can be heard. To the east
+ you can see a large mountain, upon which many <a
+ href="/school">school papers</a> are littered. Far up thus mountain
+ you can spy a little figure who appears to be me, desperately
+ scribbling a <a href="/school/thesis">thesis</a>.</p>
+ <p>To the west are several exits. One fun-looking exit is labeled <a
+ href="https://games.example.com/">"games"</a>. Another more
+ boring-looking exit is labeled <a
+ href="https://isp.example.net/">ISP™</a>.</p>
+ <p>To the south lies a dark and dank <a href="/about">contacts
+ page</a>. Cobwebs cover its disused entrance, and at one point you
+ see a rat run quickly out of the page.</p>
+</nav>

+
+  

+
+  

+
+   
In this example, nav is used in an e-mail application, to let the user switch
+   folders:

+
+   
<p><input type=button value="Compose" onclick="compose()"></p>
+<nav>
+ <h1>Folders</h1>
+ <ul>
+  <li> <a href="/inbox" onclick="return openFolder(this.href)">Inbox</a> <span class=count></span>
+  <li> <a href="/sent" onclick="return openFolder(this.href)">Sent</a>
+  <li> <a href="/drafts" onclick="return openFolder(this.href)">Drafts</a>
+  <li> <a href="/trash" onclick="return openFolder(this.href)">Trash</a>
+  <li> <a href="/customers" onclick="return openFolder(this.href)">Customers</a>
+ </ul>
+</nav>

+
+  

+
+
+
+  
4.3.5 The aside element

+
+  
Categories:
Flow content.
Sectioning content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Flow content, but with no main element descendants.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
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 element can be used for typographical effects like pull quotes or sidebars, for
+  advertising, for groups of nav elements, and for other content that is considered
+  separate from the main content of the page.

+
+  
It's not appropriate to use the aside element just for
+  parentheticals, since those are part of the main flow of the document.

+
+  

+
+   
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 following extract shows how aside can be used for blogrolls and other side
+   content on a blog:

+
+   
<body>
+ <header>
+  <h1>My wonderful blog</h1>
+  <p>My tagline</p>
+ </header>
+ <aside>
+  <!-- this aside contains two sections that are tangentially related
+  to the page, namely, links to other blogs, and links to blog posts
+  from this blog -->
+  <nav>
+   <h1>My blogroll</h1>
+   <ul>
+    <li><a href="https://blog.example.com/">Example Blog</a>
+   </ul>
+  </nav>
+  <nav>
+   <h1>Archives</h1>
+   <ol reversed>
+    <li><a href="/last-post">My last post</a>
+    <li><a href="/first-post">My first post</a>
+   </ol>
+  </nav>
+ </aside>
+ <aside>
+  <!-- this aside is tangentially related to the page also, it
+  contains twitter messages from the blog author -->
+  <h1>Twitter Feed</h1>
+  <blockquote cite="https://twitter.example.net/t31351234">
+   I'm on vacation, writing my blog.
+  </blockquote>
+  <blockquote cite="https://twitter.example.net/t31219752">
+   I'm going to go on vacation soon.
+  </blockquote>
+ </aside>
+ <article>
+  <!-- this is a blog post -->
+  <h1>My last post</h1>
+  <p>This is my last post.</p>
+  <footer>
+   <p><a href="/last-post" rel=bookmark>Permalink</a>
+  </footer>
+ </article>
+ <article>
+  <!-- this is also a blog post -->
+  <h1>My first post</h1>
+  <p>This is my first post.</p>
+  <aside>
+   <!-- this aside is about the blog post, since it's inside the
+   <article> element; it would be wrong, for instance, to put the
+   blogroll here, since the blogroll isn't really related to this post
+   specifically, only to the page as a whole -->
+   <h1>Posting</h1>
+   <p>While I'm thinking about it, I wanted to say something about
+   posting. Posting is fun!</p>
+  </aside>
+  <footer>
+   <p><a href="/first-post" rel=bookmark>Permalink</a>
+  </footer>
+ </article>
+ <footer>
+  <nav>
+   <a href="/archives">Archives</a> —
+   <a href="/about">About me</a> —
+   <a href="/copyright">Copyright</a>
+  </nav>
+ </footer>
+</body>

+
+  

+
+
+
+  
4.3.6 The h1, h2, h3, h4, h5, and
+  h6 elements

+
+  
Categories:
Flow content.
Heading content.
Palpable content.
Contexts in which this element can be used:
As a child of an hgroup element.
Where flow content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:

+    
[HTMLConstructor]
+interface HTMLHeadingElement : HTMLElement {
+  // also has obsolete members
+};

+   

+
+  
These elements represent headings for their sections.

+
+  
The semantics and meaning of these elements are defined in the section on headings and
+  sections.

+
+  
These elements have a rank given by the number in their name. The h1
+  element is said to have the highest rank, the h6 element has the lowest rank, and two
+  elements with the same name have equal rank.

+
+  

+
+   
As far as their respective document outlines (their heading and section structures) are
+   concerned, these two snippets are semantically equivalent:

+
+   
<body>
+<h1>Let's call it a draw(ing surface)</h1>
+<h2>Diving in</h2>
+<h2>Simple shapes</h2>
+<h2>Canvas coordinates</h2>
+<h3>Canvas coordinates diagram</h3>
+<h2>Paths</h2>
+</body>

+
+   
<body>
+ <h1>Let's call it a draw(ing surface)</h1>
+ <section>
+  <h1>Diving in</h1>
+ </section>
+ <section>
+  <h1>Simple shapes</h1>
+ </section>
+ <section>
+  <h1>Canvas coordinates</h1>
+  <section>
+   <h1>Canvas coordinates diagram</h1>
+  </section>
+ </section>
+ <section>
+  <h1>Paths</h1>
+ </section>
+</body>

+
+   
Authors might prefer the former style for its terseness, or the latter style for its
+   convenience in the face of heavy editing; which is best is purely an issue of preferred authoring
+   style.

+
+   
The two styles can be combined, for compatibility with legacy tools while still
+   future-proofing for when that compatibility is no longer needed. This third snippet again has the
+   same outline as the previous two:

+
+   
<body>
+ <h1>Let's call it a draw(ing surface)</h1>
+ <section>
+  <h2>Diving in</h2>
+ </section>
+ <section>
+  <h2>Simple shapes</h2>
+ </section>
+ <section>
+  <h2>Canvas coordinates</h2>
+  <section>
+   <h3>Canvas coordinates diagram</h3>
+  </section>
+ </section>
+ <section>
+  <h2>Paths</h2>
+ </section>
+</body>

+
+  

+
+
+
+
+  
4.3.7 The hgroup element

+
+  
Categories:
Flow content.
Heading content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
One or more h1, h2, h3, h4, h5, h6, and template elements.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The hgroup element represents the heading of a section, which
+  consists of all the h1–h6 element children of the
+  hgroup element. The element is used to group a set of
+  h1–h6 elements when the heading has multiple levels, such as
+  subheadings, alternative titles, or taglines.

+
+  
The rank of an hgroup element is the rank of the highest-ranked
+  h1–h6 element descendant of the hgroup element, if
+  there are any such elements, or otherwise the same as for an h1 element (the highest
+  rank). Other h1–h6 elements of heading content in the
+  hgroup element indicate subheadings or subtitles or (secondary) alternative
+  titles.

+
+  
The section on headings and sections defines how hgroup elements are
+  assigned to individual sections.

+
+  

+
+   
Here are some examples of valid headings.

+
+    
<hgroup>
+ <h1>The reality dysfunction</h1>
+ <h2>Space is not the only void</h2>
+</hgroup>

+
+    
<hgroup>
+ <h1>Dr. Strangelove</h1>
+ <h2>Or: How I Learned to Stop Worrying and Love the Bomb</h2>
+</hgroup>

+
+   
The point of using hgroup in these examples is to prevent the h2
+   element (which acts as a secondary title) from creating a separate section of its own in any
+   outline and to instead cause the contents of the h2 to be shown in
+   rendered output from the outline algorithm in some way to indicate that it is not
+   the title of a separate section but instead just a secondary title in a group of titles.

+   
+
+   
How a user agent exposes such multi-level headings in user interfaces (e.g. in tables of
+   contents or search results) is left open to implementors, as it is a user interface issue. The
+   first example above could be rendered as:

+
+   
The reality dysfunction: Space is not the only void

+
+   
Alternatively, it could look like this:
+
+   
The reality dysfunction (Space is not the only void)

+
+   
In interfaces where a title can be rendered on multiple lines, it could be rendered as
+   follows, maybe with the first line in a bigger font size:

+
+   
The reality dysfunction
+Space is not the only void

+
+  

+
+  

+   
The following two examples show ways in which two h1 headings could be used
+   within an hgroup element to group the US and UK names for the same movie.

+
+   
<hgroup>
+ <h1>The Avengers</h1>
+ <h1>Avengers Assemble</h1>
+</hgroup>
+
+<hgroup>
+ <h1>Avengers Assemble</h1>
+ <h1>The Avengers</h1>
+</hgroup>

+
+   
The first example above shows how the movie names might be grouped in a publication in the US,
+   with the US name The Avengers as the (primary) title, and the UK name Avengers
+   Assemble as the (secondary) alternative title. The second example above shows how the movie
+   names might be grouped in a publication in the UK, with the UK name as the (primary) title, and
+   the US name as the (secondary) alternative title.

+
+   
In both cases it is important to note the use of the hgroup element to group the
+   two titles indicates that the titles are not equivalent; instead the first h1 gives
+   the (primary) title while the second gives the (secondary) alternative title. Even though both
+   the title and alternative title are marked up with h1 elements, in a rendered view
+   of output from the outline algorithm, the second h1 in the
+   hgroup will be shown in some way that clearly indicates it is secondary; for
+   example:
+
+   
In a US publication:

+   
The Avengers (Avengers Assemble)

+
+   
In a UK publication:

+   
Avengers Assemble (The Avengers)

+
+  

+
+  

+
+   
In the following example, an hgroup element is used to mark up a two-level
+   heading in a wizard-style dialog box:

+
+   
<dialog onclose="walletSetup.continue(this.returnValue)">
+ <hgroup>
+  <h1>Wallet Setup</h1>
+  <h2>Configure your Wallet funding source</h2>
+ </hgroup>
+ <p>Your Wallet can be used to buy wands at the merchant in town, to buy potions from travelling
+ salesmen you may find in the dungeons, and to pay for mercenaries.</p>
+ <p>We support two payment sources:</p>
+ <form method=dialog>
+  <fieldset oninput="this.getElementsByTagName('input')[0].checked = true">
+   <legend> <label> <input type=radio name=payment-type value=cc> Credit Card </label> </legend>
+   <p><label>Name on card: <input name=cc1 autocomplete="section-cc cc-name" placeholder="Y. Name"></label>
+   <p><label>Card number: <input name=cc2 inputmode=numeric autocomplete="section-cc cc-number" placeholder="6331 1019 9999 0016"></label>
+   <p><label>Expiry Date: <input name=cc3 type=month autocomplete="section-cc cc-exp" placeholder="2020-02"></label>
+   <p><label>Security Code: <input name=cc4 inputmode=numeric autocomplete="section-cc cc-csc" placeholder="246"></label>
+  </fieldset>
+  <fieldset oninput="this.getElementsByTagName('input')[0].checked = true">
+   <legend> <label> <input type=radio name=payment-type value=bank> Checking Account </label> </legend>
+   <p><label>Name on account: <input name=bank1 autocomplete="section-bank cc-name"></label>
+   <p><label>Routing number: <input name=bank2 inputmode=numeric></label>
+   <p><label>Account number: <input name=bank3 inputmode=numeric></label>
+  </fieldset>
+  <button type=submit value="back"> ← Back </button>
+  <button type=submit value="next"> Next → </button>
+ </form>
+</dialog>

+
+  

+
+
+
+  
4.3.8 The header element

+
+  
Categories:
Flow content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Flow content, but with no header, footer, or main element descendants.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The header element represents a group of introductory or navigational
+  aids.

+
+  
A header element is intended to usually contain the section's heading
+  (an h1–h6 element or an hgroup element), but this is
+  not required. The header element can also be used to wrap a section's table of
+  contents, a search form, or any relevant logos.

+
+  

+
+  
Here are some sample headers. This first one is for a game:

+
+   
<header>
+ <p>Welcome to...</p>
+ <h1>Voidwars!</h1>
+</header>

+
+   
The following snippet shows how the element can be used to mark
+   up a specification's header:

+
+   
<header>
+ <hgroup>
+  <h1>Fullscreen API</h1>
+  <h2>Living Standard — Last Updated 19 October 2015</h2>
+ </hgroup>
+ <dl>
+  <dt>Participate:</dt>
+  <dd><a href="https://github.com/whatwg/fullscreen">GitHub whatwg/fullscreen</a></dd>
+  <dt>Commits:</dt>
+  <dd><a href="https://github.com/whatwg/fullscreen/commits">GitHub whatwg/fullscreen/commits</a></dd>
+ </dl>
+</header>

+
+  

+
+  
The header element is not sectioning content; it doesn't
+  introduce a new section.

+
+  

+
+  
In this example, the page has a page heading given by the h1 element, and two
+  subsections whose headings are given by h2 elements. The content after the
+  header element is still part of the last subsection started in the
+  header element, because the header element doesn't take part in the
+  outline algorithm.

+
+   
<body>
+ <header>
+  <h1>Little Green Guys With Guns</h1>
+  <nav>
+   <ul>
+    <li><a href="/games">Games</a>
+    <li><a href="/forum">Forum</a>
+    <li><a href="/download">Download</a>
+   </ul>
+  </nav>
+  <h2>Important News</h2> <!-- this starts a second subsection -->
+  <!-- this is part of the subsection entitled "Important News" -->
+  <p>To play today's games you will need to update your client.</p>
+  <h2>Games</h2> <!-- this starts a third subsection -->
+ </header>
+ <p>You have three active games:</p>
+ <!-- this is still part of the subsection entitled "Games" -->
+ ...

+
+  

+
+
+
+
+  
Spec bugs: 12990

+
+  
Categories:
Flow content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Flow content, but with no header, footer, or main element descendants.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The footer element represents a footer for its nearest ancestor
+  sectioning content or sectioning root element. A footer typically
+  contains information about its section such as who wrote it, links to related documents, copyright
+  data, and the like.

+
+  
When the footer element contains entire sections, they represent appendices, indexes, long colophons, verbose license
+  agreements, and other such content.

+
+  
Contact information for the author or editor of a section belongs in an
+  address element, possibly itself inside a footer. Bylines and other
+  information that could be suitable for both a header or a footer can be
+  placed in either (or neither). The primary purpose of these elements is merely to help the author
+  write self-explanatory markup that is easy to maintain and style; they are not intended to impose
+  specific structures on authors.

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

+
+  
When the nearest ancestor sectioning content or sectioning root
+  element is the body element, then it applies to the whole page.

+
+  
The footer element is not sectioning content; it doesn't
+  introduce a new section.

+
+  

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

+
+   
<body>
+ <footer><a href="../">Back to index...</a></footer>
+ <hgroup>
+  <h1>Lorem ipsum</h1>
+  <h2>The ipsum of all lorems</h2>
+ </hgroup>
+ <p>A dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+ tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
+ veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex
+ ea commodo consequat. Duis aute irure dolor in reprehenderit in
+ voluptate velit esse cillum dolore eu fugiat nulla
+ pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
+ culpa qui officia deserunt mollit anim id est laborum.</p>
+ <footer><a href="../">Back to index...</a></footer>
+</body>

+
+  

+
+  

+
+   
Here is an example which shows the footer element being used both for a site-wide
+   footer and for a section footer.

+
+   
<!DOCTYPE HTML>
+<HTML LANG="en"><HEAD>
+<TITLE>The Ramblings of a Scientist</TITLE>
+<BODY>
+<H1>The Ramblings of a Scientist</H1>
+<ARTICLE>
+ <H1>Episode 15</H1>
+ <VIDEO SRC="/fm/015.ogv" CONTROLS PRELOAD>
+  <P><A HREF="/fm/015.ogv">Download video</A>.</P>
+ </VIDEO>
+ <FOOTER> <!-- footer for article -->
+  <P>Published <TIME DATETIME="2009-10-21T18:26-07:00">on 2009/10/21 at 6:26pm</TIME></P>
+ </FOOTER>
+</ARTICLE>
+<ARTICLE>
+ <H1>My Favorite Trains</H1>
+ <P>I love my trains. My favorite train of all time is a Köf.</P>
+ <P>It is fun to see them pull some coal cars because they look so
+ dwarfed in comparison.</P>
+ <FOOTER> <!-- footer for article -->
+  <P>Published <TIME DATETIME="2009-09-15T14:54-07:00">on 2009/09/15 at 2:54pm</TIME></P>
+ </FOOTER>
+</ARTICLE>
+<FOOTER> <!-- site wide footer -->
+ <NAV>
+  <P><A HREF="/credits.html">Credits</A> —
+     <A HREF="/tos.html">Terms of Service</A> —
+     <A HREF="/index.html">Blog Index</A></P>
+ </NAV>
+ <P>Copyright © 2009 Gordon Freeman</P>
+</FOOTER>
+</BODY>
+</HTML>

+
+  

+
+  

+
+   
Some site designs have what is sometimes referred to as "fat footers" — footers that
+   contain a lot of material, including images, links to other articles, links to pages for sending
+   feedback, special offers... in some ways, a whole "front page" in the footer.

+
+   
This fragment shows the bottom of a page on a site with a "fat footer":

+
+   
...
+ <footer>
+  <nav>
+   <section>
+    <h1>Articles</h1>
+    <p><img src="images/somersaults.jpeg" alt=""> Go to the gym with
+    our somersaults class! Our teacher Jim takes you through the paces
+    in this two-part article. <a href="articles/somersaults/1">Part
+    1</a> · <a href="articles/somersaults/2">Part 2</a></p>
+    <p><img src="images/kindplus.jpeg"> Tired of walking on the edge of
+    a clif<!-- sic -->? Our guest writer Lara shows you how to bumble
+    your way through the bars. <a href="articles/kindplus/1">Read
+    more...</a></p>
+    <p><img src="images/crisps.jpeg"> The chips are down, now all
+    that's left is a potato. What can you do with it? <a
+    href="articles/crisps/1">Read more...</a></p>
+   </section>
+   <ul>
+    <li> <a href="/about">About us...</a>
+    <li> <a href="/feedback">Send feedback!</a>
+    <li> <a href="/sitemap">Sitemap</a>
+   </ul>
+  </nav>
+  <p><small>Copyright © 2015 The Snacker —
+  <a href="/tos">Terms of Service</a></small></p>
+ </footer>
+</body>

+
+  

+
+
+  
4.3.10 The address element

+
+  
Categories:
Flow content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Flow content, but with no heading
+   content descendants, no sectioning content
+   descendants, and no header, footer, or
+   address element descendants.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The address element represents the contact information for its
+  nearest article or body element ancestor. If that is the body
+  element, then the contact information applies to the document as a whole.

+
+  

+   
For example, a page at the W3C Web site related to HTML might
+   include the following contact information:

+   
<ADDRESS>
+ <A href="../People/Raggett/">Dave Raggett</A>,
+ <A href="../People/Arnaud/">Arnaud Le Hors</A>,
+ contact persons for the <A href="Activity">W3C HTML Activity</A>
+</ADDRESS>

+  

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

+
+  
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 along with other information in a
+  footer element.

+
+  
+
+  
The contact information for a node node is a collection of
+  address elements defined by the first applicable entry from the following list:

+
+  
If node is an article element
If node is a body element

+
+    
The contact information consists of all the address elements that have node as an ancestor and do not have another body or
+    article element ancestor that is a descendant of node.

+
+   
If node has an ancestor element that is an article element
If node has an ancestor element that is a body element

+
+    
The contact information of node is the same as the contact information of
+    the nearest article or body element ancestor, whichever is
+    nearest.

+
+   
If node's node document has a body
+   element

+
+    
The contact information of node is the same as the contact information of
+    the body element of the Document.

+
+   
Otherwise

+
+    
There is no contact information for node.

+
+   

+
+  
User agents may expose the contact information of a node to the user, or use it for other
+  purposes, such as indexing sections based on the sections' contact information.

+
+  
+
+  

+
+   
In this example the footer contains contact information and a copyright notice.

+
+   
<footer>
+ <address>
+  For more details, contact
+  <a href="mailto:js@example.com">John Smith</a>.
+ </address>
+ <p><small>© copyright 2038 Example Corp.</small></p>
+</footer>

+
+  

+
+
+
+  
4.3.11 Headings and sections

+
+  
The h1–h6 elements and the hgroup element are
+  headings.

+
+  
The first element of heading content in an element of sectioning
+  content represents the heading for that section. Subsequent headings of equal
+  or higher rank start new (implied) sections, headings of lower rank
+  start implied subsections that are part of the previous one. In both cases, the element
+  represents the heading of the implied section.

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

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

+
+  

+   
For the following fragment:

+   
<body>
+ <h1>Foo</h1>
+ <h2>Bar</h2>
+ <blockquote>
+  <h3>Bla</h3>
+ </blockquote>
+ <p>Baz</p>
+ <h2>Quux</h2>
+ <section>
+  <h3>Thud</h3>
+ </section>
+ <p>Grunt</p>
+</body>

+   
...the structure would be:

+   
  1. 
+     Foo (heading of explicit body section, containing the "Grunt" paragraph)
+     
    1. 
+       Bar (heading starting implied section, containing a block quote and the "Baz" paragraph)
+      
    2. 
+       Quux (heading starting implied section with no content other than the heading itself)
+      
    3. 
+       Thud (heading of explicit section section)
+      
    
+    

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

+  

+
+  
Sections may contain headings 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 headings
+  in one element of sectioning content.

+
+  

+   
For example, the following is correct:

+
+   
<body>
+ <h4>Apples</h4>
+ <p>Apples are fruit.</p>
+ <section>
+  <h2>Taste</h2>
+  <p>They taste lovely.</p>
+  <h6>Sweet</h6>
+  <p>Red apples are sweeter than green ones.</p>
+  <h1>Color</h1>
+  <p>Apples come in various colors.</p>
+ </section>
+</body>

+
+   
However, the same document would be more clearly expressed as:

+
+   
<body>
+ <h1>Apples</h1>
+ <p>Apples are fruit.</p>
+ <section>
+  <h2>Taste</h2>
+  <p>They taste lovely.</p>
+  <section>
+   <h3>Sweet</h3>
+   <p>Red apples are sweeter than green ones.</p>
+  </section>
+ </section>
+ <section>
+  <h2>Color</h2>
+  <p>Apples come in various colors.</p>
+ </section>
+</body>

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

+
+   
This third example is also semantically identical, and might be easier to maintain (e.g. if
+   sections are often moved around in editing):

+
+   
<body>
+ <h1>Apples</h1>
+ <p>Apples are fruit.</p>
+ <section>
+  <h1>Taste</h1>
+  <p>They taste lovely.</p>
+  <section>
+   <h1>Sweet</h1>
+   <p>Red apples are sweeter than green ones.</p>
+  </section>
+ </section>
+ <section>
+  <h1>Color</h1>
+  <p>Apples come in various colors.</p>
+ </section>
+</body>

+
+   
This final example would need explicit style rules to be rendered well in legacy browsers.
+   Legacy browsers without CSS support would render all the headings as top-level headings.

+
+  

+
+
+  
4.3.11.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. The element for which an outline is created
+  is said to be the outline's owner.

+
+  
A section is a container that corresponds to some nodes in
+  the original DOM tree. Each section can have one heading associated with it, and can contain any
+  number of further nested sections. 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 following markup fragment:

+
+   
<body>
+  <hgroup id="document-title">
+    <h1>HTML</h1>
+    <h2>Living Standard — Last Updated 12 August 2016</h2>
+  </hgroup>
+  <p>Some intro to the document.</p>
+  <h2>Table of contents</h2>
+  <ol id=toc>...</ol>
+  <h2>First section</h2>
+  <p>Some intro to the first section.</p>
+</body>

+
+   
...results in the following outline being created for the body node (and thus the
+   entire document):

+
+   
  1. 
+     
    Section created for body node.
    
+     
    Associated with heading <hgroup
+     id="document-title">...</hgroup> consisting of primary heading <h1>HTML</h1> and secondary heading <h2>Living
+     Standard — Last Updated 12 August 2016</h2>.
    
+     
    Also associated with the paragraph <p>Some intro to the
+     document.</p> (though it likely would not be shown in a rendered view of the
+     outline).
    
+     
    Nested sections:
    
+     
    1. 
+       
      Section implied for first h2 element.
      
+       
      Associated with heading <h2>Table of contents</h2>.
      
+       
      Also associated with the ordered list <ol id=toc>...</ol>
+       (though it likely would not be shown in a rendered view of the outline).
      
+       
      No nested sections.
      
+      
    2. 
+       
      Section implied for second h2 element.
      
+       
      Associated with heading <h2>First section</h2>.
      
+       
      Also associated with the paragraph <p>Some intro to the first
+       section.</p> (though it likely would not be shown in a rendered view of the
+       outline).
      
+       
      No nested sections.
      
+      
    
+    

+
+   
The following image shows what a rendered view of the outline might look like.

+
+   
Top-level section with the
+   multi-level heading "HTML: Living Standard — Last Updated 12 August 2016" and two
+   subsections; "Table of contents" and "First section".

+  

+
+  
+
+  
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:

+
+  
  1. Let current outline target be null. (It holds the element whose
+   outline is being created.)
  2. 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.)
  3. Create a stack to hold elements, which is used to handle nesting. Initialize this stack to
+   empty.
  4. 
+
+    
    Walk over the DOM in tree order, starting with the sectioning
+    content element or sectioning root element at the root of the subtree for
+    which an outline is to be created, and trigger the first relevant step below for each element as
+    the walk enters and exits it.
    
+
+    
    When exiting an element, if that element is the element at the top of the stack
    
+
+      
    The element being exited is a heading content element or an
+      element with a hidden attribute.
    
+
+      
    Pop that element from the stack.
    
+
+     
    If the top of the stack is a heading content element or an element with a
+     hidden attribute
    Do nothing.
    When entering an element with a hidden attribute
    
+
+      
    Push the element being entered onto the stack. (This causes the algorithm to skip that
+      element and any descendants of the element.)
    
+
+     
    When entering a sectioning content element
    
+
+      
    Run these steps:
    
+
+      
    1. 
+
+        
      If current outline target is not null, then:
      
+
+        
      1. If the current section has no heading, create an implied
+         heading and let that be the heading for the current section.
      2. Push current outline target onto the stack.
      
+
+       
    2. Let current outline target be the element that is being
+       entered.
    3. Let current section be a newly created section for the current outline target
+       element.
    4. Associate current outline target with current
+       section.
    5. Let there be a new outline for the new current outline
+       target, initialized with just the new current section as the only
+       section in the outline.
    
+
+     
    When exiting a sectioning content element, if the stack is not empty
    
+
+      
    Run these steps:
    
+
+      
    1. If the current section has no heading, create an implied heading
+       and let that be the heading for the current section.
    2. Pop the top element from the stack, and let the current outline
+       target be that element.
    3. Let current section be the last section in the
+       outline of the current outline target element.
    4. Append the outline of the sectioning content element being
+       exited to the current section. (This does not change which section is
+       the last section in the outline.)
    
+
+     
    When entering a sectioning root element
    
+
+      
    Run these steps:
    
+
+      
    1. If current outline target is not null, push current outline target onto the stack.
    2. Let current outline target be the element that is being
+       entered.
    3. Let current outline target's parent section be current section.
    4. Let current section be a newly created section for the current outline target
+       element.
    5. Let there be a new outline for the new current outline
+       target, initialized with just the new current section as the only
+       section in the outline.
    
+
+     
    When exiting a sectioning root element, if the stack is not empty
    
+
+      
    Run these steps:
    
+
+      
    1. If the current section has no heading, create an implied heading
+       and let that be the heading for the current section.
    2. Let current section be current outline
+       target's parent section.
    3. Pop the top element from the stack, and let the current outline
+       target be that element.
    
+
+     
    When exiting a sectioning content element or a sectioning root
+     element (when the stack is empty)
    
+
+      
    The current outline target is the element being exited,
+      and it is the sectioning content element or a sectioning root
+      element at the root of the subtree for which an outline is being generated.
    
+
+      
    If the current section has no heading, create an implied heading and
+      let that be the heading for the current section.
    
+
+      
    Skip to the next step in the overall set of steps. (The walk is over.)
    
+
+     
    When entering a heading content element
    
+
+      
    If the current section has no heading, let the element being entered be
+      the heading for the current section.
    
+
+      
    If the element being entered is an hgroup element, that
+      hgroup as a whole is a multi-level heading for the current
+      section, with the highest-ranked
+      h1–h6 descendant of the hgroup providing the
+      primary heading for the current section, and with other
+      h1–h6 descendants of the hgroup providing
+      secondary headings for the current section.
    
+
+      
    Otherwise, if the element being entered has a rank equal to or higher than the
+      heading of the last section of the outline of the current outline
+      target, or if the heading of the last section of the outline of the current outline target is an implied heading, then create a new section and append it to the outline of the current outline target 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:
    
+
+      
    1. Let candidate section be current
+       section.
    2. Heading loop: 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.
      
+
+       
    3. Let new candidate section be the section that contains candidate section in
+       the outline of current outline target.
    4. Let candidate section be new candidate
+       section.
    5. Return to the step labeled heading loop.
    
+
+      
    Push the element being entered onto the stack. (This causes the algorithm to skip any
+      descendants of the element.)
    
+
+      
    Recall that h1 has the highest rank, and h6
+      has the lowest rank.
    
+
+     
    Otherwise
    Do nothing.
    
+
+    
    In addition, whenever the walk exits a node, after doing the steps
+    above, if the node is not associated with a section yet,
+    associate the node with the section current
+    section.
    
+
+   
  5. Associate all non-element nodes that are in the subtree for which an outline is being
+   created with the section with which their parent element is
+   associated.
  6. Associate all nodes in the subtree with the heading of the section with which they are associated, if any.

+
+  
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.

+
+  
The outline created for the body element of a Document is the
+  outline of the entire document.

+
+  
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 heading
+  in the body is to be found.

+
+  
The outline depth of a heading content element associated with a section section is the number of sections that are ancestors of section in the
+  outermost outline that section finds itself in when the outlines of its Document's elements are created, plus 1. The
+  outline depth of a heading content element not associated with a section is 1.

+
+  
User agents should provide default headings for sections that do not have explicit section
+  headings.

+
+  

+
+   
Consider the following snippet:

+
+   
<body>
+ <nav>
+  <p><a href="/">Home</a></p>
+ </nav>
+ <p>Hello world.</p>
+ <aside>
+  <p>My cat is cute.</p>
+ </aside>
+</body>

+
+   
Although it contains no headings, this snippet has three sections: a document (the
+   body) with two subsections (a nav and an aside). A user
+   agent could present the outline as follows:

+
+   
  1. Untitled document
+     
    1. Navigation
    2. Sidebar
    
+    

+
+   
These default headings ("Untitled document", "Navigation", "Sidebar") are not specified by
+   this specification, and might vary with the user's language, the page's language, the user's
+   preferences, the user agent implementor's preferences, etc.

+
+  

+
+  

+
+   
The following JavaScript function shows how the tree walk could be implemented. The root argument is the root of the tree to walk (either a sectioning
+   content element or a sectioning root element), and the enter and exit arguments are callbacks that are called with
+   the nodes as they are entered and exited. [JAVASCRIPT]

+
+   
function (root, enter, exit) {
+  var node = root;
+  start: while (node) {
+    enter(node);
+    if (node.firstChild) {
+      node = node.firstChild;
+      continue start;
+    }
+    while (node) {
+      exit(node);
+      if (node == root) {
+        node = null;
+      } else if (node.nextSibling) {
+        node = node.nextSibling;
+        continue start;
+      } else {
+        node = node.parentNode;
+      }
+    }
+  }
+}

+
+  

+
+  
+
+
+  
4.3.11.2 Sample outlines

+
+  
This section is non-normative.

+
+  

+
+   
The following document shows a straight-forward application of the outline
+   algorithm. First, here is the document, which is a book with very short chapters and
+   subsections:

+
+   
<!DOCTYPE HTML>
+<html lang=en>
+<title>The Tax Book (all in one page)</title>
+<h1>The Tax Book</h1>
+<h2>Earning money</h2>
+<p>Earning money is good.</p>
+<h3>Getting a job</h3>
+<p>To earn money you typically need a job.</p>
+<h2>Spending money</h2>
+<p>Spending is what money is mainly used for.</p>
+<h3>Cheap things</h3>
+<p>Buying cheap things often not cost-effective.</p>
+<h3>Expensive things</h3>
+<p>The most expensive thing is often not the most cost-effective either.</p>
+<h2>Investing money</h2>
+<p>You can lend your money to other people.</p>
+<h2>Losing money</h2>
+<p>If you spend money or invest money, sooner or later you will lose money.
+<h3>Poor judgement</h3>
+<p>Usually if you lose money it's because you made a mistake.</p>

+
+   
This book would form the following outline:

+
+   
  1.  The Tax Book
+     
    1.  Earning money
+       
      1.  Getting a job
+       
      
+      
    2.  Spending money
+       
      1.  Cheap things
+        
      2.  Expensive things
+       
      
+      
    3.  Investing money
+      
    4.  Losing money
+       
      1.  Poor judgement
+       
      
+     
    
+   

+
+   
Notice that the title element does not participate in the outline.

+
+  

+
+  

+
+   
Here is a similar document, but this time using section elements to get the same
+   effect:

+
+   
<!DOCTYPE HTML>
+<html lang=en>
+<title>The Tax Book (all in one page)</title>
+<h1>The Tax Book</h1>
+<section>
+ <h1>Earning money</h1>
+ <p>Earning money is good.</p>
+ <section>
+  <h1>Getting a job</h1>
+  <p>To earn money you typically need a job.</p>
+ </section>
+</section>
+<section>
+ <h1>Spending money</h1>
+ <p>Spending is what money is mainly used for.</p>
+ <section>
+  <h1>Cheap things</h1>
+  <p>Buying cheap things often not cost-effective.</p>
+ </section>
+ <section>
+  <h1>Expensive things</h1>
+  <p>The most expensive thing is often not the most cost-effective either.</p>
+ </section>
+</section>
+<section>
+ <h1>Investing money</h1>
+ <p>You can lend your money to other people.</p>
+</section>
+<section>
+ <h1>Losing money</h1>
+ <p>If you spend money or invest money, sooner or later you will lose money.
+ <section>
+  <h1>Poor judgement</h1>
+  <p>Usually if you lose money it's because you made a mistake.</p>
+ </section>
+</section>

+
+   
This book would form the same outline:

+
+   
  1.  The Tax Book
+     
    1.  Earning money
+       
      1.  Getting a job
+       
      
+      
    2.  Spending money
+       
      1.  Cheap things
+        
      2.  Expensive things
+       
      
+      
    3.  Investing money
+      
    4.  Losing money
+       
      1.  Poor judgement
+       
      
+     
    
+   

+
+  

+
+  

+
+   
A document can contain multiple top-level headings:

+
+   
<!DOCTYPE HTML>
+<html lang=en>
+<title>Alphabetic Fruit</title>
+<h1>Apples</h1>
+<p>Pomaceous.</p>
+<h1>Bananas</h1>
+<p>Edible.</p>
+<h1>Carambola</h1>
+<p>Star.</p>

+
+   
This would form the following simple outline consisting of three top-level sections:

+
+   
  1.  Apples
+    
  2.  Bananas
+    
  3.  Carambola
+   

+
+   
Effectively, the body element is split into three.

+
+  

+
+  

+
+   
Mixing both the h1–h6 model and the
+   section/h1 model can lead to some unintuitive results.

+
+   
Consider for example the following, which is just the previous example but with the contents
+   of the (implied) body wrapped in a section:

+
+   
<!DOCTYPE HTML>
+<html lang=en>
+<title>Alphabetic Fruit</title>
+<section>
+ <h1>Apples</h1>
+ <p>Pomaceous.</p>
+ <h1>Bananas</h1>
+ <p>Edible.</p>
+ <h1>Carambola</h1>
+ <p>Star.</p>
+</section>

+
+   
The resulting outline would be:

+
+   
  1.  (untitled page)
+     
    1.  Apples
+      
    2.  Bananas
+      
    3.  Carambola
+     
    
+   

+
+   
This result is described as unintuitive because it results in three subsections even
+   though there's only one section element. Effectively, the section is
+   split into three, just like the implied body element in the previous example.

+
+   
(In this example, "(untitled page)" is the implied heading for the body
+   element, since it has no explicit heading.)

+
+  

+
+  

+
+   
Headings never rise above other sections. Thus, in the following example, the first
+   h1 does not actually describe the page header; it describes the header for the
+   second half of the page:

+
+   
<!DOCTYPE HTML>
+<html lang=en>
+<title>Feathers on The Site of Encyclopedic Knowledge</title>
+<section>
+ <h1>A plea from our caretakers</h1>
+ <p>Please, we beg of you, send help! We're stuck in the server room!</p>
+</section>
+<h1>Feathers</h1>
+<p>Epidermal growths.</p>
+

+
+   
The resulting outline would be:

+
+   
  1.  (untitled page)
+     
    1.  A plea from our caretakers
+     
    
+    
  2.  Feathers
+   

+
+  

+
+  

+
+   
Thus, when an article element starts with a nav block and only later
+   has its heading, the result is that the nav block is not part of the same section as
+   the rest of the article in the outline. For instance, take this document:

+
+   
<!DOCTYPE HTML>
+<html lang="en">
+<title>We're adopting a child! — Ray's blog</title>
+<h1>Ray's blog</h1>
+<article>
+ <header>
+  <nav>
+   <a href="?t=-1d">Yesterday</a>;
+   <a href="?t=-7d">Last week</a>;
+   <a href="?t=-1m">Last month</a>
+  </nav>
+  <h1>We're adopting a child!</h1>
+ </header>
+ <main>
+  <p>As of today, Janine and I have signed the papers to become
+  the proud parents of baby Diane! We've been looking forward to
+  this day for weeks.</p>
+ </main>
+</article>
+</html>

+
+   
The resulting outline would be:

+
+   
  1.  Ray's blog
+     
    1.  Untitled article
+       
      1.  Untitled navigation section
+       
      
+      
    2.  We're adopting a child!
+     
    
+   

+
+   
Also worthy of note in this example is that the header and main
+   elements have no effect whatsoever on the document outline.

+
+  

+
+  

+
+   
The hgroup element can be used for subheadings. For example:

+
+   
<!DOCTYPE HTML>
+<html lang="en">
+<title>Chronotype: CS Student</title>
+<hgroup>
+ <h1> The morning </h1>
+ <h2> 06:00 to 12:00 </h2>
+</hgroup>
+<p>We sleep.</p>
+<hgroup>
+ <h1> The afternoon </h1>
+ <h2> 12:00 to 18:00 </h2>
+</hgroup>
+<p>We study.</p>
+<hgroup>
+ <h2>Additional Commentary</h2>
+ <h3>Because not all this is necessarily true</h3>
+ <h6>Ok it's almost certainly not true</h6>
+</hgroup>
+<p>Yeah we probably play, rather than study.</p>
+<hgroup>
+ <h1> The evening </h1>
+ <h2> 18:00 to 00:00 </h2>
+</hgroup>
+<p>We play.</p>
+<hgroup>
+ <h1> The night </h1>
+ <h2> 00:00 to 06:00 </h2>
+</hgroup>
+<p>We play some more.</p>
+</html>

+
+   
The resulting outline would be:

+
+   
  1.  The morning 06:00 to 12:00
+    
  2.  The afternoon 12:00 to 18:00
+     
    1.  Additional Commentary Because not all this is necessarily true Ok it's almost certainly not true
+     
    
+    
  3.  The evening 18:00 to 00:00
+    
  4.  The night 00:00 to 06:00
+   

+
+   
Exactly how this is represented by user agents, as most interface issues, is left as a matter
+   of implementation preference, but the key part is that the hgroup's descendant
+   h1–h6 elements are what form the element's heading. Thus, the
+   following would be equally valid:

+
+   
  1.  The morning — 06:00 to 12:00
+    
  2.  The afternoon — 12:00 to 18:00
+     
    1.  Additional Commentary — Because not all this is necessarily true — Ok it's almost certainly not true
+     
    
+    
  3.  The evening — 18:00 to 00:00
+    
  4.  The night — 00:00 to 06:00
+   

+
+   
But so would the following:

+
+   
  1.  The morning
+    
  2.  The afternoon
+     
    1.  Additional Commentary
+     
    
+    
  3.  The evening
+    
  4.  The night
+   

+
+   
The following would also be valid, though maybe less practical in most contexts:

+
+   
  1.  
    The morning
+         
     06:00 to 12:00
+    
  2.  
    The afternoon
+         
     12:00 to 18:00
+     
    1.  
       Additional Commentary
+           
       Because not all this is necessarily true
+           
       Ok it's almost certainly not true
+     
    
+    
  3.  
    The evening
+         
     18:00 to 00:00
+    
  4.  
    The night
+         
     00:00 to 06:00
+   

+
+  

+
+
+  
4.3.11.3 Exposing outlines to users

+
+  
User agents are encouraged to expose page outlines to users to aid in navigation. This is
+  especially true for non-visual media, e.g. screen readers.

+
+  
However, to mitigate the difficulties that arise from authors misusing sectioning
+  content, user agents are also encouraged to offer a mode that navigates the page using
+  heading content alone.

+
+  

+
+   
For instance, a user agent could map the arrow keys as follows:

+
+   
Shift+← Left
+    
Go to previous section, including subsections of previous sections
+
+    
Shift+→ Right
+    
Go to next section, including subsections of the current section
+
+    
Shift+↑ Up
+    
Go to parent section of the current section
+
+    
Shift+↓ Down
+    
Go to next section, skipping subsections of the current section
+
+   

+
+   
Plus in addition, the user agent could map the j and
+   k keys to navigating to the previous or next element of heading
+   content, regardless of the section's outline depth and ignoring sections with no
+   headings.

+
+  

+
+
+
+  
4.3.12 Usage summary

+
+  
This section is non-normative.

+
+  
Element
+     Purpose
+    
Example
+   
body
+     The main content of the document.
+    
<!DOCTYPE HTML>
+<html lang="en">
+ <head> <title>Steve Hill's Home Page</title> </head>
+ <body> <p>Hard Trance is My Life.</p> </body>
+</html>

+
+    
article
+     A complete, or self-contained, composition in a document, page, application, or site and that is, in principle, independently distributable or reusable, e.g. in syndication. This could be a forum post, a magazine or newspaper article, a blog entry, a user-submitted comment, an interactive widget or gadget, or any other independent item of content.
+    
<article>
+ <img src="/tumblr_masqy2s5yn1rzfqbpo1_500.jpg" alt="Yellow smiley face with the caption 'masif'">
+ <p>My fave Masif tee so far!</p>
+ <footer>Posted 2 days ago</footer>
+</article>
+<article>
+ <img src="/tumblr_m9tf6wSr6W1rzfqbpo1_500.jpg" alt="">
+ <p>Happy 2nd birthday Masif Saturdays!!!</p>
+ <footer>Posted 3 weeks ago</footer>
+</article>

+
+    
section
+     A generic section of a document or application. A section, in this context, is a thematic grouping of content, typically with a heading.
+    
<h1>Biography</h1>
+<section>
+ <h1>The facts</h1>
+ <p>1500+ shows, 14+ countries</p>
+</section>
+<section>
+ <h1>2010/2011 figures per year</h1>
+ <p>100+ shows, 8+ countries</p>
+</section>

+
+    
nav
+     A section of a page that links to other pages or to parts within the page: a section with navigation links.
+    
<nav>
+ <p><a href="/">Home</a>
+ <p><a href="/biog.html">Bio</a>
+ <p><a href="/discog.html">Discog</a>
+</nav>

+
+    
aside
+     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.
+    
<h1>Music</h1>
+<p>As any burner can tell you, the event has a lot of trance.</p>
+<aside>You can buy the music we played at our <a href="buy.html">playlist page</a>.</aside>
+<p>This year we played a kind of trance that originated in Belgium, Germany, and the Netherlands in the mid 90s.</p>

+
+    
h1–h6
+     A section heading
+    
<h1>The Guide To Music On The Playa</h1>
+<h2>The Main Stage</h2>
+<p>If you want to play on a stage, you should bring one.</p>
+<h2>Amplified Music</h2>
+<p>Amplifiers up to 300W or 90dB are welcome.</p>

+
+    
hgroup
+     The heading of a section, which consists of all the h1–h6 element children of the hgroup element. The element is used to group a set of h1–h6 elements when the heading has multiple levels, such as subheadings, alternative titles, or taglines.
+    
<hgroup>
+ <h1>Burning Music</h1>
+ <h2>The Guide To Music On The Playa</h2>
+</hgroup>
+<section>
+ <hgroup>
+  <h1>Main Stage</h1>
+  <h2>The Fiction Of A Music Festival</h2>
+ </hgroup>
+ <p>If you want to play on a stage, you should bring one.</p>
+</section>
+<section>
+ <hgroup>
+  <h1>Loudness!</h1>
+  <h2>Questions About Amplified Music</h2>
+ </hgroup>
+ <p>Amplifiers up to 300W or 90dB are welcome.</p>
+</section>

+
+    
header
+     A group of introductory or navigational aids.
+    
<article>
+ <header>
+  <h1>Hard Trance is My Life</h1>
+  <p>By DJ Steve Hill and Technikal</p>
+ </header>
+ <p>The album with the amusing punctuation has red artwork.</p>
+</article>

+
+    
footer
+     A footer for its nearest ancestor sectioning content or sectioning root element. A footer typically contains information about its section such as who wrote it, links to related documents, copyright data, and the like.
+    
<article>
+ <h1>Hard Trance is My Life</h1>
+ <p>The album with the amusing punctuation has red artwork.</p>
+ <footer>
+  <p>Artists: DJ Steve Hill and Technikal</p>
+ </footer>
+</article>

+
+  

+
+
+  
4.3.12.1 Article or section?

+
+  
This section is non-normative.

+
+  
A section forms part of something else. An article is its own thing.
+  But how does one know which is which? Mostly the real answer is "it depends on author intent".

+
+  
For example, one could imagine a book with a "Granny Smith" chapter that just said "These
+  juicy, green apples make a great filling for apple pies."; that would be a section
+  because there'd be lots of other chapters on (maybe) other kinds of apples.

+
+  
On the other hand, one could imagine a tweet or reddit comment or tumblr post or newspaper
+  classified ad that just said "Granny Smith. These juicy, green apples make a great filling for
+  apple pies."; it would then be articles because that was the whole thing.

+
+  
A comment on an article is not part of the article on which it is commenting,
+  therefore it is its own article.

+
+
+
+  
4.4 Grouping content

+
+  
4.4.1 The p element

+
+  
Categories:
Flow content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
A p element's end tag can be omitted if the
+   p element is immediately followed by an address, article,
+   aside, blockquote, details, div, dl,
+   fieldset, figcaption, figure, footer, form, h1, h2,
+   h3, h4, h5, h6, header,
+   hgroup, hr, main, menu, nav,
+   ol, p, pre, section, table, or
+   ul element, or if there is no more content in the parent element and the parent
+   element is an HTML element that is not an a,
+   audio, del, ins, map, noscript,
+   or video element, or an autonomous custom element.
Content attributes:
Global attributes
DOM interface:

+    
[HTMLConstructor]
+interface HTMLParagraphElement : HTMLElement {
+  // also has obsolete members
+};

+   

+
+  
The p element represents a paragraph.

+
+  
While paragraphs are usually represented in visual media by blocks of text that
+  are physically separated from adjacent blocks through blank lines, a style sheet or user agent
+  would be equally justified in presenting paragraph breaks in a different manner, for instance
+  using inline pilcrows (¶).

+
+  

+   
The following examples are conforming HTML fragments:

+   
<p>The little kitten gently seated herself on a piece of
+carpet. Later in her life, this would be referred to as the time the
+cat sat on the mat.</p>

+   
<fieldset>
+ <legend>Personal information</legend>
+ <p>
+   <label>Name: <input name="n"></label>
+   <label><input name="anon" type="checkbox"> Hide from other users</label>
+ </p>
+ <p><label>Address: <textarea name="a"></textarea></label></p>
+</fieldset>

+   
<p>There was once an example from Femley,<br>
+Whose markup was of dubious quality.<br>
+The validator complained,<br>
+So the author was pained,<br>
+To move the error from the markup to the rhyming.</p>

+  

+
+  
The p element should not be used when a more specific element is more
+  appropriate.

+
+  

+
+   
The following example is technically correct:

+
+
<section>
+ <!-- ... -->
+ <p>Last modified: 2001-04-23</p>
+ <p>Author: fred@example.com</p>
+</section>

+
+   
However, it would be better marked-up as:

+
+
<section>
+ <!-- ... -->
+ <footer>Last modified: 2001-04-23</footer>
+ <address>Author: fred@example.com</address>
+</section>

+
+   
Or:

+
+
<section>
+ <!-- ... -->
+ <footer>
+  <p>Last modified: 2001-04-23</p>
+  <address>Author: fred@example.com</address>
+ </footer>
+</section>

+
+  

+
+  

+
+   
List elements (in particular, ol and ul elements) cannot be children
+   of p elements. When a sentence contains a bulleted list, therefore, one might wonder
+   how it should be marked up.

+
+   

+    
For instance, this fantastic sentence has bullets relating to

+    
  • wizards,
+     
  • faster-than-light travel, and
+     
  • telepathy,
+    

+    
and is further discussed below.

+   

+
+   
The solution is to realize that a paragraph, in HTML terms, is not a
+   logical concept, but a structural one. In the fantastic example above, there are actually
+   five paragraphs as defined by this specification: one
+   before the list, one for each bullet, and one after the list.

+
+   

+
+    
The markup for the above example could therefore be:

+
+    
<p>For instance, this fantastic sentence has bullets relating to</p>
+<ul>
+ <li>wizards,
+ <li>faster-than-light travel, and
+ <li>telepathy,
+</ul>
+<p>and is further discussed below.</p>

+
+   

+
+   
Authors wishing to conveniently style such "logical" paragraphs consisting of multiple
+   "structural" paragraphs can use the div element instead of the p
+   element.

+
+   

+
+    
Thus for instance the above example could become the following:

+
+    
<div>For instance, this fantastic sentence has bullets relating to
+<ul>
+ <li>wizards,
+ <li>faster-than-light travel, and
+ <li>telepathy,
+</ul>
+and is further discussed below.</div>

+
+    
This example still has five structural paragraphs, but now the author can style just the
+    div instead of having to consider each part of the example separately.

+
+   

+
+  

+
+
+
+  
4.4.2 The hr element

+
+  
Categories:
Flow content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
DOM interface:

+    
[HTMLConstructor]
+interface HTMLHRElement : HTMLElement {
+  // also has obsolete members
+};

+   

+
+  
The hr element represents a paragraph-level thematic
+  break, e.g. a scene change in a story, or a transition to another topic within a section of a
+  reference book.

+
+  

+
+   
The following fictional extract from a project manual shows two sections that use the
+   hr element to separate topics within the section.

+
+   
<section>
+ <h1>Communication</h1>
+ <p>There are various methods of communication. This section
+ covers a few of the important ones used by the project.</p>
+ <hr>
+ <p>Communication stones seem to come in pairs and have mysterious
+ properties:</p>
+ <ul>
+  <li>They can transfer thoughts in two directions once activated
+  if used alone.</li>
+  <li>If used with another device, they can transfer one's
+  consciousness to another body.</li>
+  <li>If both stones are used with another device, the
+  consciousnesses switch bodies.</li>
+ </ul>
+ <hr>
+ <p>Radios use the electromagnetic spectrum in the meter range and
+ longer.</p>
+ <hr>
+ <p>Signal flares use the electromagnetic spectrum in the
+ nanometer range.</p>
+</section>
+<section>
+ <h1>Food</h1>
+ <p>All food at the project is rationed:</p>
+ <dl>
+  <dt>Potatoes</dt>
+  <dd>Two per day</dd>
+  <dt>Soup</dt>
+  <dd>One bowl per day</dd>
+ </dl>
+ <hr>
+ <p>Cooking is done by the chefs on a set rotation.</p>
+</section>

+
+   
There is no need for an hr element between the sections themselves, since the
+   section elements and the h1 elements imply thematic changes
+   themselves.

+
+  

+
+  

+
+   
The following extract from Pandora's Star by Peter F. Hamilton shows two
+   paragraphs that precede a scene change and the paragraph that follows it. The scene change,
+   represented in the printed book by a gap containing a solitary centered star between the second
+   and third paragraphs, is here represented using the hr element.

+
+   
+
+   
<p>Dudley was ninety-two, in his second life, and fast approaching
+time for another rejuvenation. Despite his body having the physical
+age of a standard fifty-year-old, the prospect of a long degrading
+campaign within academia was one he regarded with dread. For a
+supposedly advanced civilization, the Intersolar Commonwealth could be
+appallingly backward at times, not to mention cruel.</p>
+<p><i>Maybe it won't be that bad</i>, he told himself. The lie was
+comforting enough to get him through the rest of the night's
+shift.</p>
+<hr>
+<p>The Carlton AllLander drove Dudley home just after dawn. Like the
+astronomer, the vehicle was old and worn, but perfectly capable of
+doing its job. It had a cheap diesel engine, common enough on a
+semi-frontier world like Gralmond, although its drive array was a
+thoroughly modern photoneural processor. With its high suspension and
+deep-tread tyres it could plough along the dirt track to the
+observatory in all weather and seasons, including the metre-deep snow
+of Gralmond's winters.</p>

+
+  

+
+  
The hr element does not affect the document's
+  outline.

+
+
+  
4.4.3 The pre element

+
+  
Categories:
Flow content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:

+    
[HTMLConstructor]
+interface HTMLPreElement : HTMLElement {
+  // also has obsolete members
+};

+   

+
+  
The pre element represents a block of preformatted text, in which
+  structure is represented by typographic conventions rather than by elements.

+
+  
In the HTML syntax, a leading newline character immediately following
+  the pre element start tag is stripped.

+
+  
Some examples of cases where the pre element could be used:

+
+  
  • 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.

+
+  
Authors are encouraged to consider how preformatted text will be experienced when
+  the formatting is lost, as will be the case for users of speech synthesizers, braille displays,
+  and the like. For cases like ASCII art, it is likely that an alternative presentation, such as a
+  textual description, would be more universally accessible to the readers of the document.

+
+  
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.

+
+  
+
+  
This element has rendering requirements involving the
+  bidirectional algorithm.

+
+  
+
+  

+
+   
In the following snippet, a sample of computer code is presented.

+
+   
<p>This is the <code>Panel</code> constructor:</p>
+<pre><code>function Panel(element, canClose, closeHandler) {
+  this.element = element;
+  this.canClose = canClose;
+  this.closeHandler = function () { if (closeHandler) closeHandler() };
+}</code></pre>

+
+  

+
+  

+
+   
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>

+
+  

+
+
+
+  
4.4.4 The blockquote element

+
+  
Categories:
Flow content.
Sectioning root.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Flow content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
cite — Link to the source of the quotation or more information about the edit
DOM interface:

+
[HTMLConstructor]
+interface HTMLQuoteElement : HTMLElement {
+  [CEReactions] attribute USVString cite;
+};

+    
The HTMLQuoteElement interface is
+    also used by the q element.

+   

+
+  
The blockquote element represents a section that is quoted from
+  another source.

+
+  
Content inside a blockquote must be quoted from another source, whose address, if
+  it has one, may be cited in the cite
+  attribute.

+
+  
If the cite attribute is present, it must be a
+  valid URL potentially surrounded by spaces. To obtain the
+  corresponding citation link, the value of the attribute must be parsed relative to the element's node document. User agents may
+  allow users to follow such citation links, but they are primarily intended for private use (e.g.,
+  by server-side scripts collecting statistics about a site's use of quotations), not for
+  readers.

+
+  
The content of a blockquote may be abbreviated or may have context added in the
+  conventional manner for the text's language.

+
+  

+
+   
For example, in English this is traditionally done using square brackets. Consider a page with
+   the sentence "Jane ate the cracker. She then said she liked apples and fish."; it could be quoted
+   as follows:

+
+   
<blockquote>
+ <p>[Jane] then said she liked [...] fish.</p>
+</blockquote>

+
+  

+
+  
Attribution for the quotation, if any, must be placed outside the blockquote
+  element.
 
+
+  

+
+   
For example, here the attribution is given in a paragraph after the quote:

+
+   
<blockquote>
+ <p>I contend that we are both atheists. I just believe in one fewer
+ god than you do. When you understand why you dismiss all the other
+ possible gods, you will understand why I dismiss yours.</p>
+</blockquote>
+<p>— Stephen Roberts</p>

+
+   
The other examples below show other ways of showing attribution.

+
+  

+
+  
+
+  
The cite IDL attribute must reflect
+  the element's cite content attribute.

+
+  
+
+  

+
+   
Here a blockquote element is used in conjunction with a figure
+   element and its figcaption to clearly relate a quote to its attribution (which is
+   not part of the quote and therefore doesn't belong inside the blockquote
+   itself):

+
+   
<figure>
+ <blockquote>
+  <p>The truth may be puzzling. It may take some work to grapple with.
+  It may be counterintuitive. It may contradict deeply held
+  prejudices. It may not be consonant with what we desperately want to
+  be true. But our preferences do not determine what's true. We have a
+  method, and that method helps us to reach not absolute truth, only
+  asymptotic approaches to the truth — never there, just closer
+  and closer, always finding vast new oceans of undiscovered
+  possibilities. Cleverly designed experiments are the key.</p>
+ </blockquote>
+ <figcaption>Carl Sagan, in "<cite>Wonder and Skepticism</cite>", from
+ the <cite>Skeptical Inquirer</cite> Volume 19, Issue 1 (January-February
+ 1995)</figcaption>
+</figure>

+
+  

+
+  

+
+   
This next example shows the use of cite alongside blockquote:

+
+   
<p>His next piece was the aptly named <cite>Sonnet 130</cite>:</p>
+<blockquote cite="https://quotes.example.org/s/sonnet130.html">
+  <p>My mistress' eyes are nothing like the sun,<br>
+  Coral is far more red, than her lips red,<br>
+  ...

+
+  

+
+  

+
+   
This example shows how a forum post could use blockquote to show what post a user
+   is replying to. The article element is used for each post, to mark up the
+   threading.

+
+   
<article>
+ <h1><a href="https://bacon.example.com/?blog=109431">Bacon on a crowbar</a></h1>
+ <article>
+  <header><strong>t3yw</strong> 12 points 1 hour ago</header>
+  <p>I bet a narwhal would love that.</p>
+  <footer><a href="?pid=29578">permalink</a></footer>
+  <article>
+   <header><strong>greg</strong> 8 points 1 hour ago</header>
+   <blockquote><p>I bet a narwhal would love that.</p></blockquote>
+   <p>Dude narwhals don't eat bacon.</p>
+   <footer><a href="?pid=29579">permalink</a></footer>
+   <article>
+    <header><strong>t3yw</strong> 15 points 1 hour ago</header>
+    <blockquote>
+     <blockquote><p>I bet a narwhal would love that.</p></blockquote>
+     <p>Dude narwhals don't eat bacon.</p>
+    </blockquote>
+    <p>Next thing you'll be saying they don't get capes and wizard
+    hats either!</p>
+    <footer><a href="?pid=29580">permalink</a></footer>
+    <article>
+     <article>
+      <header><strong>boing</strong> -5 points 1 hour ago</header>
+      <p>narwhals are worse than ceiling cat</p>
+      <footer><a href="?pid=29581">permalink</a></footer>
+     </article>
+    </article>
+   </article>
+  </article>
+  <article>
+   <header><strong>fred</strong> 1 points 23 minutes ago</header>
+   <blockquote><p>I bet a narwhal would love that.</p></blockquote>
+   <p>I bet they'd love to peel a banana too.</p>
+   <footer><a href="?pid=29582">permalink</a></footer>
+  </article>
+ </article>
+</article>

+
+  

+
+  

+
+   
This example shows the use of a blockquote for short snippets, demonstrating that
+   one does not have to use p elements inside blockquote elements:

+
+   
<p>He began his list of "lessons" with the following:</p>
+<blockquote>One should never assume that his side of
+the issue will be recognized, let alone that it will
+be conceded to have merits.</blockquote>
+<p>He continued with a number of similar points, ending with:</p>
+<blockquote>Finally, one should be prepared for the threat
+of breakdown in negotiations at any given moment and not
+be cowed by the possibility.</blockquote>
+<p>We shall now discuss these points...

+
+  

+
+  
Examples of how to represent a conversation are shown
+  in a later section; it is not appropriate to use the cite and blockquote
+  elements for this purpose.

+
+
+
+  
4.4.5 The ol element

+
+  
Categories:
Flow content.
If the element's children include at least one li element: Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Zero or more li and script-supporting elements.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
reversed — Number the list backwards
start — Starting value of the list
type — Kind of list marker
DOM interface:

+
[HTMLConstructor]
+interface HTMLOListElement : HTMLElement {
+  [CEReactions] attribute boolean reversed;
+  [CEReactions] attribute long start;
+  [CEReactions] attribute DOMString type;
+
+  // also has obsolete members
+};

+   

+
+  
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, ...).
Support: ol-reversedChrome for Android 57+Chrome 20+UC Browser for Android 11.4+iOS Safari 6.0+Firefox 18+IE NoneSamsung Internet 4+Opera Mini all+Android Browser 4.4+Edge NoneSafari 6.1+Opera 12.1+
Source: caniuse.com

+
+  
The start attribute, if present, must be a
+  valid integer. It is used to determine the starting
+  value of the list.

+
+  
+
+  
+
+  
An ol element has a starting value, which is
+  an integer determined as follows:

+
+  
  1. 
+    
    If the ol element has a start attribute,
+    then:
    
+
+    
    1. Let parsed be the result of parsing
+     the value of the attribute as an integer.
    2. If parsed is not an error, then return parsed.
    
+   
  2. If the ol element has a reversed
+   attribute, then return the number of owned li
+   elements.
  3. Return 1.

+
+  
+
+  
The type attribute can be used to specify the kind
+  of marker to use in the list, in the cases where that matters (e.g. because items are to be
+  referenced by their number/letter). The attribute, if specified, must have a value that is a
+  case-sensitive match for one of the characters given in the first cell of one of the
+  rows of the following table. The type
+  attribute represents the state given in the cell in the second column of the row whose first cell
+  matches the attribute's value; if none of the cells match, or if the attribute is omitted, then
+  the attribute represents the decimal
+  state.

+
+  
Keyword
+     State
+     Description
+     Examples for values 1-3 and 3999-4001
+   
1 (U+0031)
+     decimal
+     Decimal numbers
+     1. 2. 3. ... 3999. 4000. 4001. ...
+    
a (U+0061)
+     lower-alpha
+     Lowercase latin alphabet
+     a. b. c. ... ewu. ewv. eww. ...
+    
A (U+0041)
+     upper-alpha
+     Uppercase latin alphabet
+     A. B. C. ... EWU. EWV. EWW. ...
+    
i (U+0069)
+     lower-roman
+     Lowercase roman numerals
+     i. ii. iii. ... mmmcmxcix. i̅v̅. i̅v̅i. ...
+    
I (U+0049)
+     upper-roman
+     Uppercase roman numerals
+     I. II. III. ... MMMCMXCIX. I̅V̅. I̅V̅I. ...
+  

+
+  
+
+  
User agents should render the items of the list in a manner consistent with the state of the
+  type attribute of the ol element. Numbers less than
+  or equal to zero should always use the decimal system regardless of the type attribute.

+
+  
For CSS user agents, a mapping for this attribute to the
+  'list-style-type' CSS property is given in the rendering
+  section (the mapping is straightforward: the states above have the same names as their
+  corresponding CSS values).

+
+  
+
+  
It is possible to redefine the default CSS list styles used to implement this
+  attribute in CSS user agents; doing so will affect how list items are rendered.

+
+  
+
+  
+
+  
The reversed and
+  type IDL attributes must reflect the
+  respective content attributes of the same name.

+
+  
The start IDL attribute must reflect
+  the content attribute of the same name, with a default value of 1.

+
+  
This means that the start IDL attribute does
+  not necessarily match the list's starting value, in cases
+  where the start content attribute is omitted and the reversed content attribute is specified.

+
+  
+
+  

+
+   
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>

+
+  

+
+
+  
4.4.6 The ul element

+
+  
Categories:
Flow content.
If the element's children include at least one li element: Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Zero or more li and script-supporting elements.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:

+    
[HTMLConstructor]
+interface HTMLUListElement : HTMLElement {
+  // also has obsolete members
+};

+   

+
+  
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>

+
+  

+
+
+  
4.4.7 The li element

+
+  
Categories:
None.
Contexts in which this element can be used:
Inside ol elements.
Inside ul elements.
Inside menu elements whose type attribute is in the toolbar state.
Content model:
Flow content.
Tag omission in text/html:
An li element's end tag can be omitted if the
+   li element is immediately followed by another li element or if there is
+   no more content in the parent element.
Content attributes:
Global attributes
If the element is not a child of an ul or menu element: value — Ordinal value of the list item
DOM interface:

+
[HTMLConstructor]
+interface HTMLLIElement : HTMLElement {
+  [CEReactions] attribute long value;
+
+  // also has obsolete members
+};

+   

+
+  
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. It is used to determine the ordinal value of the list
+  item, when the li's list owner is an ol element.

+
+  
+
+  

+
+  
Any element whose computed value of 'display' is 'list-item' has a
+  list owner, which is determined as follows:

+
+  
  1. If the element is not being rendered, return null; the element has no
+   list owner.
    
+
+   
  2. Let ancestor be the element's parent.
  3. If the element has an ol, ul, or menu ancestor, set
+   ancestor to the closest such ancestor element.
  4. 
+    
    Return the closest inclusive ancestor of ancestor that produces a CSS box.
    
+
+    
    Such an element will always exist, as at the very least the document
+    element will always produce a CSS box.
    
+   

+
+  
To determine the ordinal value of each element owned by a given list
+  owner owner, perform the following steps:

+
+  
  1. Let i be 1.
  2. If owner is an ol element, let numbering be
+   owner's starting value. Otherwise, let
+   numbering be 1.
  3. Loop: If i is greater than the number of list items that owner owns, then abort this algorithm; all
+   of owner's owned list items have been assigned ordinal values.
  4. Let item be the ith of owner's owned list items, in tree order.
    
+
+   
  5. 
+    
    If item is an li element that has a value attribute, then:
    
+
+    
    1. Let parsed be the result of parsing
+     the value of the attribute as an integer.
    2. If parsed is not an error, then set numbering to
+     parsed.
    
+   
  6. The ordinal value of item is numbering.
  7. If owner is an ol element, and owner has a reversed attribute, decrement numbering by 1;
+   otherwise, increment numbering by 1.
  8. Increment i by 1.
  9. Go to the step labeled loop.
    
+  

+
+  

+
+  
The value IDL attribute must reflect
+  the value of the value content attribute.

+
+  

+   
The element's value IDL attribute does not directly
+   correspond to its ordinal value; it simply reflects
+   the content attribute. For example, given this list:
+
+   
<ol>
+ <li>Item 1
+ <li value="3">Item 3
+ <li>Item 4
+</ol>

+
+   
The ordinal values are 1, 3, and 4, whereas the value IDL attributes return 0, 3, 0 on getting.

+  

+
+  
+
+  

+
+   
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 figcaption
+   element.

+
+   
<figure>
+ <figcaption>The top 10 movies of all time</figcaption>
+ <ol>
+  <li value="10"><cite>Josie and the Pussycats</cite>, 2001</li>
+  <li value="9"><cite lang="sh">Црна мачка, бели мачор</cite>, 1998</li>
+  <li value="8"><cite>A Bug's Life</cite>, 1998</li>
+  <li value="7"><cite>Toy Story</cite>, 1995</li>
+  <li value="6"><cite>Monsters, Inc</cite>, 2001</li>
+  <li value="5"><cite>Cars</cite>, 2006</li>
+  <li value="4"><cite>Toy Story 2</cite>, 1999</li>
+  <li value="3"><cite>Finding Nemo</cite>, 2003</li>
+  <li value="2"><cite>The Incredibles</cite>, 2004</li>
+  <li value="1"><cite>Ratatouille</cite>, 2007</li>
+ </ol>
+</figure>

+
+   
The markup could also be written as follows, using the reversed attribute on the ol element:

+
+   
<figure>
+ <figcaption>The top 10 movies of all time</figcaption>
+ <ol reversed>
+  <li><cite>Josie and the Pussycats</cite>, 2001</li>
+  <li><cite lang="sh">Црна мачка, бели мачор</cite>, 1998</li>
+  <li><cite>A Bug's Life</cite>, 1998</li>
+  <li><cite>Toy Story</cite>, 1995</li>
+  <li><cite>Monsters, Inc</cite>, 2001</li>
+  <li><cite>Cars</cite>, 2006</li>
+  <li><cite>Toy Story 2</cite>, 1999</li>
+  <li><cite>Finding Nemo</cite>, 2003</li>
+  <li><cite>The Incredibles</cite>, 2004</li>
+  <li><cite>Ratatouille</cite>, 2007</li>
+ </ol>
+</figure>

+  

+
+  
While it is conforming to include heading elements (e.g. h1) inside
+  li elements, it likely does not convey the semantics that the author intended. A
+  heading starts a new section, so a heading in a list implicitly splits the list into spanning
+  multiple sections.

+
+
+
+  
4.4.8 The dl element

+
+  
Categories:
Flow content.
If the element's children include at least one name-value group: Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Either: Zero or more groups each consisting of one or more dt elements followed by one or more dd elements, optionally intermixed with script-supporting elements.
Or: One or more div elements, optionally intermixed with script-supporting elements.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:

+    
[HTMLConstructor]
+interface HTMLDListElement : HTMLElement {
+  // also has obsolete members
+};

+   

+
+  
The dl element represents an association list consisting of zero or
+  more name-value groups (a description list). A name-value group consists of one or more names
+  (dt elements, possibly as children of a div element child) followed by
+  one or more values (dd elements, possibly as children of a div element
+  child), ignoring any nodes other than dt and dd element children, and
+  dt and dd elements that are children of div element
+  children. Within a single dl element, there should not be more than one
+  dt element for each name.

+
+  
Name-value groups may be terms and definitions, metadata topics and values, questions and
+  answers, 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.

+
+  
In order to annotate groups with microdata attributes, or other global
+  attributes that apply to whole groups, or just for styling purposes, each group in a
+  dl element can be wrapped in a div element. This does not change the
+  semantics of the dl element.

+
+  
+
+  
The name-value groups of a dl element dl are determined using the
+  following algorithm. A name-value group has a name (a list of dt elements, initially
+  empty) and a value (a list of dd elements, initially empty).

+
+  
  1. Let groups be an empty list of name-value groups.
  2. Let current be a new name-value group.
  3. Let seenDd be false.
  4. Let child be dl's first child.
  5. Let grandchild be null.
  6. 
+    
    While child is not null:
    
+
+    
    1. 
+      
      If child is a div element, then:
      
+
+      
      1. Let grandchild be child's first child.
      2. 
+        
        While grandchild is not null:
        
+
+        
        1. Process dt or dd for
+         grandchild.
        2. Set grandchild to grandchild's next
+         sibling.
        
+       
      
+     
    2. Otherwise, process dt or dd for
+     child.
    3. Set child to child's next sibling.
    
+   
  7. If current is not empty, then append current to
+   groups.
  8. Return groups.

+
+  
To process dt or dd for a node node means to
+  follow these steps:

+
+  
  1. Let groups, current, and seenDd be the same variables as
+   those of the same name in the algorithm that invoked these steps.
  2. 
+    
    If node is a dt element, then:
    
+
+    
    1. If seenDd is true, then append current to groups, set
+     current to a new name-value group, and set seenDd to false.
    2. Append node to current's name.
    
+   
  3. Otherwise, if node is a dd element, then append node to
+   current's value and set seenDd to true.

+
+  
When a name-value group has an empty list as name or value, 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"). This example also uses the
+   div element around the groups of dt and dd element, to aid
+   with styling.

+
+   
<dl>
+ <div>
+  <dt> Last modified time </dt>
+  <dd> 2004-12-23T23:33Z </dd>
+ </div>
+ <div>
+  <dt> Recommended update interval </dt>
+  <dd> 60s </dd>
+ </div>
+ <div>
+  <dt> Authors </dt>
+  <dt> Editors </dt>
+  <dd> Robert Rothman </dd>
+  <dd> Daniel Jackson </dd>
+ </div>
+</dl>

+  

+
+  

+
+   
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.

+
+   
<dl>
+ <dt><dfn>Apartment</dfn>, n.</dt>
+ <dd>An execution context grouping one or more threads with one or
+ more COM objects.</dd>
+ <dt><dfn>Flat</dfn>, n.</dt>
+ <dd>A deflated tire.</dd>
+ <dt><dfn>Home</dfn>, n.</dt>
+ <dd>The user's login directory.</dd>
+</dl>

+  

+
+  

+
+   
This example uses microdata attributes in a dl element, together
+   with the div element, to annotate the ice cream desserts at a French restaurant.

+   
+
+   
<dl>
+ <div itemscope itemtype="http://schema.org/Product">
+  <dt itemprop="name">Café ou Chocolat Liégeois
+  <dd itemprop="offers" itemscope itemtype="http://schema.org/Offer">
+   <span itemprop="price">3.50</span>
+   <data itemprop="priceCurrency" value="EUR">€</data>
+  <dd itemprop="description">
+   2 boules Café ou Chocolat, 1 boule Vanille, sause café ou chocolat, chantilly
+ </div>
+
+ <div itemscope itemtype="http://schema.org/Product">
+  <dt itemprop="name">Américaine
+  <dd itemprop="offers" itemscope itemtype="http://schema.org/Offer">
+   <span itemprop="price">3.50</span>
+   <data itemprop="priceCurrency" value="EUR">€</data>
+  <dd itemprop="description">
+   1 boule Crème brûlée, 1 boule Vanille, 1 boule Caramel, chantilly
+ </div>
+</dl>

+
+   
Without the div element the markup would need to use the itemref attribute to link the data in the dd elements
+   with the item, as follows.

+
+   
<dl>
+ <dt itemscope itemtype="http://schema.org/Product" itemref="1-offer 1-description">
+  <span itemprop="name">Café ou Chocolat Liégeois</span>
+ <dd id="1-offer" itemprop="offers" itemscope itemtype="http://schema.org/Offer">
+  <span itemprop="price">3.50</span>
+  <data itemprop="priceCurrency" value="EUR">€</data>
+ <dd id="1-description" itemprop="description">
+  2 boules Café ou Chocolat, 1 boule Vanille, sause café ou chocolat, chantilly
+
+ <dt itemscope itemtype="http://schema.org/Product" itemref="2-offer 2-description">
+  <span itemprop="name">Américaine</span>
+ <dd id="2-offer" itemprop="offers" itemscope itemtype="http://schema.org/Offer">
+  <span itemprop="price">3.50</span>
+  <data itemprop="priceCurrency" value="EUR">€</data>
+ <dd id="2-description" itemprop="description">
+  1 boule Crème brûlée, 1 boule Vanille, 1 boule Caramel, chantilly
+</dl>

+
+  

+
+  
The dl element is inappropriate for marking up dialogue. See some examples of how to mark up dialogue.

+
+
+
+  
4.4.9 The dt element

+
+  
Categories:
None.
Contexts in which this element can be used:
Before dd or dt elements inside dl elements.
Before dd or dt elements inside div elements that are children of a dl element.
Content model:
Flow content, but with no header, footer, sectioning content, or heading content descendants.
Tag omission in text/html:
A dt element's end tag can be omitted if the
+   dt element is immediately followed by another dt element or a
+   dd element.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The dt element represents the term, or name, part of a
+  term-description group in a description list (dl 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.

+
+  

+
+   
This example shows a list of frequently asked questions (a FAQ) marked up using the
+   dt element for questions and the dd element for answers.

+
+   
<article>
+ <h1>FAQ</h1>
+ <dl>
+  <dt>What do we want?</dt>
+  <dd>Our data.</dd>
+  <dt>When do we want it?</dt>
+  <dd>Now.</dd>
+  <dt>Where is it?</dt>
+  <dd>We are not sure.</dd>
+ </dl>
+</article>

+
+  

+
+
+
+  
4.4.10 The dd element

+
+  
Categories:
None.
Contexts in which this element can be used:
After dt or dd elements inside dl elements.
After dt or dd elements inside div elements that are children of a dl element.
Content model:
Flow content.
Tag omission in text/html:
A dd element's end tag can be omitted if the
+   dd element is immediately followed by another dd element or a
+   dt element, or if there is no more content in the parent element.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The dd element represents the description, definition, or value, part
+  of a term-description group in a description list (dl element).

+
+  

+
+   
A dl can be used to define a vocabulary list, like in a dictionary. In the
+   following example, each entry, given by a dt with a dfn, has several
+   dds, showing the various parts of the definition.

+
+   
+   
<dl>
+ <dt><dfn>happiness</dfn></dt>
+ <dd class="pronunciation">/'hæ p. nes/</dd>
+ <dd class="part-of-speech"><i><abbr>n.</abbr></i></dd>
+ <dd>The state of being happy.</dd>
+ <dd>Good fortune; success. <q>Oh <b>happiness</b>! It worked!</q></dd>
+ <dt><dfn>rejoice</dfn></dt>
+ <dd class="pronunciation">/ri jois'/</dd>
+ <dd><i class="part-of-speech"><abbr>v.intr.</abbr></i> To be delighted oneself.</dd>
+ <dd><i class="part-of-speech"><abbr>v.tr.</abbr></i> To cause one to be delighted.</dd>
+</dl>

+  

+
+
+  
4.4.11 The figure element
Spec bugs: 25552

+
+  
Categories:
Flow content.
Sectioning root.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Either: One figcaption element followed by flow content.
Or: Flow content followed by one figcaption element.
Or: Flow content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

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

+
+  
Self-contained in this context does not necessarily mean independent. For example,
+  each sentence in a paragraph is self-contained; an image that is part of a sentence would be
+  inappropriate for figure, but an entire sentence made of images would be fitting.

+
+  
The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc.

+
+  

+
+   
When a figure is referred to from the main content of the document by identifying
+   it by its caption (e.g. by figure number), it enables such content to be easily moved away from
+   that primary content, e.g. to the side of the page, to dedicated pages, or to an appendix, without
+   affecting the flow of the document.

+
+   
If a figure element is referenced by its relative position, e.g. "in the
+   photograph above" or "as the next figure shows", then moving the figure would disrupt the page's
+   meaning. Authors are encouraged to consider using labels to refer to figures, rather than using
+   such relative references, so that the page can easily be restyled without affecting the page's
+   meaning.

+
+  

+
+  
The first figcaption element child of the element, if
+  any, represents the caption of the figure element's contents. If there is no child
+  figcaption element, then there is no caption.

+
+  
A figure element's contents are part of the surrounding flow. If the purpose of
+  the page is to display the figure, for example a photograph on an image sharing site, the
+  figure and figcaption elements can be used to explicitly provide a
+  caption for that figure. For content that is only tangentially related, or that serves a separate
+  purpose than the surrounding flow, the aside element should be used (and can itself
+  wrap a figure). For example, a pull quote that repeats content from an
+  article would be more appropriate in an aside than in a
+  figure, because it isn't part of the content, it's a repetition of the content for
+  the purposes of enticing readers or highlighting key topics.

+
+  

+
+   
This example shows the figure element to mark up a code listing.

+
+   
<p>In <a href="#l4">listing 4</a> we see the primary core interface
+API declaration.</p>
+<figure id="l4">
+ <figcaption>Listing 4. The primary core interface API declaration.</figcaption>
+ <pre><code>interface PrimaryCore {
+ boolean verifyDataLine();
+ void sendData(in sequence&lt;byte> data);
+ void initSelfDestruct();
+}</code></pre>
+</figure>
+<p>The API is designed to use UTF-8.</p>

+
+  

+
+  

+
+   
Here we see a figure element to mark up a photo that is the main content of the
+   page (as in a gallery).

+
+   
<!DOCTYPE HTML>
+<html lang="en">
+<title>Bubbles at work — My Gallery™</title>
+<figure>
+ <img src="bubbles-work.jpeg"
+      alt="Bubbles, sitting in his office chair, works on his
+           latest project intently.">
+ <figcaption>Bubbles at work</figcaption>
+</figure>
+<nav><a href="19414.html">Prev</a> — <a href="19416.html">Next</a></nav>

+
+  

+
+  

+
+   
In this example, we see an image that is not a figure, as well as an image and a
+   video that are. The first image is literally part of the example's second sentence, so it's not a
+   self-contained unit, and thus figure would be inappropriate.

+
+   
<h2>Malinko's comics</h2>
+
+<p>This case centered on some sort of "intellectual property"
+infringement related to a comic (see Exhibit A). The suit started
+after a trailer ending with these words:
+
+<blockquote>
+ <img src="promblem-packed-action.png" alt="ROUGH COPY! Promblem-Packed Action!">
+</blockquote>
+
+<p>...was aired. A lawyer, armed with a Bigger Notebook, launched a
+preemptive strike using snowballs. A complete copy of the trailer is
+included with Exhibit B.
+
+<figure>
+ <img src="ex-a.png" alt="Two squiggles on a dirty piece of paper.">
+ <figcaption>Exhibit A. The alleged <cite>rough copy</cite> comic.</figcaption>
+</figure>
+
+<figure>
+ <video src="ex-b.mov"></video>
+ <figcaption>Exhibit B. The <cite>Rough Copy</cite> trailer.</figcaption>
+</figure>
+
+<p>The case was resolved out of court.

+
+  

+
+  

+
+   
Here, a part of a poem is marked up using figure.

+
+   
<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>
+ <figcaption><cite>Jabberwocky</cite> (first verse). Lewis Carroll, 1832-98</figcaption>
+</figure>

+
+  

+
+  

+
+   
In this example, which could be part of a much larger work discussing a castle, nested
+   figure elements are used to provide both a group caption and individual captions for
+   each figure in the group:

+
+   
<figure>
+ <figcaption>The castle through the ages: 1423, 1858, and 1999 respectively.</figcaption>
+ <figure>
+  <figcaption>Etching. Anonymous, ca. 1423.</figcaption>
+  <img src="castle1423.jpeg" alt="The castle has one tower, and a tall wall around it.">
+ </figure>
+ <figure>
+  <figcaption>Oil-based paint on canvas. Maria Towle, 1858.</figcaption>
+  <img src="castle1858.jpeg" alt="The castle now has two towers and two walls.">
+ </figure>
+ <figure>
+  <figcaption>Film photograph. Peter Jankle, 1999.</figcaption>
+  <img src="castle1999.jpeg" alt="The castle lies in ruins, the original tower all that remains in one piece.">
+ </figure>
+</figure>

+
+  

+
+  

+
+   
The previous example could also be more succinctly written as follows (using title attributes in place of the nested
+   figure/figcaption pairs):

+
+   
<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.">
+ <figcaption>The castle through the ages: 1423, 1858, and 1999 respectively.</figcaption>
+</figure>

+
+  

+
+  

+
+   
The figure is sometimes referenced only implicitly from the content:

+
+   
+
+   
<article>
+ <h1>Fiscal negotiations stumble in Congress as deadline nears</h1>
+ <figure>
+  <img src="obama-reid.jpeg" alt="Obama and Reid sit together smiling in the Oval Office.">
+  <figcaption>Barack Obama and Harry Reid. White House press photograph.</figcaption>
+ </figure>
+ <p>Negotiations in Congress to end the fiscal impasse sputtered on Tuesday, leaving both chambers
+ grasping for a way to reopen the government and raise the country's borrowing authority with a
+ Thursday deadline drawing near.</p>
+ ...
+</article>

+
+  

+
+
+  
4.4.12 The figcaption element

+
+  
Categories:
None.
Contexts in which this element can be used:
As the first or last child of a figure element.
Content model:
Flow content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The figcaption element represents a caption or legend for the rest of
+  the contents of the figcaption element's parent figure element, if any.

+
+
+
+  
4.4.13 The main element

+
+  
Categories:
Flow content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Flow content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The main element can be used as a container for the dominant contents of another
+  element. It represents its children.

+
+  
The main element is distinct from the section and
+  article elements in that the main element does not contribute to the
+  document outline.

+
+  
There is no restriction as to the number of main elements in a
+  document. Indeed, there are many cases where it would make sense to have multiple
+  main elements. For example, a page with multiple article elements might
+  need to indicate the dominant contents of each such element.

+
+  

+
+   
In this example, the author has used a presentation where each component of the page is
+   rendered in a box. To wrap the main content of the page (as opposed to the header, the footer,
+   the navigation bar, and a sidebar), the main element is used.

+
+   
<!DOCTYPE html>
+<html lang="en">
+<title>RPG System 17</title>
+<style>
+ header, nav, aside, main, footer {
+   margin: 0.5em; border: thin solid; padding: 0.5em;
+   background: #EFF; color: black; box-shadow: 0 0 0.25em #033;
+ }
+ h1, h2, p { margin: 0; }
+ nav, main { float: left; }
+ aside { float: right; }
+ footer { clear: both; }
+</style>
+<header>
+ <h1>System Eighteen</h1>
+</header>
+<nav>
+ <a href="../16/">← System 17</a>
+ <a href="../18/">RPXIX →</a>
+</nav>
+<aside>
+ <p>This system has no HP mechanic, so there's no healing.
+</aside>
+<main>
+ <h2>Character creation</h2>
+ <p>Attributes (magic, strength, agility) are purchased at the cost of one point per level.</p>
+ <h2>Rolls</h2>
+ <p>Each encounter, roll the dice for all your skills. If you roll more than the opponent, you win.</p>
+</main>
+<footer>
+ <p>Copyright © 2013
+</footer>
+</html>

+
+  

+
+
+
+  
4.4.14 The div element

+
+  
Categories:
Flow content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
As a child of a dl element.
Content model:
If the element is a child of a dl element: one or more dt elements followed by one or more dd elements, optionally intermixed with script-supporting elements.
If the element is not a child of a dl element: Flow content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:

+    
[HTMLConstructor]
+interface HTMLDivElement : HTMLElement {
+  // also has obsolete members
+};

+   

+
+  
The div element has no special meaning at all. It represents its
+  children. It can be used with the class, lang, and title attributes to mark up
+  semantics common to a group of consecutive elements. It can also be used in a dl
+  element, wrapping groups of dt and dd elements.

+
+  
Authors are strongly encouraged to view the div element as an element
+  of last resort, for when no other element is suitable. Use of more appropriate elements instead of
+  the div element leads to better accessibility for readers and easier maintainability
+  for authors.

+
+  

+
+   
For example, a blog post would be marked up using article, a chapter using
+   section, a page's navigation aids using nav, and a group of form
+   controls using fieldset.

+
+   
On the other hand, div elements can be useful for stylistic purposes or to wrap
+   multiple paragraphs within a section that are all to be annotated in a similar way. In the
+   following example, we see div elements used as a way to set the language of two
+   paragraphs at once, instead of setting the language on the two paragraph elements separately:

+
+   
<article lang="en-US">
+ <h1>My use of language and my cats</h1>
+ <p>My cat's behavior hasn't changed much since her absence, except
+ that she plays her new physique to the neighbors regularly, in an
+ attempt to get pets.</p>
+ <div lang="en-GB">
+  <p>My other cat, coloured black and white, is a sweetie. He followed
+  us to the pool today, walking down the pavement with us. Yesterday
+  he apparently visited our neighbours. I wonder if he recognises that
+  their flat is a mirror image of ours.</p>
+  <p>Hm, I just noticed that in the last paragraph I used British
+  English. But I'm supposed to write in American English. So I
+  shouldn't say "pavement" or "flat" or "colour"...</p>
+ </div>
+ <p>I should say "sidewalk" and "apartment" and "color"!</p>
+</article>

+
+  

+
+
+  
4.5 Text-level semantics

+
+  
4.5.1 The a element

+
+  
Categories:
Flow content.
Phrasing content.
If the element has an href attribute: Interactive content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Transparent, but there must be no interactive content or a element descendants.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
href — Address of the hyperlink
target — Browsing context for hyperlink navigation
download — Whether to download the resource instead of navigating to it, and its file name if so
ping — URLs to ping
rel — Relationship between the location in the document containing the hyperlink and the destination resource
hreflang — Language of the linked resource
type — Hint for the type of the referenced resource
referrerpolicy — Referrer policy for fetches initiated by the element
DOM interface:

+
[HTMLConstructor]
+interface HTMLAnchorElement : HTMLElement {
+  [CEReactions] attribute DOMString target;
+  [CEReactions] attribute DOMString download;
+  [CEReactions] attribute USVString ping;
+  [CEReactions] attribute DOMString rel;
+  [SameObject, PutForwards=value] readonly attribute DOMTokenList relList;
+  [CEReactions] attribute DOMString hreflang;
+  [CEReactions] attribute DOMString type;
+
+  [CEReactions] attribute DOMString text;
+
+  [CEReactions] attribute DOMString referrerPolicy;
+
+  // also has obsolete members
+};
+HTMLAnchorElement implements HTMLHyperlinkElementUtils;

+   

+
+  
If the a element has an href attribute,
+  then it represents a hyperlink (a hypertext anchor) labeled by its
+  contents.

+
+  
+
+  
If the a element has no href attribute,
+  then the element represents a placeholder for where a link might otherwise have been
+  placed, if it had been relevant, consisting of just the element's contents.

+
+  
The target, download, ping,
+  rel, hreflang, type,
+  and referrerpolicy attributes must be omitted
+  if the href attribute is not present.

+
+  
If the itemprop attribute is specified on an a element,
+  then the href attribute must also be specified.

+
+  

+
+   
If a site uses a consistent navigation toolbar on every page, then the link that would
+   normally link to the page itself could be marked up using an a element:

+
+   
<nav>
+ <ul>
+  <li> <a href="/">Home</a> </li>
+  <li> <a href="/news">News</a> </li>
+  <li> <a>Examples</a> </li>
+  <li> <a href="/legal">Legal</a> </li>
+ </ul>
+</nav>

+
+  

+
+  
+
+  
The href, target, download, ping,
+  and referrerpolicy attributes affect what
+  happens when users follow hyperlinks or download hyperlinks created using the a
+  element. The rel, 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.

+
+  
The activation behavior of a elements that create hyperlinks is to run the following steps:

+
+  
  1. If the a element's node document is not fully active, then abort these steps.
  2. If the target of the click event is an img
+   element with an ismap attribute specified, then server-side
+   image map processing must be performed, as follows:
    
+
+    
    1. Let x and y be zero.
    2. If the click event was a real pointing-device-triggered
+     click event on the img element, then set
+     x to the distance in CSS pixels from the left edge of the
+     image to the location of the click, and set y to the distance in CSS pixels from the top edge of the image to the location of the
+     click.
    3. If x is negative, set x to zero.
    4. If y is negative, set y to zero.
    5. Let hyperlink suffix be a U+003F QUESTION MARK character, the value of
+     x expressed as a base-ten integer using ASCII digits, a U+002C COMMA
+     character (,), and the value of y expressed as a base-ten integer using ASCII
+     digits.
    
+
+   
  3. Follow the hyperlink or download the hyperlink created by the a
+   element, as determined by the download attribute
+   and any expressed user preference, passing hyperlink suffix, if the steps above
+   defined it.

+
+  
+
+  
a . text

+
+    
Same as textContent.

+
+   

+
+  
+
+  
The IDL attributes download, ping, target,
+  rel, hreflang, and type, must reflect the respective content attributes
+  of the same name.

+
+  
The IDL attribute relList must
+  reflect the rel content attribute.
Support: rellistChrome for Android (limited) 57+Chrome (limited) 50+UC Browser for Android NoneiOS Safari 9.0+Firefox 30+IE NoneSamsung Internet NoneOpera Mini NoneAndroid Browser (limited) 56+Edge NoneSafari 9+Opera (limited) 37+
Source: caniuse.com

+
+  
The IDL attribute referrerPolicy must
+  reflect the referrerpolicy
+  content attribute, limited to only known values.

+
+  
The text IDL attribute, on getting, must return the
+  same value as the textContent IDL attribute on the element, and on setting, must act
+  as if the textContent IDL attribute on the element had been set to the new value.

+
+  
+
+  

+
+   
The a element may be wrapped around entire paragraphs, lists, tables, and so
+   forth, even entire sections, so long as there is no interactive content within (e.g. buttons or
+   other links). This example shows how this can be used to make an entire advertising block into a
+   link:

+
+   
<aside class="advertising">
+ <h1>Advertising</h1>
+ <a href="https://ad.example.com/?adid=1929&amp;pubid=1422">
+  <section>
+   <h1>Mellblomatic 9000!</h1>
+   <p>Turn all your widgets into mellbloms!</p>
+   <p>Only $9.99 plus shipping and handling.</p>
+  </section>
+ </a>
+ <a href="https://ad.example.com/?adid=375&amp;pubid=1422">
+  <section>
+   <h1>The Mellblom Browser</h1>
+   <p>Web browsing at the speed of light.</p>
+   <p>No other browser goes faster!</p>
+  </section>
+ </a>
+</aside>

+
+  

+
+
+  
4.5.2 The em element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The em element represents stress emphasis of its contents.

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

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

+
+  

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

+
+   
<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 stress 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 stress 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:

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

+
+  

+
+  

+
+   
The em element isn't a generic "italics" element. Sometimes, text is intended to
+   stand out from the rest of the paragraph, as if it was in a different mood or voice. For this,
+   the i element is more appropriate.

+
+   
The em element also isn't intended to convey importance; for that purpose, the
+   strong element is more appropriate.

+
+   
+
+  

+
+
+
+  
4.5.3 The strong element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The strong element represents strong importance, seriousness, or
+  urgency for its contents.

+
+  
Importance: the strong element can be used in a heading, caption,
+  or paragraph to distinguish the part that really matters from other parts that might be more
+  detailed, more jovial, or merely boilerplate. (This is distinct from marking up subheadings, for
+  which the hgroup element is appropriate.)

+
+  
For example, the first word of the previous paragraph is marked up with
+  strong to distinguish it from the more detailed text in the rest of the
+  paragraph.

+
+  
Seriousness: the strong element can be used to mark up a warning
+  or caution notice.

+
+  
Urgency: the strong element can be used to denote contents that
+  the user needs to see sooner than other parts of the document.

+
+  
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, the word "chapter" and the actual chapter number are mere boilerplate, and the actual
+   name of the chapter is marked up with strong:

+
+   
<h1>Chapter 1: <strong>The Praxis</strong></h1>

+
+   
In the following example, the name of the diagram in the caption is marked up with
+   strong, to distinguish it from boilerplate text (before) and the description
+   (after):

+
+   
<figcaption>Figure 1. <strong>Ant colony dynamics</strong>. The ants in this colony are
+affected by the heat source (upper left) and the food source (lower right).</figcaption>

+
+   
In this example, the heading is really "Flowers, Bees, and Honey", but the author has added a
+   light-hearted addition to the heading. The strong element is thus used to mark up
+   the first part to distinguish it from the latter part.

+
+   
<h1><strong>Flowers, Bees, and Honey</strong> and other things I don't understand</h1>

+
+  

+
+  

+   
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>

+  

+
+  

+
+   
In this example, the strong element is used to denote the part of the text that
+   the user is intended to read first.

+
+   
<p>Welcome to Remy, the reminder system.</p>
+<p>Your tasks for today:</p>
+<ul>
+ <li><p><strong>Turn off the oven.</strong></p></li>
+ <li><p>Put out the trash.</p></li>
+ <li><p>Do the laundry.</p></li>
+</ul>

+
+  

+
+
+  
4.5.4 The small element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The small element represents side comments such as small print.

+
+  
Small print typically features disclaimers, caveats, legal restrictions, or
+  copyrights. Small print is also sometimes used for attribution, or for satisfying licensing
+  requirements.

+
+  
The small element does not "de-emphasize" or lower the importance of
+  text emphasized by the em element or marked as important with the strong
+  element. To mark text as not emphasized or important, simply do not mark it up with the
+  em or strong elements respectively.

+
+  
The small element should not be used for extended spans of text, such as multiple
+  paragraphs, lists, or sections of text. It is only intended for short runs of text. The text of a
+  page listing terms of use, for instance, would not be a suitable candidate for the
+  small element: in such a case, the text is not a side comment, it is the main content
+  of the page.

+
+  
The small element must not be used for subheadings; for that purpose, use the
+  hgroup element.

+
+  

+
+   
In this example, the small element is used to indicate that value-added tax is
+   not included in a price of a hotel room:

+
+   
<dl>
+ <dt>Single room
+ <dd>199 € <small>breakfast included, VAT not included</small>
+ <dt>Double room
+ <dd>239 € <small>breakfast included, VAT not included</small>
+</dl>

+
+  

+
+  

+
+   
In this second example, the small element is used for a side comment in an
+   article.

+
+   
<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>

+
+   
This is distinct from a sidebar, which might be multiple paragraphs long and is removed from
+   the main flow of text. In the following example, we see a sidebar from the same article. This
+   sidebar also has small print, indicating the source of the information in the sidebar.

+
+   
<aside>
+ <h1>Example Corp</h1>
+ <p>This company mostly creates small software and Web
+ sites.</p>
+ <p>The Example Corp company mission is "To provide entertainment
+ and news on a sample basis".</p>
+ <p><small>Information obtained from <a
+ href="https://example.com/about.html">example.com</a> home
+ page.</small></p>
+</aside>

+
+  

+
+  

+
+   
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>

+
+  

+
+
+  
4.5.5 The s element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The s element represents contents that are no longer accurate or no
+  longer relevant.

+
+  
The s element is not appropriate when indicating document edits; to
+  mark a span of text as having been removed from a document, use the del element.

+
+  

+
+   
In this example a recommended retail price has been marked as no longer relevant as the
+   product in question has a new sale price.

+
+   
<p>Buy our Iced Tea and Lemonade!</p>
+<p><s>Recommended retail price: $3.99 per bottle</s></p>
+<p><strong>Now selling for just $2.99 a bottle!</strong></p>

+
+  

+
+
+  
4.5.6 The cite element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
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,
+    a legal case report,
+    a computer program, 
+  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.)

+
+
+
+  

+
+   
This next example shows a typical use of the cite element:

+
+   
<p>My favorite book is <cite>The Reality Dysfunction</cite> by
+Peter F. Hamilton. My favorite comic is <cite>Pearls Before
+Swine</cite> by Stephan Pastis. My favorite track is <cite>Jive
+Samba</cite> by the Cannonball Adderley Sextet.</p>

+
+  

+
+  

+
+   
This is correct usage:

+
+   
<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>

+
+  

+
+  
A citation is not a quote (for which the q element
+  is appropriate).

+
+  

+
+   
This is incorrect usage, because cite is not for quotes:

+
+   
<p><cite>This is wrong!</cite>, said Ian.</p>

+
+   
This is also incorrect usage, because a person is not a work:

+
+   
<p><q>This is still wrong!</q>, said <cite>Ian</cite>.</p>

+
+   
The correct usage does not use a cite element:

+
+   
<p><q>This is correct</q>, said Ian.</p>

+
+   
As mentioned above, the b element might be relevant for marking names as being
+   keywords in certain kinds of documents:

+
+   
<p>And then <b>Ian</b> said <q>this might be right, in a
+gossip column, maybe!</q>.</p>

+
+  

+
+
+
+  
4.5.7 The q element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
cite — Link to the source of the quotation or more information about the edit
DOM interface:
Uses HTMLQuoteElement.

+
+  
The q element represents some phrasing
+  content quoted from another source.

+
+  
Quotation punctuation (such as quotation marks) that is quoting the contents of the element
+  must not appear immediately before, after, or inside q elements; they will be
+  inserted into the rendering by the user agent.

+
+  
Content inside a q element must be quoted from another source, whose address, if
+  it has one, may be cited in the cite attribute. The
+  source may be fictional, as when quoting characters in a novel or screenplay.

+
+  
If the cite attribute is present, it must be a valid
+  URL potentially surrounded by spaces. To obtain the corresponding citation
+  link, the value of the attribute must be parsed relative to the
+  element's node document. User agents may allow users to follow such citation
+  links, but they are primarily intended for private use (e.g., by server-side scripts collecting
+  statistics about a site's use of quotations), not for readers.

+
+  
The q element must not be used in place of quotation marks that do not represent
+  quotes; for example, it is inappropriate to use the q element for marking up
+  sarcastic statements.

+
+  
The use of q elements to mark up quotations is entirely optional; using explicit
+  quotation punctuation without q elements is just as correct.

+
+  

+
+   
Here is a simple example of the use of 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="https://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>

+
+  

+
+  

+
+   
In the following example, quotation marks are used instead of the q element:

+
+   
<p>His best argument was ❝I disagree❞, which
+I thought was laughable.</p>

+
+  

+
+  

+
+   
In the following example, there is no quote — the quotation marks are used to name a
+   word. Use of the q element in this case would be inappropriate.

+
+   
<p>The word "ineffable" could have been used to describe the disaster
+resulting from the campaign's mismanagement.</p>

+
+  

+
+
+  
4.5.8 The dfn element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content, but there must be no dfn element descendants.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
Also, the title attribute has special semantics on this element: Full term or expansion of abbreviation.
DOM interface:
Uses HTMLElement.

+
+  
The dfn element represents the defining instance of a term. The paragraph, description list group, or section that is the nearest ancestor of the dfn
+  element must also contain the definition(s) for the term given
+  by the dfn element.

+
+  
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 "Garage Door Opener" is first defined in the first
+   paragraph, then used in the second. In both cases, its abbreviation is what is actually
+   displayed.

+
+   
<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>

+
+  

+
+
+
+  
4.5.9 The abbr element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
Also, the title attribute has special semantics on this element: Full term or expansion of abbreviation.
DOM interface:
Uses HTMLElement.

+
+  
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>

+
+   
An alternative way to write this would be:

+
+   
<p>The <dfn id=whatwg>Web Hypertext Application Technology
+Working Group</dfn> (<abbr
+title="Web Hypertext Application Technology Working Group">WHATWG</abbr>)
+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>

+
+  

+
+  
Abbreviations do not have to be marked up using this element. It is expected to be useful in
+  the following cases:

+
+  
  • Abbreviations for which the author wants to give expansions, where using the
+   abbr element with a title attribute is an
+   alternative to including the expansion inline (e.g. in parentheses).
  • Abbreviations that are likely to be unfamiliar to the document's readers, for which authors
+   are encouraged to either mark up the abbreviation using an abbr element with a title attribute or include the expansion inline in the text the first
+   time the abbreviation is used.
  • Abbreviations whose presence needs to be semantically annotated, e.g. so that they can be
+   identified from a style sheet and given specific styles, for which the abbr element
+   can be used without a title attribute.

+
+  
Providing an expansion in a title attribute once
+  will not necessarily cause other abbr elements in the same document with the same
+  contents but without a title attribute to behave as if they had
+  the same expansion. Every abbr element is independent.

+
+
+  
4.5.10 The ruby element
Spec bugs: 25555
Support: rubyChrome for Android (limited) 57+Chrome (limited) 5+UC Browser for Android (limited) 11.4+iOS Safari (limited) 5.0+Firefox 38+IE (limited) 5.5+Samsung Internet (limited) 4+Android Browser (limited) 3+Edge (limited) 12+Safari (limited) 5+Opera (limited) 15+
Source: caniuse.com

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
See prose.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The ruby element allows one or more spans of phrasing content to be marked with
+  ruby annotations. Ruby annotations are short runs of text presented alongside base text, primarily
+  used in East Asian typography as a guide for pronunciation or to include other annotations. In
+  Japanese, this form of typography is also known as furigana.

+
+  
The content model of ruby elements consists of one or more of the following
+  sequences:

+
+  
  1. One or the other of the following:
+    
+   
  2. One or the other of the following:
+    
    • One or more rt elements
+     
    • An rp element followed by one or more rt elements, each of which is itself followed by an rp element
+    
    
+  

+
+  
+
+  
The ruby and rt elements can be used for a variety of kinds of
+  annotations, including in particular (though by no means limited to) those described below. For
+  more details on Japanese Ruby in particular, and how to render Ruby for Japanese, see
+  Requirements for Japanese Text Layout. [JLREQ]

+
+  
At the time of writing, CSS does not yet provide a way to fully control the
+  rendering of the HTML ruby element. It is hoped that CSS will be extended to support
+  the styles described below in due course.

+
+  
+
+  
Mono-ruby for individual base characters in Japanese
+
+   

+
+    
One or more hiragana or katakana characters (the ruby annotation) are placed with each
+    ideographic character (the base text). This is used to provide readings of kanji characters.
+
+    
 
+     
<ruby>B<rt>annotation</ruby>

+    

+
+    

+     
In this example, notice how each annotation corresponds to a single base character.
+     
<ruby>君<rt>くん</ruby><ruby>子<rt>し</ruby>は<ruby>和<rt>わ</ruby>して<ruby>同<rt>どう</ruby>ぜず。

+     
君くん子しは和わして同どうぜず。
+     
This example can also be written as follows, using one ruby element with two
+     segments of base text and two annotations (one for each) rather than two back-to-back
+     ruby elements each with one base text segment and annotation (as in the markup
+     above):
+     
<ruby>君<rt>くん</rt>子<rt>し</ruby>は<ruby>和<rt>わ</ruby>して<ruby>同<rt>どう</ruby>ぜず。

+    

+
+   
Mono-ruby for compound words (jukugo)
+
+   

+
+    
This is similar to the previous case: each ideographic character in the compound word (the
+    base text) has its reading given in hiragana or katakana characters (the ruby annotation). The
+    difference is that the base text segments form a compound word rather than being separate from
+    each other.
+
+    
 
+     
<ruby>B<rt>annotation</rt>B<rt>annotation</ruby>

+    

+
+    

+     
In this example, notice again how each annotation corresponds to a single base character. In this example, each compound word (jukugo) corresponds to a single ruby element.

+     
The rendering here is expected to be that each annotation be placed over (or next to, in vertical text) the corresponding base character, with the annotations not overhanging any of the adjacent characters.

+     
<ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する

+     
鬼き門もんの方ほう角がくを凝ぎょう視しする
+
+    

+
+   
Jukugo-ruby
+
+   

+
+    
This is semantically identical to the previous case (each individual ideographic character in
+    the base compound word has its reading given in an annotation in hiragana or katakana
+    characters), but the rendering is the more complicated Jukugo Ruby rendering.
+
+    

+     
This is the same example as above for mono-ruby for compound words. The different rendering is expected to be achieved using different styling (e.g. in CSS), and is not shown here.

+     
<ruby>鬼<rt>き</rt>門<rt>もん</rt></ruby>の<ruby>方<rt>ほう</rt>角<rt>がく</rt></ruby>を<ruby>凝<rt>ぎょう</rt>視<rt>し</rt></ruby>する

+     
+     
+    

+
+    
For more details on Jukugo Ruby rendering, see
+    Appendix F in the Requirements for Japanese Text Layout. [JLREQ]

+
+   
Group ruby for describing meanings
+
+   

+
+    
The annotation describes the meaning of the base text, rather than (or in addition to) the
+    pronunciation. As such, both the base text and the annotation can be multiple characters long.
+
+    
 
<ruby>BASE<rt>annotation</ruby>
 

+
+    

+     
Here a compound ideographic word has its corresponding katakana given as an annotation.
+     
<ruby>境界面<rt>インターフェース</ruby>

+     
境界面インターフェース
+    

+
+    

+     
Here a compound ideographic word has its translation in English provided as an annotation.
+     
<ruby lang="ja">編集者<rt lang="en">editor</ruby>

+     
編集者editor
+    

+
+   
Group ruby for Jukuji readings
+
+   

+
+    
A phonetic reading that corresponds to multiple base characters, because a one-to-one mapping
+    would be difficult. (In English, the words "Colonel" and "Lieutenant" are examples of words
+    where a direct mapping of pronunciation to individual letters is, in some dialects, rather
+    unclear.)
+
+    

+     
In this example, the name of a species of flowers has a phonetic reading provided using group ruby:
+     
<ruby>紫陽花<rt>あじさい</ruby>

+     
紫陽花あじさい
+    

+
+   
Text with both phonetic and semantic annotations (double-sided ruby)
+
+   

+
+    
Sometimes, ruby styles described above are combined.
+
+    
If this results in two annotations covering the same single base segment, then the
+    annotations can just be placed back to back.
+
+    

+     
<ruby>BASE<rt>annotation 1<rt>annotation 2</ruby>

+    

+
+    

+     
<ruby>B<rt>a<rt>a</ruby><ruby>A<rt>a<rt>a</ruby><ruby>S<rt>a<rt>a</ruby><ruby>E<rt>a<rt>a</ruby>

+    

+
+    

+
+     
In this contrived example, some symbols are given names in English and French.
+
+     
<ruby>
+ ♥ <rt> Heart <rt lang=fr> Cœur </rt>
+ ☘ <rt> Shamrock <rt lang=fr> Trèfle </rt>
+ ✶ <rt> Star <rt lang=fr> Étoile </rt>
+</ruby>

+
+    

+
+    
In more complication situations such as following examples, a nested ruby
+    element is used to give the inner annotations, and then that whole ruby is then
+    given an annotation at the "outer" level.
+
+    

+     
<ruby><ruby>B<rt>a</rt>A<rt>n</rt>S<rt>t</rt>E<rt>n</rt></ruby><rt>annotation</ruby>

+    

+
+    

+     
Here both a phonetic reading and the meaning are given in ruby annotations. The annotation on the nested ruby element gives a mono-ruby phonetic annotation for each base character, while the annotation in the rt element that is a child of the outer ruby element gives the meaning using hiragana.
+     
<ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt>たつみ</rt></ruby>の方角

+     
東とう南なんたつみの方角
+    

+
+    

+     
This is the same example, but the meaning is given in English instead of Japanese:
+     
<ruby><ruby>東<rt>とう</rt>南<rt>なん</rt></ruby><rt lang=en>Southeast</rt></ruby>の方角

+     
東とう南なんSoutheastの方角
+    

+
+   

+
+  

+
+  
Within a ruby element that does not have a ruby element ancestor,
+  content is segmented and segments are placed into three categories: base text segments, annotation
+  segments, and ignored segments. Ignored segments do not form part of the document's semantics
+  (they consist of some inter-element whitespace and rp elements, the
+  latter of which are used for legacy user agents that do not support ruby at all). Base text
+  segments can overlap (with a limit of two segments overlapping any one position in the DOM, and
+  with any segment having an earlier start point than an overlapping segment also having an equal or
+  later end point, and any segment have a later end point than an overlapping segment also having an
+  equal or earlier start point). Annotation segments correspond to rt elements. Each annotation
+  segment can be associated with a base text segment, and each base text segment can have annotation
+  segments associated with it. (In a conforming document, each base text segment is associated with
+  at least one annotation segment, and each annotation segment is associated with one base text
+  segment.) A ruby element represents the union of the segments of base
+  text it contains, along with the mapping from those base text segments to annotation segments.
+  Segments are described in terms of DOM ranges; annotation segment ranges always consist of exactly
+  one element. [DOM]

+
+  
At any particular time, the segmentation and categorization of content of a ruby
+  element is the result that would be obtained from running the following algorithm:

+
+  
  1. Let base text segments be an empty list of base text segments, each
+   potentially with a list of base text subsegments.
  2. Let annotation segments be an empty list of annotation segments, each
+   potentially being associated with a base text segment or subsegment.
  3. Let root be the ruby element for which the algorithm is
+   being run.
  4. If root has a ruby element ancestor, then jump to the
+   step labeled end.
  5. Let current parent be root.
  6. Let index be 0.
  7. Let start index be null.
  8. Let parent start index be null.
  9. Let current base text be null.
  10. Start mode: If index is equal to or greater than the number of
+   child nodes in current parent, then jump to the step labeled end
+   mode.
    
+
+   
  11. If the indexth node in current parent is an
+   rt or rp element, jump to the step labeled annotation
+   mode.
  12. Set start index to the value of index.
  13. Base mode: If the indexth node in current
+   parent is a ruby element, and if current parent is the
+   same element as root, then push a ruby level and then jump to
+   the step labeled start mode.
  14. If the indexth node in current parent is an
+   rt or rp element, then set the current base text and then
+   jump to the step labeled annotation mode.
  15. Increment index by one.
  16. Base mode post-increment: If index is equal to or greater than
+   the number of child nodes in current parent, then jump to the step labeled
+   end mode.
  17. Jump back to the step labeled base mode.
  18. Annotation mode: If the indexth node in current
+   parent is an rt element, then push a ruby annotation and jump to
+   the step labeled annotation mode increment.
  19. If the indexth node in current parent is an
+   rp element, jump to the step labeled annotation mode increment.
  20. If the indexth node in current parent is not a
+   Text node, or is a Text node that is not inter-element
+   whitespace, then jump to the step labeled base mode.
  21. Annotation mode increment: Let lookahead index be index plus one.
  22. Annotation mode white-space skipper: If lookahead index is
+   equal to the number of child nodes in current parent then jump to the step
+   labeled end mode.
  23. If the lookahead indexth node in current parent is
+   an rt element or an rp element, then set index to
+   lookahead index and jump to the step labeled annotation mode.
  24. If the lookahead indexth node in current parent is
+   not a Text node, or is a Text node that is not inter-element
+   whitespace, then jump to the step labeled base mode (without further incrementing
+   index, so the inter-element whitespace seen so far becomes part
+   of the next base text segment).
  25. Increment lookahead index by one.
  26. Jump to the step labeled annotation mode white-space skipper.
  27. End mode: If current parent is not the same element as root, then pop a ruby level and jump to the step labeled base mode
+   post-increment.
  28. End: Return base text segments and annotation
+   segments. Any content of the ruby element not described by segments in either
+   of those lists is implicitly in an ignored segment.

+
+
+  
When the steps above say to set the current base text, it means to run the following
+  steps at that point in the algorithm:

+
+  
  1. Let text range be a DOM range whose start is the boundary
+   point (current parent, start index) and whose
+   end is the boundary
+   point (current parent, index).
  2. Let new text segment be a base text segment described by the range
+   annotation range.
    
+
+   
  3. Add new text segment to base text
+   segments.
  4. Let current base text be new text
+   segment.
  5. Let start index be null.

+
+
+  
When the steps above say to push a ruby level, it means to run the following steps
+  at that point in the algorithm:

+
+  
  1. Let current parent be the indexth node in current parent.
  2. Let index be 0.
  3. Set saved start index to the value of start
+   index.
  4. Let start index be null.

+
+
+  
When the steps above say to pop a ruby level, it means to run the following steps at
+  that point in the algorithm:

+
+  
  1. Let index be the position of current parent in
+   root.
  2. Let current parent be root.
  3. Increment index by one.
  4. Set start index to the value of saved start
+   index.
  5. Let saved start index be null.

+
+
+  
When the steps above say to push a ruby annotation, it means to run the following
+  steps at that point in the algorithm:

+
+  
  1. Let rt be the rt element that is the indexth node of current parent.
  2. Let annotation range be a DOM range whose start is the boundary
+   point (current parent, index) and whose end is the boundary point
+   (current parent, index plus one) (i.e. that contains only
+   rt).
  3. Let new annotation segment be an annotation segment described by the
+   range annotation range.
  4. If current base text is not null, associate new
+   annotation segment with current base text.
  5. Add new annotation segment to annotation
+   segments.

+
+  

+
+   
+   
+
+   
In this example, each ideograph in the Japanese text 漢字 is annotated with its reading in hiragana.

+
+   
...
+<ruby>漢<rt>かん</rt>字<rt>じ</rt></ruby>
+...

+
+   
This might be rendered as:

+
+   
The two main ideographs, each with its annotation in hiragana rendered in a smaller font above it.

+
+  

+
+  

+
+   
+
+   
In this example, each ideograph in the traditional Chinese text 漢字 is annotated with its bopomofo reading.

+
+   
<ruby>漢<rt>ㄏㄢˋ</rt>字<rt>ㄗˋ</rt></ruby>

+
+   
This might be rendered as:

+
+   
The two main ideographs, each with its bopomofo annotation rendered in a smaller font next to it.

+
+  

+
+  

+
+   
+
+   
In this example, each ideograph in the simplified Chinese text 汉字 is annotated with its pinyin reading.

+
+   
...<ruby>汉<rt>hàn</rt>字<rt>zì</rt></ruby>...

+
+   
This might be rendered as:

+
+   
The two main ideographs, each with its pinyin annotation rendered in a smaller font above it.

+
+  

+
+  
+
+  

+
+   
In this more contrived example, the acronym "HTML" has four annotations: one for the whole
+   acronym, briefly describing what it is, one for the letters "HT" expanding them to "Hypertext",
+   one for the letter "M" expanding it to "Markup", and one for the letter "L" expanding it to
+   "Language".

+
+   
<ruby>
+ <ruby>HT<rt>Hypertext</rt>M<rt>Markup</rt>L<rt>Language</rt></ruby>
+ <rt>An abstract language for describing documents and applications
+</ruby>

+
+  

+
+
+  
4.5.11 The rt element

+
+  
Categories:
None.
Contexts in which this element can be used:
As a child of a ruby element.
Content model:
Phrasing content.
Tag omission in text/html:
An rt element's end tag can be omitted if the
+   rt element is immediately followed by an rt or rp element,
+   or if there is no more content in the parent element.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The rt element marks the ruby text component of a ruby annotation. When it is the
+  child of a ruby element, it doesn't represent
+  anything itself, but the ruby element uses it as part of determining what it
+  represents.

+
+  
+
+  
An rt element that is not a child of a ruby element
+  represents the same thing as its children.

+
+  
+
+
+  
4.5.12 The rp element

+
+  
Categories:
None.
Contexts in which this element can be used:
As a child of a ruby element, either immediately before or immediately after an rt element.
Content model:
Text.
Tag omission in text/html:
An rp element's end tag can be omitted if the
+   rp element is immediately followed by an rt or rp element,
+   or if there is no more content in the parent element.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The rp element can be used to provide parentheses or other content 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. An rp element
+  whose parent element is not a ruby element represents its
+  children.

+
+  

+
+   
The example above, in which each ideograph in the text 漢字 is annotated with its phonetic reading, could be expanded to
+   use rp so that in legacy user agents the readings are in parentheses:

+
+   
...
+<ruby>漢<rp>（</rp><rt>かん</rt><rp>）</rp>字<rp>（</rp><rt>じ</rt><rp>）</rp></ruby>
+...

+
+   
In conforming user agents the rendering would be as above, but in user agents that do not
+   support ruby, the rendering would be:

+
+   
... 漢（かん）字（じ）...

+
+  

+
+  

+
+   
When there are multiple annotations for a segment, rp elements can also be placed
+   between the annotations. Here is another copy of an earlier contrived example showing some
+   symbols with names given in English and French, but this time with rp elements as
+   well:
+
+   
<ruby>
+♥<rp>: </rp><rt>Heart</rt><rp>, </rp><rt lang=fr>Cœur</rt><rp>.</rp>
+☘<rp>: </rp><rt>Shamrock</rt><rp>, </rp><rt lang=fr>Trèfle</rt><rp>.</rp>
+✶<rp>: </rp><rt>Star</rt><rp>, </rp><rt lang=fr>Étoile</rt><rp>.</rp>
+</ruby>

+
+   
This would make the example render as follows in non-ruby-capable user agents:
+
+   
♥: Heart, Cœur. ☘: Shamrock, Trèfle. ✶: Star, Étoile.

+
+  

+
+
+  
4.5.13 The data element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
value — Machine-readable value
DOM interface:

+
[HTMLConstructor]
+interface HTMLDataElement : HTMLElement {
+  [CEReactions] attribute DOMString value;
+};

+   

+
+  
The data element represents its contents, along with a
+  machine-readable form of those contents in the value
+  attribute.

+
+  
The value attribute must be present. Its value
+  must be a representation of the element's contents in a machine-readable format.

+
+  
When the value is date- or time-related, the more specific time
+  element can be used instead.

+
+  
The element can be used for several purposes.

+
+  
When combined with microformats or the microdata attributes defined in
+  this specification, the element serves to provide both a machine-readable value for the purposes
+  of data processors, and a human-readable value for the purposes of rendering in a Web browser. In
+  this case, the format to be used in the value attribute is
+  determined by the microformats or microdata vocabulary in use.

+
+  
The element can also, however, be used in conjunction with scripts in the page, for when a
+  script has a literal value to store alongside a human-readable value. In such cases, the format to
+  be used depends only on the needs of the script. (The data-*
+  attributes can also be useful in such situations.)

+
+  
+
+  
The value IDL attribute must
+  reflect the content attribute of the same name.

+
+  
+
+  

+
+   
Here, a short table has its numeric values encoded using the data element so
+   that the table sorting JavaScript library can provide a sorting mechanism on each column
+   despite the numbers being presented in textual form in one column and in a decomposed form in
+   another.

+
+   
<script src="sortable.js"></script>
+<table class="sortable">
+ <thead> <tr> <th> Game <th> Corporations <th> Map Size
+ <tbody>
+  <tr> <td> 1830 <td> <data value="8">Eight</data> <td> <data value="93">19+74 hexes (93 total)</data>
+  <tr> <td> 1856 <td> <data value="11">Eleven</data> <td> <data value="99">12+87 hexes (99 total)</data>
+  <tr> <td> 1870 <td> <data value="10">Ten</data> <td> <data value="149">4+145 hexes (149 total)</data>
+</table>

+
+  

+
+
+
+
+  
4.5.14 The time element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
If the element has a datetime attribute: Phrasing content.
Otherwise: Text, but must match requirements described in prose below.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
datetime — Machine-readable value
DOM interface:

+
[HTMLConstructor]
+interface HTMLTimeElement : HTMLElement {
+  [CEReactions] attribute DOMString dateTime;
+};

+   

+
+  
The time element represents its contents, along with a
+  machine-readable form of those contents in the datetime
+  attribute. The kind of content is limited to various kinds of dates, times, time-zone offsets, and
+  durations, as described below.

+
+  
The datetime attribute may be present. If
+  present, its value must be a representation of the element's contents in a machine-readable
+  format.

+
+  
A time element that does not have a datetime content attribute must not have any element
+  descendants.

+
+  
The datetime value of a time element is the value of the element's
+  datetime content attribute, if it has one, otherwise the
+  child text content of the time element.

+
+  
The datetime value of a time element must match one of the following
+  syntaxes.

+
+  
A valid month string

+
+    
<time>2011-11</time>

+
+   
A valid date string

+
+    
<time>2011-11-18</time>

+
+   
A valid yearless date string

+
+    
<time>11-18</time>

+
+   
A valid time string

+
+    
<time>14:54</time>

+    
<time>14:54:39</time>

+    
<time>14:54:39.929</time>

+
+   
A valid local date and time string

+
+    
<time>2011-11-18T14:54</time>

+    
<time>2011-11-18T14:54:39</time>

+    
<time>2011-11-18T14:54:39.929</time>

+    
<time>2011-11-18 14:54</time>

+    
<time>2011-11-18 14:54:39</time>

+    
<time>2011-11-18 14:54:39.929</time>

+
+    
Times with dates but without a time zone offset are useful for specifying events
+    that are observed at the same specific time in each time zone, throughout a day. For example,
+    the 2020 new year is celebrated at 2020-01-01 00:00 in each time zone, not at the same precise
+    moment across all time zones. For events that occur at the same time across all time zones, for
+    example a videoconference meeting, a valid global date and time string is likely
+    more useful.

+
+   
A valid time-zone offset string

+
+    
<time>Z</time>

+    
<time>+0000</time>

+    
<time>+00:00</time>

+    
<time>-0800</time>

+    
<time>-08:00</time>

+
+    
For times without dates (or times referring to events that recur on multiple
+    dates), specifying the geographic location that controls the time is usually more useful than
+    specifying a time zone offset, because geographic locations change time zone offsets with
+    daylight savings time. In some cases, geographic locations even change time zone, e.g. when the
+    boundaries of those time zones are redrawn, as happened with Samoa at the end of 2011. There
+    exists a time zone database that describes the boundaries of time zones and what rules apply
+    within each such zone, known as the time zone database. [TZDATABASE]

+
+   
A valid global date and time string

+
+    
<time>2011-11-18T14:54Z</time>

+    
<time>2011-11-18T14:54:39Z</time>

+    
<time>2011-11-18T14:54:39.929Z</time>

+
+    
<time>2011-11-18T14:54+0000</time>

+    
<time>2011-11-18T14:54:39+0000</time>

+    
<time>2011-11-18T14:54:39.929+0000</time>

+
+    
<time>2011-11-18T14:54+00:00</time>

+    
<time>2011-11-18T14:54:39+00:00</time>

+    
<time>2011-11-18T14:54:39.929+00:00</time>

+
+    
<time>2011-11-18T06:54-0800</time>

+    
<time>2011-11-18T06:54:39-0800</time>

+    
<time>2011-11-18T06:54:39.929-0800</time>

+
+    
<time>2011-11-18T06:54-08:00</time>

+    
<time>2011-11-18T06:54:39-08:00</time>

+    
<time>2011-11-18T06:54:39.929-08:00</time>

+
+    
<time>2011-11-18 14:54Z</time>

+    
<time>2011-11-18 14:54:39Z</time>

+    
<time>2011-11-18 14:54:39.929Z</time>

+
+    
<time>2011-11-18 14:54+0000</time>

+    
<time>2011-11-18 14:54:39+0000</time>

+    
<time>2011-11-18 14:54:39.929+0000</time>

+
+    
<time>2011-11-18 14:54+00:00</time>

+    
<time>2011-11-18 14:54:39+00:00</time>

+    
<time>2011-11-18 14:54:39.929+00:00</time>

+
+    
<time>2011-11-18 06:54-0800</time>

+    
<time>2011-11-18 06:54:39-0800</time>

+    
<time>2011-11-18 06:54:39.929-0800</time>

+
+    
<time>2011-11-18 06:54-08:00</time>

+    
<time>2011-11-18 06:54:39-08:00</time>

+    
<time>2011-11-18 06:54:39.929-08:00</time>

+
+    
Times with dates and a time zone offset are useful for specifying specific
+    events, or recurring virtual events where the time is not anchored to a specific geographic
+    location. For example, the precise time of an asteroid impact, or a particular meeting in a
+    series of meetings held at 1400 UTC every day, regardless of whether any particular part of the
+    world is observing daylight savings time or not. For events where the precise time varies by the
+    local time zone offset of a specific geographic location, a valid local date and time
+    string combined with that geographic location is likely more useful.

+
+   
A valid week string

+
+    
<time>2011-W47</time>

+
+   
Four or more ASCII digits, at least one of which is not U+0030 DIGIT ZERO (0)

+
+    
<time>2011</time>

+
+    
<time>0001</time>

+
+   
A valid duration string

+
+    
<time>PT4H18M3S</time>

+
+    
<time>4h 18m 3s</time>

+
+   

+
+  
+
+  
The machine-readable equivalent of the element's contents must be obtained from the
+  element's datetime value by using the following algorithm:

+
+  
  1. If parsing a month string from the element's
+   datetime value returns a month, that is the
+   machine-readable equivalent; abort these steps.
  2. If parsing a date string from the element's
+   datetime value returns a date, that is the
+   machine-readable equivalent; abort these steps.
  3. If parsing a yearless date string from
+   the element's datetime value returns a yearless
+   date, that is the machine-readable equivalent; abort these steps.
  4. If parsing a time string from the element's
+   datetime value returns a time, that is the
+   machine-readable equivalent; abort these steps.
  5. If parsing a local date and time
+   string from the element's datetime value returns a local date and time, that is the machine-readable
+   equivalent; abort these steps.
  6. If parsing a time-zone offset string
+   from the element's datetime value returns a time-zone
+   offset, that is the machine-readable equivalent; abort these steps.
  7. If parsing a global date and time
+   string from the element's datetime value returns a global date and time, that is the machine-readable equivalent;
+   abort these steps.
  8. If parsing a week string from the element's
+   datetime value returns a week, that is the
+   machine-readable equivalent; abort these steps.
  9. If the element's datetime value consists of only ASCII digits,
+   at least one of which is not U+0030 DIGIT ZERO (0), then the machine-readable equivalent is the
+   base-ten interpretation of those digits, representing a year; abort these steps.
  10. If parsing a duration string from the
+   element's datetime value returns a duration,
+   that is the machine-readable equivalent; abort these steps.
  11. There is no machine-readable equivalent.

+
+  
The algorithms referenced above are intended to be designed such that for any
+  arbitrary string s, only one of the algorithms returns a value. A more
+  efficient approach might be to create a single algorithm that parses all these data types in one
+  pass; developing such an algorithm is left as an exercise to the reader.

+
+  
The dateTime IDL attribute must
+  reflect the element's datetime content
+  attribute.

+
+  
+
+  

+
+   
The time element can be used to encode dates, for example in microformats. The
+   following shows a hypothetical way of encoding an event using a variant on hCalendar that uses
+   the time element:

+
+   
<div class="vevent">
+ <a class="url" href="http://www.web2con.com/">http://www.web2con.com/</a>
+ <span class="summary">Web 2.0 Conference</span>:
+ <time class="dtstart" datetime="2005-10-05">October 5</time> -
+ <time class="dtend" datetime="2005-10-07">7</time>,
+ at the <span class="location">Argent Hotel, San Francisco, CA</span>
+</div>

+
+  

+
+  

+
+   
Here, a fictional microdata vocabulary based on the Atom vocabulary is used with the
+   time element to mark up a blog post's publication date.

+
+   
<article itemscope itemtype="https://n.example.org/rfc4287">
+ <h1 itemprop="title">Big tasks</h1>
+ <footer>Published <time itemprop="published" datetime="2009-08-29">two days ago</time>.</footer>
+ <p itemprop="content">Today, I went out and bought a bike for my kid.</p>
+</article>

+
+  

+
+  

+
+   
In this example, another article's publication date is marked up using time, this
+   time using the schema.org microdata vocabulary:

+
+   
<article itemscope itemtype="http://schema.org/BlogPosting">
+ <h1 itemprop="headline">Small tasks</h1>
+ <footer>Published <time itemprop="datePublished" datetime="2009-08-30">yesterday</time>.</footer>
+ <p itemprop="articleBody">I put a bike bell on her bike.</p>
+</article>

+
+  

+
+  

+
+   
In the following snippet, the time element is used to encode a date in the
+   ISO8601 format, for later processing by a script:

+
+   
<p>Our first date was <time datetime="2006-09-23">a Saturday</time>.</p>

+
+   
In this second snippet, the value includes a time:

+
+   
<p>We stopped talking at <time datetime="2006-09-24T05:00-07:00">5am the next morning</time>.</p>

+
+   
A script loaded by the page (and thus privy to the page's internal convention of marking up
+   dates and times using the time element) could scan through the page and look at all
+   the time elements therein to create an index of dates and times.

+
+  

+
+  

+
+   
For example, this element conveys the string "Friday" with the additional semantic that the
+   18th of November 2011 is the meaning that corresponds to "Friday":

+
+   
Today is <time datetime="2011-11-18">Friday</time>.

+
+  

+
+  

+
+   
In this example, a specific time in the Pacific Standard Time timezone is specified:

+
+   
Your next meeting is at <time datetime="2011-11-18T15:00-08:00">3pm</time>.

+
+  

+
+
+
+
+  
4.5.15 The code element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The code element represents a fragment of computer code. This could
+  be an XML element name, a file name, a computer program, or any other string that a computer would
+  recognize.

+
+  
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, can use the class attribute, e.g.
+  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.

+
+   
<pre><code class="language-pascal">var i: Integer;
+begin
+   i := 1;
+end.</code></pre>

+
+   
A class is used in that example to indicate the language used.

+
+  

+
+  
See the pre element for more details.

+
+
+  
4.5.16 The var element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The var element represents a variable. This could be an actual
+  variable in a mathematical expression or programming context, an identifier representing a
+  constant, a symbol identifying a physical quantity, a function parameter, or just be a term used
+  as a placeholder in prose.

+
+  

+   
In the paragraph below, the letter "n" is being used as a
+   variable in prose:

+   
<p>If there are <var>n</var> pipes leading to the ice
+cream factory then I expect at <em>least</em> <var>n</var>
+flavors of ice cream to be available for purchase!</p>

+  

+
+  
For mathematics, in particular for anything beyond the simplest of expressions, MathML is more
+  appropriate. However, the var element can still be used to refer to specific
+  variables that are then mentioned in MathML expressions.

+
+  

+
+   
In this example, an equation is shown, with a legend that references the variables in the
+   equation. The expression itself is marked up with MathML, but the variables are mentioned in the
+   figure's legend using var.

+
+   
<figure>
+ <math>
+  <mi>a</mi>
+  <mo>=</mo>
+  <msqrt>
+   <msup><mi>b</mi><mn>2</mn></msup>
+   <mi>+</mi>
+   <msup><mi>c</mi><mn>2</mn></msup>
+  </msqrt>
+ </math>
+ <figcaption>
+  Using Pythagoras' theorem to solve for the hypotenuse <var>a</var> of
+  a triangle with sides <var>b</var> and <var>c</var>
+ </figcaption>
+</figure>

+
+  

+
+  

+
+   
Here, the equation describing mass-energy equivalence is used in a sentence, and the
+   var element is used to mark the variables and constants in that equation:

+
+   
<p>Then she turned to the blackboard and picked up the chalk. After a few moment's
+thought, she wrote <var>E</var> = <var>m</var> <var>c</var><sup>2</sup>. The teacher
+looked pleased.</p>

+
+  

+
+
+  
4.5.17 The samp element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The samp element represents sample or quoted output from another
+  program or computing system.

+
+  
See the pre and kbd elements for more details.

+
+  
This element can be contrasted with the output element, which can be
+  used to provide immediate output in a Web application.

+
+  

+   
This example shows the samp element being used
+   inline:

+   
<p>The computer said <samp>Too much cheese in tray
+two</samp> but I didn't know what that meant.</p>

+  

+
+  

+
+   
This second example shows a block of sample output from a console program. Nested
+   samp and kbd elements allow for the styling of specific elements
+   of the sample output using a style sheet. There's also a few parts of the samp that
+   are annotated with even more detailed markup, to enable very precise styling. To achieve this,
+   span elements are used.

+
+   
<pre><samp><span class="prompt">jdoe@mowmow:~$</span> <kbd>ssh demo.example.com</kbd>
+Last login: Tue Apr 12 09:10:17 2005 from mowmow.example.com on pts/1
+Linux demo 2.6.10-grsec+gg3+e+fhs6b+nfs+gr0501+++p3+c4a+gr2b-reslog-v6.189 #1 SMP Tue Feb 1 11:22:36 PST 2005 i686 unknown
+
+<span class="prompt">jdoe@demo:~$</span> <span class="cursor">_</span></samp></pre>

+
+  

+
+  

+
+   
This third example shows a block of input and its respective output. The example uses
+   both code and samp elements.

+
+   
<pre>
+<code class="language-javascript">console.log(2.3 + 2.4)</code>
+<samp>4.699999999999999</samp>
+</pre>

+
+  

+
+
+  
4.5.18 The kbd element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The kbd element represents user input (typically keyboard input,
+  although it may also be used to represent other input, such as voice commands).

+
+  
When the kbd element is nested inside a samp element, it represents
+  the input as it was echoed by the system.

+
+  
When the kbd element contains a samp element, it represents
+  input based on system output, for example invoking a menu item.

+
+  
When the kbd element is nested inside another kbd element, it
+  represents an actual key or other single unit of input as appropriate for the input mechanism.

+
+  

+
+   
Here the kbd element is used to indicate keys to press:

+
+   
<p>To make George eat an apple, press <kbd><kbd>Shift</kbd>+<kbd>F3</kbd></kbd></p>

+
+   
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>

+
+   
Such precision isn't necessary; the following is equally fine:

+
+   
<p>To make George eat an apple, select <kbd>File | Eat Apple...</kbd></p>

+
+  

+
+
+  
4.5.19 The sub and sup elements

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Use HTMLElement.

+
+  
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.

+
+  
In certain languages, superscripts are part of the typographical conventions for some
+  abbreviations.

+
+  

+   
<p>The most beautiful women are
+<span lang="fr"><abbr>M<sup>lle</sup></abbr> Gwendoline</span> and
+<span lang="fr"><abbr>M<sup>me</sup></abbr> Denise</span>.</p>

+  

+
+  
The sub element can be used inside a var element, for variables that
+  have subscripts.

+
+  

+
+   
Here, the sub element is used to represent 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>

+  

+
+  
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]

+
+  

+   
<var>E</var>=<var>m</var><var>c</var><sup>2</sup>

+   
f(<var>x</var>, <var>n</var>) = log<sub>4</sub><var>x</var><sup><var>n</var></sup>

+  

+
+
+
+  
4.5.20 The i element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The i element represents a span of text in an alternate voice or
+  mood, or otherwise offset from the normal prose in a manner indicating a different quality of
+  text, such as a taxonomic designation, a technical term, an idiomatic phrase from another
+  language, transliteration, a thought, or a ship name in Western texts.

+
+  
Terms in languages different from the main text should be annotated with lang attributes (or, in XML, lang attributes in the XML namespace).

+
+  

+   
The examples below show uses of the i element:

+   
<p>The <i class="taxonomy">Felis silvestris catus</i> is cute.</p>
+<p>The term <i>prose content</i> is defined above.</p>
+<p>There is a certain <i lang="fr">je ne sais quoi</i> in the air.</p>

+   
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>

+  

+
+  
Authors can 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.

+
+  
Authors are encouraged to consider whether other elements might be more applicable than the
+  i element, for instance the em element for marking up stress emphasis,
+  or the dfn element to mark up the defining instance of a term.

+
+  
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.

+
+
+  
4.5.21 The b element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The b element represents a span of text to which attention is being
+  drawn for utilitarian purposes without conveying any extra importance and with no implication of
+  an alternate voice or mood, such as key words in a document abstract, product names in a review,
+  actionable words in interactive text-driven software, or an article lede.

+
+  

+
+   
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.

+
+   
<p>You enter a small room. Your <b>sword</b> glows
+brighter. A <b>rat</b> scurries past the corner wall.</p>

+
+  

+
+  

+
+   
Another case where the b element is appropriate is in marking up the lede (or
+   lead) sentence or paragraph. The following example shows how a BBC article about
+   kittens adopting a rabbit as their own could be marked up:

+
+   
<article>
+ <h2>Kittens 'adopted' by pet rabbit</h2>
+ <p><b class="lede">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>
+[...]

+
+  

+
+  
As with the i element, authors can use the class
+  attribute on the b element to identify why the element is being used, so that if the
+  style of a particular use is to be changed at a later date, the author doesn't have to go through
+  annotating each use.

+
+  
The b element should be used as a last resort when no other element is more
+  appropriate. In particular, headings 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.

+
+
+
+  
4.5.22 The u element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The u element represents a span of text with an unarticulated, though
+  explicitly rendered, non-textual annotation, such as labeling the text as being a proper name in
+  Chinese text (a Chinese proper name mark), or labeling the text as being misspelt.

+
+  
In most cases, another element is likely to be more appropriate: for marking stress emphasis,
+  the em element should be used; for marking key words or phrases either the
+  b element or the mark element should be used, depending on the context;
+  for marking book titles, the cite element should be used; for labeling text with explicit textual annotations, the
+  ruby element should be used; for technical terms, taxonomic designation,
+  transliteration, a thought, or for labeling ship names in Western texts, the i
+  element should be used.

+
+  
The default rendering of the u element in visual presentations
+  clashes with the conventional rendering of hyperlinks (underlining). Authors are encouraged to
+  avoid using the u element where it could be confused for a hyperlink.

+
+  

+
+   
In this example, a u element is used to mark a word as misspelt:

+
+   
<p>The <u>see</u> is full of fish.</p>

+
+  

+
+
+
+  
4.5.23 The mark element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
+
+  
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.

+
+  

+
+   
This example shows how the mark element 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>

+
+   
(If the goal was to mark the element as misspelt, however, the u element,
+   possibly with a class, would be more appropriate.)

+
+  

+
+  

+
+   
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.

+
+   
<p>The highlighted part below is where the error lies:</p>
+<pre><code>var i: Integer;
+begin
+   i := <mark>1.1</mark>;
+end.</code></pre>

+
+   
This is separate from syntax highlighting, for which span is more
+   appropriate. Combining both, one would get:

+
+   
<p>The highlighted part below is where the error lies:</p>
+<pre><code><span class=keyword>var</span> <span class=ident>i</span>: <span class=type>Integer</span>;
+<span class=keyword>begin</span>
+   <span class=ident>i</span> := <span class=literal><mark>1.1</mark></span>;
+<span class=keyword>end</span>.</code></pre>

+
+  

+
+  

+
+   
This is another example showing the use of mark to highlight a part of quoted
+   text that was originally not emphasized. In this example, common typographic conventions have led
+   the author to explicitly style mark elements in quotes to render in italics.

+
+   
<style>
+ blockquote mark, q mark {
+   font: inherit; font-style: italic;
+   text-decoration: none;
+   background: transparent; color: inherit;
+ }
+ .bubble em {
+   font: inherit; font-size: larger;
+   text-decoration: underline;
+ }
+</style>
+<article>
+ <h1>She knew</h1>
+ <p>Did you notice the subtle joke in the joke on panel 4?</p>
+ <blockquote>
+  <p class="bubble">I didn't <em>want</em> to believe. <mark>Of course
+  on some level I realized it was a known-plaintext attack.</mark> But I
+  couldn't admit it until I saw for myself.</p>
+ </blockquote>
+ <p>(Emphasis mine.) I thought that was great. It's so pedantic, yet it
+ explains everything neatly.</p>
+</article>

+
+   
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>

+
+  

+
+
+  
4.5.24 The bdi element
Spec bugs: 27475

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
Also, the dir global attribute has special semantics on this element.
DOM interface:
Uses HTMLElement.

+
+  
The bdi element represents a span of text that is to be isolated from
+  its surroundings for the purposes of bidirectional text formatting. [BIDI]

+
+  
The dir global attribute defaults to auto on this element (it never inherits from the parent element like
+  with other elements).

+
+  
+
+  
This element has rendering requirements involving the
+  bidirectional algorithm.

+
+  
+
+  

+
+   
This element is especially useful when embedding user-generated content with an unknown
+   directionality.

+
+   
In this example, usernames are shown along with the number of posts that the user has
+   submitted. If the bdi element were not used, the username of the Arabic user would
+   end up confusing the text (the bidirectional algorithm would put the colon and the number "3"
+   next to the word "User" rather than next to the word "posts").

+
+   
<ul>
+ <li>User <bdi>jcranmer</bdi>: 12 posts.
+ <li>User <bdi>hober</bdi>: 5 posts.
+ <li>User <bdi>إيان</bdi>: 3 posts.
+</ul>

+
+   

+    
+    
When using the bdi element, the username acts as expected.

+   

+
+   

+    
+    
If the bdi element were to be replaced by a b element, the username would confuse the bidirectional algorithm and the third bullet would end up saying "User 3 :", followed by the Arabic name (right-to-left), followed by "posts" and a period.

+   

+
+  

+
+
+  
4.5.25 The bdo element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
Also, the dir global attribute has special semantics on this element.
DOM interface:
Uses HTMLElement.

+
+  
The bdo element represents explicit text directionality formatting
+  control for its children. It allows authors to override the Unicode bidirectional algorithm by
+  explicitly specifying a direction override. [BIDI]

+
+  
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. The auto value must not be specified.

+
+  
+
+  
This element has rendering requirements involving the
+  bidirectional algorithm.

+
+  
+
+
+
+  
4.5.26 The span element

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:

+    
[HTMLConstructor]
+interface HTMLSpanElement : HTMLElement {};

+   

+
+  
The span element doesn't mean anything on its own, but can be useful when used
+  together with the global attributes, e.g. class,
+  lang, or dir. It
+  represents its children.

+
+  

+
+   
In this example, a code fragment is marked up using span elements and class attributes so that its keywords and identifiers can be
+   color-coded from CSS:

+
+   
+
+   
<pre><code class="lang-c"><span class="keyword">for</span> (<span class="ident">j</span> = 0; <span class="ident">j</span> &lt; 256; <span class="ident">j</span>++) {
+  <span class="ident">i_t3</span> = (<span class="ident">i_t3</span> & 0x1ffff) | (<span class="ident">j</span> &lt;&lt; 17);
+  <span class="ident">i_t6</span> = (((((((<span class="ident">i_t3</span> >> 3) ^ <span class="ident">i_t3</span>) >> 1) ^ <span class="ident">i_t3</span>) >> 8) ^ <span class="ident">i_t3</span>) >> 5) & 0xff;
+  <span class="keyword">if</span> (<span class="ident">i_t6</span> == <span class="ident">i_t1</span>)
+    <span class="keyword">break</span>;
+}</code></pre>

+
+  

+
+
+
+  
4.5.27 The br element

+
+  
Categories:
Flow content.
Phrasing content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
DOM interface:

+    
[HTMLConstructor]
+interface HTMLBRElement : HTMLElement {
+  // also has obsolete members
+};

+   

+
+  
The br element represents a line break.

+
+  
While line breaks are usually represented in visual media by physically moving
+  subsequent text to a new line, a style sheet or user agent would be equally justified in causing
+  line breaks to be rendered in a different manner, for instance as green dots, or as extra
+  spacing.

+
+  
br elements must be used only for line breaks that are actually part of the
+  content, as in poems or addresses.

+
+  

+
+  
The following example is correct usage of the br element:

+
+   
<p>P. Sherman<br>
+42 Wallaby Way<br>
+Sydney</p>

+
+  

+
+  
br elements must not be used for separating thematic groups in a paragraph.

+
+  

+
+   
The following examples are non-conforming, as they abuse the br element:

+
+   
<p><a ...>34 comments.</a><br>
+<a ...>Add a comment.</a></p>

+
+   
<p><label>Name: <input name="name"></label><br>
+<label>Address: <input name="address"></label></p>

+
+   
Here are alternatives to the above, which are correct:

+
+   
<p><a ...>34 comments.</a></p>
+<p><a ...>Add a comment.</a></p>

+
+   
<p><label>Name: <input name="name"></label></p>
+<p><label>Address: <input name="address"></label></p>

+
+  

+
+  
If a paragraph consists of nothing but a single br element, it
+  represents a placeholder blank line (e.g. as in a template). Such blank lines must not be used for
+  presentation purposes.

+
+  
+
+  
Any content inside br elements must not be considered part of the surrounding
+  text.

+
+  
This element has rendering requirements involving the
+  bidirectional algorithm.

+
+  
+
+
+  
4.5.28 The wbr element
Support: wbr-elementChrome for Android 57+Chrome 4+UC Browser for Android 11.4+iOS Safari 5.0+Firefox 2+IE NoneSamsung Internet 4+Opera Mini all+Android Browser 2.3+Edge 12+Safari 3.2+Opera 9.5+
Source: caniuse.com

+
+  
Categories:
Flow content.
Phrasing content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

+
+  
The wbr element represents a line break opportunity.

+
+  

+
+   
In the following example, someone is quoted as saying something which, for effect, is written
+   as one long word. However, to ensure that the text can be wrapped in a readable fashion, the
+   individual words in the quote are separated using a wbr element.

+
+   
<p>So then she pointed at the tiger and screamed
+"there<wbr>is<wbr>no<wbr>way<wbr>you<wbr>are<wbr>ever<wbr>going<wbr>to<wbr>catch<wbr>me"!</p>

+
+  

+
+  
+
+   
Any content inside wbr elements must not be considered part of the surrounding
+   text.

+
+   
var wbr = document.createElement("wbr");
+wbr.textContent = "This is wrong";
+document.body.appendChild(wbr);

+
+   
This element has rendering requirements involving the
+   bidirectional algorithm.

+
+  
+
+
+
+  
4.5.29 Usage summary

+
+  
This section is non-normative.

+
+  
Element
+     Purpose
+     Example
+   
a
+     Hyperlinks
+     
Visit my <a href="drinks.html">drinks</a> page.

+
+    
em
+     Stress emphasis
+     
I must say I <em>adore</em> lemonade.

+
+    
strong
+     Importance
+     
This tea is <strong>very hot</strong>.

+
+    
small
+     Side comments
+     
These grapes are made into wine. <small>Alcohol is addictive.</small>

+
+    
s
+     Inaccurate text
+     
Price: <s>£4.50</s> £2.00!

+
+    
cite
+     Titles of works
+     
The case <cite>Hugo v. Danielle</cite> is relevant here.

+
+    
q
+     Quotations
+     
The judge said <q>You can drink water from the fish tank</q> but advised against it.

+
+    
dfn
+     Defining instance
+     
The term <dfn>organic food</dfn> refers to food produced without synthetic chemicals.

+
+    
abbr
+     Abbreviations
+     
Organic food in Ireland is certified by the <abbr title="Irish Organic Farmers and Growers Association">IOFGA</abbr>.

+
+    
ruby, rt, rp
+     Ruby annotations
+     
<ruby> OJ <rp>(<rt>Orange Juice<rp>)</ruby>

+
+    
data
+     Machine-readable equivalent
+     
Available starting today! <data value="UPC:022014640201">North Coast Organic Apple Cider</data>

+
+    
time
+     Machine-readable equivalent of date- or time-related data
+     
Available starting on <time datetime="2011-11-18">November 18th</time>!

+
+    
code
+     Computer code
+     
The <code>fruitdb</code> program can be used for tracking fruit production.

+
+    
var
+     Variables
+     
If there are <var>n</var> fruit in the bowl, at least <var>n</var>÷2 will be ripe.

+
+    
samp
+     Computer output
+     
The computer said <samp>Unknown error -3</samp>.

+
+    
kbd
+     User input
+     
Hit <kbd>F1</kbd> to continue.

+
+    
sub
+     Subscripts
+     
Water is H<sub>2</sub>O.

+
+    
sup
+     Superscripts
+     
The Hydrogen in heavy water is usually <sup>2</sup>H.

+
+    
i
+     Alternative voice
+     
Lemonade consists primarily of <i>Citrus limon</i>.

+
+    
b
+     Keywords
+     
Take a <b>lemon</b> and squeeze it with a <b>juicer</b>.

+
+    
u
+     Annotations
+     
The mixture of apple juice and <u class="spelling">eldeflower</u> juice is very pleasant.

+
+    
mark
+     Highlight
+     
Elderflower cordial, with one <mark>part</mark> cordial to ten <mark>part</mark>s water, stands a<mark>part</mark> from the rest.

+
+    
bdi
+     Text directionality isolation
+     
The recommended restaurant is <bdi lang="">My Juice Café (At The Beach)</bdi>.

+
+    
bdo
+     Text directionality formatting
+     
The proposal is to write English, but in reverse order. "Juice" would become "<bdo dir=rtl>Juice</bdo>"

+
+    
span
+     Other
+     
In French we call it <span lang="fr">sirop de sureau</span>.

+
+    
br
+     Line break
+     
Simply Orange Juice Company<br>Apopka, FL 32703<br>U.S.A.

+
+    
wbr
+     Line breaking opportunity
+     
www.simply<wbr>orange<wbr>juice.com

+
+  

+
+
+
+  
+
+  
4.6.1 Introduction

+
+  
Links are a conceptual construct, created by a, area, and
+  link elements, that represent a connection between
+  two resources, one of which is the current Document. There are two kinds of links in
+  HTML:

+
+  
Links to
+   external resources
These are links to resources that are to be used to augment the current document,
+   generally automatically processed by the user agent.
Hyperlinks
These are links to other resources that are generally exposed to the user by the user
+   agent so that the user can cause the user agent to navigate to those resources, e.g.
+   to visit them in a browser or download them.

+
+  
For link elements with an href attribute and a
+  rel attribute, links must be created for the keywords of the
+  rel attribute, as defined for those keywords in the link types section.

+
+  
Similarly, for a and area elements with an href attribute and a rel attribute, links must be created for the keywords of the
+  rel attribute as defined for those keywords in the link types section. Unlike link elements, however,
+  a and area elements with an href
+  attribute that either do not have a rel attribute, or
+  whose rel attribute has no keywords that are defined as
+  specifying hyperlinks, must also create a hyperlink.
+  This implied hyperlink has no special meaning (it has no link type)
+  beyond linking the element's node document to the resource given by the element's href attribute.

+
+  
A hyperlink can have one or more hyperlink
+  annotations that modify the processing semantics of that hyperlink.

+
+
+  
+
+  
The href attribute on a and
+  area elements must have a value that is a valid URL potentially surrounded by
+  spaces.

+
+  
The href attribute on a and
+  area elements is not required; when those elements do not have href attributes they do not create hyperlinks.

+
+  
The target attribute, if present, must be
+  a valid browsing context name or keyword. It gives the name of the browsing
+  context that will be used. User agents use this name when
+  following hyperlinks.

+
+  
When an a or area element's activation behavior is
+  invoked, the user agent may allow the user to indicate a preference regarding whether the
+  hyperlink is to be used for navigation or whether the resource it
+  specifies is to be downloaded.

+
+  
In the absence of a user preference, the default should be navigation if the element has no
+  download attribute, and should be to download the
+  specified resource if it does.

+
+  
Whether determined by the user's preferences or via the presence or absence of the attribute,
+  if the decision is to use the hyperlink for navigation then the user
+  agent must follow the hyperlink, and if the decision is
+  to use the hyperlink to download a resource, the user agent must download the hyperlink. These terms are defined in subsequent sections
+  below.

+
+  
The download attribute, if present,
+  indicates that the author intends the hyperlink to be used for downloading a resource. The attribute may have a value; the value, if any,
+  specifies the default file name that the author recommends for use in labeling the resource in a
+  local file system. There are no restrictions on allowed values, but authors are cautioned that
+  most file systems have limitations with regard to what punctuation is supported in file names,
+  and user agents are likely to adjust file names accordingly.

+
+
+  
The ping attribute, if present,
+  gives the URLs of the resources that are interested in being notified if the user follows the
+  hyperlink. The value must be a set of space-separated tokens, each of which must be a
+  valid non-empty URL whose scheme is an
+  HTTP(S) scheme. The value is used by the user agent for hyperlink
+  auditing.
Support: pingChrome for Android 57+Chrome 15+UC Browser for Android 11.4+iOS Safari 5.0+Firefox NoneIE NoneSamsung Internet 4+Opera Mini NoneAndroid Browser 4.4+Edge NoneSafari 6+Opera 15+
Source: caniuse.com

+
+  
The rel attribute on a and
+  area elements controls what kinds of links the elements create. The attribute's value
+  must be a set of space-separated tokens. The allowed keywords
+  and their meanings are defined below.

+
+  
rel's
+  supported tokens are the keywords defined in
+  HTML link types which are allowed on a and
+  area elements, impact the processing model, and are supported by the user agent. The
+  possible supported tokens are
+  noreferrer and
+  noopener.
+  rel's
+  supported tokens must only include the tokens from
+  this list that the user agent implements the processing model for.

+
+  
Other specifications may add HTML link types as defined in Other link types, with the following additional requirements:

+
+  
  • Such specifications may require that their link types be included in rel's supported
+   tokens.
  • Such specifications may specify that their link types are body-ok.

+
+  
The rel attribute has no default value. If the
+  attribute is omitted or if none of the values in the attribute are recognized by the user agent,
+  then the document has no particular relationship with the destination resource other than there
+  being a hyperlink between the two.

+
+  
The hreflang attribute on
+  a elements that create hyperlinks, if present, gives
+  the language of the linked resource. It is purely advisory. The value must be a valid BCP 47
+  language tag. [BCP47] User agents must not consider this attribute
+  authoritative — upon fetching the resource, user agents must use only language information
+  associated with the resource to determine its language, not metadata included in the link to the
+  resource.

+
+  
The type attribute, if present, gives the
+  MIME type of the linked resource. It is purely advisory. The value must be a
+  valid MIME type. 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.

+
+  
The referrerpolicy attribute
+  is a referrer policy attribute. Its purpose is to set the referrer policy
+  used when following hyperlinks. [REFERRERPOLICY]

+
+
+  
4.6.3 API for a and area elements

+
+  
[NoInterfaceObject]
+interface HTMLHyperlinkElementUtils {
+  [CEReactions] stringifier attribute USVString href;
+  readonly attribute USVString origin;
+  [CEReactions] attribute USVString protocol;
+  [CEReactions] attribute USVString username;
+  [CEReactions] attribute USVString password;
+  [CEReactions] attribute USVString host;
+  [CEReactions] attribute USVString hostname;
+  [CEReactions] attribute USVString port;
+  [CEReactions] attribute USVString pathname;
+  [CEReactions] attribute USVString search;
+  [CEReactions] attribute USVString hash;
+};

+
+  
hyperlink . toString()
hyperlink . href

+    
Returns the hyperlink's URL.

+    
Can be set, to change the URL.

+   
hyperlink . origin

+    
Returns the hyperlink's URL's origin.

+   
hyperlink . protocol

+    
Returns the hyperlink's URL's scheme.

+    
Can be set, to change the URL's scheme.

+   
hyperlink . username

+    
Returns the hyperlink's URL's username.

+    
Can be set, to change the URL's username.

+   
hyperlink . password

+    
Returns the hyperlink's URL's password.

+    
Can be set, to change the URL's password.

+   
hyperlink . host

+    
Returns the hyperlink's URL's host and port (if different from the default port for the
+    scheme).

+    
Can be set, to change the URL's host and port.

+   
hyperlink . hostname

+    
Returns the hyperlink's URL's host.

+    
Can be set, to change the URL's host.

+   
hyperlink . port

+    
Returns the hyperlink's URL's port.

+    
Can be set, to change the URL's port.

+   
hyperlink . pathname

+    
Returns the hyperlink's URL's path.

+    
Can be set, to change the URL's path.

+   
hyperlink . search

+    
Returns the hyperlink's URL's query (includes leading "?" if
+    non-empty).

+    
Can be set, to change the URL's query (ignores leading "?").

+   
hyperlink . hash

+    
Returns the hyperlink's URL's fragment (includes leading "#" if
+    non-empty).

+    
Can be set, to change the URL's fragment (ignores leading "#").

+   

+
+  
+
+  
An element implementing the HTMLHyperlinkElementUtils mixin has an associated url (null or a URL). It is initially null.
+
+  
An element implementing the HTMLHyperlinkElementUtils mixin has an associated set the url algorithm, which runs these steps:

+
+  
  1. If this element's href content attribute is
+    absent, set this element's url to null.
  2. Otherwise, parse this element's href content
+    attribute value relative to this element's node document. If parsing is successful, set this element's url to the result; otherwise, set this element's
+    url to null.

+
+  
When elements implementing the HTMLHyperlinkElementUtils mixin are created, and
+  whenever those elements have their href content
+  attribute set, changed, or removed, the user agent must set the url.

+
+  
This is only observable for blob: URLs as
+  parsing them involves a Blob URL Store lookup.

+
+  
An element implementing the HTMLHyperlinkElementUtils mixin has an associated
+  reinitialize url algorithm, which runs these
+  steps:

+
+  
  1. If element's url is non-null, its scheme is "blob", and its
+   cannot-be-a-base-URL flag is set, terminate these steps.
  2. Set the url.

+
+  
To update href, set the element's href content attribute's value to the element's url, serialized.

+
+  

+
+  
The href attribute's getter must run these
+  steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url is null and this element has no href content attribute, return the empty string.
+
+   
  4. Otherwise, if url is null, return this element's href content attribute's value.
  5. Return url, serialized.

+
+  
The href attribute's setter must set this element's
+  href content attribute's value to the given value.
+
+  
The origin attribute's getter must run
+  these steps:

+
+  
  1. Reinitialize url.
  2. If this element's url is null, return the
+   empty string.
  3. Return the serialization of this
+   element's url's origin.

+
+  
The protocol attribute's getter must
+  run these steps:

+
+  
  1. Reinitialize url.
  2. If this element's url is null, return ":".
  3. Return this element's url's scheme, followed by ":".

+
+  
The protocol attribute's setter must run these
+  steps:

+
+  
  1. Reinitialize url.
  2. If this element's url is null, terminate these
+   steps.
  3. 
+    
    Basic URL parse the given value, followed by
+    ":", with this element's url
+    as url and scheme start state as state override.
    
+
+    
    Because the URL parser ignores multiple consecutive colons, providing a value
+    of "https:" (or even "https::::") is the same as
+    providing a value of "https".
    
+   
  4. Update href.

+
+  
The username attribute's getter must
+  run these steps:

+
+  
  1. Reinitialize url.
  2. If this element's url is null, return the
+   empty string.
  3. Return this element's url's username.

+
+  
The username attribute's setter must run these
+  steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url is null or url
+   cannot have a username/password/port, then return.
  4. Set the username, given url and the given value.
  5. Update href.

+
+  
The password attribute's getter must
+  run these steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url is null, then return the empty string.
  4. Return url's password.

+
+  
The password attribute's setter must run these
+  steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url is null or url
+   cannot have a username/password/port, then return.
  4. Set the password, given url and the given value.
  5. Update href.

+
+  
The host attribute's getter must run these
+  steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url or url's host is null,
+   return the empty string.
  4. If url's port is null, return
+   url's host, serialized.
  5. Return url's host, serialized, followed by ":" and url's port, serialized.

+
+  
The host attribute's setter must run these steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url is null or url's cannot-be-a-base-URL flag is
+   set, terminate these steps.
  4. Basic URL parse the given value, with
+   url as url and host state as state
+   override.
  5. Update href.

+
+  
The hostname attribute's getter must
+  run these steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url or url's host is null,
+   return the empty string.
  4. Return url's host, serialized.

+
+  
The hostname attribute's setter must run these
+  steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url is null or url's cannot-be-a-base-URL flag is
+   set, terminate these steps.
  4. Basic URL parse the given value, with
+   url as url and hostname state as state
+   override.
  5. Update href.

+
+  
The port attribute's getter must run these
+  steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url or url's port is null,
+   return the empty string.
  4. Return url's port, serialized.

+
+  
The port attribute's setter must run these steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url is null or url
+   cannot have a username/password/port, then return.
  4. If the given value is the empty string, then set url's port to null.
  5. Otherwise, basic URL parse the given value, with
+   url as url and port state as state
+   override.
  6. Update href.

+
+  
The pathname attribute's getter must
+  run these steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url is null, return the empty string.
  4. If url's cannot-be-a-base-URL flag is set, return the first string
+   in url's path.
  5. If url's path is empty, then return the
+   empty string.
  6. Return "/", followed by the strings in url's path (including empty strings), separated from each other by
+   "/".

+
+  
The pathname attribute's setter must run these
+  steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url is null or url's cannot-be-a-base-URL flag is
+   set, terminate these steps.
  4. Set url's path to the empty
+   list.
  5. Basic URL parse the given value, with
+   url as url and path start state as state
+   override.
  6. Update href.

+
+  
The search attribute's getter must run
+  these steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url is null, or url's query is either null or the empty string, return the empty
+   string.
  4. Return "?", followed by url's query.

+
+  
The search attribute's setter must run these
+  steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url is null, terminate these steps.
  4. If the given value is the empty string, set url's query to null.
+
+   
  5. 
+    
    Otherwise:
    
+
+    
    1. Let input be the given value with a single leading "?"
+     removed, if any.
    2. Set url's query to the empty
+     string.
    3. Basic URL parse input, with
+     url as url and query state as state override, and
+     this element's node document's document's character encoding as
+     encoding override.
    
+   
  6. Update href.

+
+  
The hash attribute's getter must run these
+  steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url is null, or url's fragment is either null or the empty string, return the
+   empty string.
  4. Return "#", followed by url's fragment.

+
+  
The hash attribute's setter must run these steps:

+
+  
  1. Reinitialize url.
  2. Let url be this element's url.
  3. If url is null, then return.
  4. If the given value is the empty string, set url's fragment to null.
+
+   
  5. 
+    
    Otherwise:
    
+
+    
    1. Let input be the given value with a single leading "#"
+     removed, if any.
    2. Set url's fragment to the empty
+     string.
    3. Basic URL parse input, with
+     url as url and fragment state as state
+     override.
    
+   
  6. Update href.

+
+
+  
Spec bugs: 28925

+
+  
When a user follows a hyperlink created by an element
+  subject, optionally with a hyperlink suffix, the user agent must run the
+  following steps:

+
+  
  1. Let replace be false.
  2. Let source be subject's node document's browsing context.
  3. Let targetAttributeValue be null.
  4. If subject is an a or area element that has a target attribute, then set targetAttributeValue
+   to that attribute's value.
  5. Otherwise, if subject is an a or area element with no
+   target attribute, but subject's node
+   document contains a base element with a target attribute, then set targetAttributeValue to
+   the value of target attribute of the first such
+   base element.
  6. Let target and replace be the result of applying the rules for
+   choosing a browsing context given targetAttributeValue and
+   source.
  7. If target is null, then return.
  8. If subject's link types include the noreferrer or noopener keyword,
+   and replace is true, then disown
+   target's opener.
  9. Parse the URL given by subject's
+   href attribute, relative to subject's
+   node document.
  10. 
+
+    
    If that is successful, let URL be the resulting URL string.
    
+
+    
    Otherwise, if parsing the URL failed, the
+    user agent may report the error to the user in a user-agent-specific manner, may queue a
+    task to navigate the target
+    browsing context to an error page to report the error, or may ignore the error and
+    do nothing. In any case, the user agent must then abort these steps.
    
+
+   
  11. If there is a hyperlink suffix, append it to URL.
  12. Let resource be a new request whose url is URL and whose referrer policy is the current state of
+   subject's referrerpolicy content attribute.
  13. Queue a task to navigate the
+   target browsing context to resource. If replace is
+   true, the navigation must be performed with replacement enabled. The
+   source browsing context must be source.

+
+  
The task source for the tasks mentioned above is the DOM manipulation task
+  source.

+
+  
+
+
+
+
+  
4.6.5 Downloading resources
Support: downloadChrome for Android 57+Chrome 14+UC Browser for Android 11.4+iOS Safari NoneFirefox 20+IE NoneSamsung Internet 4+Opera Mini NoneAndroid Browser 4.4+Edge 13+Safari 10.1+Opera 15+
Source: caniuse.com

+
+  
In some cases, resources are intended for later use rather than immediate viewing. To indicate
+  that a resource is intended to be downloaded for use later, rather than immediately used, the
+  download attribute can be specified on the
+  a or area element that creates the hyperlink to that
+  resource.

+
+  
The attribute can furthermore be given a value, to specify the file name that user agents are
+  to use when storing the resource in a file system. This value can be overridden by the `Content-Disposition` HTTP header's filename parameters.
+  [RFC6266]

+
+  
In cross-origin situations, the download
+  attribute has to be combined with the `Content-Disposition` HTTP header, specifically with the
+  attachment disposition type, to avoid the user being warned of possibly
+  nefarious activity. (This is to protect users from being made to download sensitive personal or
+  confidential information without their full understanding.)

+
+  
+
+  

+
+  
When a user downloads a hyperlink created by an
+  element subject, optionally with a hyperlink suffix, the user agent must
+  run the following steps:

+
+  
  1. Parse the URL given by
+   subject's href attribute, relative to
+   subject's node document.
  2. If parsing the URL fails, the user agent
+   may report the error to the user in a user-agent-specific manner, may
+   navigate to an error page to report the error, or may
+   ignore the error and do nothing. In either case, the user agent must abort these steps.
    
+
+   
  3. Otherwise, let URL be the resulting URL string.
  4. If there is a hyperlink suffix, append it to URL.
  5. Return to whatever algorithm invoked these steps and continue
+   these steps in parallel.
  6. Let request be a new request whose
+   url is URL,
+   client is entry settings object,
+   initiator is "download",
+   destination is the empty string, and whose
+   synchronous flag and use-URL-credentials flag are set.
+
+   
  7. Handle the result of fetching
+   request as a download.

+
+  
When a user agent is to handle a resource obtained from a fetch as a download, it
+  should provide the user with a way to save the resource for later use, if a resource is
+  successfully obtained; or otherwise should report any problems downloading the file to the
+  user.

+
+  
If the user agent needs a file name for a resource being handled as a download, it
+  should select one using the following algorithm.

+
+  
This algorithm is intended to mitigate security dangers involved in downloading
+  files from untrusted sites, and user agents are strongly urged to follow it.
 
+
+  
  1. Let filename be the void value.
  2. If the resource has a `Content-Disposition`
+   header, that header specifies the attachment disposition type, and the
+   header includes file name information, then let filename have the value
+   specified by the header, and jump to the step labeled sanitize below. [RFC6266]
  3. Let interface origin be the origin of the
+   Document in which the download or
+   navigate action resulting in the download was initiated, if any.
  4. Let resource origin be the origin of the URL of the
+   resource being downloaded, unless that URL's scheme
+   component is data, in which case let resource origin be
+   the same as the interface origin, if any.
  5. If there is no interface origin, then let trusted
+   operation be true. Otherwise, let trusted operation be true if resource origin is the same origin as interface
+   origin, and false otherwise.
  6. If trusted operation is true and the resource has a `Content-Disposition` header and that header includes file
+   name information, then let filename have the value specified by the header,
+   and jump to the step labeled sanitize below. [RFC6266]
  7. If the download was not initiated from a hyperlink created by an
+   a or area element, or if the element of the hyperlink from
+   which it was initiated did not have a download
+   attribute when the download was initiated, or if there was such an attribute but its value when
+   the download was initiated was the empty string, then jump to the step labeled no proposed
+   file name.
  8. Let proposed filename have the value of the download attribute of the element of the
+   hyperlink that initiated the download at the time the download was
+   initiated.
  9. If trusted operation is true, let filename have
+   the value of proposed filename, and jump to the step labeled sanitize
+   below.
  10. If the resource has a `Content-Disposition`
+   header and that header specifies the attachment disposition type, let filename have the value of proposed filename, and jump to the
+   step labeled sanitize below. [RFC6266]
  11. No proposed file name: If trusted operation is true, or if the
+   user indicated a preference for having the resource in question downloaded, let filename have a value derived from the URL of the resource in a
+   user-agent-defined manner, and jump to the step labeled sanitize below.
  12. 
+
+    
    Act in a user-agent-defined manner to safeguard the user from a potentially hostile
+    cross-origin download. If the download is not to be aborted, then let filename be set to the user's preferred file name or to a file name selected by
+    the user agent, and jump to the step labeled sanitize below.
    
+
+    
    
+
+     
    If the algorithm reaches this step, then a download was begun from a different origin than
+     the resource being downloaded, and the origin did not mark the file as suitable for
+     downloading, and the download was not initiated by the user. This could be because a download attribute was used to trigger the download, or
+     because the resource in question is not of a type that the user agent supports.
    
+
+     
    This could be dangerous, because, for instance, a hostile server could be trying to get a
+     user to unknowingly download private information and then re-upload it to the hostile server,
+     by tricking the user into thinking the data is from the hostile server.
    
+
+     
    Thus, it is in the user's interests that the user be somehow notified that the resource in
+     question comes from quite a different source, and to prevent confusion, any suggested file name
+     from the potentially hostile interface origin should be ignored.
    
+
+    
    
+
+   
  13. Sanitize: Optionally, allow the user to influence filename. For
+   example, a user agent could prompt the user for a file name, potentially providing the value of
+   filename as determined above as a default value.
  14. 
+
+    
    Adjust filename to be suitable for the local file system.
    
+
+    
    For example, this could involve removing characters that are not legal in
+    file names, or trimming leading and trailing whitespace.
    
+
+   
  15. If the platform conventions do not in any way use extensions to determine the types of file on the file system,
+   then return filename as the file name and abort these steps.
  16. Let claimed type be the type given by the resource's Content-Type metadata, if any is known. Let named
+   type be the type given by filename's extension, if any is known. For the purposes of this step, a
+   type is a mapping of a MIME type to an extension.
  17. If named type is consistent with the user's preferences (e.g. because
+   the value of filename was determined by prompting the user), then return filename as the file name and abort these steps.
  18. If claimed type and named type are the same type
+   (i.e. the type given by the resource's Content-Type metadata is
+   consistent with the type given by filename's extension), then return filename as the file
+   name and abort these steps.
  19. 
+
+    
    If the claimed type is known, then alter filename to
+    add an extension corresponding to claimed
+    type.
    
+
+    
    Otherwise, if named type is known to be potentially dangerous (e.g. it
+    will be treated by the platform conventions as a native executable, shell script, HTML
+    application, or executable-macro-capable document) then optionally alter filename to add a known-safe extension
+    (e.g. ".txt").
    
+
+    
    This last step would make it impossible to download executables, which might not
+    be desirable. As always, implementors are forced to balance security and usability in this
+    matter.
    
+
+   
  20. Return filename as the file name.

+
+  
For the purposes of this algorithm, a file extension
+  consists of any part of the file name that platform conventions dictate will be used for
+  identifying the type of the file. For example, many operating systems use the part of the file
+  name following the last dot (".") in the file name to determine the type of
+  the file, and from that the manner in which the file is to be opened or executed.

+
+  
User agents should ignore any directory or path information provided by the resource itself,
+  its URL, and any download attribute, in
+  deciding where to store the resulting file in the user's file system.

+
+  
+
+
+
+
+  
+
+  
Spec bugs: 24137

+
+  
If a hyperlink created by an a or area element has a
+  ping attribute, and the user follows the hyperlink, and
+  the value of the element's href attribute can be parsed, relative to the element's node document, without
+  failure, then the user agent must take the ping
+  attribute's value, split that string on ASCII
+  whitespace, parse each resulting token relative to the
+  element's node document, and then run these steps for each resulting URL
+  record ping URL, ignoring tokens that fail to parse:

+
+  
  1. If ping URL's scheme is not an
+   HTTP(S) scheme, then abort these steps.
  2. Optionally, abort these steps. (For example, the user agent might wish to ignore any or
+   all ping URLs in accordance with the user's expressed preferences.)
  3. Let request be a new request whose
+   url is ping URL, method is `POST`, body is `PING`, client is the environment settings object of
+   the Document containing the hyperlink, destination is the empty string,
+   credentials mode is "include", referrer is "no-referrer", and whose use-URL-credentials flag is set.
  4. 
+    
    Let target URL be the resulting URL string obtained from parsing the value of the element's href attribute and then:
    
+
+    
    If the URL of the Document object
+     containing the hyperlink being audited and ping URL have the same
+     origin
    If the origins are different, but the HTTPS
+     state of the Document containing the hyperlink being audited is "none"
    request must include a `Ping-From` header
+     with, as its value, the URL of the document
+     containing the hyperlink, and a `Ping-To` HTTP header with,
+     as its value, the target URL.
    Otherwise
    request must include a `Ping-To` HTTP header
+     with, as its value, target URL.  request does not
+     include a `Ping-From` header.
    
+   
  5. Fetch request.

+
+  
This may be done in parallel with the primary fetch, and is independent of the
+  result of that fetch.

+
+  
User agents should allow the user to adjust this behavior, for example in conjunction with a
+  setting that disables the sending of HTTP `Referer` (sic)
+  headers. Based on the user's preferences, UAs may either ignore the ping attribute altogether, or selectively ignore URLs in the
+  list (e.g. ignoring any third-party URLs); this is explicitly accounted for in the steps
+  above.

+
+  
User agents must ignore any entity bodies returned in the responses. User agents may close the
+  connection prematurely once they start receiving a response body.

+
+  
When the ping attribute is present, user agents
+  should clearly indicate to the user that following the hyperlink will also cause secondary
+  requests to be sent in the background, possibly including listing the actual target URLs.

+
+  
For example, a visual user agent could include the hostnames of the target ping
+  URLs along with the hyperlink's actual URL in a status bar or tooltip.

+
+  
+
+  

+
+   
The ping attribute is redundant with pre-existing
+   technologies like HTTP redirects and JavaScript in allowing Web pages to track which off-site
+   links are most popular or allowing advertisers to track click-through rates.

+
+   
However, the ping attribute provides these advantages
+   to the user over those alternatives:

+
+   
  • It allows the user to see the final target URL unobscured.
  • It allows the UA to inform the user about the out-of-band notifications.
  • It allows the user to disable the notifications without losing the underlying link
+    functionality.
  • It allows the UA to optimize the use of available network bandwidth so that the target page
+    loads faster.

+
+   
Thus, while it is possible to track users without this feature, authors are encouraged to use
+   the ping attribute so that the user agent can make the
+   user experience more transparent.

+
+  

+
+  
+
+
+
+  
4.6.6 Link types

+
+  
The following table summarizes the link types that are defined by this specification, by their
+  corresponding keywords. This table is non-normative; the actual definitions for the link types are
+  given in the next few sections.

+
+  
In this section, the term referenced document refers to the resource identified by the
+  element representing the link, and the term current document refers to the resource within
+  which the element representing the link finds itself.

+
+  
+
+  
To determine which link types apply to a link, a, or
+  area element, the element's rel attribute must be split on ASCII whitespace. The resulting tokens
+  are the keywords for the link types that apply to that element.

+
+  
+
+  
Except where otherwise specified, a keyword must not be specified more than once per rel attribute.

+
+  
Some of the sections that follow the table below list synonyms for certain keywords. The
+  indicated synonyms are to be handled as specified by user agents, but must
+  not be used in documents (for example, the keyword "copyright").

+
+  
Keywords are always ASCII case-insensitive, and must be
+  compared as such.

+
+  
Thus, rel="next" is the same as rel="NEXT".

+
+  
Keywords that are body-ok affect whether link elements are
+  allowed in the body. The body-ok keywords defined by this specification
+  are
+  dns-prefetch,
+  pingback,
+  preconnect,
+  prefetch,
+  preload,
+  prerender, and
+  stylesheet.
+  Other specifications can also define body-ok keywords.

+
+  
Link typeEffect on...body-okBrief description
linka and area
alternateHyperlinkHyperlink · Gives alternate representations of the current document.
canonicalHyperlinknot allowed · Gives the preferred URL for the current document.
authorHyperlinkHyperlink · Gives a link to the author of the current document or article.
bookmarknot allowedHyperlink · Gives the permalink for the nearest ancestor section.
dns-prefetchExternal Resourcenot allowed Yes Specifies that the user agent should preemptively perform DNS resolution for the target resource's origin.
externalnot allowedAnnotation · Indicates that the referenced document is not part of the same site as the current document.
helpHyperlinkHyperlink · Provides a link to context-sensitive help.
iconExternal Resourcenot allowed · Imports an icon to represent the current document.
licenseHyperlinkHyperlink · Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
nextHyperlinkHyperlink · Indicates that the current document is a part of a series, and that the next document in the series is the referenced document.
nofollownot allowedAnnotation · Indicates that the current document's original author or publisher does not endorse the referenced document.
noopenernot allowedAnnotation · Requires any browsing context created by following the hyperlink to disown its opener.
noreferrernot allowedAnnotation · Requires that the user agent not send an HTTP `Referer` (sic) header if the user follows the hyperlink.
pingbackExternal Resourcenot allowed Yes Gives the address of the pingback server that handles pingbacks to the current document.
preconnectExternal Resourcenot allowed Yes Specifies that the user agent should preemptively connect to the target resource's origin.
prefetchExternal Resourcenot allowed Yes Specifies that the user agent should preemptively fetch and cache the target resource as it is likely to be required for a followup navigation.
preloadExternal Resourcenot allowed Yes Specifies that the user agent must preemptively fetch and cache the target resource for current navigation according to the destination given by the as attribute (and the priority associated with that destination).
prerenderExternal Resourcenot allowed Yes Specifies that the user agent should preemptively fetch the target resource and process it in a way that helps deliver a faster response in the future.
prevHyperlinkHyperlink · Indicates that the current document is a part of a series, and that the previous document in the series is the referenced document.
searchHyperlinkHyperlink · Gives a link to a resource that can be used to search through the current document and its related pages.
serviceworkerHyperlinknot allowed · Declares a service worker registration.
stylesheetExternal Resourcenot allowed Yes Imports a stylesheet.
tagnot allowedHyperlink · Gives a tag (identified by the given address) that applies to the current document.

+
+  
+
+
+  
4.6.6.1 Link type "alternate"

+
+  
The alternate keyword may be used with link,
+  a, and area elements.

+
+  
The meaning of this keyword depends on the values of the other attributes.

+
+  
If the element is a link element and the rel
+   attribute also contains the keyword stylesheet

+
+    
The alternate keyword modifies the meaning of the stylesheet keyword in the way described for that keyword. The
+    alternate keyword does not create a link of its own.

+
+    

+
+     
Here, a set of link elements provide some style sheets:

+
+     
<!-- a persistent style sheet -->
+<link rel="stylesheet" href="default.css">
+
+<!-- the preferred alternate style sheet -->
+<link rel="stylesheet" href="green.css" title="Green styles">
+
+<!-- some alternate style sheets -->
+<link rel="alternate stylesheet" href="contrast.css" title="High contrast">
+<link rel="alternate stylesheet" href="big.css" title="Big fonts">
+<link rel="alternate stylesheet" href="wide.css" title="Wide screen">

+
+    

+
+   
If the alternate keyword is used with the type attribute set to the value application/rss+xml or the value application/atom+xml

+
+    
The keyword creates a hyperlink referencing a syndication feed (though not
+    necessarily syndicating exactly the same content as the current page).

+
+    
+
+    
For the purposes of feed autodiscovery, user agents should consider all link
+    elements in the document with the alternate keyword used and
+    with their type attribute set to the value application/rss+xml or the value application/atom+xml. If the user agent has the concept of a default
+    syndication feed, the first such element (in tree order) should be used as the
+    default.

+
+    
+
+    

+     
The following link elements give syndication feeds for a blog:

+
+     
<link rel="alternate" type="application/atom+xml" href="posts.xml" title="Cool Stuff Blog">
+<link rel="alternate" type="application/atom+xml" href="posts.xml?category=robots" title="Cool Stuff Blog: robots category">
+<link rel="alternate" type="application/atom+xml" href="comments.xml" title="Cool Stuff Blog: Comments">

+
+     
Such link elements would be used by user agents engaged in feed autodiscovery,
+     with the first being the default (where applicable).

+
+     
The following example offers various different syndication feeds to the user, using
+     a elements:

+
+     
<p>You can access the planets database using Atom feeds:</p>
+<ul>
+ <li><a href="recently-visited-planets.xml" rel="alternate" type="application/atom+xml">Recently Visited Planets</a></li>
+ <li><a href="known-bad-planets.xml" rel="alternate" type="application/atom+xml">Known Bad Planets</a></li>
+ <li><a href="unexplored-planets.xml" rel="alternate" type="application/atom+xml">Unexplored Planets</a></li>
+</ul>

+
+     
These links would not be used in feed autodiscovery.

+    

+
+   
Otherwise

+
+    
The keyword creates a hyperlink referencing an alternate representation of the
+    current document.

+
+    
The nature of the referenced document is given by the hreflang, and type attributes.

+
+    
If the alternate keyword is used with the hreflang attribute, and that attribute's value differs
+    from the document element's language, it indicates that the referenced
+    document is a translation.

+
+    
If the alternate keyword is used with the type attribute, it indicates that the referenced document is
+    a reformulation of the current document in the specified format.

+
+    
The hreflang and type attributes can be combined when specified with the alternate keyword.

+
+    

+
+     
The following example shows how you can specify versions of the page that use alternative
+     formats, are aimed at other languages, and that are intended for other media:

+
+     
<link rel=alternate href="/en/html" hreflang=en type=text/html title="English HTML">
+<link rel=alternate href="/fr/html" hreflang=fr type=text/html title="French HTML">
+<link rel=alternate href="/en/html/print" hreflang=en type=text/html media=print title="English HTML (for printing)">
+<link rel=alternate href="/fr/html/print" hreflang=fr type=text/html media=print title="French HTML (for printing)">
+<link rel=alternate href="/en/pdf" hreflang=en type=application/pdf title="English PDF">
+<link rel=alternate href="/fr/pdf" hreflang=fr type=application/pdf title="French PDF">

+
+    

+
+    
This relationship is transitive — that is, if a document links to two other documents
+    with the link type "alternate", then, in addition to implying
+    that those documents are alternative representations of the first document, it is also implying
+    that those two documents are alternative representations of each other.

+
+   

+
+
+
+  
+
+  
The author keyword may be used with link,
+  a, and area elements. This keyword creates a hyperlink.

+
+  
For a and area elements, the author
+  keyword indicates that the referenced document provides further information about the author of
+  the nearest article element ancestor of the element defining the hyperlink, if there
+  is one, or of the page as a whole, otherwise.

+
+  
For link elements, the author keyword indicates
+  that the referenced document provides further information about the author for the page as a
+  whole.

+
+  
The "referenced document" can be, and often is, a mailto: URL giving the e-mail address of the author. [MAILTO]

+
+  
+
+  
Synonyms: For historical reasons, user agents must also treat
+  link, a, and area elements that have a rev attribute with the value "made" as having the author keyword specified as a link relationship.

+
+  
+
+
+  
+
+  
The bookmark keyword may be used with a and
+  area elements. This keyword creates a hyperlink.

+
+  
The bookmark keyword gives a permalink for the nearest
+  ancestor article element of the linking element in question, or of the section the linking element is most closely associated with, if
+  there are no ancestor article elements.

+
+  

+
+   
The following snippet has three permalinks. A user agent could determine which permalink
+   applies to which part of the spec by looking at where the permalinks are given.

+
+   
 ...
+ <body>
+  <h1>Example of permalinks</h1>
+  <div id="a">
+   <h2>First example</h2>
+   <p><a href="a.html" rel="bookmark">This permalink applies to
+   only the content from the first H2 to the second H2</a>. The DIV isn't
+   exactly that section, but it roughly corresponds to it.</p>
+  </div>
+  <h2>Second example</h2>
+  <article id="b">
+   <p><a href="b.html" rel="bookmark">This permalink applies to
+   the outer ARTICLE element</a> (which could be, e.g., a blog post).</p>
+   <article id="c">
+    <p><a href="c.html" rel="bookmark">This permalink applies to
+    the inner ARTICLE element</a> (which could be, e.g., a blog comment).</p>
+   </article>
+  </article>
+ </body>
+ ...

+
+  

+
+
+  
+
+  
The canonical keyword may be used with link
+  element. This keyword creates a hyperlink.

+
+  
The canonical keyword indicates that URL given by the href attribute is the preferred URL for the current document. That
+  helps search engines reduce duplicate content, as described in more detail in The Canonical
+  Link Relation specification. [RFC6596]

+
+
+  
+
+  
The dns-prefetch keyword may be used with
+  link elements. This keyword creates an external
+  resource link. This keyword is body-ok.

+
+  
The dns-prefetch keyword indicates that preemptively
+  performing DNS resolution for the origin of the specified resource is likely to be
+  beneficial, as it is highly likely that the user will require resources located at that
+  origin, and the user experience would be improved by preempting the latency costs
+  associated with DNS resolution. User agents must implement the processing model of
+  the dns-prefetch keyword described in the Resource
+  Hints specification. [RESOURCEHINTS]

+
+  
There is no default type for resources given by the dns-prefetch keyword.

+
+
+  
+  
+
+  
The external keyword may be used with a and
+  area elements. This keyword does not create a hyperlink, but annotates any other hyperlinks created by the element (the
+  implied hyperlink, if no other keywords create one).

+
+  
The external keyword indicates that the link is leading to a
+  document that is not part of the site that the current document forms a part of.

+
+
+  
+
+  
The help keyword may be used with link,
+  a, and area elements. This keyword creates a hyperlink.

+
+  
For a and area elements, the help
+  keyword indicates that the referenced document provides further help information for the parent of
+  the element defining the hyperlink, and its children.

+
+  

+
+   
In the following example, the form control has associated context-sensitive help. The user
+   agent could use this information, for example, displaying the referenced document if the user
+   presses the "Help" or "F1" key.

+
+   
 <p><label> Topic: <input name=topic> <a href="help/topic.html" rel="help">(Help)</a></label></p>

+
+  

+
+  
For link elements, the help keyword indicates that
+  the referenced document provides help for the page as a whole.

+
+  
For a and area elements, on some browsers, the help keyword causes the link to use a different cursor.

+
+
+  
4.6.6.8 Link type "icon"
Support: link-icon-pngChrome for Android 57+Chrome 4+UC Browser for Android 11.4+iOS Safari NoneFirefox 2+IE 11+Samsung Internet 4+Opera Mini NoneAndroid Browser 2.1+Edge 12+Safari 3.1+Opera 9+
Source: caniuse.com

+
+  
The icon keyword may be used with link elements.
+  This keyword creates an external resource link.

+
+  
+
+  
The specified resource is an icon representing the page or site, and should be used by the user
+  agent when representing the page in the user interface.

+
+  
+
+  
Icons could be auditory icons, visual icons, or other kinds of icons. If
+  multiple icons are provided, the user agent must select the most appropriate icon according to the
+  type, media, and sizes attributes. If there are multiple equally appropriate icons,
+  user agents must use the last one declared in tree order at the time that the user
+  agent collected the list of icons. If the user agent tries to use an icon but that icon is
+  determined, upon closer examination, to in fact be inappropriate (e.g. because it uses an
+  unsupported format), then the user agent must try the next-most-appropriate icon as determined by
+  the attributes.

+
+  
+
+  
User agents are not required to update icons when the list of icons changes, but
+  are encouraged to do so.

+
+  
There is no default type for resources given by the icon keyword.
+  However, for the purposes of determining the type of the
+  resource, user agents must expect the resource to be an image.

+
+  
+
+  
The sizes keywords represent icon sizes in raw pixels (as
+  opposed to CSS pixels).

+
+  
An icon that is 50 CSS pixels wide intended for
+  displays with a device pixel density of two device pixels per CSS pixel
+  (2x, 192dpi) would have a width of 100 raw pixels. This feature does not support indicating that a
+  different resource is to be used for small high-resolution icons vs large low-resolution icons
+  (e.g. 50×50 2x vs 100×100 1x).

+
+  
+
+  
To parse and process the attribute's value, the user agent must first split the attribute's value on ASCII whitespace, and must then
+  parse each resulting keyword to determine what it represents.

+
+  
+
+  
The any keyword represents that the
+  resource contains a scalable icon, e.g. as provided by an SVG image.

+
+  
+
+  
Other keywords must be further parsed as follows to determine what they represent:

+
+  
  • If the keyword doesn't contain exactly one U+0078 LATIN SMALL LETTER X or U+0058 LATIN
+   CAPITAL LETTER X character, then this keyword doesn't represent anything. Abort these steps for
+   that keyword.
  • Let width string be the string before the "x" or
+   "X".
  • Let height string be the string after the "x" or
+   "X".
  • If either width string or height string start with
+   a U+0030 DIGIT ZERO (0) character or contain any characters other than ASCII digits,
+   then this keyword doesn't represent anything. Abort these steps for that keyword.
  • Apply the rules for parsing non-negative integers to width
+   string to obtain width.
  • Apply the rules for parsing non-negative integers to height
+   string to obtain height.
  • The keyword represents that the resource contains a bitmap icon with a width of width device pixels and a height of height device
+   pixels.

+
+  
+
+  
The keywords specified on the sizes attribute must not
+  represent icon sizes that are not actually available in the linked resource.

+
+  
+
+  
In the absence of a link with the icon keyword, for
+  Document objects whose URL's
+  scheme is an HTTP(S) scheme, user agents may
+  instead run these steps in parallel:

+
+  
  1. Let request be a new request whose
+   url is the URL record obtained by
+   resolving the URL "/favicon.ico" against the
+   Document object's URL, client is the Document object's
+   relevant settings object, type is "image", destination is "image", synchronous flag is set, credentials mode is "include", and whose use-URL-credentials flag is set.
  2. Let response be the result of fetching request.
  3. Use response's unsafe response as an icon as if it had been
+   declared using the icon keyword.

+
+  
+
+  

+
+   
The following snippet shows the top part of an application with several icons.

+
+   
<!DOCTYPE HTML>
+<html lang="en">
+ <head>
+  <title>lsForums — Inbox</title>
+  <link rel=icon href=favicon.png sizes="16x16" type="image/png">
+  <link rel=icon href=windows.ico sizes="32x32 48x48" type="image/vnd.microsoft.icon">
+  <link rel=icon href=mac.icns sizes="128x128 512x512 8192x8192 32768x32768">
+  <link rel=icon href=iphone.png sizes="57x57" type="image/png">
+  <link rel=icon href=gnome.svg sizes="any" type="image/svg+xml">
+  <link rel=stylesheet href=lsforums.css>
+  <script src=lsforums.js></script>
+  <meta name=application-name content="lsForums">
+ </head>
+ <body>
+  ...

+
+  

+
+  
For historical reasons, the icon keyword may be preceded by the
+  keyword "shortcut". If the "shortcut" keyword is
+  present, the rel attribute's entire value must be an
+  ASCII case-insensitive match for the string "shortcut icon" (with a single U+0020 SPACE character between the tokens and
+  no other ASCII whitespace).

+
+
+  
+
+  
The license keyword may be used with link,
+  a, and area elements. This keyword creates a hyperlink.

+
+  
The license keyword indicates that the referenced document
+  provides the copyright license terms under which the main content of the current document is
+  provided.

+
+  
This specification does not specify how to distinguish between the main content of a document
+  and content that is not deemed to be part of that main content. The distinction should be made
+  clear to the user.

+
+  

+
+   
Consider a photo sharing site. A page on that site might describe and show a photograph, and
+   the page might be marked up as follows:

+
+   
<!DOCTYPE HTML>
+<html lang="en">
+ <head>
+  <title>Exampl Pictures: Kissat</title>
+  <link rel="stylesheet" href="/style/default">
+ </head>
+ <body>
+  <h1>Kissat</h1>
+  <nav>
+   <a href="../">Return to photo index</a>
+  </nav>
+  <figure>
+   <img src="/pix/39627052_fd8dcd98b5.jpg">
+   <figcaption>Kissat</figcaption>
+  </figure>
+  <p>One of them has six toes!</p>
+  <p><small><a rel="license" href="http://www.opensource.org/licenses/mit-license.php">MIT Licensed</a></small></p>
+  <footer>
+   <a href="/">Home</a> | <a href="../">Photo index</a>
+   <p><small>© copyright 2009 Exampl Pictures. All Rights Reserved.</small></p>
+  </footer>
+ </body>
+</html>

+
+   
In this case the license applies to just the photo (the main
+   content of the document), not the whole document. In particular not the design of the page
+   itself, which is covered by the copyright given at the bottom of the document. This could be made
+   clearer in the styling (e.g. making the license link prominently positioned near the photograph,
+   while having the page copyright in light small text at the foot of the page).

+
+  

+
+  
+
+  
Synonyms: For historical reasons, user agents must also treat the keyword
+  "copyright" like the license keyword.

+
+  
+
+
+  
+
+  
The nofollow keyword may be used with a and
+  area elements. This keyword does not create a hyperlink, but annotates any other hyperlinks created by the element (the
+  implied hyperlink, if no other keywords create one).

+
+  
The nofollow keyword indicates that the link is not endorsed
+  by the original author or publisher of the page, or that the link to the referenced document was
+  included primarily because of a commercial relationship between people affiliated with the two
+  pages.

+
+
+  
Support: rel-noopenerChrome for Android 57+Chrome 49+UC Browser for Android NoneiOS Safari 10.3+Firefox 52+IE NoneSamsung Internet NoneOpera Mini NoneAndroid Browser 56+Edge NoneSafari 10.1+Opera 36+
Source: caniuse.com

+
+  
The noopener keyword may be used with a and
+  area elements. This keyword does not create a hyperlink, but annotates any other hyperlinks created by the element (the
+  implied hyperlink, if no other keywords create one).

+
+  
The keyword indicates that any newly created browsing context which results from
+  following the hyperlink will have disowned its opener, which means that
+  its window.opener property will be null.

+
+
+  
Support: rel-noreferrerChrome for Android 57+Chrome 16+UC Browser for Android 11.4+iOS Safari 4.0+Firefox 33+IE (limited) 11+Samsung Internet 4+Opera Mini NoneAndroid Browser 2.3+Edge 13+Safari 5+Opera 15+
Source: caniuse.com

+
+  
The noreferrer keyword may be used with a and
+  area elements. This keyword does not create a hyperlink, but annotates any other hyperlinks created by the element (the
+  implied hyperlink, if no other keywords create one).

+
+  
It indicates that no referrer information is to be leaked when following the link.

+
+  
+
+  
If a user agent follows a link defined by an a or area element that
+  has the noreferrer keyword, the user agent must set their
+  request's referrer to "no-referrer".

+
+  
For historical reasons, the noreferrer
+  keyword implies the behavior associated with the noopener
+  keyword when present on a hyperlink that creates a new browsing context. That is, <a
+  href="..." rel="noreferrer" target="_blank"> has the same behavior as <a href="..." rel="noreferrer noopener" target="_blank">.

+
+  
+
+  
+
+  
+
+  
The pingback keyword may be used with link
+  elements. This keyword creates an external resource
+  link. This keyword is body-ok.

+
+  
For the semantics of the pingback keyword, see the Pingback
+  1.0 specification. [PINGBACK]

+
+
+  
+
+  
The preconnect keyword may be used with link
+  elements. This keyword creates an external resource
+  link. This keyword is body-ok.

+
+  
The preconnect keyword indicates that preemptively
+  initiating a connection to the origin of the specified resource is likely to be
+  beneficial, as it is highly likely that the user will require resources located at that
+  origin, and the user experience would be improved by preempting the latency costs
+  associated with establishing the connection. User agents must implement the
+  processing model of the preconnect keyword described in
+  Resource Hints. [RESOURCEHINTS]

+
+  
There is no default type for resources given by the preconnect keyword.

+
+
+  
+
+  
The prefetch keyword may be used with link
+  elements. This keyword creates an external resource
+  link. This keyword is body-ok.

+
+  
The prefetch keyword indicates that preemptively fetching and caching the specified resource is likely to be
+  beneficial, as it is highly likely that the user will require this resource for future
+  navigations. User agents must implement the processing model of the prefetch keyword described in Resource Hints.
+  [RESOURCEHINTS]

+
+  
There is no default type for resources given by the prefetch
+  keyword.

+
+
+  
+
+  
The preload keyword may be used with link
+  elements. This keyword creates an external resource
+  link. This keyword is body-ok.

+
+  
The preload keyword indicates that the user agent must
+  preemptively fetch and cache the specified resource according
+  to the destination given by the as attribute (and the priority associated with that destination), as it is highly likely that the user
+  will require this resource for the current navigation. User agents must implement
+  the processing model of the preload keyword described in
+  Preload. [PRELOAD]

+
+  
There is no default type for resources given by the preload
+  keyword.

+
+
+  
+
+  
The prerender keyword may be used with link
+  elements. This keyword creates an external resource
+  link. This keyword is body-ok.

+
+  
The prerender keyword indicates that the specified resource
+  might be required by the next navigation, and so it may be beneficial to not only preemptively
+  fetch the resource, but also to process it, e.g. by fetching its subresources or performing some rendering. User agents must implement the processing model of the prerender keyword described in Resource Hints.
+  [RESOURCEHINTS]

+
+  
There is no default type for resources given by the prerender keyword.

+
+
+  
+
+  
The search keyword may be used with link,
+  a, and area elements. This keyword creates a hyperlink.

+
+  
The search keyword indicates that the referenced document
+  provides an interface specifically for searching the document and its related resources.

+
+  
OpenSearch description documents can be used with link elements and
+  the search link type to enable user agents to autodiscover search
+  interfaces. [OPENSEARCH]

+
+  
+
+  
The serviceworker keyword may be used with
+  link elements. This keyword creates an external
+  resource link that is used to declare a service worker registration and its
+  script url, scope url, type,
+  and use cache setting.

+
+  
User agents must implement the processing model for link-element
+  serviceworker links described in Service
+  Workers, using the href, scope, workertype, and
+  usecache attributes. [SW]

+
+
+  
+
+  
The stylesheet keyword may be used with link
+  elements. This keyword creates an external resource
+  link that contributes to the styling processing model. This keyword is
+  body-ok.

+
+  
The specified resource is a resource that describes how to present the document. Exactly how
+  the resource is to be processed depends on the actual type of the resource.

+
+  
If the alternate keyword is also specified on the
+  link element, then the link is an alternative stylesheet; in this case,
+  the title attribute must be specified on the link
+  element, with a non-empty value.

+
+  
The default type for resources given by the stylesheet
+  keyword is text/css.

+
+  
+
+  
The appropriate times to obtain the resource are:
+
+  
+  

+
+  
Quirk: If the document has been set to quirks mode, has the
+  same origin as the URL of the external resource,
+  and the Content-Type metadata of the external resource is not a
+  supported style sheet type, the user agent must instead assume it to be text/css.

+
+  
Once a resource has been obtained, if its Content-Type metadata is text/css, the user
+  agent must run these steps:

+
+  
+  
+
+  
  1. Let element be the link element that created the
+   external resource link.
  2. If element has an associated CSS style sheet, remove the CSS style sheet in question.
  3. If element no longer creates an external resource link
+   that contributes to the styling processing model, or if, since the resource in question was obtained, it has become appropriate to obtain it again (meaning this algorithm is about to be
+   invoked again for a newly obtained resource), then abort these steps.
  4. 
+
+    
    Create a CSS style sheet with the following properties:
    
+
+    
    type
    text/css
    location
    
+
+      
    The resulting URL string determined during the obtain algorithm.
    
+
+      
    This is before any redirects get applied.
    
+
+     
    owner node
    element
    media
    
+
+      
    The media attribute of element.
    
+
+      
    This is a reference to the (possibly absent at this time) attribute, rather
+      than a copy of the attribute's current value. The CSSOM specification defines what happens
+      when the attribute is dynamically set, changed, or removed.
    
+
+     
    title
    
+
+      
    The title attribute of element, if
+      element is in a document tree, or the empty string otherwise.
    
+
+      
    This is similarly a reference to the attribute, rather than a copy of the
+      attribute's current value.
    
+
+     
    alternate flag
    Set if the link is an alternative stylesheet; unset otherwise.
    origin-clean flag
    Set if the resource is CORS-same-origin; unset otherwise.
    parent CSS style sheet
    owner CSS rule
    null
    disabled flag
    Left at its default value.
    CSS rules
    Left uninitialized.
    
+
+    
    The CSS environment encoding is the result of running the following steps: [CSSSYNTAX]
    
+
+    
    1. If the element has a charset attribute, get an encoding from that attribute's value. If that
+     succeeds, return the resulting encoding and abort these steps. [ENCODING]
    2. Otherwise, return the document's character encoding. [DOM]
    
+
+   

+
+  
+
+
+
+  
+
+  
The tag keyword may be used with a and
+  area elements. This keyword creates a hyperlink.

+
+  
The tag keyword indicates that the tag that the
+  referenced document represents applies to the current document.

+
+  
Since it indicates that the tag applies to the current document, it would
+  be inappropriate to use this keyword in the markup of a tag cloud, which
+  lists the popular tags across a set of pages.

+
+  

+
+   
This document is about some gems, and so it is tagged with "https://en.wikipedia.org/wiki/Gemstone" to unambiguously categorize it as applying
+   to the "jewel" kind of gems, and not to, say, the towns in the US, the Ruby package format, or
+   the Swiss locomotive class:

+
+   
<!DOCTYPE HTML>
+<html lang="en">
+ <head>
+  <title>My Precious</title>
+ </head>
+ <body>
+  <header><h1>My precious</h1> <p>Summer 2012</p></header>
+  <p>Recently I managed to dispose of a red gem that had been
+  bothering me. I now have a much nicer blue sapphire.</p>
+  <p>The red gem had been found in a bauxite stone while I was digging
+  out the office level, but nobody was willing to haul it away. The
+  same red gem stayed there for literally years.</p>
+  <footer>
+   Tags: <a rel=tag href="https://en.wikipedia.org/wiki/Gemstone">Gemstone</a>
+  </footer>
+ </body>
+</html>

+
+  

+
+  

+
+   
In this document, there are two articles. The "tag"
+   link, however, applies to the whole page (and would do so wherever it was placed, including if it
+   was within the article elements).

+
+   
<!DOCTYPE HTML>
+<html lang="en">
+ <head>
+  <title>Gem 4/4</title>
+ </head>
+ <body>
+  <article>
+   <h1>801: Steinbock</h1>
+   <p>The number 801 Gem 4/4 electro-diesel has an ibex and was rebuilt in 2002.</p>
+  </article>
+  <article>
+   <h1>802: Murmeltier</h1>
+   <figure>
+    <img src="https://upload.wikimedia.org/wikipedia/commons/b/b0/Trains_de_la_Bernina_en_hiver_2.jpg"
+         alt="The 802 was red with pantographs and tall vents on the side.">
+    <figcaption>The 802 in the 1980s, above Lago Bianco.</figcaption>
+   </figure>
+   <p>The number 802 Gem 4/4 electro-diesel has a marmot and was rebuilt in 2003.</p>
+  </article>
+  <p class="topic"><a rel=tag href="https://en.wikipedia.org/wiki/Rhaetian_Railway_Gem_4/4">Gem 4/4</a></p>
+ </body>
+</html>

+
+  

+
+
+
+  
+
+  
Some documents form part of a sequence of documents.

+
+  
A sequence of documents is one where each document can have a previous sibling and a
+  next sibling. A document with no previous sibling is the start of its sequence, a
+  document with no next sibling is the end of its sequence.

+
+  
A document may be part of multiple sequences.

+
+
+  
+
+  
The next keyword may be used with link,
+  a, and area elements. This keyword creates a hyperlink.

+
+  
The next keyword indicates that the document is part of a
+  sequence, and that the link is leading to the document that is the next logical document in the
+  sequence.

+
+  
When the next keyword is used with a link
+  element, user agents should implement one of the processing models described in Resource
+  Hints, i.e. should process such links as if they were using one of the dns-prefetch, preconnect,
+  prefetch, or prerender
+  keywords. Which resource hint the user agent wishes to use is implementation-dependent; for
+  example, a user agent may wish to use the less-costly preconnect hint when trying to conserve data, battery power, or
+  processing power, or may wish to pick a resource hint depending on heuristic analysis of past
+  user behavior in similar scenarios. [RESOURCEHINTS]

+
+
+  
+
+  
The prev keyword may be used with link,
+  a, and area elements. This keyword creates a hyperlink.

+
+  
The prev keyword indicates that the document is part of a
+  sequence, and that the link is leading to the document that is the previous logical document in
+  the sequence.

+
+  
+
+  
Synonyms: For historical reasons, user agents must also treat the keyword
+  "previous" like the prev keyword.

+
+  
+
+
+  
+
+  
Extensions to the predefined set of link types may be
+  registered in the microformats
+  wiki existing-rel-values page. [MFREL]

+
+  
Anyone is free to edit the microformats wiki existing-rel-values page at
+  any time to add a type. Extension types must be specified with the following information:

+
+  
Keyword

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

+
+    
If the value contains a U+003A COLON character (:), it must also be an absolute
+    URL.

+
+   
Effect on... link

+
+    
One of the following:

+
+    
Not allowed
The keyword must not be specified on link elements.
Hyperlink
The keyword may be specified on a link element; it creates a
+     hyperlink.
External Resource
The keyword may be specified on a link element; it creates an external
+     resource link.

+
+   
Effect on... a and area

+
+    
One of the following:

+
+    
Not allowed
The keyword must not be specified on a and area elements.
Hyperlink
The keyword may be specified on a and area elements; it creates a
+     hyperlink.
External Resource
The keyword may be specified on a and area elements; it creates
+     an external resource link.
Hyperlink Annotation
The keyword may be specified on a and area elements; it annotates other hyperlinks
+     created by the element.

+
+   
Brief description
A short non-normative description of what the keyword's meaning is.
Specification
A link to a more detailed description of the keyword's semantics and requirements. It
+   could be another page on the Wiki, or a link to an external page.
Synonyms
A list of other keyword values that have exactly the same processing requirements. Authors
+   should not use the values defined to be synonyms, they are only intended to allow user agents to
+   support legacy content. Anyone may remove synonyms that are not used in practice; only names that
+   need to be processed as synonyms for compatibility with legacy content are to be registered in
+   this way.
Status

+
+    
One of the following:

+
+    
Proposed
The keyword has not received wide peer review and approval. Someone has proposed it and is,
+     or soon will be, using it.
Ratified
The keyword has received wide peer review and approval. It has a specification that
+     unambiguously defines how to handle pages that use the keyword, including when they use it in
+     incorrect ways.
Discontinued
The keyword 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 "specification"
+     entries will give details of what authors should use instead, if anything.

+
+    
If a keyword is found to be redundant with existing values, it should be removed and listed
+    as a synonym for the existing value.

+
+    
If a keyword is registered in the "proposed" state for a period of a month or more without
+    being used or specified, then it may be removed from the registry.

+
+    
If a keyword is added with the "proposed" status and found to be redundant with existing
+    values, it should be removed and listed as a synonym for the existing value. If a keyword is
+    added with the "proposed" status and found to be harmful, then it should be changed to
+    "discontinued" status.

+
+    
Anyone can change the status at any time, but should only do so in accordance with the
+    definitions above.

+
+   

+
+  
+
+  
Conformance checkers must use the information given on the microformats wiki
+  existing-rel-values page to establish if a value is allowed or not: values defined in this
+  specification or marked as "proposed" or "ratified" must be accepted when used on the elements for
+  which they apply as described in the "Effect on..." field, whereas values marked as "discontinued"
+  or not listed in either this specification or on the aforementioned page must be rejected as
+  invalid. Conformance checkers may cache this information (e.g. for performance reasons or to avoid
+  the use of unreliable network connectivity).

+
+  
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 "proposed" status.

+
+  
+
+  
Types defined as extensions in the microformats
+  wiki existing-rel-values page with the status "proposed" or "ratified" may be used with the
+  rel attribute on link, a, and area
+  elements in accordance to the "Effect on..." field. [MFREL]

+
+
+
+  
4.7 Edits

+
+  
The ins and del elements represent edits to the document.

+
+
+  
4.7.1 The ins element
Spec bugs: 28555

+
+  
Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Transparent.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
cite — Link to the source of the quotation or more information about the edit
datetime — Date and (optionally) time of the change
DOM interface:
Uses the HTMLModElement interface.

+
+  
The ins element represents an addition to the document.

+
+  

+
+   
The following represents the addition of a single paragraph:

+
+   
<aside>
+ <ins>
+  <p> I like fruit. </p>
+ </ins>
+</aside>

+
+   
As does the following, because everything in the aside element here counts as
+   phrasing content and therefore there is just one paragraph:

+
+   
<aside>
+ <ins>
+  Apples are <em>tasty</em>.
+ </ins>
+ <ins>
+  So are pears.
+ </ins>
+</aside>

+
+  

+
+  
ins elements should not cross implied paragraph
+  boundaries.

+
+  

+
+   
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.

+
+   
<aside>
+ <!-- don't do this -->
+ <ins datetime="2005-03-16 00:00Z">
+  <p> I like fruit. </p>
+  Apples are <em>tasty</em>.
+ </ins>
+ <ins datetime="2007-12-19 00:00Z">
+  So are pears.
+ </ins>
+</aside>

+
+   
Here is a better way of marking this up. It uses more elements, but none of the elements cross
+   implied paragraph boundaries.

+
+   
<aside>
+ <ins datetime="2005-03-16 00:00Z">
+  <p> I like fruit. </p>
+ </ins>
+ <ins datetime="2005-03-16 00:00Z">
+  Apples are <em>tasty</em>.
+ </ins>
+ <ins datetime="2007-12-19 00:00Z">
+  So are pears.
+ </ins>
+</aside>

+
+   
+
+  

+
+
+  
4.7.2 The del element

+
+  
Categories:
Flow content.
Phrasing content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Transparent.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
cite — Link to the source of the quotation or more information about the edit
datetime — Date and (optionally) time of the change
DOM interface:
Uses the HTMLModElement interface.

+
+  
The del element represents a removal from the document.

+
+  
del elements should not cross implied paragraph
+  boundaries.

+
+  

+
+   
The following shows a "to do" list where items that have been done are crossed-off with the
+   date and time of their completion.

+
+   
<h1>To Do</h1>
+<ul>
+ <li>Empty the dishwasher</li>
+ <li><del datetime="2009-10-11T01:25-07:00">Watch Walter Lewin's lectures</del></li>
+ <li><del datetime="2009-10-10T23:38-07:00">Download more tracks</del></li>
+ <li>Buy a printer</li>
+</ul>

+
+  

+
+
+
+  
4.7.3 Attributes common to ins and del elements

+
+  
The cite attribute may be used to specify the
+  URL of a document that explains the change. When that
+  document is long, for instance the minutes of a meeting, authors are encouraged to include a fragment pointing to the specific part of that document that
+  discusses the change.

+
+  
If the cite attribute is present, it must be a valid
+  URL potentially surrounded by spaces that explains the change. To obtain
+  the corresponding citation link, the value of the attribute must be parsed relative to the element's node document. User agents may
+  allow users to follow such citation links, but they are primarily intended for private use (e.g.,
+  by server-side scripts collecting statistics about a site's edits), not for readers.

+
+
+  
The datetime attribute may be used to specify
+  the time and date of the change.

+
+  
If present, the datetime attribute's value must be a
+  valid date string with optional time.

+
+  
+
+  
User agents must parse the datetime attribute according
+  to the parse a date or time string algorithm. If that doesn't return a date or a global date and time,
+  then the modification has no associated timestamp (the value is non-conforming; it is not a
+  valid date string with optional time). Otherwise, the modification is marked as
+  having been made at the given date or global date and time. If the given value is a global date and time then user agents should use the associated
+  time-zone offset information to determine which time zone to present the given datetime in.

+
+  
+
+  
This value may be shown to the user, but it is primarily intended for
+  private use.

+
+  
The ins and del elements must implement the
+  HTMLModElement interface:

+
+  
[HTMLConstructor]
+interface HTMLModElement : HTMLElement {
+  [CEReactions] attribute USVString cite;
+  [CEReactions] attribute DOMString dateTime;
+};

+
+  
+
+  
The cite IDL attribute must reflect
+  the element's cite content attribute. The dateTime IDL attribute must reflect the
+  element's datetime content attribute.

+
+  
+
+
+
+  
4.7.4 Edits and paragraphs

+
+  
This section is non-normative.

+
+  
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.
+ <!-- (don't do this) -->
+</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, as 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 encouraged to always mark
+  up all paragraphs with the p element, instead of having ins or
+  del elements that cross implied paragraphs
+  boundaries.

+
+
+  
4.7.5 Edits and lists

+
+  
This section is non-normative.

+
+  
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 emphasized show the parts that are the "current"
+   state of the list. The list item numbers don't take into account the edits, though.

+
+   
<h1>Stop-ship bugs</h1>
+<ol>
+ <li><ins datetime="2008-02-12T15:20Z">Bug 225:
+ Rain detector doesn't work in snow</ins></li>
+ <li><del datetime="2008-03-01T20:22Z"><ins datetime="2008-02-14T12:02Z">Bug 228:
+ Water buffer overflows in April</ins></del></li>
+ <li><ins datetime="2008-02-16T13:50Z">Bug 230:
+ Water heater doesn't use renewable fuels</ins></li>
+ <li><del datetime="2008-02-20T21:15Z"><ins datetime="2008-02-16T14:25Z">Bug 232:
+ Carbon dioxide emissions detected after startup</ins></del></li>
+</ol>

+
+  

+
+  

+
+   
In the following example, a list that started with just fruit was replaced by a list with just
+   colors.

+
+   
<h1>List of <del>fruits</del><ins>colors</ins></h1>
+<ul>
+ <li><del>Lime</del><ins>Green</ins></li>
+ <li><del>Apple</del></li>
+ <li>Orange</li>
+ <li><del>Pear</del></li>
+ <li><ins>Teal</ins></li>
+ <li><del>Lemon</del><ins>Yellow</ins></li>
+ <li>Olive</li>
+ <li><ins>Purple</ins></li>
+</ul>

+
+  

+
+
+  
4.7.6 Edits and tables

+
+  
This section is non-normative.

+
+  
The elements that form part of the table model have complicated content model requirements that
+  do not allow for the ins and del elements, so indicating edits to a
+  table can be difficult.

+
+  
To indicate that an entire row or an entire column has been added or removed, the entire
+  contents of each cell in that row or column can be wrapped in ins or del
+  elements (respectively).

+
+  

+
+   
Here, a table's row has been added:

+
+   
<table>
+ <thead>
+  <tr> <th> Game name           <th> Game publisher   <th> Verdict
+ <tbody>
+  <tr> <td> Diablo 2            <td> Blizzard         <td> 8/10
+  <tr> <td> Portal              <td> Valve            <td> 10/10
+  <tr> <td> <ins>Portal 2</ins> <td> <ins>Valve</ins> <td> <ins>10/10</ins>
+</table>

+
+   
Here, a column has been removed (the time at which it was removed is given also, as is a link
+   to the page explaining why):

+
+   
<table>
+ <thead>
+  <tr> <th> Game name           <th> Game publisher   <th> <del cite="/edits/r192" datetime="2011-05-02 14:23Z">Verdict</del>
+ <tbody>
+  <tr> <td> Diablo 2            <td> Blizzard         <td> <del cite="/edits/r192" datetime="2011-05-02 14:23Z">8/10</del>
+  <tr> <td> Portal              <td> Valve            <td> <del cite="/edits/r192" datetime="2011-05-02 14:23Z">10/10</del>
+  <tr> <td> Portal 2            <td> Valve            <td> <del cite="/edits/r192" datetime="2011-05-02 14:23Z">10/10</del>
+</table>

+
+  

+
+  
Generally speaking, there is no good way to indicate more complicated edits (e.g. that a cell
+  was removed, moving all subsequent cells up or to the left).

+
+
+
+
+  
4.8 Embedded content

+
+  
4.8.1 The picture element
Support: pictureChrome for Android 57+Chrome 38+UC Browser for Android 11.4+iOS Safari 9.3+Firefox 38+IE NoneSamsung Internet 4+Opera Mini NoneAndroid Browser 56+Edge 13+Safari 9.1+Opera 25+
Source: caniuse.com

+
+  
Categories:
Flow content.
Phrasing content.
Embedded content.
Contexts in which this element can be used:
Where embedded content is expected.
Content model:
Zero or more source elements, followed by one img element,
+   optionally intermixed with script-supporting elements.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
DOM interface:

+
[HTMLConstructor]
+interface HTMLPictureElement : HTMLElement {};

+   

+
+  
The picture element is a container
+  which provides multiple sources to its contained img element
+  to allow authors to declaratively control or give hints to the user agent about which image resource to use,
+  based on the screen pixel density, viewport size, image format, and other factors.
+  It represents its children.

+
+  
The picture element is somewhat different from the similar-looking
+  video and audio elements. While all of them contain source
+  elements, the source element's src attribute
+  has no meaning when the element is nested within a picture element, and the resource
+  selection algorithm is different. Also, the picture element itself does not display
+  anything; it merely provides a context for its contained img element that enables it
+  to choose from multiple URLs.

+
+
+  
4.8.2 The source element

+
+  
Categories:
None.
Contexts in which this element can be used:
As a child of a picture element, before the img element.
As a child of a media element, before any flow content or
+   track elements.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
src — Address of the resource
type — Type of embedded resource
srcset — Images to use in different situations (e.g. high-resolution displays, small monitors, etc)
sizes — Image sizes for different page layouts
media — Applicable media
DOM interface:

+
[HTMLConstructor]
+interface HTMLSourceElement : HTMLElement {
+  [CEReactions] attribute USVString src;
+  [CEReactions] attribute DOMString type;
+  [CEReactions] attribute USVString srcset;
+  [CEReactions] attribute DOMString sizes;
+  [CEReactions] attribute DOMString media;
+};

+   

+
+  
The source element allows authors to specify multiple alternative
+  source sets for img elements or multiple alternative
+  media resources for media
+  elements. It does not represent anything on its own.

+
+  
The type attribute may be present. If
+  present, the value must be a valid MIME type.

+
+  
The remainder of the requirements depend on whether the parent is a picture
+  element or a media element:

+
+  
source element's parent is a picture element

+    
The srcset attribute must be present, and
+    is a srcset attribute.

+
+    
The srcset attribute contributes the image sources to the source set, if the
+    source element is selected.

+
+    
If the srcset attribute has any image candidate strings using a width descriptor, the sizes attribute must also be present, and is a
+    sizes attribute. The sizes attribute
+    contributes the source size to the source set, if the
+    source element is selected.

+
+    
The media attributes may also be present.
+    If present, the value must contain a valid media query list. The user agent will
+    skip to the next source element if the value does not match the environment.

+
+    
The type gives the type of the images in the
+    source set, to allow the user agent to skip to the next source element
+    if it does not support the given type.

+
+    
If the type attribute is not
+    specified, the user agent will not select a different source element if it finds
+    that it does not support the image format after fetching it.

+
+    
When a source element has a following sibling source element or
+    img element with a srcset attribute
+    specified, it must have at least one of the following:

+
+    
+
+    
The src attribute must not be present.

+   
source element's parent is a media element

+    
The src attribute gives the URL
+    of the media resource. The value must be a valid non-empty URL potentially
+    surrounded by spaces. This attribute must be present.

+
+    
Dynamically modifying a source element and its attribute when the
+    element is already inserted in a video or audio element will have no
+    effect. To change what is playing, just use the src
+    attribute on the media element directly, possibly making use of the canPlayType() method to pick from amongst available
+    resources. Generally, manipulating source elements manually after the document has
+    been parsed is an unnecessarily complicated approach.

+
+    
The type attribute gives the type of the media
+    resource, to help the user agent determine if it can play this media
+    resource before fetching it. The codecs parameter, which certain
+    MIME types define, might be necessary to specify exactly how the resource is encoded. [RFC6381]

+
+    

+
+     
The following list shows some examples of how to use the codecs= MIME
+     parameter in the type attribute.

+
+     
H.264 Constrained baseline profile video (main and extended video compatible) level 3 and Low-Complexity AAC audio in MP4 container
<source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
H.264 Extended profile video (baseline-compatible) level 3 and Low-Complexity AAC audio in MP4 container
<source src='video.mp4' type='video/mp4; codecs="avc1.58A01E, mp4a.40.2"'>
H.264 Main profile video level 3 and Low-Complexity AAC audio in MP4 container
<source src='video.mp4' type='video/mp4; codecs="avc1.4D401E, mp4a.40.2"'>
H.264 'High' profile video (incompatible with main, baseline, or extended profiles) level 3 and Low-Complexity AAC audio in MP4 container
<source src='video.mp4' type='video/mp4; codecs="avc1.64001E, mp4a.40.2"'>
MPEG-4 Visual Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container
<source src='video.mp4' type='video/mp4; codecs="mp4v.20.8, mp4a.40.2"'>
MPEG-4 Advanced Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container
<source src='video.mp4' type='video/mp4; codecs="mp4v.20.240, mp4a.40.2"'>
MPEG-4 Visual Simple Profile Level 0 video and AMR audio in 3GPP container
<source src='video.3gp' type='video/3gpp; codecs="mp4v.20.8, samr"'>
Theora video and Vorbis audio in Ogg container
<source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'>
Theora video and Speex audio in Ogg container
<source src='video.ogv' type='video/ogg; codecs="theora, speex"'>
Vorbis audio alone in Ogg container
<source src='audio.ogg' type='audio/ogg; codecs=vorbis'>
Speex audio alone in Ogg container
<source src='audio.spx' type='audio/ogg; codecs=speex'>
FLAC audio alone in Ogg container
<source src='audio.oga' type='audio/ogg; codecs=flac'>
Dirac video and Vorbis audio in Ogg container
<source src='video.ogv' type='video/ogg; codecs="dirac, vorbis"'>

+    

+
+    
The srcset, sizes, and media
+    attributes must not be present.

+   

+
+  
+
+  
If a source element is inserted as a
+  child of a media element that has no src
+  attribute and whose networkState has the value NETWORK_EMPTY, the user agent must invoke the media
+  element's resource selection
+  algorithm.

+
+  
The IDL attributes src, type, srcset, sizes and media must reflect the respective
+  content attributes of the same name.

+
+  
+
+  

+   
If the author isn't sure if user agents will all be able to render the media resources
+   provided, the author can listen to the error event on the last
+   source element and trigger fallback behavior:

+
+   
<script>
+ function fallback(video) {
+   // replace <video> with its contents
+   while (video.hasChildNodes()) {
+     if (video.firstChild instanceof HTMLSourceElement)
+       video.removeChild(video.firstChild);
+     else
+       video.parentNode.insertBefore(video.firstChild, video);
+   }
+   video.parentNode.removeChild(video);
+ }
+</script>
+<video controls autoplay>
+ <source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
+ <source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'
+         onerror="fallback(parentNode)">
+ ...
+</video>

+  

+
+
+
+  
4.8.3 The img element
Spec bugs: 24055, 26068, 28096

+
+  
Categories:
Flow content.
Phrasing content.
Embedded content.
Form-associated element.
If the element has a usemap attribute: Interactive content.
Palpable content.
Contexts in which this element can be used:
Where embedded content is expected.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
alt — Replacement text for use when images are not available
src — Address of the resource
srcset — Images to use in different situations (e.g. high-resolution displays, small monitors, etc)
sizes — Image sizes for different page layouts
crossorigin — How the element handles crossorigin requests
usemap — Name of image map to use
ismap — Whether the image is a server-side image map
width — Horizontal dimension
height — Vertical dimension
referrerpolicy — Referrer policy for fetches initiated by the element
DOM interface:

+
[HTMLConstructor, NamedConstructor=Image(optional unsigned long width, optional unsigned long height)]
+interface HTMLImageElement : HTMLElement {
+  [CEReactions] attribute DOMString alt;
+  [CEReactions] attribute USVString src;
+  [CEReactions] attribute USVString srcset;
+  [CEReactions] attribute DOMString sizes;
+  [CEReactions] attribute DOMString? crossOrigin;
+  [CEReactions] attribute DOMString useMap;
+  [CEReactions] attribute boolean isMap;
+  [CEReactions] attribute unsigned long width;
+  [CEReactions] attribute unsigned long height;
+  readonly attribute unsigned long naturalWidth;
+  readonly attribute unsigned long naturalHeight;
+  readonly attribute boolean complete;
+  readonly attribute USVString currentSrc;
+  [CEReactions] attribute DOMString referrerPolicy;
+
+  // also has obsolete members
+};

+   

+
+  
An img element represents an image.

+
+  
+
+  
The image given by the src and srcset attributes, and any previous sibling
+  source elements' srcset attributes if the
+  parent is a picture element, is the embedded content; the value of the alt attribute provides equivalent content for those who
+  cannot process images or who have image loading disabled (i.e. it is the img
+  element's fallback content).
Support: srcsetChrome for Android 57+Chrome 38+UC Browser for Android 11.4+iOS Safari 9.0+Firefox 38+IE NoneSamsung Internet 4+Opera Mini NoneAndroid Browser 56+Edge NoneSafari 9+Opera 25+
Source: caniuse.com

+
+  
The requirements on the alt attribute's value are described
+  in a separate section.

+
+  
The src attribute must be present, and must contain a
+  valid non-empty URL potentially surrounded by spaces referencing a non-interactive,
+  optionally animated, image resource that is neither paged nor scripted.

+
+  
The requirements above imply that images can be static bitmaps (e.g. PNGs, GIFs,
+  JPEGs), single-page vector documents (single-page PDFs, XML files with an SVG document element),
+  animated bitmaps (APNGs, animated GIFs), animated vector graphics (XML files with an SVG
+  document element that use declarative SMIL animation), and so forth. However, these
+  definitions preclude SVG files with script, multipage PDF files, interactive MNG files, HTML
+  documents, plain text documents, and so forth. [PNG] [GIF] [JPEG] [PDF] [XML] [APNG] [SVG] [MNG] 

+
+  
The srcset attribute may also be present, and is a
+  srcset attribute.

+
+  
The srcset attribute and the src attribute (if width
+  descriptors are not used) contribute the image sources
+  to the source set (if no source element was selected).

+
+  
If the srcset attribute is present and has any image candidate strings using a width
+  descriptor, the sizes attribute must also
+  be present, and is a sizes attribute. The sizes
+  attribute contributes the source size to the source set (if no
+  source element was selected).

+
+  
The crossorigin attribute is a CORS
+  settings attribute. Its purpose is to allow images from third-party sites that allow
+  cross-origin access to be used with canvas.

+
+  
The referrerpolicy attribute is a
+  referrer policy attribute. Its purpose is to set the referrer policy
+  used when fetching the image. [REFERRERPOLICY]

+
+  

+
+  
The img element must not be used as a layout tool. In particular, img
+  elements should not be used to display transparent images, as such images rarely convey meaning and
+  rarely add anything useful to the document.

+
+  
+
+  

+
+  
What an img element represents depends on the src attribute and the alt
+  attribute.

+
+  
If the src attribute is set and the alt attribute is set to the empty string

+
+    
The image is either decorative or supplemental to the rest of the content, redundant with
+    some other information in the document.

+
+    
If the image is available and the user agent is configured
+    to display that image, then the element represents the element's image data.

+
+    
Otherwise, the element represents nothing, and may be omitted completely from
+    the rendering. User agents may provide the user with a notification that an image is present but
+    has been omitted from the rendering.

+
+   
If the src attribute is set and the alt attribute is set to a value that isn't empty

+
+    
The image is a key part of the content; the alt attribute
+    gives a textual equivalent or replacement for the image.

+
+    
If the image is available and the user agent is configured
+    to display that image, then the element represents the element's image data.

+
+    
Otherwise, the element represents the text given by the alt attribute. User agents may provide the user with a notification
+    that an image is present but has been omitted from the rendering.

+
+   
If the src attribute is set and the alt attribute is not

+
+    
The image might be a key part of the content, and there is no textual equivalent of the image
+    available.

+
+    
In a conforming document, the absence of the alt attribute indicates that the image is a key part of the content
+    but that a textual replacement for the image was not available when the image was generated.

+
+    
If the image is available and the user agent is configured
+    to display that image, then the element represents the element's image data.

+
+    
Otherwise, the user agent should display some sort of indicator that there is an image that
+    is not being rendered, and may, if requested by the user, or if so configured, or when required
+    to provide contextual information in response to navigation, provide caption information for the
+    image, derived as follows:

+
+    
  1. If the image has a title attribute whose value is not
+     the empty string, then the value of that attribute is the caption information; abort these
+     steps.
  2. If the image is a descendant of a figure element that has a child
+     figcaption element, and, ignoring the figcaption element and its
+     descendants, the figure element has no flow content descendants other
+     than inter-element whitespace and the img element, then the contents of the first such
+     figcaption element are the caption information; abort these steps.
  3. There is no caption information.

+
+   
If the src attribute is not set and either the alt attribute is set to the empty string or the alt attribute is not set at all

+
+    
The element represents nothing.

+
+   
Otherwise

+
+    
The element represents the text given by the alt attribute.

+
+   

+
+  
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.

+
+  
User agents may always provide the user with the option to display any image, or to prevent any
+  image from being displayed. User agents may also apply heuristics to help the user make use of the
+  image when the user is unable to see it, e.g. due to a visual disability or because they are using
+  a text terminal with no graphics capabilities. Such heuristics could include, for instance,
+  optical character recognition (OCR) of text found within the image.

+
+  
While user agents are encouraged to repair cases of missing alt attributes, authors must not rely on such behavior. Requirements for providing text to act as an alternative for images are described
+  in detail below.

+
+  
The contents of img elements, if any, are ignored for the purposes of
+  rendering.

+
+  
+
+  

+
+  
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 usemap and ismap attributes can result in confusing behavior when used
+  together with source elements with the media
+  attribute specified in a picture element.

+
+  
The img element supports dimension
+  attributes.

+
+  
+
+  
The alt, src, srcset and sizes IDL attributes must reflect the
+  respective content attributes of the same name.

+
+  
The crossOrigin IDL attribute must
+  reflect the crossorigin content attribute.

+
+  
The useMap IDL attribute must
+  reflect the usemap content attribute.

+
+  
The isMap IDL attribute must reflect
+  the ismap content attribute.

+
+  
The referrerPolicy IDL attribute must
+  reflect the referrerpolicy
+  content attribute, limited to only known values.

+
+  
+
+  
image . width [ = value ]
image . height [ = value ]

+
+
+    
These attributes return the actual rendered dimensions of the
+    image, or zero if the dimensions are not known.

+
+    
They can be set, to change the corresponding content
+    attributes.

+
+   
image . naturalWidth
image . naturalHeight

+
+
+    
These attributes return the intrinsic dimensions of the image,
+    or zero if the dimensions are not known.

+
+   
image . complete

+
+
+    
Returns true if the image has been completely downloaded or if
+    no image is specified; otherwise, returns false.

+
+   
image . currentSrc

+
+    
Returns the image's absolute URL.

+
+   
image = new Image( [ width [, height ] ] )

+
+
+    
Returns a new img element, with the width and height attributes set to the values
+    passed in the relevant arguments, if applicable.

+
+   

+
+  
+
+  
The IDL attributes width and height must return the rendered width and height of the
+  image, in CSS pixels, if the image is being rendered, and
+  is being rendered to a visual medium; or else the density-corrected intrinsic width and
+  height of the image, in CSS pixels, if the image has
+  intrinsic dimensions and is available but not being
+  rendered to a visual medium; or else 0, if the image is not available or does not have intrinsic dimensions. [CSS]

+
+  
On setting, they must act as if they reflected the respective
+  content attributes of the same name.

+
+  
The IDL attributes naturalWidth and
+  naturalHeight must return the
+  density-corrected intrinsic width and height of the image, in CSS pixels, if the image has intrinsic dimensions and is available, or else 0. [CSS]
Spec bugs: 23581
Support: img-naturalwidth-naturalheightChrome for Android 57+Chrome 4+UC Browser for Android 11.4+iOS Safari 3.2+Firefox 2+IE 9+Samsung Internet 4+Opera Mini all+Android Browser 2.1+Edge 12+Safari 3.1+Opera 9+
Source: caniuse.com

+
+  
The IDL attribute complete must return true if
+  any of the following conditions is true:
Spec bugs: 18742, 26113

+
+  
+
+  
Otherwise, the attribute must return false.

+
+  
The value of complete can thus change while
+  a script is executing.

+
+  
The currentSrc IDL attribute
+  must return the img element's current request's current URL.

+
+  
A constructor is provided for creating HTMLImageElement objects (in addition to
+  the factory methods from DOM such as createElement()): Image(width, height). When invoked,
+  the constructor must perform the following steps:

+
+  
  1. Let document be the current global object's associated Document.
  2. Let img be the result of creating an
+   element given document, img, and the HTML
+   namespace.
  3. If width is given, then set
+   an attribute value for img using "width"
+   and width.
  4. If height is given, then set an attribute value for img
+   using "height" and height.
  5. Return img.

+
+  
+
+  

+
+   
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
+   Carouge municipality in 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>She 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>She stared at the folder. S! The answer she had been looking for all
+this time was simply the letter S! How had she not seen that before? It all
+came together now. The phone call where Hector had referred to a lion's tail,
+the time Maria had stuck her tongue out...</p>

+
+   
Here it is not known at the time of publication what the image will be, only that it will be a
+   coat of arms of some kind, and thus no replacement text can be provided, and instead only a brief
+   caption for the image is provided, in the title attribute:

+
+   
<p>The last user to have uploaded a coat of arms uploaded this one:</p>
+<p><img src="last-uploaded-coat-of-arms.cgi" title="User-uploaded coat of arms."></p>

+
+   
Ideally, the author would find a way to provide real replacement text even in this case, e.g.
+   by asking the previous user. Not providing replacement text makes the document more difficult to
+   use for people who are unable to view images, e.g. blind users, or users or very low-bandwidth
+   connections or who pay by the byte, or users who are forced to use a text-only Web browser.

+
+  

+
+  

+
+   
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 favorite.</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. She also liked to jump.</p>
+ <aside><img src="fluffy.jpg" alt="" title="Fluffy"></aside>
+ <p>She would play in the morning, she would play in the evening.</p>
+</article>

+
+  

+
+
+  
4.8.4 Images

+
+  
4.8.4.1 Introduction

+
+  
This section is non-normative.

+
+  
To embed an image in HTML, when there is only a single image resource, use the img
+  element and its src attribute.

+
+  

+
+
<h2>From today's featured article</h2>
+<img src="/uploads/100-marie-lloyd.jpg" alt="" width="100" height="150">
+<p><b><a href="/wiki/Marie_Lloyd">Marie Lloyd</a></b> (1870–1922)
+was an English <a href="/wiki/Music_hall">music hall</a> singer, ...

+
+  

+
+  
However, there are a number of situations for which the author might wish to use multiple image
+  resources that the user agent can choose from:

+
+  
  • 
+
+    
    Different users might have different environmental characteristics:
    
+
+    
    • 
+
+      
      The users' physical screen size might be different from one another.
      
+
+      
      
+       
      A mobile phone's screen might be 4 inches diagonally, while a laptop's screen might be 14
+       inches diagonally.
      
+
+       
+        
+        
+        4″
+        
+        
+        
+        14″
+       
+      
      
+
+      
      This is only relevant when an image's rendered size depends on the
+      viewport size.
      
+
+     
    • 
+
+      
      The users' screen pixel density might be different from one another.
      
+
+      
      
+       
      A mobile phone's screen might have three times as many physical pixels per inch
+      compared to another mobile phone's screen, regardless of their physical screen size.
      
+
+       
+        
+         
+          
+          
+          
+          
+         
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        1x
+        3x
+       
+      
      
+
+     
    • 
+
+      
      The users' zoom level might be different from one another, or might change for a single
+      user over time.
      
+
+      
      A user might zoom in to a particular image to be able to get a more
+      detailed look.
      
+
+      
      The zoom level and the screen pixel density (the previous point) can both affect the number
+      of physical screen pixels per CSS pixel. This ratio is usually
+      referred to as device-pixel-ratio.
      
+
+     
    • 
+
+      
      The users' screen orientation might be different from one another, or might change for a
+      single user over time.
      
+
+      
      
+       
      A tablet can be held upright or rotated 90 degrees, so that the screen is either
+       "portrait" or "landscape".
      
+
+       
+        
+        
+        
+        Portrait
+        
+        
+        Landscape
+       
+      
      
+
+     
    • 
+
+      
      The users' network speed, network latency and bandwidth cost might be different from one
+      another, or might change for a single user over time.
      
+
+      
      A user might be on a fast, low-latency and constant-cost connection while
+      at work, on a slow, low-latency and constant-cost connection while at home, and on a
+      variable-speed, high-latency and variable-cost connection anywhere else.
      
+
+     
    
+
+   
  • 
+
+    
    Authors might want to show the same image content but with different rendered size depending
+    on, usually, the width of the viewport. This is usually referred to as
+    viewport-based selection.
    
+
+    
    
+     
    A Web page might have a banner at the top that always spans the entire viewport
+     width. In this case, the rendered size of the image depends on the physical size of the screen
+     (assuming a maximised browser window).
    
+
+     
+      
+
+      
+      
+      
+      
+
+      
+      
+      
+      
+      
+
+     
+    
    
+
+    
    
+     
    Another Web page might have images in columns, with a single column for screens with a small
+     physical size, two columns for screens with medium physical size, and three columns for screens
+     with big physical size, with the images varying in rendered size in each case to fill up the
+     viewport. In this case, the rendered size of an image might be bigger in
+     the one-column layout compared to the two-column layout, despite the screen being smaller.
    
+
+     
+      
+
+      
+      
+      
+      
+      Narrow, 1 column
+
+      
+      
+      
+      
+      
+      
+      
+      Medium, 2 columns
+
+      
+      
+      
+      
+      
+      
+      
+      Wide, 3 columns
+     
+    
    
+
+   
  • 
+
+    
    Authors might want to show different image content depending on the rendered size of the
+    image. This is usually referred to as art direction.
    
+
+    
    
+     
    When a Web page is viewed on a screen with a large physical size (assuming a maximised
+     browser window), the author might wish to include some less relevant parts surrounding the
+     critical part of the image. When the same Web page is viewed on a screen with a small physical
+     size, the author might wish to show only the critical part of the image.
    
+
+     
+      
+
+      
+      
+      
+      
+
+      
+      
+      
+      
+      
+
+     
+    
    
+
+   
  • 
+
+    
    Authors might want to show the same image content but using different image formats,
+    depending on which image formats the user agent supports. This is usually referred to as
+    image format-based selection.
    
+
+    
    A Web page might have some images in the JPEG, WebP and JPEG XR image
+    formats, with the latter two having better compression abilities compared to JPEG. Since
+    different user agents can support different image formats, with some formats offering better
+    compression ratios, the author would like to serve the better formats to user agents that
+    support them, while providing JPEG fallback for user agents that don't.
    
+
+   

+
+  
The above situations are not mutually exclusive. For example, it is reasonable to combine
+  different resources for different device-pixel-ratio with different resources for
+  art direction.

+
+  
While it is possible to solve these problems using scripting, doing so introduces some other
+  problems:

+
+  
  • Some user agents aggressively download images specified in the HTML markup, before scripts
+   have had a chance to run, so that Web pages complete loading sooner. If a script changes which
+   image to download, the user agent will potentially start two separate downloads, which can
+   instead cause worse page loading performance.
  • If the author avoids specifying any image in the HTML markup and instead instantiates a
+   single download from script, that avoids the double download problem above but then no image will
+   be downloaded at all for users with scripting disabled and the aggressive image downloading
+   optimization will also be disabled.

+
+  
With this in mind, this specification introduces a number of features to address the above
+  problems in a declarative manner.

+
+  
Device-pixel-ratio-based selection when the rendered size of the image is
+   fixed

+
+    
The src and srcset
+    attributes on the img element can be used, using the x
+    descriptor, to provide multiple images that only vary in their size (the smaller image is a
+    scaled-down version of the bigger image).

+
+    
The x descriptor is not appropriate when the rendered
+    size of the image depends on the viewport width
+    (viewport-based selection), but can be used together with
+    art direction.

+
+    

+
+
<h2>From today's featured article</h2>
+<img src="/uploads/100-marie-lloyd.jpg"
+     srcset="/uploads/150-marie-lloyd.jpg 1.5x, /uploads/200-marie-lloyd.jpg 2x"
+     alt="" width="100" height="150">
+<p><b><a href="/wiki/Marie_Lloyd">Marie Lloyd</a></b> (1870–1922)
+was an English <a href="/wiki/Music_hall">music hall</a> singer, ...

+
+     
The user agent can choose any of the given resources depending on the user's screen's pixel
+     density, zoom level, and possibly other factors such as the user's network conditions.

+
+     
For backwards compatibility with older user agents that don't yet understand the srcset attribute, one of the URLs is specified in the
+     img element's src attribute. This will result
+     in something useful (though perhaps lower-resolution than the user would like) being displayed
+     even in older user agents. For new user agents, the src
+     attribute participates in the resource selection, as if it was specified in srcset with a 1x descriptor.

+
+     
The image's rendered size is given in the width and
+     height attributes, which allows the user agent to
+     allocate space for the image before it is downloaded.

+
+    

+
+   
Viewport-based selection

+
+    
The srcset and sizes attributes can be used, using the w
+    descriptor, to provide multiple images that only vary in their size (the smaller image is a
+    scaled-down version of the bigger image).

+
+    

+
+     
In this example, a banner image takes up the entire viewport width (using
+     appropriate CSS).

+
+
<h1><img sizes="100vw" srcset="wolf-400.jpg 400w, wolf-800.jpg 800w, wolf-1600.jpg 1600w"
+     src="wolf-400.jpg" alt="The rad wolf"></h1>

+
+     
The user agent will calculate the effective pixel density of each image from the specified
+     w descriptors and the specified rendered size in the sizes attribute. It can then choose any of the given resources
+     depending on the user's screen's pixel density, zoom level, and possibly other factors such as
+     the user's network conditions.

+
+     
If the user's screen is 320 CSS pixels wide, this is equivalent
+     to specifying wolf-400.jpg 1.25x, wolf-800.jpg 2.5x, wolf-1600.jpg 5x.
+     On the other hand, if the user's screen is 1200 CSS pixels wide,
+     this is equivalent to specifying wolf-400.jpg 0.33x, wolf-800.jpg 0.67x, wolf-1600.jpg 1.33x. By using the
+     w descriptors and the sizes
+     attribute, the user agent can choose the correct image source to download regardless of how
+     large the user's device is.

+
+     
For backwards compatibility, one of the URLs is specified in the img element's
+     src attribute. In new user agents, the src attribute is ignored when the srcset attribute uses w descriptors.

+
+    

+
+    

+
+     
In this example, the Web page has three layouts depending on the width of the
+     viewport. The narrow layout has one column of images (the width of each image is
+     about 100%), the middle layout has two columns of images (the width of each image is about
+     50%), and the widest layout has three columns of images, and some page margin (the width of
+     each image is about 33%). It breaks between these layouts when the viewport is
+     30em wide and 50em wide, respectively.

+
+
<img sizes="(max-width: 30em) 100vw, (max-width: 50em) 50vw, calc(33vw - 100px)"
+     srcset="swing-200.jpg 200w, swing-400.jpg 400w, swing-800.jpg 800w, swing-1600.jpg 1600w"
+     src="swing-400.jpg" alt="Kettlebell Swing">

+
+     
The sizes attribute sets up the layout breakpoints at
+     30em and 50em, and declares the image sizes
+     between these breakpoints to be 100vw, 50vw, or
+     calc(33vw - 100px). These sizes do not necessarily have to match up
+     exactly with the actual image width as specified in the CSS.

+
+     
The user agent will pick a width from the sizes
+     attribute, using the first item with a <media-condition> (the part in
+     parentheses) that evaluates to true, or using the last item (calc(33vw -
+     100px)) if they all evaluate to false.

+
+     
For example, if the viewport width is 29em, then (max-width: 30em) evaluates to true and 100vw is used,
+     so the image size, for the purpose of resource selection, is 29em. If
+     the viewport width is instead 32em, then
+     (max-width: 30em) evaluates to false, but
+     (max-width: 50em) evaluates to true
+     and 50vw is used, so the image size, for the purpose of resource
+     selection, is 16em (half the viewport width). Notice that
+     the slightly wider viewport results in a smaller image because of the different
+     layout.

+
+     
The user agent can then calculate the effective pixel density and choose an appropriate
+     resource similarly to the previous example.

+
+    

+
+   
Art direction-based selection

+
+    
The picture element and the source element, together with the media attribute, can be used, to provide multiple images that
+    vary the image content (for instance the smaller image might be a cropped version of the bigger
+    image).

+
+    

+
+
<picture>
+  <source media="(min-width: 45em)" srcset="large.jpg">
+  <source media="(min-width: 32em)" srcset="med.jpg">
+  <img src="small.jpg" alt="The wolf runs through the snow.">
+</picture>

+
+     
The user agent will choose the first source element for which the media query
+     in the media attribute matches, and then choose an
+     appropriate URL from its srcset attribute.

+
+     
The rendered size of the image varies depending on which resource is chosen. To specify
+     dimensions that the user agent can use before having downloaded the image, CSS can be used.

+
+
img { width: 300px; height: 300px }
+@media (min-width: 32em) { img { width: 500px; height:300px } }
+@media (min-width: 45em) { img { width: 700px; height:400px } }

+
+    

+
+    

+
+     
This example combines art direction- and device-pixel-ratio-based
+     selection. A banner that takes half the viewport is provided in two versions,
+     one for wide screens and one for narrow screens.

+
+
<h1>
+ <picture>
+  <source media="(max-width: 500px)" srcset="banner-phone.jpeg, banner-phone-HD.jpeg 2x">
+  <img src="banner.jpeg" srcset="banner-HD.jpeg 2x" alt="The Breakfast Combo">
+ </picture>
+</h1>

+
+    

+
+   
Image format-based selection

+
+    
The type attribute on the source element
+    can be used, to provide multiple images in different formats.

+
+    

+
+
<h2>From today's featured article</h2>
+<picture>
+ <source srcset="/uploads/100-marie-lloyd.webp" type="image/webp">
+ <source srcset="/uploads/100-marie-lloyd.jxr" type="image/vnd.ms-photo">
+ <img src="/uploads/100-marie-lloyd.jpg" alt="" width="100" height="150">
+</picture>
+<p><b><a href="/wiki/Marie_Lloyd">Marie Lloyd</a></b> (1870–1922)
+was an English <a href="/wiki/Music_hall">music hall</a> singer, ...

+
+     
In this example, the user agent will choose the first source that has a type attribute with a supported MIME type. If the user agent
+     supports WebP images, the first source element will be chosen. If not, but the
+     user agent does support JPEG XR images, the second source element will be chosen.
+     If neither of those formats are supported, the img element will be chosen.

+
+    

+
+   

+
+
+  
4.8.4.1.1 Adaptive images

+
+  
This section is non-normative.

+
+  
CSS and media queries can be used to construct graphical page layouts that adapt dynamically to
+  the user's environment, in particular to different viewport dimensions and pixel
+  densities. For content, however, CSS does not help; instead, we have the img element's
+  srcset attribute and the picture element.
+  This section walks through a sample case showing how to use these features.

+
+  
Consider a situation where on wide screens (wider than 600 CSS
+  pixels) a 300×150 image named a-rectangle.png is to be used,
+  but on smaller screens (600 CSS pixels and less), a smaller
+  100×100 image called a-square.png is to be used. The markup for this
+  would look like this:

+
+  
<figure>
+ <picture>
+  <source srcset="a-square.png" media="(max-width: 600px)">
+  <img src="a-rectangle.png" alt="Barney Frank wears a suit and glasses.">
+ </picture>
+ <figcaption>Barney Frank, 2011</figcaption>
+</figure>

+
+  
For details on what to put in the alt
+  attribute, see the Requirements for providing text to act as an alternative for
+  images section.

+
+  
The problem with this is that the user agent does not necessarily know what dimensions to use
+  for the image when the image is loading. To avoid the layout having to be reflowed multiple times
+  as the page is loading, CSS and CSS media queries can be used to provide the dimensions:

+
+  
<style>
+ #a { width: 300px; height: 150px; }
+ @media (max-width: 600px) { #a { width: 100px; height: 100px; } }
+</style>
+<figure>
+ <picture>
+  <source srcset="a-square.png" media="(max-width: 600px)">
+  <img src="a-rectangle.png" alt="Barney Frank wears a suit and glasses." id="a">
+ </picture>
+ <figcaption>Barney Frank, 2011</figcaption>
+</figure>

+
+  
Alternatively, the width and height attributes can be used to provide the width for legacy user
+  agents, using CSS just for the user agents that support picture:

+
+  
<style media="(max-width: 600px)">
+ #a { width: 100px; height: 100px; }
+</style>
+<figure>
+ <picture>
+  <source srcset="a-square.png" media="(max-width: 600px)">
+  <img src="a-rectangle.png" width="300" height="150"
+  alt="Barney Frank wears a suit and glasses." id="a">
+ </picture>
+ <figcaption>Barney Frank, 2011</figcaption>
+</figure>

+
+  

+
+  
The img element is used with the src attribute,
+  which gives the URL of the image to use for legacy user agents that do not support the
+  picture element. This leads to a question of which image to provide in the src attribute.

+
+  
If the author wants the biggest image in legacy user agents, the markup could be as
+  follows:

+
+  
<picture>
+ <source srcset="pear-mobile.jpeg" media="(max-width: 720px)">
+ <source srcset="pear-tablet.jpeg" media="(max-width: 1280px)">
+ <img src="pear-desktop.jpeg" alt="The pear is juicy.">
+</picture>

+
+  
However, if legacy mobile user agents are more important, one can list all three images in the
+  source elements, overriding the src attribute
+  entirely.

+
+  
<picture>
+ <source srcset="pear-mobile.jpeg" media="(max-width: 720px)">
+ <source srcset="pear-tablet.jpeg" media="(max-width: 1280px)">
+ <source srcset="pear-desktop.jpeg">
+ <img src="pear-mobile.jpeg" alt="The pear is juicy.">
+</picture>

+
+  
Since at this point the src attribute is actually being
+  ignored entirely by picture-supporting user agents, the src attribute can default to any image, including one that is neither
+  the smallest nor biggest:

+
+  
<picture>
+ <source srcset="pear-mobile.jpeg" media="(max-width: 720px)">
+ <source srcset="pear-tablet.jpeg" media="(max-width: 1280px)">
+ <source srcset="pear-desktop.jpeg">
+ <img src="pear-tablet.jpeg" alt="The pear is juicy.">
+</picture>

+
+  

+
+  
Above the max-width media feature is used, giving the maximum
+  (viewport) dimensions that an image is intended for. It is also possible to use min-width instead.

+
+  
<picture>
+ <source srcset="pear-desktop.jpeg" media="(min-width: 1281px)">
+ <source srcset="pear-tablet.jpeg" media="(min-width: 721px)">
+ <img src="pear-mobile.jpeg" alt="The pear is juicy.">
+</picture>

+
+
+  
4.8.4.2 Attributes common to source and img elements

+
+  
4.8.4.2.1 Srcset attributes

+
+  
A srcset attribute is an attribute with requirements defined in this section.

+
+  
If present, its value must consist of one or more image
+  candidate strings, each separated from the next by a U+002C COMMA character (,). If an
+  image candidate string contains no descriptors and no ASCII whitespace
+  after the URL, the following image candidate string, if there is one, must begin with
+  one or more ASCII whitespace.

+
+  
An image candidate string consists of the following components, in order, with the
+  further restrictions described below this list:

+
+  
  1. Zero or more ASCII whitespace.
  2. A valid non-empty URL that does not start or end with a U+002C COMMA
+   character (,), referencing a non-interactive, optionally animated, image resource that is neither
+   paged nor scripted.
  3. Zero or more ASCII whitespace.
  4. 
+
+    
    Zero or one of the following:
    
+
+    
    • A width descriptor, consisting of: ASCII whitespace, a
+     valid non-negative integer giving a number greater than zero representing the
+     width descriptor value, and a U+0077 LATIN SMALL LETTER W character.
    • A pixel density descriptor, consisting of: ASCII whitespace, a
+     valid floating-point number giving a number greater than zero representing the
+     pixel density descriptor value, and a U+0078 LATIN SMALL LETTER X
+     character.
    
+
+   
  5. Zero or more ASCII whitespace.

+
+  
There must not be an image candidate string for an element that has the same
+  width descriptor value as another image candidate string's width
+  descriptor value for the same element.

+
+  
There must not be an image candidate string for an element that has the same
+  pixel density descriptor value as another image candidate string's
+  pixel density descriptor value for the same element. For the purpose of this
+  requirement, an image candidate string with no descriptors is equivalent to an
+  image candidate string with a 1x descriptor.

+
+  
If an image candidate string for an element has the width descriptor
+  specified, all other image candidate strings for that
+  element must also have the width descriptor specified.

+
+  
The specified width in an image candidate string's width descriptor
+  must match the intrinsic width in the resource given by the
+  image candidate string's URL, if it has an intrinsic width.

+
+  
If an element has a srcset attribute present, all image candidate strings for that element must have the width
+  descriptor specified.

+
+
+  
4.8.4.2.2 Sizes attributes

+
+  
A sizes attribute is an attribute with requirements defined in this section.

+
+  
If present, the value must be a valid source size list.

+
+  
A valid source size list is a string that matches the following grammar:
+  [CSSVALUES] [MQ]

+
+
<source-size-list> = [ <source-size># , ]? <source-size-value>
+<source-size> = <media-condition> <source-size-value>
+<source-size-value> = <length>

+
+  
A <source-size-value> must not be negative, and must not use CSS functions
+  other than the 'calc()' function.

+
+  
The <source-size-value> gives the intended layout width of the image. The
+  author can specify different widths for different environments with
+  <media-condition>s.

+
+  
Percentages are not allowed in a <source-size-value>,
+  to avoid confusion about what it would be relative to.
+  The 'vw' unit can be used for sizes relative to the viewport
+  width.

+
+
+  
+
+  
4.8.4.3 Processing model

+
+  
The task source for the tasks queued by algorithms in this section is the DOM manipulation task
+  source.

+
+  

+
+  
An img element has a current request and a pending request.
+  The current request is initially set to a new image request.
+  The pending request is initially set to null.
+  The current request is usually referred to as the img element itself.
Spec bugs: 27484

+
+  
An image request has a state, current URL and image data.

+
+  
An image request's state is one of the following:

+
+  
Unavailable
The user agent hasn't obtained any image data,
+   or has obtained some or all of the image data but
+   hasn't yet decoded enough of the image to get the image dimensions.
Partially available
The user agent has obtained some of the image data and at least the image dimensions are
+   available.
Completely available
The user agent has obtained all of the image data and at least the image dimensions are
+   available.
Broken
The user agent has obtained all of the image data that it can, but it cannot even decode the
+   image enough to get the image dimensions (e.g. the image is corrupted, or the format is not
+   supported, or no data could be obtained).

+
+  
An image request's current URL is initially the empty string.

+
+  
An image request's image data is the decoded image data.

+
+  
When an image request is either in the partially
+  available state or in the completely available state, it is
+  said to be available.

+
+  
When an img element is in the completely available
+  state and the user agent can decode the media data without errors, then the
+  img element is said to be fully decodable.

+
+  
An image request is initially unavailable.

+
+  
When an img element is available,
+  it provides a paint source
+  whose width is the image's density-corrected intrinsic width (if any),
+  whose height is the image's density-corrected intrinsic height (if any),
+  and whose appearance is the intrinsic appearance of the image.

+
+  

+
+  
An img element is said to use srcset or
+  picture if it has a srcset attribute
+  specified or if it has a parent that is a picture element.

+
+  

+
+  
Each img element has a last selected source, which must initially be
+  null.

+
+  
Each image request has a current pixel density, which must initially be undefined.

+
+  
When an img element has a current pixel density that is not 1.0, the
+  element's image data must be treated as if its resolution, in device pixels per CSS pixels, was the current pixel density. The image's
+  density-corrected intrinsic width and height are the intrinsic width and height after taking into account the current pixel
+  density.

+
+  
For example, if the current pixel density is 3.125, that means
+  that there are 300 device pixels per CSS inch, and thus if the image
+  data is 300x600, it has intrinsic dimensions of 96 CSS
+  pixels by 192 CSS pixels.

+
+  
An img element is associated with a source set.

+
+  
A source set is an ordered set of zero or more image sources
+  and a source size.

+
+  
An image source is a URL, and optionally either a pixel density
+  descriptor, or a width descriptor.

+
+  
A source size is a <source-size-value>.
+  When a source size has a unit relative to the viewport,
+  it must be interpreted relative to the img element's node document's
+  viewport.
+  Other units must be interpreted the same as in Media Queries. [MQ]

+
+  

+
+  
A parse error for algorithms in this
+  section indicates a non-fatal mismatch between input and requirements. User agents are encouraged
+  to expose parse errors somehow.

+
+  

+
+  
Whether the image is fetched successfully or not (e.g. whether the response status was an
+  ok status) must be ignored when determining the image's type and whether it is a
+  valid image.

+
+  
This allows servers to return images with error responses, and have them
+  displayed.

+
+  
The user agent should apply the image sniffing rules to determine the type of the image, with the image's associated Content-Type headers giving the official
+  type. If these rules are not applied, then the type of the image must be the type given by
+  the image's associated Content-Type headers.
Spec bugs: 25889, 26702

+
+  
User agents must not support non-image resources with the img element (e.g. XML
+  files whose document element is an HTML element). User agents must not run executable
+  code (e.g. scripts) embedded in the image resource. User agents must only display the first page
+  of a multipage resource (e.g. a PDF file). User agents must not allow the resource to act in an
+  interactive fashion, but should honour any animation in the resource.

+
+  
This specification does not specify which image types are to be supported.

+
+
+  
4.8.4.3.1 When to obtain images

+
+  
In a browsing context where scripting is
+  disabled, user agents may obtain images immediately or on demand. In a browsing
+  context where scripting is enabled, user agents
+  must obtain images immediately.

+
+  
A user agent that obtains images immediately must synchronously
+  update the image data of an img element,
+  with the restart animation flag set if so stated,
+  whenever that element is created or has experienced relevant mutations.

+
+  
A user agent that obtains images on demand must update the image data of an
+  img element whenever it needs the image data (i.e. on demand),
+  but only if the img element is in the
+  unavailable state. When an img element
+  has experienced relevant mutations, if the user
+  agent only obtains images on demand, the img element must return to the unavailable state.

+
+
+  
4.8.4.3.2 Reacting to DOM mutations

+
+  
The relevant mutations for an img element are as follows:

+
+  
+
+
+  
4.8.4.3.3 The list of available images

+
+  
Each Document object must have a list of available images. Each image
+  in this list is identified by a tuple consisting of an absolute URL, a CORS
+  settings attribute mode, and, if the mode is not No
+  CORS, an origin.
+  Each image furthermore has an ignore higher-layer caching flag.
+  User agents may copy entries from one Document
+  object's list of available images to another at any time (e.g. when the
+  Document is created, user agents can add to it all the images that are loaded in
+  other Documents), but must not change the keys of entries copied in this way when
+  doing so, and must unset the ignore higher-layer caching flag for the copied entry.
+  User agents may also remove images from such lists at any time (e.g. to save
+  memory).
+  User agents must remove entries in the list of available images as appropriate
+  given higher-layer caching semantics for the resource (e.g. the HTTP `Cache-Control` response header) when the ignore
+  higher-layer caching flag is unset.

+
+  
The list of available images is intended to enable synchronous
+  switching when changing the src attribute to a URL that has
+  previously been loaded, and to avoid re-downloading images in the same document even when they
+  don't allow caching per HTTP. It is not used to avoid re-downloading the same image while the
+  previous image is still loading.

+
+  
The user agent can also store the image data separately from the list of available images.

+
+  
For example, if a resource has the HTTP response header
+  `Cache-Control: must-revalidate`, and its ignore higher-layer
+  caching flag is unset, the user agent would remove it from the list of available
+  images but could keep the image data separately, and use that if the server responds with a
+  304 Not Modified status.

+
+
+  
4.8.4.3.4 Updating the image data

+
+  
When the user agent is to update the image data of an img element,
+  optionally with the restart animations flag set,
+  it must run the following steps:
Spec bugs: 24597, 24712

+
+  
  1. 
+
+    
    If the element's node document is not the active document,
+    then:
    
+
+    
    1. Continue running this algorithm in parallel.
    2. Wait until the element's node document is the active document.
    3. If another instance of this algorithm for this img element was started after this instance
+     (even if it aborted and is no longer running), then abort these steps.
    4. Queue a microtask to continue this algorithm.
    
+
+   
  2. If the user agent cannot support images, or its support for images has been disabled, then
+   abort the image request for the current request and the pending request,
+   set current request to the unavailable state,
+   let pending request be null,
+   and abort these steps.
  3. 
+
+    
    If the element does not use srcset or picture,
+    and it has a src attribute specified and
+    its value is not the empty string, let selected source be the value of the
+    element's src attribute, and selected pixel
+    density be 1.0. Otherwise, let selected source be null and selected pixel density be undefined.
    
+
+   
  4. Let the img element's last selected source be selected source.
  5. 
+
+    
    If selected source is not null, then:
    
+
+    
    1. Parse selected source, relative to the
+     element's node document. If that is not successful, then abort this inner set of
+     steps. Otherwise, let urlString be the resulting URL string.
    2. Let key be a tuple consisting of urlString, the img
+     element's crossorigin attribute's mode, and, if that
+     mode is not No CORS, the node
+     document's origin.
    3. 
+
+      
      If the list of available images contains an entry for key,
+      then:
      
+
+      
      1. Set the ignore higher-layer caching flag for that entry.
      2. Abort the image request for the current request and the
+        pending request.
      3. Let pending request be null.
      4. Let current request be a new image request whose image data is that of the entry and whose state is set to the
+        completely available state.
      5. Update the presentation of the image appropriately.
      6. Let the current request's current pixel density be
+        selected pixel density.
      7. Queue a task to restart the animation if restart
+        animation is set, change current request's current URL to urlString, and then fire an event named load
+        at the img element.
      8. Abort the update the image data algorithm.
      
+
+     
    
+
+   
  6. Await a stable state, allowing the task that invoked this algorithm to continue.
+   The synchronous
+   section consists of all the remaining steps of this algorithm until the algorithm says the
+   synchronous section has ended. (Steps in synchronous sections are marked with ⌛.)
  7. 
+
+    
    ⌛ If another instance of this algorithm for this img element was started
+    after this instance (even if it aborted and is no longer running), then abort these steps.
    
+
+    
    Only the last instance takes effect, to avoid multiple requests when, for
+    example, the src, srcset,
+    and crossorigin attributes are all set in
+    succession.
    
+
+   
  8. 
+
+    
    ⌛ Let selected source and selected pixel density be the
+    URL and pixel density that results from selecting an image source,
+    respectively.
    
+
+   
  9. 
+
+    
    ⌛ If selected source is null, then:
    
+
+    
    1. ⌛ Set the current request to the broken state,
+     abort the image request for the current request and the pending request,
+     and let pending request be null.
    2. ⌛ Queue a task to change the current request's current URL to the empty string, and then, if the element has a
+     src attribute or it uses srcset or picture, fire an event named error
+     at the img element.
    3. ⌛ Abort this algorithm.
    
+
+   
  10. 
+
+    
    ⌛ Queue a task to fire a progress event named loadstart at
+    the img element.
    
+
+   
  11. 
+
+    
    ⌛ Parse selected source, relative to the
+    element's node document, and let urlString be the resulting URL
+    string. If that is not successful, then:
    
+
+    
    1. ⌛ Abort the image request for the current request and
+     the pending request.
    2. ⌛ Set the current request to the broken state.
    3. ⌛ Let pending request be null.
    4. ⌛ Queue a task to change the current request's current URL to selected source, fire an event named error
+     at the img element and then fire an event
+     named loadend at the img element.
    5. ⌛ Abort the update the image data algorithm.
    
+
+   
  12. 
+
+    
    ⌛ If the pending request is not null,
+    and urlString is the same as the pending request's current URL,
+    then abort these steps.
    
+
+    
    ⌛ If urlString is the same as the current request's current URL,
+    and current request is in the partially available state,
+    then abort the image request for the pending request,
+    queue a task to restart the animation if restart animation is set,
+    and abort these steps.
    
+
+    
    ⌛ If the pending request is not null,
+    abort the image request for the pending request.
    
+
+    
    ⌛ Let image request be a new image request
+    whose current URL is urlString.
    
+
+    
    ⌛ If current request is in the unavailable state
+    or the broken state,
+    let the current request be image request.
+    Otherwise, let the pending request be image request.
    
+
+    
    ⌛ Let request be the result of creating a potential-CORS request given
+    urlString, "image", and the current state of the element's
+    crossorigin content attribute.
    
+
+    
    ⌛ Set request's client to the
+    element's node document's Window object's environment settings
+    object and type to "image".
    
+
+    
    ⌛ If the element uses srcset or
+    picture, set request's initiator to "imageset".
    
+
+    
    ⌛ Set request's
+    referrer policy to the current state of
+    the element's referrerpolicy attribute.
    
+
+    
    ⌛ Fetch request. Let this
+    instance of the fetching algorithm be associated with
+    image request.
    
+
+    
    The resource obtained in this fashion, if any, is image request's image data.
+    It can be either CORS-same-origin or CORS-cross-origin; this affects
+    the origin of the image itself (e.g. when used on a canvas).
    
+
+    
+    
    Fetching the image must delay the load event of the element's node document until the
+    task that is queued by the
+    networking task source once the resource has been fetched (defined below) has been run.
+    
    
+
+    
    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 are stricter than those
+    described above to mitigate this attack, but unfortunately such policies are typically not
+    compatible with existing Web content.
    
+
+    
    If the resource is CORS-same-origin, each task
+    that is queued by the networking task source
+    while the image is being fetched, if image request is the current
+    request, must fire a progress event named progress at the img element.
    
+
+   
  13. End the synchronous section, continuing the remaining steps in
+   parallel, but without missing any data from fetching.
  14. 
+
+    
    As soon as possible, jump to the first applicable entry from the following list:
    
+
+    
    If the resource type is multipart/x-mixed-replace
    
+
+      
    The next task that is queued by the networking task source while the image is being
+      fetched must run the following steps:
    
+
+      
    1. 
+
+        
      If image request is the pending request
+        and at least one body part has been completely decoded,
+        abort the image request for the current request,
+        upgrade the pending request to the current request.
      
+
+       
    2. 
+
+        
      Otherwise, if image request is the pending request
+        and the user agent is able to determine that image request's image
+        is corrupted in some fatal way such that the image dimensions cannot be obtained,
+        abort the image request for the current request,
+        upgrade the pending request to the current request
+        and set the current request's state to broken.
      
+
+       
    3. 
+
+        
      Otherwise, if image request is the current request,
+        it is in the unavailable state,
+        and the user agent is able to determine image request's image's width and height,
+        set the current request's state to partially available.
      
+
+       
    4. 
+
+        
      Otherwise, if image request is the current request,
+        it is in the unavailable state,
+        and the user agent is able to determine that image request's image
+        is corrupted in some fatal way such that the image dimensions cannot be obtained,
+        set the current request's state to broken.
+        
      
+
+       
    
+
+      
    Each task that is queued by the networking task source while the image is being
+      fetched must update the presentation of the image, but as each new body part comes in, it must
+      replace the previous image. Once one body part has been completely decoded, the user agent
+      must set the img element to the completely
+      available state and queue a task to fire
+      an event named load at the img
+      element.
    
+      
+
+      
    The progress and loadend events are not fired for
+      multipart/x-mixed-replace image streams.
    
+
+     
    If the resource type and data corresponds to a supported image format, as described below
    
+
+      
    The next task that is queued by the networking task source while the image is being
+      fetched must run the following steps:
    
+
+      
    1. 
+
+        
      If the user agent is able to determine image request's image's width and height,
+        and image request is pending request,
+        set image request's state to partially available.
      
+
+       
    2. 
+
+        
      Otherwise, if the user agent is able to determine image request's image's width and height,
+        and image request is current request,
+        update the img element's presentation appropriately
+        and set image request's state to partially available.
      
+
+       
    3. 
+
+        
      Otherwise, if the user agent is able to determine that image request's image
+        is corrupted in some fatal way such that the image dimensions cannot be obtained, and
+        image request is pending request, abort the image
+        request for the current request and the pending request,
+        upgrade the pending request to the current request, set current
+        request to the broken state, fire an event named error at the img element, fire an event named loadend at the img element, and abort these
+        steps.
      
+
+       
    4. 
+
+        
      Otherwise, if the user agent is able to determine that image request's image
+        is corrupted in some fatal way such that the image dimensions cannot be obtained, and
+        image request is current request, abort the image
+        request for image request, fire an
+        event named error at the img element,
+        fire an event named loadend at the img element, and abort these
+        steps.
      
+
+       
    
+
+      
    That task, and each subsequent task, that is queued by the
+      networking task source while the image is being fetched, if image
+      request is the current request, must update the presentation of the image
+      appropriately (e.g., if the image is a progressive JPEG, each packet can improve the
+      resolution of the image).
    Spec bugs: 25797, 25798
    
+
+      
    Furthermore, the last task that is queued by the networking task source once the resource has been
+      fetched must additionally run these steps:
    
+
+      
    1. If image request is the pending request,
+       abort the image request for the current request,
+       upgrade the pending request to the current request and
+       update the img element's presentation appropriately.
    2. Set image request to the completely
+       available state.
    3. Add the image to the list of available images using the key key, with the ignore higher-layer caching flag set.
    4. Fire a progress event or event named load
+       at the img element, depending on the resource in image request.
    5. Fire a progress event or event named loadend
+       at the img element, depending on the resource in image request.
    
+
+     
    Otherwise
    
+
+      
    The image data is not in a supported file format; the user agent must set image
+      request to the broken state, abort the image
+      request for the current request and the pending request,
+      upgrade the pending request to the current request if image request is
+      the pending request, and then queue a task to first fire an event named error
+      at the img element and then fire an
+      event named loadend at the img
+      element.
    
+
+     
    
+
+   

+
+  
While a user agent is running the above algorithm for an element x, there must be a
+  strong reference from the element's node document to the element x, even
+  if that element is not connected.

+
+  
To abort the image request for an image request image request means to run the following steps:

+
+  
  1. Forget image request's image data, if any.
  2. Abort any instance of the fetching algorithm for
+   image request, discarding any pending tasks generated by that algorithm.

+
+  
To upgrade the pending request to the current request for an img element means to run the following steps:

+
+  
  1. Let the img element's current request be the pending request.
  2. Let the img element's pending request be null.

+
+  
To fire a progress event or event named type at an element e,
+  depending on resource r, means to fire a progress event named
+  type at e if r is CORS-same-origin, and otherwise
+  fire an event named type at e.

+
+
+  
4.8.4.3.5 Selecting an image source

+
+  
When asked to select an image source for a given img element el,
+  user agents must do the following:

+
+  
  1. Update the source set for el.
  2. If el's source set is empty,
+   return null as the URL and undefined as the pixel density and abort these steps.
  3. Otherwise, take el's source set
+   and let it be source set.
  4. If an entry b in source set has the same associated pixel
+   density descriptor as an earlier entry a in source set, then remove
+   entry b. Repeat this step until none of the entries in source set have the
+   same associated pixel density descriptor as an earlier entry.
  5. In a user agent-specific manner,
+   choose one image source from source set.
+   Let this be selected source.
  6. Return selected source and its associated pixel density.

+
+
+  
4.8.4.3.6 Updating the source set

+
+  
When asked to update the source set for a given img element el,
+  user agents must do the following:

+
+  
  1. Set el's source set to an empty source set.
  2. If el has a parent node and that is a picture element,
+   let elements be an array containing el's parent node's child elements, retaining relative order.
+   Otherwise, let elements be array containing only el.
  3. If el has a width attribute, and parsing
+   that attribute's value using the rules for parsing dimension values doesn't generate
+   an error or a percentage value, then let width be the returned integer value.
+   Otherwise, let width be null.
  4. 
+
+    
    Iterate through elements,
+    doing the following for each item child:
    
+
+    
    1. 
+
+      
      If child is el:
      
+
+      
      1. If child has a srcset attribute,
+       parse child's srcset attribute
+       and let the returned source set be source set.
+       Otherwise, let source set be an empty source set.
      2. Parse child's sizes
+       attribute with the fallback width width, and let source set's
+       source size be the returned value.
      3. If child has a src attribute
+       whose value is not the empty string
+       and source set does not contain an
+       image source with a pixel density descriptor value of 1,
+       and no image source with a width descriptor,
+       append child's src attribute value to source set.
      4. Normalize the source densities of source set.
      5. Let el's source set be source set.
      6. Abort this algorithm.
      
+
+     
    2. If child is not a source element, continue to the next child.
+     Otherwise, child is a source element.
    3. If child does not have a srcset
+     attribute, continue to the next child.
    4. Parse child's srcset attribute and
+     let the returned source set be source set.
    5. If source set has zero image sources,
+     continue to the next child.
    6. If child has a media attribute, and
+     its value does not match the environment,
+     continue to the next child.
    7. Parse child's sizes attribute
+     with the fallback width width, and let source set's source
+     size be the returned value.
    8. If child has a type attribute, and its
+     value is an unknown or unsupported MIME type, continue to the next child.
    9. Normalize the source densities of source set.
    10. Let el's source set be source set.
    11. Abort this algorithm.
    
+
+   

+
+  
Each img element independently considers its previous sibling
+  source elements plus the img element itself for selecting an image
+  source, ignoring any other (invalid) elements, including other img elements in
+  the same picture element, or source elements that are following siblings
+  of the relevant img element.

+
+
+  
4.8.4.3.7 Parsing a srcset attribute

+
+  
When asked to parse a srcset attribute from an element, parse the value of the
+  element's srcset attribute as follows:

+
+  
  1. Let input be the value passed to this algorithm.
  2. Let position be a pointer into input,
+   initially pointing at the start of the string.
  3. Let candidates be an initially empty source set.
  4. Splitting loop: Collect a sequence of code points that are ASCII
+   whitespace or U+002C COMMA characters from input given position. If
+   any U+002C COMMA characters were collected, that is a parse error.
  5. If position is past the end of input,
+   return candidates and abort these steps.
  6. Collect a sequence of code points that are not ASCII whitespace
+   from input given position, and let that be url.
  7. Let descriptors be a new empty list.
  8. 
+
+    
    If url ends with U+002C (,), then:
    
+
+    
    1. Remove all trailing U+002C COMMA characters from url.
+     If this removed more than one character,
+     that is a parse error.
    
+
+    
    Otherwise, while true:
    
+
+    
    1. Descriptor tokenizer: Skip ASCII whitespace within input
+     given position.
    2. Let current descriptor be the empty string.
    3. Let state be in descriptor.
    4. 
+
+      
      Let c be the character at position.
+      Do the following depending on the value of state.
+      For the purpose of this step, "EOF" is a special character representing
+      that position is past the end of input.
      
+
+      
      In descriptor
      
+
+        
      Do the following, depending on the value of c:
      
+
+        
      ASCII whitespace
      If current descriptor is not empty,
+         append current descriptor to descriptors
+         and let current descriptor be the empty string.
+         Set state to after descriptor.
      U+002C COMMA (,)
      Advance position to the next character in input.
+         If current descriptor is not empty,
+         append current descriptor to descriptors.
+         Jump to the step labeled descriptor parser.
      U+0028 LEFT PARENTHESIS (()
      Append c to current descriptor.
+         Set state to in parens.
      EOF
      If current descriptor is not empty,
+         append current descriptor to descriptors.
+         Jump to the step labeled descriptor parser.
      Anything else
      Append c to current descriptor.
      
+
+       
      In parens
      
+
+        
      Do the following, depending on the value of c:
      
+
+        
      U+0029 RIGHT PARENTHESIS ())
      Append c to current descriptor.
+         Set state to in descriptor.
      EOF
      Append current descriptor to descriptors.
+         Jump to the step labeled descriptor parser.
      Anything else
      Append c to current descriptor.
      
+
+       
      After descriptor
      
+
+        
      Do the following, depending on the value of c:
      
+
+        
      ASCII whitespace
      Stay in this state.
      EOF
      Jump to the step labeled descriptor parser.
      Anything else
      Set state to in descriptor.
+         Set position to the previous character in input.
      
+
+       
      
+
+      
      Advance position to the next character in input.
      
+
+      
      In order to be compatible with future additions,
+      this algorithm supports multiple descriptors and descriptors with parens.
      
+
+     
    
+
+   
  9. Descriptor parser: Let error be no.
  10. Let width be absent.
  11. Let density be absent.
  12. Let future-compat-h be absent.
  13. 
+
+    
    For each descriptor in descriptors,
+    run the appropriate set of steps from the following list:
    
+
+    
    If the descriptor consists of a valid non-negative integer
+     followed by a U+0077 LATIN SMALL LETTER W character
    
+
+      
    1. 
+
+        
      If the user agent does not support the sizes attribute,
+        let error be yes.
      
+
+        
      A conforming user agent will support the sizes attribute.
+        However, user agents typically implement and ship features in an incremental manner in practice.
      
+
+       
    2. If width and density
+       are not both absent,
+       then let error be yes.
    3. Apply the rules for parsing non-negative integers to the descriptor.
+       If the result is zero, let error be yes.
+       Otherwise, let width be the result.
    
+
+     
    If the descriptor consists of a valid floating-point number
+     followed by a U+0078 LATIN SMALL LETTER X character
    
+
+      
    1. If width, density and future-compat-h
+       are not all absent,
+       then let error be yes.
    2. 
+
+        
      Apply the rules for parsing floating-point number values to the descriptor.
+        If the result is less than zero, let error be yes.
+        Otherwise, let density be the result.
      
+
+        
      If density is zero,
+        the intrinsic dimensions will be infinite.
+        User agents are expected to have limits in how big images can be rendered,
+        which is allowed by the hardware limitations clause.
      
+
+       
    
+
+     
    If the descriptor consists of a valid non-negative integer
+     followed by a U+0068 LATIN SMALL LETTER H character
    
+
+      
    This is a parse error.
    
+
+      
    1. If future-compat-h and density
+       are not both absent,
+       then let error be yes.
    2. Apply the rules for parsing non-negative integers to the descriptor.
+       If the result is zero, let error be yes.
+       Otherwise, let future-compat-h be the result.
    
+
+     
    Anything else
    Let error be yes.
    
+
+   
  14. If future-compat-h is not absent and width is absent,
+   let error be yes.
  15. If error is still no,
+   then append a new image source to candidates
+   whose URL is url,
+   associated with a width width if not absent
+   and a pixel density density if not absent.
+   Otherwise, there is a parse error.
  16. Return to the step labeled splitting loop.

+
+
+  
4.8.4.3.8 Parsing a sizes attribute

+
+  
When asked to parse a sizes attribute from an element, with a fallback width
+  width, parse a comma-separated list of component values from the value of
+  the element's sizes attribute (or the empty string, if the attribute is
+  absent), and let unparsed sizes list be the result. [CSSSYNTAX]

+
+  
For each unparsed size in unparsed sizes list:

+
+  
  1. Remove all consecutive <whitespace-token>s
+   from the end of unparsed size.
+   If unparsed size is now empty,
+   that is a parse error;
+   continue to the next iteration of this algorithm.
  2. If the last component value in unparsed size
+   is a valid non-negative <source-size-value>,
+   let size be its value
+   and remove the component value from unparsed size.
+   Any CSS function other than the 'calc()' function is invalid.
+   Otherwise, there is a parse error;
+   continue to the next iteration of this algorithm.
  3. Remove all consecutive <whitespace-token>s
+   from the end of unparsed size.
+   If unparsed size is now empty,
+   return size and exit this algorithm.
+   If this was not the last item in unparsed sizes list,
+   that is a parse error.
  4. Parse the remaining component values in unparsed size
+   as a <media-condition>.
+   If it does not parse correctly,
+   or it does parse correctly but the <media-condition> evaluates to false,
+   continue to the next iteration of this algorithm. [MQ]
  5. Return size and exit this algorithm.

+
+  
If the above algorithm exhausts unparsed sizes list without returning a
+  size value, follow these steps:

+
+  
  1. If width is not null, return a <length> with the value
+   width and the unit 'px'.
  2. Return 100vw.

+
+  
While a valid source size list only contains a bare <source-size-value>
+  (without an accompanying <media-condition>)
+  as the last entry in the <source-size-list>,
+  the parsing algorithm technically allows such at any point in the list,
+  and will accept it immediately as the size
+  if the preceding entries in the list weren't used.
+  This is to enable future extensions,
+  and protect against simple author errors such as a final trailing comma.

+
+
+  
4.8.4.3.9 Normalizing the source densities

+
+  
An image source can have a pixel density descriptor, a width
+  descriptor, or no descriptor at all accompanying its URL. Normalizing a source
+  set gives every image source a pixel density descriptor.

+
+  
When asked to normalize the source
+  densities of a source set source set, the user agent must do the
+  following:

+
+  
  1. Let source size be source set's source size.
  2. 
+
+    
    For each image source in source set:
    
+
+    
    1. If the image source has a pixel density descriptor, continue to the next
+     image source.
    2. 
+
+      
      Otherwise, if the image source has a width descriptor, replace the width
+      descriptor with a pixel density descriptor with a value of the width descriptor value divided by the source size and a unit
+      of x.
      
+
+      
      If the source size is zero,
+      the density would be infinity,
+      which results in the intrinsic dimensions being zero by zero.
      
+
+     
    3. Otherwise, give the image source a pixel density descriptor of 1x.
    
+
+   

+
+
+  
4.8.4.3.10 Reacting to environment changes

+
+  
The user agent may at any time run the following algorithm to update an img
+  element's image in order to react to changes in the environment. (User agents are not
+  required to ever run this algorithm; for example, if the user is not looking at the page any
+  more, the user agent might want to wait until the user has returned to the page before determining
+  which image to use, in case the environment changes again in the meantime.)

+
+  
User agents are encouraged to run this algorithm in particular when the user changes
+  the viewport's size (e.g. by resizing the window or changing the page zoom), and when
+  an img element is inserted into a
+  document, so that the density-corrected intrinsic width and height match the
+  new viewport, and so that the correct image is chosen when art direction
+  is involved.

+
+  
  1. Await a stable state. The synchronous section
+   consists of all the remaining steps of this algorithm until the algorithm says the
+   synchronous section has ended. (Steps in synchronous sections are marked with ⌛.)
  2. ⌛ If the img element does not use srcset or
+   picture, its node document is not the active
+   document, has image data whose resource type is multipart/x-mixed-replace, or
+   the pending request is not null, then abort this algorithm.
  3. ⌛ Let selected source and selected pixel
+   density be the URL and pixel density that results from selecting an image source, respectively.
  4. ⌛ If selected source is null, then abort these steps.
  5. ⌛ If selected source and selected pixel
+   density are the same as the element's last selected source and current
+   pixel density, then abort these steps.
  6. ⌛ Parse selected source, relative to
+   the element's node document, and let urlString be the resulting URL
+   string. If that is not successful, abort these steps.
  7. ⌛ Let corsAttributeState be the state of the element's crossorigin content attribute.
  8. ⌛ Let origin be the origin of the img element's node document.
  9. ⌛ Let client be the img element's node
+   document's Window object's environment settings object.
  10. ⌛ Let key be a tuple consisting of urlString,
+   corsAttributeState, and, if corsAttributeState is not No CORS, origin.
  11. ⌛ Let image request be a new image request
+   whose current URL is urlString
  12. ⌛ Let the element's pending request be image request.
  13. End the synchronous section, continuing the remaining steps
+   in parallel.
  14. 
+
+    
    If the list of available images contains an entry for key,
+    then set image request's image data to that of the entry.
+    Continue to the next step.
    
+
+    
    Otherwise:
    
+
+    
    1. Let request be the result of creating a potential-CORS request given
+     urlString, "image", and
+     corsAttributeState.
    2. Set request's client to
+     client, type to "image", initiator to "imageset", and set request's synchronous
+     flag.
    3. Set request's
+     referrer policy to the current state of
+     the element's referrerpolicy attribute.
    4. Let response be the result of fetching request.
    5. If response's unsafe response is a network error or
+     if the image format is unsupported (as determined by applying the image sniffing rules, again as mentioned earlier),
+     or if the user agent is able to determine that image request's image is corrupted in
+     some fatal way such that the image dimensions cannot be obtained, or if the resource type is
+     multipart/x-mixed-replace, then let pending request be null and abort
+     these steps.
    6. Otherwise, response's unsafe response is image
+     request's image data. It can be either
+     CORS-same-origin or CORS-cross-origin; this affects the
+     origin of the image itself (e.g., when used on a canvas).
    
+
+   
  15. 
+
+    
    Queue a task to run these steps:
    
+
+    
    1. If the img element has experienced relevant mutations
+     since this algorithm started, then let pending request be null and abort these steps.
      
+
+     
    2. Let the img element's last selected source be selected source
+     and the img element's current pixel density be selected pixel density.
    3. Set image request to the completely available state.
    4. Add the image to the list of available images using the key key,
+     with the ignore higher-layer caching flag set.
    5. Upgrade the pending request to the current request.
    6. Update the img element's presentation appropriately.
    7. Fire an event named load at the img element.
    
+
+   

+
+  
+
+
+  
4.8.4.4 Requirements for providing text to act as an alternative for images

+
+
+  
4.8.4.4.1 General guidelines

+
+  
Except where otherwise specified, the alt attribute must be
+  specified and its value must not be empty; the value must be an appropriate replacement for the
+  image. The specific requirements for the alt attribute depend on
+  what the image is intended to represent, as described in the following sections.

+
+  
The most general rule to consider when writing alternative text is the following: the
+  intent is that replacing every image with the text of its alt
+  attribute not change the meaning of the page.

+
+  
So, in general, alternative text can be written by considering what one would have written had
+  one not been able to include the image.

+
+  
A corollary to this is that the alt attribute's value should
+  never contain text that could be considered the image's caption, title, or
+  legend. It is supposed to contain replacement text that could be used by users
+  instead of the image; it is not meant to supplement the image. The title attribute can be used for supplemental information.

+
+  
Another corollary is that the alt attribute's value should
+  not repeat information that is already provided in the prose next to the image.

+
+  
One way to think of alternative text is to think about how you would read the page
+  containing the image to someone over the phone, without mentioning that there is an image present.
+  Whatever you say instead of the image is typically a good start for writing the alternative
+  text.

+
+
+  
+
+  
When an a element that creates a hyperlink, or a button
+  element, has no textual content but contains one or more images, the alt attributes must contain text that together convey the purpose of
+  the link or button.

+
+  

+
+   
In this example, a user is asked to pick their preferred color from a list of three. Each color
+   is given by an image, but for users who have configured their user agent not to display images,
+   the color names are used instead:

+
+   
<h1>Pick your color</h1>
+<ul>
+ <li><a href="green.html"><img src="green.jpeg" alt="Green"></a></li>
+ <li><a href="blue.html"><img src="blue.jpeg" alt="Blue"></a></li>
+ <li><a href="red.html"><img src="red.jpeg" alt="Red"></a></li>
+</ul>

+
+  

+
+  

+
+   
In this example, each button has a set of images to indicate the kind of color output desired
+   by the user. The first image is used in each case to give the alternative text.

+
+   
<button name="rgb"><img src="red" alt="RGB"><img src="green" alt=""><img src="blue" alt=""></button>
+<button name="cmyk"><img src="cyan" alt="CMYK"><img src="magenta" alt=""><img src="yellow" alt=""><img src="black" alt=""></button>

+
+   
Since each image represents one part of the text, it could also be written like this:

+
+   
<button name="rgb"><img src="red" alt="R"><img src="green" alt="G"><img src="blue" alt="B"></button>
+<button name="cmyk"><img src="cyan" alt="C"><img src="magenta" alt="M"><img src="yellow" alt="Y"><img src="black" alt="K"></button>

+
+   
However, with other alternative text, this might not work, and putting all the alternative
+   text into one image in each case might make more sense:

+
+   
<button name="rgb"><img src="red" alt="sRGB profile"><img src="green" alt=""><img src="blue" alt=""></button>
+<button name="cmyk"><img src="cyan" alt="CMYK profile"><img src="magenta" alt=""><img src="yellow" alt=""><img src="black" alt=""></button>

+
+  

+
+
+
+  
4.8.4.4.3 A phrase or paragraph with an alternative graphical representation: charts, diagrams, graphs, maps, illustrations

+
+  
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.

+
+  
It is important to realize that the alternative text is a replacement for the image,
+  not a description of the image.

+
+  

+
+   
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 tokenization 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 Input Stream Preprocessor, which passes it to the
+Tokenizer, which passes it 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
+Tokenizer."></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>

+
+   
Text such as "Photo of white house with boarded door" would be equally bad alternative text
+   (though it could be suitable for the title attribute or in the
+   figcaption element of a figure with this image).

+
+  

+
+
+  
4.8.4.4.4 A short phrase or label with an alternative graphical representation: icons, logos

+
+  
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:

+
+   
<nav>
+ <p><a href="/help/"><img src="/icons/help.png" alt=""> Help</a></p>
+ <p><a href="/configure/"><img src="/icons/configuration.png" alt="">
+ Configuration Tools</a></p>
+</nav>

+
+  

+
+  
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, e.g. as a page heading, 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.

+
+  

+
+
+  
4.8.4.4.5 Text that has been rendered to a graphic for typographical effect

+
+  
Sometimes, an image just consists of text, and the purpose of the image is not to highlight the
+  actual typographic effects used to render the text, but just to convey the text itself.

+
+  
In such cases, the alt attribute must be present but must
+  consist of the same text as written in the image itself.

+
+  

+
+   
Consider a graphic containing the text "Earth Day", but with the letters all decorated with
+   flowers and plants. If the text is merely being used as a heading, to spice up the page for
+   graphical users, then the correct alternative text is just the same text "Earth Day", and no
+   mention need be made of the decorations:

+
+   
<h1><img src="earthdayheading.png" alt="Earth Day"></h1>

+
+  

+
+  

+
+   
An illuminated manuscript might use graphics for some of its images. The alternative text in
+   such a situation is just the character that the image represents.

+
+   
<p><img src="initials/o.svg" alt="O">nce upon a time and a long long time ago, late at
+night, when it was dark, over the hills, through the woods, across a great ocean, in a land far
+away, in a small house, on a hill, under a full moon...
 
+
+  

+
+  
When an image is used to represent a character that cannot otherwise be represented in Unicode,
+  for example gaiji, itaiji, or new characters such as novel currency symbols, the alternative text
+  should be a more conventional way of writing the same thing, e.g. using the phonetic hiragana or
+  katakana to give the character's pronunciation.

+
+  

+
+   
In this example from 1997, a new-fangled currency symbol that looks like a curly E with two
+   bars in the middle instead of one is represented using an image. The alternative text gives the
+   character's pronunciation.

+
+   
<p>Only <img src="euro.png" alt="euro ">5.99!

+
+  

+
+  
An image should not be used if characters would serve an identical purpose. Only when the text
+  cannot be directly represented using text, e.g., because of decorations or because there is no
+  appropriate character (as in the case of gaiji), would an image be appropriate.

+
+  
If an author is tempted to use an image because their default system font does not
+  support a given character, then Web Fonts are a better solution than images.

+
+
+
+  
4.8.4.4.6 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.

+
+  
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 flowchart that repeats the previous paragraph in graphical form:

+
+   
<p>The Network passes data to the Input Stream Preprocessor, which
+passes it to the Tokenizer, which passes it 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 Tokenizer.</p>
+<p><img src="images/parsing-model-overview.png" alt=""></p>

+
+   
In these cases, it would be wrong to include alternative text that consists of just a caption.
+   If a caption is to be included, then either the title attribute
+   can be used, or the figure and figcaption elements can be used. In the
+   latter case, the image would in fact be a phrase or paragraph with an alternative graphical
+   representation, and would thus require alternative text.

+
+   
<!-- Using the title="" attribute -->
+<p>The Network passes data to the Input Stream Preprocessor, which
+passes it to the Tokenizer, which passes it 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 Tokenizer.</p>
+<p><img src="images/parsing-model-overview.png" alt=""
+        title="Flowchart representation of the parsing model."></p>

+
+   
<!-- Using <figure> and <figcaption> -->
+<p>The Network passes data to the Input Stream Preprocessor, which
+passes it to the Tokenizer, which passes it 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 Tokenizer.</p>
+<figure>
+ <img src="images/parsing-model-overview.png" alt="The Network leads to
+ the Input Stream Preprocessor, which leads to the Tokenizer, which
+ leads to the Tree Construction stage. The Tree Construction stage
+ leads to two items. The first is Script Execution, which leads via
+ document.write() back to the Tokenizer. The second item from which
+ Tree Construction leads is the DOM. The DOM is related to the Script
+ Execution.">
+ <figcaption>Flowchart representation of the parsing model.</figcaption>
+</figure>

+
+   
<!-- This is WRONG. Do not do this. Instead, do what the above examples do. -->
+<p>The Network passes data to the Input Stream Preprocessor, which
+passes it to the Tokenizer, which passes it 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 Tokenizer.</p>
+<p><img src="images/parsing-model-overview.png"
+        alt="Flowchart representation of the parsing model."></p>
+<!-- Never put the image's caption in the alt="" attribute! -->

+
+  

+
+  

+
+   
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>

+
+  

+
+
+
+  
4.8.4.4.7 Ancillary images

+
+  
Sometimes, an image is not critical to the content, but is nonetheless neither purely
+  decorative nor entirely redundant with the text. In these cases, the alt attribute must be present, and its value should either be the
+  empty string, or a textual representation of the information that the image conveys. If the image
+  has a caption giving the image's title, then the alt
+  attribute's value must not be empty (as that would be quite confusing for non-visual readers).

+
+  

+
+   
Consider a news article about a political figure, in which the individual's face was shown in
+   an image that, through a style sheet, is floated to the right. The image is not purely
+   decorative, as it is relevant to the story. The image is not entirely redundant with the story
+   either, as it shows what the politician looks like. Whether any alternative text need be provided
+   is an authoring decision, in part influenced by whether the image colors the interpretation of
+   the prose.

+
+   
In this first variant, the image is shown without context, and no alternative text is
+   provided:

+
+   
<p><img src="alexsalmond.jpeg" alt=""> Ahead of today's referendum,
+the First Minister of Scotland, Alex Salmond, wrote an open letter to all
+registered voters. In it, he admitted that all countries make mistakes.</p>

+
+   
If the picture is just a face, there might be no value in describing it. It's of no interest
+   to the reader whether the individual has red hair or blond hair, whether the individual has white
+   skin or black skin, whether the individual has one eye or two eyes.

+
+   
However, if the picture is more dynamic, for instance showing the politician as angry, or
+   particularly happy, or devastated, some alternative text would be useful in setting the tone of
+   the article, a tone that might otherwise be missed:

+
+   
<p><img src="alexsalmond.jpeg" alt="Alex Salmond is sad.">
+Ahead of today's referendum, the First Minister of Scotland, Alex Salmond,
+wrote an open letter to all registered voters. In it, he admitted that all
+countries make mistakes.</p>

+
+   
<p><img src="alexsalmond.jpeg" alt="Alex Salmond is ecstatic!">
+Ahead of today's referendum, the First Minister of Scotland, Alex Salmond,
+wrote an open letter to all registered voters. In it, he admitted that all
+countries make mistakes.</p>

+
+   
Whether the individual was "sad" or "ecstatic" makes a difference to how the rest of the
+   paragraph is to be interpreted: is he likely saying that he is resigned to the populace making a
+   bad choice in the upcoming referendum, or is he saying that the election was a mistake but the
+   likely turnout will make it irrelevant? The interpretation varies based on the image.

+
+  

+
+  

+
+   
If the image has a caption, then including alternative text avoids leaving the non-visual user
+   confused as to what the caption refers to.

+
+   
<p>Ahead of today's referendum, the First Minister of Scotland, Alex Salmond,
+wrote an open letter to all registered voters. In it, he admitted that all
+countries make mistakes.</p>
+<figure>
+ <img src="alexsalmond.jpeg"
+      alt="A high forehead, cheerful disposition, and dark hair round out Alex Salmond's face.">
+ <figcaption> Alex Salmond, SNP. Photo © 2014 PolitiPhoto. </figcaption>
+</figure>

+
+  

+
+
+
+  
4.8.4.4.8 A purely decorative image that doesn't add any information

+
+  
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.

+
+  
However, a decorative image that isn't discussed by the surrounding text but still has some
+  relevance can be included in a page using the img element. 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>

+
+  

+
+
+  
+
+  
When a picture has been sliced into smaller image files that are then displayed together to
+  form the complete picture again, one of the images must have its alt attribute set as per the relevant rules that would be appropriate
+  for the picture as a whole, and then all the remaining images must have their alt attribute set to the empty string.

+
+  

+
+   
In the following example, a picture representing a company logo for XYZ
+   Corp has been split into two pieces, the first containing the letters "XYZ" and the second
+   with the word "Corp". The alternative text ("XYZ Corp") is all in the first image.

+
+   
<h1><img src="logo1.png" alt="XYZ Corp"><img src="logo2.png" alt=""></h1>

+
+  

+
+  

+
+   
In the following example, a rating is shown as three filled stars and two empty stars. While
+   the alternative text could have been "★★★☆☆", the author has
+   instead decided to more helpfully give the rating in the form "3 out of 5". That is the
+   alternative text of the first image, and the rest have blank alternative text.

+
+   
<p>Rating: <meter max=5 value=3><img src="1" alt="3 out of 5"
+  ><img src="1" alt=""><img src="1" alt=""><img src="0" alt=""
+  ><img src="0" alt=""></meter></p>

+
+  

+
+
+
+  
+
+  
Generally, image maps should be used instead of slicing an image
+  for links.

+
+  
However, if an image is indeed sliced and any of the components of the sliced picture are the
+  sole contents of links, then one image per link must have alternative text in its alt attribute representing the purpose of the link.

+
+  

+
+   
In the following example, a picture representing the flying spaghetti monster emblem, with
+   each of the left noodly appendages and the right noodly appendages in different images, so that
+   the user can pick the left side or the right side in an adventure.

+
+   
<h1>The Church</h1>
+<p>You come across a flying spaghetti monster. Which side of His
+Noodliness do you wish to reach out for?</p>
+<p><a href="?go=left" ><img src="fsm-left.png"  alt="Left side. "></a
+  ><img src="fsm-middle.png" alt=""
+  ><a href="?go=right"><img src="fsm-right.png" alt="Right side."></a></p>

+
+  

+
+
+
+  
4.8.4.4.11 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.

+
+  
How to provide alternative text for an image that is a key part of the content depends on the
+  image's provenance.

+
+  
The general case

+
+    
When it is possible for detailed 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 can serve as a substitute for the
+    image must be given as the contents of the alt attribute.

+
+    

+
+     
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.">
+ <figcaption>Screenshot of a KDE desktop.</figcaption>
+</figure>

+
+    

+
+    

+
+     
A graph in a financial report:

+
+     
<img src="sales.gif"
+     title="Sales graph"
+     alt="From 1998 to 2005, sales increased by the following percentages
+     with each year: 624%, 75%, 138%, 40%, 35%, 9%, 21%">

+
+     
Note that "sales graph" would be inadequate alternative text for a sales graph. Text that
+     would be a good caption is not generally suitable as replacement text.

+
+    

+
+   
Images that defy a complete description

+
+    
In certain cases, the nature of the image might be such that providing thorough alternative
+    text is impractical. For example, the image could be indistinct, or could be a complex fractal,
+    or could be a detailed topographical map.

+
+    
In these cases, the alt attribute must contain some
+    suitable alternative text, but it may be somewhat brief.

+
+    

+
+     
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. However, a description,
+     even if brief, is still better than nothing:

+
+     
<figure>
+ <img src="/commons/a/a7/Rorschach1.jpg" alt="A shape with left-right
+ symmetry with indistinct edges, with a small gap in the center, two
+ larger gaps offset slightly from the center, with two similar gaps
+ under them. The outline is wider in the top half than the bottom
+ half, with the sides extending upwards higher than the center, and
+ the center extending below the sides.">
+ <figcaption>A black outline of the first of the ten cards
+ in the Rorschach inkblot test.</figcaption>
+</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.">
+ <figcaption>A black outline of the first of the ten cards
+ in the Rorschach inkblot test.</figcaption>
+</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.

+
+    

+
+    

+
+     
Another example of an image that defies full description is a fractal, which, by definition,
+     is infinite in detail.

+
+     
The following example shows one possible way of providing alternative text for the full view
+     of an image of the Mandelbrot set.

+
+     
<img src="ms1.jpeg" alt="The Mandelbrot set appears as a cardioid with
+its cusp on the real axis in the positive direction, with a smaller
+bulb aligned along the same center line, touching it in the negative
+direction, and with these two shapes being surrounded by smaller bulbs
+of various sizes.">

+
+    

+
+    

+
+     
Similarly, a photograph of a person's face, for example in a biography, can be considered
+     quite relevant and key to the content, but it can be hard to fully substitute text for:

+
+     
<section class="bio">
+ <h1>A Biography of Isaac Asimov</h1>
+ <p>Born <b>Isaak Yudovich Ozimov</b> in 1920, Isaac was a prolific author.</p>
+ <p><img src="headpics/asimov.jpeg" alt="Isaac Asimov had dark hair, a tall forehead, and wore glasses.
+ Later in life, he wore long white sideburns.">
+ <p>Asimov was born in Russia, and moved to the US when he was three years old.</p>
+ <p>...
+</section>

+
+     
In such cases it is unnecessary (and indeed discouraged) to include a reference to the
+     presence of the image itself in the alternative text, since such text would be redundant with
+     the browser itself reporting the presence of the image. For example, if the alternative text
+     was "A photo of Isaac Asimov", then a conforming user agent might read that out as "(Image) A
+     photo of Isaac Asimov" rather than the more useful "(Image) Isaac Asimov had dark hair, a tall
+     forehead, and wore glasses...".

+
+    

+
+   
Images whose contents are not known

+
+    
In some unfortunate cases, there might be no alternative text available at all, either
+    because the image is obtained in some automated fashion without any associated alternative text
+    (e.g. a Webcam), or because the page is being generated by a script using user-provided images
+    where the user did not provide suitable or usable alternative text (e.g. photograph sharing
+    sites), or because the author does not themself know what the images represent (e.g. a blind
+    photographer sharing an image on their blog).

+
+    
In such cases, the alt attribute may be omitted, but one of
+    the following conditions must be met as well:

+
+    
  • The img element is in a
+     figure element that contains a figcaption element that contains
+     content other than inter-element whitespace, and, ignoring the
+     figcaption element and its descendants, the figure element has no
+     flow content descendants other than inter-element whitespace and the
+     img element.
  • 
+
+      
    The title attribute is present and has a non-empty
+      value.
    
+
+      
+      
    Relying on the title attribute is currently
+      discouraged as many user agents do not expose the attribute in an accessible manner as
+      required by this specification (e.g. requiring a pointing device such as a mouse to cause a
+      tooltip to appear, which excludes keyboard-only users and touch-only users, such as anyone
+      with a modern phone or tablet).
    
+
+     

+
+    
Such cases are to be kept to an absolute minimum. If there is even the slightest
+    possibility of the author having the ability to provide real alternative text, then it would not
+    be acceptable to omit the alt attribute.

+
+    

+
+     
A photo on a photo-sharing site, if the site received the image with no metadata other than
+     the caption, could be marked up as follows:

+
+     
<figure>
+ <img src="1100670787_6a7c664aef.jpg">
+ <figcaption>Bubbles traveled everywhere with us.</figcaption>
+</figure>

+
+     
It would be better, however, if a detailed description of the important parts of the image
+     obtained from the user and included on the page.

+
+    

+
+    

+
+     
A blind user's blog in which a photo taken by the user is shown. Initially, the user might
+     not have any idea what the photo they took shows:

+
+     
<article>
+ <h1>I took a photo</h1>
+ <p>I went out today and took a photo!</p>
+ <figure>
+  <img src="photo2.jpeg">
+  <figcaption>A photograph taken blindly from my front porch.</figcaption>
+ </figure>
+</article>

+
+     
Eventually though, the user might obtain a description of the image from their friends and
+     could then include alternative text:

+
+     
<article>
+ <h1>I took a photo</h1>
+ <p>I went out today and took a photo!</p>
+ <figure>
+  <img src="photo2.jpeg" alt="The photograph shows my squirrel
+  feeder hanging from the edge of my roof. It is half full, but there
+  are no squirrels around. In the background, out-of-focus trees fill the
+  shot. The feeder is made of wood with a metal grate, and it contains
+  peanuts. The edge of the roof is wooden too, and is painted white
+  with light blue streaks.">
+  <figcaption>A photograph taken blindly from my front porch.</figcaption>
+ </figure>
+</article>

+
+    

+
+    

+
+     
Sometimes the entire point of the image is that a textual description is not available, and
+     the user is to provide the description. For instance, the point of a CAPTCHA image is to see if
+     the user can literally read the graphic. Here is one way to mark up a CAPTCHA (note the title attribute):

+
+     
<p><label>What does this image say?
+<img src="captcha.cgi?id=8934" title="CAPTCHA">
+<input type=text name=captcha></label>
+(If you cannot see the image, you can use an <a
+href="?audio">audio</a> test instead.)</p>

+
+     
Another example would be software that displays images and asks for alternative text
+     precisely for the purpose of then writing a page with correct alternative text. Such a page
+     could have a table of images, like this:

+
+     
<table>
+ <thead>
+  <tr> <th> Image <th> Description
+ <tbody>
+  <tr>
+   <td> <img src="2421.png" title="Image 640 by 100, filename 'banner.gif'">
+   <td> <input name="alt2421">
+  <tr>
+   <td> <img src="2422.png" title="Image 200 by 480, filename 'ad3.gif'">
+   <td> <input name="alt2422">
+</table>

+
+     
Notice that even in this example, as much useful information as possible is still included
+     in the title attribute.

+
+    

+
+    
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 rather
+    than being provided with replacement text when no alternative text is available and none can be
+    made available, as in the above examples. Lack of effort from the part of the author is not an
+    acceptable reason for omitting the alt attribute.

+
+   

+
+
+
+  
4.8.4.4.12 An image not intended for the user

+
+  
Generally authors should avoid using img elements for purposes other than showing
+  images.

+
+  
If an img element is being used for purposes other than showing an image, e.g. as
+  part of a service to count page views, then the alt attribute
+  must be the empty string.

+
+  
In such cases, the width and height attributes should both be set to zero.

+
+
+  
4.8.4.4.13 An image in an e-mail or private document intended for a specific person who is known to be able to view images

+
+  
This section does not apply to documents that are publicly accessible, or whose target
+  audience is not necessarily personally known to the author, such as documents on a Web site,
+  e-mails sent to public mailing lists, or software documentation.

+
+  
When an image is included in a private communication (such as an HTML e-mail) aimed at a
+  specific person who is known to be able to view images, the alt
+  attribute may be omitted. However, even in such cases authors are strongly urged to include
+  alternative text (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 document be forwarded on to other users whose abilities might not
+  include easily seeing images.

+
+
+
+
+  
+
+  
4.8.4.4.14 Guidance for markup generators

+
+  
Markup generators (such as WYSIWYG authoring tools) should, wherever possible, obtain
+  alternative text from their users. However, it is recognized that in many cases, this will not be
+  possible.

+
+  
For images that are the sole contents of links, markup generators should examine the link
+  target to determine the title of the target, or the URL of the target, and use information
+  obtained in this manner as the alternative text.

+
+  
For images that have captions, markup generators should use the figure and
+  figcaption elements, or the title attribute, to
+  provide the image's caption.

+
+  
As a last resort, implementors should either set the alt
+  attribute to the empty string, under the assumption that the image is a purely decorative image
+  that doesn't add any information but is still specific to the surrounding content, or omit the
+  alt attribute altogether, under the assumption that the image is
+  a key part of the content.

+
+  
Markup generators may specify a generator-unable-to-provide-required-alt
+  attribute on img elements for which they have been unable to obtain alternative text
+  and for which they have therefore omitted the alt attribute. The
+  value of this attribute must be the empty string. Documents containing such attributes are not
+  conforming, but conformance checkers will silently
+  ignore this error.

+
+  
This is intended to avoid markup generators from being pressured into replacing
+  the error of omitting the alt attribute with the even more
+  egregious error of providing phony alternative text, because state-of-the-art automated
+  conformance checkers cannot distinguish phony alternative text from correct alternative text.

+
+  
Markup generators should generally avoid using the image's own file name as the alternative
+  text. Similarly, markup generators should avoid generating alternative text from any content that
+  will be equally available to presentation user agents (e.g. Web browsers).

+
+  
This is because once a page is generated, it will typically not be updated,
+  whereas the browsers that later read the page can be updated by the user, therefore the browser is
+  likely to have more up-to-date and finely-tuned heuristics than the markup generator did when
+  generating the page.

+
+  
+
+  
+
+  
4.8.4.4.15 Guidance for conformance checkers

+
+  
A conformance checker must report the lack of an alt
+  attribute as an error unless one of the conditions listed below applies:

+
+  
  • The img element is in a figure element that satisfies the conditions described above.
  • The img element has a title attribute with a
+   value that is not the empty string (also as described
+   above).
  • The conformance checker has been configured to assume that the document is an e-mail or
+   document intended for a specific person who is known to be able to view images.
  • The img element has a (non-conforming) generator-unable-to-provide-required-alt
+   attribute whose value is the empty string. A conformance checker that is not reporting the lack
+   of an alt attribute as an error must also not report the
+   presence of the empty generator-unable-to-provide-required-alt
+   attribute as an error. (This case does not represent a case where the document is conforming,
+   only that the generator could not determine appropriate alternative text — validators are
+   not required to show an error in this case, because such an error might encourage markup
+   generators to include bogus alternative text purely in an attempt to silence validators.
+   Naturally, conformance checkers may report the lack of an alt attribute as an error even in the presence of the generator-unable-to-provide-required-alt
+   attribute; for example, there could be a user option to report all conformance errors
+   even those that might be the more or less inevitable result of using a markup
+   generator.)

+
+  
+
+
+  
4.8.5 The iframe element
Spec bugs: 28773

+
+  
Categories:
Flow content.
Phrasing content.
Embedded content.
Interactive content.
Palpable content.
Contexts in which this element can be used:
Where embedded content is expected.
Content model:
Nothing.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
src — Address of the resource
srcdoc — A document to render in the iframe
name — Name of nested browsing context
sandbox — Security rules for nested content
allowfullscreen — Whether to allow the iframe's contents to use requestFullscreen()
allowpaymentrequest — Whether the iframe's contents are allowed to use the PaymentRequest interface to make payment requests
allowusermedia — Whether to allow the iframe's contents to use getUserMedia()
width — Horizontal dimension
height — Vertical dimension
referrerpolicy — Referrer policy for fetches initiated by the element
DOM interface:

+
[HTMLConstructor]
+interface HTMLIFrameElement : HTMLElement {
+  [CEReactions] attribute USVString src;
+  [CEReactions] attribute DOMString srcdoc;
+  [CEReactions] attribute DOMString name;
+  [SameObject, PutForwards=value] readonly attribute DOMTokenList sandbox;
+  [CEReactions] attribute boolean allowFullscreen;
+  [CEReactions] attribute boolean allowPaymentRequest;
+  [CEReactions] attribute boolean allowUserMedia;
+  [CEReactions] attribute DOMString width;
+  [CEReactions] attribute DOMString height;
+  [CEReactions] attribute DOMString referrerPolicy;
+  readonly attribute Document? contentDocument;
+  readonly attribute WindowProxy? contentWindow;
+  Document? getSVGDocument();
+
+  // also has obsolete members
+};

+   

+
+  
+
+  
The iframe element represents a nested browsing
+  context.

+
+
+  
+
+  
The src attribute gives the URL
+  of a page that the nested browsing context is to contain. The attribute, if present,
+  must be a valid non-empty URL potentially surrounded by spaces. If the itemprop is specified on an iframe element, then the
+  src attribute must also be specified.

+
+  
The srcdoc attribute gives the content of the page that the
+  nested browsing context is to contain. The value of the attribute is the source of
+  an iframe srcdoc
+  document.
Support: iframe-srcdocChrome for Android 57+Chrome 20+UC Browser for Android 11.4+iOS Safari 6.0+Firefox 25+IE NoneSamsung Internet 4+Opera Mini NoneAndroid Browser 4.4+Safari 6+Opera 15+
Source: caniuse.com

+
+  
The srcdoc attribute, if present, must have a value
+  using the HTML syntax that consists of the following syntactic components, in the
+  given order:

+
+  
  1. Any number of comments and ASCII
+   whitespace.
  2. Optionally, a DOCTYPE.
+
+   
  3. Any number of comments and ASCII
+   whitespace.
  4. The document element, in the form of an html element.
  5. Any number of comments and ASCII
+   whitespace.

+
+  
The above requirements apply in XML documents as well.
+
+  

+
+   
Here a blog uses the srcdoc attribute in conjunction
+   with the sandbox attribute described below to provide
+   users of user agents that support this feature with an extra layer of protection from script
+   injection in the blog post comments:

+
+   
<article>
+ <h1>I got my own magazine!</h1>
+ <p>After much effort, I've finally found a publisher, and so now I
+ have my own magazine! Isn't that awesome?! The first issue will come
+ out in September, and we have articles about getting food, and about
+ getting in boxes, it's going to be great!</p>
+ <footer>
+  <p>Written by <a href="/users/cap">cap</a>, 1 hour ago.
+ </footer>
+ <article>
+  <footer> Thirteen minutes ago, <a href="/users/ch">ch</a> wrote: </footer>
+  <iframe sandbox srcdoc="<p>did you get a cover picture yet?"></iframe>
+ </article>
+ <article>
+  <footer> Nine minutes ago, <a href="/users/cap">cap</a> wrote: </footer>
+  <iframe sandbox srcdoc="<p>Yeah, you can see it <a href=&quot;/gallery?mode=cover&amp;amp;page=1&quot;>in my gallery</a>."></iframe>
+ </article>
+ <article>
+  <footer> Five minutes ago, <a href="/users/ch">ch</a> wrote: </footer>
+  <iframe sandbox srcdoc="<p>hey that's earl's table.
+<p>you should get earl&amp;amp;me on the next cover."></iframe>
+ </article>

+
+   
Notice the way that quotes have to be escaped (otherwise the srcdoc attribute would end prematurely), and the way raw
+   ampersands (e.g. in URLs or in prose) mentioned in the sandboxed content have to be
+   doubly escaped — once so that the ampersand is preserved when originally parsing
+   the srcdoc attribute, and once more to prevent the
+   ampersand from being misinterpreted when parsing the sandboxed content.

+
+   
Furthermore, notice that since the DOCTYPE is optional in
+   iframe srcdoc documents, and the html,
+   head, and body elements have optional
+   start and end tags, and the title element is also optional in iframe srcdoc
+   documents, the markup in a srcdoc attribute can be
+   relatively succinct despite representing an entire document, since only the contents of the
+   body element need appear literally in the syntax. The other elements are still
+   present, but only by implication.

+
+  

+
+  
In the HTML syntax, authors need only remember to use U+0022
+  QUOTATION MARK characters (") to wrap the attribute contents and then to escape all U+0022
+  QUOTATION MARK (") and U+0026 AMPERSAND (&) characters, and to specify the sandbox attribute, to ensure safe embedding of content.

+
+  
In XML the U+003C LESS-THAN SIGN character (<) needs to be escaped as well. In
+  order to prevent attribute-value
+  normalization, some of XML's whitespace characters — specifically U+0009 CHARACTER
+  TABULATION (tab), U+000A LINE FEED (LF), and U+000D CARRIAGE RETURN (CR) — also need to be
+  escaped. [XML]

+
+  
If the src attribute and the srcdoc attribute are both specified together, the srcdoc attribute takes priority. This allows authors to provide
+  a fallback URL for legacy user agents that do not support the srcdoc attribute.

+
+
+  
+
+  
 
+
+  
When an iframe element is inserted
+  into a document that has a browsing context, the
+  user agent must create a new browsing
+  context, set the element's nested browsing context to the newly-created
+  browsing context, and then process the iframe attributes
+  for the "first time".

+
+  
When an iframe element is removed
+  from a document, the user agent must discard the element's nested browsing context, if it is not null,
+  and then set the element's nested browsing context to null.

+
+  
This happens without any unload events firing
+  (the nested browsing context and its Document are discarded, not unloaded).

+
+  
+
+  
Whenever an iframe element with a non-null nested browsing context
+  has its srcdoc attribute set, changed, or removed, the
+  user agent must process the iframe attributes.

+
+  
Similarly, whenever an iframe element with a non-null nested browsing
+  context but with no srcdoc attribute specified has
+  its src attribute set, changed, or removed, the user agent
+  must process the iframe attributes.
 
+
+  
When the user agent is to process the iframe attributes, it must run
+  the first appropriate steps from the following list:

+
+  
If the srcdoc attribute is specified

+
+    
Navigate the element's nested browsing context
+    to a new response whose url list consists of about:srcdoc, header list consists of `Content-Type`/`text/html, body is the value of the attribute, CSP list is the CSP list of the iframe element's node
+    document, HTTPS state is the HTTPS state of the iframe element's
+    node document.
+
+    
The resulting Document must be considered an iframe srcdoc document.

+
+   
Otherwise, if the element has no src attribute
+   specified, and the user agent is processing the iframe's attributes for the "first
+   time"

+
+    
Queue a task to run the iframe load event steps.

+
+    
The task source for this task is the
+    DOM manipulation task source.

+
+   
Otherwise
Run the otherwise steps for iframe or frame
+   elements.

+
+  
The otherwise steps for iframe or frame elements are as
+  follows:

+
+  
  1. 
+    
    If the element has no src attribute specified, or its
+    value is the empty string, let url be the URL
+    "about:blank".
    
+    
+
+    
    Otherwise, parse the value of the src attribute, relative to the element's node
+    document.
    
+
+    
    If that is not successful, then let url be the URL
+    "about:blank". Otherwise, let url be the resulting URL
+    record.
    
+   
  2. If there exists an ancestor browsing context whose active
+   document's URL, ignoring fragments, is equal to url, then abort these
+   steps.
  3. Let resource be a new request whose url is url and whose referrer policy is the current state of the
+   element's referrerpolicy content
+   attribute.
  4. Navigate the element's nested browsing
+   context to resource.

+
+  
Any navigation required of the user agent in the process
+  the iframe attributes algorithm must use the iframe element's
+  node document's browsing context as the source browsing
+  context.

+
+  
Furthermore, if the active document of the element's nested browsing
+  context before such a navigation was not completely
+  loaded at the time of the new navigation, then the navigation must be completed with replacement enabled.

+
+  
Similarly, if the nested browsing context's session history contained
+  only one Document when the process the iframe attributes
+  algorithm was invoked, and that was the about:blank Document created
+  when the nested browsing context was created, then any navigation required of the user agent in that algorithm must be completed
+  with replacement enabled.
 
+
+  
When a Document in an iframe is marked as completely
+  loaded, the user agent must run the iframe load event steps in parallel.

+
+  
A load event is also fired at the
+  iframe element when it is created if no other data is loaded in it.

+
+  
Each Document has an iframe load in progress flag and a mute
+  iframe load flag. When a Document is created, these flags must be unset for
+  that Document.

+
+  
The iframe load event steps are as follows:

+
+  
  1. Let child document be the active document of the
+   iframe element's nested browsing context (which cannot be null at this
+   point).
  2. If child document has its mute iframe load flag set,
+   abort these steps.
  3. Set child document's iframe load in progress
+   flag.
  4. Fire an event named load at the iframe element.
  5. Unset child document's iframe load in progress
+   flag.

+
+  
This, in conjunction with scripting, can be used to probe the URL space of the
+  local network's HTTP servers. User agents may implement cross-origin
+  access control policies that are stricter than those described above to mitigate this attack, but
+  unfortunately such policies are typically not compatible with existing Web content.

+
+  
When the iframe's browsing context's active document is
+  not ready for post-load tasks, and when anything in the iframe is delaying the load event of the iframe's
+  browsing context's active document, and when the iframe's
+  browsing context is in the delaying load events
+  mode, the iframe must delay the load event of its document.

+
+  
If, during the handling of the load event, the
+  browsing context in the iframe is again navigated, that will further delay the load event.

+
+  
+
+  
+
+  
If, when the element is created, the srcdoc attribute is not set, and the src attribute is either also not set or set but its value cannot be
+  parsed, the browsing context will remain at the initial
+  about:blank page.

+
+  
If the user navigates away from this page, the
+  iframe's corresponding WindowProxy object will proxy new
+  Window objects for new Document objects, but the src attribute will not change.

+
+
+  
 
+
+  
The name attribute, if present, must be a
+  valid browsing context name. The given value is used to name the nested
+  browsing context. When the browsing context is created, if the attribute
+  is present, the browsing context name must be set to the value of this attribute;
+  otherwise, the browsing context name must be set to the empty string.

+
+  
+
+  
Whenever the name attribute is set, the nested
+  browsing context's name must be changed to
+  the new value. If the attribute is removed, the browsing context name must be set to
+  the empty string.

+
+  
+
+
+  
 
+
+  
The sandbox attribute, when specified,
+  enables a set of extra restrictions on any content hosted by the iframe. Its value
+  must be an unordered set of unique space-separated tokens that are ASCII
+  case-insensitive. The allowed values are allow-forms, allow-modals, allow-orientation-lock, allow-pointer-lock, allow-popups, allow-popups-to-escape-sandbox,
+  allow-presentation, allow-same-origin, allow-scripts, allow-top-navigation, and allow-top-navigation-by-user-activation.
Support: iframe-sandboxChrome for Android 57+Chrome 4+UC Browser for Android 11.4+iOS Safari 4.2+Firefox 28+IE 10+Samsung Internet 4+Opera Mini NoneAndroid Browser 2.2+Edge 12+Safari 5+Opera 15+
Source: caniuse.com

+
+  
When the attribute is set, the content is treated as being from a unique origin,
+  forms, scripts, and various potentially annoying APIs are disabled, links are prevented from
+  targeting other browsing contexts, and plugins are secured.
+  The allow-same-origin keyword causes
+  the content to be treated as being from its real origin instead of forcing it into a unique
+  origin; the allow-top-navigation
+  keyword allows the content to navigate its top-level browsing context;
+  the allow-top-navigation-by-user-activation
+  keyword behaves similarly but only allows such navigation when
+  triggered by user activation; and the allow-forms, allow-modals, allow-orientation-lock, allow-pointer-lock, allow-popups, allow-presentation, allow-scripts, and allow-popups-to-escape-sandbox
+  keywords re-enable forms, modal dialogs, screen orientation lock, the pointer lock API, popups,
+  the presentation API, scripts, and the creation of unsandboxed auxiliary browsing contexts respectively. [POINTERLOCK]
+  [SCREENORIENTATION] [PRESENTATION]

+
+  
The allow-top-navigation and allow-top-navigation-by-user-activation
+  keywords must not both be specified, as doing so is redundant; only allow-top-navigation will have an effect
+  in such non-conformant markup.

+
+  
Setting both the allow-scripts and allow-same-origin keywords together when the
+  embedded page has the same origin as the page containing the iframe
+  allows the embedded page to simply remove the sandbox
+  attribute and then reload itself, effectively breaking out of the sandbox altogether.

+
+  
These flags only take effect when the nested browsing context of
+  the iframe is navigated. Removing them, or removing the
+  entire sandbox attribute, has no effect on an
+  already-loaded page.

+
+  
Potentially hostile files should not be served from the same server as the file
+  containing the iframe element. Sandboxing hostile content is of minimal help if an
+  attacker can convince the user to just visit the hostile content directly, rather than in the
+  iframe. To limit the damage that can be caused by hostile HTML content, it should be
+  served from a separate dedicated domain. Using a different domain ensures that scripts in the
+  files are unable to attack the site, even if the user is tricked into visiting those pages
+  directly, without the protection of the sandbox
+  attribute.

+
+  
+
+  
+
+  
When an iframe element with a sandbox
+  attribute has its nested browsing context created (before the initial
+  about:blank Document is created), and when an iframe
+  element's sandbox attribute is set or changed while it
+  has a nested browsing context, the user agent must parse the sandboxing directive using the attribute's value as the
+  input and the iframe element's nested browsing context's
+  iframe sandboxing flag set as the output.

+
+  
When an iframe element's sandbox
+  attribute is removed while it has a non-null nested browsing context, the user agent
+  must empty the iframe element's nested browsing context's
+  iframe sandboxing flag set as the output.

+
+  
+
+  

+
+   
In this example, some completely-unknown, potentially hostile, user-provided HTML content is
+   embedded in a page. Because it is served from a separate domain, 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).

+
+   
<p>We're not scared of you! Here is your content, unedited:</p>
+<iframe sandbox src="https://usercontent.example.net/getusercontent.cgi?id=12193"></iframe>

+
+   
It is important to use a separate domain so that if the attacker convinces the
+   user to visit that page directly, the page doesn't run in the context of the site's origin, which
+   would make the user vulnerable to any attack found in the page.

+
+  

+
+  

+
+   
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.

+
+   
<iframe sandbox="allow-same-origin allow-forms allow-scripts"
+        src="https://maps.example.com/embedded.html"></iframe>

+
+  

+
+  

+
+   
Suppose a file A contained the following fragment:

+
+   
<iframe sandbox="allow-same-origin allow-forms" src=B></iframe>

+
+   
Suppose that file B contained an iframe also:

+
+   
<iframe sandbox="allow-scripts" src=C></iframe>

+
+   
Further, suppose that file C contained a link:

+
+   
<a href=D>Link</a>

+
+   
For this example, suppose all the files were served as text/html.

+
+   
Page C in this scenario has all the sandboxing flags set. Scripts are disabled, because the
+   iframe in A has scripts disabled, and this overrides the allow-scripts keyword set on the
+   iframe in B. Forms are also disabled, because the inner iframe (in B)
+   does not have the allow-forms keyword
+   set.

+
+   
Suppose now that a script in A removes all the sandbox attributes in A  and B.
+   This would change nothing immediately. If the user clicked the link in C, loading page D into the
+   iframe in B, page D would now act as if the iframe in B had the allow-same-origin and allow-forms keywords set, because that was the
+   state of the nested browsing context in the iframe in A when page B was
+   loaded.

+
+   
Generally speaking, dynamically removing or changing the sandbox attribute is ill-advised, because it can make it quite
+   hard to reason about what will be allowed and what will not.

+
+  

+
+
+  
 
+
+  
The allowfullscreen attribute is a
+  boolean attribute. When specified, it indicates that Document objects in
+  the iframe element's browsing context are to be allowed to use requestFullscreen() (if it's not blocked for other
+  reasons, e.g. there is another ancestor iframe without this attribute set).

+
+  

+
+   
Here, an iframe is used to embed a player from a video site. The allowfullscreen attribute is needed to enable the
+   player to show its video fullscreen.

+
+   
<article>
+ <header>
+  <p><img src="/usericons/1627591962735"> <b>Fred Flintstone</b></p>
+  <p><a href="/posts/3095182851" rel=bookmark>12:44</a> — <a href="#acl-3095182851">Private Post</a></p>
+ </header>
+ <main>
+  <p>Check out my new ride!</p>
+  <iframe src="https://video.example.com/embed?id=92469812" allowfullscreen></iframe>
+ </main>
+</article>

+
+  

+
+  
The allowpaymentrequest
+  attribute is a boolean attribute. When specified, it indicates that
+  Document objects in the iframe element's browsing context
+  are to be allowed to use the PaymentRequest interface to make payment requests.

+
+  
The allowusermedia attribute is a
+  boolean attribute. When specified, it indicates that Document objects in
+  the iframe element's browsing context are to be allowed to use getUserMedia() (if it's not blocked for other
+  reasons, e.g. there is another ancestor iframe without this attribute set).

+
+  
+   
To determine whether a Document object document
+   is allowed to use the feature indicated by attribute name
+   allowattribute, run these steps:

+
+   
  1. If document has no browsing context,
+    then return false.
  2. If document's browsing context's
+    active document is not document, then return false.
  3. If document's browsing context is a
+    top-level browsing context, then return true.
  4. 
+     
    If allowattribute is allowfullscreen, then:
    
+
+     
    1. If document's browsing context has
+      a browsing context container that is an iframe element with an
+      allowattribute attribute specified, and whose node document is
+      allowed to use the feature indicated by allowattribute, then return
+      true.
    
+
+     
    This step is legacy behavior for the allowfullscreen attribute that should not be used
+     for new features. If possible this will be removed, see issue 2143.
    
+    
  5. 
+     
    Otherwise:
    
+
+     
    1. If document has the allowattribute flag set, and
+      document's browsing context has a
+      browsing context container that is an iframe element whose
+      node document is allowed to use the feature indicated by
+      allowattribute, then return true.
    
+    
  6. Return false.

+
+   
To set the allow* flags for a Document document means to
+   run these steps:

+
+   
  1. 
+     
    If document's browsing context has a
+     browsing context container whose node document's origin
+     is same origin-domain with document's origin, then set the
+     allowpaymentrequest flag and the allowusermedia flag on
+     document, and abort these steps.
    
+
+     
    If document.domain has been used for
+     the browsing context container's node document, then its
+     origin cannot be same origin-domain with document's
+     origin, because these steps run when document is initialized so it
+     cannot itself yet have used document.domain. Note
+     that this is less permissive compared to doing a same origin check instead.
    
+
+     
    
+      
    In this example, the child document is not allowed to use PaymentRequest,
+      despite being same origin-domain at the time the child document tries to use it.
+      At the time the child document is initialized, only the parent document has set document.domain, and the child document has not.
    
+
+      
    <!-- https://foo.example.com/a.html -->
+<!doctype html>
+<script>
+ document.domain = 'example.com';
+</script>
+<iframe src=b.html></iframe>
    
+
+      
    <!-- https://bar.example.com/b.html -->
+<!doctype html>
+<script>
+ document.domain = 'example.com'; // This happens after the document is initialized
+ new PaymentRequest(…); // Not allowed to use
+</script>
    
+     
    
+
+     
    
+      
    In this example, the child document is allowed to use PaymentRequest,
+      despite not being same origin-domain at the time the child document tries to use
+      it. At the time the child document is initialized, none of the documents have set document.domain yet so same origin-domain
+      falls back to a normal same origin check.
    
+
+      
    <!-- https://example.com/a.html -->
+<!doctype html>
+<iframe src=b.html></iframe>
+<!-- The child document is now initialized, before the script below is run. -->
+<script>
+ document.domain = 'example.com';
+</script>
    
+
+      
    <!-- https://example.com/b.html -->
+<!doctype html>
+<script>
+ new PaymentRequest(…); // Allowed to use
+</script>
    
+     
    
+    
  2. If document's browsing context has a
+    browsing context container that is an iframe element, let
+    iframe be that element. Otherwise, abort these steps.
  3. If iframe has an allowpaymentrequest attribute specified, then
+    set the allowpaymentrequest flag on document.
  4. If iframe has an allowusermedia attribute specified, then set the
+    allowusermedia flag on document.

+  
+
+  
 
+
+  
The iframe element supports dimension attributes for cases where the
+  embedded content has specific dimensions (e.g. ad units have well-defined dimensions).

+
+  
An iframe element never has fallback content, as it will always
+  create a nested browsing context, regardless of whether the specified initial
+  contents are successfully used.

+
+  
 
+
+  
The referrerpolicy attribute is a
+  referrer policy attribute. Its purpose is to set the referrer policy
+  used when processing the iframe
+  attributes. [REFERRERPOLICY]

+
+  
 
+
+  
Descendants of iframe elements represent nothing. (In legacy user agents that do
+  not support iframe elements, the contents would be parsed as markup that could act as
+  fallback content.)

+
+  
The HTML parser treats markup inside iframe elements as
+  text.

+
+
+  
+
+  
 
+
+  
The IDL attributes src, srcdoc, name,and sandbox must reflect the respective content
+  attributes of the same name.

+
+  
The supported tokens for sandbox's DOMTokenList are the allowed
+  values defined in the sandbox attribute and supported by
+  the user agent.

+
+  
The allowFullscreen IDL attribute
+  must reflect the allowfullscreen
+  content attribute.

+
+  
The allowPaymentRequest IDL
+  attribute must reflect the allowpaymentrequest content attribute.

+
+  
The allowUserMedia IDL attribute
+  must reflect the allowusermedia
+  content attribute.

+
+  
The referrerPolicy IDL attribute
+  must reflect the referrerpolicy
+  content attribute, limited to only known values.

+
+  
The contentDocument IDL attribute,
+  on getting, must return the iframe element's content document.

+
+  
The contentWindow IDL attribute must
+  return the WindowProxy object of the iframe element's nested
+  browsing context, if its nested browsing context is non-null, or null
+  otherwise.

+
+  
+
+  

+
+   
Here is an example of a page using an iframe to include advertising from an
+   advertising broker:

+
+   
<iframe src="https://ads.example.com/?customerid=923513721&amp;format=banner"
+        width="468" height="60"></iframe>

+
+  

+
+
+
+
+  
4.8.6 The embed element

+
+
+
+  
Categories:
Flow content.
Phrasing content.
Embedded content.
Interactive content.
Palpable content.
Contexts in which this element can be used:
Where embedded content is expected.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
src — Address of the resource
type — Type of embedded resource
width — Horizontal dimension
height — Vertical dimension
Any other attribute that has no namespace (see prose).
DOM interface:

+
[HTMLConstructor]
+interface HTMLEmbedElement : HTMLElement {
+  [CEReactions] attribute USVString src;
+  [CEReactions] attribute DOMString type;
+  [CEReactions] attribute DOMString width;
+  [CEReactions] attribute DOMString height;
+  Document? getSVGDocument();
+
+  // also has obsolete members
+};

+    
+    
Depending on the type of content instantiated by the
+    embed element, the node may also support other
+    interfaces.

+    
+   

+
+  
The embed element provides an integration point for an external (typically
+  non-HTML) application or interactive content.

+
+  
The src attribute gives the URL of
+  the resource being embedded. The attribute, if present, must contain a valid non-empty URL
+  potentially surrounded by spaces.

+
+  
If the itemprop attribute is specified on an
+  embed element, then the src attribute must also
+  be specified.

+
+  
The type attribute, if present, gives the
+  MIME type by which the plugin to instantiate is selected. The value must be a
+  valid MIME type. If both the type attribute and
+  the src attribute are present, then the type attribute must specify the same type as the explicit Content-Type metadata of the resource given by the src attribute.

+
+  
+
+  
While any of the following conditions are occurring, any plugin instantiated for
+  the element must be removed, and the embed element represents
+  nothing:

+
+  
+
+  
An embed element is said to be potentially
+  active when the following conditions are all met simultaneously:

+
+  
+
+  
Whenever an embed element that was not potentially active becomes potentially active, and whenever a potentially active embed element that is
+  remaining potentially active and has its src attribute set, changed, or removed or its type attribute set, changed, or removed, the user agent must
+  queue a task using the embed task source to run the
+  embed element setup steps.

+
+  
The embed element setup steps are as follows:

+
+  
  1. If another task has since been queued to run the
+   embed element setup steps for this element, then abort these steps.
  2. If the Should element be blocked a priori by Content Security
+   Policy? algorithm returns "Blocked" when executed on the element,
+   then abort these steps. [CSP]
  3. 
+
+    
    If the element has a src attribute set
    
+
+      
    The user agent must parse the value of the element's
+      src attribute, relative to the element's node
+      document. If that is successful, the user agent should run these steps:
+
+      
    1. Let request be a new request whose
+       url is the resulting URL record,
+       client is the element's node
+       document's Window object's environment settings object,
+       destination is "embed", credentials
+       mode is "include", and whose use-URL-credentials
+       flag is set.
    2. Fetch request.
    
+
+      
    The task that is queued by the networking task source once the
+      resource has been fetched must run the following steps:
    
+      
+
+      
    1. If another task has since been queued to run
+       the embed element setup steps for this element, then abort these
+       steps.
    2. 
+
+        
      Determine the type of the content being embedded, as
+        follows (stopping at the first substep that determines the type):
      
+
+        
      1. If the element has a type attribute, and that
+attribute's value is a type that a plugin supports, then the value of the
+         type attribute is the content's type.
      2. 
+
+          
+
+          
        Otherwise, if applying the URL parser algorithm to the URL of
+          the specified resource (after any redirects) results in a URL record whose
+          path component matches a pattern that a
+          plugin supports, then the content's
+          type is the type that that plugin can handle.
        
+
+          
        For example, a plugin might say that it can handle resources with path components that end with the four character string
+          ".swf".
        
+
+          
+          
+
+         
      3. Otherwise, if the specified resource has explicit
+         Content-Type metadata, then that is the content's
+         type.
      4. Otherwise, the content has no type and there
+         can be no appropriate plugin for it.
      
+
+       
    3. 
+
+        
      If the previous step determined that the content's
+        type is image/svg+xml, then run the following substeps:
      
+
+        
      1. If the embed element's nested browsing context is null,
+         set the element's nested browsing context to a newly-created browsing context, and, if the element has a name attribute, set the browsing context name
+         of the element's new nested browsing context to the value of this
+         attribute.
        
+         
+
+         
      2. Navigate the nested browsing context to
+         the fetched resource, with replacement enabled, and with the
+         embed element's node document's browsing context as the source browsing
+         context. (The src attribute of the
+         embed element doesn't get updated if the browsing context gets further
+         navigated to other locations.)
      3. The embed element now represents its nested browsing
+         context.
      
+
+       
    4. 
+
+        
      Otherwise, find and instantiate an appropriate plugin based on the content's type, and hand that plugin the
+        content of the resource, replacing any previously instantiated plugin for the element. The
+        embed element now represents this plugin instance.
      
+
+       
    5. Once the resource or plugin has completely loaded, queue a task to fire an event named load
+       at the element.
    
+
+      
    Whether the resource is fetched successfully or not (e.g. whether the response status was
+      an ok status) must be ignored when determining the content's type and when handing the resource to the
+      plugin.
    
+
+      
    This allows servers to return data for plugins even with error responses (e.g.
+      HTTP 500 Internal Server Error codes can still contain plugin data).
    
+
+      
    Fetching the resource must delay the load event of the element's node document.
    
+      
+      
+      
+
+     
    If the element has no src attribute set
    
+
+      
    The user agent should find and instantiate an appropriate plugin based on the
+      value of the type attribute. The embed
+      element now represents this plugin instance.
    
+
+      
    Once the plugin is completely loaded, queue a task to fire an event named load
+      at the element.
    
+
+     
    
+
+   

+
+  
The embed element has no fallback content. If the user agent can't
+  find a suitable plugin when attempting to find and instantiate one for the algorithm above, then
+  the user agent must use a default plugin. This default could be as simple as saying "Unsupported
+  Format".

+
+  
Whenever an embed element that was potentially
+  active stops being potentially active, any
+  plugin that had been instantiated for that element must be unloaded.

+
+  
When a plugin is to be instantiated but it cannot be secured and the sandboxed plugins browsing context
+  flag is set on the embed element's node document's active
+  sandboxing flag set, then the user agent must not instantiate the plugin, and
+  must instead render the embed element in a manner that conveys that the
+  plugin was disabled. The user agent may offer the user the option to override the
+  sandbox and instantiate the plugin anyway; if the user invokes such an option, the
+  user agent must act as if the conditions above did not apply for the purposes of this element.

+
+  
Plugins that cannot be secured 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.

+
+  
When an embed element has a non-null nested browsing context: if the
+  embed element's nested browsing context's active document
+  is not ready for post-load tasks, and when anything is delaying the load event of the embed element's browsing
+  context's active document, and when the embed element's
+  browsing context is in the delaying load
+  events mode, the embed must delay the load event of its
+  document.

+
+  
The task source for the tasks mentioned in this
+  section is the DOM manipulation task source.

+
+  
+
+  
Any namespace-less attribute other than name, align, hspace, and vspace  may be
+  specified on the embed element, so long as its name is XML-compatible
+  and contains no ASCII upper alphas. These attributes are
+  then passed as parameters to the plugin.

+
+  
All attributes in HTML documents get lowercased automatically, so the
+  restriction on uppercase letters doesn't affect such documents.

+
+  
The four exceptions are to exclude legacy attributes that have side-effects beyond
+  just sending parameters to the plugin.

+
+  
+
+  
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, when one is instantiated.

+
+  
The HTMLEmbedElement object representing the element must expose the scriptable
+  interface of the plugin instantiated for the embed element, if any.

+
+  
+
+  
The embed element supports dimension attributes.

+
+  
+
+  
The IDL attributes src and type each must reflect the respective
+  content attributes of the same name.

+
+  
+
+  

+
+   
Here's a way to embed a resource that requires a proprietary plugin, like Flash:

+
+   
<embed src="catgame.swf">

+
+   
If the user does not have the plugin (for example if the plugin vendor doesn't support the
+   user's platform), then the user will be unable to use the resource.

+
+   
To pass the plugin a parameter "quality" with the value "high", an attribute can be
+   specified:

+
+   
<embed src="catgame.swf" quality="high">

+
+   
This would be equivalent to the following, when using an object element
+   instead:

+
+   
<object data="catgame.swf">
+ <param name="quality" value="high">
+</object>

+
+  

+
+
+
+
+  
4.8.7 The object element
Spec bugs: 25553, 27480, 24852

+
+  
Categories:
Flow content.
Phrasing content.
Embedded content.
If the element has a usemap attribute: Interactive content.
Listed and submittable form-associated element.
Palpable content.
Contexts in which this element can be used:
Where embedded content is expected.
Content model:
Zero or more param elements, then, transparent.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
data — Address of the resource
type — Type of embedded resource
typemustmatch — Whether the type attribute and the Content-Type value need to match for the resource to be used
name — Name of nested browsing context
usemap — Name of image map to use
form — Associates the control with a form element
width — Horizontal dimension
height — Vertical dimension
DOM interface:

+
[HTMLConstructor]
+interface HTMLObjectElement : HTMLElement {
+  [CEReactions] attribute USVString data;
+  [CEReactions] attribute DOMString type;
+  [CEReactions] attribute boolean typeMustMatch;
+  [CEReactions] attribute DOMString name;
+  [CEReactions] attribute DOMString useMap;
+  readonly attribute HTMLFormElement? form;
+  [CEReactions] attribute DOMString width;
+  [CEReactions] attribute DOMString height;
+  readonly attribute Document? contentDocument;
+  readonly attribute WindowProxy? contentWindow;
+  Document? getSVGDocument();
+
+  readonly attribute boolean willValidate;
+  readonly attribute ValidityState validity;
+  readonly attribute DOMString validationMessage;
+  boolean checkValidity();
+  boolean reportValidity();
+  void setCustomValidity(DOMString error);
+
+  // also has obsolete members
+};

+    
+    
Depending on the type of content instantiated by the
+    object element, the node also supports 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
+  URL of the resource. If present, the attribute must be a valid non-empty URL
+  potentially surrounded by spaces.

+
+  
Authors who reference resources from other origins
+  that they do not trust are urged to use the typemustmatch attribute defined below. Without that
+  attribute, it is possible in certain cases for an attacker on the remote host to use the plugin
+  mechanism to run arbitrary scripts, even if the author has used features such as the Flash
+  "allowScriptAccess" parameter.
 
+
+  
The type attribute, if present, specifies the
+  type of the resource. If present, the attribute must be a valid MIME type.

+
+  
At least one of either the data attribute or the type attribute must be present.

+
+  
If the itemprop attribute is specified on an object
+  element, then the data attribute must also be specified.

+
+  
The typemustmatch attribute is a
+  boolean attribute whose presence indicates that the resource specified by the data attribute is only to be used if the value of the type attribute and the Content-Type of the
+  aforementioned resource match.

+
+  
The typemustmatch attribute must not be
+  specified unless both the data attribute and the type attribute are present.

+
+  
The name attribute, if present, must be a
+  valid browsing context name. The given value is used to name the nested
+  browsing context, if applicable.

+
+  
+
+  
Whenever one of the following conditions occur:

+
+   
+
+  
...the user agent must queue a task to run the following steps to (re)determine
+  what the object element represents. This task
+  being queued or actively running must delay the load
+  event of the element's node document. 

+
+  
  1. 
+
+    
    If the user has indicated a preference that this object element's fallback
+    content be shown instead of the element's usual behavior, then jump to the step below
+    labeled fallback.
    
+
+    
    For example, a user could ask for the element's fallback content to
+    be shown because that content uses a format that the user finds more accessible.
    
+
+   
  2. 
+
+    
    If the element has an ancestor media element, or has an ancestor
+    object element that is not showing its fallback content, or
+    if the element is not in a document that has a browsing context, or if the element's node
+    document is not fully active, or if the element is still in the stack
+    of open elements of an HTML parser or XML parser, or if the
+    element is not being rendered, or if the Should element be blocked
+    a priori by Content Security Policy? algorithm returns "Blocked" when executed on the element, then jump to the step below labeled
+    fallback. [CSP]
    
+
+   
  3. 
+
+    
+
+    
    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 either plugins aren't being sandboxed or that
+    plugin can be secured, then that
+    plugin should 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 step below labeled fallback.
    
+
+    
+
+   
  4. If the data attribute is present and its value is
+   not the empty string, then:
    
+
+    
    1. 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 step below labeled fallback
+     without fetching the content to examine its real type.
    2. Parse the URL specified by the data attribute, relative to the element's node
+     document.
    3. If that failed, fire an event named error at the element, then jump to the step below labeled
+     fallback.
    4. Let request be a new request whose
+     url is the resulting URL record,
+     client is the element's node
+     document's Window object's environment settings object,
+     destination is "object", credentials
+     mode is "include", and whose use-URL-credentials
+     flag is set.
    5. 
+
+      
      Fetch request.
      
+
+      
+      
      Fetching the resource must delay the load event of the element's node
+      document until the task that is queued by the networking task source once the resource has been
+      fetched (defined next) has been run.
      
+
+      
      For the purposes of the application cache networking model, this fetch
+      operation is not for a child browsing context (though it might end up being used
+      for one after all, as defined below).
      
+
+     
    6. 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 step below labeled fallback. The task that is
+     queued by the networking task source once the
+     resource is available must 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.
    7. If the load failed (e.g. there was an HTTP 404 error, there was a DNS error), fire an event named error
+     at the element, then jump to the step below labeled fallback.
    8. 
+
+      
      Determine the resource type, as follows:
      
+
+
+
+      
      1. 
+
+        
        Let the resource type be unknown.
        
+
+       
      2. 
+
+        
        If the object element has a type
+        attribute and a typemustmatch attribute, and
+        the resource has associated Content-Type metadata, and the
+        type specified in the resource's Content-Type metadata is
+        an ASCII case-insensitive match for the value of the element's type attribute, then let resource type
+        be that type and jump to the step below labeled handler.
        
+
+        
+
+       
      3. 
+
+        
        If the object element has a typemustmatch attribute, jump to the step below
+        labeled handler.
        
+
+       
      4. 
+
+        
+
+        
        If the user agent is configured to strictly obey Content-Type headers for this resource,
+        and the resource has associated Content-Type metadata,
+        then let the resource type be the type specified in the resource's Content-Type metadata, and jump to the step below
+        labeled handler.
        
+
+        
        This can introduce a vulnerability, wherein a site is trying to embed a
+        resource that uses a particular plugin, but the remote site overrides that and instead
+        furnishes the user agent with a resource that triggers a different plugin with different
+        security characteristics. 
        
+
+       
      5. 
+
+        
        If there is a type attribute present on the
+        object element, and that attribute's value is not a type that the user agent
+        supports, but it is a type that a plugin supports, then let the resource type be the type specified in that type attribute, and jump to the step below labeled
+        handler.
        
+
+       
      6. 
+
+        
        Run the appropriate set of steps from the following
+        list:
        
+
+        
        If the resource has associated Content-Type
+         metadata
        
+
+          
        1. 
+
+            
          Let binary be false.
          
+
+           
        2. 
+
+            
          If the type specified in the resource's Content-Type
+            metadata is "text/plain", and the result of applying the rules for distinguishing if a resource is
+            text or binary to the resource is that the resource is not
+            text/plain, then set binary to true.
          
+
+           
        3. 
+
+            
          If the type specified in the resource's Content-Type
+            metadata is "application/octet-stream", then set binary to true.
          
+
+           
        4. 
+
+            
          If binary is false, then let the resource
+            type be the type specified in the resource's
+            Content-Type metadata, and jump to the step below labeled handler.
          
+
+           
        5. 
+
+            
          If there is a type attribute present on the
+            object element, and its value is not application/octet-stream,
+            then run the following steps:
          
+
+            
          1. 
+
+              
            If the attribute's value is a type that a plugin supports, or the
+     attribute's value is a type that starts with "image/" that is
+              not also an XML MIME type, then let the resource type be the
+              type specified in that type attribute.
            
+
+             
          2. 
+
+              
            Jump to the step below labeled handler.
            
+
+             
          
+
+           
        
+
+         
        Otherwise, if the resource does not have associated
+         Content-Type metadata
        
+
+          
        1. 
+
+            
          If there is a type attribute present on the
+            object element, then let the tentative type be the type
+            specified in that type attribute.
          
+
+            
          Otherwise, let tentative type be the computed type of the resource.
          
+
+           
        2. 
+
+            
          If tentative type is not
+            application/octet-stream, then let resource type be
+            tentative type and jump to the step below labeled
+            handler.
          
+
+           
        
+
+         
        
+
+       
      7. 
+
+        
+
+        
        If applying the URL parser algorithm to the URL of the
+        specified resource (after any redirects) results in a URL record whose path component matches a pattern that a plugin
+        supports, then let resource type be the type that that plugin can
+        handle.
        
+
+        
        For example, a plugin might say that it can handle resources with path components that end with the four character string
+        ".swf".
        
+
+        
+        
+
+       
      
+
+      
      It is possible for this step to finish, or for one of the substeps above to
+      jump straight to the next step, with resource type still being unknown. In
+      both cases, the next step will trigger fallback.
      
+
+     
    9. Handler: Handle the content as given by the first of the following cases that
+     matches:
      
+
+      
      If the resource type is not a type that the user agent supports, but
+       it is a type that a plugin supports
      
+
+        
      If the object element's nested browsing context is non-null,
+        then it must be discarded and then set
+        to null.
      
+
+        
      If plugins are being sandboxed and the plugin that
+        supports resource type cannot be secured, jump to the step below labeled fallback.
      
+
+        
      Otherwise, the user agent should use the plugin that supports
+        resource type and pass the content of the resource to that
+        plugin. If the plugin reports an error, then jump to the step
+        below labeled fallback.
      
+
+       
      If the resource type is an XML MIME type, or  if the resource type
+       does not start with "image/"
      
+
+        
      If the object element's nested browsing context is null, set
+        the element's nested browsing context to a newly-created browsing context.
      
+
+        
      The object element must be associated with a newly created nested
+        browsing context, if it does not already have one.
      
+
+        
      If the URL of the given resource is not about:blank, the
+        element's nested browsing context must then be navigated to that resource, with
+        replacement enabled, and with the object element's node
+        document's browsing context as the
+        source browsing context. (The data
+        attribute of the object element doesn't get updated if the browsing context
+        gets further navigated to other locations.)
      
+
+        
      If the URL of the given resource is about:blank, then,
+        instead, the user agent must queue a task to fire an event named load
+        at the object element. No load event is fired at the about:blank document
+        itself.
      
+
+        
      The object element represents the nested browsing
+        context.
      
+
+        
      If the name attribute is present, the
+        object element's nested browsing context's browsing context
+        name must be set to the value of this attribute; otherwise, the browsing
+        context name must be set to the empty string.
      
+
+        
      In certain situations, e.g., if the resource was fetched from an
+        application cache but it is an HTML file with a manifest attribute that points to a different application cache manifest, the navigation of the browsing context will be restarted
+        so as to load the resource afresh from the network or a different application
+        cache. Even if the resource is then found to have a different type, it is still used
+        as part of a nested browsing context: only the navigate algorithm
+        is restarted, not this object algorithm.
      
+
+        
+
+       
      If the resource type starts with "image/", and support
+       for images has not been disabled
      
+
+        
      If the object element's nested browsing context is non-null,
+        then it must be discarded and then set
+        to null.
      
+
+        
      Apply the image sniffing rules to
+        determine the type of the image.
      
+
+        
      The object element represents the specified image.
      
+
+        
      If the image cannot be rendered, e.g. because it is malformed or in an unsupported
+        format, jump to the step below labeled fallback.
      
+
+       
      Otherwise
      
+
+        
      The given resource type is not supported. Jump to the step below
+        labeled fallback.
      
+
+        
      If the previous step ended with the resource type being
+        unknown, this is the case that is triggered.
      
+
+       
      
+
+     
    10. The element's contents are not part of what the object element
+     represents.
      
+
+     
    11. 
+
+      
      Abort these steps. Once the resource is completely loaded, queue a task to
+      fire an event named load at the element.
      
+
+     
    
+
+   
  5. If the data attribute is absent but the type attribute is present, and the user agent can find a
+   plugin suitable according to the value of the type attribute, and either plugins aren't being sandboxed or the plugin can be
+   secured, then that plugin should be used. If these conditions cannot be met, or if the
+   plugin reports an error, jump to the step below labeled fallback. Otherwise
+   abort these steps; once the plugin is completely loaded, queue a task to fire an event named load at
+   the element.
  6. Fallback: The object element represents the element's
+   children, ignoring any leading param element children. This is the element's
+   fallback content. If the element has an instantiated plugin, then
+   unload it. If the element's nested browsing context is non-null, then it must be
+   discarded and then set to null.

+
+  
When the algorithm above instantiates a plugin, the user agent
+  should pass to the plugin used the names and values of all the attributes on the
+  element, in the order they were added to the element, with the attributes added by the parser
+  being ordered in source order, followed by a parameter named "PARAM" whose value is null, followed
+  by all the names and values of parameters given by
+  param elements that are children of the object element, in tree
+  order. If the plugin supports a scriptable interface, the
+  HTMLObjectElement object representing the element should expose that interface. The
+  object element represents the plugin. The
+  plugin is not a nested browsing context.

+
+  
Plugins are considered sandboxed for the purpose of an
+  object element if the sandboxed plugins browsing context flag is set on
+  the object element's node document's active sandboxing flag
+  set.

+
+  
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.

+
+  
When an object element's nested browsing context is non-null: if the
+  object element's nested browsing context's active document
+  is not ready for post-load tasks, and when anything is delaying the load event of the object element's browsing
+  context's active document, and when the object element's
+  browsing context is in the delaying load
+  events mode, the object must delay the load event of its
+  document.

+
+  
The task source for the tasks mentioned in this
+  section is the DOM manipulation task source.

+
+  
+
+  
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 form attribute is used to explicitly associate the
+  object element with its form owner.

+
+  
+
+  
Constraint validation: object elements are always barred
+  from constraint validation.

+
+  
+
+  
The object element supports dimension attributes.

+
+  
+
+  
The IDL attributes data, type and name each must reflect the respective
+  content attributes of the same name. The typeMustMatch IDL attribute must
+  reflect the typemustmatch content
+  attribute. The useMap IDL attribute must
+  reflect the usemap content attribute.

+
+  
The contentDocument IDL attribute,
+  on getting, must return the object element's content document.

+
+  
The contentWindow IDL attribute must
+  return the WindowProxy object of the object element's nested
+  browsing context, if its nested browsing context is non-null; otherwise, it
+  must return null.

+
+  
The willValidate, validity, and validationMessage attributes, and the checkValidity(), reportValidity(), and setCustomValidity() methods, are part of the
+  constraint validation API. The form IDL attribute
+  is part of the element's forms API.

+
+  
+
+  

+
+   
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.)

+
+   
<figure>
+ <object type="application/x-java-applet">
+  <param name="code" value="MyJavaClass">
+  <p>You do not have Java available, or it is disabled.</p>
+ </object>
+ <figcaption>My Java Clock</figcaption>
+</figure>

+
+  

+
+  

+
+   
In this example, an HTML page is embedded in another using the object
+   element.

+
+   
<figure>
+ <object data="clock.html"></object>
+ <figcaption>My HTML Clock</figcaption>
+</figure>

+
+  

+
+  

+
+   
The following example shows how a plugin can be used in HTML (in this case the Flash plugin,
+   to show a video file). Fallback is provided for users who do not have Flash enabled, in this case
+   using the video element to show the video for those using user agents that support
+   video, and finally providing a link to the video for those who have neither Flash
+   nor a video-capable browser.

+
+   
<p>Look at my video:
+ <object type="application/x-shockwave-flash">
+  <param name=movie value="https://video.example.com/library/watch.swf">
+  <param name=allowfullscreen value=true>
+  <param name=flashvars value="https://video.example.com/vids/315981">
+  <video controls src="https://video.example.com/vids/315981">
+   <a href="https://video.example.com/vids/315981">View video</a>.
+  </video>
+ </object>
+</p>

+
+  

+
+
+
+  
4.8.8 The param element

+
+  
Categories:
None.
Contexts in which this element can be used:
As a child of an object element, before any flow content.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
name — Name of parameter
value — Value of parameter
DOM interface:

+
[HTMLConstructor]
+interface HTMLParamElement : HTMLElement {
+  [CEReactions] attribute DOMString name;
+  [CEReactions] attribute DOMString value;
+
+  // also has obsolete members
+};

+   

+
+  
The param element defines parameters for plugins invoked by object
+  elements. It does not represent anything on its own.

+
+  
The name attribute gives the name of the
+  parameter.

+
+  
The value attribute gives the value of the
+  parameter.

+
+  
Both attributes must be present. They may have any value.

+
+  
+
+  
If both attributes are present, and if the parent element of the param is an
+  object element, then the element defines a parameter with the given name-value pair.

+
+  
If either the name or value of a parameter defined
+  by a param element that is the child of an object element that
+  represents an instantiated plugin changes, and if that
+  plugin is communicating with the user agent using an API that features the ability to
+  update the plugin when the name or value of a parameter so changes, then the user agent must
+  appropriately exercise that ability to notify the plugin of the change.

+
+  
The IDL attributes name and value must both reflect the respective
+  content attributes of the same name.

+
+  
+
+  

+
+   
The following example shows how the param element can be used to pass a parameter
+   to a plugin, in this case the O3D plugin.

+
+   
<!DOCTYPE HTML>
+<html lang="en">
+  <head>
+   <title>O3D Utah Teapot</title>
+  </head>
+  <body>
+   <p>
+    <object type="application/vnd.o3d.auto">
+     <param name="o3d_features" value="FloatingPointTextures">
+     <img src="o3d-teapot.png"
+          title="3D Utah Teapot illustration rendered using O3D."
+          alt="When O3D renders the Utah Teapot, it appears as a squat
+          teapot with a shiny metallic finish on which the
+          surroundings are reflected, with a faint shadow caused by
+          the lighting.">
+     <p>To see the teapot actually rendered by O3D on your
+     computer, please download and install the <a
+     href="http://code.google.com/apis/o3d/docs/gettingstarted.html#install">O3D plugin</a>.</p>
+    </object>
+    <script src="o3d-teapot.js"></script>
+   </p>
+  </body>
+</html>

+
+  

+
+
+  
4.8.9 The video element
Support: videoChrome for Android 57+Chrome 4+UC Browser for Android 11.4+iOS Safari 3.2+Firefox 20+IE 9+Samsung Internet 4+Opera Mini NoneAndroid Browser 2.3+Edge 12+Safari 4+Opera 10.5+
Source: caniuse.com
Spec bugs: 5755, 25547

+
+  
Categories:
Flow content.
Phrasing content.
Embedded content.
If the element has a controls attribute: Interactive content.
Palpable content.
Contexts in which this element can be used:
Where embedded content is expected.
Content model:
If the element has a src attribute:
+ zero or more track elements, then
+ transparent, but with no media element descendants.
If the element does not have a src attribute: zero or more source elements, then
+ zero or more track elements, then
+ transparent, but with no media element descendants.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
src — Address of the resource
crossorigin — How the element handles crossorigin requests
poster — Poster frame to show prior to video playback
preload — Hints how much buffering the media resource will likely need
autoplay — Hint that the media resource can be started automatically when the page is loaded
playsinline — Encourage the user agent to display video content within the element's playback area
loop — Whether to loop the media resource
muted — Whether to mute the media resource by default
controls — Show user agent controls
width — Horizontal dimension
height — Vertical dimension
DOM interface:

+    
[HTMLConstructor]
+interface HTMLVideoElement : HTMLMediaElement {
+  [CEReactions] attribute unsigned long width;
+  [CEReactions] attribute unsigned long height;
+  readonly attribute unsigned long videoWidth;
+  readonly attribute unsigned long videoHeight;
+  [CEReactions] attribute USVString poster;
+  [CEReactions] attribute boolean playsInline;
+};

+   

+
+  
A video element is used for playing videos or movies, and audio files with
+  captions.

+
+  
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 browsers informing them of how to access the video contents.

+
+  
In particular, this content is not intended to address accessibility concerns. To
+  make video content accessible to the partially sighted, the blind, the hard-of-hearing, the deaf,
+  and those with other physical or cognitive disabilities, a variety of features are available.
+  Captions can be provided, either embedded in the video stream or as external files using the
+  track element. Sign-language tracks can be embedded in the video stream. Audio
+  descriptions can be embedded in the video stream or in text form using a WebVTT file
+  referenced using the track element and synthesized into speech by the user agent.
+  WebVTT can also be used to provide chapter titles. For users who would rather not use a media
+  element at all, transcripts or other textual alternatives can be provided by simply linking to
+  them in the prose near the video element. [WEBVTT]

+
+  
The video element is a media element whose media data is
+  ostensibly video data, possibly with associated audio data.

+
+  
The src, preload,
+  autoplay, loop,
+  muted, and controls attributes are the attributes common to all media elements.

+
+  
The poster attribute gives the
+  URL of an image file that the user agent can show while no video data is available.
+  The attribute, if present, must contain a valid non-empty URL potentially surrounded by
+  spaces.

+
+  
+
+  
If the specified resource is to be used, then, when the element is created or when the poster attribute is set, changed, or removed, the user agent must
+  run the following steps to determine the element's poster frame (regardless of the
+  value of the element's show poster flag):
 
+
+  
  1. If there is an existing instance of this algorithm running for this video
+   element, abort that instance of this algorithm without changing the poster
+   frame.
  2. If the poster attribute's value is the empty string
+   or if the attribute is absent, then there is no poster frame; abort these
+   steps.
  3. Parse the poster attribute's value relative to the element's node
+   document. If this fails, then there is no poster frame; abort these
+   steps.
  4. Let request be a new request whose
+   url is the resulting URL record,
+   client is the element's node document's
+   Window object's environment settings object, type is "image", destination is "image",
+   credentials mode is "include", and whose use-URL-credentials flag is set.
+
+   
  5. Fetch request. This must
+   delay the load event of the element's node document.
  6. If an image is thus obtained, the poster frame is that image. Otherwise,
+   there is no poster frame.

+
+  
+
+  
The image given by the poster attribute,
+  the poster frame, is intended to be a representative frame of the
+  video (typically one of the first non-blank frames) that gives the user an idea of what the video
+  is like.

+
+
+  
The playsinline is a boolean
+  attribute. If present, it serves as a hint to the user agent that the video ought to be
+  displayed "inline" in the document by default, constrained to the element's playback area, instead
+  of being displayed fullscreen or in an independent resizable window.

+
+  
The absence of the playsinline does
+  not imply that the video will display fullscreen by default. Indeed, most user agents have chosen
+  to play all videos inline by default, and in such user agents the playsinline attribute has no effect.

+
+  
+
+  

+
+  
A video element represents what is given for the first matching condition in the
+  list below:

+
+  
When no video data is available (the element's readyState attribute is either HAVE_NOTHING, or HAVE_METADATA but no video data has yet been obtained at
+   all, or the element's readyState attribute is any
+   subsequent value but the media resource does not have a video channel)
The video element represents its poster frame, if any,
+   or else transparent black with no intrinsic dimensions.
When the video element is paused, the current playback position is the first frame of video,
+   and the element's show poster flag is set
The video element represents its poster frame, if any,
+   or else the first frame of the video.
When the video element is paused, and the
+   frame of video corresponding to the current playback
+   position is not available (e.g. because the video is seeking or buffering)
When the video element is neither potentially playing nor paused (e.g. when seeking or stalled)
The video element represents the last frame of the video to have
+   been rendered.
When the video element is paused
The video element represents the frame of video corresponding to
+   the current playback position.
Otherwise (the video element has a video channel and is potentially
+   playing)
The video element represents the frame of video at the continuously
+   increasing "current" position. When the
+   current playback position changes such that the last frame rendered is no longer the
+   frame corresponding to the current playback position in the video, the new frame
+   must be rendered.

+
+  
Frames of video must be obtained from the video track that was selected when the event loop last reached
+  step 1.

+
+  
Which frame in a video stream corresponds to a particular playback position is
+  defined by the video stream's format.

+
+  
The video element also represents any text track cues whose text track cue active flag is set and whose
+  text track is in the showing mode, and any
+  audio from the media resource, at the current playback position.

+
+  
Any audio associated with the media resource must, if played, be played
+  synchronized with the current playback position, at the element's effective
+  media volume. The user agent must play the audio from audio tracks that were enabled when the event loop last reached step
+  1.

+
+  
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.

+
+  
When a video element's media resource has a video channel, the
+  element provides a paint source whose width is the media resource's
+  intrinsic width, whose height is the
+  media resource's intrinsic
+  height, and whose appearance is the frame of video corresponding to the current playback position, if that is available, or else
+  (e.g. when the video is seeking or buffering) its previous appearance, if any, or else (e.g.
+  because the video is still loading the first frame) blackness.

+
+  

+
+  
+
+  
video . videoWidth
video . videoHeight

+
+    
These attributes return the intrinsic dimensions of the video,
+    or zero if the dimensions are not known.

+
+   

+
+  
+
+  
The intrinsic width and intrinsic height of the media resource
+  are the dimensions of the resource in CSS pixels after taking into
+  account the resource's dimensions, aspect ratio, clean aperture, resolution, and so forth, as
+  defined for the format used by the resource. If an anamorphic format does not define how to apply
+  the aspect ratio to the video data's dimensions to obtain the "correct" dimensions, then the user
+  agent must apply the ratio by increasing one dimension and leaving the other unchanged.

+
+  
The videoWidth IDL attribute must return
+  the intrinsic width of the video in CSS pixels. The videoHeight IDL attribute must return the intrinsic height of the video in CSS pixels. If the element's readyState attribute is HAVE_NOTHING, then the attributes must return 0.

+
+  
Whenever the intrinsic width
+  or intrinsic height of the video changes
+  (including, for example, because the selected video
+  track was changed), if the element's readyState
+  attribute is not HAVE_NOTHING, the user agent must
+  queue a task to fire an event named resize at the media element.

+
+  
+
+  
The video element supports dimension attributes.

+
+  
+
+  
In the absence of style rules to the contrary, 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 aspect ratio being
+  preserved. Thus, if the aspect ratio of the playback area does not match the aspect ratio of the
+  video, the video will be shown letterboxed or pillarboxed. Areas of the element's playback area
+  that do not contain the video represent nothing.

+
+  
In user agents that implement CSS, the above requirement can be implemented by
+  using the style rule suggested in the rendering section.

+
+  
The intrinsic width of a video element's playback area is the
+  intrinsic width of the poster frame, if that is available and the
+  element currently represents its poster frame; otherwise, it is the intrinsic width of the video resource, if that is
+  available; otherwise the intrinsic width is missing.

+
+  
The intrinsic height of a video element's playback area is the
+  intrinsic height of the poster frame, if that is available and the
+  element currently represents its poster frame; otherwise it is the intrinsic height of the video resource, if that is
+  available; otherwise the intrinsic height is missing.

+
+  
The default object size is a width of 300 CSS pixels
+  and a height of 150 CSS pixels. [CSSIMAGES]

+
+  
A video element is said to intersect the viewport when it is
+  being rendered and its associated CSS layout box intersects the
+  viewport.

+
+  

+
+  
User agents should provide controls to enable or disable the display of closed captions, audio
+  description tracks, and other additional data 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,
+  such as fullscreen or in an independent resizable window. User agents may even trigger such a
+  viewing mode by default upon playing a video, although they should not do so when the playsinline attribute is specified. As with 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 viewing mode, however, user agents may make full user
+  interfaces visible, 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.

+
+  

+
+  
The poster IDL attribute must
+  reflect the poster content attribute.

+
+  
The playsInline IDL attribute must
+  reflect the playsinline content
+  attribute.

+
+  
+
+  

+
+   
This example shows how to detect when a video has failed to play correctly:

+
+   
<script>
+ function failed(e) {
+   // video playback failed - show a message saying why
+   switch (e.target.error.code) {
+     case e.target.error.MEDIA_ERR_ABORTED:
+       alert('You aborted the video playback.');
+       break;
+     case e.target.error.MEDIA_ERR_NETWORK:
+       alert('A network error caused the video download to fail part-way.');
+       break;
+     case e.target.error.MEDIA_ERR_DECODE:
+       alert('The video playback was aborted due to a corruption problem or because the video used features your browser did not support.');
+       break;
+     case e.target.error.MEDIA_ERR_SRC_NOT_SUPPORTED:
+       alert('The video could not be loaded, either because the server or network failed or because the format is not supported.');
+       break;
+     default:
+       alert('An unknown error occurred.');
+       break;
+   }
+ }
+</script>
+<p><video src="tgif.vid" autoplay controls onerror="failed(event)"></video></p>
+<p><a href="tgif.vid">Download the video file</a>.</p>

+
+  

+
+
+
+
+  
+
+
+
+
+
+  
4.8.10 The audio element
Spec bugs: 7253
Support: audioChrome for Android 57+Chrome 4+UC Browser for Android 11.4+iOS Safari 4.0+Firefox 20+IE 9+Samsung Internet 4+Opera Mini NoneAndroid Browser 2.3+Edge 12+Safari 4+Opera 10.5+
Source: caniuse.com

+
+  
Categories:
Flow content.
Phrasing content.
Embedded content.
If the element has a controls attribute: Interactive content.
If the element has a controls attribute: Palpable content.
Contexts in which this element can be used:
Where embedded content is expected.
Content model:
If the element has a src attribute:
+zero or more track elements, then
+transparent, but with no media element descendants.
If the element does not have a src attribute: zero or more source elements, then
+ zero or more track elements, then
+ transparent, but with no media element descendants.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
src — Address of the resource
crossorigin — How the element handles crossorigin requests
preload — Hints how much buffering the media resource will likely need
autoplay — Hint that the media resource can be started automatically when the page is loaded
loop — Whether to loop the media resource
muted — Whether to mute the media resource by default
controls — Show user agent controls
DOM interface:

+    
[HTMLConstructor, NamedConstructor=Audio(optional DOMString src)]
+interface HTMLAudioElement : HTMLMediaElement {};

+   

+
+  
An audio element represents a sound or audio stream.

+
+  
+
+  
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 browsers informing them of how to access the audio contents.

+
+  
In particular, this content is not intended to address accessibility concerns. To
+  make audio content accessible to the deaf or to those with other physical or cognitive
+  disabilities, a variety of features are available. If captions or a sign language video are
+  available, the video element can be used instead of the audio element to
+  play the audio, allowing users to enable the visual alternatives. Chapter titles can be provided
+  to aid navigation, using the track element and a WebVTT file. And,
+  naturally, transcripts or other textual alternatives can be provided by simply linking to them in
+  the prose near the audio element. [WEBVTT]

+
+  
The audio element is a media element whose media data is
+  ostensibly audio data.

+
+  
The src, preload,
+  autoplay, loop,
+  muted, and controls attributes are the attributes common to all media elements.

+
+  
+
+  
When an audio element is potentially playing, it must have its audio
+  data played synchronized with the current playback position, at the element's
+  effective media volume. The user agent must play the audio from audio tracks that
+  were enabled when the event loop last reached step 1.

+
+  
When an audio element is not potentially playing, audio must not play
+  for the element.

+
+  
+
+  
audio = new Audio( [ url ] )

+
+    
Returns a new audio element, with the src
+    attribute set to the value passed in the argument, if applicable.

+
+   

+
+  
+
+  
A constructor is provided for creating HTMLAudioElement objects (in addition to
+  the factory methods from DOM such as createElement()):
+  Audio(src). When invoked,
+  the constructor must perform the following steps:

+
+  
  1. Let document be the current global object's associated Document.
  2. Let audio be the result of creating an
+   element given document, audio, and the HTML
+   namespace.
  3. Set an attribute value for
+   audio using "preload" and "auto".
  4. If src is given, then set
+   an attribute value for audio using "src"
+   and src. (This will cause the user
+   agent to invoke the object's resource selection
+   algorithm before returning.)
  5. Return audio.

+
+  
+
+
+
+  
+
+
+
+  
4.8.11 The track element

+
+  
Categories:
None.
Contexts in which this element can be used:
As a child of a media element, before any flow content.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
kind — The type of text track
src — Address of the resource
srclang — Language of the text track
label — User-visible label
default — Enable the track if no other text track is more suitable
DOM interface:

+
[HTMLConstructor]
+interface HTMLTrackElement : HTMLElement {
+  [CEReactions] attribute DOMString kind;
+  [CEReactions] attribute USVString src;
+  [CEReactions] attribute DOMString srclang;
+  [CEReactions] attribute DOMString label;
+  [CEReactions] attribute boolean default;
+
+  const unsigned short NONE = 0;
+  const unsigned short LOADING = 1;
+  const unsigned short LOADED = 2;
+  const unsigned short ERROR = 3;
+  readonly attribute unsigned short readyState;
+
+  readonly attribute TextTrack track;
+};

+   

+
+  
The track element allows authors to specify explicit external timed text tracks for media elements. It
+  does not represent anything on its own.

+
+  
The kind attribute is an enumerated
+  attribute. The following table lists the keywords defined for this attribute. The keyword
+  given in the first cell of each row maps to the state given in the second cell.

+
+  
Keyword
+     State
+     Brief description
+   
subtitles
+     Subtitles
+     
+      Transcription or translation of the dialogue, suitable for when the sound is available but not understood (e.g. because the user does not understand the language of the media resource's audio track).
+      Overlaid on the video.
+    
captions
+     Captions
+     
+      Transcription or translation of the dialogue, sound effects, relevant musical cues, and other relevant audio information, suitable for when sound is unavailable or not clearly audible (e.g. because it is muted, drowned-out by ambient noise, or because the user is deaf).
+      Overlaid on the video; labeled as appropriate for the hard-of-hearing.
+    
descriptions
+     Descriptions
+     
+      Textual descriptions of the video component of the media resource, intended for audio synthesis when the visual component is obscured, unavailable, or not usable (e.g. because the user is interacting with the application without a screen while driving, or because the user is blind).
+      Synthesized as audio.
+    
chapters
+     Chapters
+     
+      Chapter titles, intended to be used for navigating the media resource.
+      Displayed as an interactive (potentially nested) list in the user agent's interface.
+    
metadata
+     Metadata
+     
+      Tracks intended for use from script.
+      Not displayed by the user agent.
+  

+
+  
The attribute may be omitted. The missing value default
+  is the subtitles state. The invalid value default is the metadata state.

+
+  
The src attribute gives the URL of
+  the text track data. The value must be a valid non-empty URL potentially surrounded by
+  spaces. This attribute must be present.

+
+  
+
+  
If the element has a src attribute whose value is not the
+  empty string and whose value, when the attribute was set, could be successfully parsed relative to the element's node document, then the
+  element's track URL is the resulting URL string. Otherwise, the element's
+  track URL is the empty string.

+
+  
+
+  
If the element's track URL identifies a WebVTT resource, and the element's kind attribute is not in the metadata state, then the WebVTT file must be a
+  WebVTT file using cue text. [WEBVTT]

+
+  
Furthermore, if the element's track URL identifies a WebVTT resource, and the
+  element's kind attribute is in the chapters state, then the WebVTT file must be both a
+  WebVTT file using chapter title text and a WebVTT file using only nested
+  cues. [WEBVTT]

+
+  
The srclang attribute gives the language of
+  the text track data. The value must be a valid BCP 47 language tag. This attribute must be present
+  if the element's kind attribute is in the subtitles state. [BCP47]

+
+  
+
+  
If the element has a srclang attribute whose value is
+  not the empty string, then the element's track language is the value of the attribute.
+  Otherwise, the element has no track language.

+
+  
+
+  
The label attribute gives a user-readable
+  title for the track. This title is used by user agents when listing subtitle, caption, and audio description tracks in their user interface.

+
+  
The value of the label attribute, if the attribute is
+  present, must not be the empty string. Furthermore, there must not be two track
+  element children of the same media element whose kind attributes are in the same state, whose srclang attributes are both missing or have values that
+  represent the same language, and whose label attributes are
+  again both missing or both have the same value.

+
+  
+
+  
If the element has a label attribute whose value is not
+  the empty string, then the element's track label is the value of the attribute.
+  Otherwise, the element's track label is an empty string.

+
+  
+
+  
The default attribute is a boolean
+  attribute, which, if specified, indicates that the track is to be enabled if the user's
+  preferences do not indicate that another track would be more appropriate.

+
+  
Each media element must have no more than one track element child
+  whose kind attribute is in the subtitles or captions state and whose default attribute is specified.

+
+  
Each media element must have no more than one track element child
+  whose kind attribute is in the description state and whose default attribute is specified.

+
+  
Each media element must have no more than one track element child
+  whose kind attribute is in the chapters state and whose default attribute is specified.

+
+  
There is no limit on the number of track elements whose kind attribute is in the metadata state and whose default attribute is specified.

+
+  
track . readyState

+    
Returns the text track readiness state,
+    represented by a number from the following list:

+    
track . NONE (0)

+      
The text track not loaded state.

+     
track . LOADING (1)

+      
The text track loading state.

+     
track . LOADED (2)

+      
The text track loaded state.

+     
track . ERROR (3)

+      
The text track failed to load state.

+     

+   
track . track

+
+    
Returns the TextTrack object corresponding to the text track of the track element.

+
+   

+
+  
+
+  
The readyState attribute must return the
+  numeric value corresponding to the text track readiness state of the
+  track element's text track, as defined by the following list:

+
+  
NONE (numeric value 0)
The text track not loaded state.
LOADING (numeric value 1)
The text track loading state.
LOADED (numeric value 2)
The text track loaded state.
ERROR (numeric value 3)
The text track failed to load state.

+
+  
The track IDL attribute must, on getting,
+  return the track element's text track's corresponding
+  TextTrack object.

+
+  
The src, srclang, label, and default IDL attributes must reflect the
+  respective content attributes of the same name. The kind IDL attribute must reflect the content
+  attribute of the same name, limited to only known values.

+
+  
+
+  

+
+   
This video has subtitles in several languages:

+
+   
<video src="brave.webm">
+ <track kind=subtitles src=brave.en.vtt srclang=en label="English">
+ <track kind=captions src=brave.en.hoh.vtt srclang=en label="English for the Hard of Hearing">
+ <track kind=subtitles src=brave.fr.vtt srclang=fr lang=fr label="Français">
+ <track kind=subtitles src=brave.de.vtt srclang=de lang=de label="Deutsch">
+</video>

+
+   
(The lang attributes on the last two describe the language of
+   the label attribute, not the language of the subtitles
+   themselves. The language of the subtitles is given by the srclang attribute.)

+
+  

+
+  
4.8.12 Media elements
Spec bugs: 28625

+
+  
HTMLMediaElement objects (audio and video, in this
+  specification) are simply known as media elements.

+
+  
enum CanPlayTypeResult { "" /* empty string */, "maybe", "probably" };
+typedef (MediaStream or MediaSource or Blob) MediaProvider;
+interface HTMLMediaElement : HTMLElement {
+
+  // error state
+  readonly attribute MediaError? error;
+
+  // network state
+  [CEReactions] attribute USVString src;
+  attribute MediaProvider? srcObject;
+  readonly attribute USVString currentSrc;
+  [CEReactions] attribute DOMString? crossOrigin;
+  const unsigned short NETWORK_EMPTY = 0;
+  const unsigned short NETWORK_IDLE = 1;
+  const unsigned short NETWORK_LOADING = 2;
+  const unsigned short NETWORK_NO_SOURCE = 3;
+  readonly attribute unsigned short networkState;
+  [CEReactions] attribute DOMString preload;
+  readonly attribute TimeRanges buffered;
+  void load();
+  CanPlayTypeResult canPlayType(DOMString type);
+
+  // ready state
+  const unsigned short HAVE_NOTHING = 0;
+  const unsigned short HAVE_METADATA = 1;
+  const unsigned short HAVE_CURRENT_DATA = 2;
+  const unsigned short HAVE_FUTURE_DATA = 3;
+  const unsigned short HAVE_ENOUGH_DATA = 4;
+  readonly attribute unsigned short readyState;
+  readonly attribute boolean seeking;
+
+  // playback state
+  attribute double currentTime;
+  void fastSeek(double time);
+  readonly attribute unrestricted double duration;
+  object getStartDate();
+  readonly attribute boolean paused;
+  attribute double defaultPlaybackRate;
+  attribute double playbackRate;
+  readonly attribute TimeRanges played;
+  readonly attribute TimeRanges seekable;
+  readonly attribute boolean ended;
+  [CEReactions] attribute boolean autoplay;
+  [CEReactions] attribute boolean loop;
+  Promise<void> play();
+  void pause();
+
+  // controls
+  [CEReactions] attribute boolean controls;
+  attribute double volume;
+  attribute boolean muted;
+  [CEReactions] attribute boolean defaultMuted;
+
+  // tracks
+  [SameObject] readonly attribute AudioTrackList audioTracks;
+  [SameObject] readonly attribute VideoTrackList videoTracks;
+  [SameObject] readonly attribute TextTrackList textTracks;
+  TextTrack addTextTrack(TextTrackKind kind, optional DOMString label = "", optional DOMString language = "");
+};

+
+  
The media element attributes, src, crossorigin, preload, autoplay,
+  loop, muted, and
+  controls, apply to all media elements. They are defined in this section.

+
+  
+
+  
+
+  
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.
+
+  

+
+  
A media resource can have multiple audio and video tracks. For the purposes of a
+  media element, the video data of the media resource is only that of the
+  currently selected track (if any) as given by the element's videoTracks attribute when the event loop last
+  reached step 1, and the audio data of the media resource is the result of mixing all
+  the currently enabled tracks (if any) given by the element's audioTracks attribute when the event loop last
+  reached step 1.

+
+  
Both audio and video elements can be used for both audio
+  and video. The main difference between the two is simply that the audio element has
+  no playback area for visual content (such as video or captions), whereas the video
+  element does.

+
+  
+
+  
Except where otherwise explicitly specified, the task source for all the tasks
+  queued in this section and its subsections is the media
+  element event task source of the media element in question.

+
+  
+
+
+
+  
4.8.12.1 Error codes

+
+  
media . error

+
+    
Returns a MediaError object representing the current error state of the
+    element.

+
+    
Returns null if there is no error.

+
+   

+
+  
+
+  
All media elements have an associated error status, which
+  records the last error the element encountered since its resource selection algorithm 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.

+
+  
+
+  
interface MediaError {
+  const unsigned short MEDIA_ERR_ABORTED = 1;
+  const unsigned short MEDIA_ERR_NETWORK = 2;
+  const unsigned short MEDIA_ERR_DECODE = 3;
+  const unsigned short MEDIA_ERR_SRC_NOT_SUPPORTED = 4;
+
+  readonly attribute unsigned short code;
+  readonly attribute DOMString message;
+};

+
+  
media . error . code

+
+    
Returns the current error's error code, from the list below.

+
+   
media . error . message

+
+    
Returns a specific informative diagnostic message about the error condition encountered. The
+    message and message format are not generally uniform across different user agents. If no such
+    message is available, then the empty string is returned.

+
+   

+
+  
+
+  
Every MediaError object has a message, which is a string, and a code, which is one of the following:

+
+  
+
+  
MEDIA_ERR_ABORTED (numeric value 1)
The fetching process for 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 fetching the media
+   resource, after the resource was established to be usable.
MEDIA_ERR_DECODE (numeric value 3)
An error of some description occurred while decoding the media resource, after
+   the resource was established to be usable.
MEDIA_ERR_SRC_NOT_SUPPORTED (numeric value 4)
The media resource indicated by the src
+   attribute or assigned media provider object was not suitable.

+
+  
+
+  
To create a MediaError,
+  given an error code which is one of the above values, return a new MediaError object
+  whose code is the given error code and whose message is a string containing any details the user
+  agent is able to supply about the cause of the error condition, or the empty string if the user
+  agent is unable to supply such details. This message string must not contain only the information
+  already available via the supplied error code; for example, it must not simply be a translation of
+  the code into a string format. If no additional information is available beyond that provided by
+  the error code, the message must be set to the
+  empty string.

+
+  
The code attribute of a
+  MediaError object must return this MediaError object's code.

+
+  
The message attribute of a
+  MediaError object must return this MediaError object's message.

+
+  
+
+
+
+
+  
4.8.12.2 Location of the media resource

+
+  
The src content attribute on media elements gives the URL of the media resource (video, audio) to
+  show. The attribute, if present, must contain a valid non-empty URL potentially surrounded
+  by spaces.

+
+  
If the itemprop attribute is specified on the media
+  element, then the src attribute must also be
+  specified.

+
+  
The crossorigin content attribute on
+  media elements is a CORS settings attribute.

+
+  
+
+  
If a media element is created with a
+  src attribute, the user agent must immediately invoke the
+  media element's resource selection
+  algorithm.

+
+  
If a src attribute of a media element is set
+  or changed, the user agent must invoke the media element's media element load
+  algorithm. (Removing the src attribute does
+  not do this, even if there are source elements present.)

+
+  
The src IDL attribute on media elements must reflect the content attribute of the same
+  name.

+
+  
The crossOrigin IDL attribute must
+  reflect the crossorigin content attribute.

+
+  
+
+  
A media provider object is an object that can represent a media
+  resource, separate from a URL. MediaStream objects,
+  MediaSource objects, and Blob objects are all media provider objects.

+
+  
+
+  
Each media element can have an assigned media provider object, which is a
+  media provider object. When a media element is created, it has no
+  assigned media provider object.

+
+  
+
+  
media . srcObject [ = source ]

+
+    
Allows the media element to be assigned a media provider object.

+
+   
media . currentSrc

+
+    
Returns the URL of the current media resource, if any.

+
+    
Returns the empty string when there is no media resource, or it doesn't have a
+    URL.

+
+   

+
+  
+
+  
The currentSrc IDL attribute must initially be set to
+  the empty string. Its value is changed by the resource
+  selection algorithm defined below.

+
+  
The srcObject IDL attribute, on getting,
+  must return the element's assigned media provider object, if any, or null otherwise.
+  On setting, it must set the element's assigned media provider object to the new
+  value, and then invoke the element's media element load algorithm.

+
+  
+
+  
There are three ways to specify a media resource: the srcObject IDL attribute, the src content attribute, and source elements. The IDL
+  attribute takes priority, followed by the content attribute, followed by the elements.

+
+
+
+  
4.8.12.3 MIME types

+
+  
A media resource can be described in terms of its type, specifically a
+  MIME type, in some cases with a codecs parameter. (Whether the
+  codecs parameter is allowed or not depends on the MIME type.) [RFC6381]

+
+  
Types are usually somewhat incomplete descriptions; for example "video/mpeg" doesn't say anything except what the container type is, and even a
+  type like "video/mp4; codecs="avc1.42E01E, mp4a.40.2"" doesn't
+  include information like the actual bitrate (only the maximum bitrate). Thus, given a type, a user
+  agent can often only know whether it might be able to play media of that type (with
+  varying levels of confidence), or whether it definitely cannot play media of that
+  type.

+
+  
A type that the user agent knows it cannot render is one that describes a resource
+  that the user agent definitely does not support, for example because it doesn't recognize the
+  container type, or it doesn't support the listed codecs.

+
+  
The MIME type "application/octet-stream" with no parameters is never
+  a type that the user agent knows it cannot render. User agents must treat that type
+  as equivalent to the lack of any explicit Content-Type metadata
+  when it is used to label a potential media resource.

+
+  
Only the MIME type "application/octet-stream" with no
+  parameters is special-cased here; if any parameter appears with it, it will be treated just like
+  any other MIME type. This is a deviation from the rule  that unknown MIME type parameters should be
+  ignored.
 
+
+  
media . canPlayType(type)

+
+    
Returns the empty string (a negative response), "maybe", or "probably" based on how confident
+    the user agent is that it can play media resources of the given type.

+
+   

+
+  
+
+  
The canPlayType(type) method must return the
+  empty string if type is a type that the user agent knows it cannot
+  render or is the type "application/octet-stream"; it must return "probably" if the user agent is confident
+  that the type represents a media resource that it can render if used in with this
+  audio or video element; and it must return "maybe" otherwise. Implementors are encouraged
+  to return "maybe" unless the type can be
+  confidently established as being supported or not. Generally, a user agent should never return
+  "probably" for a type that allows the codecs parameter if that parameter is not present.

+
+  
+
+  

+
+   
This script tests to see if the user agent supports a (fictional) new format to dynamically
+   decide whether to use a video element or a plugin:

+
+   
<section id="video">
+ <p><a href="playing-cats.nfv">Download video</a></p>
+</section>
+<script>
+ var videoSection = document.getElementById('video');
+ var videoElement = document.createElement('video');
+ var support = videoElement.canPlayType('video/x-new-fictional-format;codecs="kittens,bunnies"');
+ if (support != "probably" && "New Fictional Video Plugin" in navigator.plugins) {
+   // not confident of browser support
+   // but we have a plugin
+   // so use plugin instead
+   videoElement = document.createElement("embed");
+ } else if (support == "") {
+   // no support from browser and no plugin
+   // do nothing
+   videoElement = null;
+ }
+ if (videoElement) {
+   while (videoSection.hasChildNodes())
+     videoSection.removeChild(videoSection.firstChild);
+   videoElement.setAttribute("src", "playing-cats.nfv");
+   videoSection.appendChild(videoElement);
+ }
+</script>

+
+  

+
+  
The type attribute of the
+  source element allows the user agent to avoid downloading resources that use formats
+  it cannot render.

+
+
+  
4.8.12.4 Network states

+
+  
media . networkState

+
+    
Returns the current state of network activity for the element, from the codes in the list
+    below.

+
+   

+
+  
+
+  
As media elements interact with the network, their current
+  network activity is represented by the networkState attribute. On getting, it must
+  return the current network state of the element, which must be one of the following values:

+
+  
+
+  
NETWORK_EMPTY (numeric value 0)
The element has not yet been initialized. All attributes are in their initial states.
NETWORK_IDLE (numeric value 1)
The element's resource
+   selection algorithm is active and has selected a resource, but it is not actually using the network at this time.
NETWORK_LOADING (numeric value 2)
The user agent is actively trying to download data.
NETWORK_NO_SOURCE (numeric value 3)
The element's resource
+   selection algorithm is active, but it has not yet found a resource to use.

+
+  
+
+  
The resource selection algorithm defined
+  below describes exactly when the networkState
+  attribute changes value and what events fire to indicate changes in this state.

+
+  
+
+
+
+
+  
4.8.12.5 Loading the media resource
Spec bugs: 27989, 22471

+
+  
media . load()

+
+    
Causes the element to reset and start selecting and loading a new media resource
+    from scratch.

+
+   

+
+  
+
+  
All media elements have a can autoplay flag,
+  which must begin in the true state, and a delaying-the-load-event flag, which must
+  begin in the false state. While the delaying-the-load-event flag is true, the element
+  must delay the load event of its document.

+
+  
When the load() method on a media
+  element is invoked, the user agent must run the media element load
+  algorithm.

+
+  
The media element load algorithm consists of the following steps.

+
+  
  1. Abort any already-running instance of the resource selection algorithm for this
+   element.
  2. Let pending tasks be a list of all tasks
+   from the media element's media element event task source in one of the
+   task queues.
  3. For each task in pending tasks that would resolve pending play
+   promises or reject pending play promises, immediately resolve or reject those
+   promises in the order the corresponding tasks were queued.
  4. 
+
+    
    Remove each task in pending tasks from its
+    task queue
    
+
+    
    Basically, pending events and callbacks are discarded and promises in-flight to
+    be resolved/rejected are resolved/rejected immediately when the media element starts loading a
+    new resource.
    
+
+   
  5. If the media element's networkState is set to NETWORK_LOADING or NETWORK_IDLE, queue a task to fire an event named abort at the media element.
  6. 
+
+    
    If the media element's networkState
+    is not set to NETWORK_EMPTY, then:
    
+
+    
    1. Queue a task to fire an event

\ No newline at end of file

From 959d6082407406b2a9d358178fcf920c965cabf6 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Tue, 30 May 2017 13:21:46 -0400
Subject: [PATCH 04/23] Removing additional files

---
 lib/org/chromium/webidl/HTMLFileContent.js |  3 +-
 test/node/parsing/HTMLFileContent-test.js~ | 63 ----------------------
 2 files changed, 1 insertion(+), 65 deletions(-)
 delete mode 100644 test/node/parsing/HTMLFileContent-test.js~

diff --git a/lib/org/chromium/webidl/HTMLFileContent.js b/lib/org/chromium/webidl/HTMLFileContent.js
index 1ed9f3c..1ddb8cf 100644
--- a/lib/org/chromium/webidl/HTMLFileContent.js
+++ b/lib/org/chromium/webidl/HTMLFileContent.js
@@ -22,7 +22,6 @@ foam.CLASS({
     {
       name: 'pre',
       // description: 'all pre tags found in the parsed HTML file',
-      factory: function() { return new Array; }
     }
   ],
 
@@ -86,7 +85,7 @@ foam.CLASS({
           return acc.concat(item);
         } else if (foam.core.FObject.isInstance(item)) {
           return acc.concat(foam.Array.isInstance(item.content) ?
-              item.content[1] || item.content[0] || '' : '');
+              item.content[1] || item.content[0] : '');
         }
       }, "");
     }
diff --git a/test/node/parsing/HTMLFileContent-test.js~ b/test/node/parsing/HTMLFileContent-test.js~
deleted file mode 100644
index a28195f..0000000
--- a/test/node/parsing/HTMLFileContent-test.js~
+++ /dev/null
@@ -1,63 +0,0 @@
-// Copyright 2017 The Chromium Authors. ALl rights reserved.
-// Use of this source code is governed by a BSD-style license that can be
-// found in the LICENSE file.
-'use strict';
-
-describe('HTMLFileContent', function() {
-  var HTMLParser;
-  //var Outputer;
-  var Parser;
-
-  function cmpTest(testDirectory, idlFragments) {
-		var fs = require('fs');
-		var spec = fs.readFileSync(`${testDirectory}/spec.html`).toString();
-
-    fs.readdir(testDirectory, function(err, files) {
-      // Go through each of the expected results in the folder
-      files.forEach(function(filename) {
-        var testNum = Number(filename);
-
-        if (!isNaN(testNum) && testNum < idlFragments.length) {
-          var expectedIDL = fs.readFileSync(`${testDirectory}/${filename}`).toString();
-          expect(idlFragments[testNum].idl).toBe(expectedIDL);
-        } else if (filename !== 'spec.html') {
-          console.warn(`${filename} was not used in WebUSB spec test`);
-        }
-      });
-    });
-	}
-
-  beforeEach(function() {
-    HTMLParser = foam.lookup('org.chromium.webidl.HTMLParser');
-  });
-
-  it('should parse a pre tag with no content', function() {
-    var content = '
';
-  });
-
-  it('should parse a HTML file with one Web IDL Block', function() {
-    var content = `
-        
-        [Constructor]
-        interface Dahut : Mammal {
-          const unsigned short LEVROGYROUS = 0;
-          const unsigned short DEXTROGYROUS = 1;
-          readonly attribute DOMString chirality;
-          attribute unsigned long age;
-          Dahut turnAround(float angle, boolean fall);
-          unsigned long trip();
-          void yell([AllowAny] unsigned long volume,
-              [TreatNullAs=EmptyString] DOMString sentence);
-        };
-    
`;
-    var ret = HTMLParser.create().parse(content);
-  });
-
-  it('should parse the WebUSB spec HTML file ', function() {
-    var testDirectory = `${__dirname}/webSpec/WebUSB`;
-    var idlFragments = HTMLParser.create().parse(spec);
-
-    expect(idlFragments.length).toBe(15);
-		cmpTest(testDirectory, idlFragments);
-  });
-});

From b35f7500718d5b11f5ecbbf0dbf11ec144e07866 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Tue, 30 May 2017 16:39:42 -0400
Subject: [PATCH 05/23] Adding some additional tests and filtering out examples
 / notes

---
 lib/org/chromium/webidl/HTMLFileContent.js |  44 +-
 test/node/parsing/Console/2                |  25 +
 test/node/parsing/Console/3                |  25 +
 test/node/parsing/Console/spec.html        | 580 +++++++++++++++++++++
 test/node/parsing/HTMLFileContent-test.js  |  24 +-
 test/node/parsing/UIEvent/{27 => 26}       |   0
 test/node/parsing/WebUSB/{14 => 11}        |   0
 test/node/parsing/WebUSB/3                 |  17 -
 test/node/parsing/WebUSB/4                 |  61 +++
 test/node/parsing/whatwg/29                |   7 -
 10 files changed, 732 insertions(+), 51 deletions(-)
 create mode 100644 test/node/parsing/Console/2
 create mode 100644 test/node/parsing/Console/3
 create mode 100644 test/node/parsing/Console/spec.html
 rename test/node/parsing/UIEvent/{27 => 26} (100%)
 rename test/node/parsing/WebUSB/{14 => 11} (100%)
 delete mode 100644 test/node/parsing/WebUSB/3
 create mode 100644 test/node/parsing/WebUSB/4
 delete mode 100644 test/node/parsing/whatwg/29

diff --git a/lib/org/chromium/webidl/HTMLFileContent.js b/lib/org/chromium/webidl/HTMLFileContent.js
index 1ddb8cf..3dfce67 100644
--- a/lib/org/chromium/webidl/HTMLFileContent.js
+++ b/lib/org/chromium/webidl/HTMLFileContent.js
@@ -39,26 +39,39 @@ foam.CLASS({
       // Using a stack to obtain ancestorOf 
 tags
       var tags = [];
       var pre = [];
+
+      // We ignore tags inside <* class="example"> or <* class="note">
+      // skipStack keeps track of stack levels where tags are of the above
+      var skipStack = [];
+
       results.forEach(function(node, i) {
         var item = results[i];
 
         if (foam.core.FObject.isInstance(item)) {
           var top = tags[tags.length - 1];
-          if (top === undefined || item.type.name === OPEN) {
+          var classes = '';
+          item.attributes.forEach(function(attr) {
+            if (attr.name === 'class') {
+              classes = attr.value.split(' ');
+            }
+          });
+
+          if (item.type.name === OPEN) {
+            if (classes.includes('example') || classes.includes('note')) {
+              skipStack.push(tags.length);
+            }
             tags.push(item);
-          } else if (item.nodeName === top.nodeName && item.type.name === CLOSE) {
-            // Do we need to do anything with this?
+          } else if (top !== undefined && item.nodeName === top.nodeName
+              && item.type.name === CLOSE) {
             tags.pop();
-          } else if (item.type.name === OPEN_CLOSE && item.nodeName === 'pre') {
-            // Determine if node is of class IDL
-            var isIDL = false;
-            item.attributes.forEach(function(attr) {
-              if (attr.name === 'class' && attr.value.split(' ').includes('idl')) {
-                isIDL = true;
-              }
-            });
+            if (skipStack[skipStack.length - 1] == tags.length) {
+              skipStack.pop();
+            }
+          } else if (item.type.name === OPEN_CLOSE && item.nodeName === 'pre' &&
+              skipStack.length === 0) {
+            var isIDL = classes.includes('idl');
 
-            // Add to the list of pre
+            // Add to the list of pre.
             pre.push({
               ancestor: top,
               content: self.flatten(item.content),
@@ -66,15 +79,12 @@ foam.CLASS({
             });
           } else {
             // Currently not doing anything for:
-            //  - Self closing tags (item.type.name === OPEN_CLOSE)
+            //  - Nested pre tags in example/note
+            //  - OPEN_CLOSE tags that are not pre
             //  - Malformed / Mismatched HTML Files
           }
         }
       });
-
-      if (tags.length !== 0) {
-        // We have mismatched tags! :(
-      }
       return pre;
     },
 
diff --git a/test/node/parsing/Console/2 b/test/node/parsing/Console/2
new file mode 100644
index 0000000..7351bfc
--- /dev/null
+++ b/test/node/parsing/Console/2
@@ -0,0 +1,25 @@
+[Exposed=(Window,Worker,Worklet)]
+namespace console { // but see namespace object requirements below
+  // Logging
+  void assert(optional boolean condition = false, any... data);
+  void clear();
+  void count(optional DOMString label = "default");
+  void debug(any... data);
+  void error(any... data);
+  void info(any... data);
+  void log(any... data);
+  void table(any tabularData, optional sequence properties);
+  void trace(any... data);
+  void warn(any... data);
+  void dir(any item, optional object? options);
+  void dirxml(any... data);
+
+  // Grouping
+  void group(any... data);
+  void groupCollapsed(any... data);
+  void groupEnd();
+
+  // Timing
+  void time(optional DOMString label = "default");
+  void timeEnd(optional DOMString label = "default");
+};
diff --git a/test/node/parsing/Console/3 b/test/node/parsing/Console/3
new file mode 100644
index 0000000..7351bfc
--- /dev/null
+++ b/test/node/parsing/Console/3
@@ -0,0 +1,25 @@
+[Exposed=(Window,Worker,Worklet)]
+namespace console { // but see namespace object requirements below
+  // Logging
+  void assert(optional boolean condition = false, any... data);
+  void clear();
+  void count(optional DOMString label = "default");
+  void debug(any... data);
+  void error(any... data);
+  void info(any... data);
+  void log(any... data);
+  void table(any tabularData, optional sequence properties);
+  void trace(any... data);
+  void warn(any... data);
+  void dir(any item, optional object? options);
+  void dirxml(any... data);
+
+  // Grouping
+  void group(any... data);
+  void groupCollapsed(any... data);
+  void groupEnd();
+
+  // Timing
+  void time(optional DOMString label = "default");
+  void timeEnd(optional DOMString label = "default");
+};
diff --git a/test/node/parsing/Console/spec.html b/test/node/parsing/Console/spec.html
new file mode 100644
index 0000000..6ed3a47
--- /dev/null
+++ b/test/node/parsing/Console/spec.html
@@ -0,0 +1,580 @@
+
+
+
+  
+  
+  
+  Console Standard
+  
+  
+  
+  
+
+
+ File an issue about the selected text
+  

+   
 

+   

+    
Console

+    
Living Standard — Last Updated 

+   

+   
+   

+  

+  

+   
Abstract

+   
This specification defines APIs for console debugging facilities.

+  

+  
+  

+
+
+
+   
Status

+   
This specification is an early work in progress that welcomes feedback to refine toward more
+precise and compatible definitions. It is also the editors' first specification, so please be kind
+and constructive.

+   
Please join us in the issue tracker for more
+discussion.

+   
1. Supporting abstract operations

+   
1.1. Logger(logLevel, args)

+   
The logger operation accepts a log level and a List of other arguments. Its main output is the
+implementation-defined side effect of printing the result to the console. This specification
+describes how it processes format specifiers while doing so.

+    
  1. If args is empty, abort these steps.
  2. Let first be the first element of args.
  3. Let rest be all elements following first in args.
  4. If rest is empty, perform Printer(logLevel, «first»). Abort these steps.
  5. If first does not contain any format specifiers, perform Printer(logLevel, args).
  6. Otherwise, perform Printer(logLevel, Formatter(args)).
  7. Return undefined.
 
+   

+     It’s important that the printing occurs before returning from the algorithm. Many developer
+  consoles print the result of the last operation entered into them. In such consoles, when a
+  developer enters console.log("hello!"), this should first print "hello!", then the
+  undefined return value from the console.log call. 
+    
Indicating that printing is done before return

+   

+   
1.2. Formatter(args)

+   
The formatter operation tries to format the first argument provided, using the other arguments. It
+will try to format the input until no formatting specifiers are left in the first argument, or no
+more arguments are left. It returns a List of objects suitable for printing.

+    
  1. Let target be the first element of args.
  2. Let current be the second element of args.
  3. Find the first possible format specifier specifier, from the left to the right in target.
    1. If specifier is %s, let converted be the result of ToString(current).
    2. If specifier is %d or %i, let converted be the result of %parseInt%(current, 10).
    3. If specifier is %f, let converted be the result of  %parseFloat%(current, 10).
    4. If specifier is %o, optionally let converted be current with
+    optimally useful formatting applied.
    5. If specifier is %O, optionally let converted be current with
+    generic JavaScript object formatting applied.
    6. TODO: process %c
    7. If any of the previous steps set converted, replace specifier in target with
+    converted.
    8. Let result be a List containing target together with the elements of args starting
+    from the third onward.
  4. If target does not have any format specifiers left, return result.
  5. If result contains just one element, return result.
  6. Return Formatter(result).
 
+   
1.2.1. Summary of formatting specifiers

+   
The following is an informative summary of the format specifiers processed by the above algorithm.

+   
+    
+     
+      
+     
+      
+      
+      
+      
+      
+      
Specifier
+      Purpose
+      Type Conversion
+    
%s
+      Element which substitutes is converted to a string
+      ToString(element)
+     
%d or %i
+      Element which substitutes is converted to an integer
+      %parseInt%(element, 10)
+     
%f
+      Element which substitutes is converted to a float
+      %parseFloat%(element, 10)
+     
%o
+      Element is displayed with optimally useful formatting
+      n/a
+     
%O
+      Element is displayed with generic JavaScript object formatting
+      n/a
+     
%c
+      Applies provided CSS
+      n/a
+   

+   
1.3. Printer(logLevel, args [, options])

+   
The printer operation is implementation-defined. It accepts a log level indicating severity, a List
+of arguments to print, and an optional object of implementation-specific formatting options.
+Elements appearing in args will be one of the following:

+   
+   
If the options object is passed, and is not undefined or null, implementations may use options to apply implementation-specific formatting to the elements in args.

+   
How the implementation prints args is up to the implementation, but implementations
+should separate the objects by a space or something similar, as that has become a developer
+expectation.

+   
By the time the printer operation is called, all format specifiers will have been taken into
+account, and any arguments that are meant to be consumed by format specifiers will not be present
+in args. The implementation’s job is simply to print the List. The output produced by
+calls to Printer should appear only within the last group on the appropriate group stack if the group stack is not empty, or elsewhere in the console otherwise.

+   
If the console is not open when the printer operation is called,
+implementations should buffer messages to show them in the future up to an
+implementation-chosen limit (typically on the order of at least 100).

+   
1.3.1. Indicating logLevel severity

+   
Each console method uses a unique value for the logLevel parameter when calling
+Printer, allowing implementations to customize each printed message depending on the method from
+which it originated. However, it is common practice to group together certain methods and treat
+their output similarly, in four broad categories. This table summarizes these common groupings:

+   
+    
+     
+      
+     
+      
+      
+      
+      
Grouping
+      console methods
+      Description
+    
log
+        log(), trace(), dir(), dirxml(), group(), groupCollapsed(), debug()  
+       A generic log 
+     
info
+      count(), info(), timeEnd()
+       An informative log 
+     
warn
+      warn()
+       A log warning the user of something indicated by the message 
+     
error
+      error(), assert()
+       A log indicating an error to the user 
+   

+   
These groupings are meant to document common practices, and do not constrain implementations from
+providing special behavior for each method, as in the following examples:

+   

+     Here you can see one implementation chose to make output produced by calls to timeEnd() blue, while leaving info() a more neutral color. 
+    
A demonstration of timeEnd and info formatting differences

+   

+   

+     Calls to count() might not always print new output, but instead could update previously-output counts. 
+    
A demonstration of count behavior

+   

+   
1.3.2. Printer user experience innovation

+   
Since Printer is implementation-defined, it is common to see UX innovations in its implementations.
+The following is a non-exhaustive list of potential UX enhancements:

+   
    
+    
  • 
+     
    De-duplication of identical output to prevent spam.
    
+     
    
+       In this example, the implementation not only batches multiple identical messages, but also
+      provides the number of messages that have been batched together. 
+      
    A demonstration of console message de-duplication
    
+     
    
+    
  • 
+     
    Extra UI off to the side allowing the user to filter messages by log level severity.
    
+     
      
    
+    
  •  Extra UI off to the side indicating the current state of the timer table, group stack, or other internally maintained data. 
+    
  • Flashing portions of the console to alert the user of something important.
+   

+   
1.3.3. Common object formats

+   
Typically objects will be printed in a format that is suitable for their context. This section
+describes common ways in which objects are formatted to be most useful in their context. It should
+be noted that the formatting described in this section is applied to implementation-specific object
+representations that will eventually be passed into Printer, where the actual side effect of
+formatting will be seen.

+   
An object with generic JavaScript object formatting is a potentially expandable
+representation of a generic JavaScript object. An object with optimally useful formatting is an implementation-specific, potentially-interactive
+representation of an object judged to be maximally useful and informative.

+   
1.3.4. Example printer in Node.js

+   

+     The simplest way to implement the printer operation on the Node.js platform is to join the
+  previously formatted arguments separated by a space and write the output to stdout or stderr. 
+    
Example implementation in Node.js using [ECMASCRIPT]:

+
const util = require('util');
+
+function print(logLevel, ...args) {
+  const message = util.format(...args);
+
+  if (logLevel === 'error') {
+    process.stderr.write(message + '\n');
+  } else if (logLevel === 'log' || logLevel === 'info' || logLevel === 'warn') {
+    process.stdout.write(message + '\n');
+  }
+}
+

+    
Here a lot of the work is done by the util.format function. It stringifies nested
+  objects, and converts non-string arguments into a readable string version, e.g. undefined becomes
+  the string "undefined" and false becomes "false":

+
print('log', 'duck', [{foo: 'bar'}]);     // prints: `duck [ { foo: 'bar' } ]\n` on stdout
+print('log', 'duck', false);              // prints: `duck false\n` on stdout
+print('log', 'duck', undefined);          // prints: `duck undefined\n` on stdout
+

+   

+   
2. Namespace console

+
[Exposed=(Window,Worker,Worklet)]
+namespace console { // but see namespace object requirements below
+  // Logging
+  void assert(optional boolean condition = false, any... data);
+  void clear();
+  void count(optional DOMString label = "default");
+  void debug(any... data);
+  void error(any... data);
+  void info(any... data);
+  void log(any... data);
+  void table(any tabularData, optional sequence<DOMString> properties);
+  void trace(any... data);
+  void warn(any... data);
+  void dir(any item, optional object? options);
+  void dirxml(any... data);
+
+  // Grouping
+  void group(any... data);
+  void groupCollapsed(any... data);
+  void groupEnd();
+
+  // Timing
+  void time(optional DOMString label = "default");
+  void timeEnd(optional DOMString label = "default");
+};
+

+   
 For historical reasons, console is lowercased. 

+   
 It is important that console is always visible and usable to scripts, even if the developer
+  console has not been opened or
+  does not exist. 

+   
For historical web-compatibility reasons, the namespace object for console must have as
+its [[Prototype]] an empty object, created as if by ObjectCreate(%ObjectPrototype%), instead of
+%ObjectPrototype%.

+   
2.1. Logging methods

+   
2.1.1. assert(condition, ...data)

+    
  1. If condition is true, abort these steps.
  2. Let message be a string without any formatting specifiers indicating generically an
+  assertion failure (such as "Assertion failed").
  3. If data is empty, append message to data.
  4. Otherwise, implementations should perform these substeps:
    1. Let first be the first element of data.
    2. If Type(first) is not String, prepend message to data. Abort these substeps.
    3. Let concat be the concatenation of message, U+003A COLON (:), U+0020 SPACE, and first.
    4. Set data[0] to concat.
  5. Perform Logger("assert", data).
 
+   
2.1.2. clear()

+   
Empty the appropriate group stack, and if possible for the environment, clear the console.
+Otherwise, do nothing.

+   
2.1.3. count(label)

+    
  1. Let called be the number of times count has been invoked (including this invocation) with
+  the provided label.
  2. Let concat be the concatenation of label, U+003A COLON (:), U+0020 SPACE, and
+  ToString(called).
  3. Perform Logger("count", concat).
 
+   
2.1.4. debug(...data)

+   
Perform Logger("debug", data).

+   
2.1.5. error(...data)

+   
Perform Logger("error", data).

+   
2.1.6. info(...data)

+   
Perform Logger("info", data).

+   
2.1.7. log(...data)

+   
Perform Logger("log", data).

+   
2.1.8. table(tabularData, properties)

+   
Try to construct a table with the columns of the properties of tabularData (or use properties) and rows of tabularData and log it with a logLevel of log. Fall
+back to just logging the argument if it can’t be parsed as tabular.

+   
TODO: This will need a good algorithm.

+   
2.1.9. trace(...data)

+    
  1. Let trace be some implementation-specific, potentially-interactive representation of the
+  callstack from where this method was called.
  2. Optionally let formattedData be the result of Formatter(data), and incorporate
+  formattedData as a label for trace.
  3. Perform Printer("trace", «trace»).
 
+   
 The identifier of a function printed in a stack trace is implementation-dependant. It is also not
+  guaranteed to be the same identifier that would be seen in new Error().stack 

+   
2.1.10. warn(...data)

+   
Perform Logger("warn", data).

+   
2.1.11. dir(item, options)

+    
  1. Let object be item with generic JavaScript object formatting applied.
  2. Perform Printer("dir", «object», options).
 
+   
2.1.12. dirxml(...data)

+    
  1. Let finalList be a new list, initially empty.
  2. For each item of data:
    1. Let converted be a DOM tree representation of item if possible, otherwise let
+    converted be item with optimally useful formatting applied.
    2. Append converted to finalList.
  3. Perform Logger("dirxml", finalList).
 
+   
2.2. Grouping methods

+   
A group is an implementation-specific, potentially-interactive view
+for output produced by calls to Printer, with one further level of indentation than its parent. Each console namespace object has an associated group stack, which is a stack,
+initially empty. Only the last group in a group stack will host output produced by
+calls to Printer.

+   
2.2.1. group(...data)

+    
  1. Let group be a new group.
  2. If data is not empty, let groupLabel be the result of Formatter(data). Otherwise, let
+  groupLabel be an implementation-chosen label representing a group.
  3. Incorporate groupLabel as a label for group.
  4. Optionally, if the environment supports interactive groups, group should be expanded by
+  default.
  5. Perform Printer("group", «group»).
  6. Push group onto the appropriate group stack.
 
+   
2.2.2. groupCollapsed(...data)

+    
  1. Let group be a new group.
  2. If data is not empty, let groupLabel be the result of Formatter(data). Otherwise, let
+  groupLabel be an implementation-chosen label representing a group.
  3. Incorporate groupLabel as a label for group.
  4. Optionally, if the environment supports interactive groups, group should be collapsed by
+  default.
  5. Perform Printer("groupCollapsed", «group»).
  6. Push group onto the appropriate group stack.
 
+   
2.2.3. groupEnd()

+   
Pop the last group from the group stack.

+   
2.3. Timing methods

+   
Each console namespace object has an associated timer table, which is a map of strings to times, initially empty.

+   
2.3.1. time(label)

+   
Set the value of the entry with key label in the associated timer table to the current time.

+   
2.3.2. timeEnd(label)

+    
  1. Let startTime be the result of getting the value of the entry with key
+     label in the associated timer table.
  2. Let duration be a string representing the difference between the current time and
+     startTime, in an implementation-defined format.
+     
    "4650", "4650.69 ms", "5 seconds", and "00:05"
+     are all reasonable ways of displaying a 4650.69 ms duration.
  3. Let concat be the concatenation of label, U+003A COLON (:), U+0020 SPACE, and duration.
  4. Perform Logger("timeEnd", «concat»).
 
+   
3. JavaScript object inspection

+   
TODO: Define an interface that allows JavaScript objects to format themselves for inspection.

+   
Acknowledgments

+   
The editors would like to thank
+Boris Zbarsky,
+Brent S.A. Cowgill,
+Brian Grinstead,
+Corey Farwell,
+Ian Kilpatrick,
+Jeff Carpenter,
+Joseph Pecoraro,
+Justin Woo,
+Noah Bass,
+Paul Irish,
+Raphaël, and
+Victor Costan
+for their contributions to this specification. You are awesome!

+   
This standard is written by Terin Stock (terin@terinstock.com), Robert Kowalski (rok@kowalski.gd), and Dominic Farolino (domfarolino@gmail.com)
+with major help from Domenic Denicola (Google, d@domenic.me).

+   
Per CC0, to the extent possible
+under law, the editors have waived all copyright and related or neighboring rights to this work.

+  

+  
Index

+  
Terms defined by this specification

+  
+  
Terms defined by reference

+  
+  
References

+  
Normative References

+  

+   
[ECMASCRIPT]
+   
ECMAScript Language Specification. URL: https://tc39.github.io/ecma262/
+   
[INFRA]
+   
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
+   
[WebIDL]
+   
Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. URL: https://heycam.github.io/webidl/
+  

+  
IDL Index

+
[Exposed=(Window,Worker,Worklet)]
+namespace console { // but see namespace object requirements below
+  // Logging
+  void assert(optional boolean condition = false, any... data);
+  void clear();
+  void count(optional DOMString label = "default");
+  void debug(any... data);
+  void error(any... data);
+  void info(any... data);
+  void log(any... data);
+  void table(any tabularData, optional sequence<DOMString> properties);
+  void trace(any... data);
+  void warn(any... data);
+  void dir(any item, optional object? options);
+  void dirxml(any... data);
+
+  // Grouping
+  void group(any... data);
+  void groupCollapsed(any... data);
+  void groupEnd();
+
+  // Timing
+  void time(optional DOMString label = "default");
+  void timeEnd(optional DOMString label = "default");
+};
+
+

+
\ No newline at end of file
diff --git a/test/node/parsing/HTMLFileContent-test.js b/test/node/parsing/HTMLFileContent-test.js
index cb81b96..c418866 100644
--- a/test/node/parsing/HTMLFileContent-test.js
+++ b/test/node/parsing/HTMLFileContent-test.js
@@ -29,7 +29,7 @@ describe('HTMLFileContent', function() {
           var expectedContent = fs.readFileSync(`${testDirectory}/${filename}`).toString();
           expect(preBlocks[testNum].content.trim()).toBe(expectedContent.trim());
         } else if (filename !== 'spec.html') {
-          console.warn(`${filename} was not used in ${testName} spec test`);
+          fail(`File ${filename} was not used in ${testName} spec test`);
         }
       });
     });
@@ -41,12 +41,13 @@ describe('HTMLFileContent', function() {
 
   it('should parse a pre tag with no content', function() {
     var content = '
';
+    var htmlFile = HTMLFileContent.create({ file: content });
+    expect(htmlFile).toBeDefined();
+    expect(htmlFile.pre.length).toBe(1);
   });
 
   it('should parse a HTML file with one Web IDL Block', function() {
-    var content = `
-        
-        [Constructor]
+    var idl = `[Constructor]
         interface Dahut : Mammal {
           const unsigned short LEVROGYROUS = 0;
           const unsigned short DEXTROGYROUS = 1;
@@ -56,28 +57,31 @@ describe('HTMLFileContent', function() {
           unsigned long trip();
           void yell([AllowAny] unsigned long volume,
               [TreatNullAs=EmptyString] DOMString sentence);
-        };
-    
`;
-    var ret = HTMLFileContent.create(content);
+        };`;
+    var content = `
${idl}
`;
+    var htmlFile = HTMLFileContent.create({ file: content });
+    expect(htmlFile).toBeDefined();
+    expect(htmlFile.pre.length).toBe(1);
+    expect(htmlFile.pre[0].content).toBe(idl);
   });
 
   it('should parse the UI Events spec HTML file', function() {
     var testDirectory = `${__dirname}/UIEvent`;
-    var expectedFragments = 28;
+    var expectedFragments = 27;
     var expectedIDLFrags = 18;
     cmpTest('UI Events', testDirectory, expectedFragments, expectedIDLFrags);
   });
 
   it('should parse the WebUSB spec HTML file ', function() {
     var testDirectory = `${__dirname}/WebUSB`;
-    var expectedFragments = 15;
+    var expectedFragments = 12;
     var expectedIDLFrags = 11;
     cmpTest('WebUSB', testDirectory, expectedFragments, expectedIDLFrags);
   });
 
   it('should parse the whatwg HTML standard', function() {
     var testDirectory = `${__dirname}/whatwg`;
-    var expectedFragments = 542;
+    var expectedFragments = 155;
     var expectedIDLFrags = 45;
     cmpTest('whatwg HTML', testDirectory, expectedFragments, expectedIDLFrags);
   });
diff --git a/test/node/parsing/UIEvent/27 b/test/node/parsing/UIEvent/26
similarity index 100%
rename from test/node/parsing/UIEvent/27
rename to test/node/parsing/UIEvent/26
diff --git a/test/node/parsing/WebUSB/14 b/test/node/parsing/WebUSB/11
similarity index 100%
rename from test/node/parsing/WebUSB/14
rename to test/node/parsing/WebUSB/11
diff --git a/test/node/parsing/WebUSB/3 b/test/node/parsing/WebUSB/3
deleted file mode 100644
index b13735f..0000000
--- a/test/node/parsing/WebUSB/3
+++ /dev/null
@@ -1,17 +0,0 @@
-let button = document.getElementById('request-device');
-button.addEventListener('click', async () => {
-  let device;
-  try {
-    device = await navigator.usb.requestDevice({ filters: [{
-        vendorId: 0xABCD,
-        classCode: 0xFF, // vendor-specific
-        protocolCode: 0x01
-    }]});
-  } catch () {
-    // No device was selected.
-  }
-
-  if (device !== undefined) {
-    // Add |device| to the UI.
-  }
-});
diff --git a/test/node/parsing/WebUSB/4 b/test/node/parsing/WebUSB/4
new file mode 100644
index 0000000..7e4aee4
--- /dev/null
+++ b/test/node/parsing/WebUSB/4
@@ -0,0 +1,61 @@
+enum USBRequestType {
+  "standard",
+  "class",
+  "vendor"
+};
+
+enum USBRecipient {
+  "device",
+  "interface",
+  "endpoint",
+  "other"
+};
+
+enum USBTransferStatus {
+  "ok",
+  "stall",
+  "babble"
+};
+
+dictionary USBControlTransferParameters {
+  required USBRequestType requestType;
+  required USBRecipient recipient;
+  required octet request;
+  required unsigned short value;
+  required unsigned short index;
+};
+
+[Constructor(USBTransferStatus status, optional DataView? data)]
+interface USBInTransferResult {
+  readonly attribute DataView? data;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(USBTransferStatus status, optional unsigned long bytesWritten = 0)]
+interface USBOutTransferResult {
+  readonly attribute unsigned long bytesWritten;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(USBTransferStatus status, optional DataView? data)]
+interface USBIsochronousInTransferPacket {
+  readonly attribute DataView? data;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(sequence packets, optional DataView? data)]
+interface USBIsochronousInTransferResult {
+  readonly attribute DataView? data;
+  readonly attribute FrozenArray packets;
+};
+
+[Constructor(USBTransferStatus status, optional unsigned long bytesWritten = 0)]
+interface USBIsochronousOutTransferPacket {
+  readonly attribute unsigned long bytesWritten;
+  readonly attribute USBTransferStatus status;
+};
+
+[Constructor(sequence packets)]
+interface USBIsochronousOutTransferResult {
+  readonly attribute FrozenArray packets;
+};
diff --git a/test/node/parsing/whatwg/29 b/test/node/parsing/whatwg/29
deleted file mode 100644
index f2b223e..0000000
--- a/test/node/parsing/whatwg/29
+++ /dev/null
@@ -1,7 +0,0 @@
-[LegacyUnenumerableNamedProperties]
-interface HTMLAllCollection {
-  readonly attribute unsigned long length;
-  getter Element? (unsigned long index);
-  getter (HTMLCollection or Element)? namedItem(DOMString name);
-  legacycaller (HTMLCollection or Element)? item(optional DOMString nameOrIndex);
-};

From 853d12deda11df43e209059b32570f929e1eb7d3 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Tue, 30 May 2017 17:45:53 -0400
Subject: [PATCH 06/23] Adding additional tests

---
 test/node/parsing/HTMLFileContent-test.js  |   18 +-
 test/node/parsing/WebGL/0                  |    2 +
 test/node/parsing/WebGL/3                  |    2 +
 test/node/parsing/WebGL/6                  |  552 +++
 test/node/parsing/WebGL/spec.html          | 4017 ++++++++++++++++++++
 test/node/parsing/XMLHttpRequest/0         |   61 +
 test/node/parsing/XMLHttpRequest/1         |   15 +
 test/node/parsing/XMLHttpRequest/2         |   13 +
 test/node/parsing/XMLHttpRequest/3         |   89 +
 test/node/parsing/XMLHttpRequest/spec.html | 1999 ++++++++++
 10 files changed, 6766 insertions(+), 2 deletions(-)
 create mode 100644 test/node/parsing/WebGL/0
 create mode 100644 test/node/parsing/WebGL/3
 create mode 100644 test/node/parsing/WebGL/6
 create mode 100644 test/node/parsing/WebGL/spec.html
 create mode 100644 test/node/parsing/XMLHttpRequest/0
 create mode 100644 test/node/parsing/XMLHttpRequest/1
 create mode 100644 test/node/parsing/XMLHttpRequest/2
 create mode 100644 test/node/parsing/XMLHttpRequest/3
 create mode 100644 test/node/parsing/XMLHttpRequest/spec.html

diff --git a/test/node/parsing/HTMLFileContent-test.js b/test/node/parsing/HTMLFileContent-test.js
index c418866..aab39e1 100644
--- a/test/node/parsing/HTMLFileContent-test.js
+++ b/test/node/parsing/HTMLFileContent-test.js
@@ -65,20 +65,34 @@ describe('HTMLFileContent', function() {
     expect(htmlFile.pre[0].content).toBe(idl);
   });
 
-  it('should parse the UI Events spec HTML file', function() {
+  it('should parse the UI Events spec HTML file (w3c)', function() {
     var testDirectory = `${__dirname}/UIEvent`;
     var expectedFragments = 27;
     var expectedIDLFrags = 18;
     cmpTest('UI Events', testDirectory, expectedFragments, expectedIDLFrags);
   });
 
-  it('should parse the WebUSB spec HTML file ', function() {
+  it('should parse the WebGL spec HTML file (khronos)', function() {
+    var testDirectory = `${__dirname}/WebGL`;
+    var expectedFragments = 7;
+    var expectedIDLFrags = 7;
+    cmpTest('WebGL', testDirectory, expectedFragments, expectedIDLFrags);
+  });
+
+  it('should parse the WebUSB spec HTML file (wicg)', function() {
     var testDirectory = `${__dirname}/WebUSB`;
     var expectedFragments = 12;
     var expectedIDLFrags = 11;
     cmpTest('WebUSB', testDirectory, expectedFragments, expectedIDLFrags);
   });
 
+  it('should parse the XMLHttpRequest spec HTML file (whatwg)', function() {
+    var testDirectory = `${__dirname}/XMLHttpRequest`;
+    var expectedFragments = 4;
+    var expectedIDLFrags = 4;
+    cmpTest('XMLHttpRequest', testDirectory, expectedFragments, expectedIDLFrags);
+  });
+
   it('should parse the whatwg HTML standard', function() {
     var testDirectory = `${__dirname}/whatwg`;
     var expectedFragments = 155;
diff --git a/test/node/parsing/WebGL/0 b/test/node/parsing/WebGL/0
new file mode 100644
index 0000000..ca9f940
--- /dev/null
+++ b/test/node/parsing/WebGL/0
@@ -0,0 +1,2 @@
+typedef long long GLint64;
+typedef unsigned long long GLuint64;
diff --git a/test/node/parsing/WebGL/3 b/test/node/parsing/WebGL/3
new file mode 100644
index 0000000..87983c3
--- /dev/null
+++ b/test/node/parsing/WebGL/3
@@ -0,0 +1,2 @@
+interface WebGLSync : WebGLObject {
+};
diff --git a/test/node/parsing/WebGL/6 b/test/node/parsing/WebGL/6
new file mode 100644
index 0000000..d0bc10f
--- /dev/null
+++ b/test/node/parsing/WebGL/6
@@ -0,0 +1,552 @@
+typedef ([AllowShared] Uint32Array or sequence) Uint32List;
+
+[NoInterfaceObject]
+interface WebGL2RenderingContextBase
+{
+  const GLenum READ_BUFFER                                   = 0x0C02;
+  const GLenum UNPACK_ROW_LENGTH                             = 0x0CF2;
+  const GLenum UNPACK_SKIP_ROWS                              = 0x0CF3;
+  const GLenum UNPACK_SKIP_PIXELS                            = 0x0CF4;
+  const GLenum PACK_ROW_LENGTH                               = 0x0D02;
+  const GLenum PACK_SKIP_ROWS                                = 0x0D03;
+  const GLenum PACK_SKIP_PIXELS                              = 0x0D04;
+  const GLenum COLOR                                         = 0x1800;
+  const GLenum DEPTH                                         = 0x1801;
+  const GLenum STENCIL                                       = 0x1802;
+  const GLenum RED                                           = 0x1903;
+  const GLenum RGB8                                          = 0x8051;
+  const GLenum RGBA8                                         = 0x8058;
+  const GLenum RGB10_A2                                      = 0x8059;
+  const GLenum TEXTURE_BINDING_3D                            = 0x806A;
+  const GLenum UNPACK_SKIP_IMAGES                            = 0x806D;
+  const GLenum UNPACK_IMAGE_HEIGHT                           = 0x806E;
+  const GLenum TEXTURE_3D                                    = 0x806F;
+  const GLenum TEXTURE_WRAP_R                                = 0x8072;
+  const GLenum MAX_3D_TEXTURE_SIZE                           = 0x8073;
+  const GLenum UNSIGNED_INT_2_10_10_10_REV                   = 0x8368;
+  const GLenum MAX_ELEMENTS_VERTICES                         = 0x80E8;
+  const GLenum MAX_ELEMENTS_INDICES                          = 0x80E9;
+  const GLenum TEXTURE_MIN_LOD                               = 0x813A;
+  const GLenum TEXTURE_MAX_LOD                               = 0x813B;
+  const GLenum TEXTURE_BASE_LEVEL                            = 0x813C;
+  const GLenum TEXTURE_MAX_LEVEL                             = 0x813D;
+  const GLenum MIN                                           = 0x8007;
+  const GLenum MAX                                           = 0x8008;
+  const GLenum DEPTH_COMPONENT24                             = 0x81A6;
+  const GLenum MAX_TEXTURE_LOD_BIAS                          = 0x84FD;
+  const GLenum TEXTURE_COMPARE_MODE                          = 0x884C;
+  const GLenum TEXTURE_COMPARE_FUNC                          = 0x884D;
+  const GLenum CURRENT_QUERY                                 = 0x8865;
+  const GLenum QUERY_RESULT                                  = 0x8866;
+  const GLenum QUERY_RESULT_AVAILABLE                        = 0x8867;
+  const GLenum STREAM_READ                                   = 0x88E1;
+  const GLenum STREAM_COPY                                   = 0x88E2;
+  const GLenum STATIC_READ                                   = 0x88E5;
+  const GLenum STATIC_COPY                                   = 0x88E6;
+  const GLenum DYNAMIC_READ                                  = 0x88E9;
+  const GLenum DYNAMIC_COPY                                  = 0x88EA;
+  const GLenum MAX_DRAW_BUFFERS                              = 0x8824;
+  const GLenum DRAW_BUFFER0                                  = 0x8825;
+  const GLenum DRAW_BUFFER1                                  = 0x8826;
+  const GLenum DRAW_BUFFER2                                  = 0x8827;
+  const GLenum DRAW_BUFFER3                                  = 0x8828;
+  const GLenum DRAW_BUFFER4                                  = 0x8829;
+  const GLenum DRAW_BUFFER5                                  = 0x882A;
+  const GLenum DRAW_BUFFER6                                  = 0x882B;
+  const GLenum DRAW_BUFFER7                                  = 0x882C;
+  const GLenum DRAW_BUFFER8                                  = 0x882D;
+  const GLenum DRAW_BUFFER9                                  = 0x882E;
+  const GLenum DRAW_BUFFER10                                 = 0x882F;
+  const GLenum DRAW_BUFFER11                                 = 0x8830;
+  const GLenum DRAW_BUFFER12                                 = 0x8831;
+  const GLenum DRAW_BUFFER13                                 = 0x8832;
+  const GLenum DRAW_BUFFER14                                 = 0x8833;
+  const GLenum DRAW_BUFFER15                                 = 0x8834;
+  const GLenum MAX_FRAGMENT_UNIFORM_COMPONENTS               = 0x8B49;
+  const GLenum MAX_VERTEX_UNIFORM_COMPONENTS                 = 0x8B4A;
+  const GLenum SAMPLER_3D                                    = 0x8B5F;
+  const GLenum SAMPLER_2D_SHADOW                             = 0x8B62;
+  const GLenum FRAGMENT_SHADER_DERIVATIVE_HINT               = 0x8B8B;
+  const GLenum PIXEL_PACK_BUFFER                             = 0x88EB;
+  const GLenum PIXEL_UNPACK_BUFFER                           = 0x88EC;
+  const GLenum PIXEL_PACK_BUFFER_BINDING                     = 0x88ED;
+  const GLenum PIXEL_UNPACK_BUFFER_BINDING                   = 0x88EF;
+  const GLenum FLOAT_MAT2x3                                  = 0x8B65;
+  const GLenum FLOAT_MAT2x4                                  = 0x8B66;
+  const GLenum FLOAT_MAT3x2                                  = 0x8B67;
+  const GLenum FLOAT_MAT3x4                                  = 0x8B68;
+  const GLenum FLOAT_MAT4x2                                  = 0x8B69;
+  const GLenum FLOAT_MAT4x3                                  = 0x8B6A;
+  const GLenum SRGB                                          = 0x8C40;
+  const GLenum SRGB8                                         = 0x8C41;
+  const GLenum SRGB8_ALPHA8                                  = 0x8C43;
+  const GLenum COMPARE_REF_TO_TEXTURE                        = 0x884E;
+  const GLenum RGBA32F                                       = 0x8814;
+  const GLenum RGB32F                                        = 0x8815;
+  const GLenum RGBA16F                                       = 0x881A;
+  const GLenum RGB16F                                        = 0x881B;
+  const GLenum VERTEX_ATTRIB_ARRAY_INTEGER                   = 0x88FD;
+  const GLenum MAX_ARRAY_TEXTURE_LAYERS                      = 0x88FF;
+  const GLenum MIN_PROGRAM_TEXEL_OFFSET                      = 0x8904;
+  const GLenum MAX_PROGRAM_TEXEL_OFFSET                      = 0x8905;
+  const GLenum MAX_VARYING_COMPONENTS                        = 0x8B4B;
+  const GLenum TEXTURE_2D_ARRAY                              = 0x8C1A;
+  const GLenum TEXTURE_BINDING_2D_ARRAY                      = 0x8C1D;
+  const GLenum R11F_G11F_B10F                                = 0x8C3A;
+  const GLenum UNSIGNED_INT_10F_11F_11F_REV                  = 0x8C3B;
+  const GLenum RGB9_E5                                       = 0x8C3D;
+  const GLenum UNSIGNED_INT_5_9_9_9_REV                      = 0x8C3E;
+  const GLenum TRANSFORM_FEEDBACK_BUFFER_MODE                = 0x8C7F;
+  const GLenum MAX_TRANSFORM_FEEDBACK_SEPARATE_COMPONENTS    = 0x8C80;
+  const GLenum TRANSFORM_FEEDBACK_VARYINGS                   = 0x8C83;
+  const GLenum TRANSFORM_FEEDBACK_BUFFER_START               = 0x8C84;
+  const GLenum TRANSFORM_FEEDBACK_BUFFER_SIZE                = 0x8C85;
+  const GLenum TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN         = 0x8C88;
+  const GLenum RASTERIZER_DISCARD                            = 0x8C89;
+  const GLenum MAX_TRANSFORM_FEEDBACK_INTERLEAVED_COMPONENTS = 0x8C8A;
+  const GLenum MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS       = 0x8C8B;
+  const GLenum INTERLEAVED_ATTRIBS                           = 0x8C8C;
+  const GLenum SEPARATE_ATTRIBS                              = 0x8C8D;
+  const GLenum TRANSFORM_FEEDBACK_BUFFER                     = 0x8C8E;
+  const GLenum TRANSFORM_FEEDBACK_BUFFER_BINDING             = 0x8C8F;
+  const GLenum RGBA32UI                                      = 0x8D70;
+  const GLenum RGB32UI                                       = 0x8D71;
+  const GLenum RGBA16UI                                      = 0x8D76;
+  const GLenum RGB16UI                                       = 0x8D77;
+  const GLenum RGBA8UI                                       = 0x8D7C;
+  const GLenum RGB8UI                                        = 0x8D7D;
+  const GLenum RGBA32I                                       = 0x8D82;
+  const GLenum RGB32I                                        = 0x8D83;
+  const GLenum RGBA16I                                       = 0x8D88;
+  const GLenum RGB16I                                        = 0x8D89;
+  const GLenum RGBA8I                                        = 0x8D8E;
+  const GLenum RGB8I                                         = 0x8D8F;
+  const GLenum RED_INTEGER                                   = 0x8D94;
+  const GLenum RGB_INTEGER                                   = 0x8D98;
+  const GLenum RGBA_INTEGER                                  = 0x8D99;
+  const GLenum SAMPLER_2D_ARRAY                              = 0x8DC1;
+  const GLenum SAMPLER_2D_ARRAY_SHADOW                       = 0x8DC4;
+  const GLenum SAMPLER_CUBE_SHADOW                           = 0x8DC5;
+  const GLenum UNSIGNED_INT_VEC2                             = 0x8DC6;
+  const GLenum UNSIGNED_INT_VEC3                             = 0x8DC7;
+  const GLenum UNSIGNED_INT_VEC4                             = 0x8DC8;
+  const GLenum INT_SAMPLER_2D                                = 0x8DCA;
+  const GLenum INT_SAMPLER_3D                                = 0x8DCB;
+  const GLenum INT_SAMPLER_CUBE                              = 0x8DCC;
+  const GLenum INT_SAMPLER_2D_ARRAY                          = 0x8DCF;
+  const GLenum UNSIGNED_INT_SAMPLER_2D                       = 0x8DD2;
+  const GLenum UNSIGNED_INT_SAMPLER_3D                       = 0x8DD3;
+  const GLenum UNSIGNED_INT_SAMPLER_CUBE                     = 0x8DD4;
+  const GLenum UNSIGNED_INT_SAMPLER_2D_ARRAY                 = 0x8DD7;
+  const GLenum DEPTH_COMPONENT32F                            = 0x8CAC;
+  const GLenum DEPTH32F_STENCIL8                             = 0x8CAD;
+  const GLenum FLOAT_32_UNSIGNED_INT_24_8_REV                = 0x8DAD;
+  const GLenum FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING         = 0x8210;
+  const GLenum FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPE         = 0x8211;
+  const GLenum FRAMEBUFFER_ATTACHMENT_RED_SIZE               = 0x8212;
+  const GLenum FRAMEBUFFER_ATTACHMENT_GREEN_SIZE             = 0x8213;
+  const GLenum FRAMEBUFFER_ATTACHMENT_BLUE_SIZE              = 0x8214;
+  const GLenum FRAMEBUFFER_ATTACHMENT_ALPHA_SIZE             = 0x8215;
+  const GLenum FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE             = 0x8216;
+  const GLenum FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE           = 0x8217;
+  const GLenum FRAMEBUFFER_DEFAULT                           = 0x8218;
+  const GLenum DEPTH_STENCIL_ATTACHMENT                      = 0x821A;
+  const GLenum DEPTH_STENCIL                                 = 0x84F9;
+  const GLenum UNSIGNED_INT_24_8                             = 0x84FA;
+  const GLenum DEPTH24_STENCIL8                              = 0x88F0;
+  const GLenum UNSIGNED_NORMALIZED                           = 0x8C17;
+  const GLenum DRAW_FRAMEBUFFER_BINDING                      = 0x8CA6; /* Same as FRAMEBUFFER_BINDING */
+  const GLenum READ_FRAMEBUFFER                              = 0x8CA8;
+  const GLenum DRAW_FRAMEBUFFER                              = 0x8CA9;
+  const GLenum READ_FRAMEBUFFER_BINDING                      = 0x8CAA;
+  const GLenum RENDERBUFFER_SAMPLES                          = 0x8CAB;
+  const GLenum FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER          = 0x8CD4;
+  const GLenum MAX_COLOR_ATTACHMENTS                         = 0x8CDF;
+  const GLenum COLOR_ATTACHMENT1                             = 0x8CE1;
+  const GLenum COLOR_ATTACHMENT2                             = 0x8CE2;
+  const GLenum COLOR_ATTACHMENT3                             = 0x8CE3;
+  const GLenum COLOR_ATTACHMENT4                             = 0x8CE4;
+  const GLenum COLOR_ATTACHMENT5                             = 0x8CE5;
+  const GLenum COLOR_ATTACHMENT6                             = 0x8CE6;
+  const GLenum COLOR_ATTACHMENT7                             = 0x8CE7;
+  const GLenum COLOR_ATTACHMENT8                             = 0x8CE8;
+  const GLenum COLOR_ATTACHMENT9                             = 0x8CE9;
+  const GLenum COLOR_ATTACHMENT10                            = 0x8CEA;
+  const GLenum COLOR_ATTACHMENT11                            = 0x8CEB;
+  const GLenum COLOR_ATTACHMENT12                            = 0x8CEC;
+  const GLenum COLOR_ATTACHMENT13                            = 0x8CED;
+  const GLenum COLOR_ATTACHMENT14                            = 0x8CEE;
+  const GLenum COLOR_ATTACHMENT15                            = 0x8CEF;
+  const GLenum FRAMEBUFFER_INCOMPLETE_MULTISAMPLE            = 0x8D56;
+  const GLenum MAX_SAMPLES                                   = 0x8D57;
+  const GLenum HALF_FLOAT                                    = 0x140B;
+  const GLenum RG                                            = 0x8227;
+  const GLenum RG_INTEGER                                    = 0x8228;
+  const GLenum R8                                            = 0x8229;
+  const GLenum RG8                                           = 0x822B;
+  const GLenum R16F                                          = 0x822D;
+  const GLenum R32F                                          = 0x822E;
+  const GLenum RG16F                                         = 0x822F;
+  const GLenum RG32F                                         = 0x8230;
+  const GLenum R8I                                           = 0x8231;
+  const GLenum R8UI                                          = 0x8232;
+  const GLenum R16I                                          = 0x8233;
+  const GLenum R16UI                                         = 0x8234;
+  const GLenum R32I                                          = 0x8235;
+  const GLenum R32UI                                         = 0x8236;
+  const GLenum RG8I                                          = 0x8237;
+  const GLenum RG8UI                                         = 0x8238;
+  const GLenum RG16I                                         = 0x8239;
+  const GLenum RG16UI                                        = 0x823A;
+  const GLenum RG32I                                         = 0x823B;
+  const GLenum RG32UI                                        = 0x823C;
+  const GLenum VERTEX_ARRAY_BINDING                          = 0x85B5;
+  const GLenum R8_SNORM                                      = 0x8F94;
+  const GLenum RG8_SNORM                                     = 0x8F95;
+  const GLenum RGB8_SNORM                                    = 0x8F96;
+  const GLenum RGBA8_SNORM                                   = 0x8F97;
+  const GLenum SIGNED_NORMALIZED                             = 0x8F9C;
+  const GLenum COPY_READ_BUFFER                              = 0x8F36;
+  const GLenum COPY_WRITE_BUFFER                             = 0x8F37;
+  const GLenum COPY_READ_BUFFER_BINDING                      = 0x8F36; /* Same as COPY_READ_BUFFER */
+  const GLenum COPY_WRITE_BUFFER_BINDING                     = 0x8F37; /* Same as COPY_WRITE_BUFFER */
+  const GLenum UNIFORM_BUFFER                                = 0x8A11;
+  const GLenum UNIFORM_BUFFER_BINDING                        = 0x8A28;
+  const GLenum UNIFORM_BUFFER_START                          = 0x8A29;
+  const GLenum UNIFORM_BUFFER_SIZE                           = 0x8A2A;
+  const GLenum MAX_VERTEX_UNIFORM_BLOCKS                     = 0x8A2B;
+  const GLenum MAX_FRAGMENT_UNIFORM_BLOCKS                   = 0x8A2D;
+  const GLenum MAX_COMBINED_UNIFORM_BLOCKS                   = 0x8A2E;
+  const GLenum MAX_UNIFORM_BUFFER_BINDINGS                   = 0x8A2F;
+  const GLenum MAX_UNIFORM_BLOCK_SIZE                        = 0x8A30;
+  const GLenum MAX_COMBINED_VERTEX_UNIFORM_COMPONENTS        = 0x8A31;
+  const GLenum MAX_COMBINED_FRAGMENT_UNIFORM_COMPONENTS      = 0x8A33;
+  const GLenum UNIFORM_BUFFER_OFFSET_ALIGNMENT               = 0x8A34;
+  const GLenum ACTIVE_UNIFORM_BLOCKS                         = 0x8A36;
+  const GLenum UNIFORM_TYPE                                  = 0x8A37;
+  const GLenum UNIFORM_SIZE                                  = 0x8A38;
+  const GLenum UNIFORM_BLOCK_INDEX                           = 0x8A3A;
+  const GLenum UNIFORM_OFFSET                                = 0x8A3B;
+  const GLenum UNIFORM_ARRAY_STRIDE                          = 0x8A3C;
+  const GLenum UNIFORM_MATRIX_STRIDE                         = 0x8A3D;
+  const GLenum UNIFORM_IS_ROW_MAJOR                          = 0x8A3E;
+  const GLenum UNIFORM_BLOCK_BINDING                         = 0x8A3F;
+  const GLenum UNIFORM_BLOCK_DATA_SIZE                       = 0x8A40;
+  const GLenum UNIFORM_BLOCK_ACTIVE_UNIFORMS                 = 0x8A42;
+  const GLenum UNIFORM_BLOCK_ACTIVE_UNIFORM_INDICES          = 0x8A43;
+  const GLenum UNIFORM_BLOCK_REFERENCED_BY_VERTEX_SHADER     = 0x8A44;
+  const GLenum UNIFORM_BLOCK_REFERENCED_BY_FRAGMENT_SHADER   = 0x8A46;
+  const GLenum INVALID_INDEX                                 = 0xFFFFFFFF;
+  const GLenum MAX_VERTEX_OUTPUT_COMPONENTS                  = 0x9122;
+  const GLenum MAX_FRAGMENT_INPUT_COMPONENTS                 = 0x9125;
+  const GLenum MAX_SERVER_WAIT_TIMEOUT                       = 0x9111;
+  const GLenum OBJECT_TYPE                                   = 0x9112;
+  const GLenum SYNC_CONDITION                                = 0x9113;
+  const GLenum SYNC_STATUS                                   = 0x9114;
+  const GLenum SYNC_FLAGS                                    = 0x9115;
+  const GLenum SYNC_FENCE                                    = 0x9116;
+  const GLenum SYNC_GPU_COMMANDS_COMPLETE                    = 0x9117;
+  const GLenum UNSIGNALED                                    = 0x9118;
+  const GLenum SIGNALED                                      = 0x9119;
+  const GLenum ALREADY_SIGNALED                              = 0x911A;
+  const GLenum TIMEOUT_EXPIRED                               = 0x911B;
+  const GLenum CONDITION_SATISFIED                           = 0x911C;
+  const GLenum WAIT_FAILED                                   = 0x911D;
+  const GLenum SYNC_FLUSH_COMMANDS_BIT                       = 0x00000001;
+  const GLenum VERTEX_ATTRIB_ARRAY_DIVISOR                   = 0x88FE;
+  const GLenum ANY_SAMPLES_PASSED                            = 0x8C2F;
+  const GLenum ANY_SAMPLES_PASSED_CONSERVATIVE               = 0x8D6A;
+  const GLenum SAMPLER_BINDING                               = 0x8919;
+  const GLenum RGB10_A2UI                                    = 0x906F;
+  const GLenum INT_2_10_10_10_REV                            = 0x8D9F;
+  const GLenum TRANSFORM_FEEDBACK                            = 0x8E22;
+  const GLenum TRANSFORM_FEEDBACK_PAUSED                     = 0x8E23;
+  const GLenum TRANSFORM_FEEDBACK_ACTIVE                     = 0x8E24;
+  const GLenum TRANSFORM_FEEDBACK_BINDING                    = 0x8E25;
+  const GLenum TEXTURE_IMMUTABLE_FORMAT                      = 0x912F;
+  const GLenum MAX_ELEMENT_INDEX                             = 0x8D6B;
+  const GLenum TEXTURE_IMMUTABLE_LEVELS                      = 0x82DF;
+
+  const GLint64 TIMEOUT_IGNORED                              = -1;
+
+  /* WebGL-specific enums */
+  const GLenum MAX_CLIENT_WAIT_TIMEOUT_WEBGL                 = 0x9247;
+
+  /* Buffer objects */
+  // WebGL1:
+  void bufferData(GLenum target, GLsizeiptr size, GLenum usage);
+  void bufferData(GLenum target, [AllowShared] BufferSource? srcData, GLenum usage);
+  void bufferSubData(GLenum target, GLintptr dstByteOffset, [AllowShared] BufferSource srcData);
+  // WebGL2:
+  void bufferData(GLenum target, [AllowShared] ArrayBufferView srcData, GLenum usage, GLuint srcOffset,
+                  optional GLuint length = 0);
+  void bufferSubData(GLenum target, GLintptr dstByteOffset, [AllowShared] ArrayBufferView srcData,
+                     GLuint srcOffset, optional GLuint length = 0);
+
+  void copyBufferSubData(GLenum readTarget, GLenum writeTarget, GLintptr readOffset,
+                         GLintptr writeOffset, GLsizeiptr size);
+  // MapBufferRange, in particular its read-only and write-only modes,
+  // can not be exposed safely to JavaScript. GetBufferSubData
+  // replaces it for the purpose of fetching data back from the GPU.
+  void getBufferSubData(GLenum target, GLintptr srcByteOffset, [AllowShared] ArrayBufferView dstBuffer,
+                        optional GLuint dstOffset = 0, optional GLuint length = 0);
+
+  /* Framebuffer objects */
+  void blitFramebuffer(GLint srcX0, GLint srcY0, GLint srcX1, GLint srcY1, GLint dstX0, GLint dstY0,
+                       GLint dstX1, GLint dstY1, GLbitfield mask, GLenum filter);
+  void framebufferTextureLayer(GLenum target, GLenum attachment, WebGLTexture? texture, GLint level,
+                               GLint layer);
+  void invalidateFramebuffer(GLenum target, sequence attachments);
+  void invalidateSubFramebuffer(GLenum target, sequence attachments,
+                                GLint x, GLint y, GLsizei width, GLsizei height);
+  void readBuffer(GLenum src);
+
+  /* Renderbuffer objects */
+  any getInternalformatParameter(GLenum target, GLenum internalformat, GLenum pname);
+  void renderbufferStorageMultisample(GLenum target, GLsizei samples, GLenum internalformat,
+                                      GLsizei width, GLsizei height);
+
+  /* Texture objects */
+  void texStorage2D(GLenum target, GLsizei levels, GLenum internalformat, GLsizei width,
+                    GLsizei height);
+  void texStorage3D(GLenum target, GLsizei levels, GLenum internalformat, GLsizei width,
+                    GLsizei height, GLsizei depth);
+
+  // WebGL1 legacy entrypoints:
+  void texImage2D(GLenum target, GLint level, GLint internalformat,
+                  GLsizei width, GLsizei height, GLint border, GLenum format,
+                  GLenum type, [AllowShared] ArrayBufferView? pixels);
+  void texImage2D(GLenum target, GLint level, GLint internalformat,
+                  GLenum format, GLenum type, TexImageSource source); // May throw DOMException
+
+  void texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                     GLsizei width, GLsizei height,
+                     GLenum format, GLenum type, [AllowShared] ArrayBufferView? pixels);
+  void texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                     GLenum format, GLenum type, TexImageSource source); // May throw DOMException
+
+  // WebGL2 entrypoints:
+  void texImage2D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height,
+                  GLint border, GLenum format, GLenum type, GLintptr pboOffset);
+  void texImage2D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height,
+                  GLint border, GLenum format, GLenum type,
+                  TexImageSource source); // May throw DOMException
+  void texImage2D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height,
+                  GLint border, GLenum format, GLenum type, [AllowShared] ArrayBufferView srcData,
+                  GLuint srcOffset);
+
+  void texImage3D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height,
+                  GLsizei depth, GLint border, GLenum format, GLenum type, GLintptr pboOffset);
+  void texImage3D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height,
+                  GLsizei depth, GLint border, GLenum format, GLenum type,
+                  TexImageSource source); // May throw DOMException
+  void texImage3D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height,
+                  GLsizei depth, GLint border, GLenum format, GLenum type, [AllowShared] ArrayBufferView? srcData);
+  void texImage3D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height,
+                  GLsizei depth, GLint border, GLenum format, GLenum type, [AllowShared] ArrayBufferView srcData,
+                  GLuint srcOffset);
+
+  void texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width,
+                     GLsizei height, GLenum format, GLenum type, GLintptr pboOffset);
+  void texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width,
+                     GLsizei height, GLenum format, GLenum type,
+                     TexImageSource source); // May throw DOMException
+  void texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width,
+                     GLsizei height, GLenum format, GLenum type, [AllowShared] ArrayBufferView srcData,
+                     GLuint srcOffset);
+
+  void texSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset,
+                     GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type,
+                     GLintptr pboOffset);
+  void texSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset,
+                     GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type,
+                     TexImageSource source); // May throw DOMException
+  void texSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset,
+                     GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type,
+                     [AllowShared] ArrayBufferView? srcData, optional GLuint srcOffset = 0);
+
+  void copyTexSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset,
+                         GLint x, GLint y, GLsizei width, GLsizei height);
+
+  void compressedTexImage2D(GLenum target, GLint level, GLenum internalformat, GLsizei width,
+                            GLsizei height, GLint border, GLsizei imageSize, GLintptr offset);
+  void compressedTexImage2D(GLenum target, GLint level, GLenum internalformat, GLsizei width,
+                            GLsizei height, GLint border, [AllowShared] ArrayBufferView srcData,
+                            optional GLuint srcOffset = 0, optional GLuint srcLengthOverride = 0);
+
+  void compressedTexImage3D(GLenum target, GLint level, GLenum internalformat, GLsizei width,
+                            GLsizei height, GLsizei depth, GLint border, GLsizei imageSize, GLintptr offset);
+  void compressedTexImage3D(GLenum target, GLint level, GLenum internalformat, GLsizei width,
+                            GLsizei height, GLsizei depth, GLint border, [AllowShared] ArrayBufferView srcData,
+                            optional GLuint srcOffset = 0, optional GLuint srcLengthOverride = 0);
+
+  void compressedTexSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                               GLsizei width, GLsizei height, GLenum format, GLsizei imageSize, GLintptr offset);
+  void compressedTexSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                               GLsizei width, GLsizei height, GLenum format,
+                               [AllowShared] ArrayBufferView srcData,
+                               optional GLuint srcOffset = 0,
+                               optional GLuint srcLengthOverride = 0);
+
+  void compressedTexSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                               GLint zoffset, GLsizei width, GLsizei height, GLsizei depth,
+                               GLenum format, GLsizei imageSize, GLintptr offset);
+  void compressedTexSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                               GLint zoffset, GLsizei width, GLsizei height, GLsizei depth,
+                               GLenum format, [AllowShared] ArrayBufferView srcData,
+                               optional GLuint srcOffset = 0,
+                               optional GLuint srcLengthOverride = 0);
+
+  /* Programs and shaders */
+  [WebGLHandlesContextLoss] GLint getFragDataLocation(WebGLProgram program, DOMString name);
+
+  /* Uniforms */
+  void uniform1ui(WebGLUniformLocation? location, GLuint v0);
+  void uniform2ui(WebGLUniformLocation? location, GLuint v0, GLuint v1);
+  void uniform3ui(WebGLUniformLocation? location, GLuint v0, GLuint v1, GLuint v2);
+  void uniform4ui(WebGLUniformLocation? location, GLuint v0, GLuint v1, GLuint v2, GLuint v3);
+
+  void uniform1fv(WebGLUniformLocation? location, Float32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform2fv(WebGLUniformLocation? location, Float32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform3fv(WebGLUniformLocation? location, Float32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform4fv(WebGLUniformLocation? location, Float32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+
+  void uniform1iv(WebGLUniformLocation? location, Int32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform2iv(WebGLUniformLocation? location, Int32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform3iv(WebGLUniformLocation? location, Int32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform4iv(WebGLUniformLocation? location, Int32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+
+  void uniform1uiv(WebGLUniformLocation? location, Uint32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform2uiv(WebGLUniformLocation? location, Uint32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform3uiv(WebGLUniformLocation? location, Uint32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform4uiv(WebGLUniformLocation? location, Uint32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+
+  void uniformMatrix2fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                        optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+  void uniformMatrix3x2fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                          optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+  void uniformMatrix4x2fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                          optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+
+  void uniformMatrix2x3fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                          optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+  void uniformMatrix3fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                        optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+  void uniformMatrix4x3fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                          optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+
+  void uniformMatrix2x4fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                          optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+  void uniformMatrix3x4fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                          optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+  void uniformMatrix4fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                        optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+
+  /* Vertex attribs */
+  void vertexAttribI4i(GLuint index, GLint x, GLint y, GLint z, GLint w);
+  void vertexAttribI4iv(GLuint index, Int32List values);
+  void vertexAttribI4ui(GLuint index, GLuint x, GLuint y, GLuint z, GLuint w);
+  void vertexAttribI4uiv(GLuint index, Uint32List values);
+  void vertexAttribIPointer(GLuint index, GLint size, GLenum type, GLsizei stride, GLintptr offset);
+
+  /* Writing to the drawing buffer */
+  void vertexAttribDivisor(GLuint index, GLuint divisor);
+  void drawArraysInstanced(GLenum mode, GLint first, GLsizei count, GLsizei instanceCount);
+  void drawElementsInstanced(GLenum mode, GLsizei count, GLenum type, GLintptr offset, GLsizei instanceCount);
+  void drawRangeElements(GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, GLintptr offset);
+
+  /* Reading back pixels */
+  // WebGL1:
+  void readPixels(GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type,
+                  [AllowShared] ArrayBufferView? dstData);
+  // WebGL2:
+  void readPixels(GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type,
+                  GLintptr offset);
+  void readPixels(GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type,
+                  [AllowShared] ArrayBufferView dstData, GLuint dstOffset);
+
+  /* Multiple Render Targets */
+  void drawBuffers(sequence buffers);
+
+  void clearBufferfv(GLenum buffer, GLint drawbuffer, Float32List values,
+                     optional GLuint srcOffset = 0);
+  void clearBufferiv(GLenum buffer, GLint drawbuffer, Int32List values,
+                     optional GLuint srcOffset = 0);
+  void clearBufferuiv(GLenum buffer, GLint drawbuffer, Uint32List values,
+                      optional GLuint srcOffset = 0);
+
+  void clearBufferfi(GLenum buffer, GLint drawbuffer, GLfloat depth, GLint stencil);
+
+  /* Query Objects */
+  WebGLQuery? createQuery();
+  void deleteQuery(WebGLQuery? query);
+  [WebGLHandlesContextLoss] GLboolean isQuery(WebGLQuery? query);
+  void beginQuery(GLenum target, WebGLQuery query);
+  void endQuery(GLenum target);
+  WebGLQuery? getQuery(GLenum target, GLenum pname);
+  any getQueryParameter(WebGLQuery query, GLenum pname);
+
+  /* Sampler Objects */
+  WebGLSampler? createSampler();
+  void deleteSampler(WebGLSampler? sampler);
+  [WebGLHandlesContextLoss] GLboolean isSampler(WebGLSampler? sampler);
+  void bindSampler(GLuint unit, WebGLSampler? sampler);
+  void samplerParameteri(WebGLSampler sampler, GLenum pname, GLint param);
+  void samplerParameterf(WebGLSampler sampler, GLenum pname, GLfloat param);
+  any getSamplerParameter(WebGLSampler sampler, GLenum pname);
+
+  /* Sync objects */
+  WebGLSync? fenceSync(GLenum condition, GLbitfield flags);
+  [WebGLHandlesContextLoss] GLboolean isSync(WebGLSync? sync);
+  void deleteSync(WebGLSync? sync);
+  GLenum clientWaitSync(WebGLSync sync, GLbitfield flags, GLuint64 timeout);
+  void waitSync(WebGLSync sync, GLbitfield flags, GLint64 timeout);
+  any getSyncParameter(WebGLSync sync, GLenum pname);
+
+  /* Transform Feedback */
+  WebGLTransformFeedback? createTransformFeedback();
+  void deleteTransformFeedback(WebGLTransformFeedback? tf);
+  [WebGLHandlesContextLoss] GLboolean isTransformFeedback(WebGLTransformFeedback? tf);
+  void bindTransformFeedback (GLenum target, WebGLTransformFeedback? tf);
+  void beginTransformFeedback(GLenum primitiveMode);
+  void endTransformFeedback();
+  void transformFeedbackVaryings(WebGLProgram program, sequence varyings, GLenum bufferMode);
+  WebGLActiveInfo? getTransformFeedbackVarying(WebGLProgram program, GLuint index);
+  void pauseTransformFeedback();
+  void resumeTransformFeedback();
+
+  /* Uniform Buffer Objects and Transform Feedback Buffers */
+  void bindBufferBase(GLenum target, GLuint index, WebGLBuffer? buffer);
+  void bindBufferRange(GLenum target, GLuint index, WebGLBuffer? buffer, GLintptr offset, GLsizeiptr size);
+  any getIndexedParameter(GLenum target, GLuint index);
+  sequence? getUniformIndices(WebGLProgram program, sequence uniformNames);
+  any getActiveUniforms(WebGLProgram program, sequence uniformIndices, GLenum pname);
+  GLuint getUniformBlockIndex(WebGLProgram program, DOMString uniformBlockName);
+  any getActiveUniformBlockParameter(WebGLProgram program, GLuint uniformBlockIndex, GLenum pname);
+  DOMString? getActiveUniformBlockName(WebGLProgram program, GLuint uniformBlockIndex);
+  void uniformBlockBinding(WebGLProgram program, GLuint uniformBlockIndex, GLuint uniformBlockBinding);
+
+  /* Vertex Array Objects */
+  WebGLVertexArrayObject? createVertexArray();
+  void deleteVertexArray(WebGLVertexArrayObject? vertexArray);
+  [WebGLHandlesContextLoss] GLboolean isVertexArray(WebGLVertexArrayObject? vertexArray);
+  void bindVertexArray(WebGLVertexArrayObject? array);
+};
+WebGL2RenderingContextBase implements WebGLRenderingContextBase;
+
+interface WebGL2RenderingContext
+{
+};
+WebGL2RenderingContext implements WebGL2RenderingContextBase;
diff --git a/test/node/parsing/WebGL/spec.html b/test/node/parsing/WebGL/spec.html
new file mode 100644
index 0000000..9df8128
--- /dev/null
+++ b/test/node/parsing/WebGL/spec.html
@@ -0,0 +1,4017 @@
+
+
+
+    
+    WebGL 2 Specification
+    
+    
+    
+
+
+    
+    

+        

+            

+                
+                    WebGL
+                
+            

+        

+        

+            

+                
+                    Khronos
+                
+            

+        

+    

+    

+    
+
+    
WebGL 2 Specification

+    
Editor's Draft Wed May 10 17:39:30 2017 -0400

+    

+        
This version:
+            

+                
+                    https://www.khronos.org/registry/webgl/specs/latest/2.0/
+                
+                

+                
+                    WebIDL: https://www.khronos.org/registry/webgl/specs/latest/2.0/webgl2.idl
+                
+            

+        
Latest version:
+            

+                
+                    https://www.khronos.org/registry/webgl/specs/latest/2.0/
+                
+                

+                
+                    WebIDL: https://www.khronos.org/registry/webgl/specs/latest/2.0/webgl2.idl
+                
+            

+        
Previous version:
+            

+                
+                    https://www.khronos.org/registry/webgl/specs/1.0.2/
+                
+                

+                
+                    WebIDL: https://www.khronos.org/registry/webgl/specs/1.0.2/webgl.idl
+                
+            

+        
Editors:
+            

+                Dean Jackson
+                (Apple Inc.)
+            

+            

+                Jeff Gilbert
+                (Mozilla Corp.)
+            

+    

+
+    Copyright © 2015 Khronos Group
+
+    

+
+    
Abstract

+    

+        This is Version 2.0 of the WebGL Specification.
+    

+    

+        This specification describes an additional rendering context and support
+        objects for the
+        
+            HTML 5 canvas element [CANVAS].
+        
+        This context allows rendering using an API that conforms closely to the OpenGL ES 3.0 API.
+    

+    

+      This document should be read as an extension to the 
+        WebGL 1.0 specification. It will only describe the differences from 1.0.
+
+    
Status of this document

+
+    
+    

+        This document is an editor's draft. Do not cite this document as other than work in
+        progress.
+    

+    
+
+    
Feedback

+    

+        Public discussion of this specification is welcome on
+        the public_webgl@khronos.org mailing list
+        (instructions, archives).
+    

+    

+        Please file bugs against the specification or its conformance tests in
+        the issue tracker. Pull requests
+        are welcome against the Github
+        repository.
+    

+
+    
Table of contents

+    

+
+    
1 Introduction

+    

+    

+      WebGL™ is an immediate mode 3D rendering API designed for the web. This is Version 2 of the
+      WebGL specification. It is derived from OpenGL® ES 3.0, and provides similar rendering
+      functionality, but in an HTML context.
+    

+
+    

+      WebGL 2 is not entirely backwards compatible with WebGL 1. Existing error-free content written
+      against the core WebGL 1 specification without extensions will often run in WebGL 2 without
+      modification, but this is not always the case. All exceptions to backwards compatibility are
+      recorded in the Backwards Incompatibility section.
+      To access the new behavior provided in this specification, the content explicitly requests
+      a new context (details below).
+    

+    

+
+    
1.1 Conventions

+
+    

+     Many functions described in this document contain links to OpenGL ES
+     man pages. While every effort is made to make these pages match the
+     OpenGL ES 3.0 specification [GLES30],
+     they may contain errors. In the case of a contradiction, the OpenGL
+     ES 3.0 specification is the final authority.
+    

+
+    

+      The remaining sections of this document are intended to be read in conjunction
+      with the OpenGL ES 3.0 specification (3.0.4 at the time of this writing, available
+      from the Khronos OpenGL ES API Registry).
+      Unless otherwise specified, the behavior of each method is defined by the
+      OpenGL ES 3.0 specification.  This specification may diverge from OpenGL ES 3.0
+      in order to ensure interoperability or security, often defining areas that
+      OpenGL ES 3.0 leaves implementation-defined.  These differences are summarized in the
+      Differences Between WebGL and OpenGL ES 3.0 section.
+    

+
+
+
+    
2 Context Creation and Drawing Buffer Presentation

+
+    

+        Before using the WebGL API, the author must obtain a WebGLRenderingContext
+        object for a given HTMLCanvasElement [CANVAS] as described
+        below. This object is used to manage OpenGL state and render to the drawing buffer, which
+        must be created at the time of context creation.
+    

+
+
+
+    
2.1 Context Creation

+
+    

+        Each WebGLRenderingContext and WebGL2RenderingContext has an
+        associated canvas, set upon creation, which is
+        a canvas [CANVAS].
+    

+    

+        Each WebGLRenderingContext and WebGL2RenderingContext has context
+        creation parameters, set upon creation, in
+        a WebGLContextAttributes object.
+    

+    

+        Each WebGLRenderingContext and WebGL2RenderingContext has actual
+        context parameters, set each time the drawing buffer is created, in
+        a WebGLContextAttributes object.
+    

+    

+        Each WebGLRenderingContext and WebGL2RenderingContext has a webgl
+        context lost flag, which is initially unset.
+    

+    

+        When the getContext() method of a canvas element is to return a
+        new object for
+        the contextId webgl2 [CANVASCONTEXTS],
+        the user agent must perform the following steps:
+
+        
    
+
+        
  1.  Create a new WebGL2RenderingContext object, context.
+
+        
  2.  Let context's canvas be the canvas
+             the getContext() method is associated with.
+
+        
  3.  Create a new WebGLContextAttributes object, contextAttributes.
+
+        
  4.  If getContext() was invoked with a second argument, options, set
+             the attributes of contextAttributes from those specified in options.
+
+        
  5.  Create a drawing buffer using the settings
+             specified in contextAttributes, and associate the drawing buffer
+             with context.
+
+        
  6.  If drawing buffer creation failed, perform the following steps:
+
+          
      
+
+          
    1.  Fire a WebGL context creation
+          error at canvas.
+
+          
    2.  Return null and terminate these steps.
+
+          
    
+
+        
  7.  Create a new WebGLContextAttributes object, actualAttributes.
+
+        
  8.  Set the attributes of actualAttributes based on the properties of the newly
+             created drawing buffer.
+
+        
  9.  Set context's context creation
+        parameters to contextAttributes.
+
+        
  10.  Set context's actual context
+        parameters to actualAttributes.
+
+        
  11.  Return context.
+
+        

+    

+
+    
2.2 The Drawing Buffer

+
+    

+    Different from WebGL 1.0, the depth, stencil, and
+    antialias attributes in WebGL 2.0 must be obeyed by the WebGL
+    implementation.
+    

+
+
+
+    
3 DOM Interfaces

+
+    

+        This section describes the interfaces and functionality added to the
+        DOM to support runtime access to the functionality described above.
+    

+
+    
+
+    
3.1 Types

+
+    

+      The following types are introduced in WebGL 2.0.
+    

+    
typedef long long GLint64;
+typedef unsigned long long GLuint64;
+

+
+
+
+    
3.2 WebGLQuery

+
+    

+        The WebGLQuery interface represents an OpenGL Query Object.
+        The underlying object is created as if by calling glGenQueries
+        
+          (OpenGL ES 3.0.4 §2.13,
+          man page)
+        ,
+        made active as if by calling glBeginQuery
+        
+          (OpenGL ES 3.0.4 §2.13,
+          man page)
+        ,
+        concluded as if by calling glEndQuery
+        
+          (OpenGL ES 3.0.4 §2.13,
+          man page)
+        
+        and destroyed as if by calling glDeleteQueries
+        
+          (OpenGL ES 3.0.4 §2.13,
+          man page)
+        .
+    

+    
interface WebGLQuery : WebGLObject {
+};

+
+
+
+    
3.3 WebGLSampler

+
+    

+        The WebGLSampler interface represents an OpenGL Sampler Object.
+        The underlying object is created as if by calling glGenSamplers
+        
+          (OpenGL ES 3.0.4 §3.8.2,
+          man page)
+        ,
+         bound as if by calling glBindSampler
+        
+          (OpenGL ES 3.0.4 §3.8.2,
+          man page)
+        
+        and destroyed as if by calling glDeleteSamplers
+        
+          (OpenGL ES 3.0.4 §3.8.2,
+          man page)
+        .
+    

+    
interface WebGLSampler : WebGLObject {
+};

+
+
+
+    
3.4 WebGLSync

+
+    

+        The WebGLSync interface represents an OpenGL Sync Object.
+        The underlying object is created as if by calling glFenceSync
+        
+          (OpenGL ES 3.0.4 §5.2,
+          man page)
+        ,
+        blocked on as if by calling glClientWaitSync
+        
+          (OpenGL ES 3.0.4 §5.2.1,
+          man page)
+        ,
+        waited on internal to GL as if by calling glWaitSync
+        
+          (OpenGL ES 3.0.4 §5.2.1,
+          man page)
+        ,
+        queried as if by calling glGetSynciv
+        
+          (OpenGL ES 3.0.4 §6.2.8,
+          man page)
+        ,
+        and destroyed as if by calling glDeleteSync
+        
+          (OpenGL ES 3.0.4 §5.2,
+          man page)
+        .
+    

+    

+    

+    
interface WebGLSync : WebGLObject {
+};

+
+
+
+    
3.5 WebGLTransformFeedback

+
+    

+        The WebGLTransformFeedback interface represents an OpenGL Transform Feedback Object.
+        The underlying object is created as if by calling glGenTransformFeedbacks
+        
+          (OpenGL ES 3.0.4 §2.14.1,
+          man page)
+        ,
+        bound as if by calling glBindTransformFeedback
+        
+          (OpenGL ES 3.0.4 §2.14.1,
+          man page)
+        
+        and destroyed as if by calling glDeleteTransformFeedbacks
+        
+          (OpenGL ES 3.0.4 §2.14.1,
+          man page)
+        .
+    

+    
interface WebGLTransformFeedback : WebGLObject {
+};

+
+
+
+    
3.6 WebGLVertexArrayObject

+
+    

+        The WebGLVertexArrayObject interface represents an OpenGL Vertex Array Object.
+        The underlying object is created as if by calling glGenVertexArrays
+        
+          (OpenGL ES 3.0.4 §2.10,
+          man page)
+        ,
+        bound as if by calling glBindVertexArray
+        
+          (OpenGL ES 3.0.4 §2.10,
+          man page)
+        
+        and destroyed as if by calling glDeleteVertexArrays
+        
+          (OpenGL ES 3.0.4 §2.10,
+          man page)
+        .
+    

+    
interface WebGLVertexArrayObject : WebGLObject {
+};

+
+
+
+    
3.7 The WebGL context

+
+    

+        The WebGL2RenderingContext represents the API allowing
+        OpenGL ES 3.0 style rendering into the canvas element.
+    

+
+    
typedef ([AllowShared] Uint32Array or sequence<GLuint>) Uint32List;
+
+[NoInterfaceObject]
+interface WebGL2RenderingContextBase
+{
+  const GLenum READ_BUFFER                                   = 0x0C02;
+  const GLenum UNPACK_ROW_LENGTH                             = 0x0CF2;
+  const GLenum UNPACK_SKIP_ROWS                              = 0x0CF3;
+  const GLenum UNPACK_SKIP_PIXELS                            = 0x0CF4;
+  const GLenum PACK_ROW_LENGTH                               = 0x0D02;
+  const GLenum PACK_SKIP_ROWS                                = 0x0D03;
+  const GLenum PACK_SKIP_PIXELS                              = 0x0D04;
+  const GLenum COLOR                                         = 0x1800;
+  const GLenum DEPTH                                         = 0x1801;
+  const GLenum STENCIL                                       = 0x1802;
+  const GLenum RED                                           = 0x1903;
+  const GLenum RGB8                                          = 0x8051;
+  const GLenum RGBA8                                         = 0x8058;
+  const GLenum RGB10_A2                                      = 0x8059;
+  const GLenum TEXTURE_BINDING_3D                            = 0x806A;
+  const GLenum UNPACK_SKIP_IMAGES                            = 0x806D;
+  const GLenum UNPACK_IMAGE_HEIGHT                           = 0x806E;
+  const GLenum TEXTURE_3D                                    = 0x806F;
+  const GLenum TEXTURE_WRAP_R                                = 0x8072;
+  const GLenum MAX_3D_TEXTURE_SIZE                           = 0x8073;
+  const GLenum UNSIGNED_INT_2_10_10_10_REV                   = 0x8368;
+  const GLenum MAX_ELEMENTS_VERTICES                         = 0x80E8;
+  const GLenum MAX_ELEMENTS_INDICES                          = 0x80E9;
+  const GLenum TEXTURE_MIN_LOD                               = 0x813A;
+  const GLenum TEXTURE_MAX_LOD                               = 0x813B;
+  const GLenum TEXTURE_BASE_LEVEL                            = 0x813C;
+  const GLenum TEXTURE_MAX_LEVEL                             = 0x813D;
+  const GLenum MIN                                           = 0x8007;
+  const GLenum MAX                                           = 0x8008;
+  const GLenum DEPTH_COMPONENT24                             = 0x81A6;
+  const GLenum MAX_TEXTURE_LOD_BIAS                          = 0x84FD;
+  const GLenum TEXTURE_COMPARE_MODE                          = 0x884C;
+  const GLenum TEXTURE_COMPARE_FUNC                          = 0x884D;
+  const GLenum CURRENT_QUERY                                 = 0x8865;
+  const GLenum QUERY_RESULT                                  = 0x8866;
+  const GLenum QUERY_RESULT_AVAILABLE                        = 0x8867;
+  const GLenum STREAM_READ                                   = 0x88E1;
+  const GLenum STREAM_COPY                                   = 0x88E2;
+  const GLenum STATIC_READ                                   = 0x88E5;
+  const GLenum STATIC_COPY                                   = 0x88E6;
+  const GLenum DYNAMIC_READ                                  = 0x88E9;
+  const GLenum DYNAMIC_COPY                                  = 0x88EA;
+  const GLenum MAX_DRAW_BUFFERS                              = 0x8824;
+  const GLenum DRAW_BUFFER0                                  = 0x8825;
+  const GLenum DRAW_BUFFER1                                  = 0x8826;
+  const GLenum DRAW_BUFFER2                                  = 0x8827;
+  const GLenum DRAW_BUFFER3                                  = 0x8828;
+  const GLenum DRAW_BUFFER4                                  = 0x8829;
+  const GLenum DRAW_BUFFER5                                  = 0x882A;
+  const GLenum DRAW_BUFFER6                                  = 0x882B;
+  const GLenum DRAW_BUFFER7                                  = 0x882C;
+  const GLenum DRAW_BUFFER8                                  = 0x882D;
+  const GLenum DRAW_BUFFER9                                  = 0x882E;
+  const GLenum DRAW_BUFFER10                                 = 0x882F;
+  const GLenum DRAW_BUFFER11                                 = 0x8830;
+  const GLenum DRAW_BUFFER12                                 = 0x8831;
+  const GLenum DRAW_BUFFER13                                 = 0x8832;
+  const GLenum DRAW_BUFFER14                                 = 0x8833;
+  const GLenum DRAW_BUFFER15                                 = 0x8834;
+  const GLenum MAX_FRAGMENT_UNIFORM_COMPONENTS               = 0x8B49;
+  const GLenum MAX_VERTEX_UNIFORM_COMPONENTS                 = 0x8B4A;
+  const GLenum SAMPLER_3D                                    = 0x8B5F;
+  const GLenum SAMPLER_2D_SHADOW                             = 0x8B62;
+  const GLenum FRAGMENT_SHADER_DERIVATIVE_HINT               = 0x8B8B;
+  const GLenum PIXEL_PACK_BUFFER                             = 0x88EB;
+  const GLenum PIXEL_UNPACK_BUFFER                           = 0x88EC;
+  const GLenum PIXEL_PACK_BUFFER_BINDING                     = 0x88ED;
+  const GLenum PIXEL_UNPACK_BUFFER_BINDING                   = 0x88EF;
+  const GLenum FLOAT_MAT2x3                                  = 0x8B65;
+  const GLenum FLOAT_MAT2x4                                  = 0x8B66;
+  const GLenum FLOAT_MAT3x2                                  = 0x8B67;
+  const GLenum FLOAT_MAT3x4                                  = 0x8B68;
+  const GLenum FLOAT_MAT4x2                                  = 0x8B69;
+  const GLenum FLOAT_MAT4x3                                  = 0x8B6A;
+  const GLenum SRGB                                          = 0x8C40;
+  const GLenum SRGB8                                         = 0x8C41;
+  const GLenum SRGB8_ALPHA8                                  = 0x8C43;
+  const GLenum COMPARE_REF_TO_TEXTURE                        = 0x884E;
+  const GLenum RGBA32F                                       = 0x8814;
+  const GLenum RGB32F                                        = 0x8815;
+  const GLenum RGBA16F                                       = 0x881A;
+  const GLenum RGB16F                                        = 0x881B;
+  const GLenum VERTEX_ATTRIB_ARRAY_INTEGER                   = 0x88FD;
+  const GLenum MAX_ARRAY_TEXTURE_LAYERS                      = 0x88FF;
+  const GLenum MIN_PROGRAM_TEXEL_OFFSET                      = 0x8904;
+  const GLenum MAX_PROGRAM_TEXEL_OFFSET                      = 0x8905;
+  const GLenum MAX_VARYING_COMPONENTS                        = 0x8B4B;
+  const GLenum TEXTURE_2D_ARRAY                              = 0x8C1A;
+  const GLenum TEXTURE_BINDING_2D_ARRAY                      = 0x8C1D;
+  const GLenum R11F_G11F_B10F                                = 0x8C3A;
+  const GLenum UNSIGNED_INT_10F_11F_11F_REV                  = 0x8C3B;
+  const GLenum RGB9_E5                                       = 0x8C3D;
+  const GLenum UNSIGNED_INT_5_9_9_9_REV                      = 0x8C3E;
+  const GLenum TRANSFORM_FEEDBACK_BUFFER_MODE                = 0x8C7F;
+  const GLenum MAX_TRANSFORM_FEEDBACK_SEPARATE_COMPONENTS    = 0x8C80;
+  const GLenum TRANSFORM_FEEDBACK_VARYINGS                   = 0x8C83;
+  const GLenum TRANSFORM_FEEDBACK_BUFFER_START               = 0x8C84;
+  const GLenum TRANSFORM_FEEDBACK_BUFFER_SIZE                = 0x8C85;
+  const GLenum TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN         = 0x8C88;
+  const GLenum RASTERIZER_DISCARD                            = 0x8C89;
+  const GLenum MAX_TRANSFORM_FEEDBACK_INTERLEAVED_COMPONENTS = 0x8C8A;
+  const GLenum MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS       = 0x8C8B;
+  const GLenum INTERLEAVED_ATTRIBS                           = 0x8C8C;
+  const GLenum SEPARATE_ATTRIBS                              = 0x8C8D;
+  const GLenum TRANSFORM_FEEDBACK_BUFFER                     = 0x8C8E;
+  const GLenum TRANSFORM_FEEDBACK_BUFFER_BINDING             = 0x8C8F;
+  const GLenum RGBA32UI                                      = 0x8D70;
+  const GLenum RGB32UI                                       = 0x8D71;
+  const GLenum RGBA16UI                                      = 0x8D76;
+  const GLenum RGB16UI                                       = 0x8D77;
+  const GLenum RGBA8UI                                       = 0x8D7C;
+  const GLenum RGB8UI                                        = 0x8D7D;
+  const GLenum RGBA32I                                       = 0x8D82;
+  const GLenum RGB32I                                        = 0x8D83;
+  const GLenum RGBA16I                                       = 0x8D88;
+  const GLenum RGB16I                                        = 0x8D89;
+  const GLenum RGBA8I                                        = 0x8D8E;
+  const GLenum RGB8I                                         = 0x8D8F;
+  const GLenum RED_INTEGER                                   = 0x8D94;
+  const GLenum RGB_INTEGER                                   = 0x8D98;
+  const GLenum RGBA_INTEGER                                  = 0x8D99;
+  const GLenum SAMPLER_2D_ARRAY                              = 0x8DC1;
+  const GLenum SAMPLER_2D_ARRAY_SHADOW                       = 0x8DC4;
+  const GLenum SAMPLER_CUBE_SHADOW                           = 0x8DC5;
+  const GLenum UNSIGNED_INT_VEC2                             = 0x8DC6;
+  const GLenum UNSIGNED_INT_VEC3                             = 0x8DC7;
+  const GLenum UNSIGNED_INT_VEC4                             = 0x8DC8;
+  const GLenum INT_SAMPLER_2D                                = 0x8DCA;
+  const GLenum INT_SAMPLER_3D                                = 0x8DCB;
+  const GLenum INT_SAMPLER_CUBE                              = 0x8DCC;
+  const GLenum INT_SAMPLER_2D_ARRAY                          = 0x8DCF;
+  const GLenum UNSIGNED_INT_SAMPLER_2D                       = 0x8DD2;
+  const GLenum UNSIGNED_INT_SAMPLER_3D                       = 0x8DD3;
+  const GLenum UNSIGNED_INT_SAMPLER_CUBE                     = 0x8DD4;
+  const GLenum UNSIGNED_INT_SAMPLER_2D_ARRAY                 = 0x8DD7;
+  const GLenum DEPTH_COMPONENT32F                            = 0x8CAC;
+  const GLenum DEPTH32F_STENCIL8                             = 0x8CAD;
+  const GLenum FLOAT_32_UNSIGNED_INT_24_8_REV                = 0x8DAD;
+  const GLenum FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING         = 0x8210;
+  const GLenum FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPE         = 0x8211;
+  const GLenum FRAMEBUFFER_ATTACHMENT_RED_SIZE               = 0x8212;
+  const GLenum FRAMEBUFFER_ATTACHMENT_GREEN_SIZE             = 0x8213;
+  const GLenum FRAMEBUFFER_ATTACHMENT_BLUE_SIZE              = 0x8214;
+  const GLenum FRAMEBUFFER_ATTACHMENT_ALPHA_SIZE             = 0x8215;
+  const GLenum FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE             = 0x8216;
+  const GLenum FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE           = 0x8217;
+  const GLenum FRAMEBUFFER_DEFAULT                           = 0x8218;
+  const GLenum DEPTH_STENCIL_ATTACHMENT                      = 0x821A;
+  const GLenum DEPTH_STENCIL                                 = 0x84F9;
+  const GLenum UNSIGNED_INT_24_8                             = 0x84FA;
+  const GLenum DEPTH24_STENCIL8                              = 0x88F0;
+  const GLenum UNSIGNED_NORMALIZED                           = 0x8C17;
+  const GLenum DRAW_FRAMEBUFFER_BINDING                      = 0x8CA6; /* Same as FRAMEBUFFER_BINDING */
+  const GLenum READ_FRAMEBUFFER                              = 0x8CA8;
+  const GLenum DRAW_FRAMEBUFFER                              = 0x8CA9;
+  const GLenum READ_FRAMEBUFFER_BINDING                      = 0x8CAA;
+  const GLenum RENDERBUFFER_SAMPLES                          = 0x8CAB;
+  const GLenum FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER          = 0x8CD4;
+  const GLenum MAX_COLOR_ATTACHMENTS                         = 0x8CDF;
+  const GLenum COLOR_ATTACHMENT1                             = 0x8CE1;
+  const GLenum COLOR_ATTACHMENT2                             = 0x8CE2;
+  const GLenum COLOR_ATTACHMENT3                             = 0x8CE3;
+  const GLenum COLOR_ATTACHMENT4                             = 0x8CE4;
+  const GLenum COLOR_ATTACHMENT5                             = 0x8CE5;
+  const GLenum COLOR_ATTACHMENT6                             = 0x8CE6;
+  const GLenum COLOR_ATTACHMENT7                             = 0x8CE7;
+  const GLenum COLOR_ATTACHMENT8                             = 0x8CE8;
+  const GLenum COLOR_ATTACHMENT9                             = 0x8CE9;
+  const GLenum COLOR_ATTACHMENT10                            = 0x8CEA;
+  const GLenum COLOR_ATTACHMENT11                            = 0x8CEB;
+  const GLenum COLOR_ATTACHMENT12                            = 0x8CEC;
+  const GLenum COLOR_ATTACHMENT13                            = 0x8CED;
+  const GLenum COLOR_ATTACHMENT14                            = 0x8CEE;
+  const GLenum COLOR_ATTACHMENT15                            = 0x8CEF;
+  const GLenum FRAMEBUFFER_INCOMPLETE_MULTISAMPLE            = 0x8D56;
+  const GLenum MAX_SAMPLES                                   = 0x8D57;
+  const GLenum HALF_FLOAT                                    = 0x140B;
+  const GLenum RG                                            = 0x8227;
+  const GLenum RG_INTEGER                                    = 0x8228;
+  const GLenum R8                                            = 0x8229;
+  const GLenum RG8                                           = 0x822B;
+  const GLenum R16F                                          = 0x822D;
+  const GLenum R32F                                          = 0x822E;
+  const GLenum RG16F                                         = 0x822F;
+  const GLenum RG32F                                         = 0x8230;
+  const GLenum R8I                                           = 0x8231;
+  const GLenum R8UI                                          = 0x8232;
+  const GLenum R16I                                          = 0x8233;
+  const GLenum R16UI                                         = 0x8234;
+  const GLenum R32I                                          = 0x8235;
+  const GLenum R32UI                                         = 0x8236;
+  const GLenum RG8I                                          = 0x8237;
+  const GLenum RG8UI                                         = 0x8238;
+  const GLenum RG16I                                         = 0x8239;
+  const GLenum RG16UI                                        = 0x823A;
+  const GLenum RG32I                                         = 0x823B;
+  const GLenum RG32UI                                        = 0x823C;
+  const GLenum VERTEX_ARRAY_BINDING                          = 0x85B5;
+  const GLenum R8_SNORM                                      = 0x8F94;
+  const GLenum RG8_SNORM                                     = 0x8F95;
+  const GLenum RGB8_SNORM                                    = 0x8F96;
+  const GLenum RGBA8_SNORM                                   = 0x8F97;
+  const GLenum SIGNED_NORMALIZED                             = 0x8F9C;
+  const GLenum COPY_READ_BUFFER                              = 0x8F36;
+  const GLenum COPY_WRITE_BUFFER                             = 0x8F37;
+  const GLenum COPY_READ_BUFFER_BINDING                      = 0x8F36; /* Same as COPY_READ_BUFFER */
+  const GLenum COPY_WRITE_BUFFER_BINDING                     = 0x8F37; /* Same as COPY_WRITE_BUFFER */
+  const GLenum UNIFORM_BUFFER                                = 0x8A11;
+  const GLenum UNIFORM_BUFFER_BINDING                        = 0x8A28;
+  const GLenum UNIFORM_BUFFER_START                          = 0x8A29;
+  const GLenum UNIFORM_BUFFER_SIZE                           = 0x8A2A;
+  const GLenum MAX_VERTEX_UNIFORM_BLOCKS                     = 0x8A2B;
+  const GLenum MAX_FRAGMENT_UNIFORM_BLOCKS                   = 0x8A2D;
+  const GLenum MAX_COMBINED_UNIFORM_BLOCKS                   = 0x8A2E;
+  const GLenum MAX_UNIFORM_BUFFER_BINDINGS                   = 0x8A2F;
+  const GLenum MAX_UNIFORM_BLOCK_SIZE                        = 0x8A30;
+  const GLenum MAX_COMBINED_VERTEX_UNIFORM_COMPONENTS        = 0x8A31;
+  const GLenum MAX_COMBINED_FRAGMENT_UNIFORM_COMPONENTS      = 0x8A33;
+  const GLenum UNIFORM_BUFFER_OFFSET_ALIGNMENT               = 0x8A34;
+  const GLenum ACTIVE_UNIFORM_BLOCKS                         = 0x8A36;
+  const GLenum UNIFORM_TYPE                                  = 0x8A37;
+  const GLenum UNIFORM_SIZE                                  = 0x8A38;
+  const GLenum UNIFORM_BLOCK_INDEX                           = 0x8A3A;
+  const GLenum UNIFORM_OFFSET                                = 0x8A3B;
+  const GLenum UNIFORM_ARRAY_STRIDE                          = 0x8A3C;
+  const GLenum UNIFORM_MATRIX_STRIDE                         = 0x8A3D;
+  const GLenum UNIFORM_IS_ROW_MAJOR                          = 0x8A3E;
+  const GLenum UNIFORM_BLOCK_BINDING                         = 0x8A3F;
+  const GLenum UNIFORM_BLOCK_DATA_SIZE                       = 0x8A40;
+  const GLenum UNIFORM_BLOCK_ACTIVE_UNIFORMS                 = 0x8A42;
+  const GLenum UNIFORM_BLOCK_ACTIVE_UNIFORM_INDICES          = 0x8A43;
+  const GLenum UNIFORM_BLOCK_REFERENCED_BY_VERTEX_SHADER     = 0x8A44;
+  const GLenum UNIFORM_BLOCK_REFERENCED_BY_FRAGMENT_SHADER   = 0x8A46;
+  const GLenum INVALID_INDEX                                 = 0xFFFFFFFF;
+  const GLenum MAX_VERTEX_OUTPUT_COMPONENTS                  = 0x9122;
+  const GLenum MAX_FRAGMENT_INPUT_COMPONENTS                 = 0x9125;
+  const GLenum MAX_SERVER_WAIT_TIMEOUT                       = 0x9111;
+  const GLenum OBJECT_TYPE                                   = 0x9112;
+  const GLenum SYNC_CONDITION                                = 0x9113;
+  const GLenum SYNC_STATUS                                   = 0x9114;
+  const GLenum SYNC_FLAGS                                    = 0x9115;
+  const GLenum SYNC_FENCE                                    = 0x9116;
+  const GLenum SYNC_GPU_COMMANDS_COMPLETE                    = 0x9117;
+  const GLenum UNSIGNALED                                    = 0x9118;
+  const GLenum SIGNALED                                      = 0x9119;
+  const GLenum ALREADY_SIGNALED                              = 0x911A;
+  const GLenum TIMEOUT_EXPIRED                               = 0x911B;
+  const GLenum CONDITION_SATISFIED                           = 0x911C;
+  const GLenum WAIT_FAILED                                   = 0x911D;
+  const GLenum SYNC_FLUSH_COMMANDS_BIT                       = 0x00000001;
+  const GLenum VERTEX_ATTRIB_ARRAY_DIVISOR                   = 0x88FE;
+  const GLenum ANY_SAMPLES_PASSED                            = 0x8C2F;
+  const GLenum ANY_SAMPLES_PASSED_CONSERVATIVE               = 0x8D6A;
+  const GLenum SAMPLER_BINDING                               = 0x8919;
+  const GLenum RGB10_A2UI                                    = 0x906F;
+  const GLenum INT_2_10_10_10_REV                            = 0x8D9F;
+  const GLenum TRANSFORM_FEEDBACK                            = 0x8E22;
+  const GLenum TRANSFORM_FEEDBACK_PAUSED                     = 0x8E23;
+  const GLenum TRANSFORM_FEEDBACK_ACTIVE                     = 0x8E24;
+  const GLenum TRANSFORM_FEEDBACK_BINDING                    = 0x8E25;
+  const GLenum TEXTURE_IMMUTABLE_FORMAT                      = 0x912F;
+  const GLenum MAX_ELEMENT_INDEX                             = 0x8D6B;
+  const GLenum TEXTURE_IMMUTABLE_LEVELS                      = 0x82DF;
+
+  const GLint64 TIMEOUT_IGNORED                              = -1;
+
+  /* WebGL-specific enums */
+  const GLenum MAX_CLIENT_WAIT_TIMEOUT_WEBGL                 = 0x9247;
+
+  /* Buffer objects */
+  // WebGL1:
+  void bufferData(GLenum target, GLsizeiptr size, GLenum usage);
+  void bufferData(GLenum target, [AllowShared] BufferSource? srcData, GLenum usage);
+  void bufferSubData(GLenum target, GLintptr dstByteOffset, [AllowShared] BufferSource srcData);
+  // WebGL2:
+  void bufferData(GLenum target, [AllowShared] ArrayBufferView srcData, GLenum usage, GLuint srcOffset,
+                  optional GLuint length = 0);
+  void bufferSubData(GLenum target, GLintptr dstByteOffset, [AllowShared] ArrayBufferView srcData,
+                     GLuint srcOffset, optional GLuint length = 0);
+
+  void copyBufferSubData(GLenum readTarget, GLenum writeTarget, GLintptr readOffset,
+                         GLintptr writeOffset, GLsizeiptr size);
+  // MapBufferRange, in particular its read-only and write-only modes,
+  // can not be exposed safely to JavaScript. GetBufferSubData
+  // replaces it for the purpose of fetching data back from the GPU.
+  void getBufferSubData(GLenum target, GLintptr srcByteOffset, [AllowShared] ArrayBufferView dstBuffer,
+                        optional GLuint dstOffset = 0, optional GLuint length = 0);
+
+  /* Framebuffer objects */
+  void blitFramebuffer(GLint srcX0, GLint srcY0, GLint srcX1, GLint srcY1, GLint dstX0, GLint dstY0,
+                       GLint dstX1, GLint dstY1, GLbitfield mask, GLenum filter);
+  void framebufferTextureLayer(GLenum target, GLenum attachment, WebGLTexture? texture, GLint level,
+                               GLint layer);
+  void invalidateFramebuffer(GLenum target, sequence<GLenum> attachments);
+  void invalidateSubFramebuffer(GLenum target, sequence<GLenum> attachments,
+                                GLint x, GLint y, GLsizei width, GLsizei height);
+  void readBuffer(GLenum src);
+
+  /* Renderbuffer objects */
+  any getInternalformatParameter(GLenum target, GLenum internalformat, GLenum pname);
+  void renderbufferStorageMultisample(GLenum target, GLsizei samples, GLenum internalformat,
+                                      GLsizei width, GLsizei height);
+
+  /* Texture objects */
+  void texStorage2D(GLenum target, GLsizei levels, GLenum internalformat, GLsizei width,
+                    GLsizei height);
+  void texStorage3D(GLenum target, GLsizei levels, GLenum internalformat, GLsizei width,
+                    GLsizei height, GLsizei depth);
+
+  // WebGL1 legacy entrypoints:
+  void texImage2D(GLenum target, GLint level, GLint internalformat,
+                  GLsizei width, GLsizei height, GLint border, GLenum format,
+                  GLenum type, [AllowShared] ArrayBufferView? pixels);
+  void texImage2D(GLenum target, GLint level, GLint internalformat,
+                  GLenum format, GLenum type, TexImageSource source); // May throw DOMException
+
+  void texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                     GLsizei width, GLsizei height,
+                     GLenum format, GLenum type, [AllowShared] ArrayBufferView? pixels);
+  void texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                     GLenum format, GLenum type, TexImageSource source); // May throw DOMException
+
+  // WebGL2 entrypoints:
+  void texImage2D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height,
+                  GLint border, GLenum format, GLenum type, GLintptr pboOffset);
+  void texImage2D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height,
+                  GLint border, GLenum format, GLenum type,
+                  TexImageSource source); // May throw DOMException
+  void texImage2D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height,
+                  GLint border, GLenum format, GLenum type, [AllowShared] ArrayBufferView srcData,
+                  GLuint srcOffset);
+
+  void texImage3D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height,
+                  GLsizei depth, GLint border, GLenum format, GLenum type, GLintptr pboOffset);
+  void texImage3D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height,
+                  GLsizei depth, GLint border, GLenum format, GLenum type,
+                  TexImageSource source); // May throw DOMException
+  void texImage3D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height,
+                  GLsizei depth, GLint border, GLenum format, GLenum type, [AllowShared] ArrayBufferView? srcData);
+  void texImage3D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height,
+                  GLsizei depth, GLint border, GLenum format, GLenum type, [AllowShared] ArrayBufferView srcData,
+                  GLuint srcOffset);
+
+  void texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width,
+                     GLsizei height, GLenum format, GLenum type, GLintptr pboOffset);
+  void texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width,
+                     GLsizei height, GLenum format, GLenum type,
+                     TexImageSource source); // May throw DOMException
+  void texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width,
+                     GLsizei height, GLenum format, GLenum type, [AllowShared] ArrayBufferView srcData,
+                     GLuint srcOffset);
+
+  void texSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset,
+                     GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type,
+                     GLintptr pboOffset);
+  void texSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset,
+                     GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type,
+                     TexImageSource source); // May throw DOMException
+  void texSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset,
+                     GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type,
+                     [AllowShared] ArrayBufferView? srcData, optional GLuint srcOffset = 0);
+
+  void copyTexSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset,
+                         GLint x, GLint y, GLsizei width, GLsizei height);
+
+  void compressedTexImage2D(GLenum target, GLint level, GLenum internalformat, GLsizei width,
+                            GLsizei height, GLint border, GLsizei imageSize, GLintptr offset);
+  void compressedTexImage2D(GLenum target, GLint level, GLenum internalformat, GLsizei width,
+                            GLsizei height, GLint border, [AllowShared] ArrayBufferView srcData,
+                            optional GLuint srcOffset = 0, optional GLuint srcLengthOverride = 0);
+
+  void compressedTexImage3D(GLenum target, GLint level, GLenum internalformat, GLsizei width,
+                            GLsizei height, GLsizei depth, GLint border, GLsizei imageSize, GLintptr offset);
+  void compressedTexImage3D(GLenum target, GLint level, GLenum internalformat, GLsizei width,
+                            GLsizei height, GLsizei depth, GLint border, [AllowShared] ArrayBufferView srcData,
+                            optional GLuint srcOffset = 0, optional GLuint srcLengthOverride = 0);
+
+  void compressedTexSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                               GLsizei width, GLsizei height, GLenum format, GLsizei imageSize, GLintptr offset);
+  void compressedTexSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                               GLsizei width, GLsizei height, GLenum format,
+                               [AllowShared] ArrayBufferView srcData,
+                               optional GLuint srcOffset = 0,
+                               optional GLuint srcLengthOverride = 0);
+
+  void compressedTexSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                               GLint zoffset, GLsizei width, GLsizei height, GLsizei depth,
+                               GLenum format, GLsizei imageSize, GLintptr offset);
+  void compressedTexSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                               GLint zoffset, GLsizei width, GLsizei height, GLsizei depth,
+                               GLenum format, [AllowShared] ArrayBufferView srcData,
+                               optional GLuint srcOffset = 0,
+                               optional GLuint srcLengthOverride = 0);
+
+  /* Programs and shaders */
+  [WebGLHandlesContextLoss] GLint getFragDataLocation(WebGLProgram program, DOMString name);
+
+  /* Uniforms */
+  void uniform1ui(WebGLUniformLocation? location, GLuint v0);
+  void uniform2ui(WebGLUniformLocation? location, GLuint v0, GLuint v1);
+  void uniform3ui(WebGLUniformLocation? location, GLuint v0, GLuint v1, GLuint v2);
+  void uniform4ui(WebGLUniformLocation? location, GLuint v0, GLuint v1, GLuint v2, GLuint v3);
+
+  void uniform1fv(WebGLUniformLocation? location, Float32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform2fv(WebGLUniformLocation? location, Float32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform3fv(WebGLUniformLocation? location, Float32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform4fv(WebGLUniformLocation? location, Float32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+
+  void uniform1iv(WebGLUniformLocation? location, Int32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform2iv(WebGLUniformLocation? location, Int32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform3iv(WebGLUniformLocation? location, Int32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform4iv(WebGLUniformLocation? location, Int32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+
+  void uniform1uiv(WebGLUniformLocation? location, Uint32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform2uiv(WebGLUniformLocation? location, Uint32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform3uiv(WebGLUniformLocation? location, Uint32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+  void uniform4uiv(WebGLUniformLocation? location, Uint32List data, optional GLuint srcOffset = 0,
+                  optional GLuint srcLength = 0);
+
+  void uniformMatrix2fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                        optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+  void uniformMatrix3x2fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                          optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+  void uniformMatrix4x2fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                          optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+
+  void uniformMatrix2x3fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                          optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+  void uniformMatrix3fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                        optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+  void uniformMatrix4x3fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                          optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+
+  void uniformMatrix2x4fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                          optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+  void uniformMatrix3x4fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                          optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+  void uniformMatrix4fv(WebGLUniformLocation? location, GLboolean transpose, Float32List data,
+                        optional GLuint srcOffset = 0, optional GLuint srcLength = 0);
+
+  /* Vertex attribs */
+  void vertexAttribI4i(GLuint index, GLint x, GLint y, GLint z, GLint w);
+  void vertexAttribI4iv(GLuint index, Int32List values);
+  void vertexAttribI4ui(GLuint index, GLuint x, GLuint y, GLuint z, GLuint w);
+  void vertexAttribI4uiv(GLuint index, Uint32List values);
+  void vertexAttribIPointer(GLuint index, GLint size, GLenum type, GLsizei stride, GLintptr offset);
+
+  /* Writing to the drawing buffer */
+  void vertexAttribDivisor(GLuint index, GLuint divisor);
+  void drawArraysInstanced(GLenum mode, GLint first, GLsizei count, GLsizei instanceCount);
+  void drawElementsInstanced(GLenum mode, GLsizei count, GLenum type, GLintptr offset, GLsizei instanceCount);
+  void drawRangeElements(GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, GLintptr offset);
+
+  /* Reading back pixels */
+  // WebGL1:
+  void readPixels(GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type,
+                  [AllowShared] ArrayBufferView? dstData);
+  // WebGL2:
+  void readPixels(GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type,
+                  GLintptr offset);
+  void readPixels(GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type,
+                  [AllowShared] ArrayBufferView dstData, GLuint dstOffset);
+
+  /* Multiple Render Targets */
+  void drawBuffers(sequence<GLenum> buffers);
+
+  void clearBufferfv(GLenum buffer, GLint drawbuffer, Float32List values,
+                     optional GLuint srcOffset = 0);
+  void clearBufferiv(GLenum buffer, GLint drawbuffer, Int32List values,
+                     optional GLuint srcOffset = 0);
+  void clearBufferuiv(GLenum buffer, GLint drawbuffer, Uint32List values,
+                      optional GLuint srcOffset = 0);
+
+  void clearBufferfi(GLenum buffer, GLint drawbuffer, GLfloat depth, GLint stencil);
+
+  /* Query Objects */
+  WebGLQuery? createQuery();
+  void deleteQuery(WebGLQuery? query);
+  [WebGLHandlesContextLoss] GLboolean isQuery(WebGLQuery? query);
+  void beginQuery(GLenum target, WebGLQuery query);
+  void endQuery(GLenum target);
+  WebGLQuery? getQuery(GLenum target, GLenum pname);
+  any getQueryParameter(WebGLQuery query, GLenum pname);
+
+  /* Sampler Objects */
+  WebGLSampler? createSampler();
+  void deleteSampler(WebGLSampler? sampler);
+  [WebGLHandlesContextLoss] GLboolean isSampler(WebGLSampler? sampler);
+  void bindSampler(GLuint unit, WebGLSampler? sampler);
+  void samplerParameteri(WebGLSampler sampler, GLenum pname, GLint param);
+  void samplerParameterf(WebGLSampler sampler, GLenum pname, GLfloat param);
+  any getSamplerParameter(WebGLSampler sampler, GLenum pname);
+
+  /* Sync objects */
+  WebGLSync? fenceSync(GLenum condition, GLbitfield flags);
+  [WebGLHandlesContextLoss] GLboolean isSync(WebGLSync? sync);
+  void deleteSync(WebGLSync? sync);
+  GLenum clientWaitSync(WebGLSync sync, GLbitfield flags, GLuint64 timeout);
+  void waitSync(WebGLSync sync, GLbitfield flags, GLint64 timeout);
+  any getSyncParameter(WebGLSync sync, GLenum pname);
+
+  /* Transform Feedback */
+  WebGLTransformFeedback? createTransformFeedback();
+  void deleteTransformFeedback(WebGLTransformFeedback? tf);
+  [WebGLHandlesContextLoss] GLboolean isTransformFeedback(WebGLTransformFeedback? tf);
+  void bindTransformFeedback (GLenum target, WebGLTransformFeedback? tf);
+  void beginTransformFeedback(GLenum primitiveMode);
+  void endTransformFeedback();
+  void transformFeedbackVaryings(WebGLProgram program, sequence<DOMString> varyings, GLenum bufferMode);
+  WebGLActiveInfo? getTransformFeedbackVarying(WebGLProgram program, GLuint index);
+  void pauseTransformFeedback();
+  void resumeTransformFeedback();
+
+  /* Uniform Buffer Objects and Transform Feedback Buffers */
+  void bindBufferBase(GLenum target, GLuint index, WebGLBuffer? buffer);
+  void bindBufferRange(GLenum target, GLuint index, WebGLBuffer? buffer, GLintptr offset, GLsizeiptr size);
+  any getIndexedParameter(GLenum target, GLuint index);
+  sequence<GLuint>? getUniformIndices(WebGLProgram program, sequence<DOMString> uniformNames);
+  any getActiveUniforms(WebGLProgram program, sequence<GLuint> uniformIndices, GLenum pname);
+  GLuint getUniformBlockIndex(WebGLProgram program, DOMString uniformBlockName);
+  any getActiveUniformBlockParameter(WebGLProgram program, GLuint uniformBlockIndex, GLenum pname);
+  DOMString? getActiveUniformBlockName(WebGLProgram program, GLuint uniformBlockIndex);
+  void uniformBlockBinding(WebGLProgram program, GLuint uniformBlockIndex, GLuint uniformBlockBinding);
+
+  /* Vertex Array Objects */
+  WebGLVertexArrayObject? createVertexArray();
+  void deleteVertexArray(WebGLVertexArrayObject? vertexArray);
+  [WebGLHandlesContextLoss] GLboolean isVertexArray(WebGLVertexArrayObject? vertexArray);
+  void bindVertexArray(WebGLVertexArrayObject? array);
+};
+WebGL2RenderingContextBase implements WebGLRenderingContextBase;
+
+interface WebGL2RenderingContext
+{
+};
+WebGL2RenderingContext implements WebGL2RenderingContextBase;
+
+

+
+
+
+    
3.7.1 More binding points

+
+    

+      
void bindBuffer(GLenum target, WebGLBuffer? buffer)
+          (OpenGL ES 3.0.4 §2.9.1, man page)
+      

+      

+          Binds the given WebGLBuffer object to the given binding point(target). target is given in the following table:
+          
+              
+              
+              
+              
+              
+              
+              
+              
+              
+          
target
ARRAY_BUFFER
COPY_READ_BUFFER
COPY_WRITE_BUFFER
ELEMENT_ARRAY_BUFFER
PIXEL_PACK_BUFFER
PIXEL_UNPACK_BUFFER
TRANSFORM_FEEDBACK_BUFFER
UNIFORM_BUFFER

+          
If target is not in the table above, generates an INVALID_ENUM error.

+      

+      

+          Refer to Buffer Object Binding restrictions below.
+      

+
+      
void bindFramebuffer(GLenum target, WebGLFramebuffer? framebuffer)
+          (OpenGL ES 3.0.4 §4.4.1, man page)
+      

+      

+          Binds the given WebGLFramebuffer object to the given binding point(target). target is given in the following table:
+          
+              
+              
+              
+              
+          
target
FRAMEBUFFER
READ_FRAMEBUFFER
DRAW_FRAMEBUFFER

+          
If framebuffer is null, the default framebuffer provided by the context is bound.

+          
If target is not in the table above, generates an INVALID_ENUM error.

+          
An attempt to bind a deleted framebuffer will generate an INVALID_OPERATION error, and the current binding will remain untouched.

+      

+
+      
void bindTexture(GLenum target, WebGLTexture? texture)
+          (OpenGL ES 3.0.4 §3.8.1, man page)
+      

+      

+          Binds the given WebGLTexture object to the given binding point(target). target is given in the following table:
+          
+              
+              
+              
+              
+              
+          
target
TEXTURE_2D
TEXTURE_3D
TEXTURE_2D_ARRAY
TEXTURE_CUBE_MAP

+          
If target is not in the table above, generates an INVALID_ENUM error.

+          
An attempt to bind a deleted texture will generate an INVALID_OPERATION error, and the current binding will remain untouched.

+      

+    

+
+
+
+    
3.7.2 Setting and getting state

+
+    

+        
any getParameter(GLenum pname)
+            (OpenGL ES 3.0.4 §6.1.1,
+            glGet OpenGL ES 3.0 man page,
+            glGetString OpenGL ES 3.0 man page)
+        

+            Return the value for the passed pname. As well as supporting all
+            the pname/type values from WebGL 1.0, the following parameters are supported:
+            
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+                
+            
pnamereturned type
COPY_READ_BUFFER_BINDINGWebGLBuffer
COPY_WRITE_BUFFER_BINDINGWebGLBuffer
DRAW_BUFFERiGLenum
DRAW_FRAMEBUFFER_BINDINGWebGLFramebuffer
FRAGMENT_SHADER_DERIVATIVE_HINTGLenum
MAX_3D_TEXTURE_SIZEGLint
MAX_ARRAY_TEXTURE_LAYERSGLint
MAX_CLIENT_WAIT_TIMEOUT_WEBGLGLint64
MAX_COLOR_ATTACHMENTSGLint
MAX_COMBINED_FRAGMENT_UNIFORM_COMPONENTSGLint64
MAX_COMBINED_UNIFORM_BLOCKSGLint
MAX_COMBINED_VERTEX_UNIFORM_COMPONENTSGLint64
MAX_DRAW_BUFFERSGLint
MAX_ELEMENT_INDEXGLint64
MAX_ELEMENTS_INDICESGLint
MAX_ELEMENTS_VERTICESGLint
MAX_FRAGMENT_INPUT_COMPONENTSGLint
MAX_FRAGMENT_UNIFORM_BLOCKSGLint
MAX_FRAGMENT_UNIFORM_COMPONENTSGLint
MAX_PROGRAM_TEXEL_OFFSETGLint
MAX_SAMPLESGLint
MAX_SERVER_WAIT_TIMEOUTGLint64
MAX_TEXTURE_LOD_BIASGLfloat
MAX_TRANSFORM_FEEDBACK_INTERLEAVED_COMPONENTSGLint
MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBSGLint
MAX_TRANSFORM_FEEDBACK_SEPARATE_COMPONENTSGLint
MAX_UNIFORM_BLOCK_SIZEGLint64
MAX_UNIFORM_BUFFER_BINDINGSGLint
MAX_VARYING_COMPONENTSGLint
MAX_VERTEX_OUTPUT_COMPONENTSGLint
MAX_VERTEX_UNIFORM_BLOCKSGLint
MAX_VERTEX_UNIFORM_COMPONENTSGLint
MIN_PROGRAM_TEXEL_OFFSETGLint
PACK_ROW_LENGTHGLint
PACK_SKIP_PIXELSGLint
PACK_SKIP_ROWSGLint
PIXEL_PACK_BUFFER_BINDINGWebGLBuffer
PIXEL_UNPACK_BUFFER_BINDINGWebGLBuffer
RASTERIZER_DISCARDGLboolean
READ_BUFFERGLenum
READ_FRAMEBUFFER_BINDINGWebGLFramebuffer
SAMPLE_ALPHA_TO_COVERAGEGLboolean
SAMPLE_COVERAGEGLboolean
SAMPLER_BINDINGWebGLSampler
TEXTURE_BINDING_2D_ARRAYWebGLTexture
TEXTURE_BINDING_3DWebGLTexture
TRANSFORM_FEEDBACK_ACTIVEGLboolean
TRANSFORM_FEEDBACK_BINDINGWebGLTransformFeedback
TRANSFORM_FEEDBACK_BUFFER_BINDINGWebGLBuffer
TRANSFORM_FEEDBACK_PAUSEDGLboolean
UNIFORM_BUFFER_BINDINGWebGLBuffer
UNIFORM_BUFFER_OFFSET_ALIGNMENTGLint
UNPACK_IMAGE_HEIGHTGLint
UNPACK_ROW_LENGTHGLint
UNPACK_SKIP_IMAGESGLint
UNPACK_SKIP_PIXELSGLint
UNPACK_SKIP_ROWSGLint
VERTEX_ARRAY_BINDINGWebGLVertexArrayObject


+            
All queries returning sequences or typed arrays return a new object each time.

+            
If pname is not in the table above and is not one of parameter names supported by WebGL 1.0, generates an INVALID_ENUM error and returns null.

+            
The following pname arguments return a string describing some aspect of the current WebGL implementation:

+            
+              
+                  
+              
+                  
+            
VERSIONReturns a version or release number of the form WebGL<space>2.0<optional><space><vendor-specific information></optional>.
SHADING_LANGUAGE_VERSIONReturns a version or release number of the form WebGL<space>GLSL<space>ES<space>3.00<optional><space><vendor-specific information></optional>.


+            
For RED_BITS, GREEN_BITS, BLUE_BITS, and ALPHA_BITS, if active color attachments of the draw framebuffer do not have identical formats, generates an INVALID_OPERATION error and returns 0.

+
+        
any getIndexedParameter(GLenum target, GLuint index)
+            (OpenGL ES 3.0.4 §6.1.1,
+            glGet OpenGL ES 3.0 man page)
+        

+            Return the indexed value for the passed target. The type returned is the natural type for the requested pname,
+            as given in the following table:
+            
+                
+                
+                
+                
+                
+                
+                
+            
targetreturned type
TRANSFORM_FEEDBACK_BUFFER_BINDINGWebGLBuffer
TRANSFORM_FEEDBACK_BUFFER_SIZEGLsizeiptr
TRANSFORM_FEEDBACK_BUFFER_STARTGLintptr
UNIFORM_BUFFER_BINDINGWebGLBuffer
UNIFORM_BUFFER_SIZEGLsizeiptr
UNIFORM_BUFFER_STARTGLintptr


+            
If target is not in the table above, generates an INVALID_ENUM error.

+            
If index is outside of the valid range for the indexed state target, generates an INVALID_VALUE error.

+            
If an OpenGL error is generated, returns null.

+        
GLboolean isEnabled(GLenum cap)
+            (OpenGL ES 3.0.4 §6.1.1,
+            OpenGL ES 3.0 man page)
+        

+            In addition to all of the cap values from WebGL 1.0, RASTERIZER_DISCARD is supported.
+        
void pixelStorei(GLenum pname, GLint param)
+            (OpenGL ES 3.0.4 §3.7.1, OpenGL ES 3.0 man page)
+        

+            In addition to the parameters from WebGL 1.0, the WebGL 2 specification accepts the following extra parameters:
+            
+                
+                
+                
+                
+                
+                
+                
+                
+                
+            
pname
PACK_ROW_LENGTH
PACK_SKIP_PIXELS
PACK_SKIP_ROWS
UNPACK_ROW_LENGTH
UNPACK_IMAGE_HEIGHT
UNPACK_SKIP_PIXELS
UNPACK_SKIP_ROWS
UNPACK_SKIP_IMAGES


+    

+
+
+
+    
3.7.3 Buffer objects

+
+    

+
+      
void bufferData(GLenum target, [AllowShared] ArrayBufferView srcData, GLenum usage, GLuint srcOffset, optional GLuint length = 0);
+          
+          (OpenGL ES 3.0.4 §2.10.2,
+           man page)
+          
+      

+      

+        Set the size of the currently bound WebGLBuffer object, then copy a sub-region of srcData to the buffer object.
+        


+        Let buf be the buffer bound to target.
+        


+        If length is 0:
+        
    
+        
  •  If srcData is a DataView, let copyLength be srcData.byteLength - srcOffset; the typed elements in the text below are bytes.
+        
  •  Otherwise, let copyLength be srcData.length - srcOffset.
+        

+        Otherwise, let copyLength be length.
+        


+        If srcData is a DataView, set the size of buf to copyLength; otherwise, set the size of buf to copyLength * srcData.BYTES_PER_ELEMENT.
+        


+        If srcData is a DataView, let elementSize be 1; otherwise, let elementSize be srcData.BYTES_PER_ELEMENT.
+        


+        If copyLength is greater than zero, copy copyLength typed elements
+        (each of size elementSize) from srcData into buf,
+        reading srcData starting at element index srcOffset.
+        If copyLength is 0, no data is written to buf, but this does
+        not cause a GL error to be generated.
+        
    
+          
  •  If no WebGLBuffer is bound to target, generates an INVALID_OPERATION error.
+          
  •  If srcOffset is greater than srcData.length (or srcData.byteLength for DataView), generates an INVALID_VALUE error.
+          
  •  If srcOffset + copyLength is greater than srcData.length (or srcData.byteLength for DataView), generates an INVALID_VALUE error.
+        

+        If any error is generated, buf's size is unmodified, and no data is written to it.
+      

+
+      
void bufferSubData(GLenum target, GLintptr dstByteOffset, [AllowShared] ArrayBufferView srcData, GLuint srcOffset, optional GLuint length = 0);
+          
+          (OpenGL ES 3.0.4 §2.10.2,
+           man page)
+          
+      

+      

+        Copy a sub-region of srcData to the currently bound WebGLBuffer object.
+        


+        Let buf be the buffer bound to target.
+        


+        If length is 0:
+        
    
+        
  •  If srcData is a DataView, let copyLength be srcData.byteLength - srcOffset; the typed elements in the text below are bytes.
+        
  •  Otherwise, let copyLength be srcData.length - srcOffset.
+        

+        Otherwise, let copyLength be length.
+        


+        If srcData is a DataView, let copyByteLength be copyLength; otherwise, let copyByteLength be copyLength * srcData.BYTES_PER_ELEMENT.
+        


+        If srcData is a DataView, let elementSize be 1; otherwise, let elementSize be srcData.BYTES_PER_ELEMENT.
+        


+        If copyLength is greater than zero, copy copyLength typed elements
+        (each of size elementSize) from srcData into buf,
+        reading srcData starting at element index srcOffset, and
+        writing buf starting at byte offset dstByteOffset.
+        If copyLength is 0, no data is written to buf, but this does
+        not cause a GL error to be generated.
+        
    
+          
  •  If no WebGLBuffer is bound to target, generates an INVALID_OPERATION error.
+          
  •  If dstByteOffset is less than zero, generates an INVALID_VALUE error.
+          
  •  If dstByteOffset + copyByteLength is greater than the size of buf, generates an INVALID_VALUE error.
+          
  •  If srcOffset is greater than srcData.length (or srcData.byteLength for DataView), generates an INVALID_VALUE error.
+          
  •  If srcOffset + copyLength is greater than srcData.length (or srcData.byteLength for DataView), generates an INVALID_VALUE error.
+        

+        If any error is generated, no data is written to buf.
+      

+
+
+      
any getBufferParameter(GLenum target, GLenum pname)
+          
+          (OpenGL ES 3.0.4 §6.1.9,
+          man page)
+          
+      

+      

+        Return the value for the passed pname. In addition to supporting querying with the pname BUFFER_USAGE
+        as in WebGL 1.0, querying with the pname BUFFER_SIZE returns the buffer size as a value of type
+        GLsizeiptr.
+      

+      

+        
void copyBufferSubData(GLenum readTarget, GLenum writeTarget, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size)
+          
+            (OpenGL ES 3.0.4 §2.9.5,
+            man page)
+          
+        

+      

+      

+        Copy part of the data of the buffer bound to readTarget to the buffer bound to writeTarget.
+        See Copying Buffers for restrictions imposed by the WebGL 2 API.
+      

+      

+        

+          void getBufferSubData(GLenum target, GLintptr srcByteOffset,
+                                [AllowShared] ArrayBufferView dstBuffer,
+                                optional GLuint dstOffset = 0,
+                                optional GLuint length = 0)
+        

+      

+      

+        Reads back data from the bound WebGLBuffer into dstBuffer.
+        


+        Let buf be the buffer bound to target.
+        


+        If length is 0:
+        
    
+          
  •  If dstBuffer is a DataView, let copyLength be dstBuffer.byteLength - dstOffset; the typed elements in the text below are bytes.
+          
  •  Otherwise, let copyLength be dstBuffer.length - dstOffset.
+        

+        Otherwise, let copyLength be length.
+        


+        If dstBuffer is a DataView, let copyByteLength be copyLength; otherwise, let copyByteLength be copyLength * dstBuffer.BYTES_PER_ELEMENT.
+        


+        If dstBuffer is a DataView, let elementSize be 1; otherwise, let elementSize be dstBuffer.BYTES_PER_ELEMENT.
+        


+        If copyLength is greater than zero,
+        copy copyLength typed elements (each of size elementSize)
+        from buf into dstBuffer,
+        reading buf starting at byte index srcByteOffset and
+        writing into dstBuffer starting at element index dstOffset.
+        If copyLength is 0, no data is written to dstBuffer, but
+        this does not cause a GL error to be generated.
+        
    
+          
  • If no WebGLBuffer is bound to target,
+              generates an INVALID_OPERATION error.
+          
  • If target is TRANSFORM_FEEDBACK_BUFFER,
+              and any transform feedback object is currently active,
+              generates an INVALID_OPERATION error.
+          
  • If dstOffset is greater than dstBuffer.length
+              (or dstBuffer.byteLength in the case of DataView), generates
+              an INVALID_VALUE error.
+          
  • If dstOffset + copyLength is greater than dstBuffer.length
+              (or dstBuffer.byteLength in the case of DataView), generates
+              an INVALID_VALUE error.
+          
  • If srcByteOffset is less than zero,
+              generates an INVALID_VALUE error.
+          
  • If srcByteOffset + copyByteLength is greater than the size
+              of buf, generates an INVALID_OPERATION error.
+        

+        If any error is generated, no data is written to dstBuffer.
+        


+        If the buffer is written and read sequentially by other operations and getBufferSubData,
+        it is the responsibility of the WebGL API to ensure that data are accessed consistently. This applies
+        even if the buffer is currently bound to a transform feedback binding point.
+      

+    

+
+
+
+    
3.7.4 Framebuffer objects

+
+    

+      
[WebGLHandlesContextLoss] GLenum checkFramebufferStatus(GLenum target)
+          (OpenGL ES 3.0.4 §4.4.4, man page)
+      

+        
Only differences from checkFramebufferStatus in WebGL 1 are described here.

+        
target must be DRAW_FRAMEBUFFER, READ_FRAMEBUFFER or FRAMEBUFFER. FRAMEBUFFER is equivalent to DRAW_FRAMEBUFFER.

+        
Returns FRAMEBUFFER_UNSUPPORTED if depth and stencil attachments, if present, are not the same image. See Framebuffer Object Attachments for detailed discussion.

+        
Returns FRAMEBUFFER_INCOMPLETE_MULTISAMPLE if the values of RENDERBUFFER_SAMPLES are different among attached renderbuffers, or are non-zero if the attached images are a mix of renderbuffers and textures.

+        
Returns FRAMEBUFFER_INCOMPLETE_DIMENSIONS if attached images have different width, height, and depth (for 3D textures) or array size (for 2D array textures). See checkFramebufferStatus may return FRAMEBUFFER_INCOMPLETE_DIMENSIONS.

+        
Returns FRAMEBUFFER_UNSUPPORTED if the same image is attached to more than one color
+        attachment point. See Framebuffer color attachments.

+      

+
+      
any getFramebufferAttachmentParameter(GLenum target, GLenum attachment, GLenum pname)
+          (OpenGL ES 3.0.4 §6.1.13, similar to glGetFramebufferAttachmentParameteriv)
+      

+      

+          Return the value for the passed pname given the passed target and attachment. The type
+          returned is the natural type for the requested pname, as given in the following table:
+          
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+          
pnamereturned type
FRAMEBUFFER_ATTACHMENT_ALPHA_SIZEGLint
FRAMEBUFFER_ATTACHMENT_BLUE_SIZEGLint
FRAMEBUFFER_ATTACHMENT_COLOR_ENCODINGGLenum
FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPEGLenum
FRAMEBUFFER_ATTACHMENT_DEPTH_SIZEGLint
FRAMEBUFFER_ATTACHMENT_GREEN_SIZEGLint
FRAMEBUFFER_ATTACHMENT_OBJECT_NAMEWebGLRenderbuffer or WebGLTexture
FRAMEBUFFER_ATTACHMENT_OBJECT_TYPEGLenum
FRAMEBUFFER_ATTACHMENT_RED_SIZEGLint
FRAMEBUFFER_ATTACHMENT_STENCIL_SIZEGLint
FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACEGLint
FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYERGLint
FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVELGLint

+          
If pname is not in the table above, generates an INVALID_ENUM error.

+          
If an OpenGL error is generated, returns null.

+          
If attachment is DEPTH_STENCIL_ATTACHMENT and different images are attached to the depth and stencil attachment points, generates an INVALID_OPERATION error. See Framebuffer Object Attachments for detailed discussion.

+      

+      

+        
void blitFramebuffer(GLint srcX0, GLint srcY0, GLint srcX1, GLint srcY1, GLint dstX0, GLint dstY0, GLint dstX1, GLint dstY1, GLbitfield mask, GLenum filter)
+          
+            (OpenGL ES 3.0.4 §4.3.3,
+            man page)
+          
+        

+      

+      

+        Transfer a rectangle of pixel values from one region of the read framebuffer to another in the draw
+        framebuffer. If the value of SAMPLE_BUFFERS for the read framebuffer is one and the value of
+        SAMPLE_BUFFERS for the draw framebuffer is zero, the samples corresponding to each pixel location in
+        the source are converted to a single sample before being written to the destination.


+
+        For any source pixel lying outside the read framebuffer, the corresponding destination pixel remains
+        untouched.


+
+        When blitting to the color attachment of the WebGL context's default back buffer, a context
+        created with alpha:false is considered to have internal
+        format RGB8, while a context created with alpha:true is considered
+        to have internal format RGBA8.


+
+        If this function attempts to blit to a missing attachment of a complete framebuffer, nothing is
+        blitted to that attachment and no error is generated
+        per Drawing to a Missing Attachment.

+
+        If this function attempts to read from a missing attachment of a complete framebuffer, and at least one
+        draw buffer has an image to be blitted, an INVALID_OPERATION error is generated
+        per Reading from a Missing Attachment.
+      

+      

+        
void framebufferTextureLayer(GLenum target, GLenum attachment, WebGLTexture? texture, GLint level, GLint layer)
+          
+            (OpenGL ES 3.0.4 §4.4.2,
+            man page)
+          
+        

+      

+      

+        
void invalidateFramebuffer(GLenum target, sequence<GLenum> attachments)
+          
+            (OpenGL ES 3.0.4 §4.5,
+            man page)
+          
+        

+      

+      

+        Equivalent to calling invalidateSubFramebuffer with x and y
+        set to 0 and width and height set to the largest framebuffer object's
+        attachments' width and height.
+      

+      

+        
void invalidateSubFramebuffer (GLenum target, sequence<GLenum> attachments, GLint x, GLint y, GLsizei width, GLsizei height)
+          
+            (OpenGL ES 3.0.4 §4.5,
+            man page)
+          
+        

+      

+      

+        Signal the GL that it need not preserve all contents of a bound framebuffer object.
+      

+      

+        
void readBuffer(GLenum src)
+          
+            (OpenGL ES 3.0.4 §4.3.1,
+            man page)
+          
+        

+      

+      

+        Specify a color buffer of the read framebuffer as the read buffer.
+      

+    

+
+
+
+    
3.7.5 Renderbuffer objects

+
+    

+      

+        
any getInternalformatParameter(GLenum target, GLenum internalformat, GLenum pname)
+          
+            (OpenGL ES 3.0.4 §6.1.15,
+            man page)
+          
+        

+      

+      

+          Return the value for the passed pname given the passed target and internalformat. The type
+          returned is given in the following table:
+          
+              
+              
+          
pnamereturned type
SAMPLESInt32Array

+          
If pname is not in the table above, generates an INVALID_ENUM error.

+          
If an OpenGL error is generated, returns null.

+          
Each query for SAMPLES returns a new typed array object instance.

+      

+      
any getRenderbufferParameter(GLenum target, GLenum pname)
+          (OpenGL ES 2.0 §6.1.14, similar to glGetRenderbufferParameteriv)
+      

+      

+          Return the value for the passed pname given the passed target. The type returned is the natural
+          type for the requested pname, as given in the following table:
+          
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+          
pnamereturned type
RENDERBUFFER_WIDTHGLint
RENDERBUFFER_HEIGHTGLint
RENDERBUFFER_INTERNAL_FORMATGLenum
RENDERBUFFER_RED_SIZEGLint
RENDERBUFFER_GREEN_SIZEGLint
RENDERBUFFER_BLUE_SIZEGLint
RENDERBUFFER_ALPHA_SIZEGLint
RENDERBUFFER_DEPTH_SIZEGLint
RENDERBUFFER_SAMPLESGLint
RENDERBUFFER_STENCIL_SIZEGLint

+          
If pname is not in the table above, generates an INVALID_ENUM error.

+          
If an OpenGL error is generated, returns null.

+      

+      

+        
void renderbufferStorage(GLenum target, GLenum internalformat, GLsizei width, GLsizei height)
+          
+            (OpenGL ES 3.0.4 §4.4.2,
+            man page)
+          
+        

+      

+      

+        
Accepts internal formats from OpenGL ES 3.0 as detailed in the specification and man page.

+        
To be backward compatible with WebGL 1, also accepts internal format DEPTH_STENCIL, which should be mapped to DEPTH24_STENCIL8 by implementations.

+      

+      

+        
void renderbufferStorageMultisample(GLenum target, GLsizei samples, GLenum internalformat, GLsizei width, GLsizei height)
+          
+            (OpenGL ES 3.0.4 §4.4.2,
+            man page)
+          
+        

+      

+    

+
+
+
+    
3.7.6 Texture objects

+
+    

+        Texture objects provide storage and state for texturing operations. If no WebGLTexture is bound
+        (e.g., passing null or 0 to bindTexture) then attempts to modify or query the texture object shall
+        generate an INVALID_OPERATION error. This is indicated in the functions below in cases
+        where The OpenGL ES 3.0 specification allows the function to change the default texture.
+    

+
+    

+      
any getTexParameter(GLenum target, GLenum pname)
+          (OpenGL ES 3.0.4 §6.1.3, man page)
+      

+      

+          Return the value for the passed pname given the passed target. The type returned is the natural type for the
+          requested pname, as given in the following table:
+          
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+          
pnamereturned type
TEXTURE_BASE_LEVELGLint
TEXTURE_COMPARE_FUNCGLenum
TEXTURE_COMPARE_MODEGLenum
TEXTURE_IMMUTABLE_FORMATGLboolean
TEXTURE_IMMUTABLE_LEVELSGLuint
TEXTURE_MAG_FILTERGLenum
TEXTURE_MAX_LEVELGLint
TEXTURE_MAX_LODGLfloat
TEXTURE_MIN_FILTERGLenum
TEXTURE_MIN_LODGLfloat
TEXTURE_WRAP_RGLenum
TEXTURE_WRAP_SGLenum
TEXTURE_WRAP_TGLenum

+          
If pname is not in the table above, generates an INVALID_ENUM error.

+          
If an attempt is made to call this function with no WebGLTexture bound (see above), generates an
+          INVALID_OPERATION error.

+          
If an OpenGL error is generated, returns null.

+      

+      
void texParameterf(GLenum target, GLenum pname, GLfloat param)
+          (OpenGL ES 3.0.4 §3.8.7, man page)
+      

+      

+          Set the value for the passed pname given the passed target. pname is given in the following table:
+          
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+          
pname
TEXTURE_BASE_LEVEL
TEXTURE_COMPARE_FUNC
TEXTURE_COMPARE_MODE
TEXTURE_MAG_FILTER
TEXTURE_MAX_LEVEL
TEXTURE_MAX_LOD
TEXTURE_MIN_FILTER
TEXTURE_MIN_LOD
TEXTURE_WRAP_R
TEXTURE_WRAP_S
TEXTURE_WRAP_T

+          
If pname is not in the table above, generates an INVALID_ENUM error.

+          
If an attempt is made to call this function with no WebGLTexture bound (see above), generates an
+          INVALID_OPERATION error.

+      

+      
void texParameteri(GLenum target, GLenum pname, GLint param)
+          (OpenGL ES 3.0.4 §3.8.7, man page)
+      

+      

+          
Set the value for the passed pname given the passed target. pname is this same with that of texParameterf, as given in the table above.

+          
If pname is not in the table above, generates an INVALID_ENUM error.

+          
If an attempt is made to call this function with no WebGLTexture bound (see above), generates an
+          INVALID_OPERATION error.

+      

+      

+        
void texStorage2D(GLenum target, GLsizei levels, GLenum internalformat, GLsizei width, GLsizei height)
+          
+            (OpenGL ES 3.0.4 §3.8.4,
+            man page)
+          
+        

+      

+      

+        Specify all the levels of a two-dimensional or cube-map texture at the same time. 


+
+        The image contents are set as if a buffer of sufficient size initialized to 0 would be passed to
+        each texImage2D call in the pseudocode in The OpenGL ES 3.0 specification section 3.8.4
+        (OpenGL ES 3.0.4 §3.8.4).
+
+        
texStorage2D should be considered a preferred alternative to
+        texImage2D. It may have lower memory costs than texImage2D in some
+        implementations.

+      

+      

+        
void texStorage3D(GLenum target, GLsizei levels, GLenum internalformat, GLsizei width, GLsizei height, GLsizei depth)
+          
+            (OpenGL ES 3.0.4 §3.8.4,
+            man page)
+          
+        

+      

+      

+        Specify all the levels of a three-dimensional texture or two-dimensional array texture. 


+
+        The image contents are set as if a buffer of sufficient size initialized to 0 would be passed to
+        each texImage3D call in the pseudocode in The OpenGL ES 3.0 specification section 3.8.4
+        (OpenGL ES 3.0.4 §3.8.4).
+      

+
+      

+        void texImage2D(GLenum target, GLint level, GLint internalformat, GLsizei width,
+                        GLsizei height, GLint border, GLenum format, GLenum type,
+                        [AllowShared] ArrayBufferView srcData, GLuint srcOffset)
+        (OpenGL ES 3.0.4 §3.8.4, man page)
+      

+      

+        
Only differences from texImage2D in WebGL 1 are described here. 

+        
If a WebGLBuffer is bound to the PIXEL_UNPACK_BUFFER target, generates an INVALID_OPERATION error.

+        
Sized internal formats are supported in WebGL 2 and internalformat is no longer required to be the same as format. Instead, the combination of internalformat, format, and type must be listed in Table 1 or 2 from man page.

+        
If type is specified as FLOAT_32_UNSIGNED_INT_24_8_REV,
+           srcData must be null; otherwise, generates an INVALID_OPERATION
+           error.
+        
The type of srcData must match the type according to the following
+           table; otherwise, generates an INVALID_OPERATION error:
+        

+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+        
type of srcDatatype
Int8ArrayBYTE
Uint8ArrayUNSIGNED_BYTE
Int16ArraySHORT
Uint16ArrayUNSIGNED_SHORT
Uint16ArrayUNSIGNED_SHORT_5_6_5
Uint16ArrayUNSIGNED_SHORT_5_5_5_1
Uint16ArrayUNSIGNED_SHORT_4_4_4_4
Int32ArrayINT
Uint32ArrayUNSIGNED_INT
Uint32ArrayUNSIGNED_INT_5_9_9_9_REV
Uint32ArrayUNSIGNED_INT_2_10_10_10_REV
Uint32ArrayUNSIGNED_INT_10F_11F_11F_REV
Uint32ArrayUNSIGNED_INT_24_8
Uint16ArrayHALF_FLOAT
Float32ArrayFLOAT

+        

+            If pixel store parameter constraints are not met,
+            generates an INVALID_OPERATION error.
+        

+        
Reading from srcData begins srcOffset elements into
+           srcData. (Elements are bytes for Uint8Array, int32s for Int32Array, etc.)
+        
If there's not enough data in srcData starting at srcOffset,
+           generate INVALID_OPERATION.
+      

+
+      

+        [throws]
+        void texImage2D(GLenum target, GLint level, GLint internalformat, GLsizei width,
+                        GLsizei height, GLint border, GLenum format, GLenum type,
+                        TexImageSource source) // May throw DOMException
+        (OpenGL ES 3.0.4 §3.8.4, man page)
+      

+      

+        
Only differences from texImage2D in WebGL 1 are described here. 

+        
Uploading subregions of elements is detailed in Pixel
+           store parameters for uploads from TexImageSource.
+        
If a WebGLBuffer is bound to the PIXEL_UNPACK_BUFFER target, generates an INVALID_OPERATION error.

+        
Sized internal formats are supported in WebGL 2 and internalformat is no longer required to be the same as format. Instead, the combination of internalformat, format, and type must be listed in the following table:

+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
Internal FormatFormatType
RGBRGBUNSIGNED_BYTE
UNSIGNED_SHORT_5_6_5
RGBARGBAUNSIGNED_BYTE,
UNSIGNED_SHORT_4_4_4_4
UNSIGNED_SHORT_5_5_5_1
LUMINANCE_ALPHALUMINANCE_ALPHAUNSIGNED_BYTE
LUMINANCELUMINANCEUNSIGNED_BYTE
ALPHAALPHAUNSIGNED_BYTE
R8REDUNSIGNED_BYTE
R16FREDHALF_FLOAT
FLOAT
R32FREDFLOAT
R8UIRED_INTEGERUNSIGNED_BYTE
RG8RGUNSIGNED_BYTE
RG16FRGHALF_FLOAT
FLOAT
RG32FRGFLOAT
RG8UIRG_INTEGERUNSIGNED_BYTE
RGB8RGBUNSIGNED_BYTE
SRGB8RGBUNSIGNED_BYTE
RGB565RGBUNSIGNED_BYTE
UNSIGNED_SHORT_5_6_5
R11F_G11F_B10FRGBUNSIGNED_INT_10F_11F_11F_REV
HALF_FLOAT
FLOAT
RGB9_E5RGBHALF_FLOAT
FLOAT
RGB16FRGBHALF_FLOAT
FLOAT
RGB32FRGBFLOAT
RGB8UIRGB_INTEGERUNSIGNED_BYTE
RGBA8RGBAUNSIGNED_BYTE
SRGB8_ALPHA8RGBAUNSIGNED_BYTE
RGB5_A1RGBAUNSIGNED_BYTE
UNSIGNED_SHORT_5_5_5_1
RGB10_A2RGBAUNSIGNED_INT_2_10_10_10_REV
RGBA4RGBAUNSIGNED_BYTE
UNSIGNED_SHORT_4_4_4_4
RGBA16FRGBAHALF_FLOAT
FLOAT
RGBA32FRGBAFLOAT
RGBA8UIRGBA_INTEGERUNSIGNED_BYTE

+        
When the data source is a DOM element (HTMLImageElement, HTMLCanvasElement, or HTMLVideoElement), or is an ImageBitmap or ImageData object, commonly each channel's representation is an unsigned integer type of at least 8 bits. Converting such representation to signed integers or unsigned integers with more bits is not clearly defined. For example, when converting RGBA8 to RGBA16UI,  it is unclear whether or not the intention is to scale up values to the full range of a 16-bit unsigned integer. Therefore, only converting to unsigned integer of at most 8 bits, half float, or float is allowed.

+      

+
+      
void texImage2D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height, GLint border, GLenum format, GLenum type, GLintptr offset) (OpenGL ES 3.0.4 §3.8.4, man page)
+      

+      

+        
Upload data to the currently bound WebGLTexture from the WebGLBuffer bound to the PIXEL_UNPACK_BUFFER target.

+        
offset is the byte offset into the WebGLBuffer's data store; generates an INVALID_VALUE if it's less than 0.

+        
The combination of format, type, and WebGLTexture's internal format must be listed in Table 1 or 2 from man page.

+        
If an attempt is made to call the function with no WebGLTexture bound, generates an INVALID_OPERATION error.

+        
If no WebGLBuffer is bound to the PIXEL_UNPACK_BUFFER target, generates an INVALID_OPERATION error.

+        

+            If pixel store parameter constraints are not met,
+            generates an INVALID_OPERATION error.
+        

+      

+
+      

+        void texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                               GLsizei width, GLsizei height, GLenum format, GLenum type,
+                               [AllowShared] ArrayBufferView srcData, GLuint srcOffset)
+        (OpenGL ES 3.0.4 §3.8.5, man page)
+      

+      

+        
Only differences from texSubImage2D in WebGL 1 are described here. 

+        
If a WebGLBuffer is bound to the PIXEL_UNPACK_BUFFER target, generates an INVALID_OPERATION error.

+        
The combination of format, type, and WebGLTexture's internal format must be listed in Table 1 or 2 from man page.

+        
The type of srcData must match the type according to the  above table; otherwise, generates an
+           INVALID_OPERATION error.

+        
See Pixel Storage Parameters for WebGL-specific pixel storage parameters that affect the behavior of this function.

+        

+            If  pixel store parameter constraints are not met,
+            generates an INVALID_OPERATION error.
+        

+        
Reading from srcData begins srcOffset elements into
+           srcData. (Elements are bytes for Uint8Array, int32s for Int32Array, etc.)
+        
If there's not enough data in srcData starting at srcOffset,
+           generate INVALID_OPERATION.
+      

+
+
+      

+        void texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                               GLsizei width, GLsizei height, GLenum format, GLenum type,
+                               TexImageSource source) // May throw DOMException
+        (OpenGL ES 3.0.4 §3.8.5, man page)
+      

+      

+        
Only differences from texSubImage2D in WebGL 1 are described here. 

+        
Uploading subregions of elements is detailed in Pixel
+           store parameters for uploads from TexImageSource.
+        
If a WebGLBuffer is bound to the PIXEL_UNPACK_BUFFER target, generates an INVALID_OPERATION error.

+        
The combination of format, type, and WebGLTexture's internal format must be listed in this table.

+      

+
+      

+        void texSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                               GLsizei width, GLsizei height, GLenum format, GLenum type,
+                               GLintptr offset)
+        (OpenGL ES 3.0.4 §3.8.5, man page)
+      

+      

+        
Updates a sub-rectangle of the currently bound WebGLTexture with data from the WebGLBuffer bound to PIXEL_UNPACK_BUFFER target.

+        
offset is the byte offset into the WebGLBuffer's data store; generates an INVALID_VALUE error if it's less than 0.

+        
If an attempt is made to call the function with no WebGLTexture bound, generates an INVALID_OPERATION error.

+        
If no WebGLBuffer is bound to the PIXEL_UNPACK_BUFFER target, generates an INVALID_OPERATION error.

+        

+            If  pixel store parameter constraints are not met,
+            generates an INVALID_OPERATION error.
+        

+      

+
+      

+        
void texImage3D(GLenum target, GLint level, GLint internalformat, GLsizei width,
+                           GLsizei height, GLsizei depth, GLint border, GLenum format, GLenum type,
+                           [AllowShared] ArrayBufferView? srcData)

+        
void texImage3D(GLenum target, GLint level, GLint internalformat, GLsizei width,
+                           GLsizei height, GLsizei depth, GLint border, GLenum format, GLenum type,
+                           [AllowShared] ArrayBufferView srcData, GLuint srcOffset)
+          (OpenGL ES 3.0.4 §3.8.4, man page)
+        

+      

+      

+        
Allocates and initializes the specified mipmap level of a three-dimensional or two-dimensional array texture. 

+        
If a WebGLBuffer is bound to the PIXEL_UNPACK_BUFFER target, generates an INVALID_OPERATION error.

+        
If srcData is null, a buffer of sufficient size initialized to 0 is passed. 

+        
The combination of internalformat, format, and type must be listed in Table 1 or 2 from man page.

+        
If type is specified as FLOAT_32_UNSIGNED_INT_24_8_REV,
+           srcData must be null; otherwise, generates an INVALID_OPERATION
+           error.
+        
If srcData is non-null, the type of srcData must match the type
+           according to the above table; otherwise,
+           generate an INVALID_OPERATION error.
+        
If an attempt is made to call this function with no WebGLTexture bound (see above), generates an INVALID_OPERATION error.

+        
See Pixel Storage Parameters for WebGL-specific pixel storage parameters that affect the behavior of this function. 

+        

+            If  pixel store parameter constraints are not met,
+            generates an INVALID_OPERATION error.
+        

+        
Reading from srcData begins srcOffset elements into
+           srcData. (Elements are bytes for Uint8Array, int32s for Int32Array, etc.)
+        
If there's not enough data in srcData starting at srcOffset,
+           generate INVALID_OPERATION.
+
+        
It is recommended to use texStorage3D instead of texImage3D to allocate three-dimensional textures. texImage3D may impose a higher memory cost compared to texStorage3D in some implementations.

+      

+
+      

+        

+          void texImage3D(GLenum target, GLint level, GLenum internalformat, GLsizei width,
+                          GLsizei height, GLsizei depth, GLint border, GLenum format, GLenum type,
+                          TexImageSource source) // May throw DOMException
+          (OpenGL ES 3.0.4 §3.8.4, man page)
+        

+      

+      

+        
Update a rectangular subregion of the currently bound WebGLTexture. 

+        
Uploading subregions of elements is detailed in Pixel
+           store parameters for uploads from TexImageSource.
+        
See texImage2D for the interpretation of the format and type arguments, and notes on the UNPACK_PREMULTIPLY_ALPHA_WEBGL pixel storage parameter. 

+        
See Pixel Storage Parameters for WebGL-specific pixel storage parameters that affect the behavior of this function when it is called with any argument type other than ImageBitmap.

+        
The first pixel transferred from the source to the WebGL implementation corresponds to the upper left corner of the source. This behavior is modified by the UNPACK_FLIP_Y_WEBGL pixel storage parameter, except for ImageBitmap arguments, as described in the abovementioned section. 

+        
The combination of format, type, and WebGLTexture's internal format must be listed in this table.

+        
If an attempt is made to call this function with no WebGLTexture bound (see above), generates an INVALID_OPERATION error.

+        
If a WebGLBuffer is bound to the PIXEL_UNPACK_BUFFER target, generates an INVALID_OPERATION error.

+        
If this function is called with an ImageData whose data attribute has been neutered, an INVALID_VALUE error is generated. 

+        
If this function is called with an ImageBitmap that has been neutered, an INVALID_VALUE error is generated. 

+        
If this function is called with an HTMLImageElement or HTMLVideoElement whose origin differs from the origin of the containing Document, or with an HTMLCanvasElement or ImageBitmap whose bitmap's origin-clean flag is set to false, a SECURITY_ERR exception must be thrown. See Origin Restrictions.

+      

+
+      
void texImage3D(GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLenum format, GLenum type, GLintptr offset)
+        (OpenGL ES 3.0.4 §3.8.4, man page)
+      

+      

+        
Upload data to the currently bound WebGLTexture from the WebGLBuffer bound to the PIXEL_UNPACK_BUFFER target.

+        
offset is the byte offset into the WebGLBuffer's data store; generates an INVALID_VALUE error if it's less than 0.

+        
If an attempt is made to call the function with no WebGLTexture bound, generates an INVALID_OPERATION error.

+        
If no WebGLBuffer is bound to the PIXEL_UNPACK_BUFFER target, generates an INVALID_OPERATION error.

+        

+            If pixel store parameter constraints are not met,
+            generates an INVALID_OPERATION error.
+        

+      

+
+      

+        

+          void texSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                             GLint zoffset, GLsizei width, GLsizei height, GLsizei depth,
+                             GLenum format, GLenum type, [AllowShared] ArrayBufferView? srcData,
+                             optional GLuint srcOffset = 0)
+          
+            (OpenGL ES 3.0.4 §3.8.5,
+            man page)
+          
+        

+      

+      

+        
Update a rectangular subregion of the currently bound WebGLTexture. 

+        
If an attempt is made to call this function with no WebGLTexture bound (see above), generates an INVALID_OPERATION error. 

+        
If a WebGLBuffer is bound to the PIXEL_UNPACK_BUFFER target, generates an INVALID_OPERATION error.

+        
The combination of format, type, and WebGLTexture's internal format must be listed in Table 1 or 2 from man page.

+        
If type is FLOAT_32_UNSIGNED_INT_24_8_REV, generates an INVALID_ENUM error.

+        
The type of srcData must match the type according to the above table; otherwise, generates an
+           INVALID_OPERATION error.
+        
If srcData is non-null but its size is less than what is required by the specified width, height, depth, format, type, and pixel storage parameters, generates an INVALID_OPERATION error. 

+        
See Pixel Storage Parameters for WebGL-specific pixel storage parameters that affect the behavior of this function.

+        

+            If  pixel store parameter constraints are not met,
+            generates an INVALID_OPERATION error.
+        

+        
Reading from srcData begins srcOffset elements into
+           srcData. (Elements are bytes for Uint8Array, int32s for Int32Array, etc.)
+        
If there's not enough data in srcData starting at srcOffset,
+           generate INVALID_OPERATION.
+      

+      

+        

+          void texSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                             GLint zoffset, GLsizei width, GLsizei height, GLsizei depth,
+                             GLenum format, GLenum type,
+                             TexImageSource source) // May throw DOMException
+          
+            (OpenGL ES 3.0.4 §3.8.5,
+            man page)
+          
+        

+      

+      

+        
Update a rectangular subregion of the currently bound WebGLTexture. 

+        
Uploading subregions of elements is detailed in Pixel
+           store parameters for uploads from TexImageSource.
+        
See texImage2D for the interpretation of the format and type arguments, and notes on the UNPACK_PREMULTIPLY_ALPHA_WEBGL pixel storage parameter. 

+        
See Pixel Storage Parameters for WebGL-specific pixel storage parameters that affect the behavior of this function when it is called with any argument type other than ImageBitmap.

+        
The first pixel transferred from the source to the WebGL implementation corresponds to the upper left corner of the source. This behavior is modified by the UNPACK_FLIP_Y_WEBGL pixel storage parameter, except for ImageBitmap arguments, as described in the abovementioned section. 

+        
The combination of format, type, and WebGLTexture's internal format must be listed in this table.

+        
If an attempt is made to call this function with no WebGLTexture bound (see above), generates an INVALID_OPERATION error.

+        
If a WebGLBuffer is bound to the PIXEL_UNPACK_BUFFER target, generates an INVALID_OPERATION error.

+        
If this function is called with an ImageData whose data attribute has been neutered, an INVALID_VALUE error is generated. 

+        
If this function is called with an ImageBitmap that has been neutered, an INVALID_VALUE error is generated. 

+        
If this function is called with an HTMLImageElement or HTMLVideoElement whose origin differs from the origin of the containing Document, or with an HTMLCanvasElement or ImageBitmap whose bitmap's origin-clean flag is set to false, a SECURITY_ERR exception must be thrown. See Origin Restrictions.

+      

+
+      

+        
void texSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type, GLintptr offset)
+          
+            (OpenGL ES 3.0.4 §3.8.5,
+            man page)
+          
+        

+      

+      

+        
Updates a sub-rectangle of the currently bound WebGLTexture with data from the WebGLBuffer bound to PIXEL_UNPACK_BUFFER target.

+        
offset is the byte offset into the WebGLBuffer's data store; generates an INVALID_VALUE error if it's less than 0.

+        
If an attempt is made to call the function with no WebGLTexture bound, generates an INVALID_OPERATION error.

+        
If no WebGLBuffer is bound to the PIXEL_UNPACK_BUFFER target, generates an INVALID_OPERATION error.

+        

+            If pixel store parameter constraints are not met,
+            generates an INVALID_OPERATION error.
+        

+      

+
+      

+        
void copyTexSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLint x, GLint y, GLsizei width, GLsizei height)
+          
+            (OpenGL ES 3.0.4 §3.8.5,
+            man page)
+          
+        

+      

+      

+        If an attempt is made to call this function with no WebGLTexture bound (see above), an
+        INVALID_OPERATION error is generated. 


+
+        For any pixel lying outside the framebuffer, the corresponding destination pixel remains
+        untouched; see Reading Pixels Outside
+        the Framebuffer. 


+
+        If this function attempts to read from a missing attachment of a complete framebuffer,
+        an INVALID_OPERATION error is generated
+        per Reading from a Missing Attachment.
+      

+
+      

+        

+          void compressedTexImage2D(GLenum target, GLint level, GLenum internalformat,
+                                    GLsizei width, GLsizei height, GLint border,
+                                    [AllowShared] ArrayBufferView srcData,
+                                    optional GLuint srcOffset = 0,
+                                    optional GLuint srcLengthOverride = 0)
+          
+            (OpenGL ES 3.0.4 §3.8.6,
+            man page)
+          
+        

+      

+        
Reading from srcData begins srcOffset elements into
+           srcData. (Elements are bytes for Uint8Array, int32s for Int32Array, etc.)

+        
If srcOffset > srcData.length, generates an INVALID_VALUE error.

+        
srcLengthOverride defaults to srcData.length - srcOffset.

+        
If there's not enough data in srcData starting at srcOffset, or
+           if the amount of data passed in is not consistent with the format, dimensions, and
+           contents of the compressed image, generates an INVALID_VALUE error.

+      

+      
+      

+        

+          void compressedTexSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                                       GLsizei width, GLsizei height, GLenum format,
+                                       [AllowShared] ArrayBufferView srcData,
+                                       optional GLuint srcOffset = 0,
+                                       optional GLuint srcLengthOverride = 0)
+          
+            (OpenGL ES 3.0.4 §3.8.6,
+            man page)
+          
+        

+      

+        
Reading from srcData begins srcOffset elements into
+           srcData. (Elements are bytes for Uint8Array, int32s for Int32Array, etc.)
+        
If srcOffset > srcData.length, generates an INVALID_VALUE error.

+        
srcLengthOverride defaults to srcData.length - srcOffset.

+        
If there's not enough data in srcData starting at srcOffset, or
+           if the amount of data passed in is not consistent with the format, dimensions, and
+           contents of the compressed image, generates an INVALID_VALUE error.

+      

+      
+
+      

+        

+          void compressedTexImage3D(GLenum target, GLint level, GLenum internalformat,
+                                    GLsizei width, GLsizei height, GLsizei depth, GLint border,
+                                    [AllowShared] ArrayBufferView srcData,
+                                    optional GLuint srcOffset = 0,
+                                    optional GLuint srcLengthOverride = 0)
+          
+            (OpenGL ES 3.0.4 §3.8.6,
+            man page)
+          
+        

+      

+        
Reading from srcData begins srcOffset elements into
+           srcData. (Elements are bytes for Uint8Array, int32s for Int32Array, etc.)
+        
If srcOffset > srcData.length, generates an INVALID_VALUE error.

+        
srcLengthOverride defaults to srcData.length - srcOffset.

+        
If there's not enough data in srcData starting at srcOffset, or
+           if the amount of data passed in is not consistent with the format, dimensions, and
+           contents of the compressed image, generates an INVALID_VALUE error.

+      

+      
+      

+        

+          void compressedTexSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset,
+                                       GLint zoffset, GLsizei width, GLsizei height, GLsizei depth,
+                                       GLenum format, [AllowShared] ArrayBufferView srcData,
+                                       optional GLuint srcOffset = 0,
+                                       optional GLuint srcLengthOverride = 0)
+          
+            (OpenGL ES 3.0.4 §3.8.6,
+            man page)
+          
+        

+      

+        
Reading from srcData begins srcOffset elements into
+           srcData. (Elements are bytes for Uint8Array, int32s for Int32Array, etc.)
+        
If srcOffset > srcData.length, generates an INVALID_VALUE error.

+        
srcLengthOverride defaults to srcData.length - srcOffset.

+        
If there's not enough data in srcData starting at srcOffset, or
+           if the amount of data passed in is not consistent with the format, dimensions, and
+           contents of the compressed image, generates an INVALID_VALUE error.

+      

+      
+      
This section applies to the above four entry points.

+      

+        
If an attempt is made to call these functions with no WebGLTexture bound (see above), generates an INVALID_OPERATION error.

+        
If a WebGLBuffer is bound to the PIXEL_UNPACK_BUFFER target, generates an INVALID_OPERATION error.

+        
The ETC2 and EAC texture formats defined in OpenGL ES 3.0 are not available in WebGL 2.0.
+      

+
+      

+        
void compressedTexImage2D(GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLint border, GLsizei imageSize, GLintptr offset)
+          
+            (OpenGL ES 3.0.4 §3.8.6,
+            man page)
+          
+        

+      

+      

+        
void compressedTexSubImage2D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width, GLsizei height, GLenum format, GLsizei imageSize, GLintptr offset)
+          
+            (OpenGL ES 3.0.4 §3.8.6,
+            man page)
+          
+        

+      

+      

+        
void compressedTexImage3D(GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLsizei imageSize, GLintptr offset)
+          
+            (OpenGL ES 3.0.4 §3.8.6,
+            man page)
+          
+        

+      

+      

+        
void compressedTexSubImage3D(GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLsizei imageSize, GLintptr offset)
+          
+            (OpenGL ES 3.0.4 §3.8.6,
+            man page)
+          
+        

+      

+      
This section applies to the above four entry points.

+      

+        
If an attempt is made to call these functions with no WebGLTexture bound (see above), generates an INVALID_OPERATION error.

+        
If no WebGLBuffer is bound to the PIXEL_UNPACK_BUFFER target, generates an INVALID_OPERATION error.

+        
offset is the byte offset into the WebGLBuffer's data store; generates an INVALID_VALUE error if it's less than 0.

+        
The ETC2 and EAC texture formats defined in OpenGL ES 3.0 are not available in WebGL 2.0.
+      

+    

+
+
+
+    
3.7.7 Programs and Shaders

+
+    

+      

+        
[WebGLHandlesContextLoss] GLint getFragDataLocation(WebGLProgram program, DOMString name)
+          
+            (OpenGL ES 3.0.4 §3.9.2,
+            man page)
+          
+        

+      

+      
any getProgramParameter(WebGLProgram? program, GLenum pname)
+          (OpenGL ES 3.0.4 §6.1.12, man page)
+      

+      

+          Return the value for the passed pname given the passed program. The type returned is the natural
+          type for the requested pname, as given in the following table:
+          
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+          
pnamereturned type
DELETE_STATUSGLboolean
LINK_STATUSGLboolean
VALIDATE_STATUSGLboolean
ATTACHED_SHADERSGLint
ACTIVE_ATTRIBUTESGLint
ACTIVE_UNIFORMSGLint
TRANSFORM_FEEDBACK_BUFFER_MODEGLenum
TRANSFORM_FEEDBACK_VARYINGSGLint
ACTIVE_UNIFORM_BLOCKSGLint

+          
If pname is not in the table above, generates an INVALID_ENUM error and returns null.

+          
Returns null if any OpenGL errors are generated during the execution of this
+          function.

+      

+    

+
+
+
+    
3.7.8 Uniforms and attributes

+
+    

+      

+        any getUniform(WebGLProgram program, WebGLUniformLocation location)
+          
+            (OpenGL ES 3.0.4 §6.1.12,
+            man page)
+          
+      

+      

+        Return the uniform value at the passed location in the passed program. The type returned is dependent
+        on the uniform type. The types returned for the new uniform types in WebGL 2 are given in the
+        following table:
+        
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+        
uniform typereturned type
uintGLuint
uvec2Uint32Array (with 2 elements)
uvec3Uint32Array (with 3 elements)
uvec4Uint32Array (with 4 elements)
mat2x3Float32Array (with 6 elements)
mat2x4Float32Array (with 8 elements)
mat3x2Float32Array (with 6 elements)
mat3x4Float32Array (with 12 elements)
mat4x2Float32Array (with 8 elements)
mat4x3Float32Array (with 12 elements)
any sampler typeGLint


+        
The types returned for the uniform types shared with WebGL 1 are the same as in WebGL 1.

+      

+      

+        
void uniform[1234]ui(WebGLUniformLocation? location, ...)

+        
void uniform[1234]uiv(WebGLUniformLocation? location, ...)

+        
void uniformMatrix[234]x[234]fv(WebGLUniformLocation? location, ...)
+          
+            (OpenGL ES 3.0.4 §2.11.6,
+            man page)
+          
+        

+      

+      

+        Each of the uniform* functions above sets the specified uniform or uniforms to the values
+        provided. If the passed location is not null and was not obtained from the
+        currently used program via an earlier call to getUniformLocation,
+        an INVALID_OPERATION error will be generated. If the passed
+        location is null, the data passed in will be silently ignored and no uniform
+        variables will be changed.
+        


+        If the array passed to any of the vector forms (those ending in v) has an
+        invalid length, an INVALID_VALUE error will be generated. The length is invalid
+        if it is too short for or is not an integer multiple of the assigned type.
+        
In overloads with a srcLength arg:
+          
    
+            
  • If srcLength is 0, it defaults to
+                data.length - srcOffset.
+            
  • If srcOffset + srcLength is longer than
+                data.length, generate INVALID_VALUE.
+          

+        

+      

+      
void vertexAttribI4[u]i(GLuint index, ...)

+          
void vertexAttribI4[u]iv(GLuint index, ...)
+          
+            (OpenGL ES 3.0.4 §2.7,
+            man page)
+          
+      

+      

+        Sets the vertex attribute at the passed index to the given constant integer value. Values set via the
+        vertexAttrib are guaranteed to be returned from the getVertexAttrib function
+        with the CURRENT_VERTEX_ATTRIB param, even if there have been intervening calls to
+        drawArrays or drawElements.
+      

+      

+        
void vertexAttribIPointer(GLuint index, GLint size, GLenum type, GLsizei stride, GLintptr offset)
+          
+            (OpenGL ES 3.0.4 §2.8,
+            man page)
+          
+        

+      

+      

+        Assign the WebGLBuffer object currently bound to the ARRAY_BUFFER target to the vertex
+        attribute at the passed index. Values are always left as integer values. Size is number of
+        components per attribute. Stride and offset are in units of bytes. Passed stride and offset
+        must be appropriate for the passed type and size or an INVALID_OPERATION error
+        will be generated; see Buffer Offset and Stride
+        Requirements. If offset is negative, an INVALID_VALUE error will be
+        generated. If no WebGLBuffer is bound to the ARRAY_BUFFER target,
+        an INVALID_OPERATION error will be generated. In WebGL, the maximum supported
+        stride is 255; see  Vertex Attribute Data Stride.
+      

+      
any getVertexAttrib(GLuint index, GLenum pname)
+          (OpenGL ES 3.0.4 §6.1.12, man page)
+      

+      

+          Return the information requested in pname about the vertex attribute at the passed index. The
+          type returned is dependent on the information requested, as shown in the following table:
+          
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+          
pnamereturned type
VERTEX_ATTRIB_ARRAY_BUFFER_BINDINGWebGLBuffer
VERTEX_ATTRIB_ARRAY_ENABLEDGLboolean
VERTEX_ATTRIB_ARRAY_SIZEGLint
VERTEX_ATTRIB_ARRAY_STRIDEGLint
VERTEX_ATTRIB_ARRAY_TYPEGLenum
VERTEX_ATTRIB_ARRAY_NORMALIZEDGLboolean
CURRENT_VERTEX_ATTRIBOne of Float32Array, Int32Array or Uint32Array (each with 4 elements)
VERTEX_ATTRIB_ARRAY_INTEGERGLboolean
VERTEX_ATTRIB_ARRAY_DIVISORGLint

+          
For CURRENT_VERTEX_ATTRIB, the return type is dictated by the most recent call
+            to the vertexAttrib family of functions for the given index. That is, if
+            vertexAttribI4i* was used, the return type will be Int32Array; If vertexAttribI4ui*
+            was used, the return type will be Uint32Array; Otherwise, Float32Array.
+          

+          
All queries returning sequences or typed arrays return a new object each time.

+          
If pname is not in the table above, generates an INVALID_ENUM error.

+          
If an OpenGL error is generated, returns null.

+      

+    

+
+
+
+    
3.7.9 Writing to the drawing buffer

+
+    

+      

+        
void clear(GLbitfield mask)
+          
+            (OpenGL ES 3.0.4 §4.2.3,
+            man page)
+          
+        

+      

+      

+        Clear buffers to preset values. If an integer color buffer is among the buffers that would be
+        cleared, an INVALID_OPERATION error is generated and nothing is cleared.
+      

+      

+        
void vertexAttribDivisor(GLuint index, GLuint divisor)
+          
+            (OpenGL ES 3.0.4 §2.8,
+            man page)
+          
+        

+      

+      

+        Set the rate at which the vertex attribute identified by index advances when drawing.
+      

+      

+        
void drawArrays(GLenum mode, GLint first, GLsizei count)
+          
+            (OpenGL ES 3.0.4 §2.9.3,
+            man page)
+          
+        

+      

+      

+        
void drawElements(GLenum mode, GLsizei count, GLenum type, GLintptr offset)
+          
+            (OpenGL ES 3.0.4 §2.9.3,
+            man page)
+          
+        

+      

+      

+        
void drawArraysInstanced(GLenum mode, GLint first, GLsizei count, GLsizei instanceCount)
+          
+            (OpenGL ES 3.0.4 §2.9.3,
+            man page)
+          
+        

+      

+      

+        Draw instanceCount instances of geometry using the currently enabled vertex attributes.
+        Vertex attributes which have a non-zero divisor advance once every divisor instances.


+      

+      

+        
void drawElementsInstanced(GLenum mode, GLsizei count, GLenum type, GLintptr offset, GLsizei instanceCount)
+          
+            (OpenGL ES 3.0.4 §2.9.3,
+            man page)
+          
+        

+      

+      

+        Draw instanceCount instances of geometry using the currently bound element array buffer.
+        Vertex attributes which have a non-zero divisor advance once every divisor instances.


+      

+      

+        
void drawRangeElements(GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, GLintptr offset)
+          
+            (OpenGL ES 3.0.4 §2.9.3,
+            man page)
+          
+        

+      

+      

+        Draw using the currently bound element array buffer. All error conditions specified for
+        drawElements in the section Writing
+        to the drawing buffer of the WebGL 1.0 specification apply.


+
+        In addition, if indices used to draw are outside the range of [start, end], an imeplementation
+        can either guarantee the behaviors defined in Out-of-Range
+        Array Accesses, or simply discard the arguments start and end and call drawElements
+        instead. In either situation, no GL errors should be generated for this cause.
+      

+    

+
+    

+        During calls to drawElements, drawArrays, drawRangeElements and their
+        instanced variants, WebGL 2 performs additional error checking beyond that specified in OpenGL ES 3.0:
+        

+    

+
+
+
+    
3.7.10 Reading back pixels

+
+    
Pixels in the current framebuffer can be read back into an ArrayBufferView object or a
+       WebGLBuffer bound to the PIXEL_PACK_BUFFER target.
+    
Only differences from Reading back pixels in WebGL 1 are described here.

+    

+        

+          void readPixels(GLint x, GLint y, GLsizei width, GLsizei height, GLenum format,
+                          GLenum type, [AllowShared] ArrayBufferView dstData, GLuint dstOffset)
+          (OpenGL ES 3.0 §4.3.2, man page)
+        

+        

+          
If a WebGLBuffer is bound to the PIXEL_PACK_BUFFER target, generates an INVALID_OPERATION error.

+          

+              If pixel store parameter constraints are not met,
+              generates an INVALID_OPERATION error.
+          

+          
If dstData doesn't have enough space for the read operation starting at
+             dstOffset, generate INVALID_OPERATION.
+        

+
+        
void readPixels(GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type, GLintptr offset)
+            (OpenGL ES 3.0 §4.3.2, man page)
+        

+        

+          
If no WebGLBuffer is bound to the PIXEL_PACK_BUFFER target, generates an
+             INVALID_OPERATION error.
+          
offset is the byte offset into the WebGLBuffer's data store; generates an
+             INVALID_VALUE error if it's less than 0. If the remainder of the
+             WebGLBuffer's data store is not large enough to retrieve all of the pixels in the
+             specified rectangle taking into account pixel store modes, generates an
+             INVALID_OPERATION.
+        

+    

+
+
+
+    
3.7.11 Multiple render targets

+
+    

+      

+        
void drawBuffers(sequence<GLenum> buffers)
+          
+            (OpenGL ES 3.0.4 §4.2.1,
+            man page)
+          
+        

+      

+      

+        Define the draw buffers to which all fragment colors are written.
+      

+      

+        

+          
void clearBufferfv(GLenum buffer, GLint drawbuffer, Float32List values,
+                                optional GLuint srcOffset = 0);

+          
void clearBufferiv(GLenum buffer, GLint drawbuffer, Int32List values,
+                                optional GLuint srcOffset = 0);

+          
void clearBufferuiv(GLenum buffer, GLint drawbuffer, Uint32List values,
+                                 optional GLuint srcOffset = 0);

+          
void clearBufferfi(GLenum buffer, GLint drawbuffer, GLfloat depth, GLint stencil);
+            
+              (OpenGL ES 3.0.4 §4.2.3,
+              man page)
+            
+          

+        

+      

+      

+        Set every pixel in the specified buffer to a constant value. The clearBuffer
+        function that should be used for a color buffer depends on the type of the color buffer,
+        given in the following table:
+
+        
+          
+          
+          
+          
+          
+        
Type of bufferclearBuffer function
floating pointclearBufferfv
fixed pointclearBufferfv
signed integerclearBufferiv
unsigned integerclearBufferuiv


+        If buffer is COLOR_BUFFER and the function is not chosen according to the
+        above table, an INVALID_OPERATION error is generated and nothing is cleared.
+
+        
For ArrayBufferView entrypoints, if there's not enough elements in values
+           starting at srcOffset, generate INVALID_VALUE.
+
+        
clearBufferfi may be used to clear the depth and stencil buffers.
+          buffer must be DEPTH_STENCIL and drawBuffer must be
+          zero. depth and stencil are the depth and stencil values,
+          respectively.

+
+        
If this function attempts to clear a missing attachment of a complete framebuffer, nothing
+           is cleared and no error is generated
+           per Drawing to a Missing Attachment.
+      

+    

+
+
+    
3.7.12 Query objects

+
+    

+      

+        
WebGLQuery? createQuery()
+          
+            (OpenGL ES 3.0.4 §2.13,
+            man page)
+          
+        

+      

+      

+        Create a WebGLQuery object and initialize it with a query object name as if by calling glGenQueries.
+      

+      

+        
void deleteQuery(WebGLQuery? query)
+          
+            (OpenGL ES 3.0.4 §2.13,
+            man page)
+          
+        

+      

+      

+        Delete the query object contained in the passed WebGLQuery as if by calling
+        glDeleteQueries. If the query has already been deleted the call has no effect.
+        Note that the query object will be deleted when the WebGLQuery object is destroyed.
+        This method merely gives the author greater control over when the query object is destroyed.
+      

+      

+        
[WebGLHandlesContextLoss] GLboolean isQuery(WebGLQuery? query)
+          
+            (OpenGL ES 3.0.4 §6.1.7,
+            man page)
+          
+        

+      

+      

+        Return true if the passed WebGLQuery is valid and false otherwise.


+
+        Returns false if the query's invalidated
+        flag is set.
+      

+      

+        
void beginQuery(GLenum target, WebGLQuery query)
+          
+            (OpenGL ES 3.0.4 §2.13,
+            man page)
+          
+        

+      

+      

+        Begin an asynchronous query. Target indicates the type of query to be performed.
+      

+      

+        
void endQuery(GLenum target)
+          
+            (OpenGL ES 3.0.4 §2.13,
+            man page)
+          
+        

+      

+      

+        Mark the end of the sequence of commands to be tracked for the query type given by
+        target. When the final query result is available, the query object is updated
+        to indicate this and the result may be retrieved by calling getQueryParameter.
+      

+      

+        
WebGLQuery? getQuery(GLenum target, GLenum pname)
+          
+            (OpenGL ES 3.0.4 §6.1.7,
+            man page)
+          
+        

+      

+      

+          
Returns information about a query target target, which must be one
+          of ANY_SAMPLES_PASSED or ANY_SAMPLES_PASSED_CONSERVATIVE for
+          occlusion queries, or TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN for primitive
+          queries. pname specifies the symbolic name of a query object target
+          parameter. Currently it must be CURRENT_QUERY, and returns either the
+          currently active query for the target, or null.

+
+          
If target or pname are not in the list above, generates
+          an INVALID_ENUM error and returns null.

+
+          
Returns null if any OpenGL errors are generated during the execution of this
+          function.

+      

+      

+        
any getQueryParameter(WebGLQuery query, GLenum pname)
+          
+            (OpenGL ES 3.0.4 §6.1.7,
+            man page)
+          
+        

+      

+      

+          
Returns a parameter pname of a query object. QUERY_RESULT returns
+          the value of the query object's passed samples counter.
+          QUERY_RESULT_AVAILABLE returns whether the samples counter is immediately
+          available. The type returned is the natural type for the requested pname, as given in the
+          following table:

+          
+              
+              
+              
+          
pnamereturned type
QUERY_RESULTGLuint
QUERY_RESULT_AVAILABLEGLboolean

+
+          
If pname is not in the table above, generates an INVALID_ENUM
+          error and returns null.

+
+          
If query is not a valid query object, or is a currently active query object,
+          generates an INVALID_OPERATION error and returns null.
+
+          
Returns null if any OpenGL errors are generated during the execution of this
+          function.

+
+          
In order to ensure consistent behavior across platforms, queries' results must only be made
+          available when the user agent's event
+          loop is not executing a task. In other words:
+          
    
+            
  •  A query's result must not be made available until control has returned to the user
+                 agent's main loop. 
    • 
+            
  •  Repeatedly fetching a query's QUERY_RESULT_AVAILABLE parameter in a loop, without
+                 returning control to the user agent, must always return the same value. 
    • 
+          

+          

+
+          

+            A query's result may or may not be made available when control returns to the user
+            agent's event loop. It is not guaranteed that using a single setTimeout callback with a
+            delay of 0, or a single requestAnimationFrame callback, will allow sufficient time for
+            the WebGL implementation to supply the query's results.
+          

+
+          

+            This change compared to the OpenGL ES 3.0 specification is enforced in order to prevent
+            applications from relying on being able to issue a query and fetch its result in the
+            same frame. In order to ensure best portability among devices and best performance among
+            implementations, applications must expect that queries' results will become available
+            asynchronously.
+          

+      

+    

+
+
+
+    
3.7.13 Sampler objects

+
+    

+      

+        
WebGLSampler? createSampler()
+          
+            (OpenGL ES 3.0.4 §3.8.2,
+            man page)
+          
+        

+      

+      

+        Create a WebGLSampler object and initialize it with a sampler object name as if by
+        calling glGenSamplers.
+      

+      

+        
void deleteSampler(WebGLSampler? sampler)
+          
+            (OpenGL ES 3.0.4 §3.8.2,
+            man page)
+          
+        

+      

+      

+        Delete the sampler object contained in the passed WebGLSampler as if by calling
+        glDeleteSamplers. If the sampler has already been deleted the call has no effect.
+        Note that the sampler object will be deleted when the WebGLSampler object is destroyed.
+        This method merely gives the author greater control over when the sampler object is destroyed.
+      

+      

+        
[WebGLHandlesContextLoss] GLboolean isSampler(WebGLSampler? sampler)
+          
+            (OpenGL ES 3.0.4 §3.8.2,
+            man page)
+          
+        

+      

+      

+        Return true if the passed WebGLSampler is valid and false otherwise. 


+
+        Returns false if the sampler's invalidated
+        flag is set.
+      

+      

+        
void bindSampler(GLuint unit, WebGLSampler? sampler)
+          
+            (OpenGL ES 3.0.4 §3.8.2,
+            man page)
+          
+        

+      

+      

+        Bind the sampler object contained in the passed WebGLSampler to the texture unit at the
+        passed index. If a sampler is bound to a texture unit, the sampler's state supersedes the sampling
+        state of the texture bound to that texture unit. If sampler is null, the
+        currently bound sampler is unbound from the texture unit. A single sampler object may be bound to
+        multiple texture units simultaneously. 


+        If unit is greater than or equal to the value of MAX_COMBINED_TEXTURE_IMAGE_UNITS, generates an INVALID_VALUE error.


+        An attempt to bind a deleted sampler will generate an INVALID_OPERATION error,
+        and the current binding will remain untouched.
+      

+      

+        
void samplerParameteri(WebGLSampler sampler, GLenum pname, GLint param)

+        
void samplerParameterf(WebGLSampler sampler, GLenum pname, GLfloat param)

+          
+            (OpenGL ES 3.0.4 §3.8.2,
+            man page)
+          
+        

+      

+      

+        Set the value for the passed pname given the passed sampler. pname is given in the following table:
+        
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+        
pname
TEXTURE_COMPARE_FUNC
TEXTURE_COMPARE_MODE
TEXTURE_MAG_FILTER
TEXTURE_MAX_LOD
TEXTURE_MIN_FILTER
TEXTURE_MIN_LOD
TEXTURE_WRAP_R
TEXTURE_WRAP_S
TEXTURE_WRAP_T

+        
If pname is not in the table above, generates an INVALID_ENUM error.

+        
If sampler is not a valid sampler object, generates an INVALID_OPERATION error.

+      

+      
any getSamplerParameter(WebGLSampler sampler, GLenum pname)
+          (OpenGL ES 3.0.4 §6.1.5, man page)
+      

+      

+          Return the information requested in pname about the given WebGLSampler, passed as sampler. The
+          type returned is dependent on the information requested, as shown in the following table:
+          
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+          
pnamereturned type
TEXTURE_COMPARE_FUNCGLenum
TEXTURE_COMPARE_MODEGLenum
TEXTURE_MAG_FILTERGLenum
TEXTURE_MAX_LODGLfloat
TEXTURE_MIN_FILTERGLenum
TEXTURE_MIN_LODGLfloat
TEXTURE_WRAP_RGLenum
TEXTURE_WRAP_SGLenum
TEXTURE_WRAP_TGLenum

+          
If pname is not in the table above, generates an INVALID_ENUM error.

+          
If sampler is not a valid sampler object, generates an INVALID_OPERATION error.

+          
Returns null if any OpenGL errors are generated during the execution of this function.

+      

+    

+
+
+
+    
3.7.14 Sync objects

+
+    

+        Sync objects can be used to synchronize execution between the GL server and the client.
+    

+
+    

+      

+        
WebGLSync? fenceSync(GLenum condition, GLbitfield flags)
+          
+            (OpenGL ES 3.0.4 §5.2,
+            man page)
+          
+        

+      

+      

+          Create a new fence sync object and insert an associated fence command in the GL command stream.
+      

+      

+        
[WebGLHandlesContextLoss] GLboolean isSync(WebGLSync? sync)
+          
+            (OpenGL ES 3.0.4 §6.1.8,
+            man page)
+          
+        

+      

+      

+          Return true if the passed WebGLSync is valid and false otherwise. 


+
+          Returns false if the sync's invalidated
+          flag is set.
+      

+      

+        
void deleteSync(WebGLSync? sync)
+          
+            (OpenGL ES 3.0.4 §5.2,
+            man page)
+          
+        

+      

+      

+          Delete the sync object contained in the passed WebGLSync as if by calling
+          glDeleteSync. If the sync has already been deleted the call has no effect.
+          Note that the sync object will be deleted when the WebGLSync object is destroyed.
+          This method merely gives the author greater control over when the sync object is destroyed.
+      

+      

+        
GLenum clientWaitSync(WebGLSync sync, GLbitfield flags, GLuint64 timeout)
+          
+            (OpenGL ES 3.0.4 §5.2.1,
+            man page)
+          
+        

+      

+      

+        

+        Block execution until the passed sync object is signaled or the specified timeout has
+        passed. timeout is in units of nanoseconds.
+        

+
+        

+        Returns one of four status values. A return value of ALREADY_SIGNALED indicates
+        that sync was signaled at the time clientWaitSync was
+        called. ALREADY_SIGNALED will always be returned if sync was signaled, even
+        if timeout was zero. A return value of TIMEOUT_EXPIRED indicates that the specified
+        timeout period expired before sync was signaled. A return value of CONDITION_SATISFIED
+        indicates that sync was signaled before the timeout expired. Finally, if an error occurs, in
+        addition to generating an error as specified below, returns WAIT_FAILED without blocking.
+        

+
+        

+        flags controls command flushing behavior and may include SYNC_FLUSH_COMMANDS_BIT. If
+        any other bit is set in flags an INVALID_OPERATION error is
+        generated. If SYNC_FLUSH_COMMANDS_BIT is set in flags and sync is
+        unsignaled when clientWaitSync is called, then the equivalent of flush will be
+        performed before blocking on sync.
+        

+
+        

+        As discussed in the differences section, WebGL implementations must impose a
+        short maximum timeout to prevent blocking the main thread for long periods of time. The
+        implementation-defined timeout may be queried by calling getParameter with the
+        argument MAX_CLIENT_WAIT_TIMEOUT_WEBGL. If timeout is larger than this
+        implementation-defined timeout then an INVALID_OPERATION error is generated.
+        

+
+        

+        The implementation-defined maximum timeout is not specified. It should be set low enough to keep applications
+        from compromising interactivity by waiting for long periods of time. It is acceptable for an implementation to
+        impose a zero maximum timeout. WebGL applications should not use clientWaitSync to block execution for long
+        periods of time.
+        

+
+        
Returns WAIT_FAILED if any OpenGL errors are generated during the execution of this
+        function.

+
+      

+      

+        
void waitSync(WebGLSync sync, GLbitfield flags, GLint64 timeout)
+          
+            (OpenGL ES 3.0.4 §5.2.1,
+            man page)
+          
+        

+      

+      

+        Return immediately, but wait on the GL server until the passed sync object is signaled or an
+        implementation-dependent timeout has passed. The passed timeout must be set to
+        TIMEOUT_IGNORED.
+
+        

+          In the absence of the possibility of synchronizing between multiple GL contexts, calling waitSync is effectively a no-op.
+        

+      

+      
any getSyncParameter(WebGLSync sync, GLenum pname)
+          (OpenGL ES 3.0.4 §6.1.8, man page)
+      

+      

+          Return the value for the passed pname given the passed WebGLSync object. The type returned is the natural
+          type for the requested pname, as given in the following table:
+          
+              
+              
+              
+              
+              
+          
pnamereturned type
OBJECT_TYPEGLenum
SYNC_STATUSGLenum
SYNC_CONDITIONGLenum
SYNC_FLAGSGLbitfield

+          
If pname is not in the table above, generates an INVALID_ENUM error and returns null.

+          
Returns null if any OpenGL errors are generated during the execution of this
+          function.

+      

+    

+
+
+
+    
3.7.15 Transform feedback

+
+    

+        Transform feedback mode captures the values of output variables written by the vertex shader. The
+        vertices are captured before flatshading and clipping. The transformed vertices may be optionally
+        discarded after being stored into one or more buffer objects, or they can be passed on down to the
+        clipping stage for further processing. The set of output variables captured is determined when a
+        program is linked.
+    

+
+    

+        If any output variable is specified to be streamed to a transform feedback buffer object but not actually
+        written by a vertex shader, the value is set to 0. See 
+        Transform feedback primitive capture.
+    

+
+    

+        
WebGLTransformFeedback? createTransformFeedback()
+            (OpenGL ES 3.0.4 §2.14.1,
+            similar to glGenTransformFeedbacks)
+        

+            Create a WebGLTransformFeedback object and initialize it with a transform feedback object name as if by
+            calling glGenTransformFeedbacks.
+
+        
void deleteTransformFeedback(WebGLTransformFeedback? transformFeedback)
+            (OpenGL ES 3.0.4 §2.14.1,
+            similar to glDeleteTransformFeedbacks)
+        

+            Delete the transform feedback object contained in the passed WebGLTransformFeedback as if by calling
+            glDeleteTransformFeedbacks. If the transform feedback has already been deleted the call has no effect.
+            Note that the transform feedback object will be deleted when the WebGLTransformFeedback object is destroyed.
+            This method merely gives the author greater control over when the transform feedback object is destroyed.
+
+        
[WebGLHandlesContextLoss] GLboolean isTransformFeedback(WebGLTransformFeedback? transformFeedback)
+            (OpenGL ES 3.0.4 §6.1.11,
+            man page)
+        

+            Return true if the passed WebGLTransformFeedback is valid and false otherwise. 


+
+            Returns false if the transform feedback's invalidated
+            flag is set.
+
+        
void bindTransformFeedback (GLenum target, WebGLTransformFeedback? transformFeedback)
+            (OpenGL ES 3.0.4 §2.14.1,
+            man page)
+        

+            Bind the given WebGLTransformFeedback object.
+            If transformFeedback is null, the default transform feedback object provided by the context
+            is bound.
+            An attempt to bind a deleted transform feedback will generate a INVALID_OPERATION error, and the current
+            binding will remain untouched.
+
+        
void beginTransformFeedback(GLenum primitiveMode)
+            (OpenGL ES 3.0.4 §2.14.2,
+            man page)
+        

+
+        
void endTransformFeedback()
+            (OpenGL ES 3.0.4 §2.14.2,
+            man page)
+        

+
+        
void pauseTransformFeedback()
+            (OpenGL ES 3.0.4 §2.14.2,
+            man page)
+        

+
+        
void resumeTransformFeedback()
+            (OpenGL ES 3.0.4 §2.14.2,
+            man page)
+        

+
+        
void transformFeedbackVaryings(WebGLProgram program, sequence<DOMString> varyings, GLenum bufferMode)
+            (OpenGL ES 3.0.4 §2.11.8,
+            man page)
+        

+
+        
WebGLActiveInfo? getTransformFeedbackVarying(WebGLProgram program, GLuint index)
+            (OpenGL ES 3.0.4 §2.11.8,
+            man page)
+        

+    

+
+
+
+    
3.7.16 Uniform Buffer objects

+
+    

+        Uniform buffer objects provide the storage for named uniform blocks, so the values of active uniforms
+        in named uniform blocks may be changed by modifying the contents of the buffer object.
+    

+
+    

+        
void bindBufferBase(GLenum target, GLuint index, WebGLBuffer? buffer)
+            (OpenGL ES 3.0.4 §2.9.1,
+            man page)
+        

+            Binds the given WebGLBuffer object to the binding point at index of the array of targets
+            specified by target.
+
+        
void bindBufferRange(GLenum target, GLuint index, WebGLBuffer? buffer, GLintptr offset, GLsizeiptr size)
+            (OpenGL ES 3.0.4 §2.9.1,
+            man page)
+        

+            Binds a range of the WebGLBuffer object buffer represented by offset and size
+            to the binding point at index of the array of targets specified by target.
+
+        
sequence<GLuint>? getUniformIndices(WebGLProgram program, sequence<DOMString> uniformNames)
+            (OpenGL ES 3.0.4 §2.11.6,
+            man page)
+        

+            Retrieves the indices of a number of uniforms within program.
+
+        
any getActiveUniforms(WebGLProgram program, sequence<GLuint> uniformIndices, GLenum pname)
+            (OpenGL ES 3.0.4 §2.11.6,
+            man page)
+        

+            Queries the value of the parameter named pname for each of the uniforms within program whose indices
+            are specified in the array of uniformIndices. The type returned is the natural type for the requested
+            pname, as given in the following table:
+            
+                
+                
+                
+                
+                
+                
+                
+                
+            
pnamereturned type
UNIFORM_TYPEsequence<GLenum>
UNIFORM_SIZEsequence<GLuint>
UNIFORM_BLOCK_INDEXsequence<GLint>
UNIFORM_OFFSETsequence<GLint>
UNIFORM_ARRAY_STRIDEsequence<GLint>
UNIFORM_MATRIX_STRIDEsequence<GLint>
UNIFORM_IS_ROW_MAJORsequence<GLboolean>


+            
If pname is not in the table above, generates an INVALID_ENUM error.

+
+        
GLuint getUniformBlockIndex(WebGLProgram program, DOMString uniformBlockName)
+            (OpenGL ES 3.0.4 §2.11.6,
+            man page)
+        

+            Retrieves the index of a uniform block within program.
+
+        
any getActiveUniformBlockParameter(WebGLProgram program, GLuint uniformBlockIndex, GLenum pname)
+            (OpenGL ES 3.0.4 §2.11.6,
+            man page)
+        

+            Retrieves information about an active uniform block within program. The type returned is the natural type for the requested
+            pname, as given in the following table:
+            
+                
+                
+                
+                
+                
+                
+                
+            
pnamereturned type
UNIFORM_BLOCK_BINDINGGLuint
UNIFORM_BLOCK_DATA_SIZEGLuint
UNIFORM_BLOCK_ACTIVE_UNIFORMSGLuint
UNIFORM_BLOCK_ACTIVE_UNIFORM_INDICESUint32Array
UNIFORM_BLOCK_REFERENCED_BY_VERTEX_SHADERGLboolean
UNIFORM_BLOCK_REFERENCED_BY_FRAGMENT_SHADERGLboolean


+            
If pname is not in the table above, generates an INVALID_ENUM error.

+            
If uniformBlockIndex is not an active block uniform for program or greater than or equal to the
+            value of ACTIVE_UNIFORM_BLOCKS, generates an INVALID_VALUE error.

+            
If an OpenGL error is generated, returns null.

+
+        
DOMString? getActiveUniformBlockName(WebGLProgram program, GLuint uniformBlockIndex)
+            (OpenGL ES 3.0.4 §2.11.6,
+            man page)
+        

+            Retrieves the name of the active uniform block at uniformBlockIndex within program.
+
+        
void uniformBlockBinding(WebGLProgram program, GLuint uniformBlockIndex, GLuint uniformBlockBinding)
+            (OpenGL ES 3.0.4 §2.11.6,
+            man page)
+        

+            Assigns binding points for active uniform blocks.
+    

+
+
+
+    
3.7.17 Vertex Array objects

+
+    

+        Vertex Array objects (sometimes referred to as VAOs) encapsulate all state related to the
+        definition of data used by the vertex processor.
+    

+
+    

+        
void bindVertexArray(WebGLVertexArrayObject? vertexArray)
+            (OpenGL ES 3.0.4 §2.10,
+            man page)
+        

+            Bind the given WebGLVertexArrayObject object.
+            If vertexArray is null, the default vertex array provided by the context
+            is bound.
+            An attempt to bind a deleted vertex array will generate a INVALID_OPERATION error, and
+            the current binding will remain untouched.
+
+        
WebGLVertexArrayObject? createVertexArray()
+            (OpenGL ES 3.0.4 §2.10,
+            similar to glGenVertexArrays)
+        

+            Create a WebGLVertexArrayObject object and initialize it with a vertex array object name as if by
+            calling glGenVertexArrays.
+
+        
void deleteVertexArray(WebGLVertexArrayObject? vertexArray)
+            (OpenGL ES 3.0.4 §2.10,
+            similar to glDeleteVertexArrays)
+        

+            Delete the vertex array object contained in the passed WebGLVertexArrayObject as if by calling
+            glDeleteVertexArrays. If the vertex array has already been deleted the call has no effect.
+            Note that the vertex array object will be deleted when the WebGLVertexArrayObject object is destroyed.
+            This method merely gives the author greater control over when the vertex array object is
+            destroyed.
+
+        
[WebGLHandlesContextLoss] GLboolean isVertexArray(WebGLVertexArrayObject? vertexArray)
+            (OpenGL ES 3.0.4 §6.1.10,
+            man page)
+        

+            Return true if the passed WebGLVertexArrayObject is valid and false otherwise. 


+
+            Returns false if the vertex array's invalidated
+            flag is set.
+    

+
+
+
+    
4 Other differences Between WebGL 2.0 and WebGL 1.0

+
+    

+        Needs update for WebGL 2.0
+    

+
+    
4.1 Backwards Incompatibility

+
+    
4.1.1 Errors

+
+    

+        The WebGL 2 API may behave differently in cases where the WebGL 1 API generates an error.
+        Code written against the WebGL 1 API that generates errors is not guaranteed to be
+        forward-compatible with WebGL 2.
+    

+
+    
4.1.2 Extensions

+
+    

+        Some extensions that may have been supported in the WebGL 1 API are removed from the WebGL
+        2 API. For more details, see the
+        WebGL Extension Registry.
+    

+
+    

+        Extensions are typically removed only if equivalent functionality is available in the WebGL
+        2 API either in the core specification or in an improved extension. When an application
+        using WebGL 1 extensions is modified to run on the WebGL 2 API, it is often possible to
+        create a dummy extension object for each of the promoted extensions which simply
+        redirects calls to the appropriate WebGL 2 API functions. If the application is using shader
+        language extensions, porting shaders to GLSL ES 3.00 is typically required.
+    

+
+    
4.1.3 Non-Power-of-Two Texture Access

+
+    

+        Texture access works in the WebGL 2.0 API as in the OpenGL ES 3.0 API. In other words,
+        unlike the WebGL 1.0 API, there are no special restrictions on non power of 2 textures. All
+        mipmapping and all wrapping modes are supported for non-power-of-two images.
+    

+
+    
4.1.4 Primitive Restart is Always Enabled

+
+    

+        See section PRIMITIVE_RESTART_FIXED_INDEX is always enabled.
+    

+
+    
4.1.5 Framebuffer Object Attachments

+
+    
In WebGL 1, DEPTH_STENCIL_ATTACHMENT is an alternative attachment point other than DEPTH_ATTACHMENT and STENCIL_ATTACHMENT. In WebGL 2, however, DEPTH_STENCIL_ATTACHMENT is considered an alias for DEPTH_ATTACHMENT + STENCIL_ATTACHMENT, i.e., the same image is attached to both DEPTH_ATTACHMENT and STENCIL_ATTACHMENT, overwriting the original images attached to the two attachment points.

+    
Consider the following sequence of actions:
+      
    
+       
  1. attach renderbuffer 1 to DEPTH_ATTACHMENT;
    2. 
+       
  2. attach renderbuffer 2 to DEPTH_STENCIL_ATTACHMENT;
    3. 
+       
  3. attach null to DEPTH_STENCIL_ATTACHMENT.
    4. 
+      

+      In WebGL 1, the framebuffer ends up with renderbuffer 1 attached to DEPTH_ATTACHMENT and no image attached to STENCIL_ATTACHMENT; in WebGL 2, however, neither DEPTH_ATTACHMENT nor STENCIL_ATTACHMENT has an image attached.

+    
The constraints defined in Framebuffer Object Attachments no longer apply in WebGL 2.

+    
If different images are bound to the depth and stencil attachment points, checkFramebufferStatus returns FRAMEBUFFER_UNSUPPORTED, and getFramebufferAttachmentParameter with attachment of DEPTH_STENCIL_ATTACHMENT generates an INVALID_OPERATION error.

+
+    
4.1.6 Texture Type in TexSubImage2D Calls

+
+    

+        In the WebGL 1.0 API, the type argument passed to texSubImage2D must
+        match the type used to originally define the texture object (i.e., using texImage2D).
+        In the WebGL 2.0 API, this restriction has been lifted.
+    

+
+    
4.1.7 Out-of-bounds Behaviors in copyTexSubImage2D and readPixels calls

+
+    

+        In WebGL 1.0, 
+        Reading Pixels Outside the Framebuffer, it is required that
+        copyTexSubImage2D and readPixels do not touch
+        the corresponding destination range for out-of-bound pixels.
+    

+
+    

+        In WebGL 2.0, when a PACK_BUFFER object is bound and
+        PACK_ROW_LENGTH is not zero and less than width,
+        or when a UNPACK_BUFFER object is bound and
+        UNPACK_ROW_LENGTH is not zero and less than width
+        or UNPACK_IMAGE_HEIGHT is not zero and less than height,
+        packing/unpacking a row/image may extend to the next row/image. If that
+        portion is out-of-bounds, the values may change accordingly.
+    

+
+    
4.1.8 Color conversion in copyTex{Sub}Image2D

+
+    

+        In WebGL 1 (OpenGL ES 2.0), it is allowed for the component sizes of
+        internalformat to be less than the corresponding component sizes
+        of the source buffer's internal format. However, in WebGL 2 (OpenGL ES 3.0),
+        if internalformat is sized, its component sizes must exactly
+        match the corresponding component sizes of the source buffer's effective
+        internal format.
+    

+
+    

+        In both WebGL 1 and 2, source buffer components can be dropped during the
+        conversion to internalformat, but new components cannot be added.
+    

+
+    
4.2 New Features Supported in the WebGL 2 API

+
+    
+
+    
4.3 GLSL ES 3.00 support

+
+    

+        In addition to supporting The OpenGL ES Shading Language, Version 1.00, the WebGL 2 API also accepts
+        shaders written in The OpenGL ES Shading Language, Version 3.00
+        [GLES30GLSL], with some restrictions.
+    

+
+    
    
+        
  • 
+            A shader referencing state variables or functions that are available in other versions of GLSL,
+            such as that found in versions of OpenGL for the desktop, must not be allowed to load.
+        
    • 
+    

+
+    

+        As in the WebGL 1.0 API, identifiers starting with "webgl_" and "_webgl_" are reserved for use by
+        WebGL. A shader which declares a function, variable, structure name, or structure field starting with
+        these prefixes must not be allowed to load.
+    

+
+    
4.3.1 Maximum GLSL Token Size

+
+    

+        WebGL 1.0 supports tokens up to 256 characters in length. WebGL 2.0 follows The OpenGL ES Shading Language, Version 3.00
+        (OpenGL ES 3.0.4 §3.8)
+        and allows tokens up to 1024 characters in length for both ESSL 1 and ESSL 3 shaders. Shaders containing tokens longer than 1024 characters must fail to compile.
+    

+
+    
4.3.2 Maximum Uniform and Attribute Location Lengths

+
+    

+        WebGL 2.0 imposes a limit of 1024 characters on the lengths of uniform and attribute locations.
+    

+
+    
4.4 Vertex Attribute Divisor

+
+    

+        In the WebGL 2 API, vertex attributes which have a non-zero divisor do not advance during calls to
+        drawArrays and drawElements.
+        (OpenGL ES 3.0.4 §2.9.3)
+    

+
+
+
+    
5 Differences Between WebGL and OpenGL ES 3.0

+
+    

+        This section describes changes made to the WebGL API relative to the
+        OpenGL ES 3.0 API to improve portability across various operating
+        systems and devices.
+    

+
+    
5.1 Buffer Object Binding

+
+    
+        
+            
+            
+        
+        
+            
+            
+        
+        
+            
+            
+        
+        
+            
+            
+        
+    
WebGL buffer typeBinding points that set this type
undefinednone
element arrayELEMENT_ARRAY_BUFFER
other dataall binding points except ELEMENT_ARRAY_BUFFER, COPY_READ_BUFFER and COPY_WRITE_BUFFER


+
+    

+        In the WebGL 2 API, buffers have their WebGL buffer type initially set to undefined. Calling
+        bindBuffer, bindBufferRange or bindBufferBase with the
+        target argument set to any buffer binding point except COPY_READ_BUFFER or
+        COPY_WRITE_BUFFER will then set the WebGL buffer type of the buffer being bound
+        according to the table above. Binding a buffer with type undefined to
+        the COPY_READ_BUFFER or COPY_WRITE_BUFFER binding points will set
+        its type to other data.
+    

+
+    

+        Any call to one of these functions which attempts to bind a deleted buffer will generate a
+        INVALID_OPERATION error, and the binding will remain untouched.
+    

+
+    

+        Any call to one of these functions which attempts to bind a WebGLBuffer that has the element
+        array WebGL buffer type to a binding point that falls under other data, or bind a
+        WebGLBuffer which has the other data WebGL buffer type to ELEMENT_ARRAY_BUFFER
+        will generate an INVALID_OPERATION error, and the state of the binding point will remain
+        untouched.
+    

+
+    

+        This restriction implies that a given buffer object may contain either indices or other data, but
+        not both.
+    

+
+    

+        These restrictions are similar to buffer object binding
+        restrictions in the WebGL 1 specification.
+    

+
+    

+        This restriction has been added to prevent writing to index buffers on the GPU, which would make
+        doing any CPU-side checks on index data prohibitively expensive. Handling index buffers as different
+        from other buffer data also maps better to the Direct3D API.
+    

+
+    

+        In addition, a buffer can not be simultaneously bound to a transform feedback buffer binding point
+        and another buffer binding point in the WebGL 2 API. Attempting to violate this rule generates an
+        INVALID_OPERATION error, and the state of the binding point will remain untouched.
+    

+
+    

+        This restriction has been added to prevent undefined values when reading from or writing to a buffer object that is simultaneously bound to a transform feedback buffer binding point and elsewhere in the GL. An example of such a situation is ReadPixels to a pixel buffer object binding point. See (OpenGL ES 3.0.4 §2.15.2).
+    

+
+    
5.2 Copying Buffers

+
+    

+        Attempting to use copyBufferSubData to copy between buffers that have
+        element array and other data WebGL buffer types as specified in section
+        Buffer Object Binding generates an
+        INVALID_OPERATION error and no copying is performed.
+    

+    

+        Same as with Buffer Object Binding restrictions above.
+    

+
+    
5.3 Draw Buffers

+
+    

+        The value of the MAX_COLOR_ATTACHMENTS parameter must be equal to that of the MAX_DRAW_BUFFERS
+        parameter.
+    

+    

+        There is no use case for these parameters being different.
+    

+
+    

+        If an ESSL1 fragment shader writes to neither gl_FragColor nor gl_FragData,
+        the values of the fragment colors following shader execution are untouched. If corresponding output
+        variables are not defined in an ESSL3 fragment shader, the values of the fragment colors following
+        shader execution are untouched.
+    

+    

+        All user-defined output variables default to zero if they are not written during a shader execution.
+    

+
+    

+        For optimal performance, an output array should not include any elements that are not accessed.
+    

+
+    

+        If the values written by the fragment shader do not match the format(s) of the corresponding
+        color buffer(s) (for example, the output variable is an integer, but the corresponding color
+        buffer has a floating-point format, or vice versa), and the color buffer states are not set to
+        NONE by DrawBuffers, generates an INVALID_OPERATION error;
+        if the color buffer states are set to NONE by DrawBuffers, they remain untouched.
+    

+
+    
5.4 No Program Binaries

+
+    

+        Accessing binary representations of compiled shader programs is not supported in the WebGL 2 API.
+        This includes OpenGL ES 3.0 GetProgramBinary, ProgramBinary, and
+        ProgramParameteri entry points. In addition, querying the program binary length with
+        getProgramParameter, and querying program binary formats with getParameter
+        are not supported in the WebGL 2 API.
+    

+
+    
5.5 Range Checking

+
+    

+        In addition to the range checking specified in the WebGL 1.0 specification section
+        Enabled Vertex Attributes and Range Checking,
+        indices referenced by drawElements, drawRangeElements or
+        drawElementsInstanced that are greater than the MAX_ELEMENT_INDEX parameter
+        cause the draw call to generate an INVALID_OPERATION error even if they lie within the
+        storage of the bound buffer. Range checking is not performed for indices that trigger primitive
+        restart if primitive restart is enabled. The range checking specified for drawArrays in
+        the WebGL 1.0 API is also applied to drawArraysInstanced in the WebGL 2.0 API.
+    

+    

+        The OpenGL robustness extensions do not specify what happens if indices above MAX_ELEMENT_INDEX are
+        used, so passing them to the driver is risky. On platforms where MAX_ELEMENT_INDEX is the same as
+        the maximum unsigned integer value this section will have no effect.
+    

+
+    
5.6 Enabled Attribute

+
+    

+        In the WebGL 2 API, attempting to draw with drawArrays, drawElements,
+        drawRangeElements or their instanced variants generates an INVALID_OPERATION
+        error if there is not at least one enabled vertex attribute array that has a divisor of zero and is
+        bound to an active generic attribute value in the program used for the draw command.
+    

+    

+        The removed functionality is an exotic corner case, and Direct3D based implementations of WebGL would
+        need to add complex workarounds to support it.
+    

+
+    
5.7 Active Uniform Block Backing

+
+    

+        In the WebGL 2 API, attempting to draw with drawArrays, drawElements,
+        drawRangeElements or their instanced variants generates an INVALID_OPERATION
+        error if any active uniform block in the program used for the draw command is not backed by a
+        sufficiently large buffer object.
+    

+    

+        In OpenGL, insufficient uniform block backing is allowed to cause GL interruption or termination.
+        See OpenGL ES 3.0 specification section 2.12.6 
+        (
+        OpenGL ES 3.0.4 §2.12.6), under "Uniform Buffer Object Bindings."
+    

+
+    
+
+    
5.8 Default Framebuffer

+
+    

+        WebGL always has a default framebuffer. The FRAMEBUFFER_UNDEFINED enumerant is removed
+        from the WebGL 2 API.
+    

+
+    
5.9 String Length Queries

+
+    

+        In the WebGL 2 API, the enumerants ACTIVE_UNIFORM_BLOCK_MAX_NAME_LENGTH,
+        TRANSFORM_FEEDBACK_VARYING_MAX_LENGTH, UNIFORM_BLOCK_NAME_LENGTH, and
+        UNIFORM_NAME_LENGTH are removed in addition to similar
+        enumerants removed in the WebGL 1.0 API.
+    

+
+    
5.10 Invalid Clears

+
+    

+        In the WebGL 2 API, trying to perform a clear when there is a mismatch between the type of the
+        specified clear value and the type of a buffer that is being cleared generates an
+        INVALID_OPERATION error instead of producing undefined results.
+    

+
+    
5.11 Invalid Texture Offsets

+
+    

+        A GLSL shader which attempts to use a texture offset value outside the range specified by
+        implementation-defined parameters MIN_PROGRAM_TEXEL_OFFSET and
+        MAX_PROGRAM_TEXEL_OFFSET in texture lookup function arguments must fail
+        compilation in the WebGL 2 API.
+    

+
+    

+        Using an offset outside the valid range returns undefined results, so it can not be allowed.
+        The offset must be a constant expression according to the GLSL ES spec, so checking the
+        value against the correct range can be done at compile time.
+    

+
+    
5.12 Texel Fetches

+
+    

+        Texel fetches that have undefined results in the OpenGL ES 3.0 API must return zero, or a texture
+        source color of (0, 0, 0, 1) in the case of a texel fetch from an incomplete texture in the WebGL 2
+        API.
+    

+    

+        Behavior of out-of-range texel fetches needs to be testable in order to guarantee security.
+    

+
+    
5.13 GLSL ES 1.00 Fragment Shader Output

+
+    

+        A fragment shader written in The OpenGL ES Shading Language, Version 1.00, that statically assigns a
+        value to gl_FragData[n] where n does not equal constant value 0 must fail
+        to compile in the WebGL 2 API. This is to achieve consistency with The OpenGL ES 3.0 specification
+        section 4.2.1 (OpenGL ES 3.0.4 §4.2.1)
+        and The OpenGL ES Shading Language 3.00.6 specification section 1.5 (GLSL ES 3.00.6 §1.5).
+        As in the OpenGL ES 3.0 API, multiple fragment shader outputs are only supported for GLSL ES 3.00
+        shaders in the WebGL 2 API.
+    

+
+    
5.14 No MapBufferRange

+
+    

+        The MapBufferRange, FlushMappedBufferRange, and UnmapBuffer
+        entry points are removed from the WebGL 2.0 API. The following enum values are also removed:
+        BUFFER_ACCESS_FLAGS, BUFFER_MAP_LENGTH, BUFFER_MAP_OFFSET,
+        MAP_READ_BIT, MAP_WRITE_BIT, MAP_INVALIDATE_RANGE_BIT,
+        MAP_INVALIDATE_BUFFER_BIT, MAP_FLUSH_EXPLICIT_BIT, and
+        MAP_UNSYNCHRONIZED_BIT.
+    

+
+    

+        Instead of using MapBufferRange, buffer data may be read by using the
+        getBufferSubData entry point.
+    

+
+    
5.15 TIMEOUT_IGNORED

+    

+        In the WebGL 2.0 API TIMEOUT_IGNORED is defined as a GLint64 with the value -1 instead of a GLuint64
+        with the value 0xFFFFFFFFFFFFFFFF. This is because Javascript cannot accurately represent an integer
+        that large. For the same reason clientWaitSync and waitSync both take GLint64 values instead of GLuint64
+        for timeout.
+    

+
+    
5.16 clientWaitSync

+    

+        In the WebGL 2.0 API, WebGL implementations must enforce a short maximum timeout on calls to clientWaitSync in
+        order to avoid blocking execution of the main thread for excessive periods of time. This timeout may be queried
+        by calling getParameter with the argument MAX_CLIENT_WAIT_TIMEOUT_WEBGL.
+    

+    

+        The implementation-defined maximum timeout is not specified. It is acceptable for an implementation to enforce a
+        zero maximum timeout.
+    

+
+    
5.17 Vertex Attribute Aliasing

+    

+        In the WebGL 2.0 API, if more than one active attribute name is bound to the same location, it is considered
+        aliased, regardless whether there exists a path through the shader that consumes more than of these
+        attributes. Such definition of aliasing is broader than what is defined in
+        (OpenGL ES 3.0.4 §2.11.5).
+    

+    

+        A link error is required when aliasing exists.
+    

+
+    
5.18 PRIMITIVE_RESTART_FIXED_INDEX is always enabled

+
+    

+        The PRIMITIVE_RESTART_FIXED_INDEX context state, controlled
+        with Enable/Disable in OpenGL ES 3.0, is not supported in WebGL
+        2.0. Instead, WebGL 2.0 behaves as though this state were always enabled. This is a
+        compatibility difference compared to WebGL 1.0.
+    

+    

+        When drawElements, drawElementsInstanced,
+        or drawRangeElements processes an index, if the index's value is the maximum
+        for the data type (255 for UNSIGNED_BYTE indices, 65535
+        for UNSIGNED_SHORT, or 4294967295 for UNSIGNED_INT), then the
+        vertex is not processed normally. Instead, it is as if the drawing command ended with the
+        immediately preceding vertex, and another drawing command is immediately started with the
+        same parameters, but only transferring the immediately following index through the end of
+        the originally specified indices.
+    

+    

+        This compatibility difference was introduced in order to avoid performance pitfalls in
+        Direct3D based WebGL implementations. Applications and content creation tools can be
+        adjusted to avoid using the maximum vertex index if the primitive restart behavior is not
+        desired.
+    

+
+    
5.19 No texture swizzles

+
+    

+        OpenGL ES 3.0 introduces new state on texture objects allowing a four-channel swizzle
+        operation to be specified against the texture. The swizzle is applied to every texture
+        lookup performed within any shader referencing that texture. These texture swizzles are
+        not supported in WebGL 2.0. TEXTURE_SWIZZLE_* enum values are removed from
+        the WebGL 2.0 API.
+    

+
+    

+        Texture swizzles can not be implemented in a performant manner on Direct3D based WebGL
+        implementations. Applications relying on this functionality would run significantly more
+        slowly on those implementations. Applications are still able to swizzle results of texture
+        fetches in shaders and swizzle texture data before uploading without this interface.
+    

+
+    
5.20 Queries should fail on a program that failed to link

+
+    

+        OpenGL ES 3.0 allows applications to enumerate and query properties of
+        active variables and interface blocks of a specified program even if
+        that program failed to link (OpenGL ES 3.0.4 §2.11.3).
+        In WebGL, these commands will always generate an INVALID_OPERATION error
+        on a program that failed to link, and no information is returned.
+    

+
+    

+        The returned information in OpenGL ES 3.0 is implementation dependent and may be incomplete.
+        The error condition is added to ensure consistent behavior across all platforms.
+    

+
+    
5.21 Color values from a fragment shader must match the color buffer format

+
+    

+        Color values written by a fragment shader may be floating-point, signed integer, or unsigned
+        integer. If the values written by the fragment shader do not match the format(s) of the
+        corresponding color buffer(s), the result is undefined in OpenGL ES 3.0  (OpenGL ES 3.0.4 §3.9.2). In WebGL, generates
+        an INVALID_OPERATION error in the corresponding draw call, including
+        drawArrays, drawElements, drawArraysInstanced
+        , drawElementsInstanced , and drawRangeElements.
+    

+    

+        If the color buffer has a normalized fixed-point format, floating-point color
+        values are converted to match the format; generates no error in such situation.
+    

+
+    
5.22 A sampler type must match the internal texture format

+
+    

+        Texture lookup functions return values as floating point, unsigned integer or signed integer,
+        depending on the sampler type passed to the lookup function. If the wrong sampler type is
+        used for texture access, i.e., the sampler type does not match the texture internal format,
+        the returned values are undefined in OpenGL ES Shading Language 3.00.6
+        (OpenGL ES Shading Language 3.00.6 §8.8).
+        In WebGL, generates an INVALID_OPERATION error in the corresponding draw call,
+        including drawArrays, drawElements, drawArraysInstanced,
+        drawElementsInstanced , and drawRangeElements.
+    

+    

+        If the sampler type is floating point and the internal texture format is
+        normalized integer, it is considered as a match and the returned values are converted to
+        floating point in the range [0, 1].
+    

+
+    
5.23 Queries' results must not be made available in the current frame

+
+    

+        In OpenGL ES 3.0, if the appropriate primitives (e.g. glFinish() or another
+        synchronous API) are called, a query's result may be made available in the same frame it was
+        issued. In WebGL, in order to improve application portability, a query's result must never
+        be made available to the application in the same frame the query was issued. See the
+        specification of getQueryParameter for discussion and
+        rationale.
+    

+
+    
5.24 GLSL ES 3.00 #extension directive location

+
+    

+        The WebGL 1.0 specification section 
+        GLSL ES #extension directive location only applies to OpenGL ES Shading Language 1.00
+        shaders. It does not apply to shaders that are written in OpenGL ES Shading Language 3.00.
+        In shaders written in OpenGL ES Shading Language 3.00, #extension directives
+        must occur before non-preprocessor tokens regardless of what is written in the extension
+        specification.
+    

+
+    

+        This is done to make WebGL 2.0 to follow the written GLSL ES 3.00 specification more
+        closely. Enforcing the restriction more strictly than native GLES drivers makes the behavior
+        well-defined.
+    

+
+    
5.25 Only std140 layout supported in uniform blocks

+
+    

+        The GLSL ES 3.00 specification supports the shared, packed,
+        and std140 layout qualifiers for uniform blocks, defining how variables are
+        laid out in uniform buffers' storage. Of these, the WebGL 2.0 specification supports only
+        the std140 layout, which is defined
+        in OpenGL
+        ES 3.0.4 §2.12 "Vertex Shaders", subsection "Standard Uniform Block
+        Layout". Shaders attempting to use the shared or packed layout
+        qualifiers will fail either the compilation or linking stages.
+    

+
+    

+        The initial state of compilation is as if the following were declared:
+    

+
+    

+        layout(std140) uniform;
+    

+
+    

+        This restriction is enforced to improve portability by avoiding exposing uniform block
+        layouts that are specific to one vendor's GPUs.
+    

+
+    
5.26 Disallowed variants of GLSL ES 3.00 operators

+
+    

+        In the WebGL 2.0 API, the following shading language constructs are not allowed and
+        attempting to use them must result in a compile error:
+    

+
+    
    
+        
  • Ternary operator applied to void, arrays, or structs containing arrays
    • 
+        
  • Sequence operator applied to void, arrays, or structs containing arrays
    • 
+    

+
+    

+        This restriction ensures easy portability across OpenGL ES 3.0 supporting devices.
+    

+
+    
5.27 checkFramebufferStatus may return FRAMEBUFFER_INCOMPLETE_DIMENSIONS

+
+    
All attached images much have the same width and height; otherwise, checkFramebufferStatus returns FRAMEBUFFER_INCOMPLETE_DIMENSIONS.

+
+    
In OpenGL ES 3, attached images for a framebuffer need not to have the same width and height to be framebuffer complete, and FRAMEBUFFER_INCOMPLETE_DIMENSIONS is not one of the valid return values for checkFramebufferStatus. However, in Direct3D 11, on top of which OpenGL ES 3 behavior is emulated in Windows, all render targets must have the same size in all dimensions (see msdn manual page). Emulation of the ES3 semantic on top of DirectX 11 will be inefficient. In order to have consistent WebGL 2 behaviors across platforms, it is reasonable to keep the OpenGL ES 2 / WebGL 1 restriction for WebGL 2 that all attached images must have the same width and height.

+
+    
5.28 Uniform block matching

+
+    

+        In the WebGL 2.0 API, layout qualifiers row_major and column_major
+        are required to match in matched uniform blocks even when they are applied exclusively on
+        non-matrix variables.
+    

+
+    

+        This uniform block matching rule is known to be inconsistent across OpenGL ES 3.0
+        implementations.
+    

+
+    
5.29 Framebuffer contents after invalidation

+    

+        In OpenGL ES 3.0, after calling invalidateFramebuffer or invalidateSubFramebuffer,
+        the affected region's contents become effectively undefined. In WebGL 2.0, it is required for the contents
+        to either stay unchanged or become all 0.
+    

+
+    

+        It is acceptable for WebGL 2.0 implementations to make invalidateFramebuffer or
+        invalidateSubFramebuffer a no-op.
+    

+
+    
5.30 No ArrayBufferView matching texture type FLOAT_32_UNSIGNED_INT_24_8_REV

+    

+        In texImage2D and texImage3D with ArrayBufferView, if
+        type is FLOAT_32_UNSIGNED_INT_24_8_REV and srcData is not
+        null, generates an INVALID_OPERATION.
+    

+
+    

+        In texSubImage2D and texSubImage3D with ArrayBufferView, if type is
+        FLOAT_32_UNSIGNED_INT_24_8_REV, generates an INVALID_ENUM.
+    

+
+
+    
5.31 VertexAttrib function must match shader attribute type

+
+    

+        If any of the following situations are true, attempting to draw with drawArrays,
+        drawElements, drawRangeElements or their instanced variants generates an
+        INVALID_OPERATION error:
+    

+
+    
    
+      
  • 
+        vertexAttribPointer, vertexAttrib{1234}f, or vertexAttrib{1234}fv
+         is used and the base type of the shader attribute at slot index is not
+        floating-point (e.g. is signed or unsigned integer);
+      
    • 
+      
  • 
+        vertexAttribIPointer is used with type UNSIGNED_BYTE,
+        UNSIGNED_SHORT or UNSIGNED_INT, or vertexAttribI4ui or
+        vertexAttribI4uiv is used, and the base type of the shader attribute at slot
+        index is not unsigned integer (e.g. is floating-point or signed integer);
+      
    • 
+      
  • 
+        vertexAttribIPointer is used with type BYTE,
+        SHORT or INT, or vertexAttribI4i or 
+        vertexAttribI4iv is used, and the base type of the shader attribute at slot
+        index is not signed integer (e.g. is floating-point or unsigned integer).
+      
    • 
+    

+
+    

+        This undefined behavior is in the OpenGL ES 3.0 specification section 2.8 
+        (
+        OpenGL ES 3.0.4 §2.8).
+    

+
+    
5.32 Transform feedback primitive capture

+
+    

+        If any output variable is specified to be streamed to a buffer object but not actually
+        written by a vertex shader, the value is set to 0.
+    

+
+    

+        This undefined behavior is in the OpenGL ES 3.0 specification section 2.15.2 
+        (
+        OpenGL ES 3.0.4 §2.15.2).
+    

+
+    
5.33 gl_FragDepth

+
+    

+        If a fragment shader statically assigns a value to gl_FragDepth, for any fragment
+        where statements assigning a value to gl_FragDepth are not executed, the value 0 is used.
+    

+
+    

+        This undefined behavior is in the OpenGL ES 3.0 specification section 3.9.2 
+        (
+        OpenGL ES 3.0.4 §3.9.2).
+    

+
+    
5.34 Framebuffer color attachments

+
+    

+        If an image is attached to more than one color attachment point in a framebuffer,
+        checkFramebufferStatus returns FRAMEBUFFER_UNSUPPORTED.
+        An image can be an individual mip level, an array slice (from either 2D array
+        or cube map textures), or a 3D texture slice.
+    

+
+    

+        This is a limitation of Direct3D 11, on top of which OpenGL ES 3 behavior is emulated on Windows.
+        (see msdn manual
+        page). In order to have consistent WebGL 2 behavior across platforms, it is reasonable to add
+        this limitation in WebGL 2 for all platforms.
+    

+
+    
5.35 Pixel store parameters for uploads from TexImageSource

+
+    
UNPACK_ALIGNMENT and UNPACK_ROW_LENGTH are ignored.
+       UNPACK_ALIGNMENT is specified in bytes, and is implicit and
+       implementation-dependent for TexImageSource objects. UNPACK_ROW_LENGTH is
+       currently unused.

+    
Subrect selection is possible using UNPACK_ params.
+       UNPACK_SKIP_PIXELS and UNPACK_SKIP_ROWS determine the origin of the
+       subrect, with the width and height arguments determining the size of the subrect.

+    
For 3D textures, the width, height, and depth
+       arguments specify a rectangular region of a texel array to unpack to.
+       UNPACK_SKIP_IMAGES and UNPACK_IMAGE_HEIGHT allow selection of
+       multiple slices from the 2D source.  UNPACK_IMAGE_HEIGHT determines the stride,
+       in rows, between two slices. For example, a TexImageSource 30 pixels tall may
+       have the top 10 and bottom 10 rows uploaded into two slices of a 3D texture by uploading with
+       height equal to 10, UNPACK_IMAGE_HEIGHT set to 20, and
+       depth equal to 2.  If UNPACK_IMAGE_HEIGHT is 0, the stride, in
+       rows, between two slices defaults to height.

+    
For an HTMLImageElement 20 pixels wide, passing width = 10 for
+       texture upload will cause only the left half of the image to be selected, thus uploaded. The
+       resulting texture will have a width of 10. If, additionally in this example,
+       UNPACK_SKIP_PIXELS is set to 10, only the right half of the image is selected
+       for unpack.

+    
Also, UNPACK_SKIP_IMAGES applies only to 3D entrypoints, not to 2D entrypoints.

+    
+    
Looking at another example, the above 32x48 image of six colors, each of size 16x16, is uploaded to
+      a 3D texture of  width = 2, height = 1, and depth = 3.
+      
    
+        
  • If UNPACK_SKIP_PIXELS is 0, UNPACK_SKIP_ROWS is 0, and UNPACK_IMAGE_HEIGHT
+            is 0, the entire texel array is set to red.
    • 
+        
  • If UNPACK_SKIP_PIXELS is 16, UNPACK_SKIP_ROWS is 16, and UNPACK_IMAGE_HEIGHT
+            is 0, the entire texel array is set to yellow.
    • 
+        
  • If UNPACK_SKIP_PIXELS is 0, UNPACK_SKIP_ROWS is 0, and UNPACK_IMAGE_HEIGHT
+            is 16, the first slice of the texel array is red, the second slice is blue, and the third slice is purple.
    • 
+        
  • If UNPACK_SKIP_PIXELS is 16, UNPACK_SKIP_ROWS is 0, and UNPACK_IMAGE_HEIGHT
+            is 16, the first slice of the texel array is green, the second slice is yellow, and the third slice is pink.
    • 
+      

+    

+
+    
5.36 Pixel store parameter constraints

+
+    

+        Define:
+        
    
+          
  • DataStoreWidth := ROW_LENGTH ? ROW_LENGTH : width
    • 
+          
  • DataStoreHeight := IMAGE_HEIGHT ? IMAGE_HEIGHT : height
    • 
+        

+    

+
+    

+        If PACK_SKIP_PIXELS + width > DataStoreWidth, readPixels
+        generates an INVALID_OPERATION error.
+    

+
+    

+        If UNPACK_SKIP_PIXELS + width > DataStoreWidth,
+        texImage2D and texSubImage2D generate an
+        INVALID_OPERATION error. This does not apply to texImage2D if no
+        PIXEL_UNPACK_BUFFER is bound and srcData is null.
+    

+
+    

+        If UNPACK_SKIP_PIXELS + width > DataStoreWidth or
+        UNPACK_SKIP_ROWS + height >  DataStoreHeight, texImage3D
+        and texSubImage3D generate an INVALID_OPERATION error. This does
+        not apply to texImage3D if no PIXEL_UNPACK_BUFFER is bound and
+        srcData is null.
+    

+
+    

+      
These constraints normalize the use of these parameters to specify a sub region where
+         pixels are stored. For example, in readPixels cases, if we want to store
+         pixels to a sub area of the entire data store, we can use PACK_ROW_LENGTH to
+         specify the data store width, and PACK_SKIP_PIXELS,
+         PACK_SKIP_ROWS, width and height to specify the subarea's
+         xoffset, yoffset, width, and height.
+
+      
These contraints also forbid row and image overlap, where the situations are not tested in
+         the OpenGL ES 3.0 DEQP test suites, and many drivers behave incorrectly. They also forbid
+         skipping random pixels or rows, but that can be achieved by adjusting the data store offset
+         accordingly.
+
+      
Further, for uploads from TexImageSource, implied
+         UNPACK_ROW_LENGTH and UNPACK_ALIGNMENT are not strictly defined.
+         These restrictions ensure consistent and efficient behavior regardless of implied
+         UNPACK_ params.
+    

+
+    
5.37 No ETC2 and EAC compressed texture formats

+    
OpenGL ES 3.0 requires support for the following ETC2 and EAC compressed texture formats:
+       COMPRESSED_R11_EAC, COMPRESSED_SIGNED_R11_EAC, COMPRESSED_RG11_EAC,
+       COMPRESSED_SIGNED_RG11_EAC, COMPRESSED_RGB8_ETC2, COMPRESSED_SRGB8_ETC2,
+       COMPRESSED_RGB8_PUNCHTHROUGH_ALPHA1_ETC2, COMPRESSED_SRGB8_PUNCHTHROUGH_ALPHA1_ETC2,
+       COMPRESSED_RGBA8_ETC2_EAC, and COMPRESSED_SRGB8_ALPHA8_ETC2_EAC.
+
+    
These texture formats are not supported by default in WebGL 2.0.
+
+    

+        
These formats are not natively supported by most desktop GPU hardware.
+           As such, supporting these formats requires software decompression in either the
+           WebGL implementation or the underlying driver. This results in a drastic
+           increase in video memory usage, causing performance losses which are
+           invisible to the WebGL application.
+        
On hardware which supports the ETC2 and EAC compressed texture formats natively
+           (e.g. mobile OpenGL ES 3.0+ hardware), they may be exposed via the extension
+           WEBGL_compressed_texture_etc.
+    

+
+
+
+    
6 References

+
+    

+        
[WEBGL10]

+        

+            WebGL Specification 1.0.4 Editor's Draft,
+            Dean Jackson, Jeff Gilbert.
+        

+        
[CANVAS]

+        

+            HTML5: The Canvas Element,
+            World Wide Web Consortium (W3C).
+        

+        
[CANVASCONTEXTS]

+        

+            Canvas Context Registry,
+            WHATWG.
+        

+        
[GLES30]

+        

+            OpenGL® ES Version 3.0.4,
+            B. Lipchak 2014.
+        

+        
[GLES30GLSL]

+        

+            The OpenGL® ES Shading Language Version 3.00.6,
+            R. Simpson, January 2016.
+        

+        
[REGISTRY]

+        

+            WebGL Extension Registry
+        

+        
[RFC2119]

+        

+            Key words for use in RFCs to Indicate Requirement Levels,
+            S. Bradner. IETF, March 1997.
+        

+        
[WEBIDL]

+        

+            Web IDL: W3C Editor’s Draft,
+            C. McCormack, B. Zbarsky, T. Langel.
+        

+    

+
+
+
+
\ No newline at end of file
diff --git a/test/node/parsing/XMLHttpRequest/0 b/test/node/parsing/XMLHttpRequest/0
new file mode 100644
index 0000000..dd2d2aa
--- /dev/null
+++ b/test/node/parsing/XMLHttpRequest/0
@@ -0,0 +1,61 @@
+[Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface XMLHttpRequestEventTarget : EventTarget {
+  // event handlers
+  attribute EventHandler onloadstart;
+  attribute EventHandler onprogress;
+  attribute EventHandler onabort;
+  attribute EventHandler onerror;
+  attribute EventHandler onload;
+  attribute EventHandler ontimeout;
+  attribute EventHandler onloadend;
+};
+
+[Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface XMLHttpRequestUpload : XMLHttpRequestEventTarget {
+};
+
+enum XMLHttpRequestResponseType {
+  "",
+  "arraybuffer",
+  "blob",
+  "document",
+  "json",
+  "text"
+};
+
+[Constructor,
+ Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface XMLHttpRequest : XMLHttpRequestEventTarget {
+  // event handler
+  attribute EventHandler onreadystatechange;
+
+  // states
+  const unsigned short UNSENT = 0;
+  const unsigned short OPENED = 1;
+  const unsigned short HEADERS_RECEIVED = 2;
+  const unsigned short LOADING = 3;
+  const unsigned short DONE = 4;
+  readonly attribute unsigned short readyState;
+
+  // request
+  void open(ByteString method, USVString url);
+  void open(ByteString method, USVString url, boolean async, optional USVString? username = null, optional USVString? password = null);
+  void setRequestHeader(ByteString name, ByteString value);
+           attribute unsigned long timeout;
+           attribute boolean withCredentials;
+  [SameObject] readonly attribute XMLHttpRequestUpload upload;
+  void send(optional (Document or BodyInit)? body = null);
+  void abort();
+
+  // response
+  readonly attribute USVString responseURL;
+  readonly attribute unsigned short status;
+  readonly attribute ByteString statusText;
+  ByteString? getResponseHeader(ByteString name);
+  ByteString getAllResponseHeaders();
+  void overrideMimeType(DOMString mime);
+           attribute XMLHttpRequestResponseType responseType;
+  readonly attribute any response;
+  readonly attribute USVString responseText;
+  [Exposed=Window] readonly attribute Document? responseXML;
+};
diff --git a/test/node/parsing/XMLHttpRequest/1 b/test/node/parsing/XMLHttpRequest/1
new file mode 100644
index 0000000..14c2261
--- /dev/null
+++ b/test/node/parsing/XMLHttpRequest/1
@@ -0,0 +1,15 @@
+typedef (File or USVString) FormDataEntryValue;
+
+[Constructor(optional HTMLFormElement form),
+ Exposed=(Window,Worker)]
+interface FormData {
+  void append(USVString name, USVString value);
+  void append(USVString name, Blob blobValue, optional USVString filename);
+  void delete(USVString name);
+  FormDataEntryValue? get(USVString name);
+  sequence getAll(USVString name);
+  boolean has(USVString name);
+  void set(USVString name, USVString value);
+  void set(USVString name, Blob blobValue, optional USVString filename);
+  iterable;
+};
diff --git a/test/node/parsing/XMLHttpRequest/2 b/test/node/parsing/XMLHttpRequest/2
new file mode 100644
index 0000000..f507dc3
--- /dev/null
+++ b/test/node/parsing/XMLHttpRequest/2
@@ -0,0 +1,13 @@
+[Constructor(DOMString type, optional ProgressEventInit eventInitDict),
+ Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface ProgressEvent : Event {
+  readonly attribute boolean lengthComputable;
+  readonly attribute unsigned long long loaded;
+  readonly attribute unsigned long long total;
+};
+
+dictionary ProgressEventInit : EventInit {
+  boolean lengthComputable = false;
+  unsigned long long loaded = 0;
+  unsigned long long total = 0;
+};
diff --git a/test/node/parsing/XMLHttpRequest/3 b/test/node/parsing/XMLHttpRequest/3
new file mode 100644
index 0000000..d3c2808
--- /dev/null
+++ b/test/node/parsing/XMLHttpRequest/3
@@ -0,0 +1,89 @@
+[Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface XMLHttpRequestEventTarget : EventTarget {
+  // event handlers
+  attribute EventHandler onloadstart;
+  attribute EventHandler onprogress;
+  attribute EventHandler onabort;
+  attribute EventHandler onerror;
+  attribute EventHandler onload;
+  attribute EventHandler ontimeout;
+  attribute EventHandler onloadend;
+};
+
+[Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface XMLHttpRequestUpload : XMLHttpRequestEventTarget {
+};
+
+enum XMLHttpRequestResponseType {
+  "",
+  "arraybuffer",
+  "blob",
+  "document",
+  "json",
+  "text"
+};
+
+[Constructor,
+ Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface XMLHttpRequest : XMLHttpRequestEventTarget {
+  // event handler
+  attribute EventHandler onreadystatechange;
+
+  // states
+  const unsigned short UNSENT = 0;
+  const unsigned short OPENED = 1;
+  const unsigned short HEADERS_RECEIVED = 2;
+  const unsigned short LOADING = 3;
+  const unsigned short DONE = 4;
+  readonly attribute unsigned short readyState;
+
+  // request
+  void open(ByteString method, USVString url);
+  void open(ByteString method, USVString url, boolean async, optional USVString? username = null, optional USVString? password = null);
+  void setRequestHeader(ByteString name, ByteString value);
+           attribute unsigned long timeout;
+           attribute boolean withCredentials;
+  [SameObject] readonly attribute XMLHttpRequestUpload upload;
+  void send(optional (Document or BodyInit)? body = null);
+  void abort();
+
+  // response
+  readonly attribute USVString responseURL;
+  readonly attribute unsigned short status;
+  readonly attribute ByteString statusText;
+  ByteString? getResponseHeader(ByteString name);
+  ByteString getAllResponseHeaders();
+  void overrideMimeType(DOMString mime);
+           attribute XMLHttpRequestResponseType responseType;
+  readonly attribute any response;
+  readonly attribute USVString responseText;
+  [Exposed=Window] readonly attribute Document? responseXML;
+};
+typedef (File or USVString) FormDataEntryValue;
+
+[Constructor(optional HTMLFormElement form),
+ Exposed=(Window,Worker)]
+interface FormData {
+  void append(USVString name, USVString value);
+  void append(USVString name, Blob blobValue, optional USVString filename);
+  void delete(USVString name);
+  FormDataEntryValue? get(USVString name);
+  sequence getAll(USVString name);
+  boolean has(USVString name);
+  void set(USVString name, USVString value);
+  void set(USVString name, Blob blobValue, optional USVString filename);
+  iterable;
+};
+[Constructor(DOMString type, optional ProgressEventInit eventInitDict),
+ Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface ProgressEvent : Event {
+  readonly attribute boolean lengthComputable;
+  readonly attribute unsigned long long loaded;
+  readonly attribute unsigned long long total;
+};
+
+dictionary ProgressEventInit : EventInit {
+  boolean lengthComputable = false;
+  unsigned long long loaded = 0;
+  unsigned long long total = 0;
+};
diff --git a/test/node/parsing/XMLHttpRequest/spec.html b/test/node/parsing/XMLHttpRequest/spec.html
new file mode 100644
index 0000000..01e6b15
--- /dev/null
+++ b/test/node/parsing/XMLHttpRequest/spec.html
@@ -0,0 +1,1999 @@
+
+
+
+  
+  
+  
+  XMLHttpRequest Standard
+  
+  
+  
+  
+
+ File an issue about the selected text
+  

+   
 

+   

+    
XMLHttpRequest

+    
Living Standard — Last Updated 

+   

+   
+   

+  

+  

+   
Abstract

+   
The XMLHttpRequest Standard defines an API that provides scripted client functionality for transferring data between a client and a server.

+  

+  
+  

+
+
+
+   
1. Introduction

+   
This section is non-normative. 

+   
The XMLHttpRequest object is an API for fetching resources. 

+   
The name XMLHttpRequest is historical and has no bearing on its functionality. 

+   

+     
+    
Some simple code to do something with data from an XML document
+ fetched over the network: 

+
function processData(data) {
+  // taking care of data
+}
+
+function handler() {
+  if(this.status == 200 &&
+    this.responseXML != null &&
+    this.responseXML.getElementById('test').textContent) {
+    // success!
+    processData(this.responseXML.getElementById('test').textContent);
+  } else {
+    // something went wrong
+    …
+  }
+}
+
+var client = new XMLHttpRequest();
+client.onload = handler;
+client.open("GET", "unicorn.xml");
+client.send();

+    
If you just want to log a message to the server: 

+
function log(message) {
+  var client = new XMLHttpRequest();
+  client.open("POST", "/log");
+  client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
+  client.send(message);
+}

+    
Or if you want to check the status of a document on the server: 

+
function fetchStatus(address) {
+  var client = new XMLHttpRequest();
+  client.onload = function() {
+    // in case of network errors this might not give reliable results
+    returnStatus(this.status);
+  }
+  client.open("HEAD", address);
+  client.send();
+}

+   

+   
1.1. Specification history

+   
The XMLHttpRequest object was initially defined as part of
+the WHATWG’s HTML effort. (Based on Microsoft’s implementation many years prior.)
+It moved to the W3C in 2006. Extensions (e.g. progress events and
+cross-origin requests) to XMLHttpRequest were developed in a
+separate draft (XMLHttpRequest Level 2) until end of 2011, at which point
+the two drafts were merged and XMLHttpRequest became a single
+entity again from a standards perspective. End of 2012 it moved back to the
+WHATWG. 

+   
Discussion that led to the current draft can be found in the following mailing list
+archives: 

+   
+   
2. Conformance

+   
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 specification are to be
+interpreted as described in RFC2119. For readability, these words do
+not appear in all uppercase letters in this specification. [RFC2119] 

+   
2.1. Extensibility

+   
User agents, Working Groups, and other interested parties are strongly encouraged to discuss new features with the WHATWG
+community. 

+   
3. Terminology

+   
This specification uses terminology, cross-linked throughout, from DOM,
+DOM Parsing and Serialization, Encoding, Fetch, File API, HTML, HTTP, URL, Web IDL, and
+XML. 

+   
[DOM] [DOMPS] [ENCODING] [FETCH] [FILEAPI] [HTML] [HTTP] [URL] [WEBIDL] [XML] [XMLNS]

+   
It uses the typographic conventions from HTML. [HTML] 

+   
The term user credentials for the purposes of this
+specification means cookies, HTTP authentication, and TLS client certificates.
+Specifically it does not refer to proxy authentication or the Origin header. [COOKIES] 

+   
4. Interface XMLHttpRequest

+
[Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface XMLHttpRequestEventTarget : EventTarget {
+  // event handlers
+  attribute EventHandler onloadstart;
+  attribute EventHandler onprogress;
+  attribute EventHandler onabort;
+  attribute EventHandler onerror;
+  attribute EventHandler onload;
+  attribute EventHandler ontimeout;
+  attribute EventHandler onloadend;
+};
+
+[Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface XMLHttpRequestUpload : XMLHttpRequestEventTarget {
+};
+
+enum XMLHttpRequestResponseType {
+  "",
+  "arraybuffer",
+  "blob",
+  "document",
+  "json",
+  "text"
+};
+
+[Constructor,
+ Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface XMLHttpRequest : XMLHttpRequestEventTarget {
+  // event handler
+  attribute EventHandler onreadystatechange;
+
+  // states
+  const unsigned short UNSENT = 0;
+  const unsigned short OPENED = 1;
+  const unsigned short HEADERS_RECEIVED = 2;
+  const unsigned short LOADING = 3;
+  const unsigned short DONE = 4;
+  readonly attribute unsigned short readyState;
+
+  // request
+  void open(ByteString method, USVString url);
+  void open(ByteString method, USVString url, boolean async, optional USVString? username = null, optional USVString? password = null);
+  void setRequestHeader(ByteString name, ByteString value);
+           attribute unsigned long timeout;
+           attribute boolean withCredentials;
+  [SameObject] readonly attribute XMLHttpRequestUpload upload;
+  void send(optional (Document or BodyInit)? body = null);
+  void abort();
+
+  // response
+  readonly attribute USVString responseURL;
+  readonly attribute unsigned short status;
+  readonly attribute ByteString statusText;
+  ByteString? getResponseHeader(ByteString name);
+  ByteString getAllResponseHeaders();
+  void overrideMimeType(DOMString mime);
+           attribute XMLHttpRequestResponseType responseType;
+  readonly attribute any response;
+  readonly attribute USVString responseText;
+  [Exposed=Window] readonly attribute Document? responseXML;
+};

+   
An XMLHttpRequest object has an associated XMLHttpRequestUpload object. 

+   
An XMLHttpRequest object has an associated state, which is one of unsent, opened, headers received, loading, and done. Unless stated otherwise it is unsent. 

+   
An XMLHttpRequest object has an associated send() flag. Unless stated otherwise it is unset. 

+   
An XMLHttpRequest object has an associated stop timeout flag.
+Unless stated otherwise it is unset. 

+   
4.1. Constructors

+   

+    
client = new XMLHttpRequest() 
+    
Returns a new XMLHttpRequest object. 
+   

+   
The XMLHttpRequest() constructor, when invoked, must return a new XMLHttpRequest object. 

+   
4.2. Garbage collection

+   
An XMLHttpRequest object must not be garbage collected if its state is either opened with the send() flag set, headers received, or loading, and it has one or more event listeners registered whose type is one of readystatechange, progress, abort, error, load, timeout, and loadend. 

+   
If an XMLHttpRequest object is garbage collected while its
+connection is still open, the user agent must terminate the request. 

+   
4.3. Event handlers

+   
The following are the event handlers (and their corresponding event handler event types)
+that must be supported on objects implementing an interface that inherits
+from XMLHttpRequestEventTarget as attributes: 

+   
+    
+     
+      
+     
+      
+      
+      
+      
+      
+      
+      
event handler 
+      event handler event type 
+    
onloadstart 
+      loadstart 
+     
onprogress 
+      progress 
+     
onabort 
+      abort 
+     
onerror 
+      error 
+     
onload 
+      load 
+     
ontimeout 
+      timeout 
+     
onloadend 
+      loadend 
+   

+   
The following is the event handler (and its corresponding event handler event type) that must be
+supported as attribute solely by the XMLHttpRequest object: 

+   
+    
+     
+      
+     
+      
event handler 
+      event handler event type 
+    
onreadystatechange 
+      readystatechange 
+   

+   
4.4. States

+   

+    
client . readyState 
+    

+     
Returns client’s state. 

+   

+   
The readyState attribute’s getter must return the value from the table below in the cell of the second column, from
+the row where the value in the cell in the first column is context object’s state: 

+   
+    
+     
+      
+      
+      
+      
+      
unsent 
+      UNSENT (numeric value 0) 
+      The object has been constructed. 
+     
opened 
+      OPENED (numeric value 1) 
+      The open() method has
+   been successfully invoked. During this state request headers can be set using setRequestHeader() and the fetch can be initiated using the send() method. 
+     
headers received 
+      HEADERS_RECEIVED (numeric value 2) 
+      All redirects (if any) have been followed and all HTTP headers of the response have been received. 
+     
loading 
+      LOADING (numeric value 3) 
+      The response’s body is being received. 
+     
done 
+      DONE (numeric value 4) 
+      The data transfer has been completed or something went wrong during the transfer
+   (e.g. infinite redirects). 
+   

+   
4.5. Request

+   
Each XMLHttpRequest object has the following request-associated concepts: request method, request URL, author request headers, request body, synchronous flag, upload complete flag, and upload listener flag. 

+   
The author request headers is an initially empty header list. 

+   
The request body is initially null. 

+   
The synchronous flag, upload complete flag, and upload listener flag are initially unset. 

+   

+   
To terminate the request, terminate the fetch algorithm operated by the XMLHttpRequest object with reason fatal. 

+   
4.5.1. The open() method

+   

+    
client . open(method, url [, async = true [, username = null [, password = null]]]) 
+    

+     
Sets the request method, request URL, and synchronous flag. 

+     
Throws a SyntaxError exception if
+  either method is not a valid HTTP method or url cannot be parsed. 

+     
Throws a SecurityError exception
+  if method is a case-insensitive match for
+  `CONNECT`, `TRACE` or `TRACK`. 

+     
Throws an InvalidAccessError exception if async is false, current global object is a Window object, and the timeout attribute is not zero or the responseType attribute is not the empty string. 

+   

+   
Synchronous XMLHttpRequest outside of workers is in the process of being removed from the web platform as it has
+detrimental effects to the end user’s experience. (This is a long process that takes many
+years.) Developers must not pass false for the async argument when current global object is a Window object. User agents are strongly encouraged to warn about such usage in developer tools and may
+experiment with throwing an InvalidAccessError exception when it occurs. 

+   
The open(method, url) and open(method, url, async, username, password) methods, when invoked, must run these steps: 

+   
    
+    
  1. 
+     
    If context object’s relevant settings object has a responsible document and it is not fully active, throw an InvalidStateError exception. 
    
+    
  2. 
+     
    If method is not a method, throw a SyntaxError exception. 
    
+    
  3. 
+     
    If method is a forbidden method, throw a SecurityError exception. 
    
+    
  4. 
+     
    Normalize method. 
    
+    
  5. 
+     
    Let parsedURL be the result of parsing url with context object’s relevant settings object’s API base URL. 
    
+    
  6. 
+     
    If parsedURL is failure, throw a SyntaxError exception. 
    
+    
  7. 
+     
    If the async argument is omitted, set async to true, and set username and password to null. 
    
+     
    Unfortunately legacy content prevents treating the async argument being undefined identical from it being omitted. 
    
+    
  8. 
+     
    If parsedURL’s host is non-null, run these substeps: 
    
+     
      
+      
    1. 
+       
      If the username argument is not null, set the username given parsedURL and username. 
      
+      
    2. 
+       
      If the password argument is not null, set the password given parsedURL and password. 
      
+     
    
+    
  9. 
+     
    If async is false, current global object is a Window object, and the timeout attribute value is not zero
+ or the responseType attribute value is not the
+ empty string, then throw an InvalidAccessError exception. 
    
+    
  10. 
+     
    Terminate the request. 
    
+     
    A fetch can be
+  ongoing at this point. 
    
+    
  11. 
+     
    Set variables associated with the object as follows: 
    
+     
+    
  12. 
+     
    If the state is not opened, run these substeps: 
    
+     
      
+      
    1. 
+       
      Set state to opened. 
      
+      
    2. 
+       
      Fire an event named readystatechange. 
      
+     
    
+   

+   
The reason there are two open() methods defined is due to a limitation of
+the editing software used to write the XMLHttpRequest Standard. 

+   
4.5.2. The setRequestHeader() method

+   

+    
client . setRequestHeader(name, value) 
+    

+     
Combines a header in author request headers. 

+     
Throws an InvalidStateError exception if either state is not opened or the send() flag is set. 

+     
Throws a SyntaxError exception if name is not a header name or if value is not a header value. 

+   

+   
As indicated in the algorithm below certain headers cannot
+be set and are left up to the user agent. In addition there are certain
+other headers the user agent will take control of if they are not set by
+the author as indicated at the end of the send() method section. 

+   
The setRequestHeader(name, value) method must run these steps: 

+   
    
+    
  1. 
+     
    If state is not opened, throw an InvalidStateError exception. 
    
+    
  2. 
+     
    If the send() flag is set, throw an InvalidStateError exception. 
    
+    
  3. 
+     
    Normalize value. 
    
+    
  4. 
+     
    If name is not a name or value is not a value, throw a SyntaxError exception. 
    
+     
    An empty byte sequence represents an empty header value. 
    
+    
  5. 
+     
    Terminate these steps if name is a forbidden header name. 
    
+    
  6. 
+     
    Combine name/value in author request headers. 
    
+   

+   

+     
+    
Some simple code demonstrating what happens when setting the same
+ header twice: 

+
// The following script:
+var client = new XMLHttpRequest();
+client.open('GET', 'demo.cgi');
+client.setRequestHeader('X-Test', 'one');
+client.setRequestHeader('X-Test', 'two');
+client.send();
+
+// …results in the following header being sent:
+// X-Test: one, two

+   

+   
4.5.3. The timeout attribute

+   

+    
client . timeout 
+    

+     
Can be set to a time in milliseconds. When set to a non-zero value
+  will cause fetching to
+  terminate after the given time has passed. When the time has passed, the request has
+  not yet completed, and the synchronous flag is unset, a timeout event will then be dispatched,
+  or a TimeoutError exception will be thrown otherwise
+  (for the send() method). 

+     
When set: throws an InvalidAccessError exception if
+  the synchronous flag is set and current global object is a Window object. 

+   

+   
The timeout attribute must return its value. Initially its value must be zero. 

+   
Setting the timeout attribute must run these steps: 

+   
    
+    
  1. 
+     
    If current global object is a Window object and the synchronous flag is set, throw an InvalidAccessError exception. 
    
+    
  2. 
+     
    Set its value to the new value. 
    
+   

+   
This implies that the timeout attribute can be
+set while fetching is in
+progress. If that occurs it will still be measured relative to the start
+of fetching. 

+   
4.5.4. The withCredentials attribute

+   

+    
client . withCredentials 
+    

+     
True when user credentials are to be included in a
+  cross-origin request. False when they are to be excluded in a
+  cross-origin request and when cookies are to be ignored in its response.
+  Initially false. 

+     
When set: throws an InvalidStateError exception if state is not unsent or opened, or if the send() flag is set. 

+   

+   
The withCredentials attribute must return its value. Initially its value must be false. 

+   
Setting the withCredentials attribute must run these steps: 

+   
    
+    
  1. 
+     
    If state is not unsent or opened, throw an InvalidStateError exception. 
    
+    
  2. 
+     
    If the send() flag is set, throw an InvalidStateError exception. 
    
+    
  3. 
+     
    Set the withCredentials attribute’s value to the given value. 
    
+   

+   
The withCredentials attribute has no effect when fetching same-origin resources. 

+   
4.5.5. The upload attribute

+   

+    
client . upload 
+    

+     
Returns the associated XMLHttpRequestUpload object. It can be used to gather transmission information when data is
+ transferred to a server. 

+   

+   
The upload attribute must return the associated XMLHttpRequestUpload object. 

+   
As indicated earlier, each XMLHttpRequest object has an associated XMLHttpRequestUpload object. 

+   
4.5.6. The send() method

+   

+    
client . send([body = null]) 
+    

+     
Initiates the request. The optional argument provides the request body. The argument is ignored if request method is GET or HEAD. 

+     
Throws an InvalidStateError exception if either state is not opened or the send() flag is set. 

+   

+   
The send(body) method must run these steps: 

+   
    
+    
  1. 
+     
    If state is not opened, throw an InvalidStateError exception. 
    
+    
  2. 
+     
    If the send() flag is set, throw an InvalidStateError exception. 
    
+    
  3. 
+     
    If the request method is GET or HEAD, set body to null. 
    
+    
  4. 
+     
    If body is null, go to the next step. 
    
+     
    Otherwise, let encoding and mimeType be null, and then follow these
+  rules, switching on body: 
    
+     
    
+      
    Document 
+      
    
+       
    Set encoding to `UTF-8`. 
    
+       
    Set mimeType to `text/html` if body is an HTML document, and to `application/xml` otherwise. Then append
+    `;charset=UTF-8` to mimeType. 
    
+       
    Set request body to body, serialized, converted to Unicode, and utf-8 encoded. 
    
+      
    BodyInit 
+      
    
+       
    If body is a string, set encoding to
+    `UTF-8`. 
    
+       
    Set request body and mimeType to the result of extracting body. 
    
+     
    
+     
    If mimeType is non-null and author request headers does not contain `Content-Type`, then append `Content-Type`/mimeType to author request headers. 
    
+     
    Otherwise, if the header whose name is a byte-case-insensitive match for `Content-Type` in author request headers has a value that is a valid MIME type, which has a `charset`
+  parameter whose value is not a byte-case-insensitive match for encoding, and encoding is not null, then set all the `charset` parameters whose value is
+  not a byte-case-insensitive match for encoding of that header’s value to encoding. 
    
+    
  5. 
+     
    If one or more event listeners are registered on the associated XMLHttpRequestUpload object, then set upload listener flag. 
    
+    
  6. 
+     
    Let req be a new request, initialized as
+  follows: 
    
+     
    
+      
    method 
+      
    request method 
+      
    url 
+      
    request URL 
+      
    header list 
+      
    author request headers 
+      
    unsafe-request flag 
+      
    Set. 
+      
    body 
+      
    request body 
+      
    client 
+      
    context object’s relevant settings object 
+      
    synchronous flag 
+      
    Set if the synchronous flag is set. 
+      
    mode 
+      
    "cors" 
+      
    use-CORS-preflight flag 
+      
    Set if upload listener flag is set. 
+      
    credentials mode 
+      
    If the withCredentials attribute value is true, "include", and "same-origin"
+   otherwise. 
+      
    use-URL-credentials flag 
+      
    Set if either request URL’s username is not the empty string or request URL’s password is non-null. 
+     
    
+    
  7. 
+     
    Unset the upload complete flag. 
    
+    
  8. 
+     
    If req’s body is null,
+ set the upload complete flag. 
    
+    
  9. 
+     
    Set the send() flag. 
    
+    
  10. 
+     
    If the synchronous flag is unset, run these substeps: 
    
+     
      
+      
    1. 
+       
      Fire a progress event named loadstart with 0 and 0. 
      
+      
    2. 
+       
      If the upload complete flag is unset and upload listener flag is
+   set, then fire a progress event named loadstart on the XMLHttpRequestUpload object with 0 and req’s body’s total bytes. 
      
+      
    3. 
+       
      If state is not opened or the send() flag is unset, then
+   return. 
      
+      
    4. 
+       
      Fetch req.
+    Handle the tasks queued on the networking task source per below. 
      
+       
      Run these subsubsteps in parallel: 
      
+       
        
+        
      1. 
+         
        Wait until either req’s done flag is set or 
        
+         
          
+          
        1. 
+           
          the timeout attribute value number of milliseconds has
+       passed since these subsubsteps started 
          
+          
        2. 
+           
          while timeout attribute value is not zero. 
          
+         
        
+        
      2. 
+         
        If req’s done flag is unset, then terminate fetching with reason timeout. 
        
+       
      
+       
      To process request body for request, run these subsubsteps: 
      
+       
        
+        
      1. 
+         
        If not roughly 50ms have passed since these subsubsteps were last invoked,
+     terminate these subsubsteps. 
        
+        
      2. 
+         
        If upload listener flag is set, then fire a progress event named progress on the XMLHttpRequestUpload object with request’s body’s transmitted bytes and request’s body’s total bytes. 
        
+       
      
+       
      These subsubsteps are only invoked when new bytes are transmitted. 
      
+       
      To process request end-of-body for request, run these subsubsteps: 
      
+       
        
+        
      1. 
+         
        Set the upload complete flag. 
        
+        
      2. 
+         
        If upload listener flag is unset, then terminate these subsubsteps. 
        
+        
      3. 
+         
        Let transmitted be request’s body’s transmitted bytes. 
        
+        
      4. 
+         
        Let length be request’s body’s total bytes. 
        
+        
      5. 
+         
        Fire a progress event named progress on the XMLHttpRequestUpload object with transmitted and length. 
        
+        
      6. 
+         
        Fire a progress event named load on the XMLHttpRequestUpload object with transmitted and length. 
        
+        
      7. 
+         
        Fire a progress event named loadend on the XMLHttpRequestUpload object with transmitted and length. 
        
+       
      
+       
      To process response for response,
+    run these subsubsteps: 
      
+       
        
+        
      1. 
+         
        If the stop timeout flag is unset, set the stop timeout flag. 
        
+        
      2. 
+         
        Set response to response. 
        
+        
      3. 
+         
        Handle errors for response. 
        
+        
      4. 
+         
        If response is a network error,
+     return. 
        
+        
      5. 
+         
        Set state to headers received. 
        
+        
      6. 
+         
        Fire an event named readystatechange. 
        
+        
      7. 
+         
        If state is not headers received, then return. 
        
+        
      8. 
+         
        If response’s body is null,
+     then run handle response end-of-body and return. 
        
+        
      9. 
+         
        Let reader be the result of getting a reader from response’s body’s stream. 
        
+         
        This operation will not throw an exception. 
        
+        
      10. 
+         
        Let read be the result of reading a chunk from response’s body’s stream with reader. 
        
+         
        When read is fulfilled with an object whose done property is false
+      and whose value property is a Uint8Array object, run these
+      subsubsubsteps and then run the above subsubstep again: 
        
+         
          
+          
        1. 
+           
          Append the value property to received bytes. 
          
+          
        2. 
+           
          If not roughly 50ms have passed since these subsubsubsteps were last invoked,
+       then terminate these subsubsubsteps. 
          
+          
        3. 
+           
          If state is headers received, then set state to loading. 
          
+          
        4. 
+           
          Fire an event named readystatechange. 
          
+           
          Web compatibility is the reason readystatechange fires more often than state changes. 
          
+          
        5. 
+           
          Fire a progress event named progress with response’s body’s transmitted bytes and response’s body’s total bytes. 
          
+         
        
+         
        These subsubsubsteps are only invoked when new bytes are transmitted. 
        
+         
        When read is fulfilled with an object whose done property is true,
+      run handle response end-of-body for response. 
        
+         
        When read is rejected with an exception, run handle errors for response. 
        
+       
      
+     
    
+    
  11. 
+     
    Otherwise, if the synchronous flag is set, run these substeps: 
    
+     
      
+      
    1. 
+       
      Let response be the result of fetching req. 
      
+       
      If the timeout attribute value is not
+    zero, terminate this fetch if it has not returned
+    within the amount of milliseconds from the timeout attribute value with reason timeout. 
      
+      
    2. 
+       
      If response’s body is null,
+   then run handle response end-of-body and return. 
      
+      
    3. 
+       
      Let reader be the result of getting a reader from response’s body’s stream. 
      
+       
      This operation will not throw an exception. 
      
+      
    4. 
+       
      Let promise be the result of reading all bytes from response’s body’s stream with reader. 
      
+      
    5. 
+       
      Wait for promise to be fulfilled or rejected. 
      
+      
    6. 
+       
      If promise is fulfilled with bytes, then append bytes to received bytes. 
      
+      
    7. 
+       
      Run handle response end-of-body for response. 
      
+     
    
+   

+   
To handle response end-of-body for response, run these steps: 

+   
    
+    
  1. 
+     
    If the synchronous flag is set, set response to response. 
    
+    
  2. 
+     
    Handle errors for response. 
    
+    
  3. 
+     
    If response is a network error, return. 
    
+    
  4. 
+     
    If the synchronous flag is unset, update response’s body using response. 
    
+    
  5. 
+     
    Let transmitted be response’s body’s transmitted bytes. 
    
+    
  6. 
+     
    Let length be response’s body’s total bytes. 
    
+    
  7. 
+     
    Fire a progress event named progress with transmitted and length. 
    
+    
  8. 
+     
    Set state to done. 
    
+    
  9. 
+     
    Unset the send() flag. 
    
+    
  10. 
+     
    Fire an event named readystatechange. 
    
+    
  11. 
+     
    Fire a progress event named load with transmitted and length. 
    
+    
  12. 
+     
    Fire a progress event named loadend with transmitted and length. 
    
+   

+   
To handle errors for response run these steps: 

+   
    
+    
  1. 
+     
    If the send() flag is unset, return. 
    
+    
  2. 
+     
    If response is a network error, run the request error steps for event error and
+ exception NetworkError. 
    
+    
  3. 
+     
    Otherwise, if response has a termination reason: 
    
+     
    
+      
    end-user abort 
+      
    
+       
    Run the request error steps for event abort and exception AbortError. 
    
+      
    fatal 
+      
    
+       
      
+        
    1. 
+         
      Set state to done. 
      
+        
    2. 
+         
      Unset the send() flag. 
      
+        
    3. 
+         
      Set response to a network error. 
      
+       
    
+      
    timeout 
+      
    
+       
    Run the request error steps for event timeout and exception TimeoutError. 
    
+     
    
+   

+   
The request error steps for event event and optionally an
+exception exception are: 

+   
    
+    
  1. 
+     
    Set state to done. 
    
+    
  2. 
+     
    Unset the send() flag. 
    
+    
  3. 
+     
    Set response to a network error. 
    
+    
  4. 
+     
    If the synchronous flag is set, throw an exception exception. 
    
+    
  5. 
+     
    Fire an event named readystatechange. 
    
+     
    At this point it is clear that the synchronous flag is unset. 
    
+    
  6. 
+     
    If the upload complete flag is unset, follow these substeps: 
    
+     
      
+      
    1. 
+       
      Set the upload complete flag. 
      
+      
    2. 
+       
      If upload listener flag is unset, then terminate these substeps. 
      
+      
    3. 
+       
      Fire a progress event named event on the XMLHttpRequestUpload object with 0 and 0. 
      
+      
    4. 
+       
      Fire a progress event named loadend on the XMLHttpRequestUpload object with 0 and 0. 
      
+     
    
+    
  7. 
+     
    Fire a progress event named event with 0 and 0. 
    
+    
  8. 
+     
    Fire a progress event named loadend with 0 and 0. 
    
+   

+   
4.5.7. The abort() method

+   

+    
client . abort() 
+    
Cancels any network activity. 
+   

+   
The abort() method,
+when invoked, must run these steps: 

+   
    
+    
  1. 
+     
    Terminate the request. 
    
+    
  2. 
+     
    If state is either opened with the send() flag set, headers received, or loading, run the request error steps for event abort. 
    
+    
  3. 
+     
    If state is done, then set state to unsent and response to a network error. 
    
+     
    No readystatechange event
+  is dispatched. 
    
+   

+   
4.6. Response

+   
An XMLHttpRequest has an associated response. Unless stated
+otherwise it is a network error. 

+   
An XMLHttpRequest also has an associated received bytes (a byte
+sequence). Unless stated otherwise it is the empty byte sequence. 

+   
4.6.1. The responseURL attribute

+   
The responseURL attribute
+must return the empty string if response’s url is null and its serialization with the exclude fragment flag set otherwise. 

+   
4.6.2. The status attribute

+   
The status attribute must return the response’s status. 

+   
4.6.3. The statusText attribute

+   
The statusText attribute must return the response’s status message. 

+   
4.6.4. The getResponseHeader() method

+   
The getResponseHeader(name) method must run these steps: 

+   
    
+    
  1. 
+     
    If response’s header list does not contain name, then return null. 
    
+    
  2. 
+     
    Return the combined value given name and response’s header list. 
    
+   

+   
The Fetch Standard filters response’s header list. [FETCH] 

+   

+     
+    
For the following script: 

+
var client = new XMLHttpRequest();
+client.open("GET", "unicorns-are-teh-awesome.txt", true);
+client.send();
+client.onreadystatechange = function() {
+  if(this.readyState == this.HEADERS_RECEIVED) {
+    print(client.getResponseHeader("Content-Type"));
+  }
+}

+    
The print() function will get to process something
+ like: 

+
text/plain; charset=UTF-8

+   

+   
4.6.5. The getAllResponseHeaders() method

+   
The getAllResponseHeaders() method, when invoked, must run these steps: 

+   
    
+    
  1. 
+     
    Let output be an empty byte sequence. 
    
+    
  2. 
+     
    Let headers be the result of running sort and combine with response’s header list. 
    
+    
  3. 
+     
    For each header in headers, append header’s name, followed by a 0x3A 0x20 byte pair, followed by header’s value, followed by a 0x0D 0x0A byte pair, to output. 
    
+    
  4. 
+     
    Return output. 
    
+   

+   
The Fetch Standard filters response’s header list. [FETCH] 

+   

+     
+    
For the following script: 

+
var client = new XMLHttpRequest();
+client.open("GET", "narwhals-too.txt", true);
+client.send();
+client.onreadystatechange = function() {
+  if(this.readyState == this.HEADERS_RECEIVED) {
+    print(this.getAllResponseHeaders());
+  }
+}

+    
The print() function will get to process something
+ like: 

+
connection: Keep-Alive
+content-type: text/plain; charset=utf-8
+date: Sun, 24 Oct 2004 04:58:38 GMT
+keep-alive: timeout=15, max=99
+server: Apache/1.3.31 (Unix)
+transfer-encoding: chunked

+   

+   
4.6.6. Response body

+   
The response MIME type is the result of running these steps: 

+   
    
+    
  1. 
+     
    Let mimeType be the result of extracting a MIME type from response’s header list. 
    
+    
  2. 
+     
    If mimeType is the empty byte sequence, then set mimeType to
+ `text/xml`. 
    
+    
  3. 
+     
    Return mimeType. 
    
+   

+   
The override MIME type is initially null and can get a value if overrideMimeType() is invoked. Final MIME type is the override MIME type unless that is null in which case it is the response MIME type. 

+   
The response charset is the value of
+the charset parameter of the `Content-Type` header
+or null if there was no `charset` parameter or the header could
+not be parsed or was omitted. The override charset is initially null and
+can get a value if overrideMimeType() is invoked. Final charset is the override charset unless
+that is null in which case it is the response charset. 

+   

+   
An XMLHttpRequest object has an associated response object (an object, failure,
+or null). Unless stated otherwise it is null. 

+   
An arraybuffer response is the return value of these steps: 

+   
    
+    
  1. 
+     
    Set response object to a new ArrayBuffer object representing received bytes.
+  If this throws an exception, then set response object to failure and return null. 
    
+     
    Allocating an ArrayBuffer object is not guaranteed to succeed. [ECMASCRIPT] 
    
+    
  2. 
+     
    Return response object. 
    
+   

+   
A blob response is the return value of these steps: 

+   
    
+    
  1. 
+     
    Set response object to a new Blob object representing received bytes with type final MIME type. 
    
+    
  2. 
+     
    Return response object. 
    
+   

+   
A document response is the return value of these steps: 

+   
    
+    
  1. 
+     
    If response’s body is null, then return null. 
    
+    
  2. 
+     
    If final MIME type is not `text/html`, `text/xml`,
+ `application/xml`, or does not end in `+xml`, then return null. 
    
+    
  3. 
+     
    If responseType is the empty string and final MIME type is
+  `text/html`, then return null. 
    
+     
    This is restricted to responseType being
+  "document" in order to prevent breaking legacy
+  content. 
    
+    
  4. 
+     
    If final MIME type is `text/html`, then run these substeps: 
    
+     
      
+      
    1. 
+       
      Let charset be the final charset. 
      
+      
    2. 
+       
      If charset is null, prescan the first 1024 bytes of received bytes and if
+   that does not terminate unsuccessfully then let charset be
+   the return value. 
      
+      
    3. 
+       
      If charset is null, set charset to utf-8. 
      
+      
    4. 
+       
      Let document be a document that
+   represents the result parsing received bytes following the rules set
+   forth in the HTML Standard for an HTML parser with scripting disabled and a known definite encoding charset. [HTML] 
      
+      
    5. 
+       
      Flag document as an HTML document. 
      
+     
    
+    
  5. 
+     
    Otherwise, let document be a document that represents the result of running the XML parser with XML scripting support disabled on received bytes. If that fails (unsupported character encoding,
+  namespace well-formedness error, etc.), then return null. [HTML] 
    
+     
    Resources referenced will not be loaded and no associated XSLT will be
+  applied. 
    
+    
  6. 
+     
    If charset is null, set charset to utf-8. 
    
+    
  7. 
+     
    Set document’s encoding to charset. 
    
+    
  8. 
+     
    Set document’s content type to final MIME type. 
    
+    
  9. 
+     
    Set document’s URL to response’s url. 
    
+    
  10. 
+     
    Set document’s origin to context object’s relevant settings object’s origin. 
    
+    
  11. 
+     
    Set response object to document and return it. 
    
+   

+   
A JSON response is the return value of these steps: 

+   
    
+    
  1. 
+     
    If response’s body is null, then return null. 
    
+    
  2. 
+     
    Let JSON text be the result of running utf-8 decode on received bytes. 
    
+    
  3. 
+     
    Let JSON object be the result of invoking the initial value of the parse property of the JSON object, with JSON text as its only argument. If that threw an exception, return null. [ECMASCRIPT] 
    
+    
  4. 
+     
    Set response object to JSON object and return it. 
    
+   

+   
A text response is the return value of these steps: 

+   
    
+    
  1. 
+     
    If response’s body is null, then return the
+ empty string. 
    
+    
  2. 
+     
    Let charset be the final charset. 
    
+    
  3. 
+     
    If responseType is the empty string, charset is null, and final MIME type is `text/xml`, `application/xml`, or ends in
+  `+xml`, then use the rules set forth in the XML specifications to determine the
+  encoding. Let charset be the determined encoding. [XML] [XMLNS] 
    
+     
    This is restricted to responseType being
+  the empty string to keep the non-legacy responseType value
+  "text" simple. 
    
+    
  4. 
+     
    If charset is null, set charset to utf-8. 
    
+    
  5. 
+     
    Return the result of running decode on received bytes using fallback
+ encoding charset. 
    
+   

+   
Authors are strongly encouraged to always encode their
+resources using utf-8. 

+   
4.6.7. The overrideMimeType() method

+   

+    
client . overrideMimeType(mime) 
+    

+     
Acts as if the `Content-Type` header for response is mime. 

+     
Throws an InvalidStateError exception if state is loading or done. 

+   

+   
The overrideMimeType(mime) method must run these steps: 

+   
    
+    
  1. 
+     
    If state is loading or done, throw an InvalidStateError exception. 
    
+    
  2. 
+     
    Set override MIME type to `application/octet-stream`. 
    
+    
  3. 
+     
    If mime is a parsable MIME type, then set override MIME type to its MIME type portion. 
    
+    
  4. 
+     
    If override MIME type has a `charset` parameter, then set override charset to its value. 
    
+   

+   
4.6.8. The responseType attribute

+   

+    
client . responseType [ = value ] 
+    

+     
Returns the response type. 

+     
Can be set to change the response type. Values are:
+  the empty string (default),
+  "arraybuffer",
+  "blob",
+  "document",
+  "json", and
+  "text". 

+     
When set: setting to "document" is ignored if current global object is not a Window object. 

+     
When set: throws an InvalidStateError exception if state is loading or done. 

+     
When set: throws an InvalidAccessError exception if the synchronous flag is set and current global object is a Window object. 

+   

+   
The responseType attribute must return its value. Initially its value must be the empty
+string. 

+   
Setting the responseType attribute must run these steps: 

+   
    
+    
  1. 
+     
    If current global object is not a Window object and the given value is
+ "document", terminate these steps. 
    
+    
  2. 
+     
    If state is loading or done, throw an InvalidStateError exception. 
    
+    
  3. 
+     
    If current global object is a Window object and the synchronous flag is set, throw an InvalidAccessError exception. 
    
+    
  4. 
+     
    Set the responseType attribute’s value to the given value. 
    
+   

+   
4.6.9. The response attribute

+   

+    
client . response 
+    

+     
Returns the response’s body. 

+   

+   
The response attribute must return the result of running these
+steps: 

+   

+    
If responseType is the empty string or "text" 
+    

+     
    
+      
  1. 
+       
    If state is not loading or done, return the empty string. 
    
+      
  2. 
+       
    Return the text response. 
    
+     

+    
Otherwise 
+    

+     
    
+      
  1. 
+       
    If state is not done, return null. 
    
+      
  2. 
+       
    If response object is failure, then return null. 
    
+      
  3. 
+       
    If response object is non-null, then return it. 
    
+      
  4. 
+       
    
+        
    If responseType is
+     "arraybuffer" 
+        
    
+         
    Return the arraybuffer response. 
    
+        
    If responseType is
+     "blob" 
+        
    
+         
    Return the blob response. 
    
+        
    If responseType is
+     "document" 
+        
    
+         
    Return the document response. 
    
+        
    If responseType is
+     "json" 
+        
    
+         
    Return the JSON response. 
    
+       
    
+     

+   

+   
4.6.10. The responseText attribute

+   

+    
client . responseText 
+    

+     
Returns the text response. 

+     
Throws an InvalidStateError exception if responseType is not
+  the empty string or "text". 

+   

+   
The responseText attribute must return the result of running these
+steps: 

+   
    
+    
  1. 
+     
    If responseType is not the
+ empty string or "text", throw an InvalidStateError exception. 
    
+    
  2. 
+     
    If state is not loading or done, return the empty string. 
    
+    
  3. 
+     
    Return the text response. 
    
+   

+   
4.6.11. The responseXML attribute

+   

+    
client . responseXML 
+    

+     
Returns the document response. 

+     
Throws an InvalidStateError exception if responseType is not
+  the empty string or "document". 

+   

+   
The responseXML attribute must return the result of running these steps: 

+   
    
+    
  1. 
+     
    If responseType is not
+ the empty string or "document", throw an InvalidStateError exception. 
    
+    
  2. 
+     
    If state is not done,
+ return null. 
    
+    
  3. 
+     
    If response object is non-null, then return it. 
    
+    
  4. 
+     
    Return the document response. 
    
+   

+   
The responseXML attribute has XML in its name for historical
+reasons. It also returns HTML resources as documents. 

+   
4.7. Events summary

+   
This section is non-normative. 

+   
The following events are dispatched on XMLHttpRequest and/or XMLHttpRequestUpload objects: 

+   
+    
+     
+      
+     
+      
+      
+      
+      
+      
+      
+      
+      
Event name 
+      Interface 
+      Dispatched when… 
+    
readystatechange 
+      Event 
+      The readyState attribute changes
+   value, except when it changes to UNSENT. 
+     
loadstart 
+      ProgressEvent 
+      The fetch initiates. 
+     
progress 
+      ProgressEvent 
+      Transmitting data. 
+     
abort 
+      ProgressEvent 
+      When the fetch has been aborted. For instance, by invoking the abort() method. 
+     
error 
+      ProgressEvent 
+      The fetch failed. 
+     
load 
+      ProgressEvent 
+      The fetch succeeded. 
+     
timeout 
+      ProgressEvent 
+      The author specified timeout has passed before the fetch completed. 
+     
loadend 
+      ProgressEvent 
+      The fetch completed (success or failure). 
+   

+   
5. Interface FormData

+
typedef (File or USVString) FormDataEntryValue;
+
+[Constructor(optional HTMLFormElement form),
+ Exposed=(Window,Worker)]
+interface FormData {
+  void append(USVString name, USVString value);
+  void append(USVString name, Blob blobValue, optional USVString filename);
+  void delete(USVString name);
+  FormDataEntryValue? get(USVString name);
+  sequence<FormDataEntryValue> getAll(USVString name);
+  boolean has(USVString name);
+  void set(USVString name, USVString value);
+  void set(USVString name, Blob blobValue, optional USVString filename);
+  iterable<USVString, FormDataEntryValue>;
+};

+   
The FormData object represents an ordered list of entries. Each entry consists of a name and a value. 

+   
For the purposes of interaction with other algorithms, an entry’s type is "string" if its value is a string and "file" otherwise. If
+an entry’s type is "file", its filename is
+the empty string if value is not
+a File object, and otherwise its filename is the
+value of entry’s value’s name attribute. 

+   
To create an entry for name, value, and optionally a filename, run these steps: 

+   
    
+    
  1. 
+     
    Let entry be a new entry. 
    
+    
  2. 
+     
    Set entry’s name to name. 
    
+    
  3. 
+     
    If value is a Blob object and not a File object, then set value to a new File object, representing the same bytes, whose name attribute value is
+ "blob". 
    
+    
  4. 
+     
    If value is (now) a File object and filename is given, then set value to a new File object, representing the same bytes, whose name attribute value is filename. 
    
+    
  5. 
+     
    Set entry’s value to value. 
    
+    
  6. 
+     
    Return entry. 
    
+   

+   

+   
The FormData(form) constructor must run these steps: 

+   
    
+    
  1. 
+     
    Let fd be a new FormData object. 
    
+    
  2. 
+     
    If form is given, set fd’s entries to the result of constructing the form data set for form. 
    
+    
  3. 
+     
    Return fd. 
    
+   

+   
The append(name, value) and append(name, blobValue, filename) methods, when invoked, must run these steps: 

+   
    
+    
  1. 
+     
    Let value be value if given, and blobValue otherwise. 
    
+    
  2. 
+     
    Let entry be the result of creating an entry with name, value, and filename if given. 
    
+    
  3. 
+     
    Append entry to context object’s list of entries. 
    
+   

+   
The reason there is an argument named value as well as blobValue is due to a limitation of the editing software used to write the XMLHttpRequest Standard. 

+   
The delete(name) method, when invoked, must remove all entries whose name is name. 

+   
The get(name) method, when
+invoked, must return the value of the first entry whose name is name, and null
+otherwise. 

+   
The getAll(name) method,
+when invoked, must return the values of
+all entries whose name is name, in list order, and
+the empty sequence otherwise. 

+   
The has(name) method, when
+invoked, must return true if there is an entry whose name is name, and false
+otherwise. 

+   
The set(name, value) and set(name, blobValue, filename) methods, when invoked, must run these steps: 

+   
    
+    
  1. 
+     
    Let value be value if given, and blobValue otherwise. 
    
+    
  2. 
+     
    Let entry be the result of creating an entry with name, value, and filename if given. 
    
+    
  3. 
+     
    If there are any entries in context object’s list of entries whose name is name, then replace the first such entry with entry and remove the others. 
    
+    
  4. 
+     
    Otherwise, append entry to context object’s
+ list of entries. 
    
+   

+   
The reason there is an argument named value as well as blobValue is due to a limitation of the editing software used to write the XMLHttpRequest Standard. 

+   
The value pairs to iterate over are the entries with the key being the name and the value the value. 

+   
6. Interface ProgressEvent

+
[Constructor(DOMString type, optional ProgressEventInit eventInitDict),
+ Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface ProgressEvent : Event {
+  readonly attribute boolean lengthComputable;
+  readonly attribute unsigned long long loaded;
+  readonly attribute unsigned long long total;
+};
+
+dictionary ProgressEventInit : EventInit {
+  boolean lengthComputable = false;
+  unsigned long long loaded = 0;
+  unsigned long long total = 0;
+};

+   
Events using the ProgressEvent interface indicate some kind of progression. 

+   
The lengthComputable, loaded, and total attributes must return the value they were initialized to. 

+   
6.1. Firing events using the ProgressEvent interface

+   
To fire a progress event named e at target, given transmitted and length, means to fire an event named e at target, using ProgressEvent, with the loaded attribute initialized to transmitted, and if length is not 0, with the lengthComputable attribute initialized to true and the total attribute initialized to length. 

+   
6.2. Suggested names for events using the ProgressEvent interface

+   
This section is non-normative. 

+   
The suggested type attribute values for use with events using the ProgressEvent interface are summarized in the table below.
+Specification editors are free to tune the details to their specific
+scenarios, though are strongly encouraged to discuss their usage with the
+WHATWG community to ensure input from people familiar with the subject. 

+   
+    
+     
+      
+      
+      
+      
+      
+      
+      
+      
type attribute value 
+      Description 
+      Times 
+      When 
+     
loadstart 
+      Progress has begun. 
+      Once. 
+      First. 
+     
progress 
+      In progress. 
+      Once or more. 
+      After loadstart has been dispatched. 
+     
error 
+      Progression failed. 
+      Zero or once (mutually exclusive). 
+      After the last progress has
+    been dispatched. 
+     
abort 
+      Progression is terminated. 
+     
timeout 
+      Progression is terminated due to preset time expiring. 
+     
load 
+      Progression is successful. 
+     
loadend 
+      Progress has stopped. 
+      Once. 
+      After one of error, abort, timeout or load has been dispatched. 
+   

+   
The error, abort, timeout, and load event types are mutually exclusive. 

+   
Throughout the web platform the error, abort, timeout and load event types have
+their bubbles and cancelable attributes initialized to false, so it is suggested that for consistency all events using the ProgressEvent interface do the same. 

+   
6.3. Security Considerations

+   
For cross-origin requests some kind of opt-in, e.g. the CORS protocol defined in the Fetch Standard, has to be
+used before events using the ProgressEvent interface are dispatched as information (e.g. size) would be revealed that cannot be obtained
+otherwise. [FETCH] 

+   
6.4. Example

+   

+     
+    
In this example XMLHttpRequest, combined with concepts
+ defined in the sections before, and the HTML progress element are used together to
+ display the process of fetching a resource. 

+
<!DOCTYPE html>
+<title>Waiting for Magical Unicorns</title>
+<progress id=p></progress>
+<script>
+  var progressBar = document.getElementById("p"),
+      client = new XMLHttpRequest()
+  client.open("GET", "magical-unicorns")
+  client.onprogress = function(pe) {
+    if(pe.lengthComputable) {
+      progressBar.max = pe.total
+      progressBar.value = pe.loaded
+    }
+  }
+  client.onloadend = function(pe) {
+    progressBar.value = pe.loaded
+  }
+  client.send()
+</script>

+    
Fully working code would of course be more elaborate and deal with more
+ scenarios, such as network errors or the end user terminating the request. 

+   

+   

+    
References

+    
Normative References

+    

+     
[COOKIES]
+     
A. Barth. HTTP State Management Mechanism. April 2011. Proposed Standard. URL: https://tools.ietf.org/html/rfc6265
+     
[DOM]
+     
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
+     
[DOMPS]
+     
Travis Leithead. DOM Parsing and Serialization. URL: https://w3c.github.io/DOM-Parsing/
+     
[ECMASCRIPT]
+     
ECMAScript Language Specification. URL: https://tc39.github.io/ecma262/
+     
[ENCODING]
+     
Anne van Kesteren. Encoding Standard. Living Standard. URL: https://encoding.spec.whatwg.org/
+     
[FETCH]
+     
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
+     
[FILEAPI]
+     
Arun Ranganathan; Jonas Sicking. File API. URL: https://w3c.github.io/FileAPI/
+     
[HTML]
+     
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
+     
[HTTP]
+     
R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. June 2014. Proposed Standard. URL: https://tools.ietf.org/html/rfc7230
+     
[INFRA]
+     
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
+     
[MIMESNIFF]
+     
Gordon P. Hemsley. MIME Sniffing Standard. Living Standard. URL: https://mimesniff.spec.whatwg.org/
+     
[RFC2119]
+     
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
+     
[URL]
+     
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
+     
[WEBIDL]
+     
Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. URL: https://heycam.github.io/webidl/
+     
[XML]
+     
Tim Bray; et al. Extensible Markup Language (XML) 1.0 (Fifth Edition). 26 November 2008. REC. URL: https://www.w3.org/TR/xml
+     
[XMLNS]
+     
Tim Bray; et al. Namespaces in XML 1.0 (Third Edition). 8 December 2009. REC. URL: https://www.w3.org/TR/xml-names
+    

+   

+   
Acknowledgments

+   
Thanks to
+Addison Phillips,
+Adrian Bateman,
+Ahmed Kamel,
+Alan Thomas,
+Alex Hopmann,
+Alex Vincent,
+Alexey Proskuryakov,
+Ali Alabbas,
+Andrea Marchesini,
+Asbjørn Ulsberg,
+Bertrand Guay-Paquet,
+Björn Höhrmann,
+Boris Zbarsky,
+Caitlin Potter,
+Cameron McCormack,
+Chris Marrin,
+Christophe Jolif,
+Charles McCathieNevile,
+Dan Winship,
+David Andersson,
+David Flanagan,
+David Håsäther,
+David Levin,
+Dean Jackson,
+Denis Sureau,
+Domenic Denicola,
+Dominik Röttsches,
+Doug Schepers,
+Douglas Livingstone,
+Elliott Sprehn,
+Elliotte Harold,
+Eric Lawrence,
+Eric Uhrhane,
+Erik Arvidsson,
+Erik Dahlström,
+Feras Moussa,
+Geoffrey Sneddon,
+Gideon Cohn,
+Glenn Adams,
+Gorm Haug Eriksen,
+Håkon Wium Lie,
+Hallvord R. M. Steen,
+Henri Sivonen,
+Hiroshige Hayashizaki,
+Huub Schaeks,
+Ian Davis,
+Ian Hickson,
+Ivan Herman,
+Jake Archibald,
+Jared Jacobs,
+Jarred Nicholls,
+Jeff Walden,
+Jens Lindström,
+Jim Deegan,
+Jim Ley,
+Joe Farro,
+Jonas Sicking,
+Julian Reschke,
+송정기 (Jungkee Song),
+呂康豪 (Kang-Hao Lu),
+Karl Dubost,
+Keith Yeung,
+Lachlan Hunt,
+Maciej Stachowiak,
+Magnus Kristiansen,
+Manish Goregaokar,
+Marc Hadley,
+Marcos Caceres,
+Mark Baker,
+Mark Birbeck,
+Mark Nottingham,
+Mark S. Miller,
+Martin Hassman,
+Mohamed Zergaoui,
+Ms2ger,
+Odin Hørthe Omdal,
+Olli Pettay,
+Pawel Glowacki,
+Peter Michaux,
+Philip Jägenstedt,
+Philip Taylor,
+Robin Berjon,
+Rune F. Halvorsen,
+Ruud Steltenpool,
+Sergiu Dumitriu,
+Shivakumar Jagalur Matt,
+Sigbjørn Finne,
+Simon Pieters,
+Stewart Brodie,
+Sunava Dutta,
+Takeshi Kurosawa,
+Takeshi Yoshino,
+Thomas Roessler,
+Thomas Wisniewski,
+Tom Magliery,
+Travis Leithead,
+triple-underscore,
+Yehuda Katz,
+Youenn Fablet, and
+Zhenbin Xu
+for their contributions to this standard. 

+   
Special thanks to the Microsoft employees who first implemented the XMLHttpRequest interface, which was first widely deployed by the
+Windows Internet Explorer browser. 

+   
Special thanks to Ian Hickson for drafting an initial version of this specification in
+the HTML Standard (then Web Applications 1.0). [HTML] 

+   
Special thanks to the W3C SVG WG for drafting the original ProgressEvent class as part of the SVG Micro DOM. 

+   
This standard is written by Anne van Kesteren (Mozilla, annevk@annevk.nl). 

+   
Per CC0, to
+the extent possible under law, the editor has waived all copyright and related or
+neighboring rights to this work. 

+  

+  
Index

+  
Terms defined by this specification

+  
+  
Terms defined by reference

+  
+  
IDL Index

+
[Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface XMLHttpRequestEventTarget : EventTarget {
+  // event handlers
+  attribute EventHandler onloadstart;
+  attribute EventHandler onprogress;
+  attribute EventHandler onabort;
+  attribute EventHandler onerror;
+  attribute EventHandler onload;
+  attribute EventHandler ontimeout;
+  attribute EventHandler onloadend;
+};
+
+[Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface XMLHttpRequestUpload : XMLHttpRequestEventTarget {
+};
+
+enum XMLHttpRequestResponseType {
+  "",
+  "arraybuffer",
+  "blob",
+  "document",
+  "json",
+  "text"
+};
+
+[Constructor,
+ Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface XMLHttpRequest : XMLHttpRequestEventTarget {
+  // event handler
+  attribute EventHandler onreadystatechange;
+
+  // states
+  const unsigned short UNSENT = 0;
+  const unsigned short OPENED = 1;
+  const unsigned short HEADERS_RECEIVED = 2;
+  const unsigned short LOADING = 3;
+  const unsigned short DONE = 4;
+  readonly attribute unsigned short readyState;
+
+  // request
+  void open(ByteString method, USVString url);
+  void open(ByteString method, USVString url, boolean async, optional USVString? username = null, optional USVString? password = null);
+  void setRequestHeader(ByteString name, ByteString value);
+           attribute unsigned long timeout;
+           attribute boolean withCredentials;
+  [SameObject] readonly attribute XMLHttpRequestUpload upload;
+  void send(optional (Document or BodyInit)? body = null);
+  void abort();
+
+  // response
+  readonly attribute USVString responseURL;
+  readonly attribute unsigned short status;
+  readonly attribute ByteString statusText;
+  ByteString? getResponseHeader(ByteString name);
+  ByteString getAllResponseHeaders();
+  void overrideMimeType(DOMString mime);
+           attribute XMLHttpRequestResponseType responseType;
+  readonly attribute any response;
+  readonly attribute USVString responseText;
+  [Exposed=Window] readonly attribute Document? responseXML;
+};
+typedef (File or USVString) FormDataEntryValue;
+
+[Constructor(optional HTMLFormElement form),
+ Exposed=(Window,Worker)]
+interface FormData {
+  void append(USVString name, USVString value);
+  void append(USVString name, Blob blobValue, optional USVString filename);
+  void delete(USVString name);
+  FormDataEntryValue? get(USVString name);
+  sequence<FormDataEntryValue> getAll(USVString name);
+  boolean has(USVString name);
+  void set(USVString name, USVString value);
+  void set(USVString name, Blob blobValue, optional USVString filename);
+  iterable<USVString, FormDataEntryValue>;
+};
+[Constructor(DOMString type, optional ProgressEventInit eventInitDict),
+ Exposed=(Window,DedicatedWorker,SharedWorker)]
+interface ProgressEvent : Event {
+  readonly attribute boolean lengthComputable;
+  readonly attribute unsigned long long loaded;
+  readonly attribute unsigned long long total;
+};
+
+dictionary ProgressEventInit : EventInit {
+  boolean lengthComputable = false;
+  unsigned long long loaded = 0;
+  unsigned long long total = 0;
+};
+

\ No newline at end of file

From 0f92a6b5cbca1fd32abaee98f5286a78e4d6f3bb Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Wed, 31 May 2017 13:39:51 -0400
Subject: [PATCH 07/23] Temporary work on pipeline

---
 lib/org/chromium/webidl/HTMLFileContent.js | 41 +++++++++++++++++-----
 test/node/parsing/HTMLFileContent-test.js  | 20 +++++------
 2 files changed, 42 insertions(+), 19 deletions(-)

diff --git a/lib/org/chromium/webidl/HTMLFileContent.js b/lib/org/chromium/webidl/HTMLFileContent.js
index 3dfce67..1a6d8fd 100644
--- a/lib/org/chromium/webidl/HTMLFileContent.js
+++ b/lib/org/chromium/webidl/HTMLFileContent.js
@@ -6,7 +6,7 @@
 foam.CLASS({
   package: 'org.chromium.webidl',
   name: 'HTMLFileContent',
-
+  documentation: 'stores the html file and the tags of interest found',
   requires: [
     'foam.parsers.HTMLLexer'
   ],
@@ -22,6 +22,28 @@ foam.CLASS({
     {
       name: 'pre',
       // description: 'all pre tags found in the parsed HTML file',
+      postSet: function(_, tags) {
+        var Parser = foam.lookup('org.chromium.webidl.Parser');
+        var parser = Parser.create();
+        var asts = [];
+
+        // Currently using generic parsers...
+        tags.forEach(function(tag) {
+          if (tag.isIDL) {
+            var parsedContent = parser.parseString(tag.content);
+            if (parsedContent.pos !== tag.content.length) {
+              console.warn('Incomplete parse!');
+            } else {
+              asts.push(parser.parseString(tag.content).value);
+            }
+          }
+        });
+      }
+    },
+    // Temporarily putting this here until we know where to put it
+    {
+      name: 'ast',
+      // description: 'ast of IDL files found in the parsed HTML file'
     }
   ],
 
@@ -35,13 +57,12 @@ foam.CLASS({
 
       var results = lexer.parseString(str).value;
 
-      // Tag matching
-      // Using a stack to obtain ancestorOf 
 tags
+      // Tag matching to obtain ancestorOf 
 tags
       var tags = [];
       var pre = [];
 
       // We ignore tags inside <* class="example"> or <* class="note">
-      // skipStack keeps track of stack levels where tags are of the above
+      // skipStack keeps track of stack levels where ignored tags are located
       var skipStack = [];
 
       results.forEach(function(node, i) {
@@ -49,10 +70,12 @@ foam.CLASS({
 
         if (foam.core.FObject.isInstance(item)) {
           var top = tags[tags.length - 1];
+          // Extract 'class' from attributes
           var classes = '';
-          item.attributes.forEach(function(attr) {
+          item.attributes.some(function(attr) {
             if (attr.name === 'class') {
               classes = attr.value.split(' ');
+              return;
             }
           });
 
@@ -71,9 +94,7 @@ foam.CLASS({
               skipStack.length === 0) {
             var isIDL = classes.includes('idl');
 
-            // Add to the list of pre.
             pre.push({
-              ancestor: top,
               content: self.flatten(item.content),
               isIDL: isIDL
             });
@@ -88,9 +109,11 @@ foam.CLASS({
       return pre;
     },
 
-    function flatten(obj) {
+    function flatten(tags) {
+      // Extracts contents from an array of tags and creates
+      // one resulting string.
       var self = this;
-      return obj.reduce(function(acc, item) {
+      return tags.reduce(function(acc, item) {
         if (foam.String.isInstance(item)) {
           return acc.concat(item);
         } else if (foam.core.FObject.isInstance(item)) {
diff --git a/test/node/parsing/HTMLFileContent-test.js b/test/node/parsing/HTMLFileContent-test.js
index aab39e1..a731ac4 100644
--- a/test/node/parsing/HTMLFileContent-test.js
+++ b/test/node/parsing/HTMLFileContent-test.js
@@ -48,16 +48,16 @@ describe('HTMLFileContent', function() {
 
   it('should parse a HTML file with one Web IDL Block', function() {
     var idl = `[Constructor]
-        interface Dahut : Mammal {
-          const unsigned short LEVROGYROUS = 0;
-          const unsigned short DEXTROGYROUS = 1;
-          readonly attribute DOMString chirality;
-          attribute unsigned long age;
-          Dahut turnAround(float angle, boolean fall);
-          unsigned long trip();
-          void yell([AllowAny] unsigned long volume,
-              [TreatNullAs=EmptyString] DOMString sentence);
-        };`;
+      interface Dahut : Mammal {
+        const unsigned short LEVROGYROUS = 0;
+        const unsigned short DEXTROGYROUS = 1;
+        readonly attribute DOMString chirality;
+        attribute unsigned long age;
+        Dahut turnAround(float angle, boolean fall);
+        unsigned long trip();
+        void yell([AllowAny] unsigned long volume,
+          [TreatNullAs=EmptyString] DOMString sentence);
+    };`;
     var content = `
${idl}
`;
     var htmlFile = HTMLFileContent.create({ file: content });
     expect(htmlFile).toBeDefined();

From a041087d1dce3bec2bf5dac3ced91904f2c2c6db Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Wed, 7 Jun 2017 11:21:57 -0400
Subject: [PATCH 08/23] Refactoring HTMLFileContent to correspond with
 HTMLLexer changes

---
 lib/org/chromium/webidl/HTMLFileContent.js | 111 +++++++++------------
 test/node/parsing/HTMLFileContent-test.js  |  21 ++--
 2 files changed, 56 insertions(+), 76 deletions(-)

diff --git a/lib/org/chromium/webidl/HTMLFileContent.js b/lib/org/chromium/webidl/HTMLFileContent.js
index 1a6d8fd..8db633f 100644
--- a/lib/org/chromium/webidl/HTMLFileContent.js
+++ b/lib/org/chromium/webidl/HTMLFileContent.js
@@ -8,7 +8,7 @@ foam.CLASS({
   name: 'HTMLFileContent',
   documentation: 'stores the html file and the tags of interest found',
   requires: [
-    'foam.parsers.HTMLLexer'
+    'foam.parsers.html.HTMLLexer'
   ],
 
   properties: [
@@ -16,31 +16,27 @@ foam.CLASS({
       name: 'file',
       // description: 'content of the HTML file',
       postSet: function(_, file) {
-        this.pre = this.parse(file);
+        this.idlFragments = this.parse(file);
       }
     },
     {
-      name: 'pre',
-      // description: 'all pre tags found in the parsed HTML file',
-      postSet: function(_, tags) {
+      name: 'idlFragments',
+      // description: 'all idlFragments found in the parsed HTML file',
+      postSet: function(_, fragments) {
         var Parser = foam.lookup('org.chromium.webidl.Parser');
         var parser = Parser.create();
         var asts = [];
 
-        // Currently using generic parsers...
-        tags.forEach(function(tag) {
-          if (tag.isIDL) {
-            var parsedContent = parser.parseString(tag.content);
-            if (parsedContent.pos !== tag.content.length) {
-              console.warn('Incomplete parse!');
-            } else {
-              asts.push(parser.parseString(tag.content).value);
-            }
+        fragments.forEach(function(idl) {
+          var parsedContent = parser.parseString(idl);
+          if (parsedContent.pos !== idl.length) {
+            console.warn('Incomplete parse!');
+          } else {
+            asts.push(parsedContent.value);
           }
         });
       }
     },
-    // Temporarily putting this here until we know where to put it
     {
       name: 'ast',
       // description: 'ast of IDL files found in the parsed HTML file'
@@ -57,21 +53,29 @@ foam.CLASS({
 
       var results = lexer.parseString(str).value;
 
-      // Tag matching to obtain ancestorOf 
 tags
-      var tags = [];
-      var pre = [];
-
-      // We ignore tags inside <* class="example"> or <* class="note">
-      // skipStack keeps track of stack levels where ignored tags are located
-      var skipStack = [];
-
-      results.forEach(function(node, i) {
+      var idlFragments = [];        // Processed output
+      var tagStack = [];            // Used for tag matching.
+      var tagMatching = true;       // true: not inside a pre of interest
+      var exclude = false;
+      var content = '';             // Used to group together related content
+      for (var i = 0; i < results.length; i++) {
         var item = results[i];
+        var isTag = lexer.Tag.isInstance(item);
 
-        if (foam.core.FObject.isInstance(item)) {
-          var top = tags[tags.length - 1];
+        if (!tagMatching) {
+          // Ignoring all tags. Only extracting text within pre tags.
+          if (isTag && item.nodeName === 'pre') {
+            tagMatching = true;
+            tagStack.pop();
+            idlFragments.push(content);
+            content = '';
+          } else {
+            content += isTag ? '' : item;
+          }
+        } else if (isTag) {
+          var top = tagStack[tagStack.length - 1];
+          var classes = [];
           // Extract 'class' from attributes
-          var classes = '';
           item.attributes.some(function(attr) {
             if (attr.name === 'class') {
               classes = attr.value.split(' ');
@@ -79,49 +83,28 @@ foam.CLASS({
             }
           });
 
+          var isIDL = classes.includes('idl');
+          var isExcludeTag = classes.includes('example') || classes.includes('note');
+
           if (item.type.name === OPEN) {
-            if (classes.includes('example') || classes.includes('note')) {
-              skipStack.push(tags.length);
+            if (isExcludeTag) {
+              exclude = true;
+            } else if (!exclude && item.nodeName === 'pre' && isIDL) {
+              // Found a 
.
+              // Ignore tags and only extract text now.
+              tagMatching = false;
             }
-            tags.push(item);
-          } else if (top !== undefined && item.nodeName === top.nodeName
-              && item.type.name === CLOSE) {
-            tags.pop();
-            if (skipStack[skipStack.length - 1] == tags.length) {
-              skipStack.pop();
-            }
-          } else if (item.type.name === OPEN_CLOSE && item.nodeName === 'pre' &&
-              skipStack.length === 0) {
-            var isIDL = classes.includes('idl');
-
-            pre.push({
-              content: self.flatten(item.content),
-              isIDL: isIDL
-            });
+            tagStack.push(item);
+          } else if (top && item.type.name === CLOSE && top.nodeName === item.nodeName) {
+            if (isExcludeTag) exclude = false;
+            tagStack.pop();
           } else {
-            // Currently not doing anything for:
-            //  - Nested pre tags in example/note
-            //  - OPEN_CLOSE tags that are not pre
-            //  - Malformed / Mismatched HTML Files
+            // Mismatched close tags and OPEN_CLOSE tags are ignored
           }
         }
-      });
-      return pre;
+      }
+      return idlFragments;
     },
-
-    function flatten(tags) {
-      // Extracts contents from an array of tags and creates
-      // one resulting string.
-      var self = this;
-      return tags.reduce(function(acc, item) {
-        if (foam.String.isInstance(item)) {
-          return acc.concat(item);
-        } else if (foam.core.FObject.isInstance(item)) {
-          return acc.concat(foam.Array.isInstance(item.content) ?
-              item.content[1] || item.content[0] : '');
-        }
-      }, "");
-    }
   ]
 });
 
diff --git a/test/node/parsing/HTMLFileContent-test.js b/test/node/parsing/HTMLFileContent-test.js
index a731ac4..fd31a48 100644
--- a/test/node/parsing/HTMLFileContent-test.js
+++ b/test/node/parsing/HTMLFileContent-test.js
@@ -11,23 +11,20 @@ describe('HTMLFileContent', function() {
     var fs = require('fs');
     var spec = fs.readFileSync(`${testDirectory}/spec.html`).toString();
     var htmlSpec = HTMLFileContent.create({ file: spec });
-    var preBlocks = htmlSpec.pre;
-    var idlFragments = preBlocks.filter(function(block) {
-      return block.isIDL;
-    });
+    var idlFragments = htmlSpec.idlFragments;
 
-    // Determine the number of fragments that were found
-    expect(preBlocks.length).toBe(expectedPre)
+    // Determine the number of fragments that were found.
+    //expect(preBlocks.length).toBe(expectedPre)
     expect(idlFragments.length).toBe(expectedIDL);
 
     fs.readdir(testDirectory, function(err, files) {
-      // Go through each of the expected results in the folder
+      // Go through each of the expected results in the folder.
       files.forEach(function(filename) {
         var testNum = Number(filename);
 
-        if (!isNaN(testNum) && testNum < preBlocks.length) {
+        if (!isNaN(testNum) && testNum < idlFragments.length) {
           var expectedContent = fs.readFileSync(`${testDirectory}/${filename}`).toString();
-          expect(preBlocks[testNum].content.trim()).toBe(expectedContent.trim());
+          expect(idlFragments[testNum].content.trim()).toBe(expectedContent.trim());
         } else if (filename !== 'spec.html') {
           fail(`File ${filename} was not used in ${testName} spec test`);
         }
@@ -43,7 +40,7 @@ describe('HTMLFileContent', function() {
     var content = '
';
     var htmlFile = HTMLFileContent.create({ file: content });
     expect(htmlFile).toBeDefined();
-    expect(htmlFile.pre.length).toBe(1);
+    expect(htmlFile.idlFragments.length).toBe(1);
   });
 
   it('should parse a HTML file with one Web IDL Block', function() {
@@ -61,8 +58,8 @@ describe('HTMLFileContent', function() {
     var content = `
${idl}
`;
     var htmlFile = HTMLFileContent.create({ file: content });
     expect(htmlFile).toBeDefined();
-    expect(htmlFile.pre.length).toBe(1);
-    expect(htmlFile.pre[0].content).toBe(idl);
+    expect(htmlFile.idlFragments.length).toBe(1);
+    expect(htmlFile.idlFragments[0]).toBe(idl);
   });
 
   it('should parse the UI Events spec HTML file (w3c)', function() {

From 5969d4b4a6c6ea5c8d846fa277af3bb22f59fe35 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Wed, 7 Jun 2017 15:04:44 -0400
Subject: [PATCH 09/23] Part 2 of refactor due to HTMLLexer changes

---
 lib/org/chromium/webidl/HTMLFileContent.js | 30 ++++++++++++----------
 test/node/parsing/HTMLFileContent-test.js  | 26 ++++++++-----------
 test/node/parsing/UIEvent/0                |  5 ++++
 test/node/parsing/UIEvent/1                |  7 +++--
 test/node/parsing/UIEvent/{23 => 16}       |  0
 test/node/parsing/UIEvent/{26 => 17}       |  0
 test/node/parsing/UIEvent/2                |  4 ---
 test/node/parsing/UIEvent/4                | 19 ++++++++++++++
 test/node/parsing/UIEvent/7                | 12 +++++++++
 test/node/parsing/WebUSB/{11 => 10}        |  0
 test/node/parsing/WebUSB/{4 => 3}          |  0
 11 files changed, 65 insertions(+), 38 deletions(-)
 create mode 100644 test/node/parsing/UIEvent/0
 rename test/node/parsing/UIEvent/{23 => 16} (100%)
 rename test/node/parsing/UIEvent/{26 => 17} (100%)
 delete mode 100644 test/node/parsing/UIEvent/2
 create mode 100644 test/node/parsing/UIEvent/4
 create mode 100644 test/node/parsing/UIEvent/7
 rename test/node/parsing/WebUSB/{11 => 10} (100%)
 rename test/node/parsing/WebUSB/{4 => 3} (100%)

diff --git a/lib/org/chromium/webidl/HTMLFileContent.js b/lib/org/chromium/webidl/HTMLFileContent.js
index 8db633f..ae60b3e 100644
--- a/lib/org/chromium/webidl/HTMLFileContent.js
+++ b/lib/org/chromium/webidl/HTMLFileContent.js
@@ -50,6 +50,15 @@ foam.CLASS({
       var OPEN = lexer.TagType.OPEN.name;
       var CLOSE = lexer.TagType.CLOSE.name;
       var OPEN_CLOSE = lexer.TagType.OPEN_CLOSE.name;
+      var extractAttr = function(node, attrName) {
+        var retVal;
+        node.attributes.some(function(attr) {
+          if (attr.name === attrName) {
+            retVal = attr.value.split(' ');
+          }
+        });
+        return retVal;
+      };
 
       var results = lexer.parseString(str).value;
 
@@ -67,24 +76,16 @@ foam.CLASS({
           if (isTag && item.nodeName === 'pre') {
             tagMatching = true;
             tagStack.pop();
-            idlFragments.push(content);
+            idlFragments.push(lexer.lib.unescapeString(content));
             content = '';
           } else {
             content += isTag ? '' : item;
           }
         } else if (isTag) {
           var top = tagStack[tagStack.length - 1];
-          var classes = [];
-          // Extract 'class' from attributes
-          item.attributes.some(function(attr) {
-            if (attr.name === 'class') {
-              classes = attr.value.split(' ');
-              return;
-            }
-          });
-
-          var isIDL = classes.includes('idl');
-          var isExcludeTag = classes.includes('example') || classes.includes('note');
+          var classes = extractAttr(item, 'class');
+          var isIDL = classes && classes.includes('idl');
+          var isExcludeTag = classes && (classes.includes('example') || classes.includes('note'));
 
           if (item.type.name === OPEN) {
             if (isExcludeTag) {
@@ -96,7 +97,8 @@ foam.CLASS({
             }
             tagStack.push(item);
           } else if (top && item.type.name === CLOSE && top.nodeName === item.nodeName) {
-            if (isExcludeTag) exclude = false;
+            var parentCls = extractAttr(top, 'class');
+            if (parentCls && (parentCls.includes('example') || parentCls.includes('note'))) exclude = false;
             tagStack.pop();
           } else {
             // Mismatched close tags and OPEN_CLOSE tags are ignored
@@ -104,7 +106,7 @@ foam.CLASS({
         }
       }
       return idlFragments;
-    },
+    }
   ]
 });
 
diff --git a/test/node/parsing/HTMLFileContent-test.js b/test/node/parsing/HTMLFileContent-test.js
index fd31a48..c22cc37 100644
--- a/test/node/parsing/HTMLFileContent-test.js
+++ b/test/node/parsing/HTMLFileContent-test.js
@@ -7,14 +7,13 @@ describe('HTMLFileContent', function() {
   var HTMLFileContent;
   var Parser;
 
-  function cmpTest(testName, testDirectory, expectedPre, expectedIDL) {
+  function cmpTest(testName, testDirectory, expectedIDL) {
     var fs = require('fs');
     var spec = fs.readFileSync(`${testDirectory}/spec.html`).toString();
     var htmlSpec = HTMLFileContent.create({ file: spec });
     var idlFragments = htmlSpec.idlFragments;
 
     // Determine the number of fragments that were found.
-    //expect(preBlocks.length).toBe(expectedPre)
     expect(idlFragments.length).toBe(expectedIDL);
 
     fs.readdir(testDirectory, function(err, files) {
@@ -24,7 +23,7 @@ describe('HTMLFileContent', function() {
 
         if (!isNaN(testNum) && testNum < idlFragments.length) {
           var expectedContent = fs.readFileSync(`${testDirectory}/${filename}`).toString();
-          expect(idlFragments[testNum].content.trim()).toBe(expectedContent.trim());
+          expect(idlFragments[testNum].trim()).toBe(expectedContent.trim());
         } else if (filename !== 'spec.html') {
           fail(`File ${filename} was not used in ${testName} spec test`);
         }
@@ -64,36 +63,31 @@ describe('HTMLFileContent', function() {
 
   it('should parse the UI Events spec HTML file (w3c)', function() {
     var testDirectory = `${__dirname}/UIEvent`;
-    var expectedFragments = 27;
-    var expectedIDLFrags = 18;
-    cmpTest('UI Events', testDirectory, expectedFragments, expectedIDLFrags);
+    var expectedFragments = 18;
+    cmpTest('UI Events', testDirectory, expectedFragments);
   });
 
   it('should parse the WebGL spec HTML file (khronos)', function() {
     var testDirectory = `${__dirname}/WebGL`;
     var expectedFragments = 7;
-    var expectedIDLFrags = 7;
-    cmpTest('WebGL', testDirectory, expectedFragments, expectedIDLFrags);
+    cmpTest('WebGL', testDirectory, expectedFragments);
   });
 
   it('should parse the WebUSB spec HTML file (wicg)', function() {
     var testDirectory = `${__dirname}/WebUSB`;
-    var expectedFragments = 12;
-    var expectedIDLFrags = 11;
-    cmpTest('WebUSB', testDirectory, expectedFragments, expectedIDLFrags);
+    var expectedFragments = 11;
+    cmpTest('WebUSB', testDirectory, expectedFragments);
   });
 
   it('should parse the XMLHttpRequest spec HTML file (whatwg)', function() {
     var testDirectory = `${__dirname}/XMLHttpRequest`;
     var expectedFragments = 4;
-    var expectedIDLFrags = 4;
-    cmpTest('XMLHttpRequest', testDirectory, expectedFragments, expectedIDLFrags);
+    cmpTest('XMLHttpRequest', testDirectory, expectedFragments);
   });
 
   it('should parse the whatwg HTML standard', function() {
     var testDirectory = `${__dirname}/whatwg`;
-    var expectedFragments = 155;
-    var expectedIDLFrags = 45;
-    cmpTest('whatwg HTML', testDirectory, expectedFragments, expectedIDLFrags);
+    var expectedFragments = 45;
+    cmpTest('whatwg HTML', testDirectory, expectedFragments);
   });
 });
diff --git a/test/node/parsing/UIEvent/0 b/test/node/parsing/UIEvent/0
new file mode 100644
index 0000000..75f5557
--- /dev/null
+++ b/test/node/parsing/UIEvent/0
@@ -0,0 +1,5 @@
+[Constructor(DOMString type, optional UIEventInit eventInitDict)]
+interface UIEvent : Event {
+  readonly attribute Window? view;
+  readonly attribute long detail;
+};
diff --git a/test/node/parsing/UIEvent/1 b/test/node/parsing/UIEvent/1
index 75f5557..164d8e4 100644
--- a/test/node/parsing/UIEvent/1
+++ b/test/node/parsing/UIEvent/1
@@ -1,5 +1,4 @@
-[Constructor(DOMString type, optional UIEventInit eventInitDict)]
-interface UIEvent : Event {
-  readonly attribute Window? view;
-  readonly attribute long detail;
+dictionary UIEventInit : EventInit {
+  Window? view = null;
+  long detail = 0;
 };
diff --git a/test/node/parsing/UIEvent/23 b/test/node/parsing/UIEvent/16
similarity index 100%
rename from test/node/parsing/UIEvent/23
rename to test/node/parsing/UIEvent/16
diff --git a/test/node/parsing/UIEvent/26 b/test/node/parsing/UIEvent/17
similarity index 100%
rename from test/node/parsing/UIEvent/26
rename to test/node/parsing/UIEvent/17
diff --git a/test/node/parsing/UIEvent/2 b/test/node/parsing/UIEvent/2
deleted file mode 100644
index 164d8e4..0000000
--- a/test/node/parsing/UIEvent/2
+++ /dev/null
@@ -1,4 +0,0 @@
-dictionary UIEventInit : EventInit {
-  Window? view = null;
-  long detail = 0;
-};
diff --git a/test/node/parsing/UIEvent/4 b/test/node/parsing/UIEvent/4
new file mode 100644
index 0000000..e6fbdce
--- /dev/null
+++ b/test/node/parsing/UIEvent/4
@@ -0,0 +1,19 @@
+[Constructor(DOMString type, optional MouseEventInit eventInitDict)]
+interface MouseEvent : UIEvent {
+  readonly attribute long screenX;
+  readonly attribute long screenY;
+  readonly attribute long clientX;
+  readonly attribute long clientY;
+
+  readonly attribute boolean ctrlKey;
+  readonly attribute boolean shiftKey;
+  readonly attribute boolean altKey;
+  readonly attribute boolean metaKey;
+
+  readonly attribute short button;
+  readonly attribute unsigned short buttons;
+
+  readonly attribute EventTarget? relatedTarget;
+
+  boolean getModifierState(DOMString keyArg);
+};
diff --git a/test/node/parsing/UIEvent/7 b/test/node/parsing/UIEvent/7
new file mode 100644
index 0000000..2beccde
--- /dev/null
+++ b/test/node/parsing/UIEvent/7
@@ -0,0 +1,12 @@
+[Constructor(DOMString type, optional WheelEventInit eventInitDict)]
+interface WheelEvent : MouseEvent {
+  // DeltaModeCode
+  const unsigned long DOM_DELTA_PIXEL = 0x00;
+  const unsigned long DOM_DELTA_LINE  = 0x01;
+  const unsigned long DOM_DELTA_PAGE  = 0x02;
+
+  readonly attribute double deltaX;
+  readonly attribute double deltaY;
+  readonly attribute double deltaZ;
+  readonly attribute unsigned long deltaMode;
+};
diff --git a/test/node/parsing/WebUSB/11 b/test/node/parsing/WebUSB/10
similarity index 100%
rename from test/node/parsing/WebUSB/11
rename to test/node/parsing/WebUSB/10
diff --git a/test/node/parsing/WebUSB/4 b/test/node/parsing/WebUSB/3
similarity index 100%
rename from test/node/parsing/WebUSB/4
rename to test/node/parsing/WebUSB/3

From ad7669ea13dd9af9eeee8f0d30002dbe5be2eb82 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Thu, 8 Jun 2017 10:50:25 -0400
Subject: [PATCH 10/23] Renaming components

---
 config/files.js                               |  5 +-
 lib/org/chromium/webidl/HTMLFileContents.js   | 35 +++++++++++++
 lib/org/chromium/webidl/IDLFileContents.js    |  1 -
 ...FileContent.js => IDLFragmentExtractor.js} |  8 +--
 test/any/htmlFileClasses-test.js              | 51 +++++++++++++++++++
 ...t-test.js => IDLFragmentExtractor-test.js} | 45 +++++++++++-----
 6 files changed, 125 insertions(+), 20 deletions(-)
 create mode 100644 lib/org/chromium/webidl/HTMLFileContents.js
 rename lib/org/chromium/webidl/{HTMLFileContent.js => IDLFragmentExtractor.js} (94%)
 create mode 100644 test/any/htmlFileClasses-test.js
 rename test/node/parsing/{HTMLFileContent-test.js => IDLFragmentExtractor-test.js} (68%)

diff --git a/config/files.js b/config/files.js
index 43ffff0..3113d8b 100644
--- a/config/files.js
+++ b/config/files.js
@@ -90,8 +90,9 @@
     `lib${sep}org${sep}chromium${sep}webidl${sep}ast${sep}Stringifier.js`,
     `lib${sep}org${sep}chromium${sep}webidl${sep}ast${sep}Float.js`,
 
-    // HTML File Content Parser
-    `lib${sep}org${sep}chromium${sep}webidl${sep}HTMLFileContent.js`,
+    // HTML File Content and Extractor
+    `lib${sep}org${sep}chromium${sep}webidl${sep}HTMLFileContents.js`,
+    `lib${sep}org${sep}chromium${sep}webidl${sep}IDLFragmentExtractor.js`,
 
     // Web IDL parsers
     `lib${sep}org${sep}chromium${sep}webidl${sep}BaseParser.js`,
diff --git a/lib/org/chromium/webidl/HTMLFileContents.js b/lib/org/chromium/webidl/HTMLFileContents.js
new file mode 100644
index 0000000..44d8038
--- /dev/null
+++ b/lib/org/chromium/webidl/HTMLFileContents.js
@@ -0,0 +1,35 @@
+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+'use strict';
+
+foam.CLASS({
+  package: 'org.chromium.webidl',
+  name: 'HTMLFileContents',
+
+  documentation: 'An HTML file that can be fetched via HTTP and stores it contents.',
+
+  requires: ['foam.net.HTTPRequest'],
+
+  ids: ['url', 'timestamp'],
+
+  properties: [
+    {
+      class: 'String',
+      name: 'url',
+      required: true,
+      final: true
+    },
+    {
+      class: 'Date',
+      name: 'timestamp',
+      required: true,
+      final: true,
+    },
+    {
+      class: 'String',
+      name: 'content',
+      final: true,
+    },
+  ],
+});
diff --git a/lib/org/chromium/webidl/IDLFileContents.js b/lib/org/chromium/webidl/IDLFileContents.js
index e541118..6ac6652 100644
--- a/lib/org/chromium/webidl/IDLFileContents.js
+++ b/lib/org/chromium/webidl/IDLFileContents.js
@@ -12,7 +12,6 @@ foam.CLASS({
   requires: [
     'foam.core.Property',
     'foam.net.HTTPrequest',
-    'org.chromium.webidl.IDLFileBase',
   ],
 
   properties: [
diff --git a/lib/org/chromium/webidl/HTMLFileContent.js b/lib/org/chromium/webidl/IDLFragmentExtractor.js
similarity index 94%
rename from lib/org/chromium/webidl/HTMLFileContent.js
rename to lib/org/chromium/webidl/IDLFragmentExtractor.js
index ae60b3e..df3ec54 100644
--- a/lib/org/chromium/webidl/HTMLFileContent.js
+++ b/lib/org/chromium/webidl/IDLFragmentExtractor.js
@@ -5,8 +5,8 @@
 
 foam.CLASS({
   package: 'org.chromium.webidl',
-  name: 'HTMLFileContent',
-  documentation: 'stores the html file and the tags of interest found',
+  name: 'IDLFragmentExtractor',
+  documentation: 'extracts IDL Fragments from HTML files',
   requires: [
     'foam.parsers.html.HTMLLexer'
   ],
@@ -14,9 +14,9 @@ foam.CLASS({
   properties: [
     {
       name: 'file',
-      // description: 'content of the HTML file',
+      of: 'org.chromium.webidl.HTMLFileContent',
       postSet: function(_, file) {
-        this.idlFragments = this.parse(file);
+        this.idlFragments = this.parse(file.content);
       }
     },
     {
diff --git a/test/any/htmlFileClasses-test.js b/test/any/htmlFileClasses-test.js
new file mode 100644
index 0000000..17ebf84
--- /dev/null
+++ b/test/any/htmlFileClasses-test.js
@@ -0,0 +1,51 @@
+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+'use strict';
+
+describe('HTML file classes', function() {
+  var HTMLFileContents;
+
+  beforeEach(function() {
+    HTMLFileContents = foam.lookup('org.chromium.webidl.HTMLFileContents');
+  });
+
+  it('should fetch some content and properly set the timestamp', function() {
+    var url = 'http://someTest.url/index.html';
+    var content = '';
+    var date = new Date();
+    var file = HTMLFileContents.create({
+      url: url,
+      timestamp: new Date(),
+      content: content
+    });
+
+    // Verify properties are as set
+    expect(file.url).toBe(url);
+    expect(file.timestamp.getTime()).toBe(date.getTime());
+    expect(file.content).toBe(content);
+  });
+
+  it('should fail to set HTMLFileContent props after creation', function() {
+    var initUrl = 'http://someTest.url/index.html';
+    var newUrl = 'http://someOther.url/index.html';
+    var initContent = '';
+    var newContent = 'Potato';
+    var origDate = new Date(0);
+    var newDate = new Date();
+
+    var file = HTMLFileContents.create({
+      url: initUrl,
+      timestamp: origDate,
+      content: initContent
+    });
+
+    // On set, they should fail
+    expect(function() { file.url = newUrl; }).toThrow();
+    expect(file.url).toBe(initUrl);
+    expect(function() { file.content = newContent; }).toThrow();
+    expect(file.content).toBe(initContent);
+    expect(function() { file.timestamp = newDate; }).toThrow();
+    expect(file.timestamp.getTime()).toBe(origDate.getTime());
+  });
+});
diff --git a/test/node/parsing/HTMLFileContent-test.js b/test/node/parsing/IDLFragmentExtractor-test.js
similarity index 68%
rename from test/node/parsing/HTMLFileContent-test.js
rename to test/node/parsing/IDLFragmentExtractor-test.js
index c22cc37..be47088 100644
--- a/test/node/parsing/HTMLFileContent-test.js
+++ b/test/node/parsing/IDLFragmentExtractor-test.js
@@ -3,15 +3,23 @@
 // found in the LICENSE file.
 'use strict';
 
-describe('HTMLFileContent', function() {
-  var HTMLFileContent;
+describe('IDLFragmentExtractor', function() {
+  var HTMLFileContents;
+  var IDLFragmentExtractor;
   var Parser;
 
   function cmpTest(testName, testDirectory, expectedIDL) {
     var fs = require('fs');
-    var spec = fs.readFileSync(`${testDirectory}/spec.html`).toString();
-    var htmlSpec = HTMLFileContent.create({ file: spec });
-    var idlFragments = htmlSpec.idlFragments;
+    var dir = `${testDirectory}/spec.html`;
+    var spec = fs.readFileSync(dir).toString();
+    var htmlFile = HTMLFileContents.create({
+      url: dir, // Setting URL to dir for testing purposes only.
+      timestamp: new Date(),
+      content: spec,
+    });
+
+    var extractor = IDLFragmentExtractor.create({file: htmlFile});
+    var idlFragments = extractor.idlFragments;
 
     // Determine the number of fragments that were found.
     expect(idlFragments.length).toBe(expectedIDL);
@@ -32,14 +40,20 @@ describe('HTMLFileContent', function() {
   }
 
   beforeEach(function() {
-    HTMLFileContent = foam.lookup('org.chromium.webidl.HTMLFileContent');
+    HTMLFileContents = foam.lookup('org.chromium.webidl.HTMLFileContents');
+    IDLFragmentExtractor = foam.lookup('org.chromium.webidl.IDLFragmentExtractor');
   });
 
   it('should parse a pre tag with no content', function() {
     var content = '
';
-    var htmlFile = HTMLFileContent.create({ file: content });
-    expect(htmlFile).toBeDefined();
-    expect(htmlFile.idlFragments.length).toBe(1);
+    var htmlFile = HTMLFileContents.create({
+      url: 'http://basicTest.url',
+      timestamp: new Date(),
+      content: content,
+    });
+    var extractor = IDLFragmentExtractor.create({file: htmlFile});
+    expect(extractor).toBeDefined();
+    expect(extractor.idlFragments.length).toBe(1);
   });
 
   it('should parse a HTML file with one Web IDL Block', function() {
@@ -55,10 +69,15 @@ describe('HTMLFileContent', function() {
           [TreatNullAs=EmptyString] DOMString sentence);
     };`;
     var content = `
${idl}
`;
-    var htmlFile = HTMLFileContent.create({ file: content });
-    expect(htmlFile).toBeDefined();
-    expect(htmlFile.idlFragments.length).toBe(1);
-    expect(htmlFile.idlFragments[0]).toBe(idl);
+    var htmlFile = HTMLFileContents.create({
+      url: 'http://something.url',
+      timestamp: new Date(),
+      content: content,
+    });
+    var extractor = IDLFragmentExtractor.create({file: htmlFile});
+    expect(extractor).toBeDefined();
+    expect(extractor.idlFragments.length).toBe(1);
+    expect(extractor.idlFragments[0]).toBe(idl);
   });
 
   it('should parse the UI Events spec HTML file (w3c)', function() {

From dd2bd1d4df5e04d95af19f53cb3363c277a66817 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Thu, 8 Jun 2017 11:01:22 -0400
Subject: [PATCH 11/23] Removing parsing step from extractor

---
 .../chromium/webidl/IDLFragmentExtractor.js   | 22 ++-----------------
 1 file changed, 2 insertions(+), 20 deletions(-)

diff --git a/lib/org/chromium/webidl/IDLFragmentExtractor.js b/lib/org/chromium/webidl/IDLFragmentExtractor.js
index df3ec54..4e4b438 100644
--- a/lib/org/chromium/webidl/IDLFragmentExtractor.js
+++ b/lib/org/chromium/webidl/IDLFragmentExtractor.js
@@ -16,35 +16,17 @@ foam.CLASS({
       name: 'file',
       of: 'org.chromium.webidl.HTMLFileContent',
       postSet: function(_, file) {
-        this.idlFragments = this.parse(file.content);
+        this.idlFragments = this.extract(file.content);
       }
     },
     {
       name: 'idlFragments',
       // description: 'all idlFragments found in the parsed HTML file',
-      postSet: function(_, fragments) {
-        var Parser = foam.lookup('org.chromium.webidl.Parser');
-        var parser = Parser.create();
-        var asts = [];
-
-        fragments.forEach(function(idl) {
-          var parsedContent = parser.parseString(idl);
-          if (parsedContent.pos !== idl.length) {
-            console.warn('Incomplete parse!');
-          } else {
-            asts.push(parsedContent.value);
-          }
-        });
-      }
-    },
-    {
-      name: 'ast',
-      // description: 'ast of IDL files found in the parsed HTML file'
     }
   ],
 
   methods: [
-    function parse(str) {
+    function extract(str) {
       var self = this;
       var lexer = self.HTMLLexer.create();
       var OPEN = lexer.TagType.OPEN.name;

From f812b588d2179ead0997252dc67c15f88cf63979 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Thu, 8 Jun 2017 11:19:44 -0400
Subject: [PATCH 12/23] Removing unused variables and fixing comment styling

---
 .../chromium/webidl/IDLFragmentExtractor.js   | 27 ++++++++++---------
 1 file changed, 14 insertions(+), 13 deletions(-)

diff --git a/lib/org/chromium/webidl/IDLFragmentExtractor.js b/lib/org/chromium/webidl/IDLFragmentExtractor.js
index 4e4b438..bc5a85f 100644
--- a/lib/org/chromium/webidl/IDLFragmentExtractor.js
+++ b/lib/org/chromium/webidl/IDLFragmentExtractor.js
@@ -16,22 +16,21 @@ foam.CLASS({
       name: 'file',
       of: 'org.chromium.webidl.HTMLFileContent',
       postSet: function(_, file) {
-        this.idlFragments = this.extract(file.content);
-      }
+        this.idlFragments = this.extract();
+      },
     },
     {
       name: 'idlFragments',
       // description: 'all idlFragments found in the parsed HTML file',
-    }
+    },
   ],
 
   methods: [
-    function extract(str) {
+    function extract() {
       var self = this;
       var lexer = self.HTMLLexer.create();
       var OPEN = lexer.TagType.OPEN.name;
       var CLOSE = lexer.TagType.CLOSE.name;
-      var OPEN_CLOSE = lexer.TagType.OPEN_CLOSE.name;
       var extractAttr = function(node, attrName) {
         var retVal;
         node.attributes.some(function(attr) {
@@ -42,13 +41,13 @@ foam.CLASS({
         return retVal;
       };
 
-      var results = lexer.parseString(str).value;
+      var results = lexer.parseString(self.file.content).value;
 
-      var idlFragments = [];        // Processed output
+      var idlFragments = [];
       var tagStack = [];            // Used for tag matching.
-      var tagMatching = true;       // true: not inside a pre of interest
-      var exclude = false;
-      var content = '';             // Used to group together related content
+      var tagMatching = true;       // Set whe not inside a pre tag of interest.
+      var exclude = false;          // Set when inside example or note class.
+      var content = '';             // Used to group together related content.
       for (var i = 0; i < results.length; i++) {
         var item = results[i];
         var isTag = lexer.Tag.isInstance(item);
@@ -67,10 +66,12 @@ foam.CLASS({
           var top = tagStack[tagStack.length - 1];
           var classes = extractAttr(item, 'class');
           var isIDL = classes && classes.includes('idl');
-          var isExcludeTag = classes && (classes.includes('example') || classes.includes('note'));
+          var isExcluded = function(cls) {
+            return cls && (cls.includes('example') || cls.includes('note'));
+          };
 
           if (item.type.name === OPEN) {
-            if (isExcludeTag) {
+            if (isExcluded(classes)) {
               exclude = true;
             } else if (!exclude && item.nodeName === 'pre' && isIDL) {
               // Found a 
.
@@ -80,7 +81,7 @@ foam.CLASS({
             tagStack.push(item);
           } else if (top && item.type.name === CLOSE && top.nodeName === item.nodeName) {
             var parentCls = extractAttr(top, 'class');
-            if (parentCls && (parentCls.includes('example') || parentCls.includes('note'))) exclude = false;
+            if (isExcluded(parentCls)) exclude = false;
             tagStack.pop();
           } else {
             // Mismatched close tags and OPEN_CLOSE tags are ignored

From ff6ad906676a38df91552be75497cdd194fefe55 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Thu, 8 Jun 2017 14:50:27 -0400
Subject: [PATCH 13/23] Fixing description for HTMLFileContents

---
 lib/org/chromium/webidl/HTMLFileContents.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/org/chromium/webidl/HTMLFileContents.js b/lib/org/chromium/webidl/HTMLFileContents.js
index 44d8038..7553d6a 100644
--- a/lib/org/chromium/webidl/HTMLFileContents.js
+++ b/lib/org/chromium/webidl/HTMLFileContents.js
@@ -7,7 +7,7 @@ foam.CLASS({
   package: 'org.chromium.webidl',
   name: 'HTMLFileContents',
 
-  documentation: 'An HTML file that can be fetched via HTTP and stores it contents.',
+  documentation: 'An HTML file that stores it contents.',
 
   requires: ['foam.net.HTTPRequest'],
 

From c5fb6fb591313ba3d740eaf0a853a33e691f578e Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Thu, 8 Jun 2017 17:26:51 -0400
Subject: [PATCH 14/23] Removing requirement for HTTPRequest in
 HTMLFileContents

---
 lib/org/chromium/webidl/HTMLFileContents.js | 2 --
 1 file changed, 2 deletions(-)

diff --git a/lib/org/chromium/webidl/HTMLFileContents.js b/lib/org/chromium/webidl/HTMLFileContents.js
index 7553d6a..f92c08f 100644
--- a/lib/org/chromium/webidl/HTMLFileContents.js
+++ b/lib/org/chromium/webidl/HTMLFileContents.js
@@ -9,8 +9,6 @@ foam.CLASS({
 
   documentation: 'An HTML file that stores it contents.',
 
-  requires: ['foam.net.HTTPRequest'],
-
   ids: ['url', 'timestamp'],
 
   properties: [

From c736c28f1139c9765bf6dfa86ba0d3739e8f850e Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Fri, 9 Jun 2017 10:51:09 -0400
Subject: [PATCH 15/23] Allowing for nested excluded tags

---
 lib/org/chromium/webidl/IDLFragmentExtractor.js | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/lib/org/chromium/webidl/IDLFragmentExtractor.js b/lib/org/chromium/webidl/IDLFragmentExtractor.js
index bc5a85f..2efbdaf 100644
--- a/lib/org/chromium/webidl/IDLFragmentExtractor.js
+++ b/lib/org/chromium/webidl/IDLFragmentExtractor.js
@@ -45,8 +45,8 @@ foam.CLASS({
 
       var idlFragments = [];
       var tagStack = [];            // Used for tag matching.
+      var excludeStack = [];        // Used for tracking excluded (example/note) tags.
       var tagMatching = true;       // Set whe not inside a pre tag of interest.
-      var exclude = false;          // Set when inside example or note class.
       var content = '';             // Used to group together related content.
       for (var i = 0; i < results.length; i++) {
         var item = results[i];
@@ -72,8 +72,8 @@ foam.CLASS({
 
           if (item.type.name === OPEN) {
             if (isExcluded(classes)) {
-              exclude = true;
-            } else if (!exclude && item.nodeName === 'pre' && isIDL) {
+              excludeStack.push(item);
+            } else if (excludeStack.length === 0 && item.nodeName === 'pre' && isIDL) {
               // Found a 
.
               // Ignore tags and only extract text now.
               tagMatching = false;
@@ -81,7 +81,10 @@ foam.CLASS({
             tagStack.push(item);
           } else if (top && item.type.name === CLOSE && top.nodeName === item.nodeName) {
             var parentCls = extractAttr(top, 'class');
-            if (isExcluded(parentCls)) exclude = false;
+            var excludeStackTop = excludeStack[excludeStack.length - 1];
+            if (isExcluded(parentCls) && item.nodeName === excludeStackTop.nodeName) {
+              excludeStack.pop();
+            }
             tagStack.pop();
           } else {
             // Mismatched close tags and OPEN_CLOSE tags are ignored

From af4cd9d0c9f3186b6f61f2c6a83918a57a2c1755 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Fri, 9 Jun 2017 11:06:36 -0400
Subject: [PATCH 16/23] Adding support for nested exclude tags

---
 .../chromium/webidl/IDLFragmentExtractor.js   |  2 +-
 .../node/parsing/IDLFragmentExtractor-test.js | 30 +++++++++++++++++++
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/lib/org/chromium/webidl/IDLFragmentExtractor.js b/lib/org/chromium/webidl/IDLFragmentExtractor.js
index 2efbdaf..c15a5eb 100644
--- a/lib/org/chromium/webidl/IDLFragmentExtractor.js
+++ b/lib/org/chromium/webidl/IDLFragmentExtractor.js
@@ -87,7 +87,7 @@ foam.CLASS({
             }
             tagStack.pop();
           } else {
-            // Mismatched close tags and OPEN_CLOSE tags are ignored
+            // Mismatched close tags and OPEN_CLOSE tags are ignored.
           }
         }
       }
diff --git a/test/node/parsing/IDLFragmentExtractor-test.js b/test/node/parsing/IDLFragmentExtractor-test.js
index be47088..0d3b51b 100644
--- a/test/node/parsing/IDLFragmentExtractor-test.js
+++ b/test/node/parsing/IDLFragmentExtractor-test.js
@@ -80,6 +80,36 @@ describe('IDLFragmentExtractor', function() {
     expect(extractor.idlFragments[0]).toBe(idl);
   });
 
+  it('should parse a HTML file with nested excludes', function() {
+    var firstIDL = `
+      interface Potato {
+        attribute unsigned long weight;
+      };`;
+    var secondIDL = `
+      interface Tomato {
+        attribute unsigned long weight;
+      };`;
+    var content = `
+      
+        

+          
Something here

+          

+            
${firstIDL}

+          

+        

+        
${secondIDL}

+      `;
+    var htmlFile = HTMLFileContents.create({
+      url: 'http://something.url',
+      timestamp: new Date(),
+      content: content,
+    });
+    var extractor = IDLFragmentExtractor.create({file: htmlFile});
+    expect(extractor).toBeDefined();
+    expect(extractor.idlFragments.length).toBe(1);
+    expect(extractor.idlFragments[0]).toBe(secondIDL);
+  });
+
   it('should parse the UI Events spec HTML file (w3c)', function() {
     var testDirectory = `${__dirname}/UIEvent`;
     var expectedFragments = 18;

From 20932a64f351115996a291df698d9a89bb577887 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Tue, 13 Jun 2017 11:26:41 -0400
Subject: [PATCH 17/23] Adding Future message with regards to nested pre tags

---
 lib/org/chromium/webidl/IDLFragmentExtractor.js | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/lib/org/chromium/webidl/IDLFragmentExtractor.js b/lib/org/chromium/webidl/IDLFragmentExtractor.js
index c15a5eb..43974ac 100644
--- a/lib/org/chromium/webidl/IDLFragmentExtractor.js
+++ b/lib/org/chromium/webidl/IDLFragmentExtractor.js
@@ -51,7 +51,10 @@ foam.CLASS({
       for (var i = 0; i < results.length; i++) {
         var item = results[i];
         var isTag = lexer.Tag.isInstance(item);
-
+        
+        // FUTURE: Handle nested pre tags.
+        // As of this writing, there has not been any IDL fragments
+        // that has been found within nested pre tags.
         if (!tagMatching) {
           // Ignoring all tags. Only extracting text within pre tags.
           if (isTag && item.nodeName === 'pre') {

From 5f93bbbf9c1927ff04bf9d89d6f3fe5263869951 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Tue, 13 Jun 2017 11:54:20 -0400
Subject: [PATCH 18/23] Fixing minor formatting problem

---
 lib/org/chromium/webidl/HTMLFileContents.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/org/chromium/webidl/HTMLFileContents.js b/lib/org/chromium/webidl/HTMLFileContents.js
index f92c08f..c0d3944 100644
--- a/lib/org/chromium/webidl/HTMLFileContents.js
+++ b/lib/org/chromium/webidl/HTMLFileContents.js
@@ -16,7 +16,7 @@ foam.CLASS({
       class: 'String',
       name: 'url',
       required: true,
-      final: true
+      final: true,
     },
     {
       class: 'Date',

From 30df62a068934c6bd27242c359204078b6fbdad7 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Wed, 14 Jun 2017 10:35:57 -0400
Subject: [PATCH 19/23] Additional documentation in IDLFragmentExtractor and
 HTMLFileContents

---
 lib/org/chromium/webidl/HTMLFileContents.js   | 13 +++--
 .../chromium/webidl/IDLFragmentExtractor.js   | 31 +++++++----
 test/any/HTMLFileContents-test.js             | 28 ++++++++++
 test/any/htmlFileClasses-test.js              | 51 -------------------
 .../node/parsing/IDLFragmentExtractor-test.js | 33 ++++++++----
 5 files changed, 79 insertions(+), 77 deletions(-)
 create mode 100644 test/any/HTMLFileContents-test.js
 delete mode 100644 test/any/htmlFileClasses-test.js

diff --git a/lib/org/chromium/webidl/HTMLFileContents.js b/lib/org/chromium/webidl/HTMLFileContents.js
index c0d3944..33559c2 100644
--- a/lib/org/chromium/webidl/HTMLFileContents.js
+++ b/lib/org/chromium/webidl/HTMLFileContents.js
@@ -7,7 +7,7 @@ foam.CLASS({
   package: 'org.chromium.webidl',
   name: 'HTMLFileContents',
 
-  documentation: 'An HTML file that stores it contents.',
+  documentation: 'An HTML file that stores the raw content of the response.',
 
   ids: ['url', 'timestamp'],
 
@@ -16,18 +16,21 @@ foam.CLASS({
       class: 'String',
       name: 'url',
       required: true,
-      final: true,
     },
     {
       class: 'Date',
       name: 'timestamp',
       required: true,
-      final: true,
     },
     {
       class: 'String',
-      name: 'content',
-      final: true,
+      name: 'contents',
     },
+    {
+      class: 'Array',
+      of: 'String',
+      name: 'references',
+      factory: function() { return []; },
+    }
   ],
 });
diff --git a/lib/org/chromium/webidl/IDLFragmentExtractor.js b/lib/org/chromium/webidl/IDLFragmentExtractor.js
index 43974ac..ca09fe5 100644
--- a/lib/org/chromium/webidl/IDLFragmentExtractor.js
+++ b/lib/org/chromium/webidl/IDLFragmentExtractor.js
@@ -6,9 +6,10 @@
 foam.CLASS({
   package: 'org.chromium.webidl',
   name: 'IDLFragmentExtractor',
-  documentation: 'extracts IDL Fragments from HTML files',
+  documentation: 'Extracts IDL Fragments from HTML files.',
   requires: [
-    'foam.parsers.html.HTMLLexer'
+    'foam.parsers.html.HTMLLexer',
+    'foam.parsers.html.TagType',
   ],
 
   properties: [
@@ -27,10 +28,9 @@ foam.CLASS({
 
   methods: [
     function extract() {
-      var self = this;
-      var lexer = self.HTMLLexer.create();
-      var OPEN = lexer.TagType.OPEN.name;
-      var CLOSE = lexer.TagType.CLOSE.name;
+      var lexer = this.HTMLLexer.create();
+      var OPEN = this.TagType.OPEN.name;
+      var CLOSE = this.TagType.CLOSE.name;
       var extractAttr = function(node, attrName) {
         var retVal;
         node.attributes.some(function(attr) {
@@ -41,7 +41,8 @@ foam.CLASS({
         return retVal;
       };
 
-      var results = lexer.parseString(self.file.content).value;
+      var results = lexer.parseString(this.file.contents).value;
+      if (!results) throw "IDL Parse was not successful.";
 
       var idlFragments = [];
       var tagStack = [];            // Used for tag matching.
@@ -51,12 +52,12 @@ foam.CLASS({
       for (var i = 0; i < results.length; i++) {
         var item = results[i];
         var isTag = lexer.Tag.isInstance(item);
-        
+
         // FUTURE: Handle nested pre tags.
         // As of this writing, there has not been any IDL fragments
         // that has been found within nested pre tags.
         if (!tagMatching) {
-          // Ignoring all tags. Only extracting text within pre tags.
+          // Ignoring all tags. Only extracting text content within pre tags.
           if (isTag && item.nodeName === 'pre') {
             tagMatching = true;
             tagStack.pop();
@@ -66,6 +67,8 @@ foam.CLASS({
             content += isTag ? '' : item;
           }
         } else if (isTag) {
+          // Encountered a tag and we are tag matching.
+          // Perform appropriate action based on class attribute and tagType.
           var top = tagStack[tagStack.length - 1];
           var classes = extractAttr(item, 'class');
           var isIDL = classes && classes.includes('idl');
@@ -75,6 +78,7 @@ foam.CLASS({
 
           if (item.type.name === OPEN) {
             if (isExcluded(classes)) {
+              // Entering the body of an excluded tag.
               excludeStack.push(item);
             } else if (excludeStack.length === 0 && item.nodeName === 'pre' && isIDL) {
               // Found a 
.
@@ -83,9 +87,14 @@ foam.CLASS({
             }
             tagStack.push(item);
           } else if (top && item.type.name === CLOSE && top.nodeName === item.nodeName) {
-            var parentCls = extractAttr(top, 'class');
+            // Item is a close tag matching the tag at the top of the stack.
+            // Aliasing for readability.
+            var openTag = top;
+            var closeTag = item;
+
+            var openTagCls = extractAttr(openTag, 'class');
             var excludeStackTop = excludeStack[excludeStack.length - 1];
-            if (isExcluded(parentCls) && item.nodeName === excludeStackTop.nodeName) {
+            if (isExcluded(openTagCls) && closeTag.nodeName === excludeStackTop.nodeName) {
               excludeStack.pop();
             }
             tagStack.pop();
diff --git a/test/any/HTMLFileContents-test.js b/test/any/HTMLFileContents-test.js
new file mode 100644
index 0000000..faef175
--- /dev/null
+++ b/test/any/HTMLFileContents-test.js
@@ -0,0 +1,28 @@
+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+'use strict';
+
+describe('HTML file classes', function() {
+  var HTMLFileContents;
+
+  beforeEach(function() {
+    HTMLFileContents = foam.lookup('org.chromium.webidl.HTMLFileContents');
+  });
+
+  it('should fetch some content and properly set the timestamp', function() {
+    var url = 'http://someTest.url/index.html';
+    var contents = '';
+    var date = new Date();
+    var file = HTMLFileContents.create({
+      url: url,
+      timestamp: new Date(),
+      contents: contents
+    });
+
+    // Verify properties are as set
+    expect(file.url).toBe(url);
+    expect(file.timestamp.getTime()).toBe(date.getTime());
+    expect(file.contents).toBe(contents);
+  });
+});
diff --git a/test/any/htmlFileClasses-test.js b/test/any/htmlFileClasses-test.js
deleted file mode 100644
index 17ebf84..0000000
--- a/test/any/htmlFileClasses-test.js
+++ /dev/null
@@ -1,51 +0,0 @@
-// Copyright 2017 The Chromium Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style license that can be
-// found in the LICENSE file.
-'use strict';
-
-describe('HTML file classes', function() {
-  var HTMLFileContents;
-
-  beforeEach(function() {
-    HTMLFileContents = foam.lookup('org.chromium.webidl.HTMLFileContents');
-  });
-
-  it('should fetch some content and properly set the timestamp', function() {
-    var url = 'http://someTest.url/index.html';
-    var content = '';
-    var date = new Date();
-    var file = HTMLFileContents.create({
-      url: url,
-      timestamp: new Date(),
-      content: content
-    });
-
-    // Verify properties are as set
-    expect(file.url).toBe(url);
-    expect(file.timestamp.getTime()).toBe(date.getTime());
-    expect(file.content).toBe(content);
-  });
-
-  it('should fail to set HTMLFileContent props after creation', function() {
-    var initUrl = 'http://someTest.url/index.html';
-    var newUrl = 'http://someOther.url/index.html';
-    var initContent = '';
-    var newContent = 'Potato';
-    var origDate = new Date(0);
-    var newDate = new Date();
-
-    var file = HTMLFileContents.create({
-      url: initUrl,
-      timestamp: origDate,
-      content: initContent
-    });
-
-    // On set, they should fail
-    expect(function() { file.url = newUrl; }).toThrow();
-    expect(file.url).toBe(initUrl);
-    expect(function() { file.content = newContent; }).toThrow();
-    expect(file.content).toBe(initContent);
-    expect(function() { file.timestamp = newDate; }).toThrow();
-    expect(file.timestamp.getTime()).toBe(origDate.getTime());
-  });
-});
diff --git a/test/node/parsing/IDLFragmentExtractor-test.js b/test/node/parsing/IDLFragmentExtractor-test.js
index 0d3b51b..228ed7f 100644
--- a/test/node/parsing/IDLFragmentExtractor-test.js
+++ b/test/node/parsing/IDLFragmentExtractor-test.js
@@ -8,21 +8,21 @@ describe('IDLFragmentExtractor', function() {
   var IDLFragmentExtractor;
   var Parser;
 
-  function cmpTest(testName, testDirectory, expectedIDL) {
+  function cmpTest(testName, testDirectory, numExpectedIDLFragments) {
     var fs = require('fs');
     var dir = `${testDirectory}/spec.html`;
     var spec = fs.readFileSync(dir).toString();
     var htmlFile = HTMLFileContents.create({
       url: dir, // Setting URL to dir for testing purposes only.
       timestamp: new Date(),
-      content: spec,
+      contents: spec,
     });
 
     var extractor = IDLFragmentExtractor.create({file: htmlFile});
     var idlFragments = extractor.idlFragments;
 
     // Determine the number of fragments that were found.
-    expect(idlFragments.length).toBe(expectedIDL);
+    expect(idlFragments.length).toBe(numExpectedIDLFragments);
 
     fs.readdir(testDirectory, function(err, files) {
       // Go through each of the expected results in the folder.
@@ -30,7 +30,8 @@ describe('IDLFragmentExtractor', function() {
         var testNum = Number(filename);
 
         if (!isNaN(testNum) && testNum < idlFragments.length) {
-          var expectedContent = fs.readFileSync(`${testDirectory}/${filename}`).toString();
+          var path = `${testDirectory}/${filename}`;
+          var expectedContent = fs.readFileSync(path).toString();
           expect(idlFragments[testNum].trim()).toBe(expectedContent.trim());
         } else if (filename !== 'spec.html') {
           fail(`File ${filename} was not used in ${testName} spec test`);
@@ -45,11 +46,23 @@ describe('IDLFragmentExtractor', function() {
   });
 
   it('should parse a pre tag with no content', function() {
-    var content = '
';
+    var contents = '
';
     var htmlFile = HTMLFileContents.create({
       url: 'http://basicTest.url',
       timestamp: new Date(),
-      content: content,
+      contents: contents,
+    });
+    var extractor = IDLFragmentExtractor.create({file: htmlFile});
+    expect(extractor).toBeDefined();
+    expect(extractor.idlFragments.length).toBe(1);
+  });
+
+  it('should parse a pre tag with multiple attributes', function() {
+    var contents = '
';
+    var htmlFile = HTMLFileContents.create({
+      url: 'http://basicTest.url',
+      timestamp: new Date(),
+      contents: contents,
     });
     var extractor = IDLFragmentExtractor.create({file: htmlFile});
     expect(extractor).toBeDefined();
@@ -68,11 +81,11 @@ describe('IDLFragmentExtractor', function() {
         void yell([AllowAny] unsigned long volume,
           [TreatNullAs=EmptyString] DOMString sentence);
     };`;
-    var content = `
${idl}
`;
+    var contents = `
${idl}
`;
     var htmlFile = HTMLFileContents.create({
       url: 'http://something.url',
       timestamp: new Date(),
-      content: content,
+      contents: contents,
     });
     var extractor = IDLFragmentExtractor.create({file: htmlFile});
     expect(extractor).toBeDefined();
@@ -89,7 +102,7 @@ describe('IDLFragmentExtractor', function() {
       interface Tomato {
         attribute unsigned long weight;
       };`;
-    var content = `
+    var contents = `
       
         

           
Something here

@@ -102,7 +115,7 @@ describe('IDLFragmentExtractor', function() {
     var htmlFile = HTMLFileContents.create({
       url: 'http://something.url',
       timestamp: new Date(),
-      content: content,
+      contents: contents,
     });
     var extractor = IDLFragmentExtractor.create({file: htmlFile});
     expect(extractor).toBeDefined();

From 7c3d78ea99656a4b5784180ebd7012707e751b9f Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Wed, 14 Jun 2017 10:52:44 -0400
Subject: [PATCH 20/23] Adding additional documentation to IDLFragmentExtractor

---
 .../chromium/webidl/IDLFragmentExtractor.js   | 21 +++++++++++--------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/lib/org/chromium/webidl/IDLFragmentExtractor.js b/lib/org/chromium/webidl/IDLFragmentExtractor.js
index ca09fe5..ca69286 100644
--- a/lib/org/chromium/webidl/IDLFragmentExtractor.js
+++ b/lib/org/chromium/webidl/IDLFragmentExtractor.js
@@ -32,10 +32,10 @@ foam.CLASS({
       var OPEN = this.TagType.OPEN.name;
       var CLOSE = this.TagType.CLOSE.name;
       var extractAttr = function(node, attrName) {
-        var retVal;
-        node.attributes.some(function(attr) {
+        var retVal = [];
+        node.attributes.forEach(function(attr) {
           if (attr.name === attrName) {
-            retVal = attr.value.split(' ');
+            retVal = retVal.concat(attr.value.split(' '));
           }
         });
         return retVal;
@@ -58,13 +58,16 @@ foam.CLASS({
         // that has been found within nested pre tags.
         if (!tagMatching) {
           // Ignoring all tags. Only extracting text content within pre tags.
-          if (isTag && item.nodeName === 'pre') {
-            tagMatching = true;
-            tagStack.pop();
-            idlFragments.push(lexer.lib.unescapeString(content));
-            content = '';
+          if (isTag) {
+            if (item.nodeName === 'pre') {
+              tagMatching = true;
+              tagStack.pop();
+              idlFragments.push(lexer.lib.unescapeString(content));
+              content = '';
+            }
           } else {
-            content += isTag ? '' : item;
+            // item is text fragments, so we append it.
+            content += item;
           }
         } else if (isTag) {
           // Encountered a tag and we are tag matching.

From 686562529626b5f7cd51eb9bff9cc400a506ae16 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Wed, 14 Jun 2017 10:58:12 -0400
Subject: [PATCH 21/23] Formatting and style fixes on HTMLFileContents and
 IDLFragmentExtractor

---
 lib/org/chromium/webidl/HTMLFileContents.js     |  2 +-
 lib/org/chromium/webidl/IDLFragmentExtractor.js | 13 ++++++++-----
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/lib/org/chromium/webidl/HTMLFileContents.js b/lib/org/chromium/webidl/HTMLFileContents.js
index 33559c2..9124051 100644
--- a/lib/org/chromium/webidl/HTMLFileContents.js
+++ b/lib/org/chromium/webidl/HTMLFileContents.js
@@ -31,6 +31,6 @@ foam.CLASS({
       of: 'String',
       name: 'references',
       factory: function() { return []; },
-    }
+    },
   ],
 });
diff --git a/lib/org/chromium/webidl/IDLFragmentExtractor.js b/lib/org/chromium/webidl/IDLFragmentExtractor.js
index ca69286..4171deb 100644
--- a/lib/org/chromium/webidl/IDLFragmentExtractor.js
+++ b/lib/org/chromium/webidl/IDLFragmentExtractor.js
@@ -83,13 +83,15 @@ foam.CLASS({
             if (isExcluded(classes)) {
               // Entering the body of an excluded tag.
               excludeStack.push(item);
-            } else if (excludeStack.length === 0 && item.nodeName === 'pre' && isIDL) {
+            } else if (excludeStack.length === 0
+                && item.nodeName === 'pre' && isIDL) {
               // Found a 
.
               // Ignore tags and only extract text now.
               tagMatching = false;
             }
             tagStack.push(item);
-          } else if (top && item.type.name === CLOSE && top.nodeName === item.nodeName) {
+          } else if (top && item.type.name === CLOSE
+              && top.nodeName === item.nodeName) {
             // Item is a close tag matching the tag at the top of the stack.
             // Aliasing for readability.
             var openTag = top;
@@ -97,7 +99,8 @@ foam.CLASS({
 
             var openTagCls = extractAttr(openTag, 'class');
             var excludeStackTop = excludeStack[excludeStack.length - 1];
-            if (isExcluded(openTagCls) && closeTag.nodeName === excludeStackTop.nodeName) {
+            if (isExcluded(openTagCls) &&
+                closeTag.nodeName === excludeStackTop.nodeName) {
               excludeStack.pop();
             }
             tagStack.pop();
@@ -107,7 +110,7 @@ foam.CLASS({
         }
       }
       return idlFragments;
-    }
-  ]
+    },
+  ],
 });
 

From 2dc37e81ec43e06d4cdd217b07d5c5f11098e454 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Mon, 26 Jun 2017 13:00:04 -0400
Subject: [PATCH 22/23] Minor changes to HTMLFileContents and removing unneeded
 test

---
 lib/org/chromium/webidl/HTMLFileContents.js   |  2 +-
 .../chromium/webidl/IDLFragmentExtractor.js   |  2 +-
 test/any/HTMLFileContents-test.js             | 28 -------------------
 3 files changed, 2 insertions(+), 30 deletions(-)
 delete mode 100644 test/any/HTMLFileContents-test.js

diff --git a/lib/org/chromium/webidl/HTMLFileContents.js b/lib/org/chromium/webidl/HTMLFileContents.js
index 9124051..70460c5 100644
--- a/lib/org/chromium/webidl/HTMLFileContents.js
+++ b/lib/org/chromium/webidl/HTMLFileContents.js
@@ -30,7 +30,7 @@ foam.CLASS({
       class: 'Array',
       of: 'String',
       name: 'references',
-      factory: function() { return []; },
+      // documentation: 'An array of files referencing the URL of this file',
     },
   ],
 });
diff --git a/lib/org/chromium/webidl/IDLFragmentExtractor.js b/lib/org/chromium/webidl/IDLFragmentExtractor.js
index 4171deb..89062df 100644
--- a/lib/org/chromium/webidl/IDLFragmentExtractor.js
+++ b/lib/org/chromium/webidl/IDLFragmentExtractor.js
@@ -42,7 +42,7 @@ foam.CLASS({
       };
 
       var results = lexer.parseString(this.file.contents).value;
-      if (!results) throw "IDL Parse was not successful.";
+      if (!results) throw new Error("IDL Parse was not successful.");
 
       var idlFragments = [];
       var tagStack = [];            // Used for tag matching.
diff --git a/test/any/HTMLFileContents-test.js b/test/any/HTMLFileContents-test.js
deleted file mode 100644
index faef175..0000000
--- a/test/any/HTMLFileContents-test.js
+++ /dev/null
@@ -1,28 +0,0 @@
-// Copyright 2017 The Chromium Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style license that can be
-// found in the LICENSE file.
-'use strict';
-
-describe('HTML file classes', function() {
-  var HTMLFileContents;
-
-  beforeEach(function() {
-    HTMLFileContents = foam.lookup('org.chromium.webidl.HTMLFileContents');
-  });
-
-  it('should fetch some content and properly set the timestamp', function() {
-    var url = 'http://someTest.url/index.html';
-    var contents = '';
-    var date = new Date();
-    var file = HTMLFileContents.create({
-      url: url,
-      timestamp: new Date(),
-      contents: contents
-    });
-
-    // Verify properties are as set
-    expect(file.url).toBe(url);
-    expect(file.timestamp.getTime()).toBe(date.getTime());
-    expect(file.contents).toBe(contents);
-  });
-});

From c93dec6f151093586a139566988833b43e2d96b1 Mon Sep 17 00:00:00 2001
From: Michael Cheung 
Date: Tue, 27 Jun 2017 10:21:46 -0400
Subject: [PATCH 23/23] Addressing formatting changes in HTMLFileContents

---
 lib/org/chromium/webidl/HTMLFileContents.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/org/chromium/webidl/HTMLFileContents.js b/lib/org/chromium/webidl/HTMLFileContents.js
index 70460c5..f996598 100644
--- a/lib/org/chromium/webidl/HTMLFileContents.js
+++ b/lib/org/chromium/webidl/HTMLFileContents.js
@@ -29,8 +29,8 @@ foam.CLASS({
     {
       class: 'Array',
       of: 'String',
+      documentation: 'Any array of files referencing the URL of this file.',
       name: 'references',
-      // documentation: 'An array of files referencing the URL of this file',
     },
   ],
 });