Re: [BUG] Undocumented convention for org-time-stamp-custom-formats to be "<...>" (was: time-stamp in DONE tag is not really displayed)

[Ihor Radchenko <yantar92@posteo.net>]

Tim Cross <theophilusx@gmail.com> writes:

>> I propose to do the following:
>> 1. org-time-stamp-formats and org-time-stamp-custom-formats will be
>>    treated as is, unless they contain "<" and ">" and the first and the
>>    last char.
>> 2. If the formats do contain <...>, strip the "<" and ">".
>> 3. Document (2) in the docstrings.
>>
>> Any objections?
>
> Little unsure/confused regarding what is being proposed here.
>
> - If we are removing <...>, does that mean we just retain [..] for
>   inactive timestamps and all other timestamps are 'active' by default?

org-time-stamp-formats is a constant. Users are not supposed to change
it. So, the proposed stripping of "<" and ">" has a pure purpose of not
breaking third-party code that might be using its current default value.
It is more about some internal code assumptions.

org-time-stamp-custom-formats currently has the following docstring:

    Custom formats for time stamps.  See format-time-string for the syntax.
    
    These are overlaid over the default ISO format if the variable
    org-display-custom-times is set.  Time like %H:%M should be at the
    end of the second format.  The custom formats are also honored by export
    commands, if custom time display is turned on at the time of export.

There is nothing in the docstring indicating that "<" and ">" are
required or used in any way. The current Org code assumptions only
create confusion among the users.

I propose to strip "<" and ">" just to avoid breakage if users happened
to set org-time-stamp-custom-formats to the value with "<...>" that is
required to make this defcustom working in older Org versions.

If users abused the undocumented behavior and used "[...]", we do not
need to worry as it is out of what was promised.

At the end, old user settings of org-time-stamp-custom-formats should
remain working within docstring promises.
Old user code using org-time-stamp-formats constant should also remain
working.
But users will not need to provide brackets in
org-time-stamp-custom-formats after the proposed change.

The above is the most safe way to retain backwards compatibility while
removing the existing confusion with the docstring.

> - How will this change impact code which distinguishes active/inactive
>   timestamps based on presence/absence of <..> and [..]?

org-time-stamp-formats value will not change.
org-time-stamp-custom-formats value had no impact on buffer text---just
the overlayed timestamp display. No code should be affected.

> - What impact will this have on existing org files?

None.

> - Will this cause issues in parsing when you may have dates/times which
>   are not supposed to be timestamps, but will look the same as
>   timestamps? How will you distinguish them?

No buffer text will be affected.

> Personally, I like the clear distinction between what is a timestamp and
> what isn't and what is an active timestamp and what is an inactive
> timestamp.

There is nothing about active/inactive timestamps in the discussed
variables. The usage of "<" and ">" is historical and mostly ignored by
Org code. First and last characters are simply stripped, and the required
brackets are being used when inserting the actual timestamps.

The proposed change simply aims to remove the undocumented requirement
about brackets.

-- 
Ihor Radchenko // yantar92,
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/yantar92>