doc/syntax.tex: Improve the syntax notation.

Rather than having a bunch of special rules, define the notational
extensions in terms of the parametrized nonterminals we have anyway for
declarators, and set that on a more formal footing.

I'm not quite sure how powerful this formalism is.  I believe it's
strictly more powerful than context-free grammars, but I haven't decided
whether it's Turing-equivalent.  It doesn't matter much here either way,
because the actual grammar is indeed context-free even if the formalism
is more expressive than that.

diff --git a/doc/syntax.tex b/doc/syntax.tex
index ca011cbbe79083b57013014430f98112726b71a2..11e80b6534e54134bf1ed9fa6e3cb9ec29392e81 100644 (file)
--- a/doc/syntax.tex
+++ b/doc/syntax.tex
@@ -27,30 +27,45 @@
 
 %%%--------------------------------------------------------------------------
 
-Fortunately, Sod is syntactically quite simple.  I've used a little slightly
-unusual notation in order to make the presentation easier to read.  For any
-nonterminal $x$:
+Fortunately, Sod is syntactically quite simple.  The notation is slightly
+unusual in order to make the presentation shorter and easier to read.
+
+Anywhere a simple nonterminal name $x$ may appear in the grammar, an
+\emph{indexed} nonterminal $x[a_1, \ldots, a_n]$ may also appear.  On the
+left-hand side of a production rule, the indices $a_1$, \ldots, $a_n$ are
+variables which vary over all nonterminal and terminal symbols, and the
+variables may also appear on the right-hand side in place of a nonterminal.
+Such a rule stands for a family of rules, in each variable is replaced by
+each possible simple nonterminal or terminal symbol.
+
+The letter $\epsilon$ denotes the empty nonterminal
+\begin{quote}
+  \syntax{$\epsilon$ ::=}
+\end{quote}
+
+The following indexed productions are used throughout the grammar, some often
+enough that they deserve special notation.
 \begin{itemize}
-\item $\epsilon$ denotes the empty nonterminal:
-  \begin{quote}
-    $\epsilon$ ::=
-  \end{quote}
-\item @[$x$@] means an optional $x$:
+\item @[$x$@] abbreviates @<optional>$[x]$, denoting an optional occurrence
+  of $x$:
   \begin{quote}
-    \syntax{@[$x$@] ::= $\epsilon$ @! $x$}
+    \syntax{@[$x$@] ::= <optional>$[x]$ ::= $\epsilon$ @! $x$}
   \end{quote}
-\item $x^*$ means a sequence of zero or more $x$s:
+\item $x^*$ abbreviates @<zero-or-more>$[x]$, denoting a sequence of zero or
+  more occurrences of $x$:
   \begin{quote}
-    \syntax{$x^*$ ::= $\epsilon$ @! $x^*$ $x$}
+    \syntax{$x^*$ ::= <zero-or-more>$[x]$ ::=
+      $\epsilon$ @! <zero-or-more>$[x]$ $x$}
   \end{quote}
-\item $x^+$ means a sequence of one or more $x$s:
+\item $x^+$ abbreviates @<one-or-more>$[x]$, denoting a sequence of zero or
+  more occurrences of $x$:
   \begin{quote}
-    \syntax{$x^+$ ::= $x$ $x^*$}
+    \syntax{$x^+$ ::= <one-or-more>$[x]$ ::= <zero-or-more>$[x]$ $x$}
   \end{quote}
-\item $x$@<-list> means a sequence of one or more $x$s separated
-  by commas:
+\item @<list>$[x]$ denotes a sequence of one or more occurrences of $x$
+  separated by commas:
   \begin{quote}
-    \syntax{$x$<-list> ::= $x$ @! $x$<-list> "," $x$}
+    \syntax{<list>$[x]$ ::= $x$ @! <list>$[x]$ "," $x$}
   \end{quote}
 \end{itemize}
 
@@ -323,7 +338,7 @@ The @<s-expression> is evaluated immediately.  It can do anything it likes.
 
 \begin{grammar}
 <typename-definition> ::=
-  "typename" <identifier-list> ";"
+  "typename" <list>@[<identifier>@] ";"
 \end{grammar}
 
 Each @<identifier> is declared as naming a C type.  This is important because
@@ -340,7 +355,7 @@ declarations instead.
   "code" <identifier> ":" <identifier> @[<constraints>@]
   "{" <c-fragment> "}"
 
-<constraints> ::= "[" <constraint-list> "]"
+<constraints> ::= "[" <list>@[<constraint>@] "]"
 
 <constraint> ::= @<identifier>^+
 \end{grammar}
@@ -372,7 +387,7 @@ elsewhere in the generated output files.
 \subsection{Property sets} \label{sec:syntax.propset}
 
 \begin{grammar}
-<properties> ::= "[" <property-list> "]"
+<properties> ::= "[" <list>@[<property>@] "]"
 
 <property> ::= <identifier> "=" <expression>
 \end{grammar}
@@ -474,7 +489,7 @@ All of these have their usual C meanings.
 \alt "(" <arguments> ")"
 
 <arguments> ::= $\epsilon$ | "..."
-\alt <argument-list> @["," "..."@]
+\alt <list>@[<argument>@] @["," "..."@]
 
 <argument> ::= @<declaration-specifier>^+ <argument-declarator>
 
@@ -532,13 +547,13 @@ class Sub : Super {
 \begin{grammar}
 <full-class-definition> ::=
   @[<properties>@]
-  "class" <identifier> ":" <identifier-list>
+  "class" <identifier> ":" <list>@[<identifier>@]
   "{" @<class-item>^* "}"
 
 <class-item> ::= <slot-item> ";"
+\alt <initializer-item> ";"
 \alt <message-item>
 \alt <method-item>
-\alt  <initializer-item> ";"
 \end{grammar}
 
 A full class definition provides a complete description of a class.
@@ -548,7 +563,7 @@ give the name of an existing class (other than a forward-referenced class),
 or an existing type name.  It is conventional to give classes `MixedCase'
 names, to distinguish them from other kinds of identifiers.
 
-The @<identifier-list> names the direct superclasses for the new class.  It
+The @<list>@[<identifier>@] names the direct superclasses for the new class.  It
 is an error if any of these @<identifier>s does not name a defined class.
 
 The @<properties> provide additional information.  The standard class
@@ -579,9 +594,9 @@ These items are discussed on the following sections.
 \begin{grammar}
 <slot-item> ::=
   @[<properties>@]
-  @<declaration-specifier>^+ <init-declarator-list>
+  @<declaration-specifier>^+ <list>@[<init-declarator>@]
 
-<init-declarator> ::= <declarator> @["=" <initializer>@]
+<init-declarator> ::= <simple-declarator> @["=" <initializer>@]
 \end{grammar}
 
 A @<slot-item> defines one or more slots.  All instances of the class and any
@@ -614,7 +629,7 @@ class Example : Super {
 \subsubsection{Initializer items} \label{sec:syntax.class.init}
 
 \begin{grammar}
-<initializer-item> ::= @["class"@] <slot-initializer-list>
+<initializer-item> ::= @["class"@] <list>@[<slot-initializer>@]
 
 <slot-initializer> ::= <qualified-identifier> "=" <initializer>