Is this proper time format?

Is this proper time format?

[David Masterson]

I have a meeting for this week from 10:30-12:15 M-Th.  Can I represent
that this way?

        <2023-06-05 Mon 10:30-12:15>--<2023-06-08 Thu 10:30-12:15>

Is this a valid date/time?
-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

> I have a meeting for this week from 10:30-12:15 M-Th.  Can I represent
> that this way?
>
>         <2023-06-05 Mon 10:30-12:15>--<2023-06-08 Thu 10:30-12:15>

No.

> Is this a valid date/time?

It is valid in current parser implementation, but it is not what you
expect. The first time range is ignored.

-- 
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: Is this proper time format?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>> I have a meeting for this week from 10:30-12:15 M-Th.  Can I represent
>> that this way?
>>
>>         <2023-06-05 Mon 10:30-12:15>--<2023-06-08 Thu 10:30-12:15>
>
> No.
>
>> Is this a valid date/time?
>
> It is valid in current parser implementation, but it is not what you
> expect. The first time range is ignored.

Hmm.  What about this:

      <2023-06-05 Mon>--<2023-06-08 Thu 10:30-12:15>

Is there a recommended specification for my meeting?  Or do I have to
break it into multiple tasks (one for each day)?

Anyone know how well BeOrg, Orgzly, and Organice handle this?

-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

> Hmm.  What about this:
>
>       <2023-06-05 Mon>--<2023-06-08 Thu 10:30-12:15>
>
> Is there a recommended specification for my meeting?  Or do I have to
> break it into multiple tasks (one for each day)?

AFAIK, closed date intervals with time are currently not supported by
org-agenda. You can instead use diary sexp timestamps, a bunch of active
timestamps in the body, or M-x org-clone-subtree-with-time-shift

> Anyone know how well BeOrg, Orgzly, and Organice handle this?

No idea.

-- 
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: Is this proper time format?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>> Hmm.  What about this:
>>
>>       <2023-06-05 Mon>--<2023-06-08 Thu 10:30-12:15>
>>
>> Is there a recommended specification for my meeting?  Or do I have to
>> break it into multiple tasks (one for each day)?
>
> AFAIK, closed date intervals with time are currently not supported by
> org-agenda. You can instead use diary sexp timestamps, a bunch of active
> timestamps in the body, or M-x org-clone-subtree-with-time-shift

"a bunch of active timestamps"?!?  Ooh!  I hadn't gotten the impression
that that was allowed from the "Dates and Times" section of the manual.
It always talked about "a timestamp" and it made sense to me that a task
would only have one timestamp.  Can a statement be added to the manual
to make this explicit?

By closed date interval, I assume you mean "<time1>--<time2>".  That is
mentioned in 8.1 of the manual. It's header is "Time/Date range", but it
only talks about dates (no times) including in the example.  If times
are allowed, then the paragraph could include a time example.  If not,
then the header should be changed and "timestamp" should be changed to
"datestamp". 

-- 
David Masterson

Re: Is this proper time format?

[Samuel Wales]

On 6/6/23, David Masterson <dsmasterson@gmail.com> wrote:
>Ooh!  I hadn't gotten the impression
> that that was allowed from the "Dates and Times" section of the manual.

thre exists org-agenda-skip-additional-timestamps-same-entry

Re: Is this proper time format?

[David Masterson]

Samuel Wales <samologist@gmail.com> writes:

> On 6/6/23, David Masterson <dsmasterson@gmail.com> wrote:
>>Ooh!  I hadn't gotten the impression
>> that that was allowed from the "Dates and Times" section of the manual.
>
> thre exists org-agenda-skip-additional-timestamps-same-entry

thanks -- I hadn't seen that before.

-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

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

David Masterson <dsmasterson@gmail.com> writes:

>> AFAIK, closed date intervals with time are currently not supported by
>> org-agenda. You can instead use diary sexp timestamps, a bunch of active
>> timestamps in the body, or M-x org-clone-subtree-with-time-shift
>
> "a bunch of active timestamps"?!?  Ooh!  I hadn't gotten the impression
> that that was allowed from the "Dates and Times" section of the manual.
> It always talked about "a timestamp" and it made sense to me that a task
> would only have one timestamp.  Can a statement be added to the manual
> to make this explicit?

How about the attached patch?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-org-manual.org-Clarify-how-timestamps-are-consid.patch --]
[-- Type: text/x-patch, Size: 1941 bytes --]

From c2e91d5c2c88967b5fb28a077c3c7107a2622334 Mon Sep 17 00:00:00 2001
Message-Id: <c2e91d5c2c88967b5fb28a077c3c7107a2622334.1686219879.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Thu, 8 Jun 2023 13:22:45 +0300
Subject: [PATCH] doc/org-manual.org: Clarify how timestamps are considered by
 agenda

* doc/org-manual.org (Timestamps): Clarify that multiple timestamps
may be present under a heading.
(Weekly/daily agenda): Add footnote explaining how timestamps are
selected when building agenda views.

Reported-by: David Masterson <dsmasterson@gmail.com>
Link: https://orgmode.org/list/SJ0PR03MB5455C08FAD47C64F6EA7054CA252A@SJ0PR03MB5455.namprd03.prod.outlook.com
---
 doc/org-manual.org | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index c11694849..3b54764ab 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -6002,7 +6002,8 @@ ** Timestamps
 =<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:
+agenda]]).  There can be more than one timestamp in each entry.  We
+distinguish:
 
 - Plain timestamp; Event; Appointment ::
 
@@ -8872,7 +8873,11 @@ *** Weekly/daily agenda
 #+cindex: daily agenda
 
 The purpose of the weekly/daily /agenda/ is to act like a page of
-a paper agenda, showing all the tasks for the current week or day.
+a paper agenda, showing all the tasks for the current week or day
+ [fn:: The tasks are displayed according to the contained timestamps.
+Agenda has a number of customizations that determine which timestamps
+are considered.  See =org-agenda-skip= and =org-agenda-daily/weekly=
+customization groups for the full list of customizations.].
 
 - {{{kbd(M-x org-agenda a)}}} (~org-agenda-list~) ::
 
-- 
2.40.0


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


> By closed date interval, I assume you mean "<time1>--<time2>".  That is
> mentioned in 8.1 of the manual. It's header is "Time/Date range", but it
> only talks about dates (no times) including in the example.

Handling of date intervals when TIME1/2 have time specifications is
undefined behaviour for now. And I am not in favour of making it defined -
we may consider using this semantics to define repeater intervals with
end date in future. That would allow what you attempted to do in the
original email, but using <2023-06-05 Mon 10:30-12:15>--<2023-06-08 Thu>
semantics. See https://orgmode.org/list/877cxp1fbx.fsf@localhost

> If times are allowed, then the paragraph could include a time example.
> If not, then the header should be changed and "timestamp" should be
> changed to "datestamp".

No. The same section talks about time range: <2006-11-02 Thu 10:00-12:00>

"Timestamp" is the general term we use. We make it explicit in the
parent section that timestamps may or may not have time specification:

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

-- 
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: Is this proper time format?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>>> AFAIK, closed date intervals with time are currently not supported by
>>> org-agenda. You can instead use diary sexp timestamps, a bunch of active
>>> timestamps in the body, or M-x org-clone-subtree-with-time-shift
>>
>> "a bunch of active timestamps"?!?  Ooh!  I hadn't gotten the impression
>> that that was allowed from the "Dates and Times" section of the manual.
>> It always talked about "a timestamp" and it made sense to me that a task
>> would only have one timestamp.  Can a statement be added to the manual
>> to make this explicit?
>
> How about the attached patch?

I think that's good, but...

>> By closed date interval, I assume you mean "<time1>--<time2>".  That is
>> mentioned in 8.1 of the manual. It's header is "Time/Date range", but it
>> only talks about dates (no times) including in the example.
>
> Handling of date intervals when TIME1/2 have time specifications is
> undefined behaviour for now. And I am not in favour of making it defined -
> we may consider using this semantics to define repeater intervals with
> end date in future. That would allow what you attempted to do in the
> original email, but using <2023-06-05 Mon 10:30-12:15>--<2023-06-08 Thu>
> semantics. See https://orgmode.org/list/877cxp1fbx.fsf@localhost
>
>> If times are allowed, then the paragraph could include a time example.
>> If not, then the header should be changed and "timestamp" should be
>> changed to "datestamp".
>
> No. The same section talks about time range: <2006-11-02 Thu 10:00-12:00>
>
> "Timestamp" is the general term we use. We make it explicit in the
> parent section that timestamps may or may not have time specification:
>
>     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>=

Maybe I'm not explicit enough.  In section 8.1 of the Org 9.6 manual is
a subsection "Time/Date Range" that *implies* times are supported in
ranges by the use of words "time" and "timestamp" when, above, you're
saying they are undefined (unsupported?) for now.  I'm merely saying
adjust the manual to remove the implication.

-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>> "Timestamp" is the general term we use. We make it explicit in the
>> parent section that timestamps may or may not have time specification:
>>
>>     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>=
>
> Maybe I'm not explicit enough.  In section 8.1 of the Org 9.6 manual is
> a subsection "Time/Date Range" that *implies* times are supported in
> ranges by the use of words "time" and "timestamp" when, above, you're
> saying they are undefined (unsupported?) for now.  I'm merely saying
> adjust the manual to remove the implication.

Please check the manual from main branch of Org. It has more text:

- Time/Date range ::

  #+cindex: timerange
  #+cindex: date range
  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

-- 
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: Is this proper time format?

[David Masterson]

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

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>>> "Timestamp" is the general term we use. We make it explicit in the
>>> parent section that timestamps may or may not have time specification:
>>>
>>>     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>=
>>
>> Maybe I'm not explicit enough.  In section 8.1 of the Org 9.6 manual is
>> a subsection "Time/Date Range" that *implies* times are supported in
>> ranges by the use of words "time" and "timestamp" when, above, you're
>> saying they are undefined (unsupported?) for now.  I'm merely saying
>> adjust the manual to remove the implication.
>
> Please check the manual from main branch of Org. It has more text:

I disagree. I cloned Org from Savannah and made the attached patch
file from the main branch.  First time for me attaching a file to a
message.   Does it work for you?


[-- Attachment #2: Patch of Org-Guide and Org-Manual --]
[-- Type: text/plain, Size: 6007 bytes --]

diff --git a/doc/org-guide.org b/doc/org-guide.org
index 95828e4c0..167f62e49 100644
--- a/doc/org-guide.org
+++ b/doc/org-guide.org
@@ -1088,12 +1088,12 @@ time information is called a /timestamp/ in Org mode.
 :DESCRIPTION: Assigning a time to a tree entry.
 :END:
 
-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>=.
-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 [[*The Weekly/Daily Agenda]]).  We distinguish:
+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>=.  One or
+more timestamps 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 [[*The Weekly/Daily Agenda]]).  We distinguish:
 
 - Plain timestamp; Event; Appointment ::
 
@@ -1132,15 +1132,25 @@ the agenda (see [[*The Weekly/Daily Agenda]]).  We distinguish:
     <%%(diary-float t 4 2)>
   #+end_example
 
-- Time/Date range ::
+- Date range ::
 
-  Two timestamps connected by =--= denote a range.
+  Two timestamps connected by =--= denote a date range.  NOTE: time is
+  not specified in these timestamps -- just dates,
 
   #+begin_example
   ,** Meeting in Amsterdam
      <2004-08-23 Mon>--<2004-08-26 Thu>
   #+end_example
 
+- Time range ::
+
+  Two times in a timestamp connected by =-= denote a time range.
+
+  #+begin_example
+  ,** Planning meeting
+     <2004-08-23 Mon 9:00-10:00>
+  #+end_example
+
 - Inactive timestamp ::
 
   Just like a plain timestamp, but with square brackets instead of
diff --git a/doc/org-manual.org b/doc/org-manual.org
index c11694849..824a46eaf 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5991,42 +5991,32 @@ is used in a much wider sense.
 :PROPERTIES:
 :DESCRIPTION: Assigning a time to a tree entry.
 :END:
-#+cindex: timestamps
-#+cindex: ranges, time
-#+cindex: date stamps
-#+cindex: deadlines
-#+cindex: scheduling
-
-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:
+
+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>=.  One or
+more timestamps 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 [[*The Weekly/Daily Agenda]]).  We distinguish:
 
 - Plain timestamp; Event; Appointment ::
 
-  #+cindex: timestamp
-  #+cindex: appointment
   A simple timestamp just assigns a date/time to an item.  This is
   just like writing down an appointment or event in a paper agenda.
-  In the agenda display, the headline of an entry associated with
-  a plain timestamp is shown exactly on that date.
 
   #+begin_example
   ,* Meet Peter at the movies
     <2006-11-01 Wed 19:15>
   ,* Discussion on climate change
-    <2006-11-02 Thu>
+    <2006-11-02 Thu 20:00-22:00>
   #+end_example
 
 - Timestamp with repeater interval ::
 
-  #+cindex: timestamp, with repeater interval
   A timestamp may contain a /repeater interval/, indicating that it
   applies not only on the given date, but again and again after
-  a certain interval of N hours (h), days (d), weeks (w), months (m),
-  or years (y).  The following shows up in the agenda every Wednesday:
+  a certain interval of N days (d), weeks (w), months (m), or years
+  (y).  The following shows up in the agenda every Wednesday:
 
   #+begin_example
   ,* Pick up Sam at school
@@ -6037,46 +6027,36 @@ agenda]]).  We distinguish:
 
   #+cindex: diary style timestamps
   #+cindex: sexp timestamps
-  # Mentioned inside the footnote.
-  #+findex: org-date
-  #+findex: org-anniversary
-  #+findex: org-cyclic
-  #+findex: org-block
-
   For more complex date specifications, Org mode supports using the
-  special expression diary entries implemented in the
-  [[info:emacs#Special Diary Entries][Emacs Calendar package]][fn:20].
-  For example, with optional time:
+  special expression diary entries implemented in the Emacs Calendar
+  package.  For example, with optional time:
 
   #+begin_example
   ,* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
     <%%(diary-float t 4 2)>
   #+end_example
 
-- Time/Date range ::
+- Date range ::
 
-  #+cindex: timerange
-  #+cindex: date range
-  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:
+  Two timestamps connected by =--= denote a date range.  NOTE: time is
+  not specified in these timestamps -- just dates,
 
   #+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 =-=
+- Time range ::
+
+  Two times in a timestamp connected by =-= denote a time range.
 
   #+begin_example
-  ,* Discussion on climate change
-     <2006-11-02 Thu 10:00-12:00>
+  ,** Planning meeting
+     <2004-08-23 Mon 9:00-10:00>
   #+end_example
 
 - Inactive timestamp ::
 
-  #+cindex: timestamp, inactive
-  #+cindex: inactive timestamp
   Just like a plain timestamp, but with square brackets instead of
   angular ones.  These timestamps are inactive in the sense that they
   do /not/ trigger an entry to show up in the agenda.

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



-- 
David Masterson

Re: Is this proper time format?

[David Masterson]

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

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>>> "Timestamp" is the general term we use. We make it explicit in the
>>> parent section that timestamps may or may not have time specification:
>>>
>>>     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>=
>>
>> Maybe I'm not explicit enough.  In section 8.1 of the Org 9.6 manual is
>> a subsection "Time/Date Range" that *implies* times are supported in
>> ranges by the use of words "time" and "timestamp" when, above, you're
>> saying they are undefined (unsupported?) for now.  I'm merely saying
>> adjust the manual to remove the implication.
>
> Please check the manual from main branch of Org. It has more text:

Shouldn't have inlined the attachment -- here it is as an attachment.

Again, this is a patch to the main branch of Org on Savannah.


[-- Attachment #2: Patch to Org-Guide and Org-Manual --]
[-- Type: text/plain, Size: 6007 bytes --]

diff --git a/doc/org-guide.org b/doc/org-guide.org
index 95828e4c0..167f62e49 100644
--- a/doc/org-guide.org
+++ b/doc/org-guide.org
@@ -1088,12 +1088,12 @@ time information is called a /timestamp/ in Org mode.
 :DESCRIPTION: Assigning a time to a tree entry.
 :END:
 
-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>=.
-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 [[*The Weekly/Daily Agenda]]).  We distinguish:
+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>=.  One or
+more timestamps 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 [[*The Weekly/Daily Agenda]]).  We distinguish:
 
 - Plain timestamp; Event; Appointment ::
 
@@ -1132,15 +1132,25 @@ the agenda (see [[*The Weekly/Daily Agenda]]).  We distinguish:
     <%%(diary-float t 4 2)>
   #+end_example
 
-- Time/Date range ::
+- Date range ::
 
-  Two timestamps connected by =--= denote a range.
+  Two timestamps connected by =--= denote a date range.  NOTE: time is
+  not specified in these timestamps -- just dates,
 
   #+begin_example
   ,** Meeting in Amsterdam
      <2004-08-23 Mon>--<2004-08-26 Thu>
   #+end_example
 
+- Time range ::
+
+  Two times in a timestamp connected by =-= denote a time range.
+
+  #+begin_example
+  ,** Planning meeting
+     <2004-08-23 Mon 9:00-10:00>
+  #+end_example
+
 - Inactive timestamp ::
 
   Just like a plain timestamp, but with square brackets instead of
diff --git a/doc/org-manual.org b/doc/org-manual.org
index c11694849..824a46eaf 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5991,42 +5991,32 @@ is used in a much wider sense.
 :PROPERTIES:
 :DESCRIPTION: Assigning a time to a tree entry.
 :END:
-#+cindex: timestamps
-#+cindex: ranges, time
-#+cindex: date stamps
-#+cindex: deadlines
-#+cindex: scheduling
-
-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:
+
+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>=.  One or
+more timestamps 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 [[*The Weekly/Daily Agenda]]).  We distinguish:
 
 - Plain timestamp; Event; Appointment ::
 
-  #+cindex: timestamp
-  #+cindex: appointment
   A simple timestamp just assigns a date/time to an item.  This is
   just like writing down an appointment or event in a paper agenda.
-  In the agenda display, the headline of an entry associated with
-  a plain timestamp is shown exactly on that date.
 
   #+begin_example
   ,* Meet Peter at the movies
     <2006-11-01 Wed 19:15>
   ,* Discussion on climate change
-    <2006-11-02 Thu>
+    <2006-11-02 Thu 20:00-22:00>
   #+end_example
 
 - Timestamp with repeater interval ::
 
-  #+cindex: timestamp, with repeater interval
   A timestamp may contain a /repeater interval/, indicating that it
   applies not only on the given date, but again and again after
-  a certain interval of N hours (h), days (d), weeks (w), months (m),
-  or years (y).  The following shows up in the agenda every Wednesday:
+  a certain interval of N days (d), weeks (w), months (m), or years
+  (y).  The following shows up in the agenda every Wednesday:
 
   #+begin_example
   ,* Pick up Sam at school
@@ -6037,46 +6027,36 @@ agenda]]).  We distinguish:
 
   #+cindex: diary style timestamps
   #+cindex: sexp timestamps
-  # Mentioned inside the footnote.
-  #+findex: org-date
-  #+findex: org-anniversary
-  #+findex: org-cyclic
-  #+findex: org-block
-
   For more complex date specifications, Org mode supports using the
-  special expression diary entries implemented in the
-  [[info:emacs#Special Diary Entries][Emacs Calendar package]][fn:20].
-  For example, with optional time:
+  special expression diary entries implemented in the Emacs Calendar
+  package.  For example, with optional time:
 
   #+begin_example
   ,* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
     <%%(diary-float t 4 2)>
   #+end_example
 
-- Time/Date range ::
+- Date range ::
 
-  #+cindex: timerange
-  #+cindex: date range
-  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:
+  Two timestamps connected by =--= denote a date range.  NOTE: time is
+  not specified in these timestamps -- just dates,
 
   #+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 =-=
+- Time range ::
+
+  Two times in a timestamp connected by =-= denote a time range.
 
   #+begin_example
-  ,* Discussion on climate change
-     <2006-11-02 Thu 10:00-12:00>
+  ,** Planning meeting
+     <2004-08-23 Mon 9:00-10:00>
   #+end_example
 
 - Inactive timestamp ::
 
-  #+cindex: timestamp, inactive
-  #+cindex: inactive timestamp
   Just like a plain timestamp, but with square brackets instead of
   angular ones.  These timestamps are inactive in the sense that they
   do /not/ trigger an entry to show up in the agenda.

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


-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>>> Maybe I'm not explicit enough.  In section 8.1 of the Org 9.6 manual is
>>> a subsection "Time/Date Range" that *implies* times are supported in
>>> ranges by the use of words "time" and "timestamp" when, above, you're
>>> saying they are undefined (unsupported?) for now.  I'm merely saying
>>> adjust the manual to remove the implication.
>>
>> Please check the manual from main branch of Org. It has more text:
>
> I disagree. I cloned Org from Savannah and made the attached patch
> file from the main branch.  First time for me attaching a file to a
> message.   Does it work for you?

Yes. Though it would be better to attach the diff with proper (.diff or
.patch) extension.

Even better would be providing commit message and formatting the patch
properly. See https://orgmode.org/worg/org-contribute.html#first-patch
Not mandatory though - I can format things properly on your behalf.

> -  Two timestamps connected by =--= denote a range.
> +  Two timestamps connected by =--= denote a date range.  NOTE: time is
> +  not specified in these timestamps -- just dates,

I'd avoid this NOTE. Time is actually allowed, but agenda does nothing
with it. But only agenda. The rest of Org will handle date ranges like
<2023-06-10 Sat 14:00>--<2023-06-12 Mon 18:00> correctly.

> -#+cindex: timestamps
> -#+cindex: ranges, time
> -#+cindex: date stamps
> -#+cindex: deadlines
> -#+cindex: scheduling

Is there any particular reason why you removed index entries here and
further in the diff?

>    A timestamp may contain a /repeater interval/, indicating that it
>    applies not only on the given date, but again and again after
> -  a certain interval of N hours (h), days (d), weeks (w), months (m),
> -  or years (y).  The following shows up in the agenda every Wednesday:
> +  a certain interval of N days (d), weeks (w), months (m), or years
> +  (y).  The following shows up in the agenda every Wednesday:

Why did you remove hours?
  
>    For more complex date specifications, Org mode supports using the
> -  special expression diary entries implemented in the
> -  [[info:emacs#Special Diary Entries][Emacs Calendar package]][fn:20].
> -  For example, with optional time:
> +  special expression diary entries implemented in the Emacs Calendar
> +  package.  For example, with optional time:

Why did you remove the links and the footnote?

-- 
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: Is this proper time format?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>>>> Maybe I'm not explicit enough.  In section 8.1 of the Org 9.6 manual is
>>>> a subsection "Time/Date Range" that *implies* times are supported in
>>>> ranges by the use of words "time" and "timestamp" when, above, you're
>>>> saying they are undefined (unsupported?) for now.  I'm merely saying
>>>> adjust the manual to remove the implication.
>>>
>>> Please check the manual from main branch of Org. It has more text:
>>
>> I disagree. I cloned Org from Savannah and made the attached patch
>> file from the main branch.  First time for me attaching a file to a
>> message.   Does it work for you?
>
> Yes. Though it would be better to attach the diff with proper (.diff or
> .patch) extension.

I hope you saw that I provided a "patch,txt" file in a following message
(forgot about the naming convention -- been a long time...)

> Even better would be providing commit message and formatting the patch
> properly. See https://orgmode.org/worg/org-contribute.html#first-patch
> Not mandatory though - I can format things properly on your behalf.

Thank you.  I haven't "patched" anything on Savannah and assumed I might
have to do the GNU copyright assignment.  For this, I thought it would
be easy for you.

>> -  Two timestamps connected by =--= denote a range.
>> +  Two timestamps connected by =--= denote a date range.  NOTE: time is
>> +  not specified in these timestamps -- just dates,
>
> I'd avoid this NOTE. Time is actually allowed, but agenda does nothing
> with it. But only agenda. The rest of Org will handle date ranges like
> <2023-06-10 Sat 14:00>--<2023-06-12 Mon 18:00> correctly.
>
>> -#+cindex: timestamps
>> -#+cindex: ranges, time
>> -#+cindex: date stamps
>> -#+cindex: deadlines
>> -#+cindex: scheduling
>
> Is there any particular reason why you removed index entries here and
> further in the diff?

No, there isn't.  I think what happened here is that I noticed section
8.1 in org-guide and org-manual were almost (but not quite) the same. I
assumed (incorrectly?) that they were supposed to be the same, but got
out of sync.  So I made my patch to org-guide and then replaced section
8.1 in org-manual with the one from org-guide.  I think these "cindex"
statements got dropped because of that.  If they are important in
org-manual, but not org-guide, then please put them back.

>>    A timestamp may contain a /repeater interval/, indicating that it
>>    applies not only on the given date, but again and again after
>> -  a certain interval of N hours (h), days (d), weeks (w), months (m),
>> -  or years (y).  The following shows up in the agenda every Wednesday:
>> +  a certain interval of N days (d), weeks (w), months (m), or years
>> +  (y).  The following shows up in the agenda every Wednesday:
>
> Why did you remove hours?

Oh!  Another difference between org-guide and org-manual that came over
in trying to resync the two.

>>    For more complex date specifications, Org mode supports using the
>> -  special expression diary entries implemented in the
>> -  [[info:emacs#Special Diary Entries][Emacs Calendar package]][fn:20].
>> -  For example, with optional time:
>> +  special expression diary entries implemented in the Emacs Calendar
>> +  package.  For example, with optional time:
>
> Why did you remove the links and the footnote?

Again, another diff between org-guide and org-manual, :-\

I'm relooking at this patch.  Testing finds that these work in the
timegrid agenda as expected:

* <2023-02-03 Thu 10:00-11:00>--<2023-02-04 Fri 10:00-11:00>
** Can't mark one done -- you have to mark them all done
*** Kind of expected for this form
* <2023-02-03 Thu 10:00-11:00 +1d>
** Can you limit the number of repeats? If so, how?
** Marking it DONE removes current one from agenda
*** reasonable

I have to rethink section 8.1.  With the above in mind, 8.1 is not quite
right, but it's more subtle than I thought.  Not sure how in the weeds
it should get for a user's manual. 

-- 
David Masterson

Re: Is this proper time format?

[David Masterson]

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

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>>>> Maybe I'm not explicit enough.  In section 8.1 of the Org 9.6 manual is
>>>> a subsection "Time/Date Range" that *implies* times are supported in
>>>> ranges by the use of words "time" and "timestamp" when, above, you're
>>>> saying they are undefined (unsupported?) for now.  I'm merely saying
>>>> adjust the manual to remove the implication.
>>>
>>> Please check the manual from main branch of Org. It has more text:
>>
>> I disagree. I cloned Org from Savannah and made the attached patch
>> file from the main branch.  First time for me attaching a file to a
>> message.   Does it work for you?
>
> Yes. Though it would be better to attach the diff with proper (.diff or
> .patch) extension.

I've updated my patch file taking into account what you mentioned and
what I tested.  Does this look all right?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Patch of Org-Guide and Org-Manual --]
[-- Type: text/x-diff, Size: 8461 bytes --]

diff --git a/doc/org-guide.org b/doc/org-guide.org
index 95828e4c0..12a1f0126 100644
--- a/doc/org-guide.org
+++ b/doc/org-guide.org
@@ -1079,40 +1079,51 @@ Tags and Properties]].
 :DESCRIPTION: Making items useful for planning.
 :END:
 
-To assist project planning, TODO items can be labeled with a date
-and/or a time.  The specially formatted string carrying the date and
-time information is called a /timestamp/ in Org mode.
+To assist project planning, TODO items can be labeled with dates
+and/or times for purposes described in this chapter.  The specially
+formatted string carrying the date and time information is called a
+/timestamp/ in Org mode.
 
 ** Timestamps
 :PROPERTIES:
 :DESCRIPTION: Assigning a time to a tree entry.
 :END:
+#+cindex: timestamps
+#+cindex: ranges, time
+#+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>=.
-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 [[*The Weekly/Daily Agenda]]).  We distinguish:
+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>=.  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/times in the agenda (see [[*The Weekly/Daily Agenda]]).  We
+distinguish:
 
 - Plain timestamp; Event; Appointment ::
 
   A simple timestamp just assigns a date/time to an item.  This is
-  just like writing down an appointment or event in a paper agenda.
+  just like writing down an appointment or event in a paper
+  agenda. There can be multiple timestamps in an event.
 
   #+begin_example
   ,* 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 10:00-12:00>
+  ,* My days off
+    <2006-11-03 Fri>
+    <2006-11-06 Mon>
   #+end_example
 
 - Timestamp with repeater interval ::
 
   A timestamp may contain a /repeater interval/, indicating that it
-  applies not only on the given date, but again and again after
-  a certain interval of N days (d), weeks (w), months (m), or years
-  (y).  The following shows up in the agenda every Wednesday:
+  applies not only on the given date, but again and again after a
+  certain interval of N hours (h), days (d), weeks (w), months (m), or
+  years (y).  The following shows up in the agenda every week at the
+  given day of the week and time:
 
   #+begin_example
   ,* Pick up Sam at school
@@ -1123,6 +1134,7 @@ the agenda (see [[*The Weekly/Daily Agenda]]).  We distinguish:
 
   #+cindex: diary style timestamps
   #+cindex: sexp timestamps
+
   For more complex date specifications, Org mode supports using the
   special expression diary entries implemented in the Emacs Calendar
   package.  For example, with optional time:
@@ -1132,13 +1144,24 @@ the agenda (see [[*The Weekly/Daily Agenda]]).  We distinguish:
     <%%(diary-float t 4 2)>
   #+end_example
 
+- Time range ::
+
+  Time range 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
+
 - Time/Date range ::
 
-  Two timestamps connected by =--= denote a range.
+  Two timestamps connected by =--= denote a range.  The first example specifies just the dates of the range while the second specifies particular times during the dates.
 
   #+begin_example
   ,** Meeting in Amsterdam
      <2004-08-23 Mon>--<2004-08-26 Thu>
+  ,** This weeks committee meetings
+     <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00>
   #+end_example
 
 - Inactive timestamp ::
diff --git a/doc/org-manual.org b/doc/org-manual.org
index c11694849..d56563955 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5978,14 +5978,14 @@ or a dynamic block.
 #+cindex: dates
 #+cindex: times
 #+cindex: timestamp
-#+cindex: date stamp
 
-To assist project planning, TODO items can be labeled with a date
-and/or a time.  The specially formatted string carrying the date and
-time information is called a /timestamp/ in Org mode.  This may be
-a little confusing because timestamp is often used as indicating when
-something was created or last changed.  However, in Org mode this term
-is used in a much wider sense.
+To assist project planning, TODO items can be labeled with dates
+and/or times for purposes described in this chapter.  The specially
+formatted string carrying the date and time information is called a
+/timestamp/ in Org mode.  This may be a little confusing because
+timestamp is often used as indicating when something was created or
+last changed.  However, in Org mode this term is used in a much wider
+sense.
 
 ** Timestamps
 :PROPERTIES:
@@ -5993,16 +5993,15 @@ is used in a much wider sense.
 :END:
 #+cindex: timestamps
 #+cindex: ranges, time
-#+cindex: date stamps
 #+cindex: deadlines
 #+cindex: scheduling
 
 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:
+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/times in the agenda (see
+[[*Weekly/daily agenda]]).  We distinguish:
 
 - Plain timestamp; Event; Appointment ::
 
@@ -6010,14 +6009,18 @@ agenda]]).  We distinguish:
   #+cindex: appointment
   A simple timestamp just assigns a date/time to an item.  This is
   just like writing down an appointment or event in a paper agenda.
-  In the agenda display, the headline of an entry associated with
-  a plain timestamp is shown exactly on that date.
+  In the agenda display, the headline of an entry associated with a
+  plain timestamp is shown exactly on that date/time.  There can be
+  multiple timestamps in an event.
 
   #+begin_example
   ,* Meet Peter at the movies
     <2006-11-01 Wed 19:15>
   ,* Discussion on climate change
-    <2006-11-02 Thu>
+    <2006-11-02 Thu 10:00-12:00>
+  ,* My days off
+    <2006-11-03 Fri>
+    <2006-11-06 Mon>
   #+end_example
 
 - Timestamp with repeater interval ::
@@ -6026,7 +6029,7 @@ agenda]]).  We distinguish:
   A timestamp may contain a /repeater interval/, indicating that it
   applies not only on the given date, but again and again after
   a certain interval of N hours (h), days (d), weeks (w), months (m),
-  or years (y).  The following shows up in the agenda every Wednesday:
+  or years (y).  The following shows up in the agenda every week at the given day of the week and time:
 
   #+begin_example
   ,* Pick up Sam at school
@@ -6053,24 +6056,27 @@ agenda]]).  We distinguish:
     <%%(diary-float t 4 2)>
   #+end_example
 
-- Time/Date range ::
+- Time range ::
 
-  #+cindex: timerange
-  #+cindex: date range
-  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:
+  #+cindex: time range
+
+  Time range is a timestamp consisting of two time units connected by =-=
 
   #+begin_example
-  ,** Meeting in Amsterdam
-     <2004-08-23 Mon>--<2004-08-26 Thu>
+  ,* Discussion on climate change
+     <2006-11-02 Thu 10:00-12:00>
   #+end_example
 
-  Timerange is a timestamp consisting of two time units connected by =-=
+- Time/Date range ::
+
+  #+cindex: time range
+  #+cindex: date range
+
+  Two timestamps connected by =--= denote a range.  The first example specifies just the dates of the range while the second specifies particular times during the dates.
 
   #+begin_example
-  ,* Discussion on climate change
-     <2006-11-02 Thu 10:00-12:00>
+  ,** Meeting in Amsterdam
+     <2004-08-23 Mon>--<2004-08-26 Thu>
   #+end_example
 
 - Inactive timestamp ::

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



-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>> Yes. Though it would be better to attach the diff with proper (.diff or
>> .patch) extension.
>
> I hope you saw that I provided a "patch,txt" file in a following message
> (forgot about the naming convention -- been a long time...)

Inline and attachment are both fine.

>> Even better would be providing commit message and formatting the patch
>> properly. See https://orgmode.org/worg/org-contribute.html#first-patch
>> Not mandatory though - I can format things properly on your behalf.
>
> Thank you.  I haven't "patched" anything on Savannah and assumed I might
> have to do the GNU copyright assignment.  For this, I thought it would
> be easy for you.

Yes and no. One of the things you get to do when creating a proper patch
is commit message describing the changes in detail. This helps to review
your own changes and often helps with silly typos.

So, it is generally not hard for me to write the commit message on your
behalf, but if you do it yourself, it generally makes life easier for me
when reviewing changes.

As for copyright assignment, it does not matter if you provide a diff or
patch - the work is yours and it is a subject of copyright rules we use.
<=15LOC of non-trivial changes does not require copyright assignment.

>>> -#+cindex: timestamps
>>> -#+cindex: ranges, time
>>> -#+cindex: date stamps
>>> -#+cindex: deadlines
>>> -#+cindex: scheduling
>>
>> Is there any particular reason why you removed index entries here and
>> further in the diff?
>
> No, there isn't.  I think what happened here is that I noticed section
> 8.1 in org-guide and org-manual were almost (but not quite) the same. I
> assumed (incorrectly?) that they were supposed to be the same, but got
> out of sync.  So I made my patch to org-guide and then replaced section
> 8.1 in org-manual with the one from org-guide.  I think these "cindex"
> statements got dropped because of that.  If they are important in
> org-manual, but not org-guide, then please put them back.

Well. They are kind of out of sync. But the org-guide is not supposed to
be exact copy of the manual - the guide only contains the most important
parts. That's why footnotes are dropped.

For cindex entries, they are not needed in the guide. #+cindex and
similar keywords are just anchors to build concept/variable/command
index in the manual. We do not have such index in the guide.

>> Why did you remove hours?
>
> Oh!  Another difference between org-guide and org-manual that came over
> in trying to resync the two.

This is a valid out-of-sync entry. I updated the guide now.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=e9d6a5479

> I'm relooking at this patch.  Testing finds that these work in the
> timegrid agenda as expected:
>
> * <2023-02-03 Thu 10:00-11:00>--<2023-02-04 Fri 10:00-11:00>
> ** Can't mark one done -- you have to mark them all done
> *** Kind of expected for this form
> * <2023-02-03 Thu 10:00-11:00 +1d>
> ** Can you limit the number of repeats? If so, how?

Only using diary sexp. Limiting the repeater intervals is one of the
feature requests we have.

-- 
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: Is this proper time format?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

> I've updated my patch file taking into account what you mentioned and
> what I tested.  Does this look all right?

Thanks! See inline comments below.

> -To assist project planning, TODO items can be labeled with a date
> -and/or a time.  The specially formatted string carrying the date and
> -time information is called a /timestamp/ in Org mode.
> +To assist project planning, TODO items can be labeled with dates
> +and/or times for purposes described in this chapter.  The specially
> +formatted string carrying the date and time information is called a
> +/timestamp/ in Org mode.

What is the purpose of this change? The updated sentence is rather
confusing, IMHO.
  
>  ** Timestamps
>  :PROPERTIES:
>  :DESCRIPTION: Assigning a time to a tree entry.
>  :END:
> +#+cindex: timestamps
> +#+cindex: ranges, time
> +#+cindex: deadlines
> +#+cindex: scheduling

We do not need cindex and other index keywords in org-guide.

> -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>=.
> -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 [[*The Weekly/Daily Agenda]]).  We distinguish:
> +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>=.  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/times in the agenda (see [[*The Weekly/Daily Agenda]]).  We
> +distinguish:

This is not accurate. Only date is considered by agenda. Not time.
Time can be displayed, but has no effect (by default) on whether an
entry appears in the agenda or not.

> -    <2006-11-02 Thu 20:00-22:00>
> +    <2006-11-02 Thu 10:00-12:00>

I do not mind, but wondering why you changed the time interval.

>  - Timestamp with repeater interval ::
>  
>    A timestamp may contain a /repeater interval/, indicating that it
> -  applies not only on the given date, but again and again after
> -  a certain interval of N days (d), weeks (w), months (m), or years
> -  (y).  The following shows up in the agenda every Wednesday:
> +  applies not only on the given date, but again and again after a
> +  certain interval of N hours (h), days (d), weeks (w), months (m), or
> +  years (y).  The following shows up in the agenda every week at the
> +  given day of the week and time:

I miss the point here. You changed the last sentence to mention time,
but the "following" example does not specify the time (<%%(diary-float t 4 2)>).

-- 
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: Is this proper time format?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>> -To assist project planning, TODO items can be labeled with a date
>> -and/or a time.  The specially formatted string carrying the date and
>> -time information is called a /timestamp/ in Org mode.
>> +To assist project planning, TODO items can be labeled with dates
>> +and/or times for purposes described in this chapter.  The specially
>> +formatted string carrying the date and time information is called a
>> +/timestamp/ in Org mode.
>
> What is the purpose of this change? The updated sentence is rather
> confusing, IMHO.

Mostly changing the statement from singular to plural to imply that more
than one timestamp can be in a TODO item (SCHEDULED, DEADLINE, multiple
plain timestamps) w/o directly mentioning how (leave that for later
examples in the chapter).

>>  ** Timestamps
>>  :PROPERTIES:
>>  :DESCRIPTION: Assigning a time to a tree entry.
>>  :END:
>> +#+cindex: timestamps
>> +#+cindex: ranges, time
>> +#+cindex: deadlines
>> +#+cindex: scheduling
>
> We do not need cindex and other index keywords in org-guide.

There are a couple in the diary timestamp section already, but this can
be dropped if wrong.

>> -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>=.
>> -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 [[*The Weekly/Daily Agenda]]).  We distinguish:
>> +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>=.  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/times in the agenda (see [[*The Weekly/Daily Agenda]]).  We
>> +distinguish:
>
> This is not accurate. Only date is considered by agenda. Not time.
> Time can be displayed, but has no effect (by default) on whether an
> entry appears in the agenda or not.

In testing, I found the following:

* TODO summer school
  <2023-06-05 Mon 10:30-12:15>--<2023-06-08 Thu 10:30-12:15>

This shows in my timegrid agenda for the week for Mon, Tue, Wed, & Thu
on the specified time range.  Interestingly, each agenda item had a
"(n/4)" on it (n=1 to 4).  Also, if you mark any of the 4 as DONE, then
all change to DONE (which you kind of expect for this style).

Is this being done by an add-on package?  I have these, but most of them
are not setup:

org-ac-20170401.1307 org-books-20210408.1913 org-brain-20230217.1908
org-contacts-1.1 org-download-20220906.1929 org-edna-1.1.2
org-emms-20230515.1838 org-noter-20230605.323
org-noter-pdftools-20220320.300 org-pdftools-20220320.301
org-ql-20230525.1548 org-super-agenda-20220826.2315
org-vcard-20221111.328

>> -    <2006-11-02 Thu 20:00-22:00>
>> +    <2006-11-02 Thu 10:00-12:00>
>
> I do not mind, but wondering why you changed the time interval.

It seemed strange to have a meeting so late at night.  ;-)

>>  - Timestamp with repeater interval ::
>>  
>>    A timestamp may contain a /repeater interval/, indicating that it
>> -  applies not only on the given date, but again and again after
>> -  a certain interval of N days (d), weeks (w), months (m), or years
>> -  (y).  The following shows up in the agenda every Wednesday:
>> +  applies not only on the given date, but again and again after a
>> +  certain interval of N hours (h), days (d), weeks (w), months (m), or
>> +  years (y).  The following shows up in the agenda every week at the
>> +  given day of the week and time:
>
> I miss the point here. You changed the last sentence to mention time,
> but the "following" example does not specify the time (<%%(diary-float t 4 2)>).

I think you're looking at the patch file, so you're not seeing the line
before the 'diary' line which has a time of 22:00-23:00 on it.  I don't
use 'diary-float', so did I misinterpret the example?  If so, drop the
"and time".  The main purpose was to add in "hours" after N.

-- 
David Masterson

Re: Is this proper time format?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>> Thank you.  I haven't "patched" anything on Savannah and assumed I might
>> have to do the GNU copyright assignment.  For this, I thought it would
>> be easy for you.
>
> Yes and no. One of the things you get to do when creating a proper patch
> is commit message describing the changes in detail. This helps to review
> your own changes and often helps with silly typos.

Is there a form/example for a proper commit message?

-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>>> Thank you.  I haven't "patched" anything on Savannah and assumed I might
>>> have to do the GNU copyright assignment.  For this, I thought it would
>>> be easy for you.
>>
>> Yes and no. One of the things you get to do when creating a proper patch
>> is commit message describing the changes in detail. This helps to review
>> your own changes and often helps with silly typos.
>
> Is there a form/example for a proper commit message?

https://orgmode.org/worg/org-contribute.html#commit-messages
Also, https://git.savannah.gnu.org/cgit/emacs/org-mode.git/log/

-- 
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: Is this proper time format?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>>> -To assist project planning, TODO items can be labeled with a date
>>> -and/or a time.  The specially formatted string carrying the date and
>>> -time information is called a /timestamp/ in Org mode.
>>> +To assist project planning, TODO items can be labeled with dates
>>> +and/or times for purposes described in this chapter.  The specially
>>> +formatted string carrying the date and time information is called a
>>> +/timestamp/ in Org mode.
>>
>> What is the purpose of this change? The updated sentence is rather
>> confusing, IMHO.
>
> Mostly changing the statement from singular to plural to imply that more
> than one timestamp can be in a TODO item (SCHEDULED, DEADLINE, multiple
> plain timestamps) w/o directly mentioning how (leave that for later
> examples in the chapter).

I am mostly questioning "for purposes described in this chapter".
All the TODO items can be labelled with multiple dates/times, not just in
"this chapter".

>>> +#+cindex: timestamps
>>> +#+cindex: ranges, time
>>> +#+cindex: deadlines
>>> +#+cindex: scheduling
>>
>> We do not need cindex and other index keywords in org-guide.
>
> There are a couple in the diary timestamp section already, but this can
> be dropped if wrong.

Most likely, they are there by mistake.
The guide should be short enough to not require index.

>>> +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>=.  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/times in the agenda (see [[*The Weekly/Daily Agenda]]).  We
>>> +distinguish:
>>
>> This is not accurate. Only date is considered by agenda. Not time.
>> Time can be displayed, but has no effect (by default) on whether an
>> entry appears in the agenda or not.
>
> In testing, I found the following:
>
> * TODO summer school
>   <2023-06-05 Mon 10:30-12:15>--<2023-06-08 Thu 10:30-12:15>
>
> ...
> Is this being done by an add-on package?  I have these, but most of them
> are not setup:

No. I meant that presence of time has no effect on whether an entry
appear in agenda or not. Once agenda decides that an entry should
appear, the time is taken into account when formatting the display.

You modified the manual to "Its presence causes entries to be shown on
specific dates/times in the agenda". There is no concept of "shown on
specific time" in agenda views. Just "shown on specific day".

>>> -    <2006-11-02 Thu 20:00-22:00>
>>> +    <2006-11-02 Thu 10:00-12:00>
>>
>> I do not mind, but wondering why you changed the time interval.
>
> It seemed strange to have a meeting so late at night.  ;-)

I guess you do not work in academia :)

>>>  - Timestamp with repeater interval ::
>>>  
>>>    A timestamp may contain a /repeater interval/, indicating that it
>>> -  applies not only on the given date, but again and again after
>>> -  a certain interval of N days (d), weeks (w), months (m), or years
>>> -  (y).  The following shows up in the agenda every Wednesday:
>>> +  applies not only on the given date, but again and again after a
>>> +  certain interval of N hours (h), days (d), weeks (w), months (m), or
>>> +  years (y).  The following shows up in the agenda every week at the
>>> +  given day of the week and time:
>>
>> I miss the point here. You changed the last sentence to mention time,
>> but the "following" example does not specify the time (<%%(diary-float t 4 2)>).
>
> I think you're looking at the patch file, so you're not seeing the line
> before the 'diary' line which has a time of 22:00-23:00 on it.  I don't
> use 'diary-float', so did I misinterpret the example?  If so, drop the
> "and time".  The main purpose was to add in "hours" after N.

"22:00-23:00" has no relation to timestamps.
Agenda still accounts for it because of
`org-agenda-search-headline-for-time', but this part of the manual is
talking about timestamps, not agenda extras. The diary timestamp does
not set the time.

-- 
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: Is this proper time format?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>>>> -To assist project planning, TODO items can be labeled with a date
>>>> -and/or a time.  The specially formatted string carrying the date and
>>>> -time information is called a /timestamp/ in Org mode.
>>>> +To assist project planning, TODO items can be labeled with dates
>>>> +and/or times for purposes described in this chapter.  The specially
>>>> +formatted string carrying the date and time information is called a
>>>> +/timestamp/ in Org mode.
>>>
>>> What is the purpose of this change? The updated sentence is rather
>>> confusing, IMHO.
>>
>> Mostly changing the statement from singular to plural to imply that more
>> than one timestamp can be in a TODO item (SCHEDULED, DEADLINE, multiple
>> plain timestamps) w/o directly mentioning how (leave that for later
>> examples in the chapter).
>
> I am mostly questioning "for purposes described in this chapter".
> All the TODO items can be labelled with multiple dates/times, not just in
> "this chapter".

I see.  I'm trying to say that the rest of this chapter describes how,
where and why you would use dates/times in an Org file.  For example,
the Timestamps subchapter describes what a timestamp looks like and that
it can be used in any header or paragraph in an Org file and how the
timestamp affects the agenda.

>>>> +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>=.  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/times in the agenda (see [[*The Weekly/Daily Agenda]]).  We
>>>> +distinguish:
>>>
>>> This is not accurate. Only date is considered by agenda. Not time.
>>> Time can be displayed, but has no effect (by default) on whether an
>>> entry appears in the agenda or not.
>>
>> In testing, I found the following:
>>
>> * TODO summer school
>>   <2023-06-05 Mon 10:30-12:15>--<2023-06-08 Thu 10:30-12:15>
>>
>> ...
>> Is this being done by an add-on package?  I have these, but most of them
>> are not setup:
>
> No. I meant that presence of time has no effect on whether an entry
> appear in agenda or not. Once agenda decides that an entry should
> appear, the time is taken into account when formatting the display.
>
> You modified the manual to "Its presence causes entries to be shown on
> specific dates/times in the agenda". There is no concept of "shown on
> specific time" in agenda views. Just "shown on specific day".

I think I see what you're saying.  I'm fine with dropping "/times".

>>>>  - Timestamp with repeater interval ::
>>>>  
>>>>    A timestamp may contain a /repeater interval/, indicating that it
>>>> -  applies not only on the given date, but again and again after
>>>> -  a certain interval of N days (d), weeks (w), months (m), or years
>>>> -  (y).  The following shows up in the agenda every Wednesday:
>>>> +  applies not only on the given date, but again and again after a
>>>> +  certain interval of N hours (h), days (d), weeks (w), months (m), or
>>>> +  years (y).  The following shows up in the agenda every week at the
>>>> +  given day of the week and time:
>>>
>>> I miss the point here. You changed the last sentence to mention time,
>>> but the "following" example does not specify the time (<%%(diary-float t 4 2)>).
>>
>> I think you're looking at the patch file, so you're not seeing the line
>> before the 'diary' line which has a time of 22:00-23:00 on it.  I don't
>> use 'diary-float', so did I misinterpret the example?  If so, drop the
>> "and time".  The main purpose was to add in "hours" after N.
>
> "22:00-23:00" has no relation to timestamps.
> Agenda still accounts for it because of
> `org-agenda-search-headline-for-time', but this part of the manual is
> talking about timestamps, not agenda extras. The diary timestamp does
> not set the time.

Ah, then just drop the "and time" change.

-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>> I am mostly questioning "for purposes described in this chapter".
>> All the TODO items can be labelled with multiple dates/times, not just in
>> "this chapter".
>
> I see.  I'm trying to say that the rest of this chapter describes how,
> where and why you would use dates/times in an Org file.  For example,
> the Timestamps subchapter describes what a timestamp looks like and that
> it can be used in any header or paragraph in an Org file and how the
> timestamp affects the agenda.

Maybe add a short second paragraph summarizing about timestamps,
scheduled, deadlines, and clocking? That's what people commonly do in
literature.

> I think I see what you're saying.  I'm fine with dropping "/times".
> ...
> Ah, then just drop the "and time" change.

Would you mind updating the patch?

If you do not use magit, you can easily re-create patches for a given
file from Emacs using
M-x vc-diff <RET> M-x write-file <RET> /path/to/your.path <RET>

-- 
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: Is this proper time format?

[David Masterson]

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

Ihor Radchenko <yantar92@posteo.net> writes:

> Would you mind updating the patch?

See below.

> If you do not use magit, you can easily re-create patches for a given
> file from Emacs using
> M-x vc-diff <RET> M-x write-file <RET> /path/to/your.path <RET>

I do use magit, but I'm not good with it.  In particular, I wanted to
walk thru my changes with EDiff, but, when ediff brought up the buffers,
the buffers were in org-mode and everything was folded and I didn't see
how to tell ediff to not fold so I could see the diffs.

Change log:
================
Doc change to explain timestamps better

doc/org-guide.org (Dates and Times): purpose of timestamp + examples
doc/org-manual.org (Dates and Times): purpose of timestamp + examples
================


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Change for org-guide and org-manual --]
[-- Type: text/x-diff, Size: 6741 bytes --]

diff --git a/doc/org-guide.org b/doc/org-guide.org
index 95828e4c0..3a19027ba 100644
--- a/doc/org-guide.org
+++ b/doc/org-guide.org
@@ -1080,7 +1080,9 @@ Tags and Properties]].
 :END:
 
 To assist project planning, TODO items can be labeled with a date
-and/or a time.  The specially formatted string carrying the date and
+and/or a time for purposes like a timestamp on an event, a deadline
+for a task, or clocking time on a task as described in later sections
+of this chapter.  The specially formatted string carrying the date and
 time information is called a /timestamp/ in Org mode.
 
 ** Timestamps
@@ -1099,20 +1101,24 @@ the agenda (see [[*The Weekly/Daily Agenda]]).  We distinguish:
 
   A simple timestamp just assigns a date/time to an item.  This is
   just like writing down an appointment or event in a paper agenda.
+  There can be multiple timestamps in an event.
 
   #+begin_example
   ,* Meet Peter at the movies
     <2006-11-01 Wed 19:15>
   ,* Discussion on climate change
     <2006-11-02 Thu 20:00-22:00>
+  ,* My days off
+    <2006-11-03 Fri>
+    <2006-11-06 Mon>
   #+end_example
 
 - Timestamp with repeater interval ::
 
   A timestamp may contain a /repeater interval/, indicating that it
-  applies not only on the given date, but again and again after
-  a certain interval of N days (d), weeks (w), months (m), or years
-  (y).  The following shows up in the agenda every Wednesday:
+  applies not only on the given date, but again and again after a
+  certain interval of N hours (h), days (d), weeks (w), months (m), or
+  years (y).  The following shows up in the agenda every Wednesday:
 
   #+begin_example
   ,* Pick up Sam at school
@@ -1121,8 +1127,6 @@ the agenda (see [[*The Weekly/Daily Agenda]]).  We distinguish:
 
 - Diary-style expression entries ::
 
-  #+cindex: diary style timestamps
-  #+cindex: sexp timestamps
   For more complex date specifications, Org mode supports using the
   special expression diary entries implemented in the Emacs Calendar
   package.  For example, with optional time:
@@ -1132,13 +1136,28 @@ the agenda (see [[*The Weekly/Daily Agenda]]).  We distinguish:
     <%%(diary-float t 4 2)>
   #+end_example
 
+- Time range
+
+  Time range is a timestamp having two time units connected by =-=
+
+  #+begin_example
+  ,* Discussion on climate change
+    <2006-11-02 Thu 10:00-12:00>
+  #+end_example
+
 - Time/Date range ::
 
-  Two timestamps connected by =--= denote a range.
+  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.  The first example
+  specifies just the dates of the range while the second example
+  specifies a time range for each date.
 
   #+begin_example
   ,** Meeting in Amsterdam
      <2004-08-23 Mon>--<2004-08-26 Thu>
+  ,** This weeks committee meetings
+     <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00>
   #+end_example
 
 - Inactive timestamp ::
diff --git a/doc/org-manual.org b/doc/org-manual.org
index c11694849..3ec9bc10b 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5978,10 +5978,11 @@ or a dynamic block.
 #+cindex: dates
 #+cindex: times
 #+cindex: timestamp
-#+cindex: date stamp
 
 To assist project planning, TODO items can be labeled with a date
-and/or a time.  The specially formatted string carrying the date and
+and/or a time for purposes like a timestamp on an event, a deadline
+for a task, or clocking time on a task as described in later sections
+of this chapter.  The specially formatted string carrying the date and
 time information is called a /timestamp/ in Org mode.  This may be
 a little confusing because timestamp is often used as indicating when
 something was created or last changed.  However, in Org mode this term
@@ -5993,16 +5994,15 @@ is used in a much wider sense.
 :END:
 #+cindex: timestamps
 #+cindex: ranges, time
-#+cindex: date stamps
 #+cindex: deadlines
 #+cindex: scheduling
 
-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:
+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 [[*The Weekly/Daily Agenda]]).  We distinguish:
 
 - Plain timestamp; Event; Appointment ::
 
@@ -6011,13 +6011,16 @@ agenda]]).  We distinguish:
   A simple timestamp just assigns a date/time to an item.  This is
   just like writing down an appointment or event in a paper agenda.
   In the agenda display, the headline of an entry associated with
-  a plain timestamp is shown exactly on that date.
+  a plain timestamp is shown exactly on that date.  There can be multiple timestamps in an event.
 
   #+begin_example
   ,* Meet Peter at the movies
     <2006-11-01 Wed 19:15>
   ,* Discussion on climate change
-    <2006-11-02 Thu>
+    <2006-11-02 Thu 10:00-12:00>
+  ,* My days off
+    <2006-11-03 Fri>
+    <2006-11-06 Mon>
   #+end_example
 
 - Timestamp with repeater interval ::
@@ -6053,24 +6056,31 @@ agenda]]).  We distinguish:
     <%%(diary-float t 4 2)>
   #+end_example
 
+-  Time range ::
+#+cindex time range
+
+Time range is a timestamp having two time units connected by =-=
+
+#+begin_example
+,* Discussion on climate change
+   <2006-11-02 Thu 10:00-12:00>
+#+end_example
+
 - Time/Date range ::
 
-  #+cindex: timerange
+  #+cindex: time range
   #+cindex: date range
   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:
+  dates that are displayed and fall in the range.  The first example
+  specifies just the dates of the range while the second example
+  specifies a time range for each date.
 
   #+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>
+  ,** This weeks committee meetings
+     <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00>
   #+end_example
 
 - Inactive timestamp ::

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



-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

> Ihor Radchenko <yantar92@posteo.net> writes:
>
>> Would you mind updating the patch?
>
> See below.

Thanks!

>> If you do not use magit, you can easily re-create patches for a given
>> file from Emacs using
>> M-x vc-diff <RET> M-x write-file <RET> /path/to/your.path <RET>
>
> I do use magit, but I'm not good with it.  In particular, I wanted to
> walk thru my changes with EDiff, but, when ediff brought up the buffers,
> the buffers were in org-mode and everything was folded and I didn't see
> how to tell ediff to not fold so I could see the diffs.

Usually, the diff provided in M-x magit-status is good enough.
You could also use M-x org-show-all to unfold everything.

>  To assist project planning, TODO items can be labeled with a date
> -and/or a time.  The specially formatted string carrying the date and
> +and/or a time for purposes like a timestamp on an event, a deadline
> +for a task, or clocking time on a task as described in later sections
> +of this chapter.  The specially formatted string carrying the date and
>  time information is called a /timestamp/ in Org mode.

IMHO, this is just creating confusion.
Remember that this manual/guide is going to be read by people who are
not yet familiar with Org mode terminology. What is "timestamp on an
event"? What if you put a timestamp on a non-event? What is "clocking
time"?

>  
>    A simple timestamp just assigns a date/time to an item.  This is
>    just like writing down an appointment or event in a paper agenda.
> +  There can be multiple timestamps in an event.

Why event? What about tasks? Can just use more general "heading" or "entry".

-- 
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: Is this proper time format?

[David Masterson]

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

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>>  To assist project planning, TODO items can be labeled with a date
>> -and/or a time.  The specially formatted string carrying the date and
>> +and/or a time for purposes like a timestamp on an event, a deadline
>> +for a task, or clocking time on a task as described in later sections
>> +of this chapter.  The specially formatted string carrying the date and
>>  time information is called a /timestamp/ in Org mode.
>
> IMHO, this is just creating confusion.
> Remember that this manual/guide is going to be read by people who are
> not yet familiar with Org mode terminology. What is "timestamp on an
> event"? What if you put a timestamp on a non-event? What is "clocking
> time"?

Ok.  I did use "like". ;-)

I don't want to get too in the weeds (because I don't know it all), so
how about:

... purposes like when an event happens, a deadline for a task, or
tracking time spent on a task ...

>>    A simple timestamp just assigns a date/time to an item.  This is
>>    just like writing down an appointment or event in a paper agenda.
>> +  There can be multiple timestamps in an event.
>
> Why event? What about tasks? Can just use more general "heading" or "entry".

Good point.  The paragraph already used 'item' -- would that be better?

New patch file attached:

Change log:
================
Doc change to explain timestamps better

doc/org-guide.org (Dates and Times): purpose of timestamp + examples
doc/org-manual.org (Dates and Times): purpose of timestamp + examples
================

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Change for org-guide and org-manual --]
[-- Type: text/x-diff, Size: 7049 bytes --]

diff --git a/doc/org-guide.org b/doc/org-guide.org
index 95828e4c0..e033ac0d9 100644
--- a/doc/org-guide.org
+++ b/doc/org-guide.org
@@ -1080,7 +1080,9 @@ Tags and Properties]].
 :END:
 
 To assist project planning, TODO items can be labeled with a date
-and/or a time.  The specially formatted string carrying the date and
+and/or a time purposes like when an event happens, a deadline for a
+task, or tracking time spent on a task as described in later sections
+of this chapter.  The specially formatted string carrying the date and
 time information is called a /timestamp/ in Org mode.
 
 ** Timestamps
@@ -1099,20 +1101,24 @@ the agenda (see [[*The Weekly/Daily Agenda]]).  We distinguish:
 
   A simple timestamp just assigns a date/time to an item.  This is
   just like writing down an appointment or event in a paper agenda.
+  There can be multiple timestamps in an item.
 
   #+begin_example
   ,* Meet Peter at the movies
     <2006-11-01 Wed 19:15>
   ,* Discussion on climate change
     <2006-11-02 Thu 20:00-22:00>
+  ,* My days off
+    <2006-11-03 Fri>
+    <2006-11-06 Mon>
   #+end_example
 
 - Timestamp with repeater interval ::
 
   A timestamp may contain a /repeater interval/, indicating that it
-  applies not only on the given date, but again and again after
-  a certain interval of N days (d), weeks (w), months (m), or years
-  (y).  The following shows up in the agenda every Wednesday:
+  applies not only on the given date, but again and again after a
+  certain interval of N hours (h), days (d), weeks (w), months (m), or
+  years (y).  The following shows up in the agenda every Wednesday:
 
   #+begin_example
   ,* Pick up Sam at school
@@ -1121,8 +1127,6 @@ the agenda (see [[*The Weekly/Daily Agenda]]).  We distinguish:
 
 - Diary-style expression entries ::
 
-  #+cindex: diary style timestamps
-  #+cindex: sexp timestamps
   For more complex date specifications, Org mode supports using the
   special expression diary entries implemented in the Emacs Calendar
   package.  For example, with optional time:
@@ -1132,13 +1136,28 @@ the agenda (see [[*The Weekly/Daily Agenda]]).  We distinguish:
     <%%(diary-float t 4 2)>
   #+end_example
 
+- Time range
+
+  Time range is a timestamp having two time units connected by =-=
+
+  #+begin_example
+  ,* Discussion on climate change
+    <2006-11-02 Thu 10:00-12:00>
+  #+end_example
+
 - Time/Date range ::
 
-  Two timestamps connected by =--= denote a range.
+  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.  The first example
+  specifies just the dates of the range while the second example
+  specifies a time range for each date.
 
   #+begin_example
   ,** Meeting in Amsterdam
      <2004-08-23 Mon>--<2004-08-26 Thu>
+  ,** This weeks committee meetings
+     <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00>
   #+end_example
 
 - Inactive timestamp ::
diff --git a/doc/org-manual.org b/doc/org-manual.org
index c11694849..71f52fac6 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5978,14 +5978,15 @@ or a dynamic block.
 #+cindex: dates
 #+cindex: times
 #+cindex: timestamp
-#+cindex: date stamp
 
 To assist project planning, TODO items can be labeled with a date
-and/or a time.  The specially formatted string carrying the date and
-time information is called a /timestamp/ in Org mode.  This may be
-a little confusing because timestamp is often used as indicating when
-something was created or last changed.  However, in Org mode this term
-is used in a much wider sense.
+and/or a time for purposes like when an event happens, a deadline for
+a task, or tracking time spent on a task as described in later
+sections of this chapter.  The specially formatted string carrying the
+date and time information is called a /timestamp/ in Org mode.  This
+may be a little confusing because timestamp is often used as
+indicating when something was created or last changed.  However, in
+Org mode this term is used in a much wider sense.
 
 ** Timestamps
 :PROPERTIES:
@@ -5993,16 +5994,15 @@ is used in a much wider sense.
 :END:
 #+cindex: timestamps
 #+cindex: ranges, time
-#+cindex: date stamps
 #+cindex: deadlines
 #+cindex: scheduling
 
-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:
+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 [[*The Weekly/Daily Agenda]]).  We distinguish:
 
 - Plain timestamp; Event; Appointment ::
 
@@ -6011,13 +6011,16 @@ agenda]]).  We distinguish:
   A simple timestamp just assigns a date/time to an item.  This is
   just like writing down an appointment or event in a paper agenda.
   In the agenda display, the headline of an entry associated with
-  a plain timestamp is shown exactly on that date.
+  a plain timestamp is shown exactly on that date.  There can be multiple timestamps in an item.
 
   #+begin_example
   ,* Meet Peter at the movies
     <2006-11-01 Wed 19:15>
   ,* Discussion on climate change
-    <2006-11-02 Thu>
+    <2006-11-02 Thu 10:00-12:00>
+  ,* My days off
+    <2006-11-03 Fri>
+    <2006-11-06 Mon>
   #+end_example
 
 - Timestamp with repeater interval ::
@@ -6053,24 +6056,31 @@ agenda]]).  We distinguish:
     <%%(diary-float t 4 2)>
   #+end_example
 
+-  Time range ::
+#+cindex time range
+
+Time range is a timestamp having two time units connected by =-=
+
+#+begin_example
+,* Discussion on climate change
+   <2006-11-02 Thu 10:00-12:00>
+#+end_example
+
 - Time/Date range ::
 
-  #+cindex: timerange
+  #+cindex: time range
   #+cindex: date range
   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:
+  dates that are displayed and fall in the range.  The first example
+  specifies just the dates of the range while the second example
+  specifies a time range for each date.
 
   #+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>
+  ,** This weeks committee meetings
+     <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00>
   #+end_example
 
 - Inactive timestamp ::

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


-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>  To assist project planning, TODO items can be labeled with a date
> -and/or a time.  The specially formatted string carrying the date and
> +and/or a time purposes like when an event happens, a deadline for a
> +task, or tracking time spent on a task as described in later sections
> +of this chapter.  The specially formatted string carrying the date and
>  time information is called a /timestamp/ in Org mode.

What about:

    To assist project planning, TODO items can be labeled with a date
    and/or a time.  The specially formatted string carrying the date and
    time information is called a /timestamp/ in Org mode.  This may be
    a little confusing because timestamp is often used as indicating when
    something was created or last changed.  However, in Org mode this term
    is used in a much wider sense.

    Timestamps can be used to plan appointments, schedule tasks, set
    deadlines, track time, and more.  The following sections describe
    the timestamp format and tooling that Org mode provides for common
    use cases dealing with time and time intervals.

-- 
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: Is this proper time format?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>>  To assist project planning, TODO items can be labeled with a date
>> -and/or a time.  The specially formatted string carrying the date and
>> +and/or a time purposes like when an event happens, a deadline for a
>> +task, or tracking time spent on a task as described in later sections
>> +of this chapter.  The specially formatted string carrying the date and
>>  time information is called a /timestamp/ in Org mode.
>
> What about:
>
>     To assist project planning, TODO items can be labeled with a date
>     and/or a time.  The specially formatted string carrying the date and
>     time information is called a /timestamp/ in Org mode.  This may be
>     a little confusing because timestamp is often used as indicating when
>     something was created or last changed.  However, in Org mode this term
>     is used in a much wider sense.
>
>     Timestamps can be used to plan appointments, schedule tasks, set
>     deadlines, track time, and more.  The following sections describe
>     the timestamp format and tooling that Org mode provides for common
>     use cases dealing with time and time intervals.

I agree with your change.  I'm often minimalist in my changes (especially when
I'm trying not to rock the boat), but that's not always good.  If that's
it, make the change in both files and we can call it a day.  :-)

-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>> What about:
>>
> ...
> I agree with your change.  I'm often minimalist in my changes (especially when
> I'm trying not to rock the boat), but that's not always good.  If that's
> it, make the change in both files and we can call it a day.  :-)

May you please re-create the patch for the current main?

-- 
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: Is this proper time format?

[David Masterson]

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

Ihor Radchenko <yantar92@posteo.net> writes:

> May you please re-create the patch for the current main?

Ok. See below.

Minor question -- I've used Ediff in the past, but I now see diff-mode
in Emacs.  I get the idea of it (I think I used an early version of it
in the deep past), but wonder if I am seeing a bug in it.  In the diff
file below, there is a few mentions of "=--=" in separating timestamps
in a date/time range.  When I view the diff file in Diff mode, a couple
on those strings show up and a couple do not.  I had to check the file
with 'less' to make sure the diff file was intact.  Switching from
unified to context view didn't change this.

Am I missing an option in diff mode or is this a bug around handling
this particular string?

Change log:
================
Doc change to explain timestamps better

doc/org-guide.org (Dates and Times): purpose of timestamp + examples
doc/org-manual.org (Dates and Times): purpose of timestamp + examples
================


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Changee for org-guide and org-manual --]
[-- Type: text/x-diff, Size: 6532 bytes --]

diff --git a/doc/org-guide.org b/doc/org-guide.org
index 828bdd872..a6d4e7c3d 100644
--- a/doc/org-guide.org
+++ b/doc/org-guide.org
@@ -1081,7 +1081,15 @@
 
 To assist project planning, TODO items can be labeled with a date
 and/or a time.  The specially formatted string carrying the date and
-time information is called a /timestamp/ in Org mode.
+time information is called a /timestamp/ in Org mode.  This may be
+a little confusing because timestamp is often used as indicating when
+something was created or last changed.  However, in Org mode this term
+is used in a much wider sense.
+
+Timestamps can be used to plan appointments, schedule tasks, set
+deadlines, track time, and more.  The following sections describe
+the timestamp format and tooling that Org mode provides for common
+use cases dealing with time and time intervals.
 
 ** Timestamps
 :PROPERTIES:
@@ -1099,12 +1107,16 @@ the agenda (see [[*The Weekly/Daily Agenda]]).  We distinguish:
 
   A simple timestamp just assigns a date/time to an item.  This is
   just like writing down an appointment or event in a paper agenda.
+  There can be multiple timestamps in an item.
 
   #+begin_example
   ,* Meet Peter at the movies
     <2006-11-01 Wed 19:15>
   ,* Discussion on climate change
     <2006-11-02 Thu 20:00-22:00>
+  ,* My days off
+    <2006-11-03 Fri>
+    <2006-11-06 Mon>
   #+end_example
 
 - Timestamp with repeater interval ::
@@ -1121,8 +1133,6 @@ the agenda (see [[*The Weekly/Daily Agenda]]).  We distinguish:
 
 - Diary-style expression entries ::
 
-  #+cindex: diary style timestamps
-  #+cindex: sexp timestamps
   For more complex date specifications, Org mode supports using the
   special expression diary entries implemented in the Emacs Calendar
   package.  For example, with optional time:
@@ -1132,13 +1142,28 @@ the agenda (see [[*The Weekly/Daily Agenda]]).  We distinguish:
     <%%(diary-float t 4 2)>
   #+end_example
 
+- Time range
+
+  Time range is a timestamp having two time units connected by =-=
+
+  #+begin_example
+  ,* Discussion on climate change
+    <2006-11-02 Thu 10:00-12:00>
+  #+end_example
+
 - Time/Date range ::
 
-  Two timestamps connected by =--= denote a range.
+  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.  The first example
+  specifies just the dates of the range while the second example
+  specifies a time range for each date.
 
   #+begin_example
   ,** Meeting in Amsterdam
      <2004-08-23 Mon>--<2004-08-26 Thu>
+  ,** This weeks committee meetings
+     <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00>
   #+end_example
 
 - Inactive timestamp ::
diff --git a/doc/org-manual.org b/doc/org-manual.org
index c11694849..e0c100474 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5978,7 +5978,6 @@ or a dynamic block.
 #+cindex: dates
 #+cindex: times
 #+cindex: timestamp
-#+cindex: date stamp
 
 To assist project planning, TODO items can be labeled with a date
 and/or a time.  The specially formatted string carrying the date and
@@ -5987,22 +5986,26 @@ a little confusing because timestamp is often used as indicating when
 something was created or last changed.  However, in Org mode this term
 is used in a much wider sense.
 
+Timestamps can be used to plan appointments, schedule tasks, set
+deadlines, track time, and more.  The following sections describe
+the timestamp format and tooling that Org mode provides for common
+use cases dealing with time and time intervals.
+
 ** Timestamps
 :PROPERTIES:
 :DESCRIPTION: Assigning a time to a tree entry.
 :END:
 #+cindex: timestamps
 #+cindex: ranges, time
-#+cindex: date stamps
 #+cindex: deadlines
 #+cindex: scheduling
 
-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:
+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 [[*The Weekly/Daily Agenda]]).  We distinguish:
 
 - Plain timestamp; Event; Appointment ::
 
@@ -6011,13 +6014,16 @@ agenda]]).  We distinguish:
   A simple timestamp just assigns a date/time to an item.  This is
   just like writing down an appointment or event in a paper agenda.
   In the agenda display, the headline of an entry associated with
-  a plain timestamp is shown exactly on that date.
+  a plain timestamp is shown exactly on that date.  There can be multiple timestamps in an item.
 
   #+begin_example
   ,* Meet Peter at the movies
     <2006-11-01 Wed 19:15>
   ,* Discussion on climate change
-    <2006-11-02 Thu>
+    <2006-11-02 Thu 10:00-12:00>
+  ,* My days off
+    <2006-11-03 Fri>
+    <2006-11-06 Mon>
   #+end_example
 
 - Timestamp with repeater interval ::
@@ -6053,24 +6059,31 @@ agenda]]).  We distinguish:
     <%%(diary-float t 4 2)>
   #+end_example
 
+-  Time range ::
+#+cindex time range
+
+Time range is a timestamp having two time units connected by =-=
+
+#+begin_example
+,* Discussion on climate change
+   <2006-11-02 Thu 10:00-12:00>
+#+end_example
+
 - Time/Date range ::
 
-  #+cindex: timerange
+  #+cindex: time range
   #+cindex: date range
   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:
+  dates that are displayed and fall in the range.  The first example
+  specifies just the dates of the range while the second example
+  specifies a time range for each date.
 
   #+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>
+  ,** This weeks committee meetings
+     <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00>
   #+end_example
 
 - Inactive timestamp ::

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



-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

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

David Masterson <dsmasterson@gmail.com> writes:

> Ihor Radchenko <yantar92@posteo.net> writes:
>
>> May you please re-create the patch for the current main?
>
> Ok. See below.

Thanks!
See the attached final draft.
I amended removals of cindex entries in the manual - redundancy will not
hurt here (for better searchability).
I also slightly adjusted the wording and fixed list indentation in
one of description list items.
Finally, I detailed all the changes in the commit message and added
TINYCHANGE cookie.

Let me know if you are ok with this version.

Please note that with this patch your total contribution is approaching
non-trivial 15LOC. Further patches will require FSF copyright assignment.

> Minor question -- I've used Ediff in the past, but I now see diff-mode
> in Emacs.  I get the idea of it (I think I used an early version of it
> in the deep past), but wonder if I am seeing a bug in it.  In the diff
> file below, there is a few mentions of "=--=" in separating timestamps
> in a date/time range.  When I view the diff file in Diff mode, a couple
> on those strings show up and a couple do not.  I had to check the file
> with 'less' to make sure the diff file was intact.  Switching from
> unified to context view didn't change this.
>
> Am I missing an option in diff mode or is this a bug around handling
> this particular string?

I suspect that it is greedy fontification. =--= is a part of diff
syntax, AFAIK. May report is as a bug to Emacs.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-manual-org-guide-Improve-timestamp-documentation.patch --]
[-- Type: text/x-patch, Size: 7207 bytes --]

From 17e8902e8d6f3c23a9226d697e51169c24b5414a Mon Sep 17 00:00:00 2001
Message-ID: <17e8902e8d6f3c23a9226d697e51169c24b5414a.1687004884.git.yantar92@posteo.net>
From: David Masterson <dsmasterson@gmail.com>
Date: Sat, 17 Jun 2023 15:26:55 +0300
Subject: [PATCH] org-manual, org-guide: Improve timestamp documentation

* doc/org-manual.org (Dates and Times): Explain the purpose of
timestamps in the opening paragraphs.
(Timestamps): Mention that time range.  Clarify that an entry may
contain multiple timestamps, providing an example.  Explain formal
time range meaning, with example.  Add cindex entry "time range".  Add
date range example.
* doc/org-guide.org: Syncronoize changes with org-manual, adding some
missing pieces.
(Timestamps): Remove useless cindex entries (org-guide does not
produce index).

Co-authored-by: Ihor Radchenko <yantar92@posteo.net>
Link: https://orgmode.org/list/SJ0PR03MB5455693CA8266256D46BA594A259A@SJ0PR03MB5455.namprd03.prod.outlook.com

TINYCHANGE
---
 doc/org-guide.org  | 33 +++++++++++++++++++++++++++----
 doc/org-manual.org | 49 +++++++++++++++++++++++++++++++---------------
 2 files changed, 62 insertions(+), 20 deletions(-)

diff --git a/doc/org-guide.org b/doc/org-guide.org
index 828bdd872..a6d4e7c3d 100644
--- a/doc/org-guide.org
+++ b/doc/org-guide.org
@@ -1081,7 +1081,15 @@ * Dates and Times
 
 To assist project planning, TODO items can be labeled with a date
 and/or a time.  The specially formatted string carrying the date and
-time information is called a /timestamp/ in Org mode.
+time information is called a /timestamp/ in Org mode.  This may be
+a little confusing because timestamp is often used as indicating when
+something was created or last changed.  However, in Org mode this term
+is used in a much wider sense.
+
+Timestamps can be used to plan appointments, schedule tasks, set
+deadlines, track time, and more.  The following sections describe
+the timestamp format and tooling that Org mode provides for common
+use cases dealing with time and time intervals.
 
 ** Timestamps
 :PROPERTIES:
@@ -1099,12 +1107,16 @@ ** Timestamps
 
   A simple timestamp just assigns a date/time to an item.  This is
   just like writing down an appointment or event in a paper agenda.
+  There can be multiple timestamps in an item.
 
   #+begin_example
   ,* Meet Peter at the movies
     <2006-11-01 Wed 19:15>
   ,* Discussion on climate change
     <2006-11-02 Thu 20:00-22:00>
+  ,* My days off
+    <2006-11-03 Fri>
+    <2006-11-06 Mon>
   #+end_example
 
 - Timestamp with repeater interval ::
@@ -1121,8 +1133,6 @@ ** Timestamps
 
 - Diary-style expression entries ::
 
-  #+cindex: diary style timestamps
-  #+cindex: sexp timestamps
   For more complex date specifications, Org mode supports using the
   special expression diary entries implemented in the Emacs Calendar
   package.  For example, with optional time:
@@ -1132,13 +1142,28 @@ ** Timestamps
     <%%(diary-float t 4 2)>
   #+end_example
 
+- Time range
+
+  Time range is a timestamp having two time units connected by =-=
+
+  #+begin_example
+  ,* Discussion on climate change
+    <2006-11-02 Thu 10:00-12:00>
+  #+end_example
+
 - Time/Date range ::
 
-  Two timestamps connected by =--= denote a range.
+  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.  The first example
+  specifies just the dates of the range while the second example
+  specifies a time range for each date.
 
   #+begin_example
   ,** Meeting in Amsterdam
      <2004-08-23 Mon>--<2004-08-26 Thu>
+  ,** This weeks committee meetings
+     <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00>
   #+end_example
 
 - Inactive timestamp ::
diff --git a/doc/org-manual.org b/doc/org-manual.org
index c11694849..4b00d1e6f 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -5987,6 +5987,11 @@ * Dates and Times
 something was created or last changed.  However, in Org mode this term
 is used in a much wider sense.
 
+Timestamps can be used to plan appointments, schedule tasks, set
+deadlines, track time, and more.  The following sections describe
+the timestamp format and tooling that Org mode provides for common
+use cases dealing with time and time intervals.
+
 ** Timestamps
 :PROPERTIES:
 :DESCRIPTION: Assigning a time to a tree entry.
@@ -5997,12 +6002,12 @@ ** Timestamps
 #+cindex: deadlines
 #+cindex: scheduling
 
-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:
+A timestamp is a specification of a date---possibly with a time or
+time range---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:
 
 - Plain timestamp; Event; Appointment ::
 
@@ -6011,13 +6016,17 @@ ** Timestamps
   A simple timestamp just assigns a date/time to an item.  This is
   just like writing down an appointment or event in a paper agenda.
   In the agenda display, the headline of an entry associated with
-  a plain timestamp is shown exactly on that date.
+  a plain timestamp is shown exactly on that date.  There can be
+  multiple timestamps in an item.
 
   #+begin_example
   ,* Meet Peter at the movies
     <2006-11-01 Wed 19:15>
   ,* Discussion on climate change
-    <2006-11-02 Thu>
+    <2006-11-02 Thu 10:00-12:00>
+  ,* My days off
+    <2006-11-03 Fri>
+    <2006-11-06 Mon>
   #+end_example
 
 - Timestamp with repeater interval ::
@@ -6053,24 +6062,32 @@ ** Timestamps
     <%%(diary-float t 4 2)>
   #+end_example
 
+- Time range ::
+  #+cindex: time range
+
+  Time range is a timestamp having two time units connected by =-=
+
+  #+begin_example
+,* Discussion on climate change
+   <2006-11-02 Thu 10:00-12:00>
+  #+end_example
+
 - Time/Date range ::
 
+  #+cindex: time range
   #+cindex: timerange
   #+cindex: date range
   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:
+  dates that are displayed and fall in the range.  The first example
+  specifies just the dates of the range while the second example
+  specifies a time range for each date.
 
   #+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>
+  ,** This weeks committee meetings
+     <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00>
   #+end_example
 
 - Inactive timestamp ::
-- 
2.41.0


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


-- 
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: Is this proper time format?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>> Ihor Radchenko <yantar92@posteo.net> writes:
>>
>>> May you please re-create the patch for the current main?
>>
>> Ok. See below.
>
> Thanks!
> See the attached final draft.

What's the command to save the attachment?  It doesn't look like a mime
attachment to me,

> I amended removals of cindex entries in the manual - redundancy will not
> hurt here (for better searchability).

If they've got a purpose, that's fine.

> I also slightly adjusted the wording and fixed list indentation in
> one of description list items.

One minor note -- I think of datestamp & timestamp as one word each
while 'date range' & 'time range' are two words each.  Unless you've got
other reasons, I'd follow this convention.  I think I see one 'cindex'
that has 'timerange'.

> Finally, I detailed all the changes in the commit message and added
> TINYCHANGE cookie.

Thanks.  This is a good example for me.

> Let me know if you are ok with this version.

It looks good except for the minor note above.

> Please note that with this patch your total contribution is approaching
> non-trivial 15LOC. Further patches will require FSF copyright
> assignment.

You got the number via some 'git' command??  If I get to doing more, I
will do the copyright assignment -- I just never thought I'd make much
changes. 

-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>> See the attached final draft.
>
> What's the command to save the attachment?  It doesn't look like a mime
> attachment to me,

In message-mode:

C-c C-a runs the command mml-attach-file (found in message-mode-map),
which is an autoloaded interactive native-compiled Lisp function in
‘mml.el’.

It is bound to C-c RET f and C-c C-a.

>> I also slightly adjusted the wording and fixed list indentation in
>> one of description list items.
>
> One minor note -- I think of datestamp & timestamp as one word each
> while 'date range' & 'time range' are two words each.  Unless you've got
> other reasons, I'd follow this convention.  I think I see one 'cindex'
> that has 'timerange'.

I left the incorrectly spelled 'timerange' cindex entry on purpose.
In Org, we have variables `org-agenda-timerange-leaders' and
`org-agenda-remove-timeranges-from-blocks'. So, in Info-mode, some
people may search index for 'timerange' instead of 'time range'. Again,
the purpose is helping searchability.

I now applied to patch onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=d50956e48

>> Please note that with this patch your total contribution is approaching
>> non-trivial 15LOC. Further patches will require FSF copyright
>> assignment.
>
> You got the number via some 'git' command??  If I get to doing more, I
> will do the copyright assignment -- I just never thought I'd make much
> changes. 

Not exactly. There is git command to find total number of changed LOCs:

<https://github.com/yantar92/emacs-config/blob/master/config.org#detect-fsf-contribution-status-of-sender-for-org-ml>
(shell-command-to-string
               (format "cd ~/Git/org-mode/; git log --author=\"%s\" --pretty=tformat: --numstat main | gawk '{ add += $1; subs += $2; loc += $1 - $2 } END { printf \"+l: %%s -l: %%s total: %%s\", add, subs, loc }' -"
                       (downcase (if (string-match-p email all-committers)
                                     email sender))))

However, it will count all the LOCs, not just non-trivial.
By raw number of LOCs, your patch is indeed over 15LOC. However, part of
the patch is my text or syncing org-manual and org-guide texts. Those
changes are trivial.

So, I judged that the patch is still acceptable without FSF assignment.
But it will be the limit.

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


Applied.

Re: Is this proper time format?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> In message-mode:
>
> C-c C-a runs the command mml-attach-file (found in message-mode-map),
> which is an autoloaded interactive native-compiled Lisp function in
> ‘mml.el’.

I used C-c C-a to attach my patch to the message for you.  I was looking
for the reverse to pull your patch out.  When I read the message, the
patch was inlined, so I wasn't seeing any buttons(?) to pull it out with
and the Mime command didn't seem to do anything, so I thought I was
looking in the wrong.  The patch showed in diff-mode.

> I left the incorrectly spelled 'timerange' cindex entry on purpose.
> In Org, we have variables `org-agenda-timerange-leaders' and
> `org-agenda-remove-timeranges-from-blocks'. So, in Info-mode, some
> people may search index for 'timerange' instead of 'time range'. Again,
> the purpose is helping searchability.
>
> I now applied to patch onto main.
> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=d50956e48

Thank you.

> Not exactly. There is git command to find total number of changed LOCs:
>
> <https://github.com/yantar92/emacs-config/blob/master/config.org#detect-fsf-contribution-status-of-sender-for-org-ml>
> (shell-command-to-string
>                (format "cd ~/Git/org-mode/; git log --author=\"%s\" --pretty=tformat: --numstat main | gawk '{ add += $1; subs += $2; loc += $1 - $2 } END { printf \"+l: %%s -l: %%s total: %%s\", add, subs, loc }' -"
>                        (downcase (if (string-match-p email all-committers)
>                                      email sender))))

Whoa.

> However, it will count all the LOCs, not just non-trivial.
> By raw number of LOCs, your patch is indeed over 15LOC. However, part of
> the patch is my text or syncing org-manual and org-guide texts. Those
> changes are trivial.
>
> So, I judged that the patch is still acceptable without FSF assignment.
> But it will be the limit.

Understood.

-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

> I used C-c C-a to attach my patch to the message for you.  I was looking
> for the reverse to pull your patch out.  When I read the message, the
> patch was inlined, so I wasn't seeing any buttons(?) to pull it out with
> and the Mime command didn't seem to do anything, so I thought I was
> looking in the wrong.  The patch showed in diff-mode.

It may depend on what you are using to view the patch.
In notmuch, there is `notmuch-show-save-part' and `notmuch-save-attachments'.
In Gnus, there is `notmuch-show-save-part'.

-- 
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: Is this proper time format?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>> I used C-c C-a to attach my patch to the message for you.  I was looking
>> for the reverse to pull your patch out.  When I read the message, the
>> patch was inlined, so I wasn't seeing any buttons(?) to pull it out with
>> and the Mime command didn't seem to do anything, so I thought I was
>> looking in the wrong.  The patch showed in diff-mode.
>
> It may depend on what you are using to view the patch.  In notmuch,
> there is `notmuch-show-save-part' and `notmuch-save-attachments'.  In
> Gnus, there is `notmuch-show-save-part'.

Hmm.  I think notmuch is non-standard.  I was using gnus.

-- 
David Masterson

Re: Is this proper time format?

[Ihor Radchenko]

Ihor Radchenko <yantar92@posteo.net> writes:

> Subject: [PATCH] doc/org-manual.org: Clarify how timestamps are considered by
>  agenda

Canceled.
In favor of the other applied 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>