[3.9] bpo-40939: Use the new grammar for the grammar specification documentation (GH-19969) (#21641)
(We censor the heck out of actions and some other stuff using a custom "highlighter".)
(cherry picked from commit 72cabb2aa636272e608285f5a6ba83b62be9be4e)
Co-authored-by: Pablo Galindo <Pablogsal@gmail.com>
diff --git a/Doc/reference/grammar.rst b/Doc/reference/grammar.rst
index 83d0f85..acf8376 100644
--- a/Doc/reference/grammar.rst
+++ b/Doc/reference/grammar.rst
@@ -1,7 +1,19 @@
Full Grammar specification
==========================
-This is the full Python grammar, as it is read by the parser generator and used
-to parse Python source files:
+This is the full Python grammar, derived directly from the grammar
+used to generate the CPython parser (see :source:`Grammar/python.gram`).
+The version here omits details related to code generation and
+error recovery.
-.. literalinclude:: ../../Grammar/Grammar
+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).
+
+.. literalinclude:: ../../Grammar/python.gram
+ :language: peg