Skip to content

Commit

Permalink
Editorial: Remove parameters from document.open() references
Browse files Browse the repository at this point in the history 
This effectively reverts parts of
8f2816a.
  • Loading branch information
@TimothyGu @mustaqahmed
TimothyGu authored and mustaqahmed committed Feb 15, 2019
1 parent 003168e commit 1dafd08
Showing 1 changed file with 41 additions and 46 deletions.
87 changes: 41 additions & 46 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2930,6 +2930,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<dfn data-x="es-constructing-callback-functions" data-x-href="https://heycam.github.io/webidl/#construct-a-callback-function">constructing</dfn> callback functions</li>
<li><dfn data-x-href="https://heycam.github.io/webidl/#dfn-obtain-unicode">converting to a
sequence of Unicode scalar values</dfn></li>
<li><dfn data-x-href="https://heycam.github.io/webidl/#dfn-overload-resolution-algorithm">overload resolution algorithm</dfn></li>
</ul>

<p>The Web IDL specification also defines the following types that are used in Web IDL fragments
Expand Down Expand Up @@ -9168,7 +9169,7 @@ partial interface <dfn id="document" data-lt="">Document</dfn> {
readonly attribute <span>HTMLOrSVGScriptElement</span>? <span data-x="dom-document-currentScript">currentScript</span>; // classic scripts in a document tree only

// <span>dynamic markup insertion</span>
[<span>CEReactions</span>] <span>Document</span> <span data-x="dom-document-open">open</span>(optional DOMString type, optional DOMString replace); // both type and replace are ignored
[<span>CEReactions</span>] <span>Document</span> <span data-x="dom-document-open">open</span>(optional DOMString unused1, optional DOMString unused2); // both arguments are <a href="#dom-document-open-unused-arguments">ignored</a>
<span>WindowProxy</span> <span data-x="dom-document-open-window">open</span>(USVString url, DOMString name, DOMString features);
[<span>CEReactions</span>] void <span data-x="dom-document-close">close</span>();
[<span>CEReactions</span>] void <span data-x="dom-document-write">write</span>(DOMString... text);
Expand Down Expand Up @@ -66097,8 +66098,7 @@ console.log(plasticButton.outerHTML); // will output '&lt;button is="plastic-but
this</code>).</p></li>

<li><p>The constructor must not use the <code data-x="dom-document-write">document.write()</code>
or <code data-x="dom-document-open">document.open(<var>type</var>, <var>replace</var>)</code>
methods.</p></li>
or <code data-x="dom-document-open">document.open()</code> methods.</p></li>

<li><p>The element's attributes and children must not be inspected, as in the non-<span
data-x="custom-element-upgrades">upgrade</span> case none will be present, and relying on
Expand Down Expand Up @@ -79513,10 +79513,10 @@ interface <dfn>BarProp</dfn> {
<span data-x="concept-url-origin">origin</span> assigned when the <code>Document</code> is
created.</p>

<p class="note">The <code data-x="dom-document-open">document.open(<var>type</var>,
<var>replace</var>)</code> method can change the <code>Document</code>'s <span
data-x="concept-document-url">URL</span> to "<code>about:blank</code>". Therefore the
<span>origin</span> is assigned when the <code>Document</code> is created.</p>
<p class="note">The <code data-x="dom-document-open">document.open()</code> method can change
the <code>Document</code>'s <span data-x="concept-document-url">URL</span> to
"<code>about:blank</code>". Therefore the <span>origin</span> is assigned when the
<code>Document</code> is created.</p>
</dd>


Expand Down Expand Up @@ -86547,8 +86547,7 @@ interface <dfn>ApplicationCache</dfn> : <span>EventTarget</span> {
<p class="example">For example, the <span data-x="concept-document-url">URL</span> of the
<span>responsible document</span> is used to set the <span
data-x="concept-document-url">URL</span> of the <code>Document</code> after it has been reset
using <code data-x="dom-document-open">document.open(<var>type</var>,
<var>replace</var>)</code>.</p>
using <code data-x="dom-document-open">document.open()</code>.</p>

<p>If the <span>responsible event loop</span> is not a <span>browsing context</span> <span>event loop</span>,
then the <span>environment settings object</span> has no <span>responsible document</span>.</p>
Expand Down Expand Up @@ -89968,7 +89967,7 @@ dictionary <dfn>PromiseRejectionEventInit</dfn> : <span>EventInit</span> {
</ol>

<p class="note">This algorithm is used to define <code
data-x="dom-document-open">document.open(<var>type</var>, <var>replace</var>)</code>.</p>
data-x="dom-document-open">document.open()</code>.</p>

<p>To <dfn>activate an event handler</dfn> given an <code>EventTarget</code> object
<var>eventTarget</var> and a string <var>name</var> that is the <span data-x="event handler
Expand Down Expand Up @@ -90926,8 +90925,8 @@ document.body.appendChild(frame)</code></pre>
<p><code>Document</code> objects have a <dfn>throw-on-dynamic-markup-insertion counter</dfn>,
which is used in conjunction with the <span>create an element for the token</span> algorithm to
prevent <span data-x="custom element constructor">custom element constructors</span> from being
able to use <code data-x="dom-document-open">document.open(<var>type</var>,
<var>replace</var>)</code>, <code data-x="dom-document-close">document.close()</code>, and <code
able to use <code data-x="dom-document-open">document.open()</code>, <code
data-x="dom-document-close">document.close()</code>, and <code
data-x="dom-document-write">document.write()</code> when they are invoked by the parser.
Initially, the counter must be set to zero.</p>

Expand All @@ -90938,18 +90937,13 @@ document.body.appendChild(frame)</code></pre>
<h4>Opening the input stream</h4>

<dl class="domintro">
<dt><var>document</var> = <var>document</var> . <code subdfn data-x="dom-document-open">open</code>( [ <var>type</var> [, <var>replace</var> ] ] )</dt>
<dt><var>document</var> = <var>document</var> . <code subdfn data-x="dom-document-open">open</code>( )</dt>
<dd>
<p>Causes the <code>Document</code> to be replaced in-place, as if it was a new
<code>Document</code> object, but reusing the previous object, which is then returned.</p>

<p>The resulting <code>Document</code> has an HTML parser associated with it, which can be given
data to parse using <code data-x="dom-document-write">document.write()</code>. (The
<var>type</var> argument is ignored.)</p>

<p>If the <var>replace</var> argument is present and has the value "<code
data-x="">replace</code>", the existing entries in the session history for the
<code>Document</code> object are removed.</p>
data to parse using <code data-x="dom-document-write">document.write()</code>.</p>

<p>The method has no effect if the <code>Document</code> is still being parsed.</p>

Expand All @@ -90967,11 +90961,9 @@ document.body.appendChild(frame)</code></pre>
<div w-nodev>

<p><code>Document</code> objects have an <dfn>ignore-opens-during-unload counter</dfn>, which is
used to prevent scripts from invoking the <code
data-x="dom-document-open">document.open(<var>type</var>, <var>replace</var>)</code> method
(directly or indirectly) while the document is <span data-x="unload a document">being
unloaded</span>. Initially, the counter must be set to zero.</p> <!--
https://www.hixie.ch/tests/adhoc/dom/level0/document/open/unload/ -->
used to prevent scripts from invoking the <code data-x="dom-document-open">document.open()</code>
method (directly or indirectly) while the document is <span data-x="unload a document">being
unloaded</span>. Initially, the counter must be set to zero.</p>

<p>The <dfn>document open steps</dfn>, given a <var>document</var>, are as follows:</p>

Expand Down Expand Up @@ -91000,19 +90992,17 @@ document.body.appendChild(frame)</code></pre>
<p>If <var>document</var> has an <span>active parser</span> whose <span>script nesting
level</span> is greater than 0, then return <var>document</var>.</p>

<p class="note">This basically causes <code
data-x="dom-document-open">document.open(<var>type</var>, <var>replace</var>)</code> to be
ignored when it's called in an inline script found during parsing, while still letting it have
an effect when called from a non-parser task such as a timer callback or event handler.</p>
<p class="note">This basically causes <code data-x="dom-document-open">document.open()</code> to
be ignored when it's called in an inline script found during parsing, while still letting it
have an effect when called from a non-parser task such as a timer callback or event handler.</p>
</li>

<li>
<p>Similarly, if <var>document</var>'s <span>ignore-opens-during-unload counter</span> is
greater than 0, then return <var>document</var>.</p>

<p class="note">This basically causes <code
data-x="dom-document-open">document.open(<var>type</var>, <var>replace</var>)</code> to be
ignored when it's called from a <code data-x="event-beforeunload">beforeunload</code>, <code
<p class="note">This basically causes <code data-x="dom-document-open">document.open()</code> to
be ignored when it's called from a <code data-x="event-beforeunload">beforeunload</code>, <code
data-x="event-pagehide">pagehide</code>, or <code data-x="event-unload">unload</code> event
handler while the <code>Document</code> is being unloaded.</p>
</li>
Expand All @@ -91039,7 +91029,7 @@ document.body.appendChild(frame)</code></pre>

<li><p>Create a new <span>HTML parser</span> and associate it with <var>document</var>. This is a
<dfn>script-created parser</dfn> (meaning that it can be closed by the <code
data-x="dom-document-open">document.open(<var>type</var>, <var>replace</var>)</code> and <code
data-x="dom-document-open">document.open()</code> and <code
data-x="dom-document-close">document.close()</code> methods, and that the tokenizer will wait for
an explicit call to <code data-x="dom-document-close">document.close()</code> before emitting an
end-of-file token). The encoding <span data-x="concept-encoding-confidence">confidence</span> is
Expand All @@ -91057,11 +91047,17 @@ document.body.appendChild(frame)</code></pre>
<p class="note">The <span>document open steps</span> do not affect whether a <code>Document</code>
is <span>ready for post-load tasks</span> or <span>completely loaded</span>.</p>

<p>The <dfn data-x="dom-document-open"><code>open(<var>type</var>,
<var>replace</var>)</code></dfn> method must return the result of running the <span>document open
<p>The <dfn data-x="dom-document-open"><code>open(<var>unused1</var>,
<var>unused2</var>)</code></dfn> method must return the result of running the <span>document open
steps</span> with this <code>Document</code> object.

<p class="note">The <var>type</var> argument is ignored.</p>
<p class="note" id="dom-document-open-unused-arguments">The <var>unused1</var> and
<var>unused2</var> arguments are ignored, but kept in the IDL to allow code that calls the
function with one or two arguments to continue working. They are necessary due to Web IDL
<span>overload resolution algorithm</span> rules, which would throw a <code>TypeError</code>
exception for such calls had the arguments not been there. <a
href="https://github.com/heycam/webidl/issues/581">heycam/webidl#581</a> investigates changing the
algorithm to allow for their removal. <ref spec=WEBIDL></p>

<p>The <dfn data-x="dom-document-open-window"><code>open(<var>url</var>, <var>name</var>,
<var>features</var>)</code></dfn> method must run these steps:</p>
Expand All @@ -91087,7 +91083,7 @@ document.body.appendChild(frame)</code></pre>
<dd>

<p>Closes the input stream that was opened by the <code
data-x="dom-document-open">document.open(<var>type</var>, <var>replace</var>)</code> method.</p>
data-x="dom-document-open">document.open()</code> method.</p>

<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> if the
<code>Document</code> is an <span data-x="XML documents">XML document</span>.</p>
Expand Down Expand Up @@ -91147,9 +91143,9 @@ document.body.appendChild(frame)</code></pre>
that does not correspond to the source of the document (e.g. if the string written is the string
"<code data-x="">&lt;plaintext&gt;</code>" or "<code data-x="">&lt;!--</code>"). In other cases,
the call can clear the current page first, as if <code
data-x="dom-document-open">document.open(<var>type</var>, <var>replace</var>)</code> had been
called. In yet more cases, the method is simply ignored, or throws an exception. Users agents
are <a href="#document-written-scripts-intervention">explicitly allowed to avoid executing
data-x="dom-document-open">document.open()</code> had been called. In yet more cases, the method
is simply ignored, or throws an exception. Users agents are <a
href="#document-written-scripts-intervention">explicitly allowed to avoid executing
<code>script</code> elements inserted via this method</a>. And to make matters even worse, the
exact behavior of this method can in some cases be dependent on network latency<!--

Expand Down Expand Up @@ -91178,9 +91174,8 @@ document.body.appendChild(frame)</code></pre>
<p><code>Document</code> objects have an <dfn>ignore-destructive-writes counter</dfn>, which is
used in conjunction with the processing of <code>script</code> elements to prevent external
scripts from being able to use <code data-x="dom-document-write">document.write()</code> to blow
away the document by implicitly calling <code
data-x="dom-document-open">document.open(<var>type</var>, <var>replace</var>)</code>. Initially,
the counter must be set to zero.</p>
away the document by implicitly calling <code data-x="dom-document-open">document.open()</code>.
Initially, the counter must be set to zero.</p>

<p>The <dfn>document write steps</dfn>, given a <code>Document</code> object <var>document</var>
and a string <var>input</var>, are as follows:</p>
Expand Down Expand Up @@ -91246,8 +91241,8 @@ document.body.appendChild(frame)</code></pre>
<dd>

<p>Adds the given string(s) to the <code>Document</code>'s input stream, followed by a newline
character. If necessary, calls the <code data-x="dom-document-open">open(<var>type</var>,
<var>replace</var>)</code> method implicitly first.</p>
character. If necessary, calls the <code data-x="dom-document-open">open()</code> method
implicitly first.</p>

<p>Throws an <span>"<code>InvalidStateError</code>"</span> <code>DOMException</code> when
invoked on <span>XML documents</span>.</p>
Expand Down Expand Up @@ -107803,8 +107798,8 @@ document.body.appendChild(text);

<p class="note">This could happen if, e.g., while the <span>spin the event loop</span>
algorithm is running, the <span>browsing context</span> gets closed, or the <code
data-x="dom-document-open">document.open(<var>type</var>, <var>replace</var>)</code> method
gets invoked on the <code>Document</code>.</p>
data-x="dom-document-open">document.open()</code> method gets invoked on the
<code>Document</code>.</p>

</li>

Expand Down

0 comments on commit 1dafd08

Please sign in to comment.