diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst
index ff25fe9..b62148a 100644
--- a/Doc/library/tarfile.rst
+++ b/Doc/library/tarfile.rst
@@ -34,10 +34,8 @@
   character devices and block devices and is able to acquire and restore file
   information like timestamp, access permissions and owner.
 
-* can handle tape devices.
 
-
-.. function:: open(name[, mode[, fileobj[, bufsize]]], **kwargs)
+.. function:: open(name=None, mode='r', fileobj=None, bufsize=10240, \*\*kwargs)
 
    Return a :class:`TarFile` object for the pathname *name*. For detailed
    information on :class:`TarFile` objects and the keyword arguments that are
@@ -78,7 +76,7 @@
    for *name*. It is supposed to be at position 0.
 
    For special purposes, there is a second format for *mode*:
-   ``'filemode|[compression]'``.  :func:`open` will return a :class:`TarFile`
+   ``'filemode|[compression]'``.  :func:`tarfile.open` will return a :class:`TarFile`
    object that processes its data as a stream of blocks.  No random seeking will
    be done on the file. If given, *fileobj* may be any object that has a
    :meth:`read` or :meth:`write` method (depending on the *mode*). *bufsize*
@@ -116,7 +114,7 @@
 .. class:: TarFile
 
    Class for reading and writing tar archives. Do not use this class directly,
-   better use :func:`open` instead. See :ref:`tarfile-objects`.
+   better use :func:`tarfile.open` instead. See :ref:`tarfile-objects`.
 
 
 .. function:: is_tarfile(name)
@@ -125,7 +123,7 @@
    module can read.
 
 
-.. class:: TarFileCompat(filename[, mode[, compression]])
+.. class:: TarFileCompat(filename, mode='r', compression=TAR_PLAIN)
 
    Class for limited access to tar archives with a :mod:`zipfile`\ -like interface.
    Please consult the documentation of the :mod:`zipfile` module for more details.
@@ -167,16 +165,17 @@
 
 .. exception:: ExtractError
 
-   Is raised for *non-fatal* errors when using :meth:`extract`, but only if
+   Is raised for *non-fatal* errors when using :meth:`TarFile.extract`, but only if
    :attr:`TarFile.errorlevel`\ ``== 2``.
 
 
 .. exception:: HeaderError
 
-   Is raised by :meth:`frombuf` if the buffer it gets is invalid.
+   Is raised by :meth:`TarInfo.frombuf` if the buffer it gets is invalid.
 
    .. versionadded:: 2.6
 
+
 Each of the following constants defines a tar archive format that the
 :mod:`tarfile` module is able to create. See section :ref:`tar-formats` for
 details.
@@ -202,12 +201,21 @@
    The default format for creating archives. This is currently :const:`GNU_FORMAT`.
 
 
+The following variables are available on module level:
+
+
+.. data:: ENCODING
+
+   The default character encoding i.e. the value from either
+   :func:`sys.getfilesystemencoding` or :func:`sys.getdefaultencoding`.
+
+
 .. seealso::
 
    Module :mod:`zipfile`
       Documentation of the :mod:`zipfile` standard module.
 
-   `GNU tar manual, Basic Tar Format <http://www.gnu.org/software/tar/manual/html_node/tar_134.html#SEC134>`_
+   `GNU tar manual, Basic Tar Format <http://www.gnu.org/software/tar/manual/html_node/Standard.html>`_
       Documentation for tar archive files, including GNU tar extensions.
 
 
@@ -223,7 +231,7 @@
 object, see :ref:`tarinfo-objects` for details.
 
 
-.. class:: TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=None, errors=None, pax_headers=None, debug=0, errorlevel=0)
+.. class:: TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors=None, pax_headers=None, debug=0, errorlevel=0)
 
    All following arguments are optional and can be accessed as instance attributes
    as well.
@@ -254,18 +262,18 @@
 
    .. versionadded:: 2.6
 
-   If *dereference* is ``False``, add symbolic and hard links to the archive. If it
-   is ``True``, add the content of the target files to the archive. This has no
+   If *dereference* is :const:`False`, add symbolic and hard links to the archive. If it
+   is :const:`True`, add the content of the target files to the archive. This has no
    effect on systems that do not support symbolic links.
 
-   If *ignore_zeros* is ``False``, treat an empty block as the end of the archive.
-   If it is *True*, skip empty (and invalid) blocks and try to get as many members
+   If *ignore_zeros* is :const:`False`, treat an empty block as the end of the archive.
+   If it is :const:`True`, skip empty (and invalid) blocks and try to get as many members
    as possible. This is only useful for reading concatenated or damaged archives.
 
    *debug* can be set from ``0`` (no debug messages) up to ``3`` (all debug
    messages). The messages are written to ``sys.stderr``.
 
-   If *errorlevel* is ``0``, all errors are ignored when using :meth:`extract`.
+   If *errorlevel* is ``0``, all errors are ignored when using :meth:`TarFile.extract`.
    Nevertheless, they appear as error messages in the debug output, when debugging
    is enabled.  If ``1``, all *fatal* errors are raised as :exc:`OSError` or
    :exc:`IOError` exceptions. If ``2``, all *non-fatal* errors are raised as
@@ -285,8 +293,8 @@
 
 .. method:: TarFile.open(...)
 
-   Alternative constructor. The :func:`open` function on module level is actually a
-   shortcut to this classmethod. See section :ref:`tarfile-mod` for details.
+   Alternative constructor. The :func:`tarfile.open` function is actually a
+   shortcut to this classmethod.
 
 
 .. method:: TarFile.getmember(name)
@@ -322,11 +330,11 @@
 .. method:: TarFile.next()
 
    Return the next member of the archive as a :class:`TarInfo` object, when
-   :class:`TarFile` is opened for reading. Return ``None`` if there is no more
+   :class:`TarFile` is opened for reading. Return :const:`None` if there is no more
    available.
 
 
-.. method:: TarFile.extractall([path[, members]])
+.. method:: TarFile.extractall(path=".", members=None)
 
    Extract all members from the archive to the current working directory or
    directory *path*. If optional *members* is given, it must be a subset of the
@@ -346,7 +354,7 @@
    .. versionadded:: 2.5
 
 
-.. method:: TarFile.extract(member[, path])
+.. method:: TarFile.extract(member, path="")
 
    Extract a member from the archive to the current working directory, using its
    full name. Its file information is extracted as accurately as possible. *member*
@@ -355,9 +363,8 @@
 
    .. note::
 
-      Because the :meth:`extract` method allows random access to a tar archive there
-      are some issues you must take care of yourself. See the description for
-      :meth:`extractall` above.
+      The :meth:`extract` method does not take care of several extraction issues.
+      In most cases you should consider using the :meth:`extractall` method.
 
    .. warning::
 
@@ -369,7 +376,7 @@
    Extract a member from the archive as a file object. *member* may be a filename
    or a :class:`TarInfo` object. If *member* is a regular file, a file-like object
    is returned. If *member* is a link, a file-like object is constructed from the
-   link's target. If *member* is none of the above, ``None`` is returned.
+   link's target. If *member* is none of the above, :const:`None` is returned.
 
    .. note::
 
@@ -377,7 +384,7 @@
       :meth:`read`, :meth:`readline`, :meth:`readlines`, :meth:`seek`, :meth:`tell`.
 
 
-.. method:: TarFile.add(name[, arcname[, recursive[, exclude]]])
+.. method:: TarFile.add(name, arcname=None, recursive=True, exclude=None)
 
    Add the file *name* to the archive. *name* may be any type of file (directory,
    fifo, symbolic link, etc.). If given, *arcname* specifies an alternative name
@@ -391,7 +398,7 @@
       Added the *exclude* parameter.
 
 
-.. method:: TarFile.addfile(tarinfo[, fileobj])
+.. method:: TarFile.addfile(tarinfo, fileobj=None)
 
    Add the :class:`TarInfo` object *tarinfo* to the archive. If *fileobj* is given,
    ``tarinfo.size`` bytes are read from it and added to the archive.  You can
@@ -403,7 +410,7 @@
       avoid irritation about the file size.
 
 
-.. method:: TarFile.gettarinfo([name[, arcname[, fileobj]]])
+.. method:: TarFile.gettarinfo(name=None, arcname=None, fileobj=None)
 
    Create a :class:`TarInfo` object for either the file *name* or the file object
    *fileobj* (using :func:`os.fstat` on its file descriptor).  You can modify some
@@ -451,7 +458,7 @@
 :meth:`getmember`, :meth:`getmembers` and :meth:`gettarinfo`.
 
 
-.. class:: TarInfo([name])
+.. class:: TarInfo(name="")
 
    Create a :class:`TarInfo` object.
 
@@ -472,7 +479,7 @@
    .. versionadded:: 2.6
 
 
-.. method:: TarInfo.tobuf([format[, encoding [, errors]]])
+.. method:: TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='strict')
 
    Create a string buffer from a :class:`TarInfo` object. For information on the
    arguments see the constructor of the :class:`TarFile` class.
@@ -604,6 +611,21 @@
    tar.extractall()
    tar.close()
 
+How to extract a subset of a tar archive with :meth:`TarFile.extractall` using
+a generator function instead of a list::
+
+   import os
+   import tarfile
+
+   def py_files(members):
+       for tarinfo in members:
+           if os.path.splitext(tarinfo.name)[1] == ".py":
+               yield tarinfo
+
+   tar = tarfile.open("sample.tar.gz")
+   tar.extractall(members=py_files(tar))
+   tar.close()
+
 How to create an uncompressed tar archive from a list of filenames::
 
    import tarfile
@@ -626,28 +648,6 @@
            print "something else."
    tar.close()
 
-How to create a tar archive with faked information::
-
-   import tarfile
-   tar = tarfile.open("sample.tar.gz", "w:gz")
-   for name in namelist:
-       tarinfo = tar.gettarinfo(name, "fakeproj-1.0/" + name)
-       tarinfo.uid = 123
-       tarinfo.gid = 456
-       tarinfo.uname = "johndoe"
-       tarinfo.gname = "fake"
-       tar.addfile(tarinfo, file(name))
-   tar.close()
-
-The *only* way to extract an uncompressed tar stream from ``sys.stdin``::
-
-   import sys
-   import tarfile
-   tar = tarfile.open(mode="r|", fileobj=sys.stdin)
-   for tarinfo in tar:
-       tar.extract(tarinfo)
-   tar.close()
-
 
 .. _tar-formats: