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

[Tim Cross]

Ihor Radchenko <yantar92@posteo.net> writes:

> 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.

OK, thanks for clarifying. Based on this, I don't see any issues with
your proposed change.