#1718017: document the relation of os.path and the posixpath, ntpath etc. modules...

diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 01406e06b3ff7246e72367c2bff052e887ff48a7..0e7f3765168837cb52699cad14a510eb001c978f 100644 (file)
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -1,11 +1,9 @@
-
 :mod:`os.path` --- Common pathname manipulations
 ================================================
 
 .. module:: os.path
    :synopsis: Operations on pathnames.
 
-
 .. index:: single: path; operations
 
 This module implements some useful functions on pathnames. To read or
@@ -18,6 +16,22 @@ write files see :func:`open`, and for accessing the filesystem see the
    :func:`splitunc` and :func:`ismount` do handle them correctly.
 
 
+.. note::
+
+   Since different operating systems have different path name conventions, there
+   are several versions of this module in the standard library.  The
+   :mod:`os.path` module is always the path module suitable for the operating
+   system Python is running on, and therefore usable for local paths.  However,
+   you can also import and use the individual modules if you want to manipulate
+   a path that is *always* in one of the different formats.  They all have the
+   same interface:
+
+   * :mod:`posixpath` for UNIX-style paths
+   * :mod:`ntpath` for Windows paths
+   * :mod:`macpath` for old-style MacOS paths
+   * :mod:`os2emxpath` for OS/2 EMX paths
+
+
 .. function:: abspath(path)
 
    Return a normalized absolutized version of the pathname *path*. On most

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 4ea6c7f5b3265269dd0db48e2401991e8c8df772..061f1ce408f824c47767a4467bf9151dba12167e 100644 (file)
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -46,15 +46,6 @@ the :mod:`os` module, but using them is of course a threat to portability!
    ``'ce'``, ``'java'``, ``'riscos'``.
 
 
-.. data:: path
-
-   The corresponding operating system dependent standard module for pathname
-   operations, such as :mod:`posixpath` or :mod:`ntpath`.  Thus, given the proper
-   imports, ``os.path.split(file)`` is equivalent to but more portable than
-   ``posixpath.split(file)``.  Note that this is also an importable module: it may
-   be imported directly as :mod:`os.path`.
-
-
 .. _os-procinfo:
 
 Process Parameters