Merged revisions 82871,82960-82961 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r82871 | georg.brandl | 2010-07-14 10:00:22 +0200 (Mi, 14 Jul 2010) | 1 line

  #9258: fix copy-paste errors.
........
  r82960 | georg.brandl | 2010-07-19 08:52:35 +0200 (Mo, 19 Jul 2010) | 1 line

  Clarify.
........
  r82961 | georg.brandl | 2010-07-19 08:57:52 +0200 (Mo, 19 Jul 2010) | 1 line

  Clarify :option: description.
........

Doc/documenting/markup.rst

@@ -502,8 +502,9 @@ in a different style:
 
 .. describe:: option
 
-   A command-line option to an executable program.  The leading hyphen(s) must
-   be included.
+   A command-line option of Python.  The leading hyphen(s) must be included.
+   If a matching ``cmdoption`` directive exists, it is linked to.  For options
+   of other programs or scripts, use simple ````code```` markup.
 
 .. describe:: program
 

Doc/library/io.rst

@@ -66,11 +66,11 @@ Module Interface
    Open *file* and return a corresponding stream.  If the file cannot be opened,
    an :exc:`IOError` is raised.
 
-   *file* is either a string giving the name (and the path if the file isn't
-   in the current working directory) of the file to be opened or an integer
-   file descriptor of the file to be wrapped.  (If a file descriptor is given,
-   for example, from :func:`os.fdopen`, it is closed when the returned I/O
-   object is closed, unless *closefd* is set to ``False``.)
+   *file* is either a string giving the pathname (absolute or
+   relative to the current working directory) of the file to be opened or
+   an integer file descriptor of the file to be wrapped.  (If a file descriptor
+   is given, it is closed when the returned I/O object is closed, unless
+   *closefd* is set to ``False``.)
 
    *mode* is an optional string that specifies the mode in which the file is
    opened.  It defaults to ``'r'`` which means open for reading in text mode.

Doc/library/select.rst

@@ -44,7 +44,7 @@ The module defines the following:
 
 .. function:: kqueue()
 
-   (Only supported on BSD.)  Returns a kernel queue object object; see section
+   (Only supported on BSD.)  Returns a kernel queue object; see section
    :ref:`kqueue-objects` below for the methods supported by kqueue objects.
 
    .. versionadded:: 2.6
@@ -52,8 +52,8 @@ The module defines the following:
 
 .. function:: kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)
 
-   (Only supported on BSD.)  Returns a kernel event object object; see section
-   :ref:`kevent-objects` below for the methods supported by kqueue objects.
+   (Only supported on BSD.)  Returns a kernel event object; see section
+   :ref:`kevent-objects` below for the methods supported by kevent objects.
 
    .. versionadded:: 2.6