W3C

HTML HTML5 Image Description Extension

W3C First Public Working Editors' Draft 12 March 17 May 2013

This version: http://www.w3.org/TR/2013/WD-html-longdesc-20130312/ Latest published version:
http://www.w3.org/TR/html-longdesc/ http://www.w3.org/TR/HTML-longdesc
Latest editor's draft:
http://dvcs.w3.org/hg/html-proposals/raw-file/default/longdesc1/longdesc.html
Editor: Editors:
Charles McCathie (McCathie) Nevile , Яндекс. Яндекс Yandex

Abstract

This specification defines a longdesc attribute to link extended descriptions with images in HTML5-based content.

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/.

This document was developed through the HTML Accessibility Task Force , and is published by an editors' draft proposed to the HTML Working Group with approval by the Protocols and Formats Accessibility Task Force for publication as a Working Group . Bugs can Draft, which would be filed directly into proposed as the W3C Bug tracker basis for this specification . This document was published by the HTML Working Group as a Last Call Working Draft. Following feedback on the First Public Working Draft. This document is intended to become Draft , a W3C Recommendation. number of bugs were raised and resolved . If you wish to make comments regarding this document, please send them to public-html-a11y@w3.org ( subscribe , archives ). All comments are feedback is welcome. Bugs can also be filed directly into the W3C Bug tracker for this specification .

This document is intended to become a W3C Recommendation, either on its own or merged into an HTML Recommendation.

Publication as a First Public 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 .

Table of Contents

Introduction

HTML 4 provided a longdesc attribute for the img element. This enabled a machine-discoverable description of an image to be linked to the image. This extension specification defines the same functionality for HTML5-based content.

<!-- The description is somewhere on the same page as the image --> <img src="http://example.com/graph1" alt="(The trend is for drinks to get sweeter)" title="Figure One" > <!-- The description is a page on its own -->


<!-- The description is somewhere on the same page as the image --> <img src="http://example.com/graph1" alt="(Drinks are getting sweeter)" title="Figure One" longdesc="#graph1Explained"> <!-- The description is a page on its own --> <img src="figure1" alt="figure 1" longdesc="http://example.com/desc1"> <!-- The description is one of several within an external page --> <img src="ExampleImage" alt="example" longdesc="http://example.com/descs#item3" > <!-- The description is one of several within an external page --> <img src="ExampleImage" alt="example" longdesc="http://example.com/descs#item3"> <!-- The description is included in a data: URI --> <img src="logo" alt="W3C" longdesc="data:text/html;charset=utf-8;,%3C!DOCTYPE%20html%3E%3Chtml%3E%3Chead%3E %3Ctitle%3EDescription%20of%20the%20W3C%20Logo%3C/title%3E%3C/head%3E%3Cbody%3E%3Cp%3EA%20blue%20capital%20letter
%20%22W%22%20with%20kerning%20so%20it%20touches%20a%20blue%203%2C%20followed%20by%20a%20black%20shadow%20
of%20a%20white%20capital%20letter%20C%20all%20on%20a%20white%20background%3C/body%3E%3C/html%3E"
>

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must , should , and may in this specification are to be interpreted as described in [ RFC2119 ].

1.1 Dependencies and definitions

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [ WEBIDL ]

Some of the The terms " valid non-empty URL potentially surrounded by spaces ", " hyperlink" , and " reflect ", used in this specification are defined in [ DOM4 ], [ HTML5 ] ].

This document does not define the term "accessible" nor accessibility, but uses them with the sense they have in [ WCAG . ]

2. Use Cases and Requirements

There are many ways users can successfully interact with content even if they cannot see, or see well, images included in that content. The alt attribute is designed to ensure that for everyday work, a user has enough information to replace an image, and often this is more helpful than a detailed description of every image. The longdesc attribute is designed to complement this functionality, to meet the following use cases.

Use Cases

Describing Identifying a well-known image
There are many well-known images which are widely reproduced - Mona Lisa, Washington crossing some river, the Da Vinci picture of the guy in a square and a circle, Gerníka, well known. In some cases, such as "Mona Lisa", "Gerníka", Cubbin's "Lost", Leunig's "ramming the shears". While shears", the most effective way to refer identify an image to another person is by the creator, title, and similar information that would be found in a catalogue. But different people know the images by different titles, and some images have no widely known titles, visually recognising the titles. Identifying an image is often an important part of framing a discussion. Where the image itself cannot be seen, a description can often be used to offer easier recognition than the same recognition. cataloguing information, for example "Washington crossing some river, standing heroically in the boat, while soldiers do the hard work", or "the Da Vinci picture of the guy in a square and a circle".
Requires : Discoverability
Helped by : Inline, Reuse
Describing a complex diagram
In many environments diagrams are used to explain a concept or transmit information efficiently. Where a user has a reduced ability to see the image (poor contrast vision and other conditions are as relevant here as a complete lack of vision), a description can enable that user to understand the information being presented
Requires : Structured Markup, Inline, Reuse, Simple Return
Teaching Accessible Development
In many environments producing content that is accessible to users regardless of disability is a legal and/or market requirement.
Requires : Maintenance, Backwards compatibility
A self-describing artistic work
For many pages the visual design of the page is an important part of the message it conveys to a fully-sighted user, but the author would like to convey as much of that design as possible to a user with low or no vision available.
Requires : No visual encumbrance, Structured Markup
Helped by : Reuse, Simple Return
Referring to an existing description
Many well-known images are already described by other sources. The copyright on those sources may not be compatible with re-publishing the description, but there is little value in making a new one.
Requires : Reuse, Structured Markup, Simple Return, Optional Consumption
Helped by : No Visual Encumbrance
Linking to a description included within a page
In some cases an image already has a description included within a page. Making the linkage explicit can provide further clarity for a user navigating the page who is not able to interpret the default layout, e.g. because they have forced a re-layout of the page elements, or because they do not see the default visual relationship between the element and its description.
This practice also enables description to be provided for all users.
By keeping the association clear the content maintainer can more easily check that the description and link are actually correct.
Requires : Inline, Simple Return, Structured Markup, Optional Consumption
Localising descriptions
When content is localised to multiple languages, it is important that metadata intended for human consumption, such as image descriptions, can be readily localised.
Helped by : Structured Markup, Reuse, Maintenance.

Requirements for an Image Description functionality

No visual encumbrance
It must be possible to provide a description for an image without any visual encumbrance on the page.
Structured Markup
It must be possible to include rich markup (e.g. HTML5) in the description of the image.
Inline
It must be possible to associate a description in the body of a page with an image in that page.
Reuse
It must be possible to re-use a single description for multiple occurrences of an image.
Maintenance
It must be simple to maintain a library of images and descriptions for dynamic assembly, or dis-assembly and re-assembly, of content.
Discoverability
It must be simple for a user agent to automatically discover a description provided for a given image.
A user should be able to determine that there is a description available for a given image.
Optional consumption
A user must be able to choose not to read the long description of a given image.
Simple return
A user must be able to return from the description to the image.
Backwards Compatibility
It should be possible to use existing tools and techniques to associate an image with its description.

3. The longdesc attribute

3.0 Implementation

3.0.1 Authors and Conformance checkers

Zero or one longdesc attributes may be added to any img element.

The longdesc attribute must contain a valid non-empty URL potentially surrounded by spaces . The URL is a hyperlink to a description of the image that its parent img element represents.

The linked description should be a broadly accessible format. (For example, a link to another version of the image is almost certainly not a useful description, and plain text is an extremely limiting format).

This section is informative

Best practices for checking descriptions of images are beyond the scope of this document, but there are many resources available. For  further guidance tool developers can consult e.g. [ ATAGB3 ]. ISSUE: This doesn't seem a great reference - is there anything better? This is tracked in bug 21501 and its dependent bugs. Unless a proposal is made and accepted for improvement this bug will simply be closed after Last Call.

3.0.2 Authors

Authors should put descriptions within an element which is the target of a fragment link (e.g. longdesc="example.html#description" ) if a description is only part of the target document.

This section is informative

Best practices for full descriptions of images are beyond the scope of this document, but there are many resources available.

This document does not define the term "accessible" nor accessibility. For further guidance on making an accessible document, authors can consult e.g. [ WCAG ].

3.0.3 User Agents

If the longdesc value is valid, User agents should must make the link available to all users through the regular user interface. interface(s). 

If the longdesc value is valid, User agents should must expose the link to relevant APIs, especially accessibility-oriented APIs.

User agents should enable users to discover when images in a page contain a long description.

If a longdesc attribute has invalid content, user agents may make that content available to the user. This is because a common authoring error is to include the text of a description, instead of the URL of a description, as the value of the attribute.

This section is informative

Best Complete documentation of best practices for full descriptions of images are implementation is beyond the scope of this document, but there document. However the following notes are many resources available. offered to help repair a common authoring mistake and avoid a common user agent mistake.

Best practices for implementation are beyond One of the scope most common mistakes authors make that is easily repaired by user agents is to use a description, instead of a URL that links to a description. This means there is often plain text description in the content of an invalid longdesc attribute. Converting such attributes to data URLs is a simple repair strategy that can help recover from cases where authors have made this document. mistake.

Since some images with long description are also normal link content, it is important for implementations to ensure that users can activate both behaviours. Likewise, it is generally helpful when the behaviour for finding, reading, and returning from a long description to the image described is a consistent experience.

Obviously, it is important that access to the long description is accessible to users. Further information on how to do this can be found in [ UAAG ].

3.1 Extension to the HTMLImageElement interface

partial interface <span class="idlInterfaceID">HTMLImageElement { <span class="idlAttrName"><a href="#widl-Element-longdesc">longdesc };
partial interface HTMLImageElement {
             attribute DOMStringa> longdesc;
};

3.1.1 Attribute

longdesc of type DOMString

The longdesc IDL attribute must be a valid non-empty URL potentially surrounded by spaces. It represents a hyperlink to a detailed description of the image its parent HTMLImageElement represents.

The longdesc IDL attribute must reflect the HTML content attribute longdesc .

image . longdesc [ = value ]

Returns a DOMString that represents the attribute's contents.

Can be set, to replace the contents of the attribute with the given string.

//Make
the
first
internal
longdesc
reference
absolute
var
baseURL
=
document.location.origin
+
document.location.pathname
var
someImage
=
document.querySelector('img[longdesc^=#]');
someImage.longdesc
=
baseURL
+
someImage.longdesc;

//Make the first internal longdesc reference absolute

var baseURL = document.location.origin + document.location.pathname
var someImage = document.querySelector('img[longdesc^=#]');
someImage.longdesc = baseURL + someImage.longdesc;

//Open
new
windows
for
each
longdesc
found
var
describedImages
=
document.querySelectorAll('img[longdesc]');
for
(i
in
describedImages)
{
if
(i.
longdesc
)
//there
are
a
couple
of
extra
things
matched
window.open(i.
longdesc
);
}

//Open new windows for each longdesc found

var describedImages = document.querySelectorAll('img[longdesc]');
for (i in describedImages) {
  if (i.longdesc)
    window.open(i.longdesc);
}

//Tries to repair errors where the longdesc isn't a URI

var describedImages = document.querySelectorAll('img[longdesc]');
for (i in describedImages) {
  if (i.longdesc && !(validURL(i.longdesc)) { //assumes some URL validating function
    var theData = encodeURIComponent(i.longdesc);
    i.longdesc = "data:text/plain;charset=";
    i.longdesc += document.charset;
    i.longdesc += theData;
  }
}

A. Acknowledgements

Thanks to the HTML Working group of the late 1990s for the original specification of longdesc, to those who have implemented it in various kinds of software, and to many many people involved with the development of HTML5 (including but not limited to those who discussed "ISSUE-30" in the HTML Working Group, the Protocols and Formats Working Group, the W3C Advisory Board, and around countless dinner tables, coffee breaks, and elsewhere) for the ideas, discussions and contributions that led to the initial draft of this specification. With the exception of Laura Carlson, who did far more very valuable work than it took me to produce this specification, I haven't named them: the list might be larger than the content of the specification.

For specific comments and suggestions that led to improvements over successive drafts of this specification, thanks to the W3C's HTML Accessibility Task Force, the W3C Internationalisation Working Group, and to Jonathan Avila, Robin Berjon, James Craig, Steve Faulkner, John Foliot, Geoff Freed, Richard Ishida, Anne van Kesteren, David MacDonald, Chris Mills, Jay Munro, Devarshi Pant, Leif Halvard Silli, Mathew Turvey and Boris Zbarsky. Any errors are despite, not as a result of, their efforts.

B. References

B.1 Normative references

[DOM4] Anne van Kesteren; Aryeh Gregor; Lachlan Hunt; Ms2ger. DOM4 . 6 December 2012. W3C Working Draft. URL: http://www.w3.org/TR/2012/WD-dom-20121206
[HTML5]
Robin Berjon et. al., eds. HTML5. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/html5
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. Web IDL. 27 September 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/
[XML10]

B.2 Informative references

[ATAGB3]
C. M. Sperberg-McQueen et al. Jutta Treviranus et. al., eds. Extensible Markup Language (XML) 1.0 (Fifth Edition) Implementing ATAG 2.0 . 26 November , Principle B3 "Authors must be supported in improving the accessibility of existing content" October 2011. W3C Working Draft. URL: http://www.w3.org/TR/ATAG20-TECHS/#principle_b3
[WCAG]
Ben Caldwell et. al., eds. Web Content Accessibility Guidelines 2.0 , December 2008. W3C Recommendation. URL: http://www.w3.org/TR/2008/REC-xml-20081126/ http://www.w3.org/TR/2008/REC-WCAG20-20081211/
[UAAG]
Ian Jacobs et. al., eds. User Agent Accessibility Guidelines 2.0 , December 2002. W3C Recommendation. URL: http://www.w3.org/TR/2002/REC-UAAG10-20021217/ . A draft for a version 2.0 is available at http://www.w3.org/TR/UAAG20/

C. Change History

(This section is not normative)

Since the First Public Working Draft substantive changes include:

  • Added a requirement that the destination of a longdesc should be "accessible".
  • The requirement to present content through the standard User Interace was changed from should to must .
  • The requirement to present content through the standard User Interace was narrowed to apply only to valid values of longdesc .
  • The requirement to present content through the Accessibiltiy APIs was changed from should to must .
  • The requirement to present content through the Accessibility APIs was narrowed to apply only to valid values of longdesc .
  • The IDL attribute longdesc was changed to reflect the HTML content attribute longdesc .

Editorial changes include:

  • Clarifying that the document does not define "accessible", except that it is used in the sense that it is used in [ WCAG ].
  • Sectioning requirements according to whom they apply.
  • Removed the statement that User Agents may present descriptions which are erroneously included in the content instead of a link.
  • Added more examples