Various communities have, over the years, lamented the lack of classic 'footnote' capabilities in HTML. This specification defines elements that can be used to markup notes and references thereto. It further specifies default styling for these elements, and suggests alternate ways that they might be organized and presented for specific uses.
This specification is designed to be an extension to [[!HTML5]]. This is a very early draft to collect together use cases, prioritize them, and start to mock up a solution that can address them.
Since the earliest versions of HTML, it has been possible to define a connection between areas of documents. Unfortunately, this simple and ubiquitous mechanism is not completely able to represent the rich semantics inherent in all sorts of connections that appear within and among documents.
This section defines terms that are use throughout this specification.
The accessible name is the name of a user interface element. Each platform accessibility API provides the accessible name property. The value of the accessible name may be derived from a visible (e.g., the visible text on a button) or invisible (e.g., the text alternative that describes an icon) property of the user interface element.
A simple use for the accessible name property may be illustrated by an "OK" button. The text "OK" is the accessible name. When the button receives focus, assistive technologies may concatenate the platform's role description with the accessible name. For example, a screen reader may speak "push-button OK" or "OK button". The order of concatenation and specifics of the role description (e.g., "button", "push-button", "clickable button") are determined by platform accessibility APIs or assistive technologies.
Hardware and/or software that:
This definition may differ from that used in other documents.
Examples of assistive technologies that are important in the context of this document include the following:
The following requirements were gathered via several email exchanges in 2015.
Instead of relying up @role to control the semantics of the notes, we *could* introduce an enumerated list of @kind values (ala the HTML5 track element) and define explicit semantics for the kinds of notes we support. Optionally permit other values for @kind, but say that their semantics are undefined. Candidate values for @kind would be footnote, sectionnote, endnote. If we wanted it to be really fun and declarative, also define the region where the notes would be gathered / relocated via @region (IDREF).
notegroup elementgroup — Default group name to use for notes contained in
the elementtype — Default type of note marker to use for notes
contained in the elementregion (default - do not set),
doc-endnotes [[!DPUB-ARIA-1.0]]
interface HTMLNotegroupElement : HTMLElement {
attribute DOMString group;
attribute DOMString type;
};
interface GroupInfo {
readonly attribute DOMString group;
readonly attribute DOMString type;
readonly attribute long nextValue;
};
interface HTMLNotegroupCollection {
readonly attribute long length;
getter GroupInfo (unsigned long index);
getter GroupInfo (DOMString group);
};
partial interface Document {
[SameObject] readonly attribute HTMLNotegroupCollection noteGroups;
};
The notegroup element represents a section of a document
or application that encloses note and other related content.
Typically the content of a notegroup is one or more note elements.
If a group attribute value is supplied, it represents
the name of this collection of notes. It's value can effect the note
group of any
enclosed note elements.
If a type attribute is supplied,
it can effect the type of any enclosed note
elements.
The group IDL attribute
MUST reflect the value of the group attribute.
The type IDL attribute
MUST reflect the value of the type attribute.
This specification extends the document object with the HTMLNotegroupCollection noteGroups. This is a list of all of the note groups defined in the document along with their associated state information.
A note is a self-contained node. When such a note is referenced via a noteref element, and that reference is activated via someone using assistive technology, should the AT only "display" the contents of the referenced note? Even if the note is part of a large collection of notes? Or should the AT start "displaying" at the node for the node, and continue until it runs out of content or the user stops the displaying and returns to the reference via the "back" action?
User agents MUST process the notegroup element as follows:
group attribute is present, let Group equal
its value.notegroup element, and that
element's group attribute is present, let Group equal its
value.type attribute is present, let Type equal
its value.notegroup element, and that
element's type attribute is present, let Type equal its
value.note elementgroup — Name of the note groupvalue — Ordinal value of the notetype — The type of the note markernote (default - do not set),
doc-footnote, doc-endnote [[!DPUB-ARIA-1.0]]
interface HTMLNoteElement : HTMLElement {
attribute DOMString group;
attribute DOMString type;
attribute DOMString title;
attribute long value;
readonly attribute DOMString displayValue;
readonly attribute NodeList references;
};
The note element represents content that is related to other content in the
document. Typically the content of a note is a reference or other supporting
information that would be distracting to the reader if it were included in the normal flow of
the content that references it.
The group content attribute, if present, represents the name of a
note group.
If no group is specified, then the default
group is used.
The type
attribute
can be used to specify the kind of marker to use on the
note.
The attribute, if specified, must have a value that is a
case-sensitive match
for one of the values given in the first cell of one of the rows of
the table in Appendix A. 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.
The value content attribute, if present, must be an
integer giving the ordinal value of the note.
If no value is supplied, the next available value within the
note's group is used.
The group IDL attribute MUST reflect the content attribute of the same name.
The type IDL attribute MUST reflect the content attribute of the same name, limited to only known values from the table in Appendix A.
The value IDL attribute MUST reflect the ordinal value for the note (see Processing model below for details about determining value).
The displayValue IDL attribute MUST reflect the value IDL attribute when transformed according to the element's type IDL attribute as defined in Appendix A.
The references IDL attribute MUST
reflect the list of noteref elements that reference the
note.
By default, the contents of this element are displayed prefixed by the note's display value.
User agents MUST process the note element as follows:
This model requires that the ID of each note be document unique. In theory it is possible to only require that the ID be unique within the collection of notes in the same group within the document. This would require implementations to perform navigation using something other than fragment identifiers, however. Is this desirable?
The style of value processing defined here permits duplicate values within a group of notes. Should duplicate note values be prevented?
id attribute is present and is not unique in the
document, or if the element's id attribute is NOT present, abort processing. This
is not a valid note as it cannot be referenced.group attribute is present, let Group equal
its value.notegroup element, and that
element's group attribute is present, let Group equal its
value.type attribute is present, let Type equal
its value.notegroup element, and that
element's type attribute is present, let Type equal its
value.value attribute is present, let Value equal
its value.noteref elementnoteref or
a element descendants.note — the ID of a note to referencelink (default - do not set),
doc-noteref [[!DPUB-ARIA-1.0]]
interface HTMLNoterefElement : HTMLElement {
readonly attribute DOMString displayValue;
readonly attribute DOMString note;
};
The content model for noteref is similar to that of a. This makes
sense and is maximally flexible. However, in the most common use case, noteref
will be used with no content at all:
Requiring the opening and closing tags in this common use case is inconvenient. Unfortunately, HTML does not have a simple way to short circuit a tag like XML does. And permitting the omission of the end tag in this case would result in inconsistent and undesirable parsing.
The noteref element represents a reference to a note
within the same document. When this element is visible, its content is displayed prefixed
with the
display value of the associated note.
The note's display value and any content of the
noteref element are focusable and selectable. By default,
selecting and activating the
content changes focus to the note referenced, in
exactly the same manner as navigation from an
a element to its target. This has the logical follow-on
effect that the user agent's "back" functionality will return focus to
the location of the original reference.
It is possible to override the default behavior through scripting. For example, changing focus to the note could cause the referenced note's content to be displayed in a pop-up window, in a magin, in an area at the bottom of the screen, or whatever other mechanism is appropriate for the style of note and the idiom of the document. When such features are implemented, they SHOULD always keep in mind the needs of users with various accessibility requirements. For example, having the content of a note appear in a pop-up window when the reference acquires focus is fine for sighted users, but a user relying up a screen reader may wish to activate the reference in order to change focus to that popup so their reader will convey the contents of the note.
The note content attribute represents the id of the note element
being referenced. A note element with that ID MUST be present in the document in
order for the noteref element to be considered a reference to a note (see Processing Model below).
A note reference SHOULD have an accessible name so that assistive technologies can make the semantics of the reference clear to their users.
If the noteref element has a note attribute specified, user
agents MUST process it as follows:
note element, with the element's node document as the context node. This
will return either an element (the note) or null.note attribute.references.The display value for a note is determined by using its type to transform its value according to the table below.
When determining the display value, user agents MUST process the type
and title attributes as follows:
none:
The following people and organizations were super helpful in their support of developing this document: