Moved description of mktime 9-tuple to top.

Added description of strftime format string.
Minor small editing.

2 files changed, 178 insertions, 22 deletions

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 @@ 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.
 
+\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 @@ east of the 0th meridian (as in Western Europe, including the UK).
 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 @@ Convert a tuple representing a time as returned by \code{gmtime()} or
 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 @@ Nonzero if a DST timezone is defined.
 \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 @@ to 1 when DST applies to the given time.
 
 \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 @@ be a floating point number to indicate a more precise sleep time.
 \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 @@ A tuple of two strings: the first is the name of the local non-DST
 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}
+
diff --git a/Doc/libtime.tex b/Doc/libtime.tex
index e934408..7c52f7c 100644
--- a/Doc/libtime.tex
+++ b/Doc/libtime.tex
@@ -32,6 +32,19 @@ 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.
 
+\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 @@ east of the 0th meridian (as in Western Europe, including the UK).
 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 @@ Convert a tuple representing a time as returned by \code{gmtime()} or
 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 @@ Nonzero if a DST timezone is defined.
 \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 @@ to 1 when DST applies to the given time.
 
 \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 @@ be a floating point number to indicate a more precise sleep time.
 \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 @@ A tuple of two strings: the first is the name of the local non-DST
 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}
+