4 files changed, 24 insertions, 6 deletions
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 49c2abe3e3..fdacabb5a2 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -633,7 +633,7 @@ Text I/O
 
 .. class:: StringIO([initial_value[, encoding[, errors[, newline]]]])
 
-   An in-memory stream for text.  It in inherits :class:`TextIOWrapper`.
+   An in-memory stream for text.  It inherits :class:`TextIOWrapper`.
 
    Create a new StringIO stream with an inital value, encoding, error handling,
    and newline setting.  See :class:`TextIOWrapper`\'s constructor for more
diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst
index 3c98a1eeba..cd90c389c3 100644
--- a/Doc/library/platform.rst
+++ b/Doc/library/platform.rst
@@ -234,7 +234,15 @@ Unix Platforms
 
 .. function:: dist(distname='', version='', id='', supported_dists=('SuSE','debian','redhat','mandrake',...))
 
-   This is another name for :func:`linux_distribution`.
+   This is an old version of the functionality now provided by
+   :func:`linux_distribution`. For new code, please use the
+   :func:`linux_distribution`.
+
+   The only difference between the two is that ``dist()`` always
+   returns the short name of the distribution taken from the
+   ``supported_dists`` parameter.
+
+   .. deprecated:: 2.6
 
 .. function:: linux_distribution(distname='', version='', id='', supported_dists=('SuSE','debian','redhat','mandrake',...), full_distribution_name=1)
 
@@ -252,6 +260,8 @@ Unix Platforms
    parameters.  ``id`` is the item in parentheses after the version number.  It
    is usually the version codename.
 
+   .. versionadded:: 2.6
+
 .. function:: libc_ver(executable=sys.executable, lib='', version='', chunksize=2048)
 
    Tries to determine the libc version against which the file executable (defaults
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index a435b82012..d1b107ecc6 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -731,12 +731,13 @@ correspond to Unix system calls applicable to sockets.
 
 Some notes on socket blocking and timeouts: A socket object can be in one of
 three modes: blocking, non-blocking, or timeout.  Sockets are always created in
-blocking mode.  In blocking mode, operations block until complete.  In
+blocking mode.  In blocking mode, operations block until complete or
+the system returns an error (such as connection timed out).  In
 non-blocking mode, operations fail (with an error that is unfortunately
 system-dependent) if they cannot be completed immediately.  In timeout mode,
 operations fail if they cannot be completed within the timeout specified for the
-socket.  The :meth:`setblocking` method is simply a shorthand for certain
-:meth:`settimeout` calls.
+socket or if the system returns an error.  The :meth:`setblocking` method is simply
+a shorthand for certain :meth:`settimeout` calls.
 
 Timeout mode internally sets the socket in non-blocking mode.  The blocking and
 timeout modes are shared between file descriptors and socket objects that refer
@@ -747,7 +748,9 @@ completed immediately will fail.
 
 Note that the :meth:`connect` operation is subject to the timeout setting, and
 in general it is recommended to call :meth:`settimeout` before calling
-:meth:`connect`.
+:meth:`connect` or pass a timeout parameter to :meth:`create_connection`.
+The system network stack may return a connection timeout error
+of its own regardless of any python socket timeout setting.
 
 
 .. method:: socket.setsockopt(level, optname, value)
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 4069d07aba..3417970dcb 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -2114,6 +2114,11 @@ Files have the following methods:
    Flush the internal buffer, like ``stdio``'s :cfunc:`fflush`.  This may be a
    no-op on some file-like objects.
 
+   .. note::
+
+      :meth:`flush` does not necessarily write the file's data to disk.  Use
+      :meth:`flush` followed by :func:`os.fsync` to ensure this behavior.
+
 
 .. method:: file.fileno()