Recorded merge of revisions 86795,86798-86799,86801 via svnmerge from

svn+ssh://svn.python.org/python/branches/py3k

........
  r86795 | georg.brandl | 2010-11-26 12:55:48 +0100 (Fr, 26 Nov 2010) | 1 line

  Use PyLong_FromLong where appropriate.
........
  r86798 | georg.brandl | 2010-11-26 13:05:48 +0100 (Fr, 26 Nov 2010) | 1 line

  #10420: fix docs of bdb.effective().
........
  r86799 | georg.brandl | 2010-11-26 13:08:19 +0100 (Fr, 26 Nov 2010) | 1 line

  Remove parenthetical remark that is confusing now that the module is not named "__builtin__" anymore.
........
  r86801 | georg.brandl | 2010-11-26 13:12:14 +0100 (Fr, 26 Nov 2010) | 1 line

  Better example for os.system(): do not change the system time.
........

Doc/extending/embedding.rst

@@ -209,7 +209,7 @@ Python extension.  For example::
    {
        if(!PyArg_ParseTuple(args, ":numargs"))
            return NULL;
-       return Py_BuildValue("i", numargs);
+       return PyLong_FromLong(numargs);
    }
 
    static PyMethodDef EmbMethods[] = {

Doc/extending/extending.rst

@@ -74,7 +74,7 @@ shortly how it ends up being called)::
        if (!PyArg_ParseTuple(args, "s", &command))
            return NULL;
        sts = system(command);
-       return Py_BuildValue("i", sts);
+       return PyLong_FromLong(sts);
    }
 
 There is a straightforward translation from the argument list in Python (for
@@ -266,13 +266,10 @@ the string we just got from :cfunc:`PyArg_ParseTuple`::
 
    sts = system(command);
 
-Our :func:`spam.system` function must return the value of :cdata:`sts` as a
-Python object.  This is done using the function :cfunc:`Py_BuildValue`, which is
-something like the inverse of :cfunc:`PyArg_ParseTuple`: it takes a format
-string and an arbitrary number of C values, and returns a new Python object.
-More info on :cfunc:`Py_BuildValue` is given later. ::
+Our :func:`spam.system` function must return the value of :c:data:`sts` as a
+Python object.  This is done using the function :cfunc:`PyLong_FromLong`. ::
 
-   return Py_BuildValue("i", sts);
+   return PyLong_FromLong(sts);
 
 In this case, it will return an integer object.  (Yes, even integers are objects
 on the heap in Python!)
@@ -1193,7 +1190,7 @@ The function :cfunc:`spam_system` is modified in a trivial way::
        if (!PyArg_ParseTuple(args, "s", &command))
            return NULL;
        sts = PySpam_System(command);
-       return Py_BuildValue("i", sts);
+       return PyLong_FromLong(sts);
    }
 
 In the beginning of the module, right after the line ::

Doc/library/bdb.rst

@@ -342,12 +342,10 @@ Finally, the module defines the following functions:
 .. 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.
+   Return a tuple of the breakpoint and a boolean that indicates if it is ok
+   to delete a temporary breakpoint.  Return ``(None, None)`` if there is no
+   matching breakpoint.
 
 .. function:: set_trace()
 
-   Starts debugging with a :class:`Bdb` instance from caller's frame.
+   Start debugging with a :class:`Bdb` instance from caller's frame.

Doc/library/builtins.rst

@@ -32,9 +32,8 @@ that wants to implement an :func:`open` function that wraps the built-in
 
        # ...
 
-As an implementation detail, most modules have the name ``__builtins__`` (note
-the ``'s'``) made available as part of their globals.  The value of
-``__builtins__`` is normally either this module or the value of this modules's
-:attr:`__dict__` attribute.  Since this is an implementation detail, it may not
-be used by alternate implementations of Python.
-
+As an implementation detail, most modules have the name ``__builtins__`` made
+available as part of their globals.  The value of ``__builtins__`` is normally
+either this module or the value of this modules's :attr:`__dict__` attribute.
+Since this is an implementation detail, it may not be used by alternate
+implementations of Python.

Doc/tutorial/stdlib.rst

@@ -14,11 +14,11 @@ The :mod:`os` module provides dozens of functions for interacting with the
 operating system::
 
    >>> import os
-   >>> os.system('time 0:02')
-   0
    >>> os.getcwd()      # Return the current working directory
    'C:\\Python31'
-   >>> os.chdir('/server/accesslogs')
+   >>> os.chdir('/server/accesslogs')   # Change current working directory
+   >>> os.system('mkdir today')   # Run the command mkdir in the system shell
+   0
 
 Be sure to use the ``import os`` style instead of ``from os import *``.  This
 will keep :func:`os.open` from shadowing the built-in :func:`open` function which