Skip to content

Meta: give all document references an explicit for attribute #1337

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 16, 2024
Merged

Meta: give all document references an explicit for attribute #1337

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 49 additions & 48 deletions dom.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -336,7 +336,7 @@ are invoked, now in reverse <a>tree order</a>.

<p>The <code>debug</code> function will be invoked twice. Each time the <a>event</a>'s
{{Event/target}} attribute value will be the <code>span</code> <a for=/>element</a>. The first time
{{Event/currentTarget}} attribute's value will be the <a>document</a>, the second time the
{{Event/currentTarget}} attribute's value will be the <a for=/>document</a>, the second time the
<code>body</code> <a for=/>element</a>. {{Event/eventPhase}} attribute's value switches from
{{Event/CAPTURING_PHASE}} to {{Event/BUBBLING_PHASE}}. If an <a>event listener</a> was registered
for the <code>span</code> <a for=/>element</a>, {{Event/eventPhase}} attribute's value would have
Expand Down Expand Up @@ -2340,16 +2340,16 @@ therefore alone in a <a>tree</a>.
<h4 id=document-trees>Document tree</h4>

<p>A <dfn export id=concept-document-tree>document tree</dfn> is a <a>node tree</a> whose
<a for=tree>root</a> is a <a>document</a>.
<a for=tree>root</a> is a <a for=/>document</a>.

<p>The <dfn export>document element</dfn> of a <a>document</a> is the <a for=/>element</a> whose
<a for=tree>parent</a> is that <a>document</a>, if it exists; otherwise null.
<p>The <dfn export>document element</dfn> of a <a for=/>document</a> is the <a for=/>element</a>
whose <a for=tree>parent</a> is that <a for=/>document</a>, if it exists; otherwise null.

<p class=note>Per the <a>node tree</a> constraints, there can be only one such
<a for=/>element</a>.

<p>A <a for=/>node</a> is <dfn export>in a document tree</dfn> if its <a for=tree>root</a> is a
<a>document</a>.
<a for=/>document</a>.

<p>A <a for=/>node</a> is <dfn export>in a document</dfn> if it is <a>in a document tree</a>.
<span class=note>The term <a>in a document</a> is no longer supposed to be used. It indicates that
Expand All @@ -2370,7 +2370,7 @@ referred to as the <dfn export id=concept-light-tree>light tree</dfn>.</p>
itself.</p>

<p id=in-a-shadow-including-document>A <a for=/>node</a> is <dfn export>connected</dfn> if its
<a>shadow-including root</a> is a <a>document</a>.
<a>shadow-including root</a> is a <a for=/>document</a>.

<h5 id=shadow-tree-slots>Slots</h5>

Expand Down Expand Up @@ -2628,12 +2628,12 @@ steps:
"{{HierarchyRequestError!!exception}}" {{DOMException}}.

<li><p>If either <var>node</var> is a {{Text}} <a for=/>node</a> and <var>parent</var> is a
<a>document</a>, or <var>node</var> is a <a>doctype</a> and <var>parent</var> is not a
<a>document</a>, then <a>throw</a> a "{{HierarchyRequestError!!exception}}" {{DOMException}}.
<a for=/>document</a>, or <var>node</var> is a <a>doctype</a> and <var>parent</var> is not a
<a for=/>document</a>, then <a>throw</a> a "{{HierarchyRequestError!!exception}}" {{DOMException}}.

<li>
<p>If <var>parent</var> is a <a>document</a>, and any of the statements below, switched on the
interface <var>node</var> <a>implements</a>, are true, then <a>throw</a> a
<p>If <var>parent</var> is a <a for=/>document</a>, and any of the statements below, switched on
the interface <var>node</var> <a>implements</a>, are true, then <a>throw</a> a
"{{HierarchyRequestError!!exception}}" {{DOMException}}.

<dl class=switch>
Expand Down Expand Up @@ -2898,12 +2898,12 @@ within a <var>parent</var>, run these steps:
"{{HierarchyRequestError!!exception}}" {{DOMException}}.

<li><p>If either <var>node</var> is a {{Text}} <a for=/>node</a> and <var>parent</var> is a
<a>document</a>, or <var>node</var> is a <a>doctype</a> and <var>parent</var> is not a
<a>document</a>, then <a>throw</a> a "{{HierarchyRequestError!!exception}}" {{DOMException}}.
<a for=/>document</a>, or <var>node</var> is a <a>doctype</a> and <var>parent</var> is not a
<a for=/>document</a>, then <a>throw</a> a "{{HierarchyRequestError!!exception}}" {{DOMException}}.

<li>
<p>If <var>parent</var> is a <a>document</a>, and any of the statements below, switched on the
interface <var>node</var> <a>implements</a>, are true, then <a>throw</a> a
<p>If <var>parent</var> is a <a for=/>document</a>, and any of the statements below, switched on
the interface <var>node</var> <a>implements</a>, are true, then <a>throw</a> a
"{{HierarchyRequestError!!exception}}" {{DOMException}}.

<dl class=switch>
Expand Down Expand Up @@ -4130,7 +4130,7 @@ get a direct instance of it.

<p>Each <a for=/>node</a> has an associated
<dfn export for=Node id=concept-node-document>node document</dfn>, set upon creation, that is a
<a>document</a>.
<a for=/>document</a>.

<p class=note>A <a for=/>node</a>'s <a for=Node>node document</a> can be changed by the
<a>adopt</a> algorithm.
Expand Down Expand Up @@ -4334,10 +4334,11 @@ statement, switching on the interface <a>this</a> <a>implements</a>:
if <a>this</a> is <a>connected</a>; otherwise false.</p>

<p>The <dfn attribute for=Node><code>ownerDocument</code></dfn> getter steps are to return null,
if <a>this</a> is a <a>document</a>; otherwise <a>this</a>'s <a for=Node>node document</a>.
if <a>this</a> is a <a for=/>document</a>; otherwise <a>this</a>'s <a for=Node>node document</a>.

<p class=note>The <a for=Node>node document</a> of a <a>document</a> is that <a>document</a> itself.
All <a for=/>nodes</a> have a <a for=Node>node document</a> at all times.
<p class=note>The <a for=Node>node document</a> of a <a for=/>document</a> is that
<a for=/>document</a> itself. All <a for=/>nodes</a> have a <a for=Node>node document</a> at all
times.

<p>The <dfn method for=Node><code>getRootNode(<var>options</var>)</code></dfn> method steps are to
return <a>this</a>'s <a>shadow-including root</a> if
Expand Down Expand Up @@ -5152,9 +5153,9 @@ dictionary ElementCreationOptions {
<p>{{Document}} <a for=/>nodes</a> are simply
known as <dfn export id=concept-document lt="document">documents</dfn>.

<p>A <a>document</a>'s <a>node document</a> is itself.
<p>A <a for=/>document</a>'s <a>node document</a> is itself.

<p>Each <a>document</a> has an associated
<p>Each <a for=/>document</a> has an associated
<dfn export for=Document id=concept-document-encoding>encoding</dfn> (an <a for=/>encoding</a>),
<dfn export for=Document id=concept-document-content-type>content type</dfn> (a string),
<dfn export for=Document id=concept-document-url>URL</dfn> (a <a for=/>URL</a>),
Expand All @@ -5166,18 +5167,19 @@ known as <dfn export id=concept-document lt="document">documents</dfn>.
[[!URL]]
[[!HTML]]

<p>Unless stated otherwise, a <a>document</a>'s <a for=Document>encoding</a> is the <a>utf-8</a>
<a for=/>encoding</a>, <a for=Document>content type</a> is
<p>Unless stated otherwise, a <a for=/>document</a>'s <a for=Document>encoding</a> is the
<a>utf-8</a> <a for=/>encoding</a>, <a for=Document>content type</a> is
"<code>application/xml</code>", <a for=Document>URL</a> is "<code>about:blank</code>",
<a for=Document>origin</a> is an <a>opaque origin</a>,
<a for=Document>type</a> is "<code>xml</code>", <a for=Document>mode</a> is
"<code>no-quirks</code>", and its <a for=Document>allow declarative shadow roots</a> is false.

<p>A <a>document</a> is said to be an <dfn export>XML document</dfn> if its <a for=Document>type</a>
is "<code>xml</code>"; otherwise an <dfn export>HTML document</dfn>. Whether a <a>document</a> is an
<a>HTML document</a> or an <a>XML document</a> affects the behavior of certain APIs.
<p>A <a for=/>document</a> is said to be an <dfn export>XML document</dfn> if its
<a for=Document>type</a> is "<code>xml</code>"; otherwise an <dfn export>HTML document</dfn>.
Whether a <a for=/>document</a> is an <a>HTML document</a> or an <a>XML document</a> affects the
behavior of certain APIs.

<p>A <a>document</a> is said to be in
<p>A <a for=/>document</a> is said to be in
<dfn export id=concept-document-no-quirks>no-quirks mode</dfn> if its
<a for=Document>mode</a> is "<code>no-quirks</code>",
<dfn export id=concept-document-quirks>quirks mode</dfn> if its <a for=Document>mode</a>
Expand All @@ -5196,16 +5198,16 @@ is "<code>quirks</code>", and
are nonsensical.)
</div>

<p>A <a>document</a>'s <a>get the parent</a> algorithm, given an <var>event</var>, returns
<p>A <a for=/>document</a>'s <a>get the parent</a> algorithm, given an <var>event</var>, returns
null if <var>event</var>'s {{Event/type}} attribute value is "<code>load</code>" or
<a>document</a> does not have a <a for=Document>browsing context</a>; otherwise the
<a>document</a>'s <a>relevant global object</a>.
<a for=/>document</a> does not have a <a for=Document>browsing context</a>; otherwise the
<a for=/>document</a>'s <a>relevant global object</a>.

<hr>

<dl class=domintro>
<dt><code><var>document</var> = new {{Document()}}</code>
<dd>Returns a new <a>document</a>.
<dd>Returns a new <a for=/>document</a>.

<dt><code><var>document</var> . {{Document/implementation}}</code>
<dd>Returns <var>document</var>'s {{DOMImplementation}} object.
Expand Down Expand Up @@ -5233,7 +5235,7 @@ steps are to set <a>this</a>'s <a for=Document>origin</a> to the <a for=Document
<a>current global object</a>'s <a>associated <code>Document</code></a>. [[!HTML]]

<p class=note>Unlike {{DOMImplementation/createDocument()}}, this constructor does not
return an {{XMLDocument}} object, but a <a>document</a> ({{Document}} object).
return an {{XMLDocument}} object, but a <a for=/>document</a> ({{Document}} object).

<p>The
<dfn attribute for=Document><code>implementation</code></dfn> getter steps are to return the
Expand Down Expand Up @@ -5297,7 +5299,7 @@ otherwise "<code>CSS1Compat</code>".
<dt><var>collection</var> = <var>document</var> . {{Document/getElementsByClassName(classNames)}}</code>
<dt><var>collection</var> = <var>element</var> . {{Element/getElementsByClassName(classNames)}}</code>
<dd><p>Returns an {{HTMLCollection}} of the <a for=/>elements</a> in the object on which the method
was invoked (a <a>document</a> or an <a for=/>element</a>) that have all the classes given by
was invoked (a <a for=/>document</a> or an <a for=/>element</a>) that have all the classes given by
<var>classNames</var>. The <var>classNames</var> argument is interpreted as a space-separated list
of classes.
</dl>
Expand Down Expand Up @@ -5557,16 +5559,16 @@ method steps are:
<p>Returns a copy of <var>node</var>. If <var>deep</var> is true, the copy also includes the
<var>node</var>'s <a for=tree>descendants</a>.

<p>If <var>node</var> is a <a>document</a> or a <a for=/>shadow root</a>, throws a
<p>If <var>node</var> is a <a for=/>document</a> or a <a for=/>shadow root</a>, throws a
"{{NotSupportedError!!exception}}" {{DOMException}}.

<dt><var>node</var> = <var>document</var> . {{adoptNode(node)}}

<dd>
Moves <var>node</var> from another
<a>document</a> and returns it.
<a for=/>document</a> and returns it.

If <var>node</var> is a <a>document</a>, throws a "{{NotSupportedError!!exception}}"
If <var>node</var> is a <a for=/>document</a>, throws a "{{NotSupportedError!!exception}}"
{{DOMException}} or, if <var>node</var> is a <a for=/>shadow root</a>, throws a
"{{HierarchyRequestError!!exception}}" {{DOMException}}.
</dl>
Expand All @@ -5575,8 +5577,8 @@ method steps are:
method steps are:

<ol>
<li><p>If <var>node</var> is a <a>document</a> or <a for=/>shadow root</a>, then <a>throw</a> a
"{{NotSupportedError!!exception}}" {{DOMException}}.
<li><p>If <var>node</var> is a <a for=/>document</a> or <a for=/>shadow root</a>, then <a>throw</a>
a "{{NotSupportedError!!exception}}" {{DOMException}}.

<li><p>Return a <a lt="clone a node">clone</a> of <var>node</var>, with <a>this</a> and the
<i>clone children flag</i> set if <var>deep</var> is true.
Expand Down Expand Up @@ -5627,7 +5629,7 @@ these steps:
<p>The <dfn method for=Document><code>adoptNode(<var>node</var>)</code></dfn> method steps are:

<ol>
<li><p>If <var>node</var> is a <a>document</a>, then <a>throw</a> a
<li><p>If <var>node</var> is a <a for=/>document</a>, then <a>throw</a> a
"{{NotSupportedError!!exception}}" {{DOMException}}.

<li><p>If <var>node</var> is a <a for=/>shadow root</a>, then <a>throw</a> a
Expand Down Expand Up @@ -5786,9 +5788,8 @@ method steps are:

<h4 id=interface-domimplementation>Interface {{DOMImplementation}}</h4>

User agents must create a {{DOMImplementation}} object whenever
a <a>document</a> is created and associate it
with that <a>document</a>.
<p>User agents must create a {{DOMImplementation}} object whenever a <a for=/>document</a> is
created and associate it with that <a for=/>document</a>.

<pre class=idl>
[Exposed=Window]
Expand Down Expand Up @@ -5831,7 +5832,7 @@ interface DOMImplementation {
<dt><code><var>doc</var> = <var>document</var> . {{Document/implementation}} . <a method for=DOMImplementation lt=createHTMLDocument()>createHTMLDocument([<var>title</var>])</a></code>

<dd>
Returns a <a>document</a>, with a basic
Returns a <a for=/>document</a>, with a basic
<a>tree</a> already constructed including a
<{title}> element, unless the <var>title</var>
argument is omitted.
Expand All @@ -5849,7 +5850,7 @@ method steps are:
<li><p>Return a new <a>doctype</a>, with <var>qualifiedName</var> as its
<a for=DocumentType>name</a>, <var>publicId</var> as its <a>public ID</a>, and <var>systemId</var>
as its <a>system ID</a>, and with its <a for=Node>node document</a> set to the associated
<a>document</a> of <a>this</a>.
<a for=/>document</a> of <a>this</a>.
</ol>

<p class=note>No check is performed that <var>publicId</var> code points match the
Expand All @@ -5874,7 +5875,7 @@ method steps are:
<li><p>If <var>element</var> is non-null, <a>append</a> <var>element</var> to <var>document</var>.

<li><p><var>document</var>'s <a for=Document>origin</a> is <a>this</a>'s associated
<a>document</a>'s <a for=Document>origin</a>.
<a for=/>document</a>'s <a for=Document>origin</a>.

<li>
<p><var>document</var>'s <a for=Document>content type</a> is determined by <var>namespace</var>:
Expand All @@ -5898,7 +5899,7 @@ method steps are:
method steps are:

<ol>
<li><p>Let <var>doc</var> be a new <a>document</a> that is an <a>HTML document</a>.
<li><p>Let <var>doc</var> be a new <a for=/>document</a> that is an <a>HTML document</a>.

<li><p>Set <var>doc</var>'s <a for=Document>content type</a> to "<code>text/html</code>".

Expand Down Expand Up @@ -5927,8 +5928,8 @@ method steps are:
<li><p><a>Append</a> the result of <a>creating an element</a> given <var>doc</var>,
"<code>body</code>", and the <a>HTML namespace</a>, to the <{html}> element created earlier.</li>

<li><p><var>doc</var>'s <a for=Document>origin</a> is <a>this</a>'s associated <a>document</a>'s
<a for=Document>origin</a>.
<li><p><var>doc</var>'s <a for=Document>origin</a> is <a>this</a>'s associated
<a for=/>document</a>'s <a for=Document>origin</a>.

<li><p>Return <var>doc</var>.
</ol>
Expand Down Expand Up @@ -8194,7 +8195,7 @@ to set <a>this</a>'s <a for=range>start</a> and <a for=range>end</a> to

<dl class=domintro>
<dt><var>container</var> = <var>range</var> . {{Range/commonAncestorContainer}}
<dd>Returns the <a for=/>node</a>, furthest away from the <a>document</a>, that is an
<dd>Returns the <a for=/>node</a>, furthest away from the <a for=/>document</a>, that is an
<a for=tree>ancestor</a> of both <var>range</var>'s <a for=range>start node</a> and
<a for=range>end node</a>.
</dl>
Expand Down