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

1 files changed, 16 insertions, 2 deletions

diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 01406e0..0e7f376 100644
--- 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