Skip to content

Commit 2819334

Browse files
authored
Editorial: account for SharedArrayBuffer change in Web IDL
See whatwg/webidl#1311 for context. At the same time, address some Bikeshed errors around label(s) and reduce the amount of confusion between label the member of encoding and label the type by not cross-referencing the latter to the former.
1 parent 3721bec commit 2819334

File tree

1 file changed

+33
-38
lines changed

1 file changed

+33
-38
lines changed

encoding.bs

Lines changed: 33 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -349,21 +349,20 @@ given an <a for=list>item</a> <var>item</var>, <a for=/>encoding</a>'s <a for=/>
349349
<h3 id=names-and-labels>Names and labels</h3>
350350

351351
<p>The table below lists all <a for=/>encodings</a>
352-
and their <a>labels</a> user agents must support.
352+
and their <a for=encoding>labels</a> user agents must support.
353353
User agents must not support any other <a for=/>encodings</a>
354-
or <a>labels</a>.
354+
or <a for=encoding>labels</a>.
355355

356356
<p class=note>For each encoding, <a lt="ASCII lowercase">ASCII-lowercasing</a> its
357357
<a for=encoding>name</a> yields one of its <a for=encoding>labels</a>.
358358

359-
<p>Authors must use the <a>UTF-8</a> <a for=/>encoding</a> and must use the
360-
<a>ASCII case-insensitive</a> "<code>utf-8</code>" <a>label</a> to
361-
identify it.
359+
<p>Authors must use the <a>UTF-8</a> <a for=/>encoding</a> and must use its
360+
(<a>ASCII case-insensitive</a>) "<code>utf-8</code>" <a for=encoding>label</a> to identify it.
362361

363-
<p>New protocols and formats, as well as existing formats deployed in new contexts, must
364-
use the <a>UTF-8</a> <a for=/>encoding</a> exclusively. If these protocols and
365-
formats need to expose the <a for=/>encoding</a>'s <a>name</a> or
366-
<a>label</a>, they must expose it as "<code>utf-8</code>".
362+
<p>New protocols and formats, as well as existing formats deployed in new contexts, must use the
363+
<a>UTF-8</a> <a for=/>encoding</a> exclusively. If these protocols and formats need to expose the
364+
<a for=/>encoding</a>'s <a for=encoding>name</a> or <a for=encoding>label</a>, they must expose it
365+
as "<code>utf-8</code>".
367366
<!-- “UTF-8 or death” — Emil A Eklund -->
368367

369368
<p>To
@@ -374,21 +373,20 @@ from a string <var>label</var>, run these steps:
374373
<li><p>Remove any leading and trailing <a>ASCII whitespace</a> from
375374
<var>label</var>.
376375

377-
<li><p>If <var>label</var> is an <a>ASCII case-insensitive</a> match for any of the <a>labels</a>
378-
listed in the table below, then return the corresponding <a for=/>encoding</a>; otherwise return
379-
failure.
376+
<li><p>If <var>label</var> is an <a>ASCII case-insensitive</a> match for any of the labels listed
377+
in the table below, then return the corresponding <a for=/>encoding</a>; otherwise return failure.
380378
</ol>
381379

382-
<p class="note no-backref">This is a more basic and restrictive algorithm of mapping <a>labels</a>
383-
to <a for=/>encodings</a> than
380+
<p class=note>This is a more basic and restrictive algorithm of mapping labels to
381+
<a for=/>encodings</a> than
384382
<a href=https://www.unicode.org/reports/tr22/tr22-8.html#Charset_Alias_Matching>section 1.4 of Unicode Technical Standard #22</a>
385383
prescribes, as that is necessary to be compatible with deployed content.
386384

387385
<table>
388386
<thead>
389387
<tr>
390-
<th><a>Name</a>
391-
<th><a>Labels</a>
388+
<th>Name
389+
<th>Labels
392390
<tbody>
393391
<tr><th colspan=2><a href=#the-encoding>The Encoding</a>
394392
<tr>
@@ -713,9 +711,8 @@ prescribes, as that is necessary to be compatible with deployed content.
713711
<td>"<code>x-user-defined</code>"
714712
</table>
715713

716-
<p class=note>All <a for=/>encodings</a> and their
717-
<a>labels</a> are also available as non-normative
718-
<a href=encodings.json>encodings.json</a> resource.
714+
<p class=note>All <a for=/>encodings</a> and their <a for=encoding>labels</a> are also available as
715+
non-normative <a href=encodings.json>encodings.json</a> resource.
719716

720717
<p class=note id=supported-encodings>The set of supported <a for=/>encodings</a> is primarily based
721718
on the intersection of the sets supported by major browser engines when the development of this
@@ -1041,9 +1038,9 @@ optional I/O queue of bytes <var>output</var> (default « »), return the result
10411038
<div class=note>
10421039
<p>Standards are strongly discouraged from using <a>decode</a>, <a>BOM sniff</a>, and
10431040
<a for=/>encode</a>, except as needed for compatibility. Standards needing these legacy hooks will
1044-
most likely also need to use <a>get an encoding</a> (to turn a <a>label</a> into an
1045-
<a for=/>encoding</a>) and <a>get an output encoding</a> (to turn an <a for=/>encoding</a> into
1046-
another <a for=/>encoding</a> that is suitable to pass into <a>encode</a>).
1041+
most likely also need to use <a>get an encoding</a> (to turn a label into an <a for=/>encoding</a>)
1042+
and <a>get an output encoding</a> (to turn an <a for=/>encoding</a> into another
1043+
<a for=/>encoding</a> that is suitable to pass into <a>encode</a>).
10471044

10481045
<p>For the extremely niche case of URL percent-encoding, custom encoder error handling is needed.
10491046
The <a>get an encoder</a> and <a>encode or fail</a> algorithms are to be used for that. Other
@@ -1341,7 +1338,7 @@ dictionary TextDecodeOptions {
13411338
interface TextDecoder {
13421339
constructor(optional DOMString label = "utf-8", optional TextDecoderOptions options = {});
13431340

1344-
USVString decode(optional [AllowShared] BufferSource input, optional TextDecodeOptions options = {});
1341+
USVString decode(optional AllowSharedBufferSource input, optional TextDecodeOptions options = {});
13451342
};
13461343
TextDecoder includes TextDecoderCommon;
13471344
</pre>
@@ -1354,10 +1351,8 @@ initially false.
13541351
<dt><code><var>decoder</var> = new <a constructor for=TextDecoder lt=TextDecoder()>TextDecoder([<var>label</var> = "utf-8" [, <var>options</var>]])</a></code>
13551352
<dd>
13561353
<p>Returns a new {{TextDecoder}} object.
1357-
<p>If <var>label</var> is either not a <a>label</a> or is a
1358-
<a>label</a> for <a>replacement</a>,
1359-
<a>throws</a> a
1360-
{{RangeError}}.
1354+
<p>If <var>label</var> is either not a label or is a <a for=encoding>label</a> for
1355+
<a>replacement</a>, <a>throws</a> a {{RangeError}}.
13611356

13621357
<dt><code><var>decoder</var> . <a attribute for=TextDecoderCommon>encoding</a></code>
13631358
<dd><p>Returns <a for=TextDecoderCommon>encoding</a>'s <a>name</a>, lowercased.
@@ -1673,8 +1668,8 @@ TextDecoderStream includes GenericTransformStream;
16731668
"utf-8" [, <var>options</var>]])</a></code>
16741669
<dd>
16751670
<p>Returns a new {{TextDecoderStream}} object.
1676-
<p>If <var>label</var> is either not a <a>label</a> or is a <a>label</a> for <a>replacement</a>,
1677-
<a>throws</a> a {{RangeError}}.
1671+
<p>If <var>label</var> is either not a label or is a <a for=encoding>label</a> for
1672+
<a>replacement</a>, <a>throws</a> a {{RangeError}}.
16781673

16791674
<dt><code><var>decoder</var> . <a attribute for=TextDecoderCommon>encoding</a></code>
16801675
<dd><p>Returns <a for=TextDecoderCommon>encoding</a>'s <a>name</a>, lowercased.
@@ -1695,7 +1690,7 @@ TextDecoderStream includes GenericTransformStream;
16951690
<dt><code><var>decoder</var> . <a attribute for=GenericTransformStream>writable</a></code>
16961691
<dd>
16971692
<p>Returns a <a>writable stream</a> which accepts
1698-
<code>[<a extended-attribute>AllowShared</a>] <a typedef>BufferSource</a></code> chunks and runs
1693+
<code><a typedef>AllowSharedBufferSource</a></code> chunks and runs
16991694
them through <a for=TextDecoderCommon>encoding</a>'s <a for=/>decoder</a> before making them
17001695
available to {{GenericTransformStream/readable}}.
17011696

@@ -1758,7 +1753,7 @@ constructor steps are:
17581753
<ol>
17591754
<li><p>Let <var>bufferSource</var> be the result of
17601755
<a lt="converted to an IDL value">converting</a> <var>chunk</var> to an
1761-
<code>[<a extended-attribute>AllowShared</a>] <a typedef>BufferSource</a></code>.
1756+
<code><a typedef>AllowSharedBufferSource</a></code>.
17621757

17631758
<li>
17641759
<p><a>Push</a> a <a lt="get a copy of the buffer source">copy of</a> <var>bufferSource</var> to
@@ -2030,9 +2025,9 @@ that are split between strings. [[!INFRA]]
20302025

20312026
<h4 id=utf-8-decoder dfn export>UTF-8 decoder</h4>
20322027

2033-
<p class="note no-backref">A byte order mark has priority over a <a>label</a> as it has been found
2034-
to be more accurate in deployed content. Therefore it is not part of the <a>UTF-8 decoder</a>
2035-
algorithm but rather the <a>decode</a> and <a>UTF-8 decode</a> algorithms.
2028+
<p class=note>A byte order mark has priority over a label as it has been found to be more accurate
2029+
in deployed content. Therefore it is not part of the <a>UTF-8 decoder</a> algorithm, but rather the
2030+
<a>decode</a> and <a>UTF-8 decode</a> algorithms.
20362031

20372032
<p><a>UTF-8</a>'s <a for=/>decoder</a> has an associated
20382033
<dfn>UTF-8 code point</dfn>, <dfn>UTF-8 bytes seen</dfn>, and
@@ -3253,9 +3248,9 @@ the server and the client.
32533248

32543249
<h4 id=shared-utf-16-decoder dfn export>shared UTF-16 decoder</h4>
32553250

3256-
<p class="note no-backref">A byte order mark has priority over a <a>label</a> as it
3257-
has been found to be more accurate in deployed content. Therefore it is not part of the
3258-
<a>shared UTF-16 decoder</a> algorithm but rather the <a>decode</a> algorithm.
3251+
<p class=note>A byte order mark has priority over a label as it has been found to be more accurate
3252+
in deployed content. Therefore it is not part of the <a>shared UTF-16 decoder</a> algorithm, but
3253+
rather the <a>decode</a> algorithm.
32593254

32603255
<p><a>shared UTF-16 decoder</a> has an associated <dfn>UTF-16 lead byte</dfn> and
32613256
<dfn>UTF-16 lead surrogate</dfn> (both initially null), and
@@ -3331,7 +3326,7 @@ its <a>is UTF-16BE decoder</a> set to true.
33313326

33323327
<h3 id=utf-16le dfn export>UTF-16LE</h3>
33333328

3334-
<p class="note no-backref">"<code>utf-16</code>" is a <a>label</a> for <a>UTF-16LE</a> to deal with
3329+
<p class=note>"<code>utf-16</code>" is a <a for=encoding>label</a> for <a>UTF-16LE</a> to deal with
33353330
deployed content.
33363331

33373332

0 commit comments

Comments
 (0)