Change the grammar productions to use the new productionlist environment;

this supports a hyperlinked version of the grammar that can make tracking
down details and definitions a little easier.

Doc/ref/ref2.tex

@@ -237,13 +237,18 @@ lexical definitions:
 \index{identifier}
 \index{name}
 
-\begin{verbatim}
-identifier:     (letter|"_") (letter|digit|"_")*
-letter:         lowercase | uppercase
-lowercase:      "a"..."z"
-uppercase:      "A"..."Z"
-digit:          "0"..."9"
-\end{verbatim}
+\begin{productionlist}
+  \production{identifier}
+             {(\token{letter}|"_") (\token{letter} | \token{digit} | "_")*}
+  \production{letter}
+             {\token{lowercase} | \token{uppercase}}
+  \production{lowercase}
+             {"a"..."z"}
+  \production{uppercase}
+             {"A"..."Z"}
+  \production{digit}
+             {"0"..."9"}
+\end{productionlist}
 
 Identifiers are unlimited in length.  Case is significant.
 
@@ -303,17 +308,27 @@ Literals are notations for constant values of some built-in types.
 String literals are described by the following lexical definitions:
 \index{string literal}
 
-\begin{verbatim}
-stringliteral:   shortstring | longstring
-shortstring:     "'" shortstringitem* "'" | '"' shortstringitem* '"'
-longstring:      "'''" longstringitem* "'''" | '"""' longstringitem* '"""'
-shortstringitem: shortstringchar | escapeseq
-longstringitem:  longstringchar | escapeseq
-shortstringchar: <any ASCII character except "\" or newline or the quote>
-longstringchar:  <any ASCII character except "\">
-escapeseq:       "\" <any ASCII character>
-\end{verbatim}
 \index{ASCII@\ASCII{}}
+\begin{productionlist}
+  \production{stringliteral}
+             {\token{shortstring} | \token{longstring}}
+  \production{shortstring}
+             {"'" \token{shortstringitem}* "'"
+              | '"' \token{shortstringitem}* '"'}
+  \production{longstring}
+             {"'''" \token{longstringitem}* "'''"
+              | '"""' \token{longstringitem}* '"""'}
+  \production{shortstringitem}
+             {\token{shortstringchar} | \token{escapeseq}}
+  \production{longstringitem}
+             {\token{longstringchar} | \token{escapeseq}}
+  \production{shortstringchar}
+             {<any ASCII character except "\e" or newline or the quote>}
+  \production{longstringchar}
+             {<any ASCII character except "\e">}
+  \production{escapeseq}
+             {"\e" <any ASCII character>}
+\end{productionlist}
 
 \index{triple-quoted string}
 \index{Unicode Consortium}
@@ -452,16 +467,24 @@ Note that numeric literals do not include a sign; a phrase like
 Integer and long integer literals are described by the following
 lexical definitions:
 
-\begin{verbatim}
-longinteger:    integer ("l"|"L")
-integer:        decimalinteger | octinteger | hexinteger
-decimalinteger: nonzerodigit digit* | "0"
-octinteger:     "0" octdigit+
-hexinteger:     "0" ("x"|"X") hexdigit+
-nonzerodigit:   "1"..."9"
-octdigit:       "0"..."7"
-hexdigit:        digit|"a"..."f"|"A"..."F"
-\end{verbatim}
+\begin{productionlist}
+  \production{longinteger}
+             {\token{integer} ("l" | "L")}
+  \production{integer}
+             {\token{decimalinteger} | \token{octinteger} | \token{hexinteger}}
+  \production{decimalinteger}
+             {\token{nonzerodigit} \token{digit}* | "0"}
+  \production{octinteger}
+             {"0" \token{octdigit}+}
+  \production{hexinteger}
+             {"0" ("x" | "X") \token{hexdigit}+}
+  \production{nonzerodigit}
+             {"1"..."9"}
+  \production{octdigit}
+             {"0"..."7"}
+  \production{hexdigit}
+             {\token{digit} | "a"..."f" | "A"..."F"}
+\end{productionlist}
 
 Although both lower case `l' and upper case `L' are allowed as suffix
 for long integers, it is strongly recommended to always use `L', since
@@ -487,14 +510,21 @@ Some examples of plain and long integer literals:
 Floating point literals are described by the following lexical
 definitions:
 
-\begin{verbatim}
-floatnumber:    pointfloat | exponentfloat
-pointfloat:     [intpart] fraction | intpart "."
-exponentfloat:  (nonzerodigit digit* | pointfloat) exponent
-intpart:        nonzerodigit digit* | "0"
-fraction:       "." digit+
-exponent:       ("e"|"E") ["+"|"-"] digit+
-\end{verbatim}
+\begin{productionlist}
+  \production{floatnumber}
+             {\token{pointfloat} | \token{exponentfloat}}
+  \production{pointfloat}
+             {[\token{intpart}] \token{fraction} | \token{intpart} "."}
+  \production{exponentfloat}
+             {(\token{nonzerodigit} \token{digit}* | \token{pointfloat})
+              \token{exponent}}
+  \production{intpart}
+             {\token{nonzerodigit} \token{digit}* | "0"}
+  \production{fraction}
+             {"." \token{digit}+}
+  \production{exponent}
+             {("e" | "E") ["+" | "-"] \token{digit}+}
+\end{productionlist}
 
 Note that the integer part of a floating point number cannot look like
 an octal integer, though the exponent may look like an octal literal
@@ -517,9 +547,9 @@ Note that numeric literals do not include a sign; a phrase like
 
 Imaginary literals are described by the following lexical definitions:
 
-\begin{verbatim}
-imagnumber:     (floatnumber | intpart) ("j"|"J")
-\end{verbatim}
+\begin{productionlist}
+  \production{imagnumber}{(\token{floatnumber} | \token{intpart}) ("j" | "J")}
+\end{productionlist}
 
 An imaginary literal yields a complex number with a real part of
 0.0.  Complex numbers are represented as a pair of floating point

Doc/ref/ref7.tex

@@ -40,13 +40,18 @@ if x < y < z: print x; print y; print z
 
 Summarizing:
 
-\begin{verbatim}
-compound_stmt:  if_stmt | while_stmt | for_stmt
-              | try_stmt | funcdef | classdef
-suite:          stmt_list NEWLINE | NEWLINE INDENT statement+ DEDENT
-statement:      stmt_list NEWLINE | compound_stmt
-stmt_list:      simple_stmt (";" simple_stmt)* [";"]
-\end{verbatim}
+\begin{productionlist}
+  \production{compound_stmt}
+             {\token{if_stmt} | \token{while_stmt} | \token{for_stmt}
+              | \token{try_stmt} | \token{funcdef} | \token{classdef}}
+  \production{suite}
+             {\token{stmt_list} NEWLINE
+              | NEWLINE INDENT \token{statement}+ DEDENT}
+  \production{statement}
+             {\token{stmt_list} NEWLINE | \token{compound_stmt}}
+  \production{stmt_list}
+             {\token{simple_stmt} (";" \token{simple_stmt})* [";"]}
+\end{productionlist}
 
 Note that statements always end in a
 \code{NEWLINE}\index{NEWLINE token} possibly followed by a
@@ -66,11 +71,12 @@ each clause on a separate line for clarity.
 
 The \keyword{if} statement is used for conditional execution:
 
-\begin{verbatim}
-if_stmt:        "if" expression ":" suite
-               ("elif" expression ":" suite)*
-               ["else" ":" suite]
-\end{verbatim}
+\begin{productionlist}
+  \production{if_stmt}
+             {"if" \token{expression} ":" \token{suite}
+              ( "elif" \token{expression} ":" \token{suite} )*
+              ["else" ":" \token{suite}]}
+\end{productionlist}
 
 It selects exactly one of the suites by evaluating the expressions one
 by one until one is found to be true (see section \ref{Booleans} for
@@ -89,10 +95,11 @@ present, is executed.
 The \keyword{while} statement is used for repeated execution as long
 as an expression is true:
 
-\begin{verbatim}
-while_stmt:     "while" expression ":" suite
-               ["else" ":" suite]
-\end{verbatim}
+\begin{productionlist}
+  \production{while_stmt}
+             {"while" \token{expression} ":" \token{suite}
+               ["else" ":" \token{suite}]}
+\end{productionlist}
 
 This repeatedly tests the expression and, if it is true, executes the
 first suite; if the expression is false (which may be the first time it
@@ -116,10 +123,12 @@ The \keyword{for} statement is used to iterate over the elements of a
 sequence (such as a string, tuple or list) or other iterable object:
 \obindex{sequence}
 
-\begin{verbatim}
-for_stmt:       "for" target_list "in" expression_list ":" suite
-               ["else" ":" suite]
-\end{verbatim}
+\begin{productionlist}
+  \production{for_stmt}
+             {"for" \token{target_list} "in" \token{expression_list}
+              ":" \token{suite}
+              ["else" ":" \token{suite}]}
+\end{productionlist}
 
 The expression list is evaluated once; it should yield a sequence.  The
 suite is then executed once for each item in the sequence, in the
@@ -179,14 +188,18 @@ for x in a[:]:
 The \keyword{try} statement specifies exception handlers and/or cleanup
 code for a group of statements:
 
-\begin{verbatim}
-try_stmt:       try_exc_stmt | try_fin_stmt
-try_exc_stmt:   "try" ":" suite
-               ("except" [expression ["," target]] ":" suite)+
-               ["else" ":" suite]
-try_fin_stmt:   "try" ":" suite
-                "finally" ":" suite
-\end{verbatim}
+\begin{productionlist}
+  \production{try_stmt}
+             {\token{try_exc_stmt} | \token{try_fin_stmt}}
+  \production{try_exc_stmt}
+             {"try" ":" \token{suite}
+              ("except" [\token{expression} ["," \token{target}]] ":"
+              \token{suite})+
+              ["else" ":" \token{suite}]}
+  \production{try_fin_stmt}
+             {"try" ":" \token{suite}
+              "finally" ":" \token{suite}}
+\end{productionlist}
 
 There are two forms of \keyword{try} statement:
 \keyword{try}...\keyword{except} and
@@ -291,16 +304,24 @@ section \ref{types}):
 \obindex{user-defined function}
 \obindex{function}
 
-\begin{verbatim}
-funcdef:        "def" funcname "(" [parameter_list] ")" ":" suite
-parameter_list: (defparameter ",")* ("*" identifier [, "**" identifier] 
-                                    | "**" identifier 
-                                    | defparameter [","])
-defparameter:   parameter ["=" expression]
-sublist:        parameter ("," parameter)* [","]
-parameter:      identifier | "(" sublist ")"
-funcname:       identifier
-\end{verbatim}
+\begin{productionlist}
+  \production{funcdef}
+             {"def" \token{funcname} "(" [\token{parameter_list}] ")"
+              ":" \token{suite}}
+  \production{parameter_list}
+             {(\token{defparameter} ",")*
+              ("*" \token{identifier} [, "**" \token{identifier}]
+               | "**" \token{identifier}
+               | \token{defparameter} [","])}
+  \production{defparameter}
+             {\token{parameter} ["=" \token{expression}]}
+  \production{sublist}
+             {\token{parameter} ("," \token{parameter})* [","]}
+  \production{parameter}
+             {\token{identifier} | "(" \token{sublist} ")"}
+  \production{funcname}
+             {\token{identifier}}
+\end{productionlist}
 
 A function definition is an executable statement.  Its execution binds
 the function name in the current local namespace to a function object
@@ -376,11 +397,15 @@ description of the new semantics.
 A class definition defines a class object (see section \ref{types}):
 \obindex{class}
 
-\begin{verbatim}
-classdef:       "class" classname [inheritance] ":" suite
-inheritance:    "(" [expression_list] ")"
-classname:      identifier
-\end{verbatim}
+\begin{productionlist}
+  \production{classdef}
+             {"class" \token{classname} [\token{inheritance}] ":"
+              \token{suite}}
+  \production{inheritance}
+             {"(" [\token{expression_list}] ")"}
+  \production{classname}
+             {\token{identifier}}
+\end{productionlist}
 
 A class definition is an executable statement.  It first evaluates the
 inheritance list, if present.  Each item in the inheritance list

Doc/ref/ref8.tex

@@ -49,9 +49,10 @@ program.
 
 All input read from non-interactive files has the same form:
 
-\begin{verbatim}
-file_input:     (NEWLINE | statement)*
-\end{verbatim}
+\begin{productionlist}
+  \production{file_input}
+             {(NEWLINE | \token{statement})*}
+\end{productionlist}
 
 This syntax is used in the following situations:
 
@@ -70,9 +71,10 @@ This syntax is used in the following situations:
 
 Input in interactive mode is parsed using the following grammar:
 
-\begin{verbatim}
-interactive_input: [stmt_list] NEWLINE | compound_stmt NEWLINE
-\end{verbatim}
+\begin{productionlist}
+  \production{interactive_input}
+             {[\token{stmt_list}] NEWLINE | \token{compound_stmt} NEWLINE}
+\end{productionlist}
 
 Note that a (top-level) compound statement must be followed by a blank
 line in interactive mode; this is needed to help the parser detect the
@@ -87,16 +89,18 @@ whitespace.
 The string argument to \function{eval()} must have the following form:
 \bifuncindex{eval}
 
-\begin{verbatim}
-eval_input:     expression_list NEWLINE*
-\end{verbatim}
+\begin{productionlist}
+  \production{eval_input}
+             {\token{expression_list} NEWLINE*}
+\end{productionlist}
 
 The input line read by \function{input()} must have the following form:
 \bifuncindex{input}
 
-\begin{verbatim}
-input_input:    expression_list NEWLINE
-\end{verbatim}
+\begin{productionlist}
+  \production{input_input}
+             {\token{expression_list} NEWLINE}
+\end{productionlist}
 
 Note: to read `raw' input line without interpretation, you can use the
 built-in function \function{raw_input()} or the \method{readline()} method