Suggested re-wording for lexical order

Author: rjmccall

abi.html

@@ -5584,34 +5584,59 @@ <h4><a href="#closure-types">5.1.8 Closure Types (Lambdas)</a></h4>
 <h4><a href="#lexical-ordering">5.1.9 Lexical ordering</a></h4>
 
 <p>
-Lexical ordering is used for numbering local entities
-(unnamed classes and enumerations,
-closure types, and static local variables)
-when there is no other way of distinguishing them.
-Except as described below, all local entities are to be numbered,
-even if subsequent optimization makes some of them unnecessary,
-or no mangled name is actually required for some of them.
-The ordering of entities appearing in a
-mem-initializer-list shall be the order that the entities appear in
-the source, which may be different from the order in which the
-initializers will be executed when the program runs.
-It is expected that this will be the 'natural' order in most compilers.
-
-<p>
-Within a non-template, the numbering
-is in strictly lexical order based on the original token sequence.
-Within a template instantiation, the numbering
-is established after packs are expanded and discarded statements in
-constexpr ifs are removed.
+Lexical ordering is used for numbering local entities (named and unnamed
+local classes and enumerations, closure types, and static local variables)
+when there is no other way of distinguishing them.  Except as described below,
+all local entities are to be numbered, even if subsequent optimization makes
+some of them unnecessary, or no mangled name is actually required for
+some of them.
+
+<p>
+The order of entities is the source order of a key token unique to the
+entity as if:
+
+<ul>
+<li>the discarded sub-statements of <tt>if constexpr</tt> within a
+template did not exist and
+<li>pack expansions were lexically expanded.
+</ul>
+
+<p>In all cases, this is meant to imitate the numbering that would
+be produced by a simple implementation which numbered entities as it
+processed the source and recursively expanded packs.  Since discarded
+substatements of <tt>if constexpr</tt> are still processed in
+non-template code, entities within them are still numbered.
+
+<p>Entities may be lexically nested without being in different
+contexts for the purposes of mangling.  For example, the lambdas in
+<code>[x = []{}]{}</code> are both part of the enclosing context.
+The order of such entities is determined by the source order of a key
+token in the entity.  In general, this token is the first token
+past which the signature of the entity (as is necessary to mangle it)
+is known:
+
+<ul>
+<li>The key token of a class or enum is the end of the
+  <code>enum-head-name</code> (<code>enum-key</code> if unnamed) or
+  <code>class-head-name</code> (<code>class-key</code> if unnamed)
+  in its first declaration.
+<li>The key token of a lambda is its closing brace (<code>}</code>).
+<li>The key token of a static local variable is the last token of its
+  <code>declarator</code> (not its initializer).
+</ul>
+
+<p>
 All entities from one expansion of a pack are considered to occur
 lexically before any entities from the next expansion of the same pack,
 but the ordering is otherwise based on the original token sequence.
 This is expected to match the numbering that would be established for
 the corresponding non-template generated by substitution into the template.
 As a consequence of these rules, the entity instantiated for a particular
 source construct can have a different mangling number in different
-instantiations of the same template.
-For example:
+instantiations of the same template.  An entity appearing in the original
+source may also go entirely un-numbered if it appears in a discarded
+sub-statement of <code>if constexpr</code> or in a pack expansion of an
+empty pack.  For example:
 
 <code><pre>
 void g(...);
@@ -5637,6 +5662,12 @@ <h4><a href="#lexical-ordering">5.1.9 Lexical ordering</a></h4>
 }
 </pre></code>
 
+<p>
+Note that the numbering of entities appearing within a
+<code>mem-initializer-list</code> reflects the order that the
+initializers appear in the source, which may be different from the
+order in which the initializers will be executed when the program runs.
+
 <p>
 <a name="mangling-compression">
 <h4><a href="#mangling-compression">5.1.10 Compression</a></h4>