Ihor Radchenko <[email protected]> writes:
> David Masterson <[email protected]> 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?
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 ::
--
David Masterson
