Timestamp and timestamp range definitions

Timestamp and timestamp range definitions

[Ilya Chernyshov]

Hello

What's a type of timestamp <2022-10-15 Sat 10:00-13:00>?

From org-manual:

the definition for a timestamp is:

A timestamp is a specification of a date (possibly with a time or 
a range of times) in a
special format, either '<2003-09-16 Tue>' or '<2003-09-16 Tue 
09:39>'
or ‘<2003-09-16 Tue 12:00-12:30>'

Also, the definition for timestamp range is:

Two timestamps connected by '--' denote a range. The headline is 
shown on
the first and last day of the range, and on any dates that are 
displayed and fall
in the range. Here is an example:
,* Meeting in Amsterdam
<2004-08-23 Mon>--<2004-08-26 Thu>

But, according to tests in test-org-element.el such a timestamp is
considered a timerange [added in commit cb32494e2]:

(should
   (eq 'active-range
       (org-test-with-temp-text "<2012-03-29 Thu 7:30-16:40>"
	 (org-element-property :type (org-element-context)))))

So, we either should change the behavior of
(org-element-timestamp-parser) or update the definitions of 
timestamp
and timestamp range in org-manual. What do you think?
-- 
Best,
Ilya

Re: Timestamp and timestamp range definitions

[Ihor Radchenko]

Ilya Chernyshov <ichernyshovvv@gmail.com> writes:

> So, we either should change the behavior of
> (org-element-timestamp-parser) or update the definitions of 
> timestamp
> and timestamp range in org-manual. What do you think?

Updating the manual will make more sense. Would you mind writing a patch?

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

Re: Timestamp and timestamp range definitions

[Ilya Chernyshov]

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


Ihor Radchenko <yantar92@posteo.net> writes:

> Updating the manual will make more sense. Would you mind writing 
> a patch?

Of course.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-manual.org-Update-timestamp-and-timerange-defini.patch --]
[-- Type: text/x-patch, Size: 2629 bytes --]

From da84673301de7e9453cb359536235d8ce56399f1 Mon Sep 17 00:00:00 2001
From: Ilya Chernyshov <ichernyshovvv@gmail.com>
Date: Fri, 17 Feb 2023 01:23:27 +0700
Subject: [PATCH] org-manual.org: Update timestamp and timerange definitions

* doc/org-manual.org (Timestamps): Document that time specification of the
form <2023-02-17 Fri 10:00-12:00> is not a timestamp, but a timerange.
---
 doc/org-manual.org | 27 +++++++++++++++++----------
 1 file changed, 17 insertions(+), 10 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 2d38cf76c..5b6633417 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5915,12 +5915,12 @@ ** Timestamps
 #+cindex: deadlines
 #+cindex: scheduling
 
-A timestamp is a specification of a date (possibly with a time or
-a range of times) in a special format, either =<2003-09-16 Tue>= or
-=<2003-09-16 Tue 09:39>= or =<2003-09-16 Tue 12:00-12:30>=[fn:19].
-A timestamp can appear anywhere in the headline or body of an Org tree
-entry.  Its presence causes entries to be shown on specific dates in
-the agenda (see [[*Weekly/daily agenda]]).  We distinguish:
+A timestamp is a specification of a date (possibly with a time) in a
+special format, either =<2003-09-16 Tue>= or
+=<2003-09-16 Tue 09:39>=[fn:19].  A timestamp can appear anywhere in
+the headline or body of an Org tree entry.  Its presence causes
+entries to be shown on specific dates in the agenda (see [[*Weekly/daily
+agenda]]).  We distinguish:
 
 - Plain timestamp; Event; Appointment ::
 
@@ -5935,7 +5935,7 @@ ** Timestamps
   ,* Meet Peter at the movies
     <2006-11-01 Wed 19:15>
   ,* Discussion on climate change
-    <2006-11-02 Thu 20:00-22:00>
+    <2006-11-02 Thu>
   #+end_example
 
 - Timestamp with repeater interval ::
@@ -5974,15 +5974,22 @@ ** Timestamps
 
   #+cindex: timerange
   #+cindex: date range
-  Two timestamps connected by =--= denote a range.  The headline is
-  shown on the first and last day of the range, and on any dates that
-  are displayed and fall in the range.  Here is an example:
+  Two timestamps connected by =--= denote a range.  In the agenda, the
+  headline is shown on the first and last day of the range, and on any
+  dates that are displayed and fall in the range.  Here is an example:
 
   #+begin_example
   ,** Meeting in Amsterdam
      <2004-08-23 Mon>--<2004-08-26 Thu>
   #+end_example
 
+  Timerange is a timestamp consisting of two time units connected by =-=
+
+  #+begin_example
+  ,* Discussion on climate change
+     <2006-11-02 Thu 10:00-12:00>
+  #+end_example
+
 - Inactive timestamp ::
 
   #+cindex: timestamp, inactive
-- 
2.39.0


[-- Attachment #3: Type: text/plain, Size: 16 bytes --]


-- 
Best,
Ilya

Re: Timestamp and timestamp range definitions

[Ihor Radchenko]

Ilya Chernyshov <ichernyshovvv@gmail.com> writes:

> Subject: [PATCH] org-manual.org: Update timestamp and timerange definitions
>

Thanks!
Applied, onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=715f74db3

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