Re: Making decoded-times and calendar dates compatible?

[Richard Stallman <rms@gnu.org>]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]


  > The only documentation I'm aware of (besides the Calendar/Diary section
  > in the Emacs manual, which doesn't deal with the programming interface)
  > is in the docstrings of the library. The docstrings of the functions

  > calendar-extract-year
  > calendar-extract-month
  > calendar-extract-day

  > are where the (MONTH DAY YEAR) format is mentioned.

Would someoe like to add some comments at the start of the file
documenging this data structure?

  > This is the "standard", Gregorian format for calendar dates, but it is
  > not the only format that the calendar works with. Internally it also
  > uses an "absolute" format which is an integer number of days since
  > December 31, 1BC (see e.g. `calendar-absolute-from-gregorian'), and
  > converts between different calendar scales by converting to and from the
  > absolute format (see e.g. `calendar-iso-from-absolute').

It would be helpful to describe that representation too, in those comments.

  > Similarly, the only documentation I'm aware of for the decoded-time
  > format is in the docstrings of the functions `decode-time' and
  > `parse-time-string', and in the symbol documentation for `decoded-time',
  > which is declared as a cl-struct with :type list in simple.el. According
  > to a comment there, the point of this declaration is to provide
  > accessors for the various slots in the list, e.g. `decoded-time-month'.

This IS described in the Emacs Lisp Reference Manual, in section Time of Day.


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)