HTML Notes and Note References (original) (raw)

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.

Introduction

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.

Terms

This section defines terms that are use throughout this specification.

Accessible Name

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.

Assistive Technologies

Hardware and/or software that:

relies on services provided by a user agent to retrieve and render Web content
works with a user agent or web content itself through the use of APIs, and
provides services beyond those offered by the user agent to facilitate user interaction with web content by people with disabilities

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:

screen magnifiers, which are used to enlarge and improve the visual readability of rendered text and images;
screen readers, which are most-often used to convey information through synthesized speech or a refreshable Braille display;
text-to-speech software, which is used to convert text into synthetic speech;
speech recognition software, which is used to allow spoken control and dictation;
alternate input technologies (including head pointers, on-screen keyboards, single switches, and sip/puff devices), which are used to simulate the keyboard;
alternate pointing devices, which are used to simulate mouse pointing and clicking.

Display Value

The display value for a note is the ordinal value (manually or automatically) assigned to the note, transformed into a display style as defined by the note's associated type.

Note

For the purposes of this specification, a note is ancillary or supporting content that is referenced 0 or more times in the document.

Note Group

A note group is a collection of notes that are related to one another in some way. Notes in a note group have display values that are unique with the note group.

Note Reference

For purposes of this specification, a note reference is an explicit connection from a location in the document to a note.

Use Cases and Requirements

Use Cases

Dave is writing a scientific article for a journal. The article will be published both on-line and in print. The article has many supporting references and ancillary data that are gathered at its end. Those references and data are referred to from within the article. Dave needs a consistent way to define these "notes" and refer to them that is easy to use, accessible, and will work well on-line and in print.
Matthew is editing his thesis on the history of the kilt into a large-format sumptuously illustrated book for a more general audience. He uses end-notes for references that he cites and keeps small anecdotes, glossary explanations and occasional dates in footnotes, so that readers can easily see at a glance whether a footnote might be interesting to them.
Susan has been helping an Iranian scholar edit an English translation of some poems from modern Persian; simple glosses (word explanations) appear in the right margin. Where possible the glosses are aligned with the text they explain; if necessary they are shifted up or down to make room. Footnotes point to longer explanations that contextualize the work. Both footnotes and glosses include mixtures of text direction, language and script. The original English translation had footnotes of its own, and these are numbered separately on each page and are printed immediately below the main text, above any new footnotes. The Persian also has occasional footnotes which again are numbered separately and printed (in English) at the foot of the page below the new footnotes. A line separates the three sets of footnotes.
Annette is writing Calculus Basics and wants to offer her lecture notes to other instructors. She uses Web Annotations [[ANNOTATION-MODEL]] to add tips for instructors in the margins to create an instructors’ Edition, available in print or electronic format.
Pria is writing a journal article with multiple bibliographic reference using the APA style guide, meaning multiple references point to the same note. It must be possible for her readers to examine the note and return to the point from which it was referenced. (Note: this has implications for [[WCAG20]] compliance, requiring title on the link).

Requirements

The following requirements were gathered via several email exchanges in 2015.

There must be a way to declaratively define a note and one or more references to a note.
There must be a way to easily navigate to and from a note, or to examine the content of the note from the context of a reference to that note.
There must be a way to determine / navigate among all references to a note.
It must be possible to fully style notes such that, for example, they could manifest differently on different sorts of devices, appear as side notes, appear as floating "tooltips", be organized into "endnotes", or whatever other innovative presentation mechanism the author might come up with.
It must be possible to support a mixture of end-notes, footnotes, inline notes, and marginalia
It must be possible to reference a single note multiple times; navigation back from a note must return to the correct starting-point even where a note had multiple reference pointing to it.
It should be possible to navigate among all notes / notes with specific @role or @rel values.
The scope of a note (beginning and end) must be well-defined, so that it is possible to extract all notes or process them separately in any order.
It must be possible to embed a note within a note. @@@ What does this mean in terms of knowing where a note starts and ends?
It must be possible to include markup (including for example MathML, SVG, HTML tables...) in a note
It must be possible to enhance the semantics associated with a note through well-defined values for @role or other attributes that inform semantics.
It must be possible to have note identifiers be automatically generated.
It must be possible to override the automatic generation of note identifiers
It should be possible to define multiple sequences of notes / note identifiers
It must be possible to carefully control the position of notes - from Bill Kasdorf
It must be possible for end-users to override the publisher's positioning requirements - from Bill Kasdorf
It must be possible to mark a section of text as the link to the note (anchor), rather than just a marker at a single point - from http://lists.w3.org/Archives/Public/public-digipub-ig/2015Feb/0094.html Robert Sanderson]
It must be possible to have a note refer to multiple sections of the text, rather than only one @@@ This seems odd - notes don't refer to the text. Text refers to notes. @@@
It should be possible to have alternative representations of the note based upon arbitrary criteria (e.g., age, developmental level, interest level)
It should be possible to reference a note so that it can be further commented upon
It must be possible to create notes that reference non-text items such as the bounding box of image-based media @@@ again - notes don't reference text @@@
It must be possible to define a note with non-text (e.g., image, audio, video)
It must be possible to style the reference to a note
It must be possible to extract semantic information about the provenance of a note (e.g., creator, date created, etc) when that information is available @@@ this supposes some external annotation techniques, and may be outside the scope of this specification; however, it should not be precluded @@@
It must be possible for an author or enduser to control the presentation of the note through scripting and/or other preference settings.

Elements

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

The `notegroup` element

Categories:

Flow

Sectioning

Contexts in which this element can be used:

Where flow content is expected.

Content model:

Flow content.

Content attributes:

Global attributes

group — Default group name to use for notes contained in the element

type — Default type of note marker to use for notes contained in the element

Tag omission in text/html:

Neither tag is omissible.

Allowed ARIA role attribute values:

region (default - do not set),doc-endnotes [[!DPUB-ARIA-1.0]]

Allowed ARIA State and Property Attributes:

Global aria-* attibutes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

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?

Processing model

User agents MUST process the notegroup element as follows:

Determine the value for Group:
1. If the element's group attribute is present, let Group equal its value.
2. Otherwise, if the element is a child of a notegroup element, and that element's group attribute is present, let Group equal its value.
3. Otherwise, let Group equal the empty string.
If the noteGroups entry associated with Group does not exist, create one and set its group attribute to Group.
Let GroupInfo equal the noteGroups entry associated with Group.
Determine the value for Type:
1. If the element's type attribute is present, let Type equal its value.
2. Otherwise, if GroupInfo has a value for itstype attribute, let Type equal that value.
3. Otherwise, if the element is a child of a notegroup element, and that element's type attribute is present, let Type equal its value.
4. Otherwise, let Type equal '1'.
If the nextValue attribute of GroupInfo is NOT set, set it to 1.
If the type attribute of_GroupInfo_ is NOT set, set it to Type.

The `note` element

Categories:

Flow

Contexts in which this element can be used:

@@@TODO@@@

Content model:

Flow

Tag omission in text/html:

Neither tag is omissible.

Content attributes:

Global attributes

group — Name of the note group

value — Ordinal value of the note

type — The type of the note marker

Allowed ARIA role attribute values:

note (default - do not set), doc-footnote, doc-endnote [[!DPUB-ARIA-1.0]]

Allowed ARIA State and Property Attributes:

Global aria-* attibutes

Any aria-* attributes applicable to the allowed roles.

DOM interface:

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

Processing model

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?

If the element's 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.
Otherwise, determine the value for Group:
1. If the element's group attribute is present, let Group equal its value.
2. Otherwise, if the element is a child of a notegroup element, and that element's group attribute is present, let Group equal its value.
3. Otherwise, let Group equal the empty string.
If the noteGroups entry associated with Group does not exist, create one and set its group attribute to Group.
Let GroupInfo equal the noteGroups entry associated with Group.
Determine the value for Type:
1. If the element's type attribute is present, let Type equal its value.
2. Otherwise, if GroupInfo has a value for itstype attribute, let Type equal that value.
3. Otherwise, if the element is a child of a notegroup element, and that element's type attribute is present, let Type equal its value.
4. Otherwise, let Type equal '1'.
Determine the value for Value:
1. If the element's value attribute is present, let Value equal its value.
2. Otherwise, if GroupInfo has a value for its nextValue attribute, let Value equal its value.
3. Otherwise, let Value equal '1'.
Set the nextValue attribute of GroupInfo to Value plus 1.
If the type attribute of GroupInfo is NOT set, set it to Type.
Set the displayValue attribute to the appropriate display value by correlating Type with_title_ and / or Value as defined in the Appendix A.

The `noteref` element

Categories:

Phrasing

Contexts in which this element can be used:

Where phrasing content is expected.

Content model:

Transparent, but there MUST be no interactive content or noteref ora element descendants.

Tag omission in text/html:

Neither tag is omissible.

Content attributes:

Global attributes

note — the ID of a note to reference

Allowed ARIA role attribute values:

link (default - do not set), doc-noteref [[!DPUB-ARIA-1.0]]

Allowed ARIA State and Property Attributes:

Global aria-* attibutes

aria-linktype

DOM interface:

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 thenoteref element are focusable and selectable. By default, selecting and activating the content changes focus to the note referenced, inexactly the same manner as navigation from ana 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.

Processing model

If the noteref element has a note attribute specified, user agents MUST process it as follows:

Parse the attribute's value using the rules for parsing a hash-name reference to anote element, with the element's node document as the context node. This will return either an element (the note) or null.
If that returned null, then abort these steps.
Otherwise, perform the following steps:
1. Set the element's IDL attribute note to the value of the element's note attribute.
2. Set the element's IDL attribute displayValue to the note's IDL attribute displayValue
3. Add the element's DOM node to the note's IDL attribute references.

Note types

The display value for a note is determined by using itstype to transform itsvalue according to the table below.

Note Types Table
Keyword	State	Description	Examples for values 1-3 and 3999-4001
none (U+006e U+006f U+006e U+0065)	none or decimal	Title attribute or Decimal numbers if no title	title-or-1.	title-or-2.	title-or-3.	...	title-or-3999.	title-or-4000.	title-or-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.	...

Processing model

When determining the display value, user agents MUST process the type and title attributes as follows:

Let DisplayValue equal the value of the note.
If the type of the note equals none:
1. If the title of the note is non-empty, let_DisplayValue_ equal the value of title.
  In the case where title is empty, the DisplayValue will already be set to the value of the note in Decimal form.
Otherwise:
1. If the value of the type matches a value from column 1 of the table, transform the DisplayValue into the form as defined in column 2 of the table.
2. If the value of the title of the note is non-empty, append a space (U+0020) and the value of the title to DisplayValue.

Examples

Acknowledgements

The following people and organizations were super helpful in their support of developing this document:

HTML Notes and Note References (original) (raw)

Introduction

Terms

Use Cases and Requirements

Use Cases

Requirements

Elements

The notegroup element

Processing model

The note element

Processing model

The noteref element

Processing model

Note types

Processing model

Examples

Acknowledgements

The `notegroup` element

The `note` element

The `noteref` element