--- a/Doc/lib/libdatetime.tex	Mon Jan 20 16:54:59 2003 +0000
+++ b/Doc/lib/libdatetime.tex	Mon Jan 20 22:54:38 2003 +0000
@@ -30,7 +30,7 @@
 
 For applications requiring more, \class{datetime} and \class{time}
 objects have an optional time zone information member,
-\member{tzinfo}, that can contain an instance of a subclass of 
+\member{tzinfo}, that can contain an instance of a subclass of
 the abstract \class{tzinfo} class.  These \class{tzinfo} objects
 capture information about the offset from UTC time, the time zone
 name, and whether Daylight Saving Time is in effect.  Note that no
@@ -1048,9 +1048,11 @@
 
     If \method{utcoffset()} does not return \code{None},
     \method{dst()} should not return \code{None} either.
+
+    The default implementation of \method{utcoffset()} raises
+    \exception{NotImplementedError}.
 \end{methoddesc}
 
-
 \begin{methoddesc}{dst}{self, dt}
   Return the daylight saving time (DST) adjustment, in minutes east of
   UTC, or \code{None} if DST information isn't known.  Return \code{0} if
@@ -1060,7 +1062,7 @@
   Note that DST offset, if applicable, has
   already been added to the UTC offset returned by
   \method{utcoffset()}, so there's no need to consult \method{dst()}
-  unless you're interested in displaying DST info separately.  For
+  unless you're interested in obtaining DST info separately.  For
   example, \method{datetime.timetuple()} calls its \member{tzinfo}
   member's \method{dst()} method to determine how the
   \member{tm_isdst} flag should be set, and
@@ -1080,6 +1082,10 @@
   cannot detect violations; it's the programmer's responsibility to
   ensure it.
 
+  The default implementation of \method{dst()} raises
+  \exception{NotImplementedError}.
+\end{methoddesc}
+
 \begin{methoddesc}{tzname}{self, dt}
   Return the timezone name corresponding to the \class{datetime}
   object represented
@@ -1092,8 +1098,9 @@
   will wish to return different names depending on the specific value
   of \var{dt} passed, especially if the \class{tzinfo} class is
   accounting for daylight time.
-\end{methoddesc}
 
+  The default implementation of \method{tzname()} raises
+  \exception{NotImplementedError}.
 \end{methoddesc}
 
 These methods are called by a \class{datetime} or \class{time} object,
@@ -1106,21 +1113,23 @@
 When \code{None} is passed, it's up to the class designer to decide the
 best response.  For example, returning \code{None} is appropriate if the
 class wishes to say that time objects don't participate in the
-\class{tzinfo} protocol.  In other applications, it may be more useful
-for \code{utcoffset(None)} to return the standard UTC offset.
+\class{tzinfo} protocol.  It may be more useful for \code{utcoffset(None)}
+to return the standard UTC offset, as there is no other convention for
+discovering the standard offset.
 
 When a \class{datetime} object is passed in response to a
 \class{datetime} method, \code{dt.tzinfo} is the same object as
 \var{self}.  \class{tzinfo} methods can rely on this, unless
 user code calls \class{tzinfo} methods directly.  The intent is that
 the \class{tzinfo} methods interpret \var{dt} as being in local time,
-and not need to worry about objects in other timezones.
+and not need worry about objects in other timezones.
 
 Example \class{tzinfo} classes:
 
 \verbatiminput{tzinfo-examples.py}
 
-Note that there are unavoidable subtleties twice per year in a tzinfo
+Note that there are unavoidable subtleties twice per year in a
+\class{tzinfo}
 subclass accounting for both standard and daylight time, at the DST
 transition points.  For concreteness, consider US Eastern (UTC -0500),
 where EDT begins the minute after 1:59 (EST) on the first Sunday in
@@ -1140,32 +1149,29 @@
 to 3:00.  A wall time of the form 2:MM doesn't really make sense on that
 day, so \code{astimezone(Eastern)} won't deliver a result with
 \code{hour==2} on the
-day DST begins.  How an Eastern instance chooses to interpret 2:MM on
-that day is its business.  The example Eastern implementation above
-chose to
-consider it as a time in EDT, simply because it "looks like it's
-after 2:00", and so synonymous with the EST 1:MM times on that day.
-Your Eastern class may wish, for example, to raise an exception instead
-when it sees a 2:MM time on the day EDT begins.
+day DST begins.  In order for \method{astimezone()} to make this
+guarantee, the \class{tzinfo} \method{dst()} method must consider times
+in the "missing hour" (2:MM for Eastern) to be in daylight time.
 
 When DST ends (the "end" line), there's a potentially worse problem:
-there's an hour that can't be spelled unambiguously in local wall time, the
-hour beginning at the moment DST ends.  In this example, that's times of
-the form 6:MM UTC on the day daylight time ends.  The local wall clock
+there's an hour that can't be spelled unambiguously in local wall time:
+the last hour of daylight time.  In Eastern, that's times of
+the form 5:MM UTC on the day daylight time ends.  The local wall clock
 leaps from 1:59 (daylight time) back to 1:00 (standard time) again.
-1:MM is taken as daylight time (it's "before 2:00"), so maps to 5:MM UTC.
-2:MM is taken as standard time (it's "after 2:00"), so maps to 7:MM UTC.
-There is no local time that maps to 6:MM UTC on this day.
+Local times of the form 1:MM are ambiguous.  \method{astimezone()} mimics
+the local clock's behavior by mapping two adjacent UTC hours into the
+same local hour then.  In the Eastern example, UTC times of the form
+5:MM and 6:MM both map to 1:MM when converted to Eastern.  In order for
+\method{astimezone()} to make this guarantee, the \class{tzinfo}
+\method{dst()} method must consider times in the "repeated hour" to be in
+standard time.  This is easily arranged, as in the example, by expressing
+DST switch times in the time zone's standard local time.
 
-Just as the wall clock does, \code{astimezone(Eastern)} maps both UTC
-hours 5:MM
-and 6:MM to Eastern hour 1:MM on this day.  However, this result is
-ambiguous (there's no way for Eastern to know which repetition of 1:MM
-is intended).  Applications that can't bear such ambiguity
-should avoid using hybrid tzinfo classes; there are no
-ambiguities when using UTC, or any other fixed-offset tzinfo subclass
-(such as a class representing only EST (fixed offset -5 hours), or only
-EDT (fixed offset -4 hours)).
+Applications that can't bear such ambiguities should avoid using hybrid
+\class{tzinfo} subclasses; there are no ambiguities when using UTC, or
+any other fixed-offset \class{tzinfo} subclass (such as a class
+representing only EST (fixed offset -5 hours), or only EDT (fixed offset
+-4 hours)).
 
 
 \subsection{\method{strftime()} Behavior}