Consolidate with the Full Grammar intro

encukou · blaisep · encukou · commit ec90d4066987 · 2025-05-21T18:06:29.000+02:00
Co-authored-by: Blaise Pabon &lt;blaise@gmail.com&gt;
diff --git a/Doc/reference/grammar.rst b/Doc/reference/grammar.rst
@@ -8,15 +8,13 @@ used to generate the CPython parser (see :source:`Grammar/python.gram`).
 The version here omits details related to code generation and
 error recovery.
 
-The notation is a mixture of `EBNF
-<https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form>`_
-and `PEG <https://en.wikipedia.org/wiki/Parsing_expression_grammar>`_.
-In particular, ``&`` followed by a symbol, token or parenthesized
-group indicates a positive lookahead (i.e., is required to match but
-not consumed), while ``!`` indicates a negative lookahead (i.e., is
-required *not* to match).  We use the ``|`` separator to mean PEG's
-"ordered choice" (written as ``/`` in traditional PEG grammars). See
-:pep:`617` for more details on the grammar's syntax.
+The notation used here is the same as in the preceding docs,
+and is described in the :ref:`notation <notation>` section,
+except for a few extra complications:
+
+* ``&e``: a positive lookahead (that is, ``e`` is required to match but
+  not consumed)
+* ``!e``: a negative lookahead (that is, ``e`` is required *not* to match)
 
 .. literalinclude:: ../../Grammar/python.gram
   :language: peg
diff --git a/Doc/reference/introduction.rst b/Doc/reference/introduction.rst
@@ -90,9 +90,10 @@ Notation
 
 .. index:: BNF, grammar, syntax, notation
 
-The descriptions of lexical analysis and syntax use a modified
-`Backus–Naur form (BNF) <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ grammar
-notation.  This uses the following style of definition:
+The descriptions of lexical analysis use a grammar notation that is a mixture
+of `EBNF <https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form>`_
+and `PEG <https://en.wikipedia.org/wiki/Parsing_expression_grammar>`_.
+For example:
 
 .. grammar-snippet::
    :group: notation
@@ -136,7 +137,11 @@ The definition to the right of the colon uses the following syntax elements:
 * ``e1 e2``: Items separated only by whitespace denote a sequence.
   Here, ``e1`` must be followed by ``e2``.
 * ``e1 | e2``: A vertical bar is used to separate alternatives.
-  It is the least tightly binding operator in this notation.
+  It denotes PEG's "ordered choice": if ``e1`` matches, ``e2`` is
+  not considered.
+  In traditional PEG grammars, this is written as a slash, ``/``, rather than
+  a vertical bar.
+  See :pep:`617` for more background and details.
 * ``e*``: A star means zero or more repetitions of the preceding item.
 * ``e+``: Likewise, a plus means one or more repetitions.
 * ``[e]``: A phrase enclosed in square brackets means zero or
@@ -145,7 +150,8 @@ The definition to the right of the colon uses the following syntax elements:
   the preceding item is optional.
 * ``(e)``: Parentheses are used for grouping.
 
-The unary operators (``*``, ``+``, ``?``) bind as tightly as possible.
+The unary operators (``*``, ``+``, ``?``) bind as tightly as possible;
+the vertical bar (``|``) binds most loosely.
 
 White space is only meaningful to separate tokens.
 
