/[emacs]/emacs/man/emacs-xtra.texi
ViewVC logotype

Diff of /emacs/man/emacs-xtra.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.8 by kfstorm, Wed Feb 9 15:50:35 2005 UTC revision 1.9 by gm, Sat Mar 26 17:45:40 2005 UTC
# Line 10  Line 10 
10  @copying  @copying
11  This manual describes specialized features of Emacs.  This manual describes specialized features of Emacs.
12    
13  Copyright (C) 2004  Copyright (C) 2004, 2005
14  Free Software Foundation, Inc.  Free Software Foundation, Inc.
15    
16  @quotation  @quotation
# Line 59  license to the document, as described in Line 59  license to the document, as described in
59  * Introduction::                  What documentation belongs here?  * Introduction::                  What documentation belongs here?
60  * Autorevert::                    Auto Reverting non-file buffers.  * Autorevert::                    Auto Reverting non-file buffers.
61  * Subdir switches::               Subdirectory switches in Dired.  * Subdir switches::               Subdirectory switches in Dired.
62    * Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
63  * Index::  * Index::
64  @end menu  @end menu
65    
# Line 307  You can make Dired forget about all subd Line 308  You can make Dired forget about all subd
308  all subdirectories with the buffer's default switches using  all subdirectories with the buffer's default switches using
309  @kbd{M-x dired-reset-subdir-switches}.  This also reverts the Dired buffer.  @kbd{M-x dired-reset-subdir-switches}.  This also reverts the Dired buffer.
310    
311    
312    @c Moved here from the Emacs Lisp Reference Manual, 2005-03-26.
313    @node Advanced Calendar/Diary Usage
314    @chapter Customizing the Calendar and Diary
315    
316      There are many customizations that you can use to make the calendar and
317    diary suit your personal tastes.
318    
319    @menu
320    * Calendar Customizing::   Defaults you can set.
321    * Holiday Customizing::    Defining your own holidays.
322    * Date Display Format::    Changing the format.
323    * Time Display Format::    Changing the format.
324    * Daylight Savings::       Changing the default.
325    * Diary Customizing::      Defaults you can set.
326    * Hebrew/Islamic Entries:: How to obtain them.
327    * Fancy Diary Display::    Enhancing the diary display, sorting entries,
328                                 using included diary files.
329    * Sexp Diary Entries::     Fancy things you can do.
330    * Appt Customizing::       Customizing appointment reminders.
331    @end menu
332    
333    @node Calendar Customizing
334    @section Customizing the Calendar
335    @vindex view-diary-entries-initially
336    
337      If you set the variable @code{view-diary-entries-initially} to
338    @code{t}, calling up the calendar automatically displays the diary
339    entries for the current date as well.  The diary dates appear only if
340    the current date is visible.  If you add both of the following lines to
341    your init file:@refill
342    
343    @example
344    (setq view-diary-entries-initially t)
345    (calendar)
346    @end example
347    
348    @noindent
349    this displays both the calendar and diary windows whenever you start Emacs.
350    
351    @vindex view-calendar-holidays-initially
352      Similarly, if you set the variable
353    @code{view-calendar-holidays-initially} to @code{t}, entering the
354    calendar automatically displays a list of holidays for the current
355    three-month period.  The holiday list appears in a separate
356    window.
357    
358    @vindex mark-diary-entries-in-calendar
359      You can set the variable @code{mark-diary-entries-in-calendar} to
360    @code{t} in order to mark any dates with diary entries.  This takes
361    effect whenever the calendar window contents are recomputed.  There are
362    two ways of marking these dates: by changing the face
363    (@pxref{Faces,,, elisp, the Emacs Lisp Reference Manual}), or by placing
364    a plus sign (@samp{+}) beside the date.
365    
366    @vindex mark-holidays-in-calendar
367      Similarly, setting the variable @code{mark-holidays-in-calendar} to
368    @code{t} marks holiday dates, either with a change of face or with an
369    asterisk (@samp{*}).
370    
371    @vindex calendar-holiday-marker
372    @vindex diary-entry-marker
373      The variable @code{calendar-holiday-marker} specifies how to mark a
374    date as being a holiday.  Its value may be a single-character string
375    to insert next to the date, or a face name to use for displaying the
376    date.  Likewise, the variable @code{diary-entry-marker} specifies how
377    to mark a date that has diary entries.  The calendar creates faces
378    named @code{holiday-face} and @code{diary-face} for these purposes;
379    those symbols are the default values of these variables.
380    
381    @vindex calendar-load-hook
382      The variable @code{calendar-load-hook} is a normal hook run when the
383    calendar package is first loaded (before actually starting to display
384    the calendar).
385    
386    @vindex initial-calendar-window-hook
387      Starting the calendar runs the normal hook
388    @code{initial-calendar-window-hook}.  Recomputation of the calendar
389    display does not run this hook.  But if you leave the calendar with the
390    @kbd{q} command and reenter it, the hook runs again.@refill
391    
392    @vindex today-visible-calendar-hook
393      The variable @code{today-visible-calendar-hook} is a normal hook run
394    after the calendar buffer has been prepared with the calendar when the
395    current date is visible in the window.  One use of this hook is to
396    replace today's date with asterisks; to do that, use the hook function
397    @code{calendar-star-date}.
398    
399    @findex calendar-star-date
400    @example
401    (add-hook 'today-visible-calendar-hook 'calendar-star-date)
402    @end example
403    
404    @noindent
405    Another standard hook function marks the current date, either by
406    changing its face or by adding an asterisk.  Here's how to use it:
407    
408    @findex calendar-mark-today
409    @example
410    (add-hook 'today-visible-calendar-hook 'calendar-mark-today)
411    @end example
412    
413    @noindent
414    @vindex calendar-today-marker
415    The variable @code{calendar-today-marker} specifies how to mark
416    today's date.  Its value should be a single-character string to insert
417    next to the date or a face name to use for displaying the date.  A
418    face named @code{calendar-today-face} is provided for this purpose;
419    that symbol is the default for this variable.
420    
421    @vindex today-invisible-calendar-hook
422    @noindent
423      A similar normal hook, @code{today-invisible-calendar-hook} is run if
424    the current date is @emph{not} visible in the window.
425    
426    @vindex calendar-move-hook
427      Each of the calendar cursor motion commands runs the hook
428    @code{calendar-move-hook} after it moves the cursor.
429    
430    @node Holiday Customizing
431    @section Customizing the Holidays
432    
433    @vindex calendar-holidays
434    @vindex christian-holidays
435    @vindex hebrew-holidays
436    @vindex islamic-holidays
437      Emacs knows about holidays defined by entries on one of several lists.
438    You can customize these lists of holidays to your own needs, adding or
439    deleting holidays.  The lists of holidays that Emacs uses are for
440    general holidays (@code{general-holidays}), local holidays
441    (@code{local-holidays}), Christian holidays (@code{christian-holidays}),
442    Hebrew (Jewish) holidays (@code{hebrew-holidays}), Islamic (Muslim)
443    holidays (@code{islamic-holidays}), and other holidays
444    (@code{other-holidays}).
445    
446    @vindex general-holidays
447      The general holidays are, by default, holidays common throughout the
448    United States.  To eliminate these holidays, set @code{general-holidays}
449    to @code{nil}.
450    
451    @vindex local-holidays
452      There are no default local holidays (but sites may supply some).  You
453    can set the variable @code{local-holidays} to any list of holidays, as
454    described below.
455    
456    @vindex all-christian-calendar-holidays
457    @vindex all-hebrew-calendar-holidays
458    @vindex all-islamic-calendar-holidays
459      By default, Emacs does not include all the holidays of the religions
460    that it knows, only those commonly found in secular calendars.  For a
461    more extensive collection of religious holidays, you can set any (or
462    all) of the variables @code{all-christian-calendar-holidays},
463    @code{all-hebrew-calendar-holidays}, or
464    @code{all-islamic-calendar-holidays} to @code{t}.  If you want to
465    eliminate the religious holidays, set any or all of the corresponding
466    variables @code{christian-holidays}, @code{hebrew-holidays}, and
467    @code{islamic-holidays} to @code{nil}.@refill
468    
469    @vindex other-holidays
470      You can set the variable @code{other-holidays} to any list of
471    holidays.  This list, normally empty, is intended for individual use.
472    
473    @cindex holiday forms
474      Each of the lists (@code{general-holidays}, @code{local-holidays},
475    @code{christian-holidays}, @code{hebrew-holidays},
476    @code{islamic-holidays}, and @code{other-holidays}) is a list of
477    @dfn{holiday forms}, each holiday form describing a holiday (or
478    sometimes a list of holidays).
479    
480      Here is a table of the possible kinds of holiday form.  Day numbers
481    and month numbers count starting from 1, but ``dayname'' numbers
482    count Sunday as 0.  The element @var{string} is always the
483    name of the holiday, as a string.
484    
485    @table @code
486    @item (holiday-fixed @var{month} @var{day} @var{string})
487    A fixed date on the Gregorian calendar.
488    
489    @item (holiday-float @var{month} @var{dayname} @var{k} @var{string})
490    The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar
491    (@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back
492    from the end of the month.
493    
494    @item (holiday-hebrew @var{month} @var{day} @var{string})
495    A fixed date on the Hebrew calendar.
496    
497    @item (holiday-islamic @var{month} @var{day} @var{string})
498    A fixed date on the Islamic calendar.
499    
500    @item (holiday-julian @var{month} @var{day} @var{string})
501    A fixed date on the Julian calendar.
502    
503    @item (holiday-sexp @var{sexp} @var{string})
504    A date calculated by the Lisp expression @var{sexp}.  The expression
505    should use the variable @code{year} to compute and return the date of a
506    holiday, or @code{nil} if the holiday doesn't happen this year.  The
507    value of @var{sexp} must represent the date as a list of the form
508    @code{(@var{month} @var{day} @var{year})}.
509    
510    @item (if @var{condition} @var{holiday-form})
511    A holiday that happens only if @var{condition} is true.
512    
513    @item (@var{function} @r{[}@var{args}@r{]})
514    A list of dates calculated by the function @var{function}, called with
515    arguments @var{args}.
516    @end table
517    
518      For example, suppose you want to add Bastille Day, celebrated in
519    France on July 14.  You can do this as follows:
520    
521    @smallexample
522    (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
523    @end smallexample
524    
525    @noindent
526    The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the
527    fourteenth day of the seventh month (July).
528    
529      Many holidays occur on a specific day of the week, at a specific time
530    of month.  Here is a holiday form describing Hurricane Supplication Day,
531    celebrated in the Virgin Islands on the fourth Monday in August:
532    
533    @smallexample
534    (holiday-float 8 1 4 "Hurricane Supplication Day")
535    @end smallexample
536    
537    @noindent
538    Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
539    Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
540    the month (1 specifies the first occurrence, 2 the second occurrence,
541    @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and
542    so on).
543    
544      You can specify holidays that occur on fixed days of the Hebrew,
545    Islamic, and Julian calendars too.  For example,
546    
547    @smallexample
548    (setq other-holidays
549          '((holiday-hebrew 10 2 "Last day of Hanukkah")
550            (holiday-islamic 3 12 "Mohammed's Birthday")
551            (holiday-julian 4 2 "Jefferson's Birthday")))
552    @end smallexample
553    
554    @noindent
555    adds the last day of Hanukkah (since the Hebrew months are numbered with
556    1 starting from Nisan), the Islamic feast celebrating Mohammed's
557    birthday (since the Islamic months are numbered from 1 starting with
558    Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
559    Julian calendar.
560    
561      To include a holiday conditionally, use either Emacs Lisp's @code{if} or the
562    @code{holiday-sexp} form.  For example, American presidential elections
563    occur on the first Tuesday after the first Monday in November of years
564    divisible by 4:
565    
566    @smallexample
567    (holiday-sexp '(if (= 0 (% year 4))
568                       (calendar-gregorian-from-absolute
569                        (1+ (calendar-dayname-on-or-before
570                              1 (+ 6 (calendar-absolute-from-gregorian
571                                      (list 11 1 year)))))))
572                  "US Presidential Election")
573    @end smallexample
574    
575    @noindent
576    or
577    
578    @smallexample
579    (if (= 0 (% displayed-year 4))
580        (fixed 11
581               (extract-calendar-day
582                 (calendar-gregorian-from-absolute
583                   (1+ (calendar-dayname-on-or-before
584                         1 (+ 6 (calendar-absolute-from-gregorian
585                                  (list 11 1 displayed-year)))))))
586               "US Presidential Election"))
587    @end smallexample
588    
589      Some holidays just don't fit into any of these forms because special
590    calculations are involved in their determination.  In such cases you
591    must write a Lisp function to do the calculation.  To include eclipses,
592    for example, add @code{(eclipses)} to @code{other-holidays}
593    and write an Emacs Lisp function @code{eclipses} that returns a
594    (possibly empty) list of the relevant Gregorian dates among the range
595    visible in the calendar window, with descriptive strings, like this:
596    
597    @smallexample
598    (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
599    @end smallexample
600    
601    @node Date Display Format
602    @section Date Display Format
603    @vindex calendar-date-display-form
604    
605      You can customize the manner of displaying dates in the diary, in mode
606    lines, and in messages by setting @code{calendar-date-display-form}.
607    This variable holds a list of expressions that can involve the variables
608    @code{month}, @code{day}, and @code{year}, which are all numbers in
609    string form, and @code{monthname} and @code{dayname}, which are both
610    alphabetic strings.  In the American style, the default value of this
611    list is as follows:
612    
613    @smallexample
614    ((if dayname (concat dayname ", ")) monthname " " day ", " year)
615    @end smallexample
616    
617    @noindent
618    while in the European style this value is the default:
619    
620    @smallexample
621    ((if dayname (concat dayname ", ")) day " " monthname " " year)
622    @end smallexample
623    
624    @noindent
625    The ISO standard date representation is this:
626    
627    @smallexample
628    (year "-" month "-" day)
629    @end smallexample
630    
631    @noindent
632    This specifies a typical American format:
633    
634    @smallexample
635    (month "/" day "/" (substring year -2))
636    @end smallexample
637    
638    @node Time Display Format
639    @section Time Display Format
640    @vindex calendar-time-display-form
641    
642      The calendar and diary by default display times of day in the
643    conventional American style with the hours from 1 through 12, minutes,
644    and either @samp{am} or @samp{pm}.  If you prefer the European style,
645    also known in the US as military, in which the hours go from 00 to 23,
646    you can alter the variable @code{calendar-time-display-form}.  This
647    variable is a list of expressions that can involve the variables
648    @code{12-hours}, @code{24-hours}, and @code{minutes}, which are all
649    numbers in string form, and @code{am-pm} and @code{time-zone}, which are
650    both alphabetic strings.  The default value of
651    @code{calendar-time-display-form} is as follows:
652    
653    @smallexample
654    (12-hours ":" minutes am-pm
655              (if time-zone " (") time-zone (if time-zone ")"))
656    @end smallexample
657    
658    @noindent
659    Here is a value that provides European style times:
660    
661    @smallexample
662    (24-hours ":" minutes
663              (if time-zone " (") time-zone (if time-zone ")"))
664    @end smallexample
665    
666    @node Daylight Savings
667    @section Daylight Savings Time
668    @cindex daylight savings time
669    
670      Emacs understands the difference between standard time and daylight
671    savings time---the times given for sunrise, sunset, solstices,
672    equinoxes, and the phases of the moon take that into account.  The rules
673    for daylight savings time vary from place to place and have also varied
674    historically from year to year.  To do the job properly, Emacs needs to
675    know which rules to use.
676    
677      Some operating systems keep track of the rules that apply to the place
678    where you are; on these systems, Emacs gets the information it needs
679    from the system automatically.  If some or all of this information is
680    missing, Emacs fills in the gaps with the rules currently used in
681    Cambridge, Massachusetts, which is the center of GNU's world.
682    
683    
684    @vindex calendar-daylight-savings-starts
685    @vindex calendar-daylight-savings-ends
686      If the default choice of rules is not appropriate for your location,
687    you can tell Emacs the rules to use by setting the variables
688    @code{calendar-daylight-savings-starts} and
689    @code{calendar-daylight-savings-ends}.  Their values should be Lisp
690    expressions that refer to the variable @code{year}, and evaluate to the
691    Gregorian date on which daylight savings time starts or (respectively)
692    ends, in the form of a list @code{(@var{month} @var{day} @var{year})}.
693    The values should be @code{nil} if your area does not use daylight
694    savings time.
695    
696      Emacs uses these expressions to determine the start and end dates of
697    daylight savings time as holidays and for correcting times of day in the
698    solar and lunar calculations.
699    
700      The values for Cambridge, Massachusetts are as follows:
701    
702    @example
703    @group
704    (calendar-nth-named-day 1 0 4 year)
705    (calendar-nth-named-day -1 0 10 year)
706    @end group
707    @end example
708    
709    @noindent
710    i.e., the first 0th day (Sunday) of the fourth month (April) in
711    the year specified by @code{year}, and the last Sunday of the tenth month
712    (October) of that year.  If daylight savings time were
713    changed to start on October 1, you would set
714    @code{calendar-daylight-savings-starts} to this:
715    
716    @example
717    (list 10 1 year)
718    @end example
719    
720      For a more complex example, suppose daylight savings time begins on
721    the first of Nisan on the Hebrew calendar.  You should set
722    @code{calendar-daylight-savings-starts} to this value:
723    
724    @example
725    (calendar-gregorian-from-absolute
726      (calendar-absolute-from-hebrew
727        (list 1 1 (+ year 3760))))
728    @end example
729    
730    @noindent
731    because Nisan is the first month in the Hebrew calendar and the Hebrew
732    year differs from the Gregorian year by 3760 at Nisan.
733    
734      If there is no daylight savings time at your location, or if you want
735    all times in standard time, set @code{calendar-daylight-savings-starts}
736    and @code{calendar-daylight-savings-ends} to @code{nil}.
737    
738    @vindex calendar-daylight-time-offset
739      The variable @code{calendar-daylight-time-offset} specifies the
740    difference between daylight savings time and standard time, measured in
741    minutes.  The value for Cambridge is 60.
742    
743    @vindex calendar-daylight-savings-starts-time
744    @vindex calendar-daylight-savings-ends-time
745      The variable @code{calendar-daylight-savings-starts-time} and the
746    variable @code{calendar-daylight-savings-ends-time} specify the number
747    of minutes after midnight local time when the transition to and from
748    daylight savings time should occur.  For Cambridge, both variables'
749    values are 120.
750    
751    @node Diary Customizing
752    @section Customizing the Diary
753    
754    @vindex holidays-in-diary-buffer
755      Ordinarily, the mode line of the diary buffer window indicates any
756    holidays that fall on the date of the diary entries.  The process of
757    checking for holidays can take several seconds, so including holiday
758    information delays the display of the diary buffer noticeably.  If you'd
759    prefer to have a faster display of the diary buffer but without the
760    holiday information, set the variable @code{holidays-in-diary-buffer} to
761    @code{nil}.@refill
762    
763    @vindex number-of-diary-entries
764      The variable @code{number-of-diary-entries} controls the number of
765    days of diary entries to be displayed at one time.  It affects the
766    initial display when @code{view-diary-entries-initially} is @code{t}, as
767    well as the command @kbd{M-x diary}.  For example, the default value is
768    1, which says to display only the current day's diary entries.  If the
769    value is 2, both the current day's and the next day's entries are
770    displayed.  The value can also be a vector of seven elements: for
771    example, if the value is @code{[0 2 2 2 2 4 1]} then no diary entries
772    appear on Sunday, the current date's and the next day's diary entries
773    appear Monday through Thursday, Friday through Monday's entries appear
774    on Friday, while on Saturday only that day's entries appear.
775    
776    @vindex print-diary-entries-hook
777    @findex print-diary-entries
778      The variable @code{print-diary-entries-hook} is a normal hook run
779    after preparation of a temporary buffer containing just the diary
780    entries currently visible in the diary buffer.  (The other, irrelevant
781    diary entries are really absent from the temporary buffer; in the diary
782    buffer, they are merely hidden.)  The default value of this hook does
783    the printing with the command @code{lpr-buffer}.  If you want to use a
784    different command to do the printing, just change the value of this
785    hook.  Other uses might include, for example, rearranging the lines into
786    order by day and time.
787    
788    @vindex diary-date-forms
789      You can customize the form of dates in your diary file, if neither the
790    standard American nor European styles suits your needs, by setting the
791    variable @code{diary-date-forms}.  This variable is a list of patterns
792    for recognizing a date.  Each date pattern is a list whose elements may
793    be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs
794    Lisp Reference Manual}) or the symbols @code{month}, @code{day},
795    @code{year}, @code{monthname}, and @code{dayname}.  All these elements
796    serve as patterns that match certain kinds of text in the diary file.
797    In order for the date pattern, as a whole, to match, all of its elements
798    must match consecutively.
799    
800      A regular expression in a date pattern matches in its usual fashion,
801    using the standard syntax table altered so that @samp{*} is a word
802    constituent.
803    
804      The symbols @code{month}, @code{day}, @code{year}, @code{monthname},
805    and @code{dayname} match the month number, day number, year number,
806    month name, and day name of the date being considered.  The symbols that
807    match numbers allow leading zeros; those that match names allow
808    three-letter abbreviations and capitalization.  All the symbols can
809    match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any
810    month'', and so on, it should match regardless of the date being
811    considered.
812    
813      The default value of @code{diary-date-forms} in the American style is
814    this:
815    
816    @example
817    ((month "/" day "[^/0-9]")
818     (month "/" day "/" year "[^0-9]")
819     (monthname " *" day "[^,0-9]")
820     (monthname " *" day ", *" year "[^0-9]")
821     (dayname "\\W"))
822    @end example
823    
824      The date patterns in the list must be @emph{mutually exclusive} and
825    must not match any portion of the diary entry itself, just the date and
826    one character of whitespace.  If, to be mutually exclusive, the pattern
827    must match a portion of the diary entry text---beyond the whitespace
828    that ends the date---then the first element of the date pattern
829    @emph{must} be @code{backup}.  This causes the date recognizer to back
830    up to the beginning of the current word of the diary entry, after
831    finishing the match.  Even if you use @code{backup}, the date pattern
832    must absolutely not match more than a portion of the first word of the
833    diary entry.  The default value of @code{diary-date-forms} in the
834    European style is this list:
835    
836    @example
837    ((day "/" month "[^/0-9]")
838     (day "/" month "/" year "[^0-9]")
839     (backup day " *" monthname "\\W+\\<[^*0-9]")
840     (day " *" monthname " *" year "[^0-9]")
841     (dayname "\\W"))
842    @end example
843    
844    @noindent
845    Notice the use of @code{backup} in the third pattern, because it needs
846    to match part of a word beyond the date itself to distinguish it from
847    the fourth pattern.
848    
849    @node Hebrew/Islamic Entries
850    @section Hebrew- and Islamic-Date Diary Entries
851    
852      Your diary file can have entries based on Hebrew or Islamic dates, as
853    well as entries based on the world-standard Gregorian calendar.
854    However, because recognition of such entries is time-consuming and most
855    people don't use them, you must explicitly enable their use.  If you
856    want the diary to recognize Hebrew-date diary entries, for example,
857    you must do this:
858    
859    @vindex nongregorian-diary-listing-hook
860    @vindex nongregorian-diary-marking-hook
861    @findex list-hebrew-diary-entries
862    @findex mark-hebrew-diary-entries
863    @smallexample
864    (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
865    (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
866    @end smallexample
867    
868    @noindent
869    If you want Islamic-date entries, do this:
870    
871    @findex list-islamic-diary-entries
872    @findex mark-islamic-diary-entries
873    @smallexample
874    (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
875    (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
876    @end smallexample
877    
878      Hebrew- and Islamic-date diary entries have the same formats as
879    Gregorian-date diary entries, except that @samp{H} precedes a Hebrew
880    date and @samp{I} precedes an Islamic date.  Moreover, because the
881    Hebrew and Islamic month names are not uniquely specified by the first
882    three letters, you may not abbreviate them.  For example, a diary entry
883    for the Hebrew date Heshvan 25 could look like this:
884    
885    @smallexample
886    HHeshvan 25 Happy Hebrew birthday!
887    @end smallexample
888    
889    @noindent
890    and would appear in the diary for any date that corresponds to Heshvan 25
891    on the Hebrew calendar.  And here is an Islamic-date diary entry that matches
892    Dhu al-Qada 25:
893    
894    @smallexample
895    IDhu al-Qada 25 Happy Islamic birthday!
896    @end smallexample
897    
898      As with Gregorian-date diary entries, Hebrew- and Islamic-date entries
899    are nonmarking if they are preceded with an ampersand (@samp{&}).
900    
901      Here is a table of commands used in the calendar to create diary entries
902    that match the selected date and other dates that are similar in the Hebrew
903    or Islamic calendar:
904    
905    @table @kbd
906    @item i h d
907    Add a diary entry for the Hebrew date corresponding to the selected date
908    (@code{insert-hebrew-diary-entry}).
909    @item i h m
910    Add a diary entry for the day of the Hebrew month corresponding to the
911    selected date (@code{insert-monthly-hebrew-diary-entry}).  This diary
912    entry matches any date that has the same Hebrew day-within-month as the
913    selected date.
914    @item i h y
915    Add a diary entry for the day of the Hebrew year corresponding to the
916    selected date (@code{insert-yearly-hebrew-diary-entry}).  This diary
917    entry matches any date which has the same Hebrew month and day-within-month
918    as the selected date.
919    @item i i d
920    Add a diary entry for the Islamic date corresponding to the selected date
921    (@code{insert-islamic-diary-entry}).
922    @item i i m
923    Add a diary entry for the day of the Islamic month corresponding to the
924    selected date (@code{insert-monthly-islamic-diary-entry}).
925    @item i i y
926    Add a diary entry for the day of the Islamic year corresponding to the
927    selected date (@code{insert-yearly-islamic-diary-entry}).
928    @end table
929    
930    @findex insert-hebrew-diary-entry
931    @findex insert-monthly-hebrew-diary-entry
932    @findex insert-yearly-hebrew-diary-entry
933    @findex insert-islamic-diary-entry
934    @findex insert-monthly-islamic-diary-entry
935    @findex insert-yearly-islamic-diary-entry
936      These commands work much like the corresponding commands for ordinary
937    diary entries: they apply to the date that point is on in the calendar
938    window, and what they do is insert just the date portion of a diary entry
939    at the end of your diary file.  You must then insert the rest of the
940    diary entry.
941    
942    @node Fancy Diary Display
943    @section Fancy Diary Display
944    @vindex diary-display-hook
945    @findex simple-diary-display
946    
947      Diary display works by preparing the diary buffer and then running the
948    hook @code{diary-display-hook}.  The default value of this hook
949    (@code{simple-diary-display}) hides the irrelevant diary entries and
950    then displays the buffer.  However, if you specify the hook as follows,
951    
952    @cindex diary buffer
953    @findex fancy-diary-display
954    @example
955    (add-hook 'diary-display-hook 'fancy-diary-display)
956    @end example
957    
958    @noindent
959    this enables fancy diary display.  It displays diary entries and
960    holidays by copying them into a special buffer that exists only for the
961    sake of display.  Copying to a separate buffer provides an opportunity
962    to change the displayed text to make it prettier---for example, to sort
963    the entries by the dates they apply to.
964    
965      As with simple diary display, you can print a hard copy of the buffer
966    with @code{print-diary-entries}.  To print a hard copy of a day-by-day
967    diary for a week, position point on Sunday of that week, type
968    @kbd{7 d}, and then do @kbd{M-x print-diary-entries}.  As usual, the
969    inclusion of the holidays slows down the display slightly; you can speed
970    things up by setting the variable @code{holidays-in-diary-buffer} to
971    @code{nil}.
972    
973    @vindex diary-list-include-blanks
974      Ordinarily, the fancy diary buffer does not show days for which there are
975    no diary entries, even if that day is a holiday.  If you want such days to be
976    shown in the fancy diary buffer, set the variable
977    @code{diary-list-include-blanks} to @code{t}.@refill
978    
979    @cindex sorting diary entries
980      If you use the fancy diary display, you can use the normal hook
981    @code{list-diary-entries-hook} to sort each day's diary entries by their
982    time of day.  Here's how:
983    
984    @findex sort-diary-entries
985    @example
986    (add-hook 'list-diary-entries-hook 'sort-diary-entries t)
987    @end example
988    
989    @noindent
990    For each day, this sorts diary entries that begin with a recognizable
991    time of day according to their times.  Diary entries without times come
992    first within each day.
993    
994      Fancy diary display also has the ability to process included diary
995    files.  This permits a group of people to share a diary file for events
996    that apply to all of them.  Lines in the diary file of this form:
997    
998    @smallexample
999    #include "@var{filename}"
1000    @end smallexample
1001    
1002    @noindent
1003    includes the diary entries from the file @var{filename} in the fancy
1004    diary buffer.  The include mechanism is recursive, so that included files
1005    can include other files, and so on; you must be careful not to have a
1006    cycle of inclusions, of course.  Here is how to enable the include
1007    facility:
1008    
1009    @vindex list-diary-entries-hook
1010    @vindex mark-diary-entries-hook
1011    @findex include-other-diary-files
1012    @findex mark-included-diary-files
1013    @smallexample
1014    (add-hook 'list-diary-entries-hook 'include-other-diary-files)
1015    (add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
1016    @end smallexample
1017    
1018    The include mechanism works only with the fancy diary display, because
1019    ordinary diary display shows the entries directly from your diary file.
1020    
1021    @node Sexp Diary Entries
1022    @section Sexp Entries and the Fancy Diary Display
1023    @cindex sexp diary entries
1024    
1025      Sexp diary entries allow you to do more than just have complicated
1026    conditions under which a diary entry applies.  If you use the fancy
1027    diary display, sexp entries can generate the text of the entry depending
1028    on the date itself.  For example, an anniversary diary entry can insert
1029    the number of years since the anniversary date into the text of the
1030    diary entry.  Thus the @samp{%d} in this dairy entry:
1031    
1032    @findex diary-anniversary
1033    @smallexample
1034    %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
1035    @end smallexample
1036    
1037    @noindent
1038    gets replaced by the age, so on October 31, 1990 the entry appears in
1039    the fancy diary buffer like this:
1040    
1041    @smallexample
1042    Arthur's birthday (42 years old)
1043    @end smallexample
1044    
1045    @noindent
1046    If the diary file instead contains this entry:
1047    
1048    @smallexample
1049    %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
1050    @end smallexample
1051    
1052    @noindent
1053    the entry in the fancy diary buffer for October 31, 1990 appears like this:
1054    
1055    @smallexample
1056    Arthur's 42nd birthday
1057    @end smallexample
1058    
1059      Similarly, cyclic diary entries can interpolate the number of repetitions
1060    that have occurred:
1061    
1062    @findex diary-cyclic
1063    @smallexample
1064    %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
1065    @end smallexample
1066    
1067    @noindent
1068    looks like this:
1069    
1070    @smallexample
1071    Renew medication (5th time)
1072    @end smallexample
1073    
1074    @noindent
1075    in the fancy diary display on September 8, 1990.
1076    
1077      There is an early reminder diary sexp that includes its entry in the
1078    diary not only on the date of occurrence, but also on earlier dates.
1079    For example, if you want a reminder a week before your anniversary, you
1080    can use
1081    
1082    @findex diary-remind
1083    @smallexample
1084    %%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary
1085    @end smallexample
1086    
1087    @noindent
1088    and the fancy diary will show
1089    @smallexample
1090    Ed's anniversary
1091    @end smallexample
1092    @noindent
1093    both on December 15 and on December 22.
1094    
1095    @findex diary-date
1096      The function @code{diary-date} applies to dates described by a month,
1097    day, year combination, each of which can be an integer, a list of
1098    integers, or @code{t}. The value @code{t} means all values.  For
1099    example,
1100    
1101    @smallexample
1102    %%(diary-date '(10 11 12) 22 t) Rake leaves
1103    @end smallexample
1104    
1105    @noindent
1106    causes the fancy diary to show
1107    
1108    @smallexample
1109    Rake leaves
1110    @end smallexample
1111    
1112    @noindent
1113    on October 22, November 22, and December 22 of every year.
1114    
1115    @findex diary-float
1116      The function @code{diary-float} allows you to describe diary entries
1117    that apply to dates like the third Friday of November, or the last
1118    Tuesday in April.  The parameters are the @var{month}, @var{dayname},
1119    and an index @var{n}. The entry appears on the @var{n}th @var{dayname}
1120    of @var{month}, where @var{dayname}=0 means Sunday, 1 means Monday, and
1121    so on.  If @var{n} is negative it counts backward from the end of
1122    @var{month}.  The value of @var{month} can be a list of months, a single
1123    month, or @code{t} to specify all months.  You can also use an optional
1124    parameter @var{day} to specify the @var{n}th @var{dayname} of
1125    @var{month} on or after/before @var{day}; the value of @var{day} defaults
1126    to 1 if @var{n} is positive and to the last day of @var{month} if
1127    @var{n} is negative.  For example,
1128    
1129    @smallexample
1130    %%(diary-float t 1 -1) Pay rent
1131    @end smallexample
1132    
1133    @noindent
1134    causes the fancy diary to show
1135    
1136    @smallexample
1137    Pay rent
1138    @end smallexample
1139    
1140    @noindent
1141    on the last Monday of every month.
1142    
1143      The generality of sexp diary entries lets you specify any diary
1144    entry that you can describe algorithmically.  A sexp diary entry
1145    contains an expression that computes whether the entry applies to any
1146    given date.  If its value is non-@code{nil}, the entry applies to that
1147    date; otherwise, it does not.  The expression can use the variable
1148    @code{date} to find the date being considered; its value is a list
1149    (@var{month} @var{day} @var{year}) that refers to the Gregorian
1150    calendar.
1151    
1152      The sexp diary entry applies to a date when the expression's value
1153    is non-@code{nil}, but some values have more specific meanings.  If
1154    the value is a string, that string is a description of the event which
1155    occurs on that date.  The value can also have the form
1156    @code{(@var{mark} . @var{string})}; then @var{mark} specifies how to
1157    mark the date in the calendar, and @var{string} is the description of
1158    the event.  If @var{mark} is a single-character string, that character
1159    appears next to the date in the calendar.  If @var{mark} is a face
1160    name, the date is displayed in that face.  If @var{mark} is
1161    @code{nil}, that specifies no particular highlighting for the date.
1162    
1163      Suppose you get paid on the 21st of the month if it is a weekday, and
1164    on the Friday before if the 21st is on a weekend.  Here is how to write
1165    a sexp diary entry that matches those dates:
1166    
1167    @smallexample
1168    &%%(let ((dayname (calendar-day-of-week date))
1169             (day (car (cdr date))))
1170          (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
1171              (and (memq day '(19 20)) (= dayname 5)))
1172             ) Pay check deposited
1173    @end smallexample
1174    
1175      The following sexp diary entries take advantage of the ability (in the fancy
1176    diary display) to concoct diary entries whose text varies based on the date:
1177    
1178    @findex diary-sunrise-sunset
1179    @findex diary-phases-of-moon
1180    @findex diary-day-of-year
1181    @findex diary-iso-date
1182    @findex diary-julian-date
1183    @findex diary-astro-day-number
1184    @findex diary-hebrew-date
1185    @findex diary-islamic-date
1186    @findex diary-french-date
1187    @findex diary-mayan-date
1188    @table @code
1189    @item %%(diary-sunrise-sunset)
1190    Make a diary entry for the local times of today's sunrise and sunset.
1191    @item %%(diary-phases-of-moon)
1192    Make a diary entry for the phases (quarters) of the moon.
1193    @item %%(diary-day-of-year)
1194    Make a diary entry with today's day number in the current year and the number
1195    of days remaining in the current year.
1196    @item %%(diary-iso-date)
1197    Make a diary entry with today's equivalent ISO commercial date.
1198    @item %%(diary-julian-date)
1199    Make a diary entry with today's equivalent date on the Julian calendar.
1200    @item %%(diary-astro-day-number)
1201    Make a diary entry with today's equivalent astronomical (Julian) day number.
1202    @item %%(diary-hebrew-date)
1203    Make a diary entry with today's equivalent date on the Hebrew calendar.
1204    @item %%(diary-islamic-date)
1205    Make a diary entry with today's equivalent date on the Islamic calendar.
1206    @item %%(diary-french-date)
1207    Make a diary entry with today's equivalent date on the French Revolutionary
1208    calendar.
1209    @item %%(diary-mayan-date)
1210    Make a diary entry with today's equivalent date on the Mayan calendar.
1211    @end table
1212    
1213    @noindent
1214    Thus including the diary entry
1215    
1216    @example
1217    &%%(diary-hebrew-date)
1218    @end example
1219    
1220    @noindent
1221    causes every day's diary display to contain the equivalent date on the
1222    Hebrew calendar, if you are using the fancy diary display.  (With simple
1223    diary display, the line @samp{&%%(diary-hebrew-date)} appears in the
1224    diary for any date, but does nothing particularly useful.)
1225    
1226      These functions can be used to construct sexp diary entries based on
1227    the Hebrew calendar in certain standard ways:
1228    
1229    @cindex rosh hodesh
1230    @findex diary-rosh-hodesh
1231    @cindex parasha, weekly
1232    @findex diary-parasha
1233    @cindex candle lighting times
1234    @findex diary-sabbath-candles
1235    @cindex omer count
1236    @findex diary-omer
1237    @cindex yahrzeits
1238    @findex diary-yahrzeit
1239    @table @code
1240    @item %%(diary-rosh-hodesh)
1241    Make a diary entry that tells the occurrence and ritual announcement of each
1242    new Hebrew month.
1243    @item %%(diary-parasha)
1244    Make a Saturday diary entry that tells the weekly synagogue scripture reading.
1245    @item %%(diary-sabbath-candles)
1246    Make a Friday diary entry that tells the @emph{local time} of Sabbath
1247    candle lighting.
1248    @item %%(diary-omer)
1249    Make a diary entry that gives the omer count, when appropriate.
1250    @item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name}
1251    Make a diary entry marking the anniversary of a date of death.  The date
1252    is the @emph{Gregorian} (civil) date of death.  The diary entry appears
1253    on the proper Hebrew calendar anniversary and on the day before.  (In
1254    the European style, the order of the parameters is changed to @var{day},
1255    @var{month}, @var{year}.)
1256    @end table
1257    
1258      All the functions documented above take an optional argument
1259    @var{mark} which specifies how to mark the date in the calendar display.
1260    If one of these functions decides that it applies to a certain date,
1261    it returns a value that contains @var{mark}.
1262    
1263    @node Appt Customizing
1264    @section Customizing Appointment Reminders
1265    
1266      You can specify exactly how Emacs reminds you of an appointment, and
1267    how far in advance it begins doing so, by setting these variables:
1268    
1269    @vindex appt-message-warning-time
1270    @vindex appt-audible
1271    @vindex appt-visible
1272    @vindex appt-display-mode-line
1273    @vindex appt-msg-window
1274    @vindex appt-display-duration
1275    @vindex appt-disp-window-function
1276    @vindex appt-delete-window-function
1277    @table @code
1278    @item appt-message-warning-time
1279    The time in minutes before an appointment that the reminder begins.  The
1280    default is 12 minutes.
1281    @item appt-audible
1282    If this is non-@code{nil}, Emacs rings the
1283    terminal bell for appointment reminders.  The default is @code{t}.
1284    @item appt-visible
1285    If this is non-@code{nil}, Emacs displays the appointment
1286    message in the echo area.  The default is @code{t}.
1287    @item appt-display-mode-line
1288    If this is non-@code{nil}, Emacs displays the number of minutes
1289    to the appointment on the mode line.  The default is @code{t}.
1290    @item appt-msg-window
1291    If this is non-@code{nil}, Emacs displays the appointment
1292    message in another window.  The default is @code{t}.
1293    @item appt-disp-window-function
1294    This variable holds a function to use to create the other window
1295    for the appointment message.
1296    @item appt-delete-window-function
1297    This variable holds a function to use to get rid of the appointment
1298    message window, when its time is up.
1299    @item appt-display-duration
1300    The number of seconds to display an appointment message.  The default
1301    is 10 seconds.
1302    @end table
1303    
1304    
1305  @node Index  @node Index
1306  @unnumbered Index  @unnumbered Index
1307    

Legend:
Removed from v.1.8  
changed lines
  Added in v.1.9

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26