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

[Ihor Radchenko]

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

Done on main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=e3a7c01874c9bb80e04ffa58c578619faf09e7f0

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

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  writes:

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

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

[Samuel Wales]

please feel free to ignore this post if it is off topic.  i cannot
tell if it is of topic or not.

long ago i wanted to mke it so that if i hovered over a timesamp it
woud produce a time span notation relative to .  and also i
wanted to make a custom time stamp format for the same purpose.  but i
think was not possible.

if any changes are actually done to custom format, perhaps, if not
already done, hooks can be strategically added or so.


On 10/25/22, Ihor Radchenko  wrote:
> Tim Cross  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 .
> Support Org development at ,
> or support my work at 
>
>


-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

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

[Ihor Radchenko]

Tim Cross  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 .
Support Org development at ,
or support my work at 

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  writes:

> Uwe Brauer  writes:
>
>> My time-stamps are of the form <2022-10-23 Sun>
>> I have an entry like this 
>>
>> - State "DONE"   from "WAIT"   [2022-10-23 21:06] \\
>>
>>
>>
>> However it is displayed when I use org-toggle-time-stamp-overlays  as
>>  [23.10.%]
>>
>> Neither the year not the time is displayed, why!
>>  
>> I have set 
>> org-time-stamp-custom-formats 
>> to 
>> (" %d.%m.%Y " . " %d.%m.%Y")
>>
>> I am puzzled, any ideas?
>
> Confirmed.
>
> This is because Org expects the first and the last characters in
> org-time-stamp-custom-formats to be opening/closing brackets.
> (undocumented)
>
> Why?
> Because org-time-stamp-formats does so.
>
> Why does org-time-stamp-formats does so?
> No idea.
> This code dates back to initial Org commits.
>
> I think it would make sense to change it.
> However, if we change special treatment of the first/last characters in
> org-time-stamp-custom-formats, it will also make sense to change
> org-time-stamp-formats constant.
>
> For backwards compatibility, we will need to keep special treatment to
> strip brackets around the formats, if present.
>
> 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?

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

- What impact will this have on existing org files?

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

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.

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

[Ihor Radchenko]

Uwe Brauer  writes:

> My time-stamps are of the form <2022-10-23 Sun>
> I have an entry like this 
>
> - State "DONE"   from "WAIT"   [2022-10-23 21:06] \\
>
>
>
> However it is displayed when I use org-toggle-time-stamp-overlays  as
>  [23.10.%]
>
> Neither the year not the time is displayed, why!
>  
> I have set 
> org-time-stamp-custom-formats 
> to 
> (" %d.%m.%Y " . " %d.%m.%Y")
>
> I am puzzled, any ideas?

Confirmed.

This is because Org expects the first and the last characters in
org-time-stamp-custom-formats to be opening/closing brackets.
(undocumented)

Why?
Because org-time-stamp-formats does so.

Why does org-time-stamp-formats does so?
No idea.
This code dates back to initial Org commits.

I think it would make sense to change it.
However, if we change special treatment of the first/last characters in
org-time-stamp-custom-formats, it will also make sense to change
org-time-stamp-formats constant.

For backwards compatibility, we will need to keep special treatment to
strip brackets around the formats, if present.

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?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at