Moved description of mktime 9-tuple to top.
Added description of strftime format string.
Minor small editing.
diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex
index e934408..7c52f7c 100644
--- a/Doc/lib/libtime.tex
+++ b/Doc/lib/libtime.tex
@@ -32,6 +32,19 @@
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.
+\item
+The time tuple as returned by \code{gmtime()} and \code{localtime()},
+or as accpted by \code{mktime()} is a tuple of 9
+integers: year (e.g.\ 1993), month (1--12), day (1--31), hour
+(0--23), minute (0--59), second (0--59), weekday (0--6, monday is 0),
+Julian day (1--366) and daylight savings flag (-1, 0 or 1).
+Note that unlike the C structure, the month value is a range of 1-12, not
+0-11. A year value of $<$ 100 will typically be silently converted to
+1900 $+$ year value. A -1 argument as daylight savings flag, passed to
+\code{mktime()} will usually result in the correct daylight savings
+state to be filled in.
+
+
\end{itemize}
The module defines the following functions and data items:
@@ -45,7 +58,6 @@
Only use this if \code{daylight} is nonzero.
\end{datadesc}
-
\begin{funcdesc}{asctime}{tuple}
Convert a tuple representing a time as returned by \code{gmtime()} or
\code{localtime()} to a 24-character string of the following form:
@@ -53,14 +65,12 @@
the same name, there is no trailing newline.
\end{funcdesc}
-
\begin{funcdesc}{clock}{}
Return the current CPU time as a floating point number expressed in
seconds. The precision, and in fact the very definiton of the meaning
of ``CPU time'', depends on that of the C function of the same name.
\end{funcdesc}
-
\begin{funcdesc}{ctime}{secs}
Convert a time expressed in seconds since the epoch to a string
representing local time. \code{ctime(t)} is equivalent to
@@ -72,11 +82,9 @@
\end{datadesc}
\begin{funcdesc}{gmtime}{secs}
-Convert a time expressed in seconds since the epoch to a tuple of 9
-integers, in UTC: year (e.g.\ 1993), month (1--12), day (1--31), hour
-(0--23), minute (0--59), second (0--59), weekday (0--6, monday is 0),
-Julian day (1--366), dst flag (always zero). Fractions of a second are
-ignored. Note subtle differences with the C function of this name.
+Convert a time expressed in seconds since the epoch to a time tuple
+in UTC in which the dst flag is always zero. Fractions of a second are
+ignored.
\end{funcdesc}
\begin{funcdesc}{localtime}{secs}
@@ -86,7 +94,9 @@
\begin{funcdesc}{mktime}{tuple}
This is the inverse function of \code{localtime}. Its argument is the
-full 9-tuple (since the dst flag is needed). It returns a floating
+full 9-tuple (since the dst flag is needed --- pass -1 as the dst flag if
+it is unknown) which expresses the time
+in \em{local} time, not UTC. It returns a floating
point number, for compatibility with \code{time.time()}. If the input
value can't be represented as a valid time, OverflowError is raised.
\end{funcdesc}
@@ -99,8 +109,75 @@
\begin{funcdesc}{strftime}{format, tuple}
Convert a tuple representing a time as returned by \code{gmtime()} or
\code{localtime()} to a string as specified by the format argument.
-See the \code{strftime(3)} man page for details of the syntax of
-format strings.
+
+ The following directives, shown without the optional field width and
+ precision specification, are replaced by the indicated characters:
+
+\begin{tabular}{lp{25em}}
+ \%a & Locale's abbreviated weekday name. \\
+ \%A & Locale's full weekday name. \\
+ \%b & Locale's abbreviated month name. \\
+ \%B & Locale's full month name. \\
+ \%c & Locale's appropriate date and time representation. \\
+ \%d & Day of the month as a decimal number [01,31]. \\
+ \%E & Locale's combined Emperor/Era name and year. \\
+ \%H & Hour (24-hour clock) as a decimal number [00,23]. \\
+ \%I & Hour (12-hour clock) as a decimal number [01,12]. \\
+ \%j & Day of the year as a decimal number [001,366]. \\
+ \%m & Month as a decimal number [01,12]. \\
+ \%M & Minute as a decimal number [00,59]. \\
+ \%n & New-line character. \\
+ \%N & Locale's Emperor/Era name. \\
+ \%o & Locale's Emperor/Era year. \\
+ \%p & Locale's equivalent of either AM or PM. \\
+ \%S & Second as a decimal number [00,61]. \\
+ \%t & Tab character. \\
+ \%U & Week number of the year (Sunday as the first day of the
+ week) as a decimal number [00,53]. All days in a new
+ year preceding the first Sunday are considered to be in
+ week 0. \\
+ \%w & Weekday as a decimal number [0(Sunday),6]. \\
+ \%W & Week number of the year (Monday as the first day of the
+ week) as a decimal number [00,53]. All days in a new
+ year preceding the first Sunday are considered to be in
+ week 0. \\
+ \%x & Locale's appropriate date representation. \\
+ \%X & Locale's appropriate time representation. \\
+ \%y & Year without century as a decimal number [00,99]. \\
+ \%Y & Year with century as a decimal number. \\
+ \%Z & Time zone name (or by no characters if no time zone
+ exists). \\
+ \%\% & \% \\
+\end{tabular}
+
+ An optional field width and precision specification can immediately
+ follow the initial \% of a directive in the following order: \\
+
+\begin{tabular}{lp{25em}}
+ [-|0]w & the decimal digit string w specifies a minimum field
+ width in which the result of the conversion is right-
+ or left-justified. It is right-justified (with space
+ padding) by default. If the optional flag `-' is
+ specified, it is left-justified with space padding on
+ the right. If the optional flag `0' is specified, it
+ is right-justified and padded with zeros on the left. \\
+ .p & the decimal digit string p specifies the minimum number
+ of digits to appear for the d, H, I, j, m, M, o, S, U,
+ w, W, y and Y directives, and the maximum number of
+ characters to be used from the a, A, b, B, c, D, E, F,
+ h, n, N, p, r, t, T, x, X, z, Z, and % directives. In
+ the first case, if a directive supplies fewer digits
+ than specified by the precision, it will be expanded
+ with leading zeros. In the second case, if a directive
+ supplies more characters than specified by the
+ precision, excess characters will truncated on the
+ right.
+\end{tabular}
+
+ If no field width or precision is specified for a d, H, I, m, M, S, U,
+ W, y, or j directive, a default of .2 is used for all but j for which
+ .3 is used.
+
\end{funcdesc}
\begin{funcdesc}{time}{}
@@ -121,3 +198,4 @@
timezone, the second is the name of the local DST timezone. If no DST
timezone is defined, the second string should not be used.
\end{datadesc}
+