Merged revisions 85530,85534,85538,85540-85542 via svnmerge from

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

........
  r85530 | georg.brandl | 2010-10-15 17:32:05 +0200 (Fr, 15 Okt 2010) | 1 line

  Refrain from using inline suites.
........
  r85534 | georg.brandl | 2010-10-15 18:19:43 +0200 (Fr, 15 Okt 2010) | 1 line

  #9801: document how list and dict proxies created by Managers behave w.r.t. mutable items.
........
  r85538 | georg.brandl | 2010-10-15 18:35:46 +0200 (Fr, 15 Okt 2010) | 1 line

  #7303: add documentation for useful pkgutil functions and classes.
........
  r85540 | georg.brandl | 2010-10-15 18:42:37 +0200 (Fr, 15 Okt 2010) | 1 line

  #6798: fix wrong docs for the arguments to several trace events.
........
  r85541 | georg.brandl | 2010-10-15 18:53:24 +0200 (Fr, 15 Okt 2010) | 1 line

  #4968: updates to inspect.is* function docs.
........
  r85542 | georg.brandl | 2010-10-15 19:01:15 +0200 (Fr, 15 Okt 2010) | 1 line

  #7790: move table of struct_time members to the actual description of struct_time.
........

1 files changed, 50 insertions, 44 deletions

diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index c38b0e0..d6efcee 100644
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -17,21 +17,23 @@ semantics of these functions varies among platforms.
 
 An explanation of some terminology and conventions is in order.
 
-  .. index:: single: epoch
+.. index:: single: epoch
 
 * The :dfn:`epoch` is the point where the time starts.  On January 1st of that
   year, at 0 hours, the "time since the epoch" is zero.  For Unix, the epoch is
   1970.  To find out what the epoch is, look at ``gmtime(0)``.
 
-  .. index:: single: Year 2038
+.. index:: single: Year 2038
 
 * The functions in this module do not handle dates and times before the epoch or
   far in the future.  The cut-off point in the future is determined by the C
   library; for Unix, it is typically in 2038.
 
-  .. index::
-     single: Year 2000
-     single: Y2K
+.. index::
+   single: Year 2000
+   single: Y2K
+
+.. _time-y2kissues:
 
 * **Year 2000 (Y2K) issues**:  Python depends on the platform's C library, which
   generally doesn't have year 2000 issues, since all dates and times are
@@ -48,16 +50,16 @@ An explanation of some terminology and conventions is in order.
   Note that this is new as of Python 1.5.2(a2); earlier versions, up to Python
   1.5.1 and 1.5.2a1, would add 1900 to year values below 1900.
 
-  .. index::
-     single: UTC
-     single: Coordinated Universal Time
-     single: Greenwich Mean Time
+.. index::
+   single: UTC
+   single: Coordinated Universal Time
+   single: Greenwich Mean Time
 
 * UTC is Coordinated Universal Time (formerly known as Greenwich Mean Time, or
   GMT).  The acronym UTC is not a mistake but a compromise between English and
   French.
 
-  .. index:: single: Daylight Saving Time
+.. index:: single: Daylight Saving Time
 
 * DST is Daylight Saving Time, an adjustment of the timezone by (usually) one
   hour during part of the year.  DST rules are magic (determined by local law) and
@@ -82,38 +84,7 @@ An explanation of some terminology and conventions is in order.
   values of :func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer
   attribute names for individual fields.
 
-  +-------+-------------------+---------------------------------+
-  | Index | Attribute         | Values                          |
-  +=======+===================+=================================+
-  | 0     | :attr:`tm_year`   | (for example, 1993)             |
-  +-------+-------------------+---------------------------------+
-  | 1     | :attr:`tm_mon`    | range [1, 12]                   |
-  +-------+-------------------+---------------------------------+
-  | 2     | :attr:`tm_mday`   | range [1, 31]                   |
-  +-------+-------------------+---------------------------------+
-  | 3     | :attr:`tm_hour`   | range [0, 23]                   |
-  +-------+-------------------+---------------------------------+
-  | 4     | :attr:`tm_min`    | range [0, 59]                   |
-  +-------+-------------------+---------------------------------+
-  | 5     | :attr:`tm_sec`    | range [0, 61]; see **(1)** in   |
-  |       |                   | :func:`strftime` description    |
-  +-------+-------------------+---------------------------------+
-  | 6     | :attr:`tm_wday`   | range [0, 6], Monday is 0       |
-  +-------+-------------------+---------------------------------+
-  | 7     | :attr:`tm_yday`   | range [1, 366]                  |
-  +-------+-------------------+---------------------------------+
-  | 8     | :attr:`tm_isdst`  | 0, 1 or -1; see below           |
-  +-------+-------------------+---------------------------------+
-
-  Note that unlike the C structure, the month value is a range of [1, 12],
-  not [0, 11].
-  A year value will be handled as described under "Year 2000 (Y2K) issues" above.
-  A ``-1`` argument as the daylight savings flag, passed to :func:`mktime` will
-  usually result in the correct daylight savings state to be filled in.
-
-  When a tuple with an incorrect length is passed to a function expecting a
-  :class:`struct_time`, or having elements of the wrong type, a :exc:`TypeError`
-  is raised.
+  See :class:`struct_time` for a description of these objects.
 
   .. versionchanged:: 2.2
      The time value sequence was changed from a tuple to a :class:`struct_time`, with
@@ -419,13 +390,48 @@ The module defines the following functions and data items:
    documented as supported.
 
 
-.. data:: struct_time
+.. class:: struct_time
 
    The type of the time value sequence returned by :func:`gmtime`,
-   :func:`localtime`, and :func:`strptime`.
+   :func:`localtime`, and :func:`strptime`.  It is an object with a :term:`named
+   tuple` interface: values can be accessed by index and by attribute name.  The
+   following values are present:
+
+   +-------+-------------------+---------------------------------+
+   | Index | Attribute         | Values                          |
+   +=======+===================+=================================+
+   | 0     | :attr:`tm_year`   | (for example, 1993)             |
+   +-------+-------------------+---------------------------------+
+   | 1     | :attr:`tm_mon`    | range [1, 12]                   |
+   +-------+-------------------+---------------------------------+
+   | 2     | :attr:`tm_mday`   | range [1, 31]                   |
+   +-------+-------------------+---------------------------------+
+   | 3     | :attr:`tm_hour`   | range [0, 23]                   |
+   +-------+-------------------+---------------------------------+
+   | 4     | :attr:`tm_min`    | range [0, 59]                   |
+   +-------+-------------------+---------------------------------+
+   | 5     | :attr:`tm_sec`    | range [0, 61]; see **(1)** in   |
+   |       |                   | :func:`strftime` description    |
+   +-------+-------------------+---------------------------------+
+   | 6     | :attr:`tm_wday`   | range [0, 6], Monday is 0       |
+   +-------+-------------------+---------------------------------+
+   | 7     | :attr:`tm_yday`   | range [1, 366]                  |
+   +-------+-------------------+---------------------------------+
+   | 8     | :attr:`tm_isdst`  | 0, 1 or -1; see below           |
+   +-------+-------------------+---------------------------------+
 
    .. versionadded:: 2.2
 
+   Note that unlike the C structure, the month value is a range of [1, 12], not
+   [0, 11].  A year value will be handled as described under :ref:`Year 2000
+   (Y2K) issues <time-y2kissues>` above.  A ``-1`` argument as the daylight
+   savings flag, passed to :func:`mktime` will usually result in the correct
+   daylight savings state to be filled in.
+
+   When a tuple with an incorrect length is passed to a function expecting a
+   :class:`struct_time`, or having elements of the wrong type, a
+   :exc:`TypeError` is raised.
+
 
 .. function:: time()