diary-lib.el doc fixes.

* lisp/calendar/diary-lib.el (diary-list-entries-hook)
(diary-mark-entries-hook, diary-nongregorian-listing-hook)
(diary-nongregorian-marking-hook, diary-list-entries)
(diary-include-other-diary-files, diary-mark-entries)
(diary-mark-included-diary-files): Doc fixes.

2 files changed, 90 insertions, 47 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 2b61509fb30..cbb03baa3bf 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,11 @@
+2011-05-10  Glenn Morris  <rgm@gnu.org>
+
+        * calendar/diary-lib.el (diary-list-entries-hook)
+        (diary-mark-entries-hook, diary-nongregorian-listing-hook)
+        (diary-nongregorian-marking-hook, diary-list-entries)
+        (diary-include-other-diary-files, diary-mark-entries)
+        (diary-mark-included-diary-files): Doc fixes.
+
 2011-05-09  Juanma Barranquero  <lekktu@gmail.com>
 
         * misc.el: Require tabulated-list.el during compilation.
diff --git a/lisp/calendar/diary-lib.el b/lisp/calendar/diary-lib.el
index 1e1066028ac..62da7579d50 100644
--- a/lisp/calendar/diary-lib.el
+++ b/lisp/calendar/diary-lib.el
@@ -212,7 +212,15 @@ you will probably also want to add `diary-mark-included-diary-files' to
 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.  Note how the sort function is placed last,
-so that it can sort the entries included from other files."
+so that it can sort the entries included from other files.
+
+This hook runs after `diary-nongregorian-listing-hook'.  These two hooks
+differ only if you are using included diary files.  In that case,
+`diary-nongregorian-listing-hook' runs for each file, whereas
+`diary-list-entries-hook' only runs once, for the main diary file.
+So for example, to sort the complete list of diary entries you would
+use the list-entries hook, whereas to process e.g. Islamic entries in
+the main file and all included files, you would use the nongregorian hook."
   :type 'hook
   :options '(diary-include-other-diary-files diary-sort-entries)
   :group 'diary)
@@ -224,7 +232,12 @@ so that it can sort the entries included from other files."
   "List of functions called after marking diary entries in the calendar.
 You might wish to add `diary-mark-included-diary-files', in which case
 you will probably also want to add `diary-include-other-diary-files' to
-`diary-list-entries-hook'."
+`diary-list-entries-hook'.
+
+This hook runs after `diary-nongregorian-marking-hook'.  These two hooks
+differ only if you are using included diary files.  In that case,
+`diary-nongregorian-marking-hook' runs for each file, whereas
+`diary-mark-entries-hook' only runs once, for the main diary file."
   :type 'hook
   :options '(diary-mark-included-diary-files)
   :group 'diary)
@@ -238,7 +251,11 @@ As the files are processed for diary entries, these functions are used
 to cull relevant entries.  You can use any or all of
 `diary-bahai-list-entries', `diary-hebrew-list-entries', and
 `diary-islamic-list-entries'.  The documentation for these functions
-describes the style of such diary entries."
+describes the style of such diary entries.
+
+You can use this hook for other functions as well, if you want them to
+be run on the main diary file and any included diary files.  Otherwise,
+use `diary-list-entries-hook', which runs only for the main diary file."
   :type 'hook
   :options '(diary-bahai-list-entries
              diary-hebrew-list-entries
@@ -254,7 +271,11 @@ As the files are processed for diary entries, these functions are used
 to cull relevant entries.  You can use any or all of
 `diary-bahai-mark-entries', `diary-hebrew-mark-entries' and
 `diary-islamic-mark-entries'.  The documentation for these functions
-describes the style of such diary entries."
+describes the style of such diary entries.
+
+You can use this hook for other functions as well, if you want them to
+be run on the main diary file and any included diary files.  Otherwise,
+use `diary-mark-entries-hook', which runs only for the main diary file."
   :type 'hook
   :options '(diary-bahai-mark-entries
              diary-hebrew-mark-entries
@@ -757,12 +778,11 @@ of the appropriate type."
 (defvar diary-included-files nil
   "List of any diary files included in the last call to `diary-list-entries'.")
 
-;; FIXME non-greg and list hooks run same number of times?
 (defun diary-list-entries (date number &optional list-only)
   "Create and display a buffer containing the relevant lines in `diary-file'.
-The arguments are DATE and NUMBER; the entries selected are those
-for NUMBER days starting with date DATE.  The other entries are hidden
-using overlays.  If NUMBER is less than 1, this function does nothing.
+Selects entries for NUMBER days starting with date DATE.  Hides any
+other entries using overlays.  If NUMBER is less than 1, this function
+does nothing.
 
 Returns a list of all relevant diary entries found.
 The list entries have the form ((MONTH DAY YEAR) STRING SPECIFIER) where
@@ -771,30 +791,30 @@ 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.
 
-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
+If producing entries 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'.
+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:
+After preparing the initial list, hooks run in this order:
 
-  `diary-nongregorian-listing-hook' can cull dates from the diary
-      and each included file, for example to process Islamic diary
-      entries.  Applied to *each* file.
+  `diary-nongregorian-listing-hook' runs for the main diary file,
+      and each included file.  For example, this is the appropriate hook
+      to process Islamic entries in all diary files.
 
-  `diary-list-entries-hook' adds or manipulates diary entries from
-      external sources.  Used, for example, to include diary entries
-      from other files or to sort the diary entries.  Invoked *once*
-      only, before the display hook is run.
+  `diary-list-entries-hook' runs once only, for the main diary file.
+      For example, this is appropriate for sorting all the entries.
+      If not using include files, there is no difference from the previous
+      hook.
 
-  `diary-hook' is run last, after the diary is displayed.
+  `diary-hook' runs last, after the diary is displayed.
       This is used e.g. by `appt-check'.
 
 Functions called by these hooks may use the variables ORIGINAL-DATE
@@ -867,8 +887,17 @@ LIST-ONLY is non-nil, in which case it just returns the list."
                               (calendar-gregorian-from-absolute
                                (1+ (calendar-absolute-from-gregorian date)))))))
                   (goto-char (point-min))
+                  ;; Although it looks like list-entries-hook runs
+                  ;; every time, diary-include-other-diary-files
+                  ;; binds it to nil (essentially) when it runs
+                  ;; in included files.
                   (run-hooks 'diary-nongregorian-listing-hook
                              'diary-list-entries-hook)
+                  ;; We could make this explicit:
+                  ;;; (run-hooks 'diary-nongregorian-listing-hook)
+                  ;;; (if d-incp
+                  ;;;     (diary-include-other-diary-files) ; recurse
+                  ;;;   (run-hooks 'diary-list-entries-hook))
                   (unless list-only
                     (if (and diary-display-function
                              (listp diary-display-function))
@@ -893,14 +922,13 @@ LIST-ONLY is non-nil, in which case it just returns the list."
 ;(defvar number)                         ; already declared above
 
 (defun diary-include-other-diary-files ()
-  "Include the diary entries from other diary files with those of `diary-file'.
-This function is suitable for use with `diary-list-entries-hook';
-it enables you to use shared diary files together with your own.
-The files included are specified in the `diary-file' by lines of this form:
-        #include \"filename\"
-This is recursive; that is, #include directives in diary files thus included
-are obeyed.  You can change the `#include' to some other string by changing
-the variable `diary-include-string'."
+  "Add diary entries from included diary files to `diary-entries-list'.
+For example, this enables you to share common diary files.
+To use, add this function to `diary-list-entries-hook'.
+Specify include files using lines matching `diary-include-string', e.g.
+    #include \"filename\"
+This is recursive; that is, included files may include other files.
+See also `diary-mark-included-diary-files'."
   (goto-char (point-min))
   (while (re-search-forward
           (format "^%s \"\\([^\"]*\\)\"" (regexp-quote diary-include-string))
@@ -1350,13 +1378,18 @@ function that converts absolute dates to dates of the appropriate type.  "
 ;;;###cal-autoload
 (defun diary-mark-entries (&optional redraw)
   "Mark days in the calendar window that have diary entries.
-Each entry in the diary file visible in the calendar window is
-marked.  After the entries are marked, the hooks
-`diary-nongregorian-marking-hook' and `diary-mark-entries-hook'
-are run.  If the optional argument REDRAW is non-nil (which is
-the case interactively, for example) then any existing diary
-marks are first removed.  This is intended to deal with deleted
-diary entries."
+Marks each entry in the diary that is visible in the calendar window.
+
+After marking the entries, runs `diary-nongregorian-marking-hook'
+for the main diary file, and each included file.  For example,
+this is the appropriate hook to process Islamic entries in all
+diary files.  Next `diary-mark-entries-hook' runs, for the main diary
+file only.  If not using include files, there is no difference between
+these two hooks.
+
+If the optional argument REDRAW is non-nil (which is the case
+interactively, for example) then this first removes any existing diary
+marks.  This is intended to deal with deleted diary entries."
   (interactive "p")
   ;; To remove any deleted diary entries. Do not redraw when:
   ;; i) processing #include diary files (else only get the marks from
@@ -1378,6 +1411,9 @@ diary entries."
         (with-syntax-table diary-syntax-table
           (diary-mark-entries-1 'calendar-mark-date-pattern)
           (diary-mark-sexp-entries)
+          ;; Although it looks like mark-entries-hook runs every time,
+          ;; diary-mark-included-diary-files binds it to nil
+          ;; (essentially) when it runs in included files.
           (run-hooks 'diary-nongregorian-marking-hook
                      'diary-mark-entries-hook))
         (message "Marking diary entries...done")))))
@@ -1463,14 +1499,13 @@ is marked.  See the documentation for the function `diary-list-sexp-entries'."
   'diary-mark-sexp-entries "23.1")
 
 (defun diary-mark-included-diary-files ()
-  "Mark the diary entries from other diary files with those of the diary file.
-This function is suitable for use with `diary-mark-entries-hook'; it enables
-you to use shared diary files together with your own.  The files included are
-specified in the `diary-file' by lines of this form:
-        #include \"filename\"
-This is recursive; that is, #include directives in diary files thus included
-are obeyed.  You can change the `#include' to some other string by changing
-the variable `diary-include-string'."
+  "Mark diary entries from included diary files.
+For example, this enables you to share common diary files.
+To use, add this function to `diary-mark-entries-hook'.
+Specify include files using lines matching `diary-include-string', e.g.
+    #include \"filename\"
+This is recursive; that is, included files may include other files.
+See also `diary-include-other-diary-files'."
   (goto-char (point-min))
   (while (re-search-forward
           (format "^%s \"\\([^\"]*\\)\"" (regexp-quote diary-include-string))