Fix some sentances, add a little info about ceval, remove asdl_seq_APPEND()

pep-0339.txt

@@ -86,7 +86,7 @@ Abstract Syntax Trees (AST)
 
 The abstract syntax tree (AST) is a high-level representation of the
 program structure without the necessity of containing the source code;
-it can be thought of a abstract representation of the source code.  The
+it can be thought of as an abstract representation of the source code.  The
 specification of the AST nodes is specified using the Zephyr Abstract
 Syntax Definition Language (ASDL) [Wang97]_.
 
@@ -188,6 +188,12 @@ As stated above, in general you should not have to worry about memory
 management when working on the compiler.  The technical details have been
 designed to be hidden from you for most cases.
 
+The only exception comes about when managing a PyObject.  Since the rest
+of Python uses reference counting, there is extra support added
+to the arena to cleanup each PyObject that was allocated.  These cases
+are very rare.  However, if you've allocated a PyObject, you must tell
+the arena about it by calling PyArena_AddPyObject().
+
 
 Parse Tree to AST
 -----------------
@@ -204,11 +210,9 @@ Do realize that there is no automated nor symbolic connection between
 the grammar specification and the nodes in the parse tree.  No help is
 directly provided by the parse tree as in yacc.
 
-For instance, one must keep track of
-which node in the parse tree one is working with (e.g., if you are
-working with an 'if' statement you need to watch out for the ':' token
-to find the end of the conditional).  No help is directly provided by
-the parse tree as in yacc.
+For instance, one must keep track of which node in the parse tree
+one is working with (e.g., if you are working with an 'if' statement
+you need to watch out for the ':' token to find the end of the conditional).
 
 The functions called to generate AST nodes from the parse tree all have
 the name ast_for_xx where xx is what the grammar rule that the function
@@ -228,8 +232,6 @@ in Python/asdl.c and Include/asdl.h:
 	Get item held at a specific position in an asdl_seq
 - ``asdl_seq_SET()``
 	Set a specific index in an asdl_seq to the specified value
-- ``asdl_seq_APPEND()``
-	Append a value to the end of an asdl_seq
 - ``asdl_seq_LEN(asdl_seq *)``
 	Return the length of an asdl_seq
 
@@ -320,7 +322,7 @@ VISIT_SLICE() just for handling slices.
 Emission of bytecode is handled by the following macros:
 
 - ``ADDOP()``
-    add a specified opcode.
+    add a specified opcode
 - ``ADDOP_I()``
     add an opcode that takes an argument
 - ``ADDOP_O(struct compiler *c, int op, PyObject *type, PyObject *obj)``
@@ -385,12 +387,13 @@ Lib/opcode.py and Doc/lib/libdis.tex .
 
 With a new bytecode you must also change what is called the magic number for
 .pyc files.  The variable ``MAGIC`` in Python/import.c contains the number.
-Changing this number will lead to 
+Changing this number will lead to all .pyc files with the old MAGIC
+to be recompiled by the interpreter on import.
 
 Finally, you need to introduce the use of the new bytecode.  Altering
-Python/compile.c will be the primary place for changes.  But you will also need
-to change the 'compiler' package.  The key files to do that are
-Lib/compiler/pyassem.py and Lib/compiler/pycodegen.py .
+Python/compile.c and Python/ceval.c will be the primary places to change.
+But you will also need to change the 'compiler' package.  The key files
+to do that are Lib/compiler/pyassem.py and Lib/compiler/pycodegen.py .
 
 If you make a change here that can affect the output of bytecode that
 is already in existence and you do not change the magic number constantly, make
@@ -407,9 +410,13 @@ bytecode properly.
 Code Objects
 ------------
 
-In the end, one ends up with a PyCodeObject which is defined in
+The result of ``PyAST_Compile()`` is a PyCodeObject which is defined in
 Include/code.h .  And with that you now have executable Python bytecode!
 
+The code objects (byte code) is executed in Python/ceval.c .  This file
+will also need a new case statement for the new opcode in the big switch
+statement in PyEval_EvalFrameEx().
+
 
 Important Files
 ---------------
@@ -446,6 +453,9 @@ Important Files
     - ast.c
         Converts Python's parse tree into the abstract syntax tree.
 
+    - ceval.c
+        Executes byte code (aka, eval loop).
+
     - compile.c
         Emits bytecode based on the AST.