bug#46505: 27.1.91; Having a hard time manipulating a date

[Damien Cassou <damien@cassou.me>]

Hi,

I'm finding it very hard to manipulate dates.

What I want:

Example input: "2021-01-20"
Corresponding expected output: "20 Jan 2021"

What I tried:

  (format-time-string "%d %b %Y" (iso8601-parse "2021-01-20"))
    ⇒ invalid time specification

  (format-time-string "%d %b %Y" (iso8601-parse "2021-01-20T00:00:00"))
    ⇒ "01 Jan 1970"  ;; note the wrong year

What works:

  (format-time-string
       "%d %b %Y"
       (encode-time (iso8601-parse "2021-01-20T00:00:00")))
    ⇒ "20 Jan 2021"

I found the Elisp manual confusing with all the date formats, all the
functions and their different kinds of arguments.

Possible improvements:

- make format-time-string accept as 2nd argument the return value of
  (iso8601-parse "2021-01-20T00:00:00") with a correct year

- make format-time-string accept as 2nd argument the return value of
  (iso8601-parse "2021-01-20") without sending an "invalid time
  specification"

- restructure the manual to start with a page describing the different
  time formats used throughout Emacs with a table listing all conversion
  functions, the kind of input they take and the kind of output they
  generate and examples for each.

In GNU Emacs 27.1.91 (build 1, x86_64-pc-linux-gnu, GTK+ Version
3.24.21, cairo version 1.16.0) Windowing system distributor 'Fedora
Project', version 11.0.12010000 System Description: Fedora 33
(Workstation Edition)

Best,

-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill