Merged revisions 59259-59274 via svnmerge from

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

........
  r59260 | lars.gustaebel | 2007-12-01 22:02:12 +0100 (Sat, 01 Dec 2007) | 5 lines

  Issue #1531: Read fileobj from the current offset, do not seek to
  the start.

  (will backport to 2.5)
........
  r59262 | georg.brandl | 2007-12-01 23:24:47 +0100 (Sat, 01 Dec 2007) | 4 lines

  Document PyEval_* functions from ceval.c.

  Credits to Michael Sloan from GHOP.
........
  r59263 | georg.brandl | 2007-12-01 23:27:56 +0100 (Sat, 01 Dec 2007) | 2 lines

  Add a few refcount data entries.
........
  r59264 | georg.brandl | 2007-12-01 23:38:48 +0100 (Sat, 01 Dec 2007) | 4 lines

  Add test suite for cmd module.

  Written by Michael Schneider for GHOP.
........
  r59265 | georg.brandl | 2007-12-01 23:42:46 +0100 (Sat, 01 Dec 2007) | 3 lines

  Add examples to the ElementTree documentation.
  Written by h4wk.cz for GHOP.
........
  r59266 | georg.brandl | 2007-12-02 00:12:45 +0100 (Sun, 02 Dec 2007) | 3 lines

  Add "Using Python on Windows" document, by Robert Lehmann.
  Written for GHOP.
........
  r59271 | georg.brandl | 2007-12-02 15:34:34 +0100 (Sun, 02 Dec 2007) | 3 lines

  Add example to mmap docs.
  Written for GHOP by Rafal Rawicki.
........
  r59272 | georg.brandl | 2007-12-02 15:37:29 +0100 (Sun, 02 Dec 2007) | 2 lines

  Convert bdb.rst line endings to Unix style.
........
  r59274 | georg.brandl | 2007-12-02 15:58:50 +0100 (Sun, 02 Dec 2007) | 4 lines

  Add more entries to the glossary.

  Written by Jeff Wheeler for GHOP.
........

16 files changed, 508 insertions, 392 deletions

diff --git a/Doc/library/atexit.rst b/Doc/library/atexit.rst
index f6c76de..abef2fe 100644
--- a/Doc/library/atexit.rst
+++ b/Doc/library/atexit.rst
@@ -88,7 +88,7 @@ passed along to the registered function when it is called::
    # or:
    atexit.register(goodbye, adjective='nice', name='Donny')
 
-Usage as a decorator::
+Usage as a :term:`decorator`::
 
    import atexit
 
diff --git a/Doc/library/bdb.rst b/Doc/library/bdb.rst
index da5357b..a8a61f1 100644
--- a/Doc/library/bdb.rst
+++ b/Doc/library/bdb.rst
@@ -1,337 +1,337 @@
-:mod:`bdb` --- Debugger framework

-=================================

-

-.. module:: bdb

-   :synopsis: Debugger framework.

-

-The :mod:`bdb` module handles basic debugger functions, like setting breakpoints

-or managing execution via the debugger.

-

-The following exception is defined:

-

-.. exception:: BdbQuit

-

-   Exception raised by the :class:`Bdb` class for quitting the debugger.

-

-

-The :mod:`bdb` module also defines two classes:

-

-.. class:: Breakpoint(self, file, line[, temporary=0[, cond=None [, funcname=None]]])

-

-   This class implements temporary breakpoints, ignore counts, disabling and

-   (re-)enabling, and conditionals.

-

-   Breakpoints are indexed by number through a list called :attr:`bpbynumber`

-   and by ``(file, line)`` pairs through :attr:`bplist`.  The former points to a

-   single instance of class :class:`Breakpoint`.  The latter points to a list of

-   such instances since there may be more than one breakpoint per line.

-

-   When creating a breakpoint, its associated filename should be in canonical

-   form.  If a *funcname* is defined, a breakpoint hit will be counted when the

-   first line of that function is executed.  A conditional breakpoint always

-   counts a hit.

-

-:class:`Breakpoint` instances have the following methods:

-

-.. method:: Breakpoint.deleteMe()

-

-   Delete the breakpoint from the list associated to a file/line.  If it is the

-   last breakpoint in that position, it also deletes the entry for the

-   file/line.

-

-.. method:: Breakpoint.enable()

-

-   Mark the breakpoint as enabled.

-

-.. method:: Breakpoint.disable()

-

-   Mark the breakpoint as disabled.

-

-.. method:: Breakpoint.bpprint([out])

-

-   Print all the information about the breakpoint:

-

-   * The breakpoint number.

-   * If it is temporary or not.

-   * Its file,line position.

-   * The condition that causes a break.

-   * If it must be ignored the next N times.

-   * The breakpoint hit count.

-

-

-.. class:: Bdb()

-

-   The :class:`Bdb` acts as a generic Python debugger base class.

-

-   This class takes care of the details of the trace facility; a derived class

-   should implement user interaction.  The standard debugger class

-   (:class:`pdb.Pdb`) is an example.

-

-

-The following methods of :class:`Bdb` normally don't need to be overridden.

-

-.. method:: Bdb.canonic(filename)

-

-   Auxiliary method for getting a filename in a canonical form, that is, as a

-   case-normalized (on case-insensitive filesystems) absolute path, stripped

-   of surrounding angle brackets.

-

-.. method:: Bdb.reset()

-

-   Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and

-   :attr:`quitting` attributes with values ready to start debugging.

-

-

-.. method:: Bdb.trace_dispatch(frame, event, arg)

-

-   This function is installed as the trace function of debugged frames.  Its

-   return value is the new trace function (in most cases, that is, itself).

-

-   The default implementation decides how to dispatch a frame, depending on the

-   type of event (passed as a string) that is about to be executed.  *event* can

-   be one of the following:

-

-   * ``"line"``: A new line of code is going to be executed.

-   * ``"call"``: A function is about to be called, or another code block

-     entered.

-   * ``"return"``: A function or other code block is about to return.

-   * ``"exception"``: An exception has occurred.

-   * ``"c_call"``: A C function is about to be called.

-   * ``"c_return"``: A C function has returned.

-   * ``"c_exception"``: A C function has thrown an exception.

-

-   For the Python events, specialized functions (see below) are called.  For the

-   C events, no action is taken.

-

-   The *arg* parameter depends on the previous event.

-

-   For more information on trace functions, see :ref:`debugger-hooks`.  For more

-   information on code and frame objects, refer to :ref:`types`.

-

-.. method:: Bdb.dispatch_line(frame)

-

-   If the debugger should stop on the current line, invoke the :meth:`user_line`

-   method (which should be overridden in subclasses).  Raise a :exc:`BdbQuit`

-   exception if the :attr:`Bdb.quitting` flag is set (which can be set from

-   :meth:`user_line`).  Return a reference to the :meth:`trace_dispatch` method

-   for further tracing in that scope.

-

-.. method:: Bdb.dispatch_call(frame, arg)

-

-   If the debugger should stop on this function call, invoke the

-   :meth:`user_call` method (which should be overridden in subclasses).  Raise a

-   :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can

-   be set from :meth:`user_call`).  Return a reference to the

-   :meth:`trace_dispatch` method for further tracing in that scope.

-

-.. method:: Bdb.dispatch_return(frame, arg)

-

-   If the debugger should stop on this function return, invoke the

-   :meth:`user_return` method (which should be overridden in subclasses).  Raise

-   a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can

-   be set from :meth:`user_return`).  Return a reference to the

-   :meth:`trace_dispatch` method for further tracing in that scope.

-

-.. method:: Bdb.dispatch_exception(frame, arg)

-

-   If the debugger should stop at this exception, invokes the

-   :meth:`user_exception` method (which should be overridden in subclasses).

-   Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set

-   (which can be set from :meth:`user_exception`).  Return a reference to the

-   :meth:`trace_dispatch` method for further tracing in that scope.

-

-Normally derived classes don't override the following methods, but they may if

-they want to redefine the definition of stopping and breakpoints.

-

-.. method:: Bdb.stop_here(frame)

-

-   This method checks if the *frame* is somewhere below :attr:`botframe` in the

-   call stack.  :attr:`botframe` is the frame in which debugging started.

-

-.. method:: Bdb.break_here(frame)

-

-   This method checks if there is a breakpoint in the filename and line

-   belonging to *frame* or, at least, in the current function.  If the

-   breakpoint is a temporary one, this method deletes it.

-

-.. method:: Bdb.break_anywhere(frame)

-

-   This method checks if there is a breakpoint in the filename of the current

-   frame.

-

-Derived classes should override these methods to gain control over debugger

-operation.

-

-.. method:: Bdb.user_call(frame, argument_list)

-

-   This method is called from :meth:`dispatch_call` when there is the

-   possibility that a break might be necessary anywhere inside the called

-   function.

-

-.. method:: Bdb.user_line(frame)

-

-   This method is called from :meth:`dispatch_line` when either

-   :meth:`stop_here` or :meth:`break_here` yields True.

-

-.. method:: Bdb.user_return(frame, return_value)

-

-   This method is called from :meth:`dispatch_return` when :meth:`stop_here`

-   yields True.

-

-.. method:: Bdb.user_exception(frame, exc_info)

-

-   This method is called from :meth:`dispatch_exception` when :meth:`stop_here`

-   yields True.

-

-.. method:: Bdb.do_clear(arg)

-

-   Handle how a breakpoint must be removed when it is a temporary one.

-

-   This method must be implemented by derived classes.

-

-

-Derived classes and clients can call the following methods to affect the 

-stepping state.

-

-.. method:: Bdb.set_step()

-

-   Stop after one line of code.

-

-.. method:: Bdb.set_next(frame)

-

-   Stop on the next line in or below the given frame.

-

-.. method:: Bdb.set_return(frame)

-

-   Stop when returning from the given frame.

-

-.. method:: Bdb.set_trace([frame])

-

-   Start debugging from *frame*.  If *frame* is not specified, debugging starts

-   from caller's frame.

-

-.. method:: Bdb.set_continue()

-

-   Stop only at breakpoints or when finished.  If there are no breakpoints, set

-   the system trace function to None.

-

-.. method:: Bdb.set_quit()

-

-   Set the :attr:`quitting` attribute to True.  This raises :exc:`BdbQuit` in

-   the next call to one of the :meth:`dispatch_\*` methods.

-

-

-Derived classes and clients can call the following methods to manipulate

-breakpoints.  These methods return a string containing an error message if

-something went wrong, or ``None`` if all is well.

-

-.. method:: Bdb.set_break(filename, lineno[, temporary=0[, cond[, funcname]]])

-

-   Set a new breakpoint.  If the *lineno* line doesn't exist for the *filename*

-   passed as argument, return an error message.  The *filename* should be in

-   canonical form, as described in the :meth:`canonic` method.

-

-.. method:: Bdb.clear_break(filename, lineno)

-

-   Delete the breakpoints in *filename* and *lineno*.  If none were set, an

-   error message is returned.

-

-.. method:: Bdb.clear_bpbynumber(arg)

-

-   Delete the breakpoint which has the index *arg* in the

-   :attr:`Breakpoint.bpbynumber`.  If `arg` is not numeric or out of range,

-   return an error message.

-

-.. method:: Bdb.clear_all_file_breaks(filename)

-

-   Delete all breakpoints in *filename*.  If none were set, an error message is

-   returned.

-

-.. method:: Bdb.clear_all_breaks()

-

-   Delete all existing breakpoints.

-

-.. method:: Bdb.get_break(filename, lineno)

-

-   Check if there is a breakpoint for *lineno* of *filename*.

-

-.. method:: Bdb.get_breaks(filename, lineno)

-

-   Return all breakpoints for *lineno* in *filename*, or an empty list if none

-   are set.

-

-.. method:: Bdb.get_file_breaks(filename)

-

-   Return all breakpoints in *filename*, or an empty list if none are set.

-

-.. method:: Bdb.get_all_breaks()

-

-   Return all breakpoints that are set.

-

-

-Derived classes and clients can call the following methods to get a data

-structure representing a stack trace.

-

-.. method:: Bdb.get_stack(f, t)

-

-   Get a list of records for a frame and all higher (calling) and lower frames,

-   and the size of the higher part.

-

-.. method:: Bdb.format_stack_entry(frame_lineno, [lprefix=': '])

-

-   Return a string with information about a stack entry, identified by a

-   ``(frame, lineno)`` tuple:

-

-   * The canonical form of the filename which contains the frame.

-   * The function name, or ``"<lambda>"``.

-   * The input arguments.

-   * The return value.

-   * The line of code (if it exists).

-

-

-The following two methods can be called by clients to use a debugger to debug a

-statement, given as a string.

-

-.. method:: Bdb.run(cmd, [globals, [locals]])

-

-   Debug a statement executed via the :func:`exec` function.  *globals*

-   defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.

-

-.. method:: Bdb.runeval(expr, [globals, [locals]])

-

-   Debug an expression executed via the :func:`eval` function.  *globals* and

-   *locals* have the same meaning as in :meth:`run`.

-

-.. method:: Bdb.runctx(cmd, globals, locals)

-

-   For backwards compatibility.  Calls the :meth:`run` method.

-

-.. method:: Bdb.runcall(func, *args, **kwds)

-

-   Debug a single function call, and return its result.

-

-

-Finally, the module defines the following functions:

-

-.. function:: checkfuncname(b, frame)

-

-   Check whether we should break here, depending on the way the breakpoint *b*

-   was set.

-   

-   If it was set via line number, it checks if ``b.line`` is the same as the one

-   in the frame also passed as argument.  If the breakpoint was set via function

-   name, we have to check we are in the right frame (the right function) and if

-   we are in its first executable line.

-

-.. function:: effective(file, line, frame)

-

-   Determine if there is an effective (active) breakpoint at this line of code.

-   Return breakpoint number or 0 if none.

-	

-   Called only if we know there is a breakpoint at this location.  Returns the

-   breakpoint that was triggered and a flag that indicates if it is ok to delete

-   a temporary breakpoint.

-

-.. function:: set_trace()

-

-   Starts debugging with a :class:`Bdb` instance from caller's frame.

+:mod:`bdb` --- Debugger framework
+=================================
+
+.. module:: bdb
+   :synopsis: Debugger framework.
+
+The :mod:`bdb` module handles basic debugger functions, like setting breakpoints
+or managing execution via the debugger.
+
+The following exception is defined:
+
+.. exception:: BdbQuit
+
+   Exception raised by the :class:`Bdb` class for quitting the debugger.
+
+
+The :mod:`bdb` module also defines two classes:
+
+.. class:: Breakpoint(self, file, line[, temporary=0[, cond=None [, funcname=None]]])
+
+   This class implements temporary breakpoints, ignore counts, disabling and
+   (re-)enabling, and conditionals.
+
+   Breakpoints are indexed by number through a list called :attr:`bpbynumber`
+   and by ``(file, line)`` pairs through :attr:`bplist`.  The former points to a
+   single instance of class :class:`Breakpoint`.  The latter points to a list of
+   such instances since there may be more than one breakpoint per line.
+
+   When creating a breakpoint, its associated filename should be in canonical
+   form.  If a *funcname* is defined, a breakpoint hit will be counted when the
+   first line of that function is executed.  A conditional breakpoint always
+   counts a hit.
+
+:class:`Breakpoint` instances have the following methods:
+
+.. method:: Breakpoint.deleteMe()
+
+   Delete the breakpoint from the list associated to a file/line.  If it is the
+   last breakpoint in that position, it also deletes the entry for the
+   file/line.
+
+.. method:: Breakpoint.enable()
+
+   Mark the breakpoint as enabled.
+
+.. method:: Breakpoint.disable()
+
+   Mark the breakpoint as disabled.
+
+.. method:: Breakpoint.bpprint([out])
+
+   Print all the information about the breakpoint:
+
+   * The breakpoint number.
+   * If it is temporary or not.
+   * Its file,line position.
+   * The condition that causes a break.
+   * If it must be ignored the next N times.
+   * The breakpoint hit count.
+
+
+.. class:: Bdb()
+
+   The :class:`Bdb` acts as a generic Python debugger base class.
+
+   This class takes care of the details of the trace facility; a derived class
+   should implement user interaction.  The standard debugger class
+   (:class:`pdb.Pdb`) is an example.
+
+
+The following methods of :class:`Bdb` normally don't need to be overridden.
+
+.. method:: Bdb.canonic(filename)
+
+   Auxiliary method for getting a filename in a canonical form, that is, as a
+   case-normalized (on case-insensitive filesystems) absolute path, stripped
+   of surrounding angle brackets.
+
+.. method:: Bdb.reset()
+
+   Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and
+   :attr:`quitting` attributes with values ready to start debugging.
+
+
+.. method:: Bdb.trace_dispatch(frame, event, arg)
+
+   This function is installed as the trace function of debugged frames.  Its
+   return value is the new trace function (in most cases, that is, itself).
+
+   The default implementation decides how to dispatch a frame, depending on the
+   type of event (passed as a string) that is about to be executed.  *event* can
+   be one of the following:
+
+   * ``"line"``: A new line of code is going to be executed.
+   * ``"call"``: A function is about to be called, or another code block
+     entered.
+   * ``"return"``: A function or other code block is about to return.
+   * ``"exception"``: An exception has occurred.
+   * ``"c_call"``: A C function is about to be called.
+   * ``"c_return"``: A C function has returned.
+   * ``"c_exception"``: A C function has thrown an exception.
+
+   For the Python events, specialized functions (see below) are called.  For the
+   C events, no action is taken.
+
+   The *arg* parameter depends on the previous event.
+
+   For more information on trace functions, see :ref:`debugger-hooks`.  For more
+   information on code and frame objects, refer to :ref:`types`.
+
+.. method:: Bdb.dispatch_line(frame)
+
+   If the debugger should stop on the current line, invoke the :meth:`user_line`
+   method (which should be overridden in subclasses).  Raise a :exc:`BdbQuit`
+   exception if the :attr:`Bdb.quitting` flag is set (which can be set from
+   :meth:`user_line`).  Return a reference to the :meth:`trace_dispatch` method
+   for further tracing in that scope.
+
+.. method:: Bdb.dispatch_call(frame, arg)
+
+   If the debugger should stop on this function call, invoke the
+   :meth:`user_call` method (which should be overridden in subclasses).  Raise a
+   :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
+   be set from :meth:`user_call`).  Return a reference to the
+   :meth:`trace_dispatch` method for further tracing in that scope.
+
+.. method:: Bdb.dispatch_return(frame, arg)
+
+   If the debugger should stop on this function return, invoke the
+   :meth:`user_return` method (which should be overridden in subclasses).  Raise
+   a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
+   be set from :meth:`user_return`).  Return a reference to the
+   :meth:`trace_dispatch` method for further tracing in that scope.
+
+.. method:: Bdb.dispatch_exception(frame, arg)
+
+   If the debugger should stop at this exception, invokes the
+   :meth:`user_exception` method (which should be overridden in subclasses).
+   Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
+   (which can be set from :meth:`user_exception`).  Return a reference to the
+   :meth:`trace_dispatch` method for further tracing in that scope.
+
+Normally derived classes don't override the following methods, but they may if
+they want to redefine the definition of stopping and breakpoints.
+
+.. method:: Bdb.stop_here(frame)
+
+   This method checks if the *frame* is somewhere below :attr:`botframe` in the
+   call stack.  :attr:`botframe` is the frame in which debugging started.
+
+.. method:: Bdb.break_here(frame)
+
+   This method checks if there is a breakpoint in the filename and line
+   belonging to *frame* or, at least, in the current function.  If the
+   breakpoint is a temporary one, this method deletes it.
+
+.. method:: Bdb.break_anywhere(frame)
+
+   This method checks if there is a breakpoint in the filename of the current
+   frame.
+
+Derived classes should override these methods to gain control over debugger
+operation.
+
+.. method:: Bdb.user_call(frame, argument_list)
+
+   This method is called from :meth:`dispatch_call` when there is the
+   possibility that a break might be necessary anywhere inside the called
+   function.
+
+.. method:: Bdb.user_line(frame)
+
+   This method is called from :meth:`dispatch_line` when either
+   :meth:`stop_here` or :meth:`break_here` yields True.
+
+.. method:: Bdb.user_return(frame, return_value)
+
+   This method is called from :meth:`dispatch_return` when :meth:`stop_here`
+   yields True.
+
+.. method:: Bdb.user_exception(frame, exc_info)
+
+   This method is called from :meth:`dispatch_exception` when :meth:`stop_here`
+   yields True.
+
+.. method:: Bdb.do_clear(arg)
+
+   Handle how a breakpoint must be removed when it is a temporary one.
+
+   This method must be implemented by derived classes.
+
+
+Derived classes and clients can call the following methods to affect the 
+stepping state.
+
+.. method:: Bdb.set_step()
+
+   Stop after one line of code.
+
+.. method:: Bdb.set_next(frame)
+
+   Stop on the next line in or below the given frame.
+
+.. method:: Bdb.set_return(frame)
+
+   Stop when returning from the given frame.
+
+.. method:: Bdb.set_trace([frame])
+
+   Start debugging from *frame*.  If *frame* is not specified, debugging starts
+   from caller's frame.
+
+.. method:: Bdb.set_continue()
+
+   Stop only at breakpoints or when finished.  If there are no breakpoints, set
+   the system trace function to None.
+
+.. method:: Bdb.set_quit()
+
+   Set the :attr:`quitting` attribute to True.  This raises :exc:`BdbQuit` in
+   the next call to one of the :meth:`dispatch_\*` methods.
+
+
+Derived classes and clients can call the following methods to manipulate
+breakpoints.  These methods return a string containing an error message if
+something went wrong, or ``None`` if all is well.
+
+.. method:: Bdb.set_break(filename, lineno[, temporary=0[, cond[, funcname]]])
+
+   Set a new breakpoint.  If the *lineno* line doesn't exist for the *filename*
+   passed as argument, return an error message.  The *filename* should be in
+   canonical form, as described in the :meth:`canonic` method.
+
+.. method:: Bdb.clear_break(filename, lineno)
+
+   Delete the breakpoints in *filename* and *lineno*.  If none were set, an
+   error message is returned.
+
+.. method:: Bdb.clear_bpbynumber(arg)
+
+   Delete the breakpoint which has the index *arg* in the
+   :attr:`Breakpoint.bpbynumber`.  If `arg` is not numeric or out of range,
+   return an error message.
+
+.. method:: Bdb.clear_all_file_breaks(filename)
+
+   Delete all breakpoints in *filename*.  If none were set, an error message is
+   returned.
+
+.. method:: Bdb.clear_all_breaks()
+
+   Delete all existing breakpoints.
+
+.. method:: Bdb.get_break(filename, lineno)
+
+   Check if there is a breakpoint for *lineno* of *filename*.
+
+.. method:: Bdb.get_breaks(filename, lineno)
+
+   Return all breakpoints for *lineno* in *filename*, or an empty list if none
+   are set.
+
+.. method:: Bdb.get_file_breaks(filename)
+
+   Return all breakpoints in *filename*, or an empty list if none are set.
+
+.. method:: Bdb.get_all_breaks()
+
+   Return all breakpoints that are set.
+
+
+Derived classes and clients can call the following methods to get a data
+structure representing a stack trace.
+
+.. method:: Bdb.get_stack(f, t)
+
+   Get a list of records for a frame and all higher (calling) and lower frames,
+   and the size of the higher part.
+
+.. method:: Bdb.format_stack_entry(frame_lineno, [lprefix=': '])
+
+   Return a string with information about a stack entry, identified by a
+   ``(frame, lineno)`` tuple:
+
+   * The canonical form of the filename which contains the frame.
+   * The function name, or ``"<lambda>"``.
+   * The input arguments.
+   * The return value.
+   * The line of code (if it exists).
+
+
+The following two methods can be called by clients to use a debugger to debug a
+:term:`statement`, given as a string.
+
+.. method:: Bdb.run(cmd, [globals, [locals]])
+
+   Debug a statement executed via the :keyword:`exec` statement.  *globals*
+   defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
+
+.. method:: Bdb.runeval(expr, [globals, [locals]])
+
+   Debug an expression executed via the :func:`eval` function.  *globals* and
+   *locals* have the same meaning as in :meth:`run`.
+
+.. method:: Bdb.runctx(cmd, globals, locals)
+
+   For backwards compatibility.  Calls the :meth:`run` method.
+
+.. method:: Bdb.runcall(func, *args, **kwds)
+
+   Debug a single function call, and return its result.
+
+
+Finally, the module defines the following functions:
+
+.. function:: checkfuncname(b, frame)
+
+   Check whether we should break here, depending on the way the breakpoint *b*
+   was set.
+   
+   If it was set via line number, it checks if ``b.line`` is the same as the one
+   in the frame also passed as argument.  If the breakpoint was set via function
+   name, we have to check we are in the right frame (the right function) and if
+   we are in its first executable line.
+
+.. function:: effective(file, line, frame)
+
+   Determine if there is an effective (active) breakpoint at this line of code.
+   Return breakpoint number or 0 if none.
+	
+   Called only if we know there is a breakpoint at this location.  Returns the
+   breakpoint that was triggered and a flag that indicates if it is ok to delete
+   a temporary breakpoint.
+
+.. function:: set_trace()
+
+   Starts debugging with a :class:`Bdb` instance from caller's frame.
diff --git a/Doc/library/codeop.rst b/Doc/library/codeop.rst
index 419e873..35430b4 100644
--- a/Doc/library/codeop.rst
+++ b/Doc/library/codeop.rst
@@ -43,8 +43,8 @@ To do just the former:
    :exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal.
 
    The *symbol* argument determines whether *source* is compiled as a statement
-   (``'single'``, the default) or as an expression (``'eval'``).  Any other value
-   will cause :exc:`ValueError` to  be raised.
+   (``'single'``, the default) or as an :term:`expression` (``'eval'``).  Any
+   other value will cause :exc:`ValueError` to  be raised.
 
    .. warning::
       
diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst
index 6a4fd3d..cab2e8c 100644
--- a/Doc/library/contextlib.rst
+++ b/Doc/library/contextlib.rst
@@ -15,9 +15,9 @@ Functions provided:
 
 .. function:: contextmanager(func)
 
-   This function is a decorator that can be used to define a factory function for
-   :keyword:`with` statement context managers, without needing to create a class or
-   separate :meth:`__enter__` and :meth:`__exit__` methods.
+   This function is a :term:`decorator` that can be used to define a factory
+   function for :keyword:`with` statement context managers, without needing to
+   create a class or separate :meth:`__enter__` and :meth:`__exit__` methods.
 
    A simple example (this is not recommended as a real way of generating HTML!)::
 
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index 721d7c0..99a2921 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -1070,7 +1070,8 @@ capabilities, then you should use the advanced API.
 The advanced API revolves around two container classes, which are used to store
 the interactive examples extracted from doctest cases:
 
-* :class:`Example`: A single python statement, paired with its expected output.
+* :class:`Example`: A single python :term:`statement`, paired with its expected
+  output.
 
 * :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted
   from a single docstring or text file.
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 5d0d8a5..37c53a5 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -177,8 +177,8 @@ available.  They are listed here in alphabetical order.
           @classmethod
           def f(cls, arg1, arg2, ...): ...
 
-   The ``@classmethod`` form is a function decorator -- see the description of
-   function definitions in :ref:`function` for details.
+   The ``@classmethod`` form is a function :term:`decorator` -- see the description
+   of function definitions in :ref:`function` for details.
 
    It can be called either on the class (such as ``C.f()``) or on an instance (such
    as ``C().f()``).  The instance is ignored except for its class. If a class
@@ -814,7 +814,7 @@ available.  They are listed here in alphabetical order.
 
    If given, *doc* will be the docstring of the property attribute. Otherwise, the
    property will copy *fget*'s docstring (if it exists).  This makes it possible to
-   create read-only properties easily using :func:`property` as a decorator::
+   create read-only properties easily using :func:`property` as a :term:`decorator`::
 
       class Parrot(object):
           def __init__(self):
@@ -906,7 +906,7 @@ available.  They are listed here in alphabetical order.
 
    .. index:: single: Numerical Python
 
-   Return a slice object representing the set of indices specified by
+   Return a :term:`slice` object representing the set of indices specified by
    ``range(start, stop, step)``.  The *start* and *step* arguments default to
    ``None``.  Slice objects have read-only data attributes :attr:`start`,
    :attr:`stop` and :attr:`step` which merely return the argument values (or their
@@ -952,8 +952,8 @@ available.  They are listed here in alphabetical order.
           @staticmethod
           def f(arg1, arg2, ...): ...
 
-   The ``@staticmethod`` form is a function decorator -- see the description of
-   function definitions in :ref:`function` for details.
+   The ``@staticmethod`` form is a function :term:`decorator` -- see the
+   description of function definitions in :ref:`function` for details.
 
    It can be called either on the class (such as ``C.f()``) or on an instance (such
    as ``C().f()``).  The instance is ignored except for its class.
diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index a3d3729..1c8fa5b 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -76,9 +76,9 @@ The :mod:`functools` module defines the following functions:
    *WRAPPER_UPDATES* (which updates the wrapper function's *__dict__*, i.e. the
    instance dictionary).
 
-   The main intended use for this function is in decorator functions which wrap the
-   decorated function and return the wrapper. If the wrapper function is not
-   updated, the metadata of the returned function will reflect the wrapper
+   The main intended use for this function is in :term:`decorator` functions which
+   wrap the decorated function and return the wrapper. If the wrapper function is
+   not updated, the metadata of the returned function will reflect the wrapper
    definition rather than the original function definition, which is typically less
    than helpful.
 
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 988b737..5cdec20 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -220,7 +220,7 @@ attributes:
 
 .. function:: isfunction(object)
 
-   Return true if the object is a Python function or unnamed (lambda) function.
+   Return true if the object is a Python function or unnamed (:term:`lambda`) function.
 
 
 .. function:: istraceback(object)
diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst
index 26748c4..715610e 100644
--- a/Doc/library/mmap.rst
+++ b/Doc/library/mmap.rst
@@ -84,6 +84,49 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
    *offset* may be specified as a non-negative integer offset. mmap references will 
    be relative to the offset from the beginning of the file. *offset* defaults to 0.
    *offset* must be a multiple of the PAGESIZE or ALLOCATIONGRANULARITY.
+   
+   This example shows a simple way of using :func:`mmap`::
+
+      import mmap
+
+      # write a simple example file
+      with open("hello.txt", "w") as f:
+          f.write("Hello Python!\n")
+
+      with open("hello.txt", "r+") as f:
+          # memory-map the file, size 0 means whole file
+          map = mmap.mmap(f.fileno(), 0)
+          # read content via standard file methods
+          print map.readline()  # prints "Hello Python!"
+          # read content via slice notation
+          print map[:5]  # prints "Hello"
+          # update content using slice notation;
+          # note that new content must have same size
+          map[6:] = " world!\n"
+          # ... and read again using standard file methods
+          map.seek(0)
+          print map.readline()  # prints "Hello  world!"
+          # close the map
+          map.close()
+
+
+   The next example demonstrates how to create an anonymous map and exchange
+   data between the parent and child processes::
+
+      import mmap
+      import os
+
+      map = mmap.mmap(-1, 13)
+      map.write("Hello world!")
+
+      pid = os.fork()
+
+      if pid == 0: # In a child process
+          map.seek(0)
+          print map.readline()
+
+          map.close()
+
 
 Memory-mapped file objects support the following methods:
 
diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst
index cb89a7f..15f46eb 100644
--- a/Doc/library/operator.rst
+++ b/Doc/library/operator.rst
@@ -262,10 +262,10 @@ Operations which work with sequences include:
 
 Many operations have an "in-place" version.  The following functions provide a
 more primitive access to in-place operators than the usual syntax does; for
-example, the statement ``x += y`` is equivalent to ``x = operator.iadd(x, y)``.
-Another way to put it is to say that ``z = operator.iadd(x, y)`` is equivalent
-to the compound statement ``z = x; z += y``.
-
+example, the :term:`statement` ``x += y`` is equivalent to
+``x = operator.iadd(x, y)``.  Another way to put it is to say that
+``z = operator.iadd(x, y)`` is equivalent to the compound statement
+``z = x; z += y``.
 
 .. function:: iadd(a, b)
               __iadd__(a, b)
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index e94560b..56d4851 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -2149,8 +2149,8 @@ decimal arithmetic context. The specific types are not treated specially beyond
 their implementation of the context management protocol. See the
 :mod:`contextlib` module for some examples.
 
-Python's :term:`generator`\s and the ``contextlib.contextfactory`` decorator provide a
-convenient way to implement these protocols.  If a generator function is
+Python's :term:`generator`\s and the ``contextlib.contextfactory`` :term:`decorator`
+provide a convenient way to implement these protocols.  If a generator function is
 decorated with the ``contextlib.contextfactory`` decorator, it will return a
 context manager implementing the necessary :meth:`__enter__` and
 :meth:`__exit__` methods, rather than the iterator produced by an undecorated
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 3b9112a..97f94aa 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -80,9 +80,9 @@ always available.
    If *value* is not ``None``, this function prints it to ``sys.stdout``, and saves
    it in ``builtins._``.
 
-   ``sys.displayhook`` is called on the result of evaluating an expression entered
-   in an interactive Python session.  The display of these values can be customized
-   by assigning another one-argument function to ``sys.displayhook``.
+   ``sys.displayhook`` is called on the result of evaluating an :term:`expression`
+   entered in an interactive Python session.  The display of these values can be
+   customized by assigning another one-argument function to ``sys.displayhook``.
 
 
 .. function:: excepthook(type, value, traceback)
@@ -536,14 +536,16 @@ always available.
           stderr
 
    File objects corresponding to the interpreter's standard input, output and error
-   streams.  ``stdin`` is used for all interpreter input except for scripts.
-   ``stdout`` is used for the output of :func:`print` and expression statements.
-   The interpreter's own prompts and (almost all of) its error messages go to
-   ``stderr``.  ``stdout`` and ``stderr`` needn't be built-in file objects: any
-   object is acceptable as long as it has a :meth:`write` method that takes a
-   string argument.  (Changing these objects doesn't affect the standard I/O
-   streams of processes executed by :func:`os.popen`, :func:`os.system` or the
-   :func:`exec\*` family of functions in the :mod:`os` module.)
+   streams.  ``stdin`` is used for all interpreter input except for scripts but
+   including calls to :func:`input`.  ``stdout`` is used for
+   the output of :func:`print` and :term:`expression` statements and for the
+   prompts of :func:`input`. The interpreter's own prompts
+   and (almost all of) its error messages go to ``stderr``.  ``stdout`` and
+   ``stderr`` needn't be built-in file objects: any object is acceptable as long
+   as it has a :meth:`write` method that takes a string argument.  (Changing these 
+   objects doesn't affect the standard I/O streams of processes executed by
+   :func:`os.popen`, :func:`os.system` or the :func:`exec\*` family of functions in
+   the :mod:`os` module.)
 
 
 .. data:: __stdin__
diff --git a/Doc/library/timeit.rst b/Doc/library/timeit.rst
index 3387c7f..6a8a94d 100644
--- a/Doc/library/timeit.rst
+++ b/Doc/library/timeit.rst
@@ -85,11 +85,12 @@ The module defines the following public class:
 
    .. note::
 
-      By default, :meth:`timeit` temporarily turns off garbage collection during the
-      timing.  The advantage of this approach is that it makes independent timings
-      more comparable.  This disadvantage is that GC may be an important component of
-      the performance of the function being measured.  If so, GC can be re-enabled as
-      the first statement in the *setup* string.  For example::
+      By default, :meth:`timeit` temporarily turns off :term:`garbage collection`
+      during the timing.  The advantage of this approach is that it makes
+      independent timings more comparable.  This disadvantage is that GC may be
+      an important component of the performance of the function being measured.
+      If so, GC can be re-enabled as the first statement in the *setup* string.
+      For example::
 
          timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()
 
diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst
index 9a1e076..fdfbae0 100644
--- a/Doc/library/weakref.rst
+++ b/Doc/library/weakref.rst
@@ -20,22 +20,22 @@ In the following, the term :dfn:`referent` means the object which is referred to
 by a weak reference.
 
 A weak reference to an object is not enough to keep the object alive: when the
-only remaining references to a referent are weak references, garbage collection
-is free to destroy the referent and reuse its memory for something else.  A
-primary use for weak references is to implement caches or mappings holding large
-objects, where it's desired that a large object not be kept alive solely because
-it appears in a cache or mapping.  For example, if you have a number of large
-binary image objects, you may wish to associate a name with each.  If you used a
-Python dictionary to map names to images, or images to names, the image objects
-would remain alive just because they appeared as values or keys in the
-dictionaries.  The :class:`WeakKeyDictionary`, :class:`WeakValueDictionary`
-and :class:`WeakSet` classes supplied by the :mod:`weakref` module are an
-alternative, using weak references to construct mappings that don't keep objects
-alive solely because they appear in the container objects.
-If, for example, an image object is a value in a :class:`WeakValueDictionary`,
-then when the last remaining references to that image object are the weak
-references held by weak mappings, garbage collection can reclaim the object,
-and its corresponding entries in weak mappings are simply deleted.
+only remaining references to a referent are weak references,
+:term:`garbage collection` is free to destroy the referent and reuse its memory
+for something else.  A primary use for weak references is to implement caches or
+mappings holding large objects, where it's desired that a large object not be
+kept alive solely because it appears in a cache or mapping.  For example, if you
+have a number of large binary image objects, you may wish to associate a name
+with each.  If you used a Python dictionary to map names to images, or images to
+names, the image objects would remain alive just because they appeared as values
+or keys in the dictionaries.  The :class:`WeakKeyDictionary` and
+:class:`WeakValueDictionary` classes supplied by the :mod:`weakref` module are
+an alternative, using weak references to construct mappings that don't keep
+objects alive solely because they appear in the mapping objects.  If, for
+example, an image object is a value in a :class:`WeakValueDictionary`, then when
+the last remaining references to that image object are the weak references held
+by weak mappings, garbage collection can reclaim the object, and its
+corresponding entries in weak mappings are simply deleted.
 
 :class:`WeakKeyDictionary` and :class:`WeakValueDictionary` use weak references
 in their implementation, setting up callback functions on the weak references
diff --git a/Doc/library/windows.rst b/Doc/library/windows.rst
index a231bc2..b09dd8b 100644
--- a/Doc/library/windows.rst
+++ b/Doc/library/windows.rst
@@ -1,3 +1,4 @@
+.. _mswin-specific-services:
 
 ****************************
 MS Windows Specific Services
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index 81a9316..172a2a0 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -31,6 +31,9 @@ convert it from and to XML.
 
 A C implementation of this API is available as :mod:`xml.etree.cElementTree`.
 
+See http://effbot.org/zone/element-index.htm for tutorials and links to other
+docs. Fredrik Lundh's page is also the location of the development version of the 
+xml.etree.ElementTree.
 
 .. _elementtree-functions:
 
@@ -355,6 +358,33 @@ ElementTree Objects
    object opened for writing. *encoding* is the output encoding (default is
    US-ASCII).
 
+This is the XML file that is going to be manipulated::
+
+    <html>
+        <head>
+            <title>Example page</title>
+        </head>
+        <body>
+            <p>Moved to <a href="http://example.org/">example.org</a> 
+            or <a href="http://example.com/">example.com</a>.</p>
+        </body>
+    </html>
+
+Example of changing the attribute "target" of every link in first paragraph::
+
+    >>> from xml.etree.ElementTree import ElementTree
+    >>> tree = ElementTree()
+    >>> tree.parse("index.xhtml")
+    <Element html at b7d3f1ec>
+    >>> p = tree.find("body/p")     # Finds first occurrence of tag p in body
+    >>> p
+    <Element p at 8416e0c>
+    >>> links = p.getiterator("a")  # Returns list of all links
+    >>> links
+    [<Element a at b7d4f9ec>, <Element a at b7d4fb0c>]
+    >>> for i in links:             # Iterates through all found links
+    ...     i.attrib["target"] = "blank"
+    >>> tree.write("output.xhtml")
 
 .. _elementtree-qname-objects:
 
@@ -440,3 +470,41 @@ XMLTreeBuilder Objects
 
    Feeds data to the parser. *data* is encoded data.
 
+:meth:`XMLTreeBuilder.feed` calls *target*\'s :meth:`start` method
+for each opening tag, its :meth:`end` method for each closing tag,
+and data is processed by method :meth:`data`. :meth:`XMLTreeBuilder.close` 
+calls *target*\'s method :meth:`close`. 
+:class:`XMLTreeBuilder` can be used not only for building a tree structure. 
+This is an example of counting the maximum depth of an XML file::
+
+    >>> from xml.etree.ElementTree import XMLTreeBuilder
+    >>> class MaxDepth:                     # The target object of the parser
+    ...     maxDepth = 0
+    ...     depth = 0
+    ...     def start(self, tag, attrib):   # Called for each opening tag.
+    ...         self.depth += 1 
+    ...         if self.depth > self.maxDepth:
+    ...             self.maxDepth = self.depth
+    ...     def end(self, tag):             # Called for each closing tag.
+    ...         self.depth -= 1
+    ...     def data(self, data):   
+    ...         pass            # We do not need to do anything with data.
+    ...     def close(self):    # Called when all data has been parsed.
+    ...         return self.maxDepth
+    ... 
+    >>> target = MaxDepth()
+    >>> parser = XMLTreeBuilder(target=target)
+    >>> exampleXml = """
+    ... <a>
+    ...   <b>
+    ...   </b>
+    ...   <b>
+    ...     <c>
+    ...       <d>
+    ...       </d>
+    ...     </c>
+    ...   </b>
+    ... </a>"""
+    >>> parser.feed(exampleXml)
+    >>> parser.close()
+    4