Editorial: Rework the 'Identity' section

spec.html

@@ -1107,10 +1107,25 @@ <h1>Value Notation</h1>
     <emu-clause id="sec-identity">
       <h1>Identity</h1>
       <p>In this specification, both specification values and ECMAScript language values are compared for equality. When comparing for equality, values fall into one of two categories. <dfn variants="values without identity,value without identity">Values without identity</dfn> are equal to other values without identity if all of their innate characteristics are the same — characteristics such as the magnitude of an integer or the length of a sequence. Values without identity may be manifest without prior reference by fully describing their characteristics. In contrast, each <dfn variants="values with identity">value with identity</dfn> is unique and therefore only equal to itself. Values with identity are like values without identity but with an additional unguessable, unchangeable, universally-unique characteristic called <em>identity</em>. References to existing values with identity cannot be manifest simply by describing them, as the identity itself is indescribable; instead, references to these values must be explicitly passed from one place to another. Some values with identity are mutable and therefore can have their characteristics (except their identity) changed in-place, causing all holders of the value to observe the new characteristics. A value without identity is never equal to a value with identity.</p>
-      <p>From the perspective of this specification, the word “is” is used to compare two values for equality, as in “If _bool_ is *true*, then ...”, and the word “contains” is used to search for a value inside lists using equality comparisons, as in "If _list_ contains a Record _r_ such that _r_.[[Foo]] is *true*, then ...". The <em>specification identity</em> of values determines the result of these comparisons and is axiomatic in this specification.</p>
-      <p>From the perspective of the ECMAScript language, language values are compared for equality using the SameValue abstract operation and the abstract operations it transitively calls. The algorithms of these comparison abstract operations determine <em>language identity</em> of ECMAScript language values.</p>
-      <p>For specification values, examples of values without specification identity include, but are not limited to: mathematical values and extended mathematical values; ECMAScript source text, surrogate pairs, Directive Prologues, etc; UTF-16 code units; Unicode code points; enums; abstract operations, including syntax-directed operations, host hooks, etc; and ordered pairs. Examples of specification values with specification identity include, but are not limited to: any kind of Records, including Property Descriptors, PrivateElements, etc; Parse Nodes; Lists; <emu-xref href="#sec-set-and-relation-specification-type">Sets</emu-xref> and Relations; Abstract Closures; Data Blocks; Private Names; execution contexts and execution context stacks; agent signifiers; and WaiterList Records.</p>
-      <p>Specification identity agrees with language identity for all ECMAScript language values except Symbol values produced by <emu-xref href="#sec-symbol.for">Symbol.for</emu-xref>. The ECMAScript language values without specification identity and without language identity are <emu-xref href="#sec-ecmascript-language-types-undefined-type">*undefined*</emu-xref>, <emu-xref href="#sec-ecmascript-language-types-null-type">*null*</emu-xref>, <emu-xref href="#sec-ecmascript-language-types-boolean-type">Booleans</emu-xref>, <emu-xref href="#sec-ecmascript-language-types-string-type">Strings</emu-xref>, <emu-xref href="#sec-ecmascript-language-types-number-type">Numbers</emu-xref>, and <emu-xref href="#sec-ecmascript-language-types-bigint-type">BigInts</emu-xref>. The ECMAScript language values with specification identity and language identity are <emu-xref href="#sec-ecmascript-language-types-symbol-type">Symbols</emu-xref> not produced by <emu-xref href="#sec-symbol.for">Symbol.for</emu-xref> and <emu-xref href="#sec-object-type">Objects</emu-xref>. Symbol values produced by <emu-xref href="#sec-symbol.for">Symbol.for</emu-xref> have specification identity, but not language identity.</p>
+      <p>To some extent, which values have identity depends on perspective, so we distinguish <em>specification identity</em> and <em>language identity</em>.</p>
+      <p><dfn id="specification-identity">Specification identity</dfn> is identity as seen from the perspective of the algorithms of this specification. Within these algorithms, the word “is” is used to compare two values for equality, as in “If _bool_ is *true*, then ...”, and the word “contains” is used to search for a value inside lists using equality comparisons, as in "If _list_ contains a Record _r_ such that _r_.[[Foo]] is *true*, then ...". For such comparisons:</p>
+      <ul>
+        <li>
+          <p>values <em>with</em> specification identity include, but are not limited to:</p>
+          <ul>
+            <li>language values: <emu-xref href="#sec-object-type">Objects</emu-xref> and <emu-xref href="#sec-ecmascript-language-types-symbol-type">Symbols</emu-xref></li>
+            <li>specification values: any kind of Records, including Property Descriptors, PrivateElements, etc; Parse Nodes; Lists; <emu-xref href="#sec-set-and-relation-specification-type">Sets</emu-xref> and Relations; Abstract Closures; Data Blocks; Private Names; execution contexts and execution context stacks; and agent signifiers</li>
+          </ul>
+        </li>
+        <li>
+          <p>and values <em>without</em> specification identity include, but are not limited to:</p>
+          <ul>
+            <li>language values: <emu-xref href="#sec-ecmascript-language-types-undefined-type">*undefined*</emu-xref>, <emu-xref href="#sec-ecmascript-language-types-null-type">*null*</emu-xref>, <emu-xref href="#sec-ecmascript-language-types-boolean-type">Booleans</emu-xref>, <emu-xref href="#sec-ecmascript-language-types-string-type">Strings</emu-xref>, <emu-xref href="#sec-ecmascript-language-types-number-type">Numbers</emu-xref>, and <emu-xref href="#sec-ecmascript-language-types-bigint-type">BigInts</emu-xref></li>
+            <li>specification values: mathematical values and extended mathematical values; ECMAScript source text, surrogate pairs, Directive Prologues, etc; UTF-16 code units; Unicode code points; enums; abstract operations, including syntax-directed operations, host hooks, etc; and ordered pairs</li>
+          </ul>
+        </li>
+      </ul>
+      <p><dfn id="language-identity">Language identity</dfn> is identity as seen from the perspective of ECMAScript code. There, language values can be compared for equality in various ways, but the most discriminating is the `Object.is` built-in function, whose semantics are given by the SameValue abstract operation and the abstract operations it transitively calls. These semantics are such that, to a first approximation, language identity matches specification identity. In fact, the only difference between the two involves Symbol values: whereas all Symbols have specification identity, Symbols produced by <emu-xref href="#sec-symbol.for">Symbol.for</emu-xref> do not have language identity.</p>
     </emu-clause>
   </emu-clause>
 </emu-clause>