Patch #1489771: update syntax rules in Python Reference Manual.

Python 2.5 added support for explicit relative import statements and
yield expressions, which were missing in the manual.
Also fix grammar productions that used the names from the Grammar file,
markup that broke the generated grammar.txt, and wrap some lines that
broke the pdf output.
 (backport from rev. 54559)

Doc/ref/ref1.tex

@@ -93,7 +93,7 @@ grammar notation.  This uses the following style of definition:
 \index{syntax}
 \index{notation}
 
-\begin{productionlist}
+\begin{productionlist}[*]
   \production{name}{\token{lc_letter} (\token{lc_letter} | "_")*}
   \production{lc_letter}{"a"..."z"}
 \end{productionlist}

Doc/ref/ref6.tex

@@ -108,7 +108,8 @@ objects:
 
 \begin{productionlist}
   \production{assignment_stmt}
-             {(\token{target_list} "=")+ \token{expression_list}}
+             {(\token{target_list} "=")+
+              (\token{expression_list} | \token{yield_expression})}
   \production{target_list}
              {\token{target} ("," \token{target})* [","]}
   \production{target}
@@ -273,11 +274,11 @@ operation and an assignment statement:
 
 \begin{productionlist}
   \production{augmented_assignment_stmt}
-             {\token{target} \token{augop} \token{expression_list}}
+             {\token{target} \token{augop}
+              (\token{expression_list} | \token{yield_expression})}
   \production{augop}
              {"+=" | "-=" | "*=" | "/=" | "\%=" | "**="}
-  % The empty groups below prevent conversion to guillemets.
-  \productioncont{| ">{}>=" | "<{}<=" | "\&=" | "\textasciicircum=" | "|="}
+  \productioncont{| ">>=" | "<<=" | "\&=" | "\textasciicircum=" | "|="}
 \end{productionlist}
 
 (See section~\ref{primaries} for the syntax definitions for the last
@@ -376,9 +377,9 @@ right type (but even this is determined by the sliced object).
 
 \begin{productionlist}
   \production{print_stmt}
-             {"print" ( \optional{\token{expression} ("," \token{expression})* \optional{","}}}
+             {"print" ([\token{expression} ("," \token{expression})* [","]}
   \productioncont{| ">>" \token{expression}
-                  \optional{("," \token{expression})+ \optional{","}} )}
+                  [("," \token{expression})+ [","])}
 \end{productionlist}
 
 \keyword{print} evaluates each expression in turn and writes the
@@ -460,7 +461,7 @@ to include an \grammartoken{expression_list}.  In that context, a bare
 
 \begin{productionlist}
   \production{yield_stmt}
-             {"yield" \token{expression_list}}
+             {\token{yield_expression}}
 \end{productionlist}
 
 \index{generator!function}
@@ -630,15 +631,19 @@ It continues with the next cycle of the nearest enclosing loop.
   \production{import_stmt}
              {"import" \token{module} ["as" \token{name}]
                 ( "," \token{module} ["as" \token{name}] )*}
-  \productioncont{| "from" \token{module} "import" \token{identifier}
+  \productioncont{| "from" \token{relative_module} "import" \token{identifier}
                     ["as" \token{name}]}
   \productioncont{  ( "," \token{identifier} ["as" \token{name}] )*}
-  \productioncont{| "from" \token{module} "import" "(" \token{identifier}
-                    ["as" \token{name}]}
+  \productioncont{| "from" \token{relative_module} "import" "("
+                    \token{identifier} ["as" \token{name}]}
   \productioncont{  ( "," \token{identifier} ["as" \token{name}] )* [","] ")"}
   \productioncont{| "from" \token{module} "import" "*"}
   \production{module}
              {(\token{identifier} ".")* \token{identifier}}
+  \production{relative_module}
+             {"."* \token{module} | "."+}
+  \production{name}
+             {\token{identifier}}
 \end{productionlist}
 
 Import statements are executed in two steps: (1) find a module, and
@@ -757,8 +762,10 @@ before the release in which the feature becomes standard.
 
 \begin{productionlist}[*]
   \production{future_statement}
-             {"from" "__future__" "import" feature ["as" name] ("," feature ["as" name])*}
-  \productioncont{| "from" "__future__" "import" "(" feature ["as" name] ("," feature ["as" name])* [","] ")"}
+             {"from" "__future__" "import" feature ["as" name]}
+  \productioncont{  ("," feature ["as" name])*}
+  \productioncont{| "from" "__future__" "import" "(" feature ["as" name]}
+  \productioncont{  ("," feature ["as" name])* [","] ")"}
   \production{feature}{identifier}
   \production{name}{identifier}
 \end{productionlist}
@@ -775,9 +782,10 @@ lines that can appear before a future statement are:
 
 \end{itemize}
 
-The features recognized by Python 2.3 are \samp{generators},
-\samp{division} and \samp{nested_scopes}.  \samp{generators} and
-\samp{nested_scopes} are redundant in 2.3 because they are always
+The features recognized by Python 2.5 are \samp{absolute_import},
+\samp{division}, \samp{generators}, \samp{nested_scopes} and
+\samp{with_statement}.  \samp{generators} and \samp{nested_scopes} 
+are redundant in Python version 2.3 and above because they are always
 enabled. 
 
 A future statement is recognized and treated specially at compile
@@ -872,7 +880,7 @@ containing the \keyword{exec} statement.  The same applies to the
 
 \begin{productionlist}
   \production{exec_stmt}
-             {"exec" \token{expression}
+             {"exec" \token{or_expr}
               ["in" \token{expression} ["," \token{expression}]]}
 \end{productionlist}
 
@@ -916,3 +924,5 @@ for use by \keyword{exec}.
 
   
 
+
+

Doc/ref/ref7.tex

@@ -319,7 +319,7 @@ be encapsulated for convenient reuse.
 
 \begin{productionlist}
   \production{with_stmt}
-  {"with" \token{expression} ["as" target] ":" \token{suite}}
+  {"with" \token{expression} ["as" \token{target}] ":" \token{suite}}
 \end{productionlist}
 
 The execution of the \keyword{with} statement proceeds as follows:

Misc/NEWS

@@ -452,6 +452,9 @@ Windows
 Documentation
 -------------
 
+- Patch #1489771: the syntax rules in Python Reference Manual were
+  updated to reflect the current Python syntax.
+
 - Patch #1686451: Fix return type for
   PySequence_{Count,Index,Fast_GET_SIZE}.