Re: [POLL] Proposed syntax for timestamps with time zone info (was: [FEATURE REQUEST] Timezone support in org-mode datestamps and org-agenda)

[Timothy <orgmode@tec.tecosaur.net>]

[-- Attachment #1: Type: text/plain, Size: 6220 bytes --]

Hi Ihor,

Thanks for the detailed proposal! The effort you’ve put into soliciting feedback
and working out an effective and concise proposal is most commendable 😃.

> I propose two forms of time zone information in Org timestamps
>
> 1. Timestamp with explicit UTC offset
>
>    YYYY-MM-DD [optional day name] HH:MM[^ \]>]*?[+-−]HH[MM]?
>    YYYY-MM-DD [optional day name] HH:MM[^ \]>]*?Z[ \]>]
>
>    “-” is latin “HYPHEN-MINUS” (code 0x2D)
>    “−” is unicode “MINUS SIGN” (code 0x2212), as prescribed by ISO8601
>    we will not actually use it when generating timestamps, but allow it
>    to keep some compatibility with ISO standard.
>
>    “Z” in the second format refers to “Zulu” time (another name for UTC)
>    and must be either the last character in the timestamp or the
>    last character before space. Not sure if many users are familiar with
>    “Z” convention, but it is (1) in ISO; (2) succinct for users who are
>    familiar with it. We will prefer +00 number offset in auto-generated
>    timestamps.
>
>    Examples:
>    2022-11-12 12:00+02 # 12:00 UTC+2
>    2022-11-12 14:00+0230 # 14:00 UTC+2:30
>    2022-11-12 14:00-0230 # 14:00 UTC-2:30
>    2022-11-12 14:00Z # 14:00 UTC
>
>    The offset is a subset of what is defined by ISO8601.
>
>    Note that unlike ISO8601, “:” is not allowed in the offset specifier.
>    This is to disambiguate with the time intervals in Org timestamps:
>    [2022-11-12 Sat 08:00]–[2022-11-12 Sat 09:00]  in Org is a time range from 8am to 9am.
>
>    For time ranges, we will only allow a single offset and time zone
>    specifier for both start and end times:
>    [2022-11-12 Sat 08:00]–[2022-11-12 Sat 09:00]
>    If different time zones are necessary to specify the start/end times,
>    users can still use full timestamp range syntax
>    [2022-11-12 Sat 08:00]–[2022-11-12 Sat 22:00]
>
>    The format is also forward-compatible with extending Org timestamps
>    for second/sub-second precision: 2022-11-12 14:00:05.0012+0230 will
>    remain valid if we decide to adopt such format.

This functions well, however I see a potential to be confusing at a glance here.
Consider the visual similarity of 10:30 to 11:00 in local time and 10:30 in
UTC-11, and the combination of both.

┌────
│ [2022-11-12 10:30-11:00]
│ [2022-11-12 10:30-1100]
│ [2022-11-12 10:30-11:00-1100]
└────

I’d be inclined to put the UTC offset together with the time zone name if
possible. Do you think something along the lines of `@-1100,America/Anchorage'
could be viable? I’d think that would reduce the chance of confusion.

┌────
│ [2022-11-12 10:30-11:00]
│ [2022-11-12 10:30 @-1100]
│ [2022-11-12 10:30-11:00 @-1100]
└────

Looking at this, I also personally rather like that it puts all the timezone
information together in a single `@TZINFO' token.

> 2. Timestamp with time zone specifier
>
>    YYYY-MM-DD [optional day name] HH:MM[^ ]* @[!]?<[^ \]>]>
>
>    For now, time zone name will only be processed when it follows TZ
>    POSIX format. If necessary, the proposed syntax will still allow
>    extensions to TZ POSIX.
>
>    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
>
>    The “@” symbol is selected to disambiguate time zone specifier from
>    other auxiliary information in the timestamp. Like calendar name,
>    which might be added in future. Note that we cannot use […] from
>    the standard draft. I selected “@” because it is read as “at” -
>    location specifier.
>
>    The “!” symbol is adapted from
>    <https://datatracker.ietf.org/doc/draft-ietf-sedate-datetime-extended/>
>
>    I use space before “@” to improve readability. We deviate from the
>    standard here so may as well. In contrast, no space before [+-]offset
>    is closer to the standard yet not cluttering the timestamp too much
>    (IMHO).

This looks like it works rather nicely to me.

> 3. (1) and (2) can be combined
>
>    2022-11-12 12:00+08 @Asia/Singapore
>
>    Org will unconditionally use +08 offset and ignore the time zone
>    name. We prefer absolute offset because it is non-ambiguous wrt
>    out-of-date tzdb on the computer. One may also not update the TZ
>    variable upon travelling - the system clock will again be more likely
>    accurate.
>
>    This redundant time offset info can serve as human-readable
>    indication of absolute time, while the time zone name will indicate
>    the location.
>
>    2022-11-12 12:00+07 @!Asia/Singapore
>
>    Org will calculate the internal time for both +07 offset and
>    Asia/Singapore time zone. If they do not match, Org will issue a
>    warning. The offset will still be preferred if we have to proceed.
>
>    This can be useful when planning future meetings and sending Org file
>    with a timestamp to someone else, potentially with obsolete tzdb.

I like the way that combining these features works, but I do wonder if perhaps
warning when these two bits of information don’t match should be the default
behaviour, and the `!' used to specify which of them should be prioritised?

It also occurs to me that this proposed behaviour might be easier with a single
`@TZINFO' form as I mentioned earlier, e.g.

┌────
│ [2022-11-12 12:00 @+07,Asia/Singapore]  # warn when mismatch
│ [2022-11-12 12:00 @+07,!Asia/Singapore] # use Asia/Singapore over +07
│ [2022-11-12 12:00 @!+07,Asia/Singapore] # use +07 over Asia/Singapore
└────

What are you thoughts on this?

Thanks again for your work on this,
Timothy

-- 
Timothy (‘tecosaur’/‘TEC’), Org mode contributor.
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/tec>.