--- rest25/library/time.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/time.rst	2009-04-07 00:06:53.000000000 +0900
@@ -1,22 +1,25 @@
 
 :mod:`time` --- Time access and conversions
 ===========================================
 
 .. module:: time
    :synopsis: Time access and conversions.
 
 
-This module provides various time-related functions.  It is always available,
-but not all functions are available on all platforms.  Most of the functions
+This module provides various time-related functions. For related
+functionality, see also the :mod:`datetime` and :mod:`calendar` modules.
+
+Although this module is always available,
+not all functions are available on all platforms.  Most of the functions
 defined in this module call platform C library functions with the same name.  It
 may sometimes be helpful to consult the platform documentation, because the
 semantics of these functions varies among platforms.
 
 An explanation of some terminology and conventions is in order.
 
   .. 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)``.
 
@@ -55,78 +58,95 @@
   French.
 
   .. 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
   can change from year to year.  The C library has a table containing the local
   rules (often it is read from a system file for flexibility) and is the only
   source of True Wisdom in this respect.
 
 * The precision of the various real-time functions may be less than suggested by
   the units in which their value or argument is expressed. E.g. on most Unix
-  systems, the clock "ticks" only 50 or 100 times a second, and on the Mac, times
-  are only accurate to whole seconds.
+  systems, the clock "ticks" only 50 or 100 times a second.
 
 * On the other hand, the precision of :func:`time` and :func:`sleep` is better
   than their Unix equivalents: times are expressed as floating point numbers,
   :func:`time` returns the most accurate time available (using Unix
   :cfunc:`gettimeofday` where available), and :func:`sleep` will accept a time
   with a nonzero fraction (Unix :cfunc:`select` is used to implement this, where
   available).
 
 * The time value as returned by :func:`gmtime`, :func:`localtime`, and
   :func:`strptime`, and accepted by :func:`asctime`, :func:`mktime` and
-  :func:`strftime`, is a sequence of 9 integers.  The return values of
-  :func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer attribute
-  names for individual fields.
+  :func:`strftime`, may be considered as a sequence of 9 integers.  The return
+  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        |
-  +-------+------------------+------------------------------+
+
+  +-------+-------------------+---------------------------------+
+  | 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.
 
   .. versionchanged:: 2.2
      The time value sequence was changed from a tuple to a :class:`struct_time`, with
      the addition of attribute names for the fields.
 
+* Use the following functions to convert between time representations:
 
+  +-------------------------+-------------------------+-------------------------+
+  | From                    | To                      | Use                     |
+  +=========================+=========================+=========================+
+  | seconds since the epoch | :class:`struct_time` in | :func:`gmtime`          |
+  |                         | UTC                     |                         |
+  +-------------------------+-------------------------+-------------------------+
+  | seconds since the epoch | :class:`struct_time` in | :func:`localtime`       |
+  |                         | local time              |                         |
+  +-------------------------+-------------------------+-------------------------+
+  | :class:`struct_time` in | seconds since the epoch | :func:`calendar.timegm` |
+  | UTC                     |                         |                         |
+  +-------------------------+-------------------------+-------------------------+
+  | :class:`struct_time` in | seconds since the epoch | :func:`mktime`          |
+  | local time              |                         |                         |
+  +-------------------------+-------------------------+-------------------------+
+
+
-The module defines the following functions and data items:
+The module defines the following functions and data items:
 
 .. data:: accept2dyear
 
    Boolean value indicating whether two-digit year values will be accepted.  This
    is true by default, but will be set to false if the environment variable
    :envvar:`PYTHONY2K` has been set to a non-empty string.  It may also be modified
    at run time.
 
 
 .. data:: altzone
 
    The offset of the local DST timezone, in seconds west of UTC, if one is defined.
@@ -361,38 +381,51 @@
    Additional directives may be supported on certain platforms, but only the ones
    listed here have a meaning standardized by ANSI C.
 
    On some platforms, an optional field width and precision specification can
    immediately follow the initial ``'%'`` of a directive in the following order;
    this is also not portable. The field width is normally 2 except for ``%j`` where
    it is 3.
 
 
 .. function:: strptime(string[, format])
 
    Parse a string representing a time according to a format.  The return  value is
-   a :class:`struct_time` as returned by :func:`gmtime` or :func:`localtime`.  The
+   a :class:`struct_time` as returned by :func:`gmtime` or :func:`localtime`.
-   *format* parameter uses the same directives as those used by :func:`strftime`;
-   it defaults to ``"%a %b %d %H:%M:%S %Y"`` which matches the formatting returned
-   by :func:`ctime`.  If *string* cannot be parsed according to *format*,
+   The *format* parameter uses the same directives as those used by
+   :func:`strftime`; it defaults to ``"%a %b %d %H:%M:%S %Y"`` which matches the
+   formatting returned by :func:`ctime`. If *string* cannot be parsed according to
-   :exc:`ValueError` is raised.  If the string to be parsed has excess data after
-   parsing, :exc:`ValueError` is raised.  The default values used to fill in any
-   missing data when more accurate values cannot be inferred are ``(1900, 1, 1, 0,
-   0, 0, 0, 1, -1)`` .
+
+   *format*, or if it has excess data after parsing, :exc:`ValueError` is raised.
+   The default values used to fill in any missing data when more accurate values
+   cannot be inferred are ``(1900, 1, 1, 0, 0, 0, 0, 1, -1)``.
+
+   For example:
+
+      >>> import time
+      >>> time.strptime("30 Nov 00", "%d %b %y")   # doctest: +NORMALIZE_WHITESPACE
+      time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,
+                       tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)
 
    Support for the ``%Z`` directive is based on the values contained in ``tzname``
    and whether ``daylight`` is true.  Because of this, it is platform-specific
    except for recognizing UTC and GMT which are always known (and are considered to
    be non-daylight savings timezones).
 
+   Only the directives specified in the documentation are supported.  Because
+   ``strftime()`` is implemented per platform it can sometimes offer more
+   directives than those listed.  But ``strptime()`` is independent of any platform
+   and thus does not necessarily support all directives available that are not
+   documented as supported.
+
 
 .. data:: struct_time
 
    The type of the time value sequence returned by :func:`gmtime`,
    :func:`localtime`, and :func:`strptime`.
 
    .. versionadded:: 2.2
 
 
 .. function:: time()
 
    Return the time as a floating point number expressed in seconds since the epoch,
@@ -424,62 +457,62 @@
    .. versionadded:: 2.3
 
    Availability: Unix.
 
    .. note::
 
       Although in many cases, changing the :envvar:`TZ` environment variable may
       affect the output of functions like :func:`localtime` without calling
       :func:`tzset`, this behavior should not be relied on.
 
       The :envvar:`TZ` environment variable should contain no whitespace.
 
-   The standard format of the :envvar:`TZ` environment variable is: (whitespace
-   added for clarity)
+   The standard format of the :envvar:`TZ` environment variable is (whitespace
+   added for clarity)::
 
-   std offset [dst [offset
-      [,start[/time], end[/time]]]]
+      std offset [dst [offset [,start[/time], end[/time]]]]
 
-   Where:
+   Where the components are:
 
-   std and dst
+   ``std`` and ``dst``
       Three or more alphanumerics giving the timezone abbreviations. These will be
       propagated into time.tzname
 
-   offset
-      The offset has the form: ± hh[:mm[:ss]]. This indicates the value added the
-      local time to arrive at UTC.  If preceded by a '-', the timezone is east of the
-      Prime  Meridian; otherwise, it is west. If no offset follows dst, summer time is
-      assumed to be one hour ahead of standard time.
+   ``offset``
+      The offset has the form: ``± hh[:mm[:ss]]``. This indicates the value
+      added the local time to arrive at UTC.  If preceded by a '-', the timezone
+      is east of the Prime Meridian; otherwise, it is west. If no offset follows
+      dst, summer time is assumed to be one hour ahead of standard time.
 
-   start[/time
-      ,end[/time]] Indicates when to change to and back from DST. The format of the
+   ``start[/time], end[/time]``
+      Indicates when to change to and back from DST. The format of the
       start and end dates are one of the following:
 
-      J*n*
-         The Julian day *n* (1 <= *n* <= 365). Leap days are not  counted, so in all
-         years February 28 is day 59 and March 1 is day 60.
-
-      *n*
-         The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and it is
-         possible to refer to February 29.
-
-      M*m*.*n*.*d*
-         The *d*'th day (0 <= *d* <= 6) or week *n*  of month *m* of the year (1 <= *n*
-         <= 5,  1 <= *m* <= 12, where week 5 means "the last *d* day in month *m*" which
-         may occur in either the fourth or  the fifth week). Week 1 is the first week in
-         which the  *d*'th day occurs. Day zero is Sunday.
+      :samp:`J{n}`
+         The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in
+         all years February 28 is day 59 and March 1 is day 60.
+
+      :samp:`{n}`
+         The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and
+         it is possible to refer to February 29.
+
+      :samp:`M{m}.{n}.{d}`
+         The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1
+         <= *n* <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in
+         month *m*" which may occur in either the fourth or the fifth
+         week). Week 1 is the first week in which the *d*'th day occurs. Day
+         zero is Sunday.
 
-      time has the same format as offset except that no leading sign ('-' or '+') is
-      allowed. The default, if time is not given, is 02:00:00.
+      ``time`` has the same format as ``offset`` except that no leading sign
+      ('-' or '+') is allowed. The default, if time is not given, is 02:00:00.
 
    ::
 
       >>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
       >>> time.tzset()
       >>> time.strftime('%X %x %Z')
       '02:07:36 05/08/03 EDT'
       >>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
       >>> time.tzset()
       >>> time.strftime('%X %x %Z')
       '16:08:12 05/08/03 AEST'
 
