Ihor Radchenko <yanta...@posteo.net> writes:
> David Masterson <dsmaster...@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
================
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 ::
--
David Masterson
