From: Ihor Radchenko <yantar92@posteo.net>
To: Tim Cross <theophilusx@gmail.com>
Cc: emacs-orgmode@gnu.org
Subject: Re: [BUG] Undocumented convention for org-time-stamp-custom-formats to be "<...>" (was: time-stamp in DONE tag is not really displayed)
Date: Wed, 26 Oct 2022 04:12:31 +0000 [thread overview]
Message-ID: <87r0yvql3k.fsf@localhost> (raw)
In-Reply-To: <861qqwk778.fsf@gmail.com>
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>
next prev parent reply other threads:[~2022-10-26 4:14 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-10-23 20:32 time-stamp in DONE tag is not really displayed Uwe Brauer
2022-10-24 9:07 ` [BUG] Undocumented convention for org-time-stamp-custom-formats to be "<...>" (was: time-stamp in DONE tag is not really displayed) Ihor Radchenko
2022-10-24 15:21 ` [BUG] Undocumented convention for org-time-stamp-custom-formats to be "<...>" Uwe Brauer
2022-10-25 6:18 ` Ihor Radchenko
2022-10-25 1:29 ` [BUG] Undocumented convention for org-time-stamp-custom-formats to be "<...>" (was: time-stamp in DONE tag is not really displayed) Tim Cross
2022-10-26 4:12 ` Ihor Radchenko [this message]
2022-10-26 4:20 ` Samuel Wales
2022-10-26 5:06 ` Tim Cross
2022-11-07 7:21 ` Ihor Radchenko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87r0yvql3k.fsf@localhost \
--to=yantar92@posteo.net \
--cc=emacs-orgmode@gnu.org \
--cc=theophilusx@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).