[PATCH] Clarify that REST is not supported on the start TIME in a time-range timestamp.

[PATCH] Clarify that REST is not supported on the start TIME in a time-range timestamp.

[Tom Alexander]

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

If REST is included in the first TIME on a time-range timestamp then the entire timestamp becomes a single range-less timestamp. To test I used the following test document:
```
[1970-01-01 Thu 8:15-13:15foo]
[1970-01-01 Thu 8:15foo-13:15]
```

The first line parses as a timerange from 8:15-13:15.
The second line parses as a single timestamp at 8:15.

--
Tom Alexander
pgp: https://fizz.buzz/pgp.asc

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-syntax.org-Timestamps-Clarify-that-REST-is-not-s.patch --]
[-- Type: text/x-patch; name="0001-org-syntax.org-Timestamps-Clarify-that-REST-is-not-s.patch", Size: 1616 bytes --]

From b1114e983d961d48e1d837b8d2ad209a976a5417 Mon Sep 17 00:00:00 2001
From: Tom Alexander <tom@fizz.buzz>
Date: Mon, 2 Oct 2023 17:35:28 -0400
Subject: [PATCH] * org-syntax.org (Timestamps): Clarify that REST is not
 supported on the start TIME in a time-range timestamp.

If REST is included in the first TIME on a time-range timestamp then the entire timestamp becomes a single range-less timestamp. To test I used the following test document:
```
[1970-01-01 Thu 8:15-13:15foo]
[1970-01-01 Thu 8:15foo-13:15]
```

The first line parses as a timerange from 8:15-13:15.
The second line parses as a single timestamp at 8:15.
---
 org-syntax.org | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/org-syntax.org b/org-syntax.org
index c2061431..0c326ba8 100644
--- a/org-syntax.org
+++ b/org-syntax.org
@@ -1686,9 +1686,10 @@ YYYY-MM-DD DAYNAME
   - DAYNAME (optional) :: A string consisting of non-whitespace
     characters except =+=, =-=, =]=, =>=, a digit, or =\n=.
 + TIME (optional) :: An instance of the pattern =H:MMREST= where =H=
-  represents a one to two digit number (and can start with =0=), and =M=
-  represents a single digit.  =REST= can contain anything but =\n= or
-  closing bracket.
+  represents a one to two digit number (and can start with =0=), and
+  =M= represents a single digit.  =REST= can contain anything but =\n=
+  or closing bracket. =REST= cannot exist on the start TIME in a
+  time-range timestamp (the patterns with =TIME-TIME=).
 + REPEATER-OR-DELAY (optional) :: An instance of the following pattern:
   #+begin_example
 MARK VALUE UNIT
-- 
2.42.0

Re: [PATCH] Clarify that REST is not supported on the start TIME in a time-range timestamp.

[Tom Alexander]

Potentially related, org-mode is accepting this malformed timestamp from[1]:
```
<2016-02-14 Sun ++y>
```

The org-mode documentation[2] only includes REST with TIME, defining TIME as "H:MMREST". The above does not have any TIME but it accepts the timestamp anyway:
```
(timestamp
  :type active
  :range-type nil
  :raw-value "<2016-02-14 Sun ++y>"
  :year-start 2016
  :month-start 2
  :day-start 14
  :hour-start nil
  :minute-start nil
  :year-end 2016
  :month-end 2
  :day-end 14
  :hour-end nil
  :minute-end nil
)
```

Perhaps that grammar is wrong and REST needs to be separated from TIME?

[1] https://github.com/howardabrams/pdx-emacs-hackers/blob/bfb7bd640fdf0ce3def21f9fc591ed35d776b26d/workshops/org-mode-gtd-feature-demo.org#L183
[2] https://orgmode.org/worg/org-syntax.html#Timestamps

--
Tom Alexander
pgp: https://fizz.buzz/pgp.asc

Re: [PATCH] Clarify that REST is not supported on the start TIME in a time-range timestamp.

[Ihor Radchenko]

"Tom Alexander" <tom@fizz.buzz> writes:

> Potentially related, org-mode is accepting this malformed timestamp from[1]:
> ```
> <2016-02-14 Sun ++y>
> ```
>
> The org-mode documentation[2] only includes REST with TIME, defining TIME as "H:MMREST". The above does not have any TIME but it accepts the timestamp anyway:
> ...
> Perhaps that grammar is wrong and REST needs to be separated from TIME?

We have no internal consistency here, AFAIR.
The actual matching is done with

(defconst org-element--timestamp-regexp
  (concat org-ts-regexp-both
	  "\\|"
	  "\\(?:<[0-9]+-[0-9]+-[0-9]+[^>\n]+?\\+[0-9]+[dwmy]>\\)"
	  "\\|"
	  "\\(?:<%%\\(?:([^>\n]+)\\)>\\)")
  "Regexp matching any timestamp type object.")

with org-ts-regexp-both matching

(rx (seq
       (= 4 digit) "-" (= 2 digit) "-" (= 2 digit)
       (optional " " (*? nonl))))

(and also brackets)

Then, `org-element-timestamp-parser' looks for DATE/TIME/REPEATERS/etc
inside the above match, disregarding any order:

(string-match
		    "[012]?[0-9]:[0-5][0-9]\\(-\\([012]?[0-9]\\):\\([0-5][0-9]\\)\\)"
		    date-start)

(string-match "\\([.+]?\\+\\)\\([0-9]+\\)\\([hdwmy]\\)"
				 raw-value)                    

(string-match "\\(-\\)?-\\([0-9]+\\)\\([hdwmy]\\)" raw-value)

However, not all the Org code is using org-element parser yet. Certain
parts of Org are matching manually using a separate, more strict
regexps, like org-ts-regexp0, org-ts-regexp1, ...

So, we chose to use a more strict definition in org-syntax for the time
being, before we consolidate things together in more uniform ways.

As for the problem with REST you raised, I am inclined to remove it from
syntax doc for the time being - it only creates more confusion,
unfortunately.

-- 
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: Clarify that REST is not supported on the start TIME in a time-range timestamp.

[Tom Alexander]

> As for the problem with REST you raised, I am inclined to remove it from
> syntax doc for the time being - it only creates more confusion,
> unfortunately.

Makes sense, thanks. Is there anything we do to mark patches as rejected? I removed [PATCH] from the subject line.

--
Tom Alexander
pgp: https://fizz.buzz/pgp.asc

Re: Clarify that REST is not supported on the start TIME in a time-range timestamp.

[Ihor Radchenko]

"Tom Alexander" <tom@fizz.buzz> writes:

>> As for the problem with REST you raised, I am inclined to remove it from
>> syntax doc for the time being - it only creates more confusion,
>> unfortunately.
>
> Makes sense, thanks. Is there anything we do to mark patches as rejected? I removed [PATCH] from the subject line.

Canceled.
^^ This cancels the patch. See https://tracker.orgmode.org/howto

I have removed REST spec from the doc in https://git.sr.ht/~bzg/worg/commit/ba8f5fdc

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