procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

diary-lib.el doc fixes.

Browse source 
* 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.
This commit is contained in:
Glenn Morris 2011-05-09 19:22:55 -07:00
parent 84f29e6bd8
commit 4f99f44b34
2 changed files with 90 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

8
lisp/ChangeLog
View file

@ -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.

129
lisp/calendar/diary-lib.el
View file

@ -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))