Re: Is this proper time format?

[David Masterson <dsmasterson@gmail.com>]

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