bug#32902: Add support for (TIMESTAMP . RESOLUTION) Lisp timestamps

[Eli Zaretskii]

> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Mon, 1 Oct 2018 18:00:26 -0700
> 
> The attached patches follow up on a suggestion by Stefan a few weeks 
> ago, by adding support for a new Lisp timestamp format (TIMESTAMP . 
> FREQUENCY), where TIMESTAMP is an integer that counts clock ticks and 
> FREQUENCY is a positive integer that counts ticks per second. For 
> brevity the documentation says (TICKS . HZ) instead of (TIMESTAMP . 
> FREQUENCY).

Thanks for working on this.

I'd prefer not to move stuff from editfns.c to a new file, as that
makes forensics significantly harder.  Is it feasible to leave the
time-related code in editfns.c?

>  DEFUN ("current-time", Fcurrent_time, Scurrent_time, 0, 0, 0,
> -       doc: /* Return the current time, as the number of seconds since 
> 1970-01-01 00:00:00.
> -The time is returned as a list of integers (HIGH LOW USEC PSEC).
> -HIGH has the most significant bits of the seconds, while LOW has the
> -least significant 16 bits.  USEC and PSEC are the microsecond and
> -picosecond counts.  */)
> +       doc: /* Return the current time, counting the number of seconds since 
> the epoch.
> +
> +See Info node `(elisp)Time of Day' for the format of the returned
> +timestamp.  Although this is currently list format, it may change in
> +future versions of Emacs.  Use `encode-time' if you need a particular
> +form; for example, (encode-time nil \\='list) returns the current time
> +in list form.  */)

I think this obfuscation of the time values in doc strings (here and
elsewhere in the patch) is not a good idea, and asking users to read
the manual just to understand what kind of data they will get or need
to pass to a function, is a step backwards.  Doc strings only send to
the manuals for additional details and explanations, not for the basic
facts such as these.

The manual and NEWS can (and probably should) explain that this stuff
is in transition, but we shouldn't describe return values as opaque
objects because of that.  IMO, this is not the Emacsy way of dealing
with complex data structures.

I also don't like saying in a doc string that something might change
in a future version: that's stuff for the manual.  Doc strings should
describe the current state of affairs.

> +If TIME is a list (SECOND MINUTE HOUR DAY MONTH YEAR IGNORED DST ZONE)
> +it a decoded time in the style of `decode-time', so that (encode-time
   ^^
A typo: should be "it is" or "it's".

> +If FORM is a positive integer, the time is returned as a pair of
> +integers (TICKS . FORM), where TICKS is the number of clock ticks and FORM
> +is the clock frequency in ticks per second.  (Currently the positive
> +integer should be at least 65536 if the returned value is expected to
> +be given to standard functions expecting Lisp timestamps.)  If FORM is
> +t, the time is returned as (TICKS . PHZ), where PHZ is a
> +platform-dependent clock frequency.

This doesn't tell in what units the clock frequency is returned.

> -usage: (encode-time SECOND MINUTE HOUR DAY MONTH YEAR &optional ZONE)  */)
> +usage: (encode-time TIME &optional FORM)  */)

This makes an impression the function doesn't support more than 2
arguments, which is incorrect.  Can we provide a more accurate 'usage'
form?

I think it would be good to add tests for the functions being
modified, otherwise we might be breaking something without paying
attention.