Change current-time back to list form

Change current-time and related functions back to using the
traditional list form.  Also, add a new boolean variable
current-time-list that lets people try out (TICKS . HZ) form,
with the goal of smoothing the transition.
* src/timefns.c (CURRENT_TIME_LIST): Change default back to true.
(current-time-list): New boolean Lisp variable, which defaults to
CURRENT_TIME_LIST.  All uses of CURRENT_TIME_LIST changed to
use current_time_list, and all documentation changed.

4 files changed, 47 insertions, 19 deletions

diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index afaed10cdfe..049c8a65a8f 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -15343,9 +15343,12 @@ nil
 100
 @end group
 @group
-(1351051674579989697 . 1000000000)
-(1173477761000000000 . 1000000000)
-(1351050967734791805 . 1000000000)
+(20615 27034 579989 697000)
+(17905 55681 0 0)
+(20615 26327 734791 805000)@footnote{If @code{current-time-list} is
+@code{nil} the three timestamps are @code{(1351051674579989697
+. 1000000000)}, @code{(1173477761000000000 . 1000000000)}, and
+@code{(1351050967734791805 . 1000000000)}, respectively.}
 13188
 "-rw-r--r--"
 @end group
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 4394f64a320..75905658e64 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1423,9 +1423,9 @@ For example, here are the file attributes for @file{files.texi}:
 @group
 (file-attributes "files.texi" 'string)
      @result{}  (nil 1 "lh" "users"
-          (1351023123050040152 . 1000000000)
-          (1310720023000000000 . 1000000000)
-          (1351023659902289872 . 1000000000)
+          (20614 64019 50040 152000)
+          (20000 23 0 0)
+          (20614 64555 902289 872000)
           122295 "-rw-rw-rw-"
           t 6473924464520138
           1014478468)
@@ -1449,14 +1449,20 @@ is owned by the user with name @samp{lh}.
 @item "users"
 is in the group with name @samp{users}.
 
-@item (1351023123050040152 . 1000000000)
-was last accessed on October 23, 2012, at 20:12:03.050040152 UTC.
+@item (20614 64019 50040 152000)
+was last accessed on October 23, 2012, at 20:12:03.050040152 UTC@.
+(This timestamp is @code{(1351023123050040152 . 1000000000)}
+if @code{current-time-list} is @code{nil}.)
 
-@item (1310720023000000000 . 1000000000)
-was last modified on July 15, 2001, at 08:53:43.000000000 UTC.
+@item (20000 23 0 0)
+was last modified on July 15, 2001, at 08:53:43.000000000 UTC@.
+(This timestamp is @code{(1310720023000000000 . 1000000000)}
+if @code{current-time-list} is @code{nil}.)
 
-@item (1351023659902289872 . 1000000000)
-last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC.
+@item (20614 64555 902289 872000)
+last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC@.
+(This timestamp is @code{(1351023659902289872 . 1000000000)}
+if @code{current-time-list} is @code{nil}.)
 
 @item 122295
 is 122295 bytes long.  (It may not contain 122295 characters, though,
diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index d1a3fef7a4b..975215d6976 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -503,9 +503,11 @@ if the information is not available.
 @example
 @group
 emacs-build-time
-     @result{} (1650228902637038831 . 1000000000)
+     @result{} (25194 55894 8547 617000)
 @end group
 @end example
+(This timestamp is @code{(1651169878008547617 . 1000000000)}
+if @code{current-time-list} was @code{nil} when Emacs was built.)
 @end defvar
 
 @defvar emacs-version
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 89ddf164a17..20b6c1cec63 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1359,6 +1359,10 @@ This represents the number of seconds using the formula:
 @tex
 $high \times 2^{16} + low + micro \times 10^{-6} + pico \times 10^{-12}$.
 @end tex
+If @code{current-time-list} is @code{t},
+some functions may default to returning two- or
+three-element lists, with omitted @var{micro} and @var{pico}
+components defaulting to zero.
 On all current machines @var{pico} is a multiple of 1000, but this
 may change as higher-resolution clocks become available.
 @end itemize
@@ -1410,15 +1414,28 @@ The operating system limits the range of time and zone values.
 @end example
 @end defun
 
+@defvar current-time-list
+This boolean variable is a transition aid.  If @code{t},
+@code{current-time} and related functions return timestamps in list
+form, typically @code{(@var{high} @var{low} @var{micro} @var{pico})};
+otherwise, they use @code{(@var{ticks} . @var{hz})} form.  Currently
+this variable defaults to @code{t}, for behavior compatible with
+previous Emacs versions.  Developers are encourage to test
+timestamp-related code with this variable set to @code{nil}, as it
+will default to @code{nil} in a future Emacs version, and will be
+removed in some version after that.
+@end defvar
+
 @defun current-time
 This function returns the current time as a Lisp timestamp.
-The timestamp has the form @code{(@var{ticks} . @var{hz})} where
+If @code{current-time-list} is @code{nil},
+the timestamp has the form @code{(@var{ticks} . @var{hz})} where
 @var{ticks} counts clock ticks and @var{hz} is the clock ticks per second.
-
-In Emacs 28 and earlier, the returned timestamp had the list form
-@code{(@var{high} @var{low} @var{usec} @var{psec})}.  You can use
-@code{(time-convert nil 'list)} to return the current time in this
-older form.  @xref{Time Conversion}.
+Otherwise, the timestamp has the list form
+@code{(@var{high} @var{low} @var{usec} @var{psec})}.
+You can use @code{(time-convert nil t)} or @code{(time-convert nil 'list)}
+to obtain a particular form regardless of the value of
+@code{current-time-list}.  @xref{Time Conversion}.
 @end defun
 
 @defun float-time &optional time