[BUG] Inverse behavior from \ [9.6.4 (release_9.6.4-1-g76cf21 @ /Users/johnw/.emacs.d/lisp/org-mode/lisp/)]

[John Wiegley]

When I type ‘\ c’, the agenda view limits to my (c)all tags. This is what I
expected to see.

When I type ‘\ ’, however, it limits to every tag *but* the empty tag.
This is the opposite of what I expect to see.

Emacs  : GNU Emacs 28.2 (build 1, x86_64-apple-darwin22.5.0, Carbon Version 169 
AppKit 2299.6)
Package: Org mode version 9.6.4 (release_9.6.4-1-g76cf21 @ 
/Users/johnw/.emacs.d/lisp/org-mode/lisp/)
-- 
John Wiegley  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com  60E1 46C4 BD1A 7AC1 4BA2

Re: outline-* -> org-* possible?

[Samuel Wales]

thank you.  it looks like outline-hide-subtree is the only one i will
need to synchronously change, to an org-fold version.


On 6/11/23, Ihor Radchenko  wrote:
> Samuel Wales  writes:
>
>> in my old version, i am finding functions and variables named
>> outline-* that have no obvious org-* replacement.  a few do, and a few
>> can be substituted with no probable issues.  here are examples of
>> stuff i might in principle be running:
>
> Almost all the org-* alternatives are available, except
> outline-next-heading/outline-previous-heading, which will remain
> functional. Org provides
> org-next-visible-heading/org-previous-visible-heading though, which are
> more useful interactively.
>
> --
> Ihor Radchenko // yantar92,
> Org mode contributor,
> Learn more about Org mode at .
> Support Org development at ,
> or support my work at 
>


-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

Re: Is this proper time format?

[David Masterson]

Ihor Radchenko  writes:

> David Masterson  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-2022.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  writes:

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

[PATCH] ox-icalendar: Unscheduled tasks & repeating tasks

[Jack Kamm]

Hello,

I am attaching an updated patch for ox-icalendar unscheduled and
repeating TODOs, incorporating some of Ihor's feedback to my RFC some
months ago.

Compared to my original RFC, here are the main changes:

- For unscheduled TODOs with repeating deadline, the deadline warning
  days is used as the start time by default, in order to comply with
  the iCalendar spec which demands a start time in this case.

- Previously I had separate patches for unscheduled and repeating
  TODOs, but now I combine them into a single patch because of the way
  repeats and start times are intertwined for repeating deadlines.

- New customization `org-icalendar-todo-unscheduled-start' controls
  the exported start time for unscheduled TODOs. It replaces
  `org-icalendar-todo-force-scheduling' from my previous version of
  the patch.

- In case of a SCHEDULED repeater, and a DEADLINE with no repeater,
  the task repeats until the deadline, using the RRULE UNTIL keyword.

- Added linting for the case where SCHEDULED and DEADLINE have
  mismatching repeaters.

- Added several tests for ox-icalendar, and a test for the new lint as well.

There are still a few cases that are not yet handled, but they are
less common and will take some more work to implement, so I would
prefer to leave them to future patches:

- Case where SCHEDULED and DEADLINE have mismatched repeaters.  We can
  use RDATE with differing DURATION for this.

- Case where DEADLINE has repeater but SCHEDULED does not.  We can use
  RDATE for the first instance, and RRULE for the subsequent repeats.

- Case of catch-up "++" repeaters.  We can use EXDATE to exclude
  repeats before today.

- Case of restart ".+" repeaters.  I don't think iCalendar can handle
  this case, and we should ignore it.

>From 1135e3e7cb08353892c439b085d3bf0bf1072ecb Mon Sep 17 00:00:00 2001
From: Jack Kamm 
Date: Sun, 11 Jun 2023 07:50:20 -0700
Subject: [PATCH] ox-icalendar: Add support for unscheduled and repeating TODOs

* lisp/ox-icalendar.el (org-icalendar-todo-unscheduled-start): New
customization to control the exported start time of unscheduled tasks.
(org-icalendar--rrule): Helper function for RRULE export.
(org-icalendar--vevent): Use the new helper function for RRULE.
(org-icalendar--vtodo): Change how unscheduled TODOs are handled using
the new customization option.  Export SCHEDULED and DEADLINE
repeaters.  In case of SCHEDULED repeater and a DEADLINE without
repeater, treat DEADLINE as RRULE UNTIL.  Emit a warning for tricky
edge cases that are not yet implemented.
* testing/lisp/test-ox-icalendar.el
(test-ox-icalendar/todo-repeater-shared): Test for exporting shared
SCHEDULED/DEADLINE repeater.
(test-ox-icalendar/todo-repeating-deadline-warndays): Test using
warning days as DTSTART of repeating deadline.
(test-ox-icalendar/todo-repeater-until): Test using DEADLINE as RRULE
UNTIL.
(test-ox-icalendar/todo-repeater-until-utc): Test RRULE UNTIL is in
UTC format when DTSTART is not in local time format.
* lisp/org-lint.el (org-lint-mismatched-planning-repeaters): Add lint
for mismatched SCHEDULED and DEADLINE repeaters.
* testing/lisp/test-org-lint.el
(test-org-lint/mismatched-planning-repeaters): Add test for linting of
mismatched SCHEDULED and DEADLINE repeaters.
---
 etc/ORG-NEWS  |  64 
 lisp/org-lint.el  |  34 ++
 lisp/ox-icalendar.el  | 165 +-
 testing/lisp/test-org-lint.el |   7 ++
 testing/lisp/test-ox-icalendar.el |  74 ++
 5 files changed, 320 insertions(+), 24 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 7e7015064..a24caddfe 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -50,6 +50,21 @@ ox-icalendar.  In particular, older versions of org-caldav may
 encounter issues, and users are advised to update to the most recent
 version of org-caldav.  See [[https://github.com/dengste/org-caldav/commit/618bf4cdc9be140ca1993901d017b7f18297f1b8][this org-caldav commit]] for more information.
 
+*** Icalendar export of unscheduled TODOs no longer have start time of today
+
+For TODOs without a scheduled start time, ox-icalendar no longer
+forces them to have a scheduled start time of today when exporting.
+
+Instead, the new customization ~org-icalendar-todo-unscheduled-start~
+controls the exported start date for unscheduled tasks.  Its default
+is ~recurring-deadline-warning~ which will export unscheduled tasks
+with no start date, unless it has a recurring deadline (in which case
+the iCalendar spec demands a start date, and
+~org-deadline-warning-days~ is used for that).
+
+To revert to the old behavior, set
+~org-icalendar-todo-unscheduled-start~ to ~current-datetime~.
+
 ** New and changed options
 *** Commands affected by ~org-fold-catch-invisible-edits~ can now be customized
 
@@ -188,6 +203,28 @@ default settings of "Body only", "Visible only", and "Force
 publishing" in the ~org-export-dispatch~ UI to be customized,
 respectively.
 
+*** New 

Re: Babel results don't respect narrowing

[Ihor Radchenko]

[Adding Org ML back to CC]

Sebastian Wålinder  writes:

>> May you elaborate about what kind of library you are referring to?
>> Please describe the actual problem you ran into.
> I'm using the AI API library `org-assistant` 
> (https://github.com/tyler-dodge/org-assistant).
> The library uses org SRC blocks. When you execute a block, it adds an ID tag 
> to the org SRC result tag using the standard org SRC execute mechanism.
> However, the library then searches for that ID in the buffer so that it can 
> be replaced with the actual async output, but it doesn't search outside the 
> narrowing, and so can't find it.

I'd say that org-assistant should disregard narrowing.
AFAIU, org-assistant is using some kind of custom async processing (why
not `org-babel-comint-async-register'?). If async processing is used, at
the time when result is to be inserted, the user might set arbitrary
narrowing in the buffer - it does not make sense to make things
dependent on that custom narrowing.

> This could be fixed in `org-assistant` itself, by disregarding the narrowing 
> when searching for the ID, but I think it makes more sense to have org blocks 
> respect the narrowing when outputting results, as the narrowing is respected 
> by most other commands.
>
> An advantage of respecting the narrowing when searching for the result tag is 
> that the user can save old results from being overwritten by the next 
> execution of the SRC block by simply narrowing so that the result tag isn't 
> in view.

Maybe. But it is too late.
Honouring narrowing in `org-babel-where-is-src-block' will be a breaking
change. At least, it is breaking a dozen of Org's own tests.

The best I can do here is documenting the current behaviour in the
docstring, to avoid confusion.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: Org element cache in indirect buffers

[Ihor Radchenko]

Sebastian Wålinder  writes:

> It appears that indirect buffers duplicate the entire org element cache from 
> the base buffer whenever created.

Not exactly. Only link to the cache root is copied and some cache
elements may not be garbage-collected.

> Running `memory-report` indicates that each indirect buffer has the same 
> memory blueprint.

> This becomes a massive issue with large org files.
>
> My in my 160 000 line org file, the org element cache takes 100 mb, and so 
> each new indirect buffer consumes an additional 100 mbs of memory.

This has to be a bug in `memory-report'. Most of the cache elements will
be referenced by link and thus there should be double-counting going on 
somewhere.

> I also wonder if this means the caching is performed by each indirect buffer 
> independently, and doesn't carry over.

Caching is using base buffer actually.
I guess we can explicitly set reference to the cache root to nil in
indirect buffers.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Org element cache in indirect buffers

[Sebastian Wålinder]

Hello!

It appears that indirect buffers duplicate the entire org element cache from 
the base buffer whenever created.

Running `memory-report` indicates that each indirect buffer has the same memory 
blueprint.

This becomes a massive issue with large org files.

My in my 160 000 line org file, the org element cache takes 100 mb, and so each 
new indirect buffer consumes an additional 100 mbs of memory.

I also wonder if this means the caching is performed by each indirect buffer 
independently, and doesn't carry over.

Thoughts?

Thanks,
Sebastian

Re: org-todo-state-tags-triggers not working with regexp?

[Ihor Radchenko]

Ypo  writes:

> I would like to remove every tag when changing to done state.
>
> This is not working:
>
>   '(org-todo-state-tags-triggers '((done ("(.*)"
>
> This works though:
>
>   '(org-todo-state-tags-triggers '((done ("Atag"

Yes, regexps are not supported in `org-todo-state-tags-triggers'.
You can use `org-trigger-hook'.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

org-todo-state-tags-triggers not working with regexp?

[Ypo]

Hi

I would like to remove every tag when changing to done state.

This is not working:

 '(org-todo-state-tags-triggers '((done ("(.*)"

This works though:

 '(org-todo-state-tags-triggers '((done ("Atag"


Best regards

Re: Where does headline data end for the purpose of `org-adapt-indentation´ == ´headline-data

[Farblos]

On 2023-06-11  12:21, Ihor Radchenko wrote:


This is a bug. Fixed now, on main.


Thanks!

Re: outline-* -> org-* possible?

[Ihor Radchenko]

Samuel Wales  writes:

> in my old version, i am finding functions and variables named
> outline-* that have no obvious org-* replacement.  a few do, and a few
> can be substituted with no probable issues.  here are examples of
> stuff i might in principle be running:

Almost all the org-* alternatives are available, except
outline-next-heading/outline-previous-heading, which will remain
functional. Org provides
org-next-visible-heading/org-previous-visible-heading though, which are
more useful interactively.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: Where does headline data end for the purpose of `org-adapt-indentation´ == ´headline-data

[Ihor Radchenko]

Jens Schmidt  writes:

> (setq org-adapt-indentation 'headline-data)
>
> Paste the following into a new org file, headline A being the on the
> first line:
>
>  snip 
> ** Headline A
>
>
>
> ** Headline B
>
>
>
> ** Headline C
> :properties:
>  snip 
>
> Then try TAB on lines (my humble opinion in parentheses)
>
> 2: no indent (NOK)

This is right:

`org-adapt-indentation' docstring states

When this variable is set to headline-data, Org only adapts the
indentation of the data lines right below the headline, such as
planning/clock lines and property/logbook drawers.

Blank line is not a planning/clock/line/property drawer/logbook.
So, we do not indent.

> 6: indent (OK)
> 7: indent (NOK)

This is a bug. Fixed now, on main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=34082ff18

The logic in `org-indent-line' did not account for blank lines after heading.

> 11: no indent (NOK)

This is also OK. ":properties:", from Org's point of view is not a
property drawer, but a paragraph (there is no closing :end: and property
values inside). So, it is not a headline data.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: Is this proper time format?

[Ihor Radchenko]

David Masterson  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 .
Support Org development at ,
or support my work at 

Re: Is this proper time format?

[Ihor Radchenko]

David Masterson  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 .
Support Org development at ,
or support my work at 

Re: Is this proper time format?

[David Masterson]

Ihor Radchenko  writes:

> David Masterson  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
@@