Brought the strftime explanation into synch with the plain-text sandbox

docs, and moved its section to the end (before the "C API" section,
which latter doesn't really belong in the Library manual).

1 files changed, 56 insertions, 45 deletions

diff --git a/Doc/lib/libdatetime.tex b/Doc/lib/libdatetime.tex
index 4435ae3..a7d9926 100644
--- a/Doc/lib/libdatetime.tex
+++ b/Doc/lib/libdatetime.tex
@@ -123,51 +123,6 @@ object
             datetimetz
 \end{verbatim}
 
-
-\subsection{\method{strftime()} Behavior}
-
-\class{date}, \class{datetime}, \class{datetimetz}, \class{time},
-and \class{timetz} objects all support a \code{strftime(\var{format})}
-method, to create a string representing the time under the control of
-an explicit format string.  Broadly speaking,
-\begin{verbatim}
-d.strftime(fmt)
-\end{verbatim}
-acts like the \refmodule{time} module's
-\begin{verbatim}
-time.strftime(fmt, d.timetuple())
-\end{verbatim}
-although not all objects support a \method{timetuple()} method.
-
-For time and \class{timetz} objects, format codes for year, month, and
-day should not be used, as time objects have no such values.  \code{0}
-is used instead.
-
-For date objects, format codes for hours, minutes, and seconds should
-not be used, as date objects have no such values.  \code{0} is used
-instead.
-
-For a \naive\ object, the \code{\%z} and \code{\%Z} format codes are
-replaced by empty strings.
-
-For an aware object:
-
-\begin{itemize}
-  \item[\code{\%z}]
-    \method{utcoffset()} is transformed into a 5-character string of
-    the form +HHMM or -HHMM, where HH is a 2-digit string giving the
-    number of UTC offset hours, and MM is a 2-digit string giving the
-    number of UTC offset minutes.  For example, if
-    \method{utcoffset()} returns -180, \code{\%z} is replaced with the
-    string \code{'-0300'}.
-
-  \item[\code{\%Z}]
-    If \method{tzname()} returns \code{None}, \code{\%Z} is replaced
-    by an empty string.  Else \code{\%Z} is replaced by the returned
-    value, which must be a string.
-\end{itemize}
-
-
 \subsection{\class{timedelta} \label{datetime-timedelta}}
 
 A \class{timedelta} object represents a duration, the difference
@@ -1156,6 +1111,62 @@ Instance methods:
 \code{str(\var{d})} is equivalent to \code{\var{d}.isoformat(' ')}.
 
 
+\subsection{\method{strftime()} Behavior}
+
+\class{date}, \class{datetime}, \class{datetimetz}, \class{time},
+and \class{timetz} objects all support a \code{strftime(\var{format})}
+method, to create a string representing the time under the control of
+an explicit format string.  Broadly speaking,
+\begin{verbatim}
+d.strftime(fmt)
+\end{verbatim}
+acts like the \refmodule{time} module's
+\begin{verbatim}
+time.strftime(fmt, d.timetuple())
+\end{verbatim}
+although not all objects support a \method{timetuple()} method.
+
+For \class{time} and \class{timetz} objects, format codes for year,
+month, and day should not be used, as time objects have no such values.
+\code{1900} is used for the year, and \code{0} for the month and day.
+
+For \class{date} objects, format codes for hours, minutes, and seconds
+should not be used, as date objects have no such values.  \code{0} is
+used instead.
+
+For a \naive\ object, the \code{\%z} and \code{\%Z} format codes are
+replaced by empty strings.
+
+For an aware object:
+
+\begin{itemize}
+  \item[\code{\%z}]
+    \method{utcoffset()} is transformed into a 5-character string of
+    the form +HHMM or -HHMM, where HH is a 2-digit string giving the
+    number of UTC offset hours, and MM is a 2-digit string giving the
+    number of UTC offset minutes.  For example, if
+    \method{utcoffset()} returns -180, \code{\%z} is replaced with the
+    string \code{'-0300'}.
+
+  \item[\code{\%Z}]
+    If \method{tzname()} returns \code{None}, \code{\%Z} is replaced
+    by an empty string.  Else \code{\%Z} is replaced by the returned
+    value, which must be a string.
+\end{itemize}
+
+The full set of format codes supported varies across platforms,
+because Python calls the platform C library's \function{strftime()}
+function, and platform variations are common.  The documentation for
+Python's \refmodule{time} module lists the format codes that the C
+standard (1989 version) requires, and those work on all platforms
+with a standard C implementation.  Note that the 1999 version of the
+C standard added additional format codes.
+
+The exact range of years for which \method{strftime()} works also
+varies across platforms.  Regardless of platform, years before 1900
+cannot be used.
+
+
 \subsection{C API}
 
 Struct typedefs: