Merged revisions 67162 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r67162 | benjamin.peterson | 2008-11-08 10:55:33 -0600 (Sat, 08 Nov 2008) | 1 line

  a few compile() and ast doc improvements
........

Doc/library/ast.rst

@@ -15,13 +15,12 @@ abstract syntax grammar.  The abstract syntax itself might change with each
 Python release; this module helps to find out programmatically what the current
 grammar looks like.
 
-An abstract syntax tree can be generated by passing :data:`_ast.PyCF_ONLY_AST`
-as a flag to the :func:`compile` builtin function, or using the :func:`parse`
+An abstract syntax tree can be generated by passing :data:`ast.PyCF_ONLY_AST` as
+a flag to the :func:`compile` builtin function, or using the :func:`parse`
 helper provided in this module.  The result will be a tree of objects whose
-classes all inherit from :class:`ast.AST`.
+classes all inherit from :class:`ast.AST`.  An abstract syntax tree can be
+compiled into a Python code object using the built-in :func:`compile` function.
 
-A modified abstract syntax tree can be compiled into a Python code object using
-the built-in :func:`compile` function.
 
 Node classes
 ------------
@@ -113,7 +112,7 @@ and classes for traversing abstract syntax trees:
 .. function:: parse(expr, filename='<unknown>', mode='exec')
 
    Parse an expression into an AST node.  Equivalent to ``compile(expr,
-   filename, mode, PyCF_ONLY_AST)``.
+   filename, mode, ast.PyCF_ONLY_AST)``.
 
    
 .. function:: literal_eval(node_or_string)

Doc/library/functions.rst

@@ -199,21 +199,20 @@ are always available.  They are listed here in alphabetical order.
 
 .. function:: compile(source, filename, mode[, flags[, dont_inherit]])
 
-   Compile the *source* into a code object or AST object.  Code objects can be
-   executed by a call to :func:`exec` or evaluated by a call to
-   :func:`eval`. *source* can either be a string or an AST object.  Refer to the
-   :mod:`_ast` module documentation for information on how to compile into and
-   from AST objects.
-
-   The *filename* argument should give the file from
-   which the code was read; pass some recognizable value if it wasn't
-   read from a file (``'<string>'`` is commonly used). The *mode*
-   argument specifies what kind of code must be compiled; it can be
-   ``'exec'`` if *source* consists of a sequence of statements,
-   ``'eval'`` if it consists of a single expression, or ``'single'``
-   if it consists of a single interactive statement (in the latter
-   case, expression statements that evaluate to something else than
-   ``None`` will be printed).
+   Compile the *source* into a code or AST object.  Code objects can be executed
+   by an :keyword:`exec` statement or evaluated by a call to :func:`eval`.
+   *source* can either be a string or an AST object.  Refer to the :mod:`ast`
+   module documentation for information on how to work with AST objects.
+
+   The *filename* argument should give the file from which the code was read;
+   pass some recognizable value if it wasn't read from a file (``'<string>'`` is
+   commonly used).
+
+   The *mode* argument specifies what kind of code must be compiled; it can be
+   ``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it
+   consists of a single expression, or ``'single'`` if it consists of a single
+   interactive statement (in the latter case, expression statements that
+   evaluate to something else than ``None`` will be printed).
 
    The optional arguments *flags* and *dont_inherit* control which future
    statements (see :pep:`236`) affect the compilation of *source*.  If neither
@@ -233,6 +232,14 @@ are always available.  They are listed here in alphabetical order.
    This function raises :exc:`SyntaxError` if the compiled source is invalid,
    and :exc:`TypeError` if the source contains null bytes.
 
+   .. note::
+
+      When compiling a string with multi-line statements, line endings must be
+      represented by a single newline character (``'\n'``), and the input must
+      be terminated by at least one newline character.  If line endings are
+      represented by ``'\r\n'``, use :meth:`str.replace` to change them into
+      ``'\n'``.
+
 
 .. function:: complex([real[, imag]])