Add a temporary driver to help track down remaining leak(s).

clearing a shallow copy _run_examples() makes itself can't hurt anything.

break cycles, which are a special problem when running generator tests
that provoke exceptions by invoking the .next() method of a named
generator-iterator:  then the iterator is named in globs, and the
iterator's frame gets a tracekback object pointing back to globs, and
gc doesn't chase these types so the cycle leaks.

Also changed _run_examples() to make a copy of globs itself, so its
callers (direct and indirect) don't have to (and changed the callers
to stop making their own copies); *that* much is a change I've been
meaning to make for a long time (it's more robust the new way).

Here's a way to provoke the symptom without doctest; it leaks at a
prodigious rate; if the last two "source" lines are replaced with
    g().next()
the iterator isn't named and then there's no leak:

source = """\
def g():
    yield 1/0

k = g()
k.next()
"""

code = compile(source, "<source>", "exec")

def f(globs):
    try:
        exec code in globs
    except ZeroDivisionError:
        pass

while 1:
    f(globals().copy())

After this change, running test_generators in an infinite loop still leaks,
but reduced from a flood to a trickle.

example (an obvious trackback cycle).  Repaired.
Bugfix candidate.

of other tests.

because it picks up the first line of traceback.format_exception_only()
instead of the last line.  Pick up the last line instead!

Good news:  Some of this stuff is pretty sophisticated (read nuts), and
I haven't bumped into a bug yet.
Bad news:  If I run the doctest in an infinite loop, memory is clearly
leaking.

because I need to make progress and don't have time now to think about
whatever it is the new code is trying to accomplish.

but it's a heck of a good generator exerciser (think about it <wink>).

together.

Contributed by Jun-ichiro "itojun" Hagino. get{addr,name}info emulation
code taken from WIDE.

Iterators list and Python-Dev; e.g., these all pass now:

def g1():
    try:
        return
    except:
        yield 1
assert list(g1()) == []

def g2():
    try:
        return
    finally:
        yield 1
assert list(g2()) == [1]

def g3():
    for i in range(3):
        yield None
    yield None
assert list(g3()) == [None] * 4

compile.c:  compile_funcdef and com_return_stmt:  Just van Rossum's patch
to compile the same code for "return" regardless of function type (this
goes back to the previous scheme of returning Py_None).

ceval.c:  gen_iternext:  take a return (but not a yield) of Py_None as
meaning the generator is exhausted.

chapter number.  This also makes the reference a hyperlink in the HTML
version.

not NULL.  I don't think it can be NULL from Python code, but if using
generators via the C API I expect a NULL frame is possible.

the next free valuestack slot, not to the base (in America, stacks push
and pop at the top -- they mutate at the bottom in Australia <winK>).
eval_frame():  assert that f_stacktop isn't NULL upon entry.
frame_delloc():  avoid ordered pointer comparisons involving f_stacktop
when f_stacktop is NULL.

Fix a very minor (but annoying when looking for things!) markup nit.

cuts for the complex math functions.  Includes a brief description of
what branch cuts are.

standard \textbar macro (not supported in many versions of LaTeX2HTML).

Added newline to error message.

\plusminus:  New macros to allow us to avoid math mode for these symbols.

Make sure we do not lose track of the build directory -- convert a user-
supplied directory to an absolute path.

Derived from Thomas Wouters's patch on the Iterators list, but doesn't
try to read c->c_block[c->c_nblocks].