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
........

1 files changed, 22 insertions, 15 deletions

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index c2af1e8..e885c3b 100644
--- a/Doc/library/functions.rst
+++ b/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]])