Merged revisions 85548,85572-85573,85606,85609-85612,85614-85616 via svnmerge from

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

........
  r85548 | georg.brandl | 2010-10-15 21:46:19 +0200 (Fr, 15 Okt 2010) | 1 line

  #10072: assume a bit less knowledge of the FTP protocol in the ftplib docs.
........
  r85572 | georg.brandl | 2010-10-16 20:51:05 +0200 (Sa, 16 Okt 2010) | 1 line

  #10122: typo fix.
........
  r85573 | georg.brandl | 2010-10-16 20:53:08 +0200 (Sa, 16 Okt 2010) | 1 line

  #10124: typo fix.
........
  r85606 | georg.brandl | 2010-10-17 08:32:59 +0200 (So, 17 Okt 2010) | 1 line

  #10058: tweak wording about exception returns.
........
  r85609 | georg.brandl | 2010-10-17 11:19:03 +0200 (So, 17 Okt 2010) | 1 line

  #8556: use less confusing mapping key in example.
........
  r85610 | georg.brandl | 2010-10-17 11:23:05 +0200 (So, 17 Okt 2010) | 1 line

  #8686: remove potentially confusing wording that does not add any value.
........
  r85611 | georg.brandl | 2010-10-17 11:33:24 +0200 (So, 17 Okt 2010) | 1 line

  #8811: small fixes to sqlite3 docs.
........
  r85612 | georg.brandl | 2010-10-17 11:37:54 +0200 (So, 17 Okt 2010) | 1 line

  #8855: add shelve security warning.
........
  r85614 | georg.brandl | 2010-10-17 11:46:11 +0200 (So, 17 Okt 2010) | 1 line

  #8968: add actual name of token constants.
........
  r85615 | georg.brandl | 2010-10-17 12:05:13 +0200 (So, 17 Okt 2010) | 1 line

  #459007: merge info from PC/getpathp.c and using/windows.rst to document the forming of sys.path under Windows.
........
  r85616 | georg.brandl | 2010-10-17 12:07:29 +0200 (So, 17 Okt 2010) | 1 line

  Fix copy-paste error in example.
........

1 files changed, 19 insertions, 14 deletions

diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index 4b25d85..b6db983 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -91,18 +91,21 @@ The module defines the following items:
 
 .. exception:: error_temp
 
-   Exception raised when an error code in the range 400--499 is received.
+   Exception raised when an error code signifying a temporary error (response
+   codes in the range 400--499) is received.
 
 
 .. exception:: error_perm
 
-   Exception raised when an error code in the range 500--599 is received.
+   Exception raised when an error code signifying a permanent error (response
+   codes in the range 500--599) is received.
 
 
 .. exception:: error_proto
 
-   Exception raised when a reply is received from the server that does not
-   begin with a digit in the range 1--5.
+   Exception raised when a reply is received from the server that does not fit
+   the response specifications of the File Transfer Protocol, i.e. begin with a
+   digit in the range 1--5.
 
 
 .. data:: all_errors
@@ -198,9 +201,9 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
 
 .. method:: FTP.voidcmd(command)
 
-   Send a simple command string to the server and handle the response. Return
-   nothing if a response code in the range 200--299 is received. Raise an exception
-   otherwise.
+   Send a simple command string to the server and handle the response.  Return
+   nothing if a response code corresponding to success (codes in the range
+   200--299) is received.  Raise :exc:`error_reply` otherwise.
 
 
 .. method:: FTP.retrbinary(command, callback[, maxblocksize[, rest]])
@@ -220,9 +223,11 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
    Retrieve a file or directory listing in ASCII transfer mode.  *command*
    should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or a
    command such as ``LIST``, ``NLST`` or ``MLSD`` (usually just the string
-   ``'LIST'``).  The *callback* function is called for each line with a
-   string argument containing the line with the trailing CRLF stripped.
-   The default *callback* prints the line to ``sys.stdout``.
+   ``'LIST'``).  ``LIST`` retrieves a list of files and information about those files.
+   ``NLST`` retrieves a list of file names.  On some servers, ``MLSD`` retrieves
+   a machine readable list of files and information about those files.  The *callback*
+   function is called for each line with a string argument containing the line with
+   the trailing CRLF stripped.  The default *callback* prints the line to ``sys.stdout``.
 
 
 .. method:: FTP.set_pasv(boolean)
@@ -293,10 +298,10 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
 
 .. method:: FTP.nlst(argument[, ...])
 
-   Return a list of files as returned by the ``NLST`` command.  The optional
-   *argument* is a directory to list (default is the current server directory).
-   Multiple arguments can be used to pass non-standard options to the ``NLST``
-   command.
+   Return a list of file names as returned by the ``NLST`` command.  The
+   optional *argument* is a directory to list (default is the current server
+   directory).  Multiple arguments can be used to pass non-standard options to
+   the ``NLST`` command.
 
 
 .. method:: FTP.dir(argument[, ...])