Added remark about time() and sleep()'s subsecond precision.

Added hint about using clock() for benchmarks etc.
Removed non-portable strftime directives and field width, and added a
warning about non-standard features.

2 files changed, 34 insertions, 64 deletions

diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex
index 7c52f7c..bc83f03 100644
--- a/Doc/lib/libtime.tex
+++ b/Doc/lib/libtime.tex
@@ -33,6 +33,14 @@ 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
+On the other hand, the precision of \code{time()} and \code{sleep()}
+is better than their UNIX equivalents: times are expressed as floating
+point numbers, \code{time()} returns the most accurate time available
+(using UNIX \code{gettimeofday()} where available), and \code{sleep()}
+will accept a time with a nonzero fraction (UNIX \code{select()} is
+used to implement this, where available).
+
+\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
@@ -68,7 +76,9 @@ the same name, there is no trailing newline.
 \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.
+of ``CPU time'', depends on that of the C function of the same name,
+but in any case, this is the function to use for benchmarking Python
+or timing algorithms.
 \end{funcdesc}
 
 \begin{funcdesc}{ctime}{secs}
@@ -120,18 +130,13 @@ Convert a tuple representing a time as returned by \code{gmtime()} or
            \%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
@@ -150,33 +155,13 @@ Convert a tuple representing a time as returned by \code{gmtime()} or
            \%\%  &     \% \\
 \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}
+      Additional directives may be supported on certain platforms, but
+      only the ones listed here have a meaning standardized by ANSI C.
 
-      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.
+      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.
 
 \end{funcdesc}
 
diff --git a/Doc/libtime.tex b/Doc/libtime.tex
index 7c52f7c..bc83f03 100644
--- a/Doc/libtime.tex
+++ b/Doc/libtime.tex
@@ -33,6 +33,14 @@ 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
+On the other hand, the precision of \code{time()} and \code{sleep()}
+is better than their UNIX equivalents: times are expressed as floating
+point numbers, \code{time()} returns the most accurate time available
+(using UNIX \code{gettimeofday()} where available), and \code{sleep()}
+will accept a time with a nonzero fraction (UNIX \code{select()} is
+used to implement this, where available).
+
+\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
@@ -68,7 +76,9 @@ the same name, there is no trailing newline.
 \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.
+of ``CPU time'', depends on that of the C function of the same name,
+but in any case, this is the function to use for benchmarking Python
+or timing algorithms.
 \end{funcdesc}
 
 \begin{funcdesc}{ctime}{secs}
@@ -120,18 +130,13 @@ Convert a tuple representing a time as returned by \code{gmtime()} or
            \%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
@@ -150,33 +155,13 @@ Convert a tuple representing a time as returned by \code{gmtime()} or
            \%\%  &     \% \\
 \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}
+      Additional directives may be supported on certain platforms, but
+      only the ones listed here have a meaning standardized by ANSI C.
 
-      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.
+      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.
 
 \end{funcdesc}