| ID | f426393c-28c4-4814-863c-c674e374dae0 |
|---|---|
| DeertopiaVisibility | public |
Org timestamp time zones
Details
Timestamp objects have an optional zone property. nil represents local/system time.
Setting the default time zone per heading or file may be nice.
Timestamps, as written in an Org document, will not be automatically converted/updated. Time zones only influence the interpretation. I am fine with using overlays to automatically adjust and display timestamps.
Configurable alist to define time zone abbreviations? As far as I know, neither the OS nor Emacs handles time zone abbreviations.
Timestamps w/ time zones offer a strict superset of functionality. Fully backwards-compatible.
Time zone completion?
A time zone identifier such as America/Denver is somewhat ambigious, and that is perfectly fine. By saying "this event takes place at 09:00, Denver time," we don't care about the precise atomic time the event occurs. The event is happening whenever it's 09:00 in Denver, and that's that. UTC and offsets therupon are for atomic time — use them! See: Re: [FEATURE REQUEST] Timezone support in org-mode datestamps and org-agenda.
Time zone conversion
Elisp + POSIX is powerful enough to faciliate all time zone conversions. Some experimenting must be done to ensure compatibility with non-POSIX garbage. The most relevant procedures are encode-time and decode-time.
N.B. the 9-element timestamp lists are structured as following:
(second minute hour day month year ignored-for-compat dst zone)
See encode-time.
Examples
;; Convert 12:00:00, 1 Jan 2000 from Denver time to UTC.
(decode-time (encode-time '(0 0 12 1 1 2000 nil -1 "America/Denver"))
"Etc/UTC")
unimplemented! (fixed-width)
{:type "fixed-width",
:affiliated {:results ""},
:value "(0 0 19 1 1 2000 6 nil 0)",
:position
{:start {:line 49, :column 1, :offset 2051},
:end {:line 49, :column 28, :offset 2078}}}
;; DST is automatically resolved by the OS, when -1 is passed.
;; Some things to note:
;; * In Denver, on 10 Mar 2024, clocks were set one hour forward for DST.
;; See: https://www.timeanddate.com/time/change/usa/colorado
;; * MST = UTC-7, MDT = UTC-6.
;; In the results, notice that despite both Denver timestamps occuring at
;; 12:00:00, the UTC equivalents are an hour apart. Fuck you, DST!
(let ((mst-timestamp
;; 12:00:00, 9 Mar 2024
(encode-time '(0 0 12 9 3 2024 nil -1 "America/Denver")))
(mdt-timestamp
;; 12:00:00, 10 Mar 2024
(encode-time '(0 0 12 10 3 2024 nil -1 "America/Denver"))))
`(("MST→UTC" . ,(decode-time mst-timestamp "Etc/UTC"))
("MDT→UTC" . ,(decode-time mdt-timestamp "Etc/UTC"))))
Implementation plan
Proof of concept unimplemented! (statistics-cookie)
{:type "statistics-cookie",
:begin 2938,
:end 2943,
:value "[0/2]",
:post-blank 0,
:position
{:start {:line 71, :column 22, :offset 2938},
:end {:line 71, :column 27, :offset 2943}}}
unimplemented! (statistics-cookie)
{:type "statistics-cookie",
:begin 2938,
:end 2943,
:value "[0/2]",
:post-blank 0,
:position
{:start {:line 71, :column 22, :offset 2938},
:end {:line 71, :column 27, :offset 2943}}}
FOR NOW: The plan is to parse TZDB identifiers with the @-syntax, and get the agenda working. We can extend the syntax for added convenience later.
Parse the TZDB identifiers
Convert time zones in the agenda
Things to worry about
Intervals
Portability
How do timestamp strings work across unices, or on non-POSIX systems?
From: Daryl Manning
I think you may only be looking at the representation and not considering the actual mechanics which will be required to make this all work.
Consider for example an agenda file where the TODO items have been added while I am here in Australia (currently +11:00 w/ DST). Tomorrow I fly to Europe where I will be working for the next 6 weeks. I need all my TODOs with active timestamps to be updated to Berlin's TZ. How does this work?
Your un-zoned timestamps will behave exactly as they did before, resorting to local time. Timestamps that do have a time zone will be converted as expected.
From: Tim Cross
An org user who travels and is often in a different time zone from their 'home' time zone. IN this scenario, they probably want their meeting times to be adjusted to the local time zone they are in (unless they are already recorded in that time zone). Note that this was a specific example form a previous feature request for time zone support in org time stamps.
The agenda, and potentially in-document overlays will display local times.
Syntax
The syntax I plan to implement is unchanged that proposed by Ihor Radchenko's. See: [POLL] Proposed syntax for timestamps with time zone info.
1 Timestamp w/ explicit UTC offset
YYYY-MM-DD [optional day name] HH:MM[^ \]>]*?[+-−]HH[MM]? YYYY-MM-DD [optional day name] HH:MM[^ \]>]*?Z[ \]>]
2 Timestamp w/ time zone specifier
Examples
2022-11-12 12:00 @Asia/Singapore # tzdb syntax 2022-11-12 10:00 @Europe/Berlin 2022-11-12 10:00 @!Europe/Berlin # “!” does nothing here, see below 2022-11-12 10:00 @EST+5 # TZ syntax 2022-11-12 10:00 @EST+5EDT,M3.2.0/2,M11.1.0/2 # manual time zone spec allowed in TZ
3 Combine 1 and 2
Allow an explicit UTC offset, or a time zone, or both. In the case of both,
one of the two may be prefixed with a bang (!) to prioritise one over the other.
References
Org-mode ML: [FEATURE REQUEST] Timezone support in org-mode datestamps and org-agenda
[POLL] Proposed syntax for timestamps with time zone info
Re: [POLL] Proposed syntax for timestamps with time zone info
Re: [FEATURE REQUEST] Timezone support in org-mode datestamps and org-agenda
Explains time zones vs. offsets. I believe it to be a good rebuttal to anyone complaining about the ambiguity of geographic time zones.
Elisp manual: Time Zone Rules
libc manual: Specifying the Time Zone with TZ
Falsehoods programmers believe about time
A classic piece by Tim Viseé.