Move OSError docs to exceptions doc, remove obsolete descriptions

from os docs, rework posix docs.

3 files changed, 44 insertions, 65 deletions

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 6122d44..1d85ddf 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -233,11 +233,24 @@ The following exceptions are the exceptions that are actually raised.
 
 .. exception:: OSError
 
-   This class is derived from :exc:`EnvironmentError` and is used primarily as the
-   :mod:`os` module's ``os.error`` exception. See :exc:`EnvironmentError` above for
-   a description of the possible associated values.
+    and is used primarily as
+   the :mod:`os` module's :exc:`os.error` exception.  See :exc:`EnvironmentError`
+   above for a description of the possible associated values.
 
    .. versionadded:: 1.5.2
+   .. index:: module: errno
+
+   This exception is derived from :exc:`EnvironmentError`.  It is raised when a
+   function returns a system-related error (not for illegal argument types or
+   other incidental errors).  The :attr:`errno` attribute is a numeric error
+   code from :cdata:`errno`, and the :attr:`strerror` attribute is the
+   corresponding string, as would be printed by the C function :cfunc:`perror`.
+   See the module :mod:`errno`, which contains names for the error codes defined
+   by the underlying operating system.
+
+   For exceptions that involve a file system path (such as :func:`chdir` or
+   :func:`unlink`), the exception instance will contain a third attribute,
+   :attr:`filename`, which is the file name passed to the function.
 
 
 .. exception:: OverflowError
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 06a82ec..b39ec1b 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1,4 +1,3 @@
-
 :mod:`os` --- Miscellaneous operating system interfaces
 =======================================================
 
@@ -6,54 +5,33 @@
    :synopsis: Miscellaneous operating system interfaces.
 
 
-This module provides a more portable way of using operating system dependent
-functionality than importing an operating system dependent built-in module like
-:mod:`posix` or :mod:`nt`. If you just want to read or write a file see
-:func:`open`, if you want to manipulate paths, see the :mod:`os.path`
-module, and if you want to read all the lines in all the files on the
-command line see the :mod:`fileinput` module. For creating temporary
-files and directories see the :mod:`tempfile` module, and for high-level
-file and directory handling see the :mod:`shutil` module.
-
-This module searches for an operating system dependent built-in module like
-:mod:`mac` or :mod:`posix` and exports the same functions and data as found
-there.  The design of all built-in operating system dependent modules of Python
-is such that as long as the same functionality is available, it uses the same
-interface; for example, the function ``os.stat(path)`` returns stat information
-about *path* in the same format (which happens to have originated with the POSIX
+This module provides a portable way of using operating system dependent
+functionality.  If you just want to read or write a file see :func:`open`, if
+you want to manipulate paths, see the :mod:`os.path` module, and if you want to
+read all the lines in all the files on the command line see the :mod:`fileinput`
+module.  For creating temporary files and directories see the :mod:`tempfile`
+module, and for high-level file and directory handling see the :mod:`shutil`
+module.
+
+The design of all built-in operating system dependent modules of Python is such
+that as long as the same functionality is available, it uses the same interface;
+for example, the function ``os.stat(path)`` returns stat information about
+*path* in the same format (which happens to have originated with the POSIX
 interface).
 
 Extensions peculiar to a particular operating system are also available through
 the :mod:`os` module, but using them is of course a threat to portability!
 
-Note that after the first time :mod:`os` is imported, there is *no* performance
-penalty in using functions from :mod:`os` instead of directly from the operating
-system dependent built-in module, so there should be *no* reason not to use
-:mod:`os`!
+.. note::
 
-The :mod:`os` module contains many functions and data values. The items below
-and in the following sub-sections are all available directly from the :mod:`os`
-module.
+   All functions in this module raise :exc:`OSError` in the case of invalid or
+   inaccessible file names and paths, or other arguments that have the correct
+   type, but are not accepted by the operating system.
 
 
 .. exception:: error
 
-   .. index:: module: errno
-
-   This exception is raised when a function returns a system-related error (not for
-   illegal argument types or other incidental errors). This is also known as the
-   built-in exception :exc:`OSError`.  The accompanying value is a pair containing
-   the numeric error code from :cdata:`errno` and the corresponding string, as
-   would be printed by the C function :cfunc:`perror`.  See the module
-   :mod:`errno`, which contains names for the error codes defined by the underlying
-   operating system.
-
-   When exceptions are classes, this exception carries two attributes,
-   :attr:`errno` and :attr:`strerror`.  The first holds the value of the C
-   :cdata:`errno` variable, and the latter holds the corresponding error message
-   from :cfunc:`strerror`.  For exceptions that involve a file system path (such as
-   :func:`chdir` or :func:`unlink`), the exception instance will contain a third
-   attribute, :attr:`filename`, which is the file name passed to the function.
+   An alias for the built-in :exc:`OSError` exception.
 
 
 .. data:: name
@@ -748,7 +726,6 @@ platforms.  For descriptions of their availability and use, consult
 Files and Directories
 ---------------------
 
-
 .. function:: access(path, mode)
 
    Use the real uid/gid to test for access to *path*.  Note that most operations
@@ -2032,8 +2009,8 @@ Miscellaneous System Information
 
 .. function:: getloadavg()
 
-   Return the number of processes in the system run queue averaged over the last 1,
-   5, and 15 minutes or raises :exc:`OSError` if the load  average was
+   Return the number of processes in the system run queue averaged over the last
+   1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
    unobtainable.
 
    .. versionadded:: 2.3
diff --git a/Doc/library/posix.rst b/Doc/library/posix.rst
index 2074e45..8c8ddde 100644
--- a/Doc/library/posix.rst
+++ b/Doc/library/posix.rst
@@ -1,4 +1,3 @@
-
 :mod:`posix` --- The most common POSIX system calls
 ===================================================
 
@@ -22,13 +21,8 @@ available through the :mod:`os` interface.  Once :mod:`os` is imported, there is
 :mod:`os` provides some additional functionality, such as automatically calling
 :func:`putenv` when an entry in ``os.environ`` is changed.
 
-The descriptions below are very terse; refer to the corresponding Unix manual
-(or POSIX documentation) entry for more information. Arguments called *path*
-refer to a pathname given as a string.
-
 Errors are reported as exceptions; the usual exceptions are given for type
-errors, while errors reported by the system calls raise :exc:`error` (a synonym
-for the standard exception :exc:`OSError`), described below.
+errors, while errors reported by the system calls raise :exc:`OSError`.
 
 
 .. _posix-large-files:
@@ -42,9 +36,8 @@ Large File Support
 
 .. sectionauthor:: Steve Clift <clift@mail.anacapa.net>
 
-
-Several operating systems (including AIX, HPUX, Irix and Solaris) provide
-support for files that are larger than 2 Gb from a C programming model where
+Several operating systems (including AIX, HP-UX, Irix and Solaris) provide
+support for files that are larger than 2 GB from a C programming model where
 :ctype:`int` and :ctype:`long` are 32-bit values. This is typically accomplished
 by defining the relevant size and offset types as 64-bit values. Such files are
 sometimes referred to as :dfn:`large files`.
@@ -68,16 +61,16 @@ On large-file-capable Linux systems, this might work::
 
 .. _posix-contents:
 
-Module Contents
----------------
-
-Module :mod:`posix` defines the following data item:
+Notable Module Contents
+-----------------------
 
+In addition to many functions described in the :mod:`os` module documentation,
+:mod:`posix` defines the following data item:
 
 .. data:: environ
 
-   A dictionary representing the string environment at the time the interpreter was
-   started. For example, ``environ['HOME']`` is the pathname of your home
+   A dictionary representing the string environment at the time the interpreter
+   was started.  For example, ``environ['HOME']`` is the pathname of your home
    directory, equivalent to ``getenv("HOME")`` in C.
 
    Modifying this dictionary does not affect the string environment passed on by
@@ -91,7 +84,3 @@ Module :mod:`posix` defines the following data item:
       updates the environment on modification.  Note also that updating ``os.environ``
       will render this dictionary obsolete.  Use of the :mod:`os` module version of
       this is recommended over direct access to the :mod:`posix` module.
-
-Additional contents of this module should only be accessed via the :mod:`os`
-module; refer to the documentation for that module for further information.
-