The format of time values in lisp/calendar/time-date.el.

[Lute Kamstra]

The various function in time-date.el seem to use different formats for
their arguments.  According to the node Time Calculations in the Lisp
Manual, the following functions should use the format (HIGH LOW MICRO)
to specify HIGH * 65536 + LOW + MICRO / 1000000 seconds:

- time-less-p
- time-subtract
- time-add
- time-to-days
- time-to-day-in-year

However, in reality:

- time-less-p expects (HIGH LOW) for its arguments
- time-subtract expects (HIGH LOW) for its arguments and returns (HIGH
  LOW) as well
- time-add expects either (HIGH LOW MICRO), (HIGH LOW), or (HIGH .
  LOW) and returns (HIGH LOW MICRO).
- time-to-days and time-to-day-in-year use decode-time on its argument.
  decode-time expects (HIGH LOW . IGNORED) or (HIGH . LOW).

Was there an evolution in format from (HIGH . LOW), via (HIGH LOW), to
(HIGH LOW MICRO)?

Shall I fix time-less-p and time-subtract to deal with (HIGH LOW
MICRO) arguments as well?

Should they deal with (HIGH . LOW) too?

What about the return value of time-subtract (and time-add): should it
be backward compatible in the sense that it returns (HIGH LOW) if both
its arguments are of that format?

Lute.