[Python-checkins] devguide: Move PEP 306 to here.

[brett.cannon]

brett.cannon pushed e9b11c83b6a6 to devguide:

http://hg.python.org/devguide/rev/e9b11c83b6a6
changeset:   115:e9b11c83b6a6
tag:         tip
user:        Brett Cannon <brett at python.org>
date:        Mon Jan 17 16:29:24 2011 -0800
summary:
  Move PEP 306 to here.

files:
  grammar.rst
  index.rst

diff --git a/grammar.rst b/grammar.rst
new file mode 100644
--- /dev/null
+++ b/grammar.rst
@@ -0,0 +1,74 @@
+.. _grammar:
+
+Changing CPython's Grammar
+==========================
+
+Abstract
+--------
+
+There's more to changing Python's grammar than editing
+Grammar/Grammar and Python/compile.c.  This PEP aims to be a
+checklist of places that must also be fixed.
+
+It is probably incomplete.  If you see omissions, just add them if
+you can -- you are not going to offend the author's sense of
+ownership.  Otherwise submit a bug or patch and assign it to mwh.
+
+This PEP is not intended to be an instruction manual on Python
+grammar hacking, for several reasons.
+
+
+Rationale
+---------
+
+People are getting this wrong all the time; it took well over a
+year before someone `noticed <How to Change Python's Grammar>`_
+that adding the floor division
+operator (//) broke the parser module.
+
+
+Checklist
+---------
+
+* Grammar/Grammar: OK, you'd probably worked this one out :)
+
+* Parser/Python.asdl may need changes to match the Grammar.  Run make to
+  regenerate Include/Python-ast.h and Python/Python-ast.c.
+
+* Python/ast.c will need changes to create the AST objects involved with the
+  Grammar change.  Lib/compiler/ast.py will need matching changes to the
+  pure-python AST objects.
+
+* Parser/pgen needs to be rerun to regenerate Include/graminit.h and
+  Python/graminit.c. (make should handle this for you.)
+
+* Python/symbtable.c: This handles the symbol collection pass
+  that happens immediately before the compilation pass.
+
+* Python/compile.c: You will need to create or modify the
+  compiler_* functions to generate opcodes for your productions.
+
+* You may need to regenerate Lib/symbol.py and/or Lib/token.py
+  and/or Lib/keyword.py.
+
+* The parser module.  Add some of your new syntax to test_parser,
+  bang on Modules/parsermodule.c until it passes.
+
+* Add some usage of your new syntax to test_grammar.py
+
+* The compiler package.  A good test is to compile the standard
+  library and test suite with the compiler package and then check
+  it runs.  Note that this only needs to be done in Python 2.x.
+
+* If you've gone so far as to change the token structure of
+  Python, then the Lib/tokenizer.py library module will need to be changed.
+
+* Certain changes may require tweaks to the library module pyclbr.
+
+* Documentation must be written!
+
+* After everything's been checked in, you're likely to see a new
+  change to Python/Python-ast.c.  This is because this
+  (generated) file contains the SVN version of the source from
+  which it was generated.  There's no way to avoid this; you just
+  have to submit this file separately.
diff --git a/index.rst b/index.rst
--- a/index.rst
+++ b/index.rst
@@ -21,6 +21,8 @@
    stdlibchanges
    langchanges
 
+   grammar
+
 
 .. todolist::
 
@@ -74,6 +76,8 @@
 * Source code
     * `Browse online <http://svn.python.org/view/>`_
     * `Daily snapshot <http://svn.python.org/snapshots/>`_
+* Help with ...
+    * :ref:`grammar`
 
 
 .. _buildbots: http://python.org/dev/buildbot/

--
Repository URL: http://hg.python.org/devguide