Doc fixes related to diary-sort-entries.

* lisp/calendar/diary-lib.el (diary-list-entries-hook, diary-sort-entries):
Doc fixes.

* doc/emacs/cal-xtra.texi (Fancy Diary Display): Emphasize that sort
should be the last hook item.

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index af408d44a399284e396c1d4019a286f3dd81c9e2..2c47fbe0daf97620c5d16a80953920e816a3a180 100644 (file)
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,5 +1,8 @@
 2010-09-14  Glenn Morris  <rgm@gnu.org>
 
+       * cal-xtra.texi (Fancy Diary Display): Emphasize that sort should be
+       the last hook item.
+
        * calendar.texi (Appointments): Also updated when a diary include file
        is saved.
 

diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi
index 6058854235618697d4401df51c25ebfdf0335c19..de36ccc4f5f2be205d797b3336e172c12114ec0b 100644 (file)
--- a/doc/emacs/cal-xtra.texi
+++ b/doc/emacs/cal-xtra.texi
@@ -613,7 +613,9 @@ each day's diary entries by their time of day.  Here's how:
 @noindent
 For each day, this sorts diary entries that begin with a recognizable
 time of day according to their times.  Diary entries without times come
-first within each day.
+first within each day.  Note how the sort command is placed at the end
+of the hook list, in case earlier members of the list change the order
+of the diary entries, or add items.
 
 @vindex diary-include-string
   Your main diary file can include other files.  This permits a group of

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 66be118bf7e40dc4e22661be72535b82e009934c..6098dad51de7cb4d0db6ed8672da3922e7db633a 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,8 @@
 2010-09-14  Glenn Morris  <rgm@gnu.org>
 
+       * calendar/diary-lib.el (diary-list-entries-hook, diary-sort-entries):
+       Doc fixes.
+
        * calendar/diary-lib.el (diary-included-files): New variable.
        (diary-list-entries): Maybe initialize diary-included-files.
        (diary-include-other-diary-files): Append to diary-included-files.

diff --git a/lisp/calendar/diary-lib.el b/lisp/calendar/diary-lib.el
index 83b49e91e76f59fa4508e47a709942e2c67b0de4..46926050362497e084f8bd13a71bc57a3e22868a 100644 (file)
--- a/lisp/calendar/diary-lib.el
+++ b/lisp/calendar/diary-lib.el
@@ -187,11 +187,12 @@ you will probably also want to add `diary-mark-included-diary-files' to
 
      (setq diary-display-function 'diary-fancy-display)
      (add-hook 'diary-list-entries-hook 'diary-include-other-diary-files)
-     (add-hook 'diary-list-entries-hook 'diary-sort-entries)
+     (add-hook 'diary-list-entries-hook 'diary-sort-entries t)
 
 in your `.emacs' file to cause the fancy diary buffer to be displayed with
 diary entries from various included files, each day's entries sorted into
-lexicographic order."
+lexicographic order.  Note how the sort function is placed last,
+so that it can sort the entries included from other files."
   :type 'hook
   :options '(diary-include-other-diary-files diary-sort-entries)
   :group 'diary)
@@ -1584,7 +1585,10 @@ be used instead of a colon (:) to separate the hour and minute parts."
                       (string-lessp ts1 ts2)))))))
 
 (defun diary-sort-entries ()
-  "Sort the list of diary entries by time of day."
+  "Sort the list of diary entries by time of day.
+If you add this function to `diary-list-entries-hook', it should
+be the last item in the hook, in case earlier items add diary
+entries, or change the order."
   (setq diary-entries-list (sort diary-entries-list 'diary-entry-compare)))
 
 (define-obsolete-function-alias 'sort-diary-entries 'diary-sort-entries "23.1")