Change symbolLiteral to match actual implementation, clean up reserved words formatting (#1588)

Clean up reserved words formatting, change symbolLiteral to match actual implementation. Clarify the 'Symbols' section.

Author: eernstg

specification/dartLangSpec.tex

@@ -8966,30 +8966,28 @@ \subsection{Symbols}
 \LMHash{}%
 A \IndexCustom{symbol literal}{literal!symbol}
 denotes a name that would be either
-a valid declaration name or a valid library name in a Dart program.
+a valid declaration name, a valid library name, or \VOID.
 
 \begin{grammar}
-<symbolLiteral> ::= `#' (<operator> | (<identifier> (`.' <identifier>)*))
+<symbolLiteral> ::=
+  `#' (<identifier> (`.' <identifier>)* | <operator> | \VOID)
 \end{grammar}
 
 \LMHash{}%
-A symbol literal \code{\#\id} where \id{} is an identifier
-that does not begin with an underscore (`\code{\_}'),
-evaluates to an instance of \code{Symbol} representing the identifier \id.
-All occurrences of \code{\#\id} evaluate to the same instance
-\commentary{(symbol instances are canonicalized)},
-and no other symbol literals evaluate to that \code{Symbol} instance
-or to a \code{Symbol} instance that is equal
-(according to the \lit{==} operator \ref{equality}) to that instance.
+The static type of a symbol literal is \code{Symbol}.
+
+\LMHash{}%
+Let \id{} be an identifier that does not begin with an underscore
+(`\code{\_}').
+The symbol literal \code{\#\id}
+evaluates to an instance of \code{Symbol}
+representing the identifier \id.
 
 \LMHash{}%
-A symbol literal \code{\#$\id.\id_2\ldots\id_n$}
-where $\id{} \ldots \id_n$ are identifiers,
-evaluates to an instance of \code{Symbol} representing that particular sequence of identifiers.
-All occurrences of \code{\#$\id.\id_2\ldots\id_n$} with the same sequence of identifiers
-evaluate to the same instance,
-and no other symbol literals evaluate to that \code{Symbol} instance
-or to a \code{Symbol} instance that is \lit{==} to that instance.
+A symbol literal \code{\#$\id_1$.$\id_2$.$\cdots$.$\id_n$}
+where \List{\id}{1}{n} are identifiers
+evaluates to an instance of \code{Symbol}
+representing that particular sequence of identifiers.
 \commentary{%
 This kind of symbol literal denotes the name of a library declaration,
 as specified in a \synt{libraryName}.
@@ -8998,18 +8996,39 @@ \subsection{Symbols}
 }
 
 \LMHash{}%
-A symbol literal \code{\#\metavar{operator}} evaluates to an instance of \code{Symbol}
+A symbol literal \code{\#\metavar{op}}
+where \metavar{op} is derived from \synt{operator}
+evaluates to an instance of \code{Symbol}
 representing that particular operator name.
-All occurrences of \code{\#\metavar{operator}} evaluate to the same instance,
-and no other symbol literals evaluate to that \code{Symbol} instance
-or to a \code{Symbol} instance that is \lit{==} to that instance.
 
 \LMHash{}%
-A symbol literal \code{\#\_\id}, evaluates to an instance of \code{Symbol}
+The symbol literal \code{\#void}
+evaluates to an instance of \code{Symbol}
+representing the reserved word \VOID.
+
+\LMHash{}%
+Assume that the term $t$ is an identifier \id{}
+that does not start with an underscore,
+that $t$ is \VOID,
+that $t$ is a period separated sequence of identifiers
+\code{$id_1$.$id_2$.$\cdots$.$id_n$},
+or that $t$ is derived from \synt{operator}.
+Any two occurrences of \code{\#t} evaluate to the same object
+(\commentary{that is, symbol instances are canonicalized}),
+and no other symbol literals evaluate to that object,
+nor to a \code{Symbol} instance that is equal to that object
+according to the \lit{==} operator
+(\ref{equality}).
+
+\LMHash{}%
+A symbol literal \code{\#\_\id} where \id{} is an identifier
+evaluates to an instance of \code{Symbol}
 representing the private identifier \code{\_\id} of the containing library.
-All occurrences of \code{\#\_\id} \emph{in the same library} evaluate to the same instance,
-and no other symbol literals evaluate to that \code{Symbol} instance
-or to a \code{Symbol} instance that is \lit{==} to that instance.
+All occurrences of \code{\#\_\id} \emph{in the same library} evaluate to
+the same object,
+and no other symbol literals evaluate to the same object,
+nor to a \code{Symbol} instance that is equal to that object
+according to the \lit{==} operator.
 
 \LMHash{}%
 The objects created by symbol literals all override
@@ -9043,9 +9062,6 @@ \subsection{Symbols}
 convenient substitutes for enums are secondary benefits.%
 }
 
-\LMHash{}%
-The static type of a symbol literal is \code{Symbol}.
-
 
 \subsection{Collection Literals}
 \LMLabel{collectionLiterals}
@@ -16048,6 +16064,13 @@ \subsection{Identifier Reference}
 
 <qualifiedName> ::= <typeIdentifier> `.' <identifier>
   \alt <typeIdentifier> `.' <typeIdentifier> `.' <identifier>
+
+<LETTER> ::= `a' .. `z'
+  \alt `A' .. `Z'
+
+<DIGIT> ::= `0' .. `9'
+
+<WHITESPACE> ::= (`\\t' | ` ' | <NEWLINE>)+
 \end{grammar}
 
 \LMHash{}%
@@ -21424,17 +21447,28 @@ \subsubsection{Reserved Words}
 \LMLabel{reservedWords}
 
 \LMHash{}%
-A \Index{reserved word} may not be used as an identifier; it is a compile-time error if a reserved word is used where an identifier is expected.
+A \Index{reserved word} can only be used in the syntactic positions
+specified by the grammar.
+In particular, a compile-time error occurs if a reserved word is used
+where an identifier is expected.
 
-\ASSERT{}, \BREAK{}, \CASE{}, \CATCH{}, \CLASS{}, \CONST{}, \CONTINUE{}, \DEFAULT{}, \DO{}, \ELSE{}, \ENUM{}, \EXTENDS{}, \FALSE{}, \FINAL{}, \FINALLY{}, \FOR{}, \IF{}, \IN{}, \IS{}, \NEW{}, \NULL{}, \RETHROW, \RETURN{}, \SUPER{}, \SWITCH{}, \THIS{}, \THROW{}, \TRUE{}, \TRY{}, \VAR{}, \VOID{}, \WHILE{}, \WITH{}.
+\commentary{%
+Note that reserved words occur bold and unquoted in grammar rules
+(e.g., \ASSERT{})
+even though the consistent notation would use quotes
+(e.g., \lit{assert}).
+This notational abuse occurs because we believe
+it makes the grammar rules more readable.%
+}
 
 \begin{grammar}
-<LETTER> ::= `a' .. `z'
-  \alt `A' .. `Z'
-
-<DIGIT> ::= `0' .. `9'
-
-<WHITESPACE> ::= (`\\t' | ` ' | <NEWLINE>)+
+<reservedWord> ::= \ASSERT{} | \BREAK{} | \CASE{} | \CATCH{} |
+    \CLASS{} | \CONST{} | \CONTINUE{}
+  \alt\hspace{-3mm} \DEFAULT{} | \DO{} | \ELSE{} | \ENUM{} | \EXTENDS{} |
+    \FALSE{} | \FINAL{} | \FINALLY{} | \FOR{} | \IF{} | \IN{} | \IS{}
+  \alt\hspace{-3mm} \NEW{} | \NULL{} | \RETHROW{} | \RETURN{} | \SUPER{} |
+    \SWITCH{} | \THIS{} | \THROW{} | \TRUE{} | \TRY{}
+  \alt\hspace{-3mm} \VAR{} | \VOID{} | \WHILE{} | \WITH{}
 \end{grammar}