# HG changeset patch
# User Glenn Morris <rgm@gnu.org>
# Date 1284518079 25200
# Node ID 87d704ff4a52d15bbd900f17ad95cf1c6faf8d19
# Parent  d2f5496377e6033541456a48044cef9215ff183c
* lisp/calendar/diary-lib.el (diary-list-entries): Doc fix.  (Bug#7019)

diff -r d2f5496377e6 -r 87d704ff4a52 lisp/ChangeLog
--- a/lisp/ChangeLog	Tue Sep 14 13:11:44 2010 +0200
+++ b/lisp/ChangeLog	Tue Sep 14 19:34:39 2010 -0700
@@ -1,3 +1,7 @@
+2010-09-15  Glenn Morris  <rgm@gnu.org>
+
+	* calendar/diary-lib.el (diary-list-entries): Doc fix.  (Bug#7019)
+
 2010-09-14  Stefan Monnier  <monnier@iro.umontreal.ca>
 
 	* emacs-lisp/byte-run.el (set-advertised-calling-convention):
diff -r d2f5496377e6 -r 87d704ff4a52 lisp/calendar/diary-lib.el
--- a/lisp/calendar/diary-lib.el	Tue Sep 14 13:11:44 2010 +0200
+++ b/lisp/calendar/diary-lib.el	Tue Sep 14 19:34:39 2010 -0700
@@ -711,14 +711,26 @@
 for NUMBER days starting with date DATE.  The other entries are hidden
 using overlays.  If NUMBER is less than 1, this function does nothing.
 
-Returns a list of all relevant diary entries found, if any, in order by date.
+Returns a list of all relevant diary entries found.
 The list entries have the form ((MONTH DAY YEAR) STRING SPECIFIER) where
 \(MONTH DAY YEAR) is the date of the entry, STRING is the entry text, and
 SPECIFIER is the applicability.  If the variable `diary-list-include-blanks'
 is non-nil, this list includes a dummy diary entry consisting of the empty
 string for a date with no diary entries.
 
-After the list is prepared, the following hooks are run:
+If entries are being produced for multiple dates (i.e., NUMBER > 1),
+then this function normally returns the entries from any given
+diary file in date order.  The entries for any given day are in
+the order in which they were found in the file, not necessarily
+in time-of-day order.  Note that any functions present on the
+hooks (see below) may add entries, or change the order.  For
+example, `diary-include-other-diary-files' adds entries from any
+include files that it finds to the end of the original list.  The
+entries from each file will be in date order, but the overall
+list will not be.  If you want the entire list to be in time order,
+add `diary-sort-entries' to the end of `diary-list-entries-hook'.
+
+After the initial list is prepared, the following hooks are run:
 
   `diary-nongregorian-listing-hook' can cull dates from the diary
       and each included file, for example to process Islamic diary