Update sys.platform doc for #12326.

Backport from Python 3.2 (e11b4c945f7e).

1 files changed, 28 insertions, 18 deletions

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 6df371f..4afef5a 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -709,28 +709,38 @@ always available.
    This string contains a platform identifier that can be used to append
    platform-specific components to :data:`sys.path`, for instance.
 
-   For Unix systems, this is the lowercased OS name as returned by ``uname -s``
-   with the first part of the version as returned by ``uname -r`` appended,
-   e.g. ``'sunos5'`` or ``'linux2'``, *at the time when Python was built*.
-   Unless you want to test for a specific system version, it is therefore
-   recommended to use the following idiom::
-
-      if sys.platform.startswith('linux'):
+   For most Unix systems, this is the lowercased OS name as returned by ``uname
+   -s`` with the first part of the version as returned by ``uname -r`` appended,
+   e.g. ``'sunos5'``, *at the time when Python was built*.  Unless you want to
+   test for a specific system version, it is therefore recommended to use the
+   following idiom::
+
+      if sys.platform.startswith('freebsd'):
+          # FreeBSD-specific code here...
+      elif sys.platform.startswith('linux'):
           # Linux-specific code here...
 
+   .. versionchanged:: 2.7.3
+      Since lots of code check for ``sys.platform == 'linux2'``, and there is
+      no essential change between Linux 2.x and 3.x, ``sys.platform`` is always
+      set to ``'linux2'``, even on Linux 3.x.  In Python 3.3 and later, the
+      value will always be set to ``'linux'``, so it is recommended to always
+      use the ``startswith`` idiom presented above.
+
    For other systems, the values are:
 
-   ================ ===========================
-   System           :data:`platform` value
-   ================ ===========================
-   Windows          ``'win32'``
-   Windows/Cygwin   ``'cygwin'``
-   Mac OS X         ``'darwin'``
-   OS/2             ``'os2'``
-   OS/2 EMX         ``'os2emx'``
-   RiscOS           ``'riscos'``
-   AtheOS           ``'atheos'``
-   ================ ===========================
+   ===================== ===========================
+   System                :data:`platform` value
+   ===================== ===========================
+   Linux (2.x *and* 3.x) ``'linux2'``
+   Windows               ``'win32'``
+   Windows/Cygwin        ``'cygwin'``
+   Mac OS X              ``'darwin'``
+   OS/2                  ``'os2'``
+   OS/2 EMX              ``'os2emx'``
+   RiscOS                ``'riscos'``
+   AtheOS                ``'atheos'``
+   ===================== ===========================
 
    .. seealso::
       :attr:`os.name` has a coarser granularity.  :func:`os.uname` gives