Hello !


I would like to submit the attached patch for org.el.

This patch introduces the new function org-find-timestamps, which has 
the documentation given below.

Part of its functionality is also added as a new option to the
function org-sparse-tree. However, the full functionality of
org-find-timestamps can only be used if it is called directly.

This is my first patch to org-mode so I would be grateful for any
advice and comments.
(There already has been some very helpful discussion with Bastien
see news://news.gmane.org:119/4E29C4BA.5090906@online.de)

If this patch is deemed acceptable I would be glad to submit a secound 
patch to the documentation as well. By the way: There are surely 
official documentation standards, that I could adhere for this. However, 
at present I cannot find them. Could anyone provide me a pointer please ?

with kind regards, Marc-Oliver Ihm


> org-find-timestamps is an interactive Lisp function in `org.el'.
>
> (org-find-timestamps &optional FIRST-DATE LAST-DATE BUFFER-NAME WHICH
> COLLECT-METHOD SORT)
>
> Find inactive timestamps within a date-range and maybe sort them.
>
> This function can help to bring the notes, that you take within
> org-mode, into a chronological order, even if they are scattered
> among many different nodes. The result is somewhat like a diary,
> listing the timestamps of the notes, that you have taken on each day.
> Such a listing might help to provide an answer to the common question
> 'What have I done last Week ?'
> Please be aware however: This intended usage requires,
> that you routinely insert (inactive) timestamps into the
> notes that you write, which is a prerequisite habit that you may or
> may not want to adopt.
>
> org-find-timstamps works in these steps: Create a regular expression
> to match a given range of dates; search for it and
> display the results either as a sparse tree or with the help
> of occur. The original buffer is not modified.
>
> The Arguments FIRST-DATE and LAST-DATE (yyyy-mm-dd) define the range
> of timestamps to search for. In general anything, that can be
> understood by `org-read-date' will be accepted.
>
> BUFFER-NAME specifies the name of the buffer to search. If nil, use
> the current buffer.
>
> The Argument WHICH (one of the symbols `active', `inactive'
> or `both'), tells the function, which timestamps to search for.
>
> COLLECT-METHOD can be one of `org-occur', `occur' and
> `multi-occur' and determines, Which buffers to search (current or
> all org-mode buffers) and how to present the matches.
>
> Results will be sorted according to SORT (either the symbol `y'
> or `n'). Sorting however is only possible, if results are presented
> with `occur' or `multi-occur'.
>
> All Arguments can be `nil' (or ommitted), in which case their values
> are queried interactively.