Merged revisions 62260-62261,62266,62271,62277-62279,62289-62290,62293-62298,62302-62306,62308,62311,62313-62315,62319-62321 via svnmerge from

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

........
  r62260 | gregory.p.smith | 2008-04-10 01:11:56 +0200 (Thu, 10 Apr 2008) | 2 lines

  better diagnostics
........
  r62261 | gregory.p.smith | 2008-04-10 01:16:37 +0200 (Thu, 10 Apr 2008) | 3 lines

  Raise SystemError when size < 0 is passed into PyString_FromStringAndSize,
  PyBytes_FromStringAndSize or PyUnicode_FromStringAndSize.  [issue2587]
........
  r62266 | neal.norwitz | 2008-04-10 07:46:39 +0200 (Thu, 10 Apr 2008) | 5 lines

  Remove the test file before writing it in case there is no write permission.
  This might help fix some of the failures on Windows box(es).  It doesn't hurt
  either way and ensure the tests are a little more self contained (ie have
  less assumptions).
........
  r62271 | gregory.p.smith | 2008-04-10 21:50:36 +0200 (Thu, 10 Apr 2008) | 2 lines

  get rid of assert (size >= 0) now that an explicit if (size < 0) is in the code.
........
  r62277 | andrew.kuchling | 2008-04-10 23:27:10 +0200 (Thu, 10 Apr 2008) | 1 line

  Remove forward-looking statement
........
  r62278 | andrew.kuchling | 2008-04-10 23:28:51 +0200 (Thu, 10 Apr 2008) | 1 line

  Add punctuation
........
  r62279 | andrew.kuchling | 2008-04-10 23:29:01 +0200 (Thu, 10 Apr 2008) | 1 line

  Use issue directive
........
  r62289 | thomas.heller | 2008-04-11 15:05:38 +0200 (Fri, 11 Apr 2008) | 3 lines

  Move backwards compatibility macro to the correct place;
  PyIndex_Check() was introduced in Python 2.5.
........
  r62290 | thomas.heller | 2008-04-11 16:20:26 +0200 (Fri, 11 Apr 2008) | 2 lines

  Performance improvements.
........
  r62293 | christian.heimes | 2008-04-12 15:03:03 +0200 (Sat, 12 Apr 2008) | 2 lines

  Applied patch #2617 from Frank Wierzbicki wit some extras from me
  -J and -X are now reserved for Jython and non-standard arguments (e.g. IronPython). I've added some extra comments to make sure the reservation don't get missed in the future.
........
  r62294 | georg.brandl | 2008-04-12 20:11:18 +0200 (Sat, 12 Apr 2008) | 2 lines

  Use absolute path in sys.path.
........
  r62295 | georg.brandl | 2008-04-12 20:36:09 +0200 (Sat, 12 Apr 2008) | 2 lines

  #2615: small consistency update by Jeroen Ruigrok van der Werven.
........
  r62296 | georg.brandl | 2008-04-12 21:00:20 +0200 (Sat, 12 Apr 2008) | 2 lines

  Add Jeroen.
........
  r62297 | georg.brandl | 2008-04-12 21:05:37 +0200 (Sat, 12 Apr 2008) | 2 lines

  Don't offend snake lovers.
........
  r62298 | gregory.p.smith | 2008-04-12 22:37:48 +0200 (Sat, 12 Apr 2008) | 2 lines

  fix compiler warnings
........
  r62302 | gregory.p.smith | 2008-04-13 00:24:04 +0200 (Sun, 13 Apr 2008) | 3 lines

  socket.error inherits from IOError, it no longer needs listing in
  the all_errors tuple.
........
  r62303 | brett.cannon | 2008-04-13 01:44:07 +0200 (Sun, 13 Apr 2008) | 8 lines

  Re-implement the 'warnings' module in C. This allows for usage of the
  'warnings' code in places where it was previously not possible (e.g., the
  parser). It could also potentially lead to a speed-up in interpreter start-up
  if the C version of the code (_warnings) is imported over the use of the
  Python version in key places.

  Closes issue #1631171.
........
  r62304 | gregory.p.smith | 2008-04-13 02:03:25 +0200 (Sun, 13 Apr 2008) | 3 lines

  Adds a profile-opt target for easy compilation of a python binary using
  gcc's profile guided optimization.
........
  r62305 | brett.cannon | 2008-04-13 02:18:44 +0200 (Sun, 13 Apr 2008) | 3 lines

  Fix a bug in PySys_HasWarnOption() where it was not properly checking the
  length of the list storing the warning options.
........
  r62306 | brett.cannon | 2008-04-13 02:25:15 +0200 (Sun, 13 Apr 2008) | 2 lines

  Fix an accidental bug of an non-existent init function.
........
  r62308 | andrew.kuchling | 2008-04-13 03:05:59 +0200 (Sun, 13 Apr 2008) | 1 line

  Mention -J, -X
........
  r62311 | benjamin.peterson | 2008-04-13 04:20:05 +0200 (Sun, 13 Apr 2008) | 2 lines

  Give the "Interactive Interpreter Changes" section in 2.6 whatsnew a unique link name
........
  r62313 | brett.cannon | 2008-04-13 04:42:36 +0200 (Sun, 13 Apr 2008) | 3 lines

  Fix test_warnings by making the state of things more consistent for each test
  when it is run.
........
  r62314 | skip.montanaro | 2008-04-13 05:17:30 +0200 (Sun, 13 Apr 2008) | 2 lines

  spelling
........
  r62315 | georg.brandl | 2008-04-13 09:07:44 +0200 (Sun, 13 Apr 2008) | 2 lines

  Fix markup.
........
  r62319 | christian.heimes | 2008-04-13 11:30:17 +0200 (Sun, 13 Apr 2008) | 1 line

  Fix compiler warning Include/warnings.h:19:28: warning: no newline at end of file
........
  r62320 | christian.heimes | 2008-04-13 11:33:24 +0200 (Sun, 13 Apr 2008) | 1 line

  Use PyString_InternFromString instead of PyString_FromString for static vars
........
  r62321 | christian.heimes | 2008-04-13 11:37:05 +0200 (Sun, 13 Apr 2008) | 1 line

  Added new files to the pcbuild files
........

1 files changed, 30 insertions, 1 deletions

diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index e149710..a9d534e 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -438,7 +438,36 @@ The :keyword:`yield` statement is only used when defining a generator function,
 and is only used in the body of the generator function. Using a :keyword:`yield`
 statement in a function definition is sufficient to cause that definition to
 create a generator function instead of a normal function.
->>>>>>> .merge-right.r59773
+When a generator function is called, it returns an iterator known as a generator
+iterator, or more commonly, a generator.  The body of the generator function is
+executed by calling the generator's :meth:`next` method repeatedly until it
+raises an exception.
+
+When a :keyword:`yield` statement is executed, the state of the generator is
+frozen and the value of :token:`expression_list` is returned to :meth:`next`'s
+caller.  By "frozen" we mean that all local state is retained, including the
+current bindings of local variables, the instruction pointer, and the internal
+evaluation stack: enough information is saved so that the next time :meth:`next`
+is invoked, the function can proceed exactly as if the :keyword:`yield`
+statement were just another external call.
+
+As of Python version 2.5, the :keyword:`yield` statement is now allowed in the
+:keyword:`try` clause of a :keyword:`try` ...  :keyword:`finally` construct.  If
+the generator is not resumed before it is finalized (by reaching a zero
+reference count or by being garbage collected), the generator-iterator's
+:meth:`close` method will be called, allowing any pending :keyword:`finally`
+clauses to execute.
+
+
+.. seealso::
+
+   :pep:`0255` - Simple Generators
+      The proposal for adding generators and the :keyword:`yield` statement to Python.
+
+   :pep:`0342` - Coroutines via Enhanced Generators
+      The proposal that, among other generator enhancements, proposed allowing
+      :keyword:`yield` to appear inside a :keyword:`try` ... :keyword:`finally` block.
+
 
 .. _raise: