1 This is ../info/xemacs.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * XEmacs: (xemacs). XEmacs Editor.
9 This file documents the XEmacs editor.
11 Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
12 1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
13 Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided also
21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
22 General Public License" are included exactly as in the original, and
23 provided that the entire resulting derived work is distributed under the
24 terms of a permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above conditions for modified
28 versions, except that the sections entitled "The GNU Manifesto",
29 "Distribution" and "GNU General Public License" may be included in a
30 translation approved by the author instead of in the original English.
33 File: xemacs.info, Node: Holiday Customizing, Next: Date Display Format, Prev: Calendar Customizing, Up: Calendar Customization
35 Customizing the Holidays
36 ........................
38 Emacs knows about holidays defined by entries on one of several
39 lists. You can customize these lists of holidays to your own needs,
40 adding or deleting holidays. The lists of holidays that Emacs uses are
41 for general holidays (`general-holidays'), local holidays
42 (`local-holidays'), Christian holidays (`christian-holidays'), Hebrew
43 (Jewish) holidays (`hebrew-holidays'), Islamic (Moslem) holidays
44 (`islamic-holidays'), and other holidays (`other-holidays').
46 The general holidays are, by default, holidays common throughout the
47 United States. To eliminate these holidays, set `general-holidays' to
50 There are no default local holidays (but sites may supply some). You
51 can set the variable `local-holidays' to any list of holidays, as
54 By default, Emacs does not include all the holidays of the religions
55 that it knows, only those commonly found in secular calendars. For a
56 more extensive collection of religious holidays, you can set any (or
57 all) of the variables `all-christian-calendar-holidays',
58 `all-hebrew-calendar-holidays', or `all-islamic-calendar-holidays' to
59 `t'. If you want to eliminate the religious holidays, set any or all
60 of the corresponding variables `christian-holidays', `hebrew-holidays',
61 and `islamic-holidays' to `nil'.
63 You can set the variable `other-holidays' to any list of holidays.
64 This list, normally empty, is intended for individual use.
66 Each of the lists (`general-holidays', `local-holidays',
67 `christian-holidays', `hebrew-holidays', `islamic-holidays', and
68 `other-holidays') is a list of "holiday forms", each holiday form
69 describing a holiday (or sometimes a list of holidays).
71 Here is a table of the possible kinds of holiday form. Day numbers
72 and month numbers count starting from 1, but "dayname" numbers count
73 Sunday as 0. The element STRING is always the name of the holiday, as
76 `(holiday-fixed MONTH DAY STRING)'
77 A fixed date on the Gregorian calendar. MONTH and DAY are
78 numbers, STRING is the name of the holiday.
80 `(holiday-float MONTH DAYNAME K STRING)'
81 The Kth DAYNAME in MONTH on the Gregorian calendar (DAYNAME=0 for
82 Sunday, and so on); negative K means count back from the end of
83 the month. STRING is the name of the holiday.
85 `(holiday-hebrew MONTH DAY STRING)'
86 A fixed date on the Hebrew calendar. MONTH and DAY are numbers,
87 STRING is the name of the holiday.
89 `(holiday-islamic MONTH DAY STRING)'
90 A fixed date on the Islamic calendar. MONTH and DAY are numbers,
91 STRING is the name of the holiday.
93 `(holiday-julian MONTH DAY STRING)'
94 A fixed date on the Julian calendar. MONTH and DAY are numbers,
95 STRING is the name of the holiday.
97 `(holiday-sexp SEXP STRING)'
98 A date calculated by the Lisp expression SEXP. The expression
99 should use the variable `year' to compute and return the date of a
100 holiday, or `nil' if the holiday doesn't happen this year. The
101 value of SEXP must represent the date as a list of the form
102 `(MONTH DAY YEAR)'. STRING is the name of the holiday.
104 `(if CONDITION HOLIDAY-FORM &optional HOLIDAY-FORM)'
105 A holiday that happens only if CONDITION is true.
108 A list of dates calculated by the function FUNCTION, called with
111 For example, suppose you want to add Bastille Day, celebrated in
112 France on July 14. You can do this by adding the following line to
115 (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
117 The holiday form `(holiday-fixed 7 14 "Bastille Day")' specifies the
118 fourteenth day of the seventh month (July).
120 Many holidays occur on a specific day of the week, at a specific time
121 of month. Here is a holiday form describing Hurricane Supplication Day,
122 celebrated in the Virgin Islands on the fourth Monday in August:
124 (holiday-float 8 1 4 "Hurricane Supplication Day")
126 Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
127 Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
128 the month (1 specifies the first occurrence, 2 the second occurrence,
129 -1 the last occurrence, -2 the second-to-last occurrence, and so on).
131 You can specify holidays that occur on fixed days of the Hebrew,
132 Islamic, and Julian calendars too. For example,
135 '((holiday-hebrew 10 2 "Last day of Hanukkah")
136 (holiday-islamic 3 12 "Mohammed's Birthday")
137 (holiday-julian 4 2 "Jefferson's Birthday")))
139 adds the last day of Hanukkah (since the Hebrew months are numbered with
140 1 starting from Nisan), the Islamic feast celebrating Mohammed's
141 birthday (since the Islamic months are numbered from 1 starting with
142 Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
145 To include a holiday conditionally, use either Emacs Lisp's `if' or
146 the `holiday-sexp' form. For example, American presidential elections
147 occur on the first Tuesday after the first Monday in November of years
150 (holiday-sexp (if (= 0 (% year 4))
151 (calendar-gregorian-from-absolute
152 (1+ (calendar-dayname-on-or-before
153 1 (+ 6 (calendar-absolute-from-gregorian
154 (list 11 1 year))))))
155 "US Presidential Election"))
159 (if (= 0 (% displayed-year 4))
161 (extract-calendar-day
162 (calendar-gregorian-from-absolute
163 (1+ (calendar-dayname-on-or-before
164 1 (+ 6 (calendar-absolute-from-gregorian
165 (list 11 1 displayed-year)))))))
166 "US Presidential Election"))
168 Some holidays just don't fit into any of these forms because special
169 calculations are involved in their determination. In such cases you
170 must write a Lisp function to do the calculation. To include eclipses,
171 for example, add `(eclipses)' to `other-holidays' and write an Emacs
172 Lisp function `eclipses' that returns a (possibly empty) list of the
173 relevant Gregorian dates among the range visible in the calendar
174 window, with descriptive strings, like this:
176 (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
179 File: xemacs.info, Node: Date Display Format, Next: Time Display Format, Prev: Holiday Customizing, Up: Calendar Customization
184 You can customize the manner of displaying dates in the diary, in
185 mode lines, and in messages by setting `calendar-date-display-form'.
186 This variable holds a list of expressions that can involve the variables
187 `month', `day', and `year', which are all numbers in string form, and
188 `monthname' and `dayname', which are both alphabetic strings. In the
189 American style, the default value of this list is as follows:
191 ((if dayname (concat dayname ", ")) monthname " " day ", " year)
193 while in the European style this value is the default:
195 ((if dayname (concat dayname ", ")) day " " monthname " " year)
197 + The ISO standard date representation is this:
199 (year "-" month "-" day)
201 This specifies a typical American format:
203 (month "/" day "/" (substring year -2))
206 File: xemacs.info, Node: Time Display Format, Next: Daylight Savings, Prev: Date Display Format, Up: Calendar Customization
211 The calendar and diary by default display times of day in the
212 conventional American style with the hours from 1 through 12, minutes,
213 and either `am' or `pm'. If you prefer the European style, also known
214 in the US as military, in which the hours go from 00 to 23, you can
215 alter the variable `calendar-time-display-form'. This variable is a
216 list of expressions that can involve the variables `12-hours',
217 `24-hours', and `minutes', which are all numbers in string form, and
218 `am-pm' and `time-zone', which are both alphabetic strings. The
219 default value of `calendar-time-display-form' is as follows:
221 (12-hours ":" minutes am-pm
222 (if time-zone " (") time-zone (if time-zone ")"))
224 Here is a value that provides European style times:
226 (24-hours ":" minutes
227 (if time-zone " (") time-zone (if time-zone ")"))
229 gives military-style times like `21:07 (UT)' if time zone names are
230 defined, and times like `21:07' if they are not.
233 File: xemacs.info, Node: Daylight Savings, Next: Diary Customizing, Prev: Time Display Format, Up: Calendar Customization
235 Daylight Savings Time
236 .....................
238 Emacs understands the difference between standard time and daylight
239 savings time--the times given for sunrise, sunset, solstices,
240 equinoxes, and the phases of the moon take that into account. The rules
241 for daylight savings time vary from place to place and have also varied
242 historically from year to year. To do the job properly, Emacs needs to
243 know which rules to use.
245 Some operating systems keep track of the rules that apply to the
246 place where you are; on these systems, Emacs gets the information it
247 needs from the system automatically. If some or all of this
248 information is missing, Emacs fills in the gaps with the rules
249 currently used in Cambridge, Massachusetts. If the resulting rules are
250 not what you want, you can tell Emacs the rules to use by setting
253 If the default choice of rules is not appropriate for your location,
254 you can tell Emacs the rules to use by setting the variables
255 `calendar-daylight-savings-starts' and
256 `calendar-daylight-savings-ends'. Their values should be Lisp
257 expressions that refer to the variable `year', and evaluate to the
258 Gregorian date on which daylight savings time starts or (respectively)
259 ends, in the form of a list `(MONTH DAY YEAR)'. The values should be
260 `nil' if your area does not use daylight savings time.
262 Emacs uses these expressions to determine the starting date of
263 daylight savings time for the holiday list and for correcting times of
264 day in the solar and lunar calculations.
266 The values for Cambridge, Massachusetts are as follows:
268 (calendar-nth-named-day 1 0 4 year)
269 (calendar-nth-named-day -1 0 10 year)
271 That is, the first 0th day (Sunday) of the fourth month (April) in the
272 year specified by `year', and the last Sunday of the tenth month
273 (October) of that year. If daylight savings time were changed to start
274 on October 1, you would set `calendar-daylight-savings-starts' to this:
278 For a more complex example, suppose daylight savings time begins on
279 the first of Nisan on the Hebrew calendar. You should set
280 `calendar-daylight-savings-starts' to this value:
282 (calendar-gregorian-from-absolute
283 (calendar-absolute-from-hebrew
284 (list 1 1 (+ year 3760))))
286 because Nisan is the first month in the Hebrew calendar and the Hebrew
287 year differs from the Gregorian year by 3760 at Nisan.
289 If there is no daylight savings time at your location, or if you want
290 all times in standard time, set `calendar-daylight-savings-starts' and
291 `calendar-daylight-savings-ends' to `nil'.
293 The variable `calendar-daylight-time-offset' specifies the
294 difference between daylight savings time and standard time, measured in
295 minutes. The value for Cambridge, Massachusetts is 60.
297 The two variables `calendar-daylight-savings-starts-time' and
298 `calendar-daylight-savings-ends-time' specify the number of minutes
299 after midnight local time when the transition to and from daylight
300 savings time should occur. For Cambridge, Massachusetts both variables'
304 File: xemacs.info, Node: Diary Customizing, Next: Hebrew/Islamic Entries, Prev: Daylight Savings, Up: Calendar Customization
306 Customizing the Diary
307 .....................
309 Ordinarily, the mode line of the diary buffer window indicates any
310 holidays that fall on the date of the diary entries. The process of
311 checking for holidays can take several seconds, so including holiday
312 information delays the display of the diary buffer noticeably. If you'd
313 prefer to have a faster display of the diary buffer but without the
314 holiday information, set the variable `holidays-in-diary-buffer' to
317 The variable `number-of-diary-entries' controls the number of days
318 of diary entries to be displayed at one time. It affects the initial
319 display when `view-diary-entries-initially' is `t', as well as the
320 command `M-x diary'. For example, the default value is 1, which says
321 to display only the current day's diary entries. If the value is 2,
322 both the current day's and the next day's entries are displayed. The
323 value can also be a vector of seven elements: for example, if the value
324 is `[0 2 2 2 2 4 1]' then no diary entries appear on Sunday, the
325 current date's and the next day's diary entries appear Monday through
326 Thursday, Friday through Monday's entries appear on Friday, while on
327 Saturday only that day's entries appear.
329 The variable `print-diary-entries-hook' is a normal hook run after
330 preparation of a temporary buffer containing just the diary entries
331 currently visible in the diary buffer. (The other, irrelevant diary
332 entries are really absent from the temporary buffer; in the diary
333 buffer, they are merely hidden.) The default value of this hook does
334 the printing with the command `lpr-buffer'. If you want to use a
335 different command to do the printing, just change the value of this
336 hook. Other uses might include, for example, rearranging the lines into
337 order by day and time.
339 You can customize the form of dates in your diary file, if neither
340 the standard American nor European styles suits your needs, by setting
341 the variable `diary-date-forms'. This variable is a list of patterns
342 for recognizing a date. Each date pattern is a list whose elements may
343 be regular expressions (*note Regexps::) or the symbols `month', `day',
344 `year', `monthname', and `dayname'. All these elements serve as
345 patterns that match certain kinds of text in the diary file. In order
346 for the date pattern, as a whole, to match, all of its elements must
349 A regular expression in a date pattern matches in its usual fashion,
350 using the standard syntax table altered so that `*' is a word
353 The symbols `month', `day', `year', `monthname', and `dayname' match
354 the month number, day number, year number, month name, and day name of
355 the date being considered. The symbols that match numbers allow
356 leading zeros; those that match names allow three-letter abbreviations
357 and capitalization. All the symbols can match `*'; since `*' in a
358 diary entry means "any day", "any month", and so on, it should match
359 regardless of the date being considered.
361 The default value of `diary-date-forms' in the American style is
364 ((month "/" day "[^/0-9]")
365 (month "/" day "/" year "[^0-9]")
366 (monthname " *" day "[^,0-9]")
367 (monthname " *" day ", *" year "[^0-9]")
370 Emacs matches of the diary entries with the date forms is done with the
371 standard syntax table from Fundamental mode (*note Syntax Tables:
372 (lispref)Syntax Tables.), but with the `*' changed so that it is a word
375 The date patterns in the list must be _mutually exclusive_ and must
376 not match any portion of the diary entry itself, just the date and one
377 character of whitespace. If, to be mutually exclusive, the pattern
378 must match a portion of the diary entry text--beyond the whitespace
379 that ends the date--then the first element of the date pattern _must_
380 be `backup'. This causes the date recognizer to back up to the
381 beginning of the current word of the diary entry, after finishing the
382 match. Even if you use `backup', the date pattern must absolutely not
383 match more than a portion of the first word of the diary entry. The
384 default value of `diary-date-forms' in the European style is this list:
386 ((day "/" month "[^/0-9]")
387 (day "/" month "/" year "[^0-9]")
388 (backup day " *" monthname "\\W+\\<[^*0-9]")
389 (day " *" monthname " *" year "[^0-9]")
392 Notice the use of `backup' in the third pattern, because it needs to
393 match part of a word beyond the date itself to distinguish it from the
397 File: xemacs.info, Node: Hebrew/Islamic Entries, Next: Fancy Diary Display, Prev: Diary Customizing, Up: Calendar Customization
399 Hebrew- and Islamic-Date Diary Entries
400 ......................................
402 Your diary file can have entries based on Hebrew or Islamic dates, as
403 well as entries based on the world-standard Gregorian calendar.
404 However, because recognition of such entries is time-consuming and most
405 people don't use them, you must explicitly enable their use. If you
406 want the diary to recognize Hebrew-date diary entries, for example, you
409 (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
410 (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
412 If you want Islamic-date entries, do this:
414 (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
415 (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
417 Hebrew- and Islamic-date diary entries have the same formats as
418 Gregorian-date diary entries, except that `H' precedes a Hebrew date
419 and `I' precedes an Islamic date. Moreover, because the Hebrew and
420 Islamic month names are not uniquely specified by the first three
421 letters, you may not abbreviate them. For example, a diary entry for
422 the Hebrew date Heshvan 25 could look like this:
424 HHeshvan 25 Happy Hebrew birthday!
426 and would appear in the diary for any date that corresponds to Heshvan
427 25 on the Hebrew calendar. And here is Islamic-date diary entry that
428 matches Dhu al-Qada 25:
430 IDhu al-Qada 25 Happy Islamic birthday!
432 and would appear in the diary for any date that corresponds to Dhu
433 al-Qada 25 on the Islamic calendar.
435 As with Gregorian-date diary entries, Hebrew- and Islamic-date
436 entries are nonmarking if they are preceded with an ampersand (`&').
438 Here is a table of commands used in the calendar to create diary
439 entries that match the selected date and other dates that are similar
440 in the Hebrew or Islamic calendar:
443 Add a diary entry for the Hebrew date corresponding to the
444 selected date (`insert-hebrew-diary-entry').
447 Add a diary entry for the day of the Hebrew month corresponding to
448 the selected date (`insert-monthly-hebrew-diary-entry'). This
449 diary entry matches any date that has the same Hebrew
450 day-within-month as the selected date.
453 Add a diary entry for the day of the Hebrew year corresponding to
454 the selected date (`insert-yearly-hebrew-diary-entry'). This diary
455 entry matches any date which has the same Hebrew month and
456 day-within-month as the selected date.
459 Add a diary entry for the Islamic date corresponding to the
460 selected date (`insert-islamic-diary-entry').
463 Add a diary entry for the day of the Islamic month corresponding
464 to the selected date (`insert-monthly-islamic-diary-entry').
467 Add a diary entry for the day of the Islamic year corresponding to
468 the selected date (`insert-yearly-islamic-diary-entry').
470 These commands work much like the corresponding commands for ordinary
471 diary entries: they apply to the date that point is on in the calendar
472 window, and what they do is insert just the date portion of a diary
473 entry at the end of your diary file. You must then insert the rest of
477 File: xemacs.info, Node: Fancy Diary Display, Next: Included Diary Files, Prev: Hebrew/Islamic Entries, Up: Calendar Customization
482 Diary display works by preparing the diary buffer and then running
483 the hook `diary-display-hook'. The default value of this hook
484 (`simple-diary-display') hides the irrelevant diary entries and then
485 displays the buffer. However, if you specify the hook as follows,
487 (add-hook 'diary-display-hook 'fancy-diary-display)
489 this enables fancy diary display. It displays diary entries and
490 holidays by copying them into a special buffer that exists only for the
491 sake of display. Copying to a separate buffer provides an opportunity
492 to change the displayed text to make it prettier--for example, to sort
493 the entries by the dates they apply to.
495 As with simple diary display, you can print a hard copy of the buffer
496 with `print-diary-entries'. To print a hard copy of a day-by-day diary
497 for a week by positioning point on Sunday of that week, type `7 d' and
498 then do `M-x print-diary-entries'. As usual, the inclusion of the
499 holidays slows down the display slightly; you can speed things up by
500 setting the variable `holidays-in-diary-buffer' to `nil'.
502 Ordinarily, the fancy diary buffer does not show days for which
503 there are no diary entries, even if that day is a holiday. If you want
504 such days to be shown in the fancy diary buffer, set the variable
505 `diary-list-include-blanks' to `t'.
507 If you use the fancy diary display, you can use the normal hook
508 `list-diary-entries-hook' to sort each day's diary entries by their
509 time of day. Add this line to your `.emacs' file:
511 (add-hook 'list-diary-entries-hook 'sort-diary-entries t)
513 For each day, this sorts diary entries that begin with a recognizable
514 time of day according to their times. Diary entries without times come
515 first within each day.
518 File: xemacs.info, Node: Included Diary Files, Next: Sexp Diary Entries, Prev: Fancy Diary Display, Up: Calendar Customization
523 Fancy diary display also has the ability to process included diary
524 files. This permits a group of people to share a diary file for events
525 that apply to all of them. Lines in the diary file of this form:
529 includes the diary entries from the file FILENAME in the fancy diary
530 buffer. The include mechanism is recursive, so that included files can
531 include other files, and so on; you must be careful not to have a cycle
532 of inclusions, of course. Here is how to enable the include facility:
534 (add-hook 'list-diary-entries-hook 'include-other-diary-files)
535 (add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
537 The include mechanism works only with the fancy diary display,
538 because ordinary diary display shows the entries directly from your
542 File: xemacs.info, Node: Sexp Diary Entries, Next: Appt Customizing, Prev: Included Diary Files, Up: Calendar Customization
544 Sexp Entries and the Fancy Diary Display
545 ........................................
547 Sexp diary entries allow you to do more than just have complicated
548 conditions under which a diary entry applies. If you use the fancy
549 diary display, sexp entries can generate the text of the entry depending
550 on the date itself. For example, an anniversary diary entry can insert
551 the number of years since the anniversary date into the text of the
552 diary entry. Thus the `%d' in this dairy entry:
554 %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
556 gets replaced by the age, so on October 31, 1990 the entry appears in
557 the fancy diary buffer like this:
559 Arthur's birthday (42 years old)
561 If the diary file instead contains this entry:
563 %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
565 the entry in the fancy diary buffer for October 31, 1990 appears like
568 Arthur's 42nd birthday
570 Similarly, cyclic diary entries can interpolate the number of
571 repetitions that have occurred:
573 %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
577 Renew medication (5th time)
579 in the fancy diary display on September 8, 1990.
581 The generality of sexp diary entries lets you specify any diary entry
582 that you can describe algorithmically. A sexp diary entry contains an
583 expression that computes whether the entry applies to any given date.
584 If its value is non-`nil', the entry applies to that date; otherwise,
585 it does not. The expression can use the variable `date' to find the
586 date being considered; its value is a list (MONTH DAY YEAR) that refers
587 to the Gregorian calendar.
589 Suppose you get paid on the 21st of the month if it is a weekday, and
590 on the Friday before if the 21st is on a weekend. Here is how to write
591 a sexp diary entry that matches those dates:
593 &%%(let ((dayname (calendar-day-of-week date))
594 (day (car (cdr date))))
595 (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
596 (and (memq day '(19 20)) (= dayname 5)))
597 ) Pay check deposited
599 applies to just those dates. This example illustrates how the sexp can
600 depend on the variable `date'; this variable is a list (MONTH DAY YEAR)
601 that gives the Gregorian date for which the diary entries are being
602 found. If the value of the expression is `t', the entry applies to
603 that date. If the expression evaluates to `nil', the entry does _not_
606 The following sexp diary entries take advantage of the ability (in
607 the fancy diary display) to concoct diary entries whose text varies
610 `%%(diary-sunrise-sunset)'
611 Make a diary entry for the local times of today's sunrise and
614 `%%(diary-phases-of-moon)'
615 Make a diary entry for the phases (quarters) of the moon.
617 `%%(diary-day-of-year)'
618 Make a diary entry with today's day number in the current year and
619 the number of days remaining in the current year.
622 Make a diary entry with today's equivalent ISO commercial date.
624 `%%(diary-julian-date)'
625 Make a diary entry with today's equivalent date on the Julian
628 `%%(diary-astro-day-number)'
629 Make a diary entry with today's equivalent astronomical (Julian)
632 `%%(diary-hebrew-date)'
633 Make a diary entry with today's equivalent date on the Hebrew
636 `%%(diary-islamic-date)'
637 Make a diary entry with today's equivalent date on the Islamic
640 `%%(diary-french-date)'
641 Make a diary entry with today's equivalent date on the French
642 Revolutionary calendar.
644 `%%(diary-mayan-date)'
645 Make a diary entry with today's equivalent date on the Mayan
648 Thus including the diary entry
650 &%%(diary-hebrew-date)
652 causes every day's diary display to contain the equivalent date on the
653 Hebrew calendar, if you are using the fancy diary display. (With simple
654 diary display, the line `&%%(diary-hebrew-date)' appears in the diary
655 for any date, but does nothing particularly useful.)
657 These functions can be used to construct sexp diary entries based on
658 the Hebrew calendar in certain standard ways:
660 `%%(diary-rosh-hodesh)'
661 Make a diary entry that tells the occurrence and ritual
662 announcement of each new Hebrew month.
665 Make a Saturday diary entry that tells the weekly synagogue
668 `%%(diary-sabbath-candles)'
669 Make a Friday diary entry that tells the _local time_ of Sabbath
673 Make a diary entry that gives the omer count, when appropriate.
675 `%%(diary-yahrzeit MONTH DAY YEAR) NAME'
676 Make a diary entry marking the anniversary of a date of death.
677 The date is the _Gregorian_ (civil) date of death. The diary
678 entry appears on the proper Hebrew calendar anniversary and on the
679 day before. (In the European style, the order of the parameters
680 is changed to DAY, MONTH, YEAR.)
683 File: xemacs.info, Node: Appt Customizing, Prev: Sexp Diary Entries, Up: Calendar Customization
685 Customizing Appointment Reminders
686 .................................
688 You can specify exactly how Emacs reminds you of an appointment, and
689 how far in advance it begins doing so, by setting these variables:
691 `appt-message-warning-time'
692 The time in minutes before an appointment that the reminder
693 begins. The default is 10 minutes.
696 If this is `t' (the default), Emacs rings the terminal bell for
697 appointment reminders.
700 If this is `t' (the default), Emacs displays the appointment
701 message in echo area.
703 `appt-display-mode-line'
704 If this is `t' (the default), Emacs displays the number of minutes
705 to the appointment on the mode line.
708 If this is `t' (the default), Emacs displays the appointment
709 message in another window.
711 `appt-display-duration'
712 The number of seconds an appointment message is displayed. The
713 default is 5 seconds.
716 File: xemacs.info, Node: Sorting, Next: Shell, Prev: Calendar/Diary, Up: Top
721 XEmacs provides several commands for sorting text in a buffer. All
722 operate on the contents of the region (the text between point and the
723 mark). They divide the text of the region into many "sort records",
724 identify a "sort key" for each record, and then reorder the records
725 using the order determined by the sort keys. The records are ordered so
726 that their keys are in alphabetical order, or, for numerical sorting, in
727 numerical order. In alphabetical sorting, all upper-case letters `A'
728 through `Z' come before lower-case `a', in accordance with the ASCII
731 The sort commands differ in how they divide the text into sort
732 records and in which part of each record they use as the sort key.
733 Most of the commands make each line a separate sort record, but some
734 commands use paragraphs or pages as sort records. Most of the sort
735 commands use each entire sort record as its own sort key, but some use
736 only a portion of the record as the sort key.
739 Divide the region into lines and sort by comparing the entire text
740 of a line. A prefix argument means sort in descending order.
742 `M-x sort-paragraphs'
743 Divide the region into paragraphs and sort by comparing the entire
744 text of a paragraph (except for leading blank lines). A prefix
745 argument means sort in descending order.
748 Divide the region into pages and sort by comparing the entire text
749 of a page (except for leading blank lines). A prefix argument
750 means sort in descending order.
753 Divide the region into lines and sort by comparing the contents of
754 one field in each line. Fields are defined as separated by
755 whitespace, so the first run of consecutive non-whitespace
756 characters in a line constitutes field 1, the second such run
757 constitutes field 2, etc.
759 You specify which field to sort by with a numeric argument: 1 to
760 sort by field 1, etc. A negative argument means sort in descending
761 order. Thus, minus 2 means sort by field 2 in reverse-alphabetical
764 `M-x sort-numeric-fields'
765 Like `M-x sort-fields', except the specified field is converted to
766 a number for each line and the numbers are compared. `10' comes
767 before `2' when considered as text, but after it when considered
771 Like `M-x sort-fields', except that the text within each line used
772 for comparison comes from a fixed range of columns. An explanation
775 For example, if the buffer contains:
777 On systems where clash detection (locking of files being edited) is
778 implemented, XEmacs also checks the first time you modify a buffer
779 whether the file has changed on disk since it was last visited or
780 saved. If it has, you are asked to confirm that you want to change
783 then if you apply `M-x sort-lines' to the entire buffer you get:
785 On systems where clash detection (locking of files being edited) is
786 implemented, XEmacs also checks the first time you modify a buffer
787 saved. If it has, you are asked to confirm that you want to change
789 whether the file has changed on disk since it was last visited or
791 where the upper case `O' comes before all lower case letters. If you
792 apply instead `C-u 2 M-x sort-fields' you get:
794 saved. If it has, you are asked to confirm that you want to change
795 implemented, XEmacs also checks the first time you modify a buffer
797 On systems where clash detection (locking of files being edited) is
798 whether the file has changed on disk since it was last visited or
800 where the sort keys were `If', `XEmacs', `buffer', `systems', and `the'.
802 `M-x sort-columns' requires more explanation. You specify the
803 columns by putting point at one of the columns and the mark at the other
804 column. Because this means you cannot put point or the mark at the
805 beginning of the first line to sort, this command uses an unusual
806 definition of `region': all of the line point is in is considered part
807 of the region, and so is all of the line the mark is in.
809 For example, to sort a table by information found in columns 10 to
810 15, you could put the mark on column 10 in the first line of the table,
811 and point on column 15 in the last line of the table, and then use this
812 command. Or you could put the mark on column 15 in the first line and
813 point on column 10 in the last line.
815 This can be thought of as sorting the rectangle specified by point
816 and the mark, except that the text on each line to the left or right of
817 the rectangle moves along with the text inside the rectangle. *Note
821 File: xemacs.info, Node: Shell, Next: Narrowing, Prev: Sorting, Up: Top
823 Running Shell Commands from XEmacs
824 ==================================
826 XEmacs has commands for passing single command lines to inferior
827 shell processes; it can also run a shell interactively with input and
828 output to an XEmacs buffer `*shell*'.
831 Run a specified shell command line and display the output
835 Run a specified shell command line with region contents as input;
836 optionally replace the region with the output
837 (`shell-command-on-region').
840 Run a subshell with input and output through an XEmacs buffer.
841 You can then give commands interactively.
844 Run a subshell with input and output through an XEmacs buffer.
845 You can then give commands interactively. Full terminal emulation
850 * Single Shell:: How to run one shell command and return.
851 * Interactive Shell:: Permanent shell taking input via XEmacs.
852 * Shell Mode:: Special XEmacs commands used with permanent shell.
853 * Terminal emulator:: An XEmacs window as a terminal emulator.
854 * Term Mode:: Special XEmacs commands used in Term mode.
855 * Paging in Term:: Paging in the terminal emulator.
858 File: xemacs.info, Node: Single Shell, Next: Interactive Shell, Prev: Shell, Up: Shell
860 Single Shell Commands
861 ---------------------
863 `M-!' (`shell-command') reads a line of text using the minibuffer
864 and creates an inferior shell to execute the line as a command.
865 Standard input from the command comes from the null device. If the
866 shell command produces any output, the output goes to an XEmacs buffer
867 named `*Shell Command Output*', which is displayed in another window
868 but not selected. A numeric argument, as in `M-1 M-!', directs this
869 command to insert any output into the current buffer. In that case,
870 point is left before the output and the mark is set after the output.
872 `M-|' (`shell-command-on-region') is like `M-!' but passes the
873 contents of the region as input to the shell command, instead of no
874 input. If a numeric argument is used to direct output to the current
875 buffer, then the old region is deleted first and the output replaces it
876 as the contents of the region.
878 Both `M-!' and `M-|' use `shell-file-name' to specify the shell to
879 use. This variable is initialized based on your `SHELL' environment
880 variable when you start XEmacs. If the file name does not specify a
881 directory, the directories in the list `exec-path' are searched; this
882 list is initialized based on the `PATH' environment variable when you
883 start XEmacs. You can override either or both of these default
884 initializations in your `.emacs' file.
886 When you use `M-!' and `M-|', XEmacs has to wait until the shell
887 command completes. You can quit with `C-g'; that terminates the shell
891 File: xemacs.info, Node: Interactive Shell, Next: Shell Mode, Prev: Single Shell, Up: Shell
893 Interactive Inferior Shell
894 --------------------------
896 To run a subshell interactively with its typescript in an XEmacs
897 buffer, use `M-x shell'. This creates (or reuses) a buffer named
898 `*shell*' and runs a subshell with input coming from and output going
899 to that buffer. That is to say, any "terminal output" from the subshell
900 will go into the buffer, advancing point, and any "terminal input" for
901 the subshell comes from text in the buffer. To give input to the
902 subshell, go to the end of the buffer and type the input, terminated by
905 XEmacs does not wait for the subshell to do anything. You can switch
906 windows or buffers and edit them while the shell is waiting, or while
907 it is running a command. Output from the subshell waits until XEmacs
908 has time to process it; this happens whenever XEmacs is waiting for
909 keyboard input or for time to elapse.
911 To get multiple subshells, change the name of buffer `*shell*' to
912 something different by using `M-x rename-buffer'. The next use of `M-x
913 shell' creates a new buffer `*shell*' with its own subshell. By
914 renaming this buffer as well you can create a third one, and so on.
915 All the subshells run independently and in parallel.
917 The file name used to load the subshell is the value of the variable
918 `explicit-shell-file-name', if that is non-`nil'. Otherwise, the
919 environment variable `ESHELL' is used, or the environment variable
920 `SHELL' if there is no `ESHELL'. If the file name specified is
921 relative, the directories in the list `exec-path' are searched (*note
922 Single Shell Commands: Single Shell.).
924 As soon as the subshell is started, it is sent as input the contents
925 of the file `~/.emacs_SHELLNAME', if that file exists, where SHELLNAME
926 is the name of the file that the shell was loaded from. For example,
927 if you use `csh', the file sent to it is `~/.emacs_csh'.
929 `cd', `pushd', and `popd' commands given to the inferior shell are
930 watched by XEmacs so it can keep the `*shell*' buffer's default
931 directory the same as the shell's working directory. These commands
932 are recognized syntactically by examining lines of input that are sent.
933 If you use aliases for these commands, you can tell XEmacs to
934 recognize them also. For example, if the value of the variable
935 `shell-pushd-regexp' matches the beginning of a shell command line,
936 that line is regarded as a `pushd' command. Change this variable when
937 you add aliases for `pushd'. Likewise, `shell-popd-regexp' and
938 `shell-cd-regexp' are used to recognize commands with the meaning of
941 `M-x shell-resync-dirs' queries the shell and resynchronizes XEmacs'
942 idea of what the current directory stack is. `M-x
943 shell-dirtrack-toggle' turns directory tracking on and off.
945 XEmacs keeps a history of the most recent commands you have typed in
946 the `*shell*' buffer. If you are at the beginning of a shell command
947 line and type <M-p>, the previous shell input is inserted into the
948 buffer before point. Immediately typing <M-p> again deletes that input
949 and inserts the one before it. By repeating <M-p> you can move
950 backward through your commands until you find one you want to repeat.
951 You may then edit the command before typing <RET> if you wish. <M-n>
952 moves forward through the command history, in case you moved backward
953 past the one you wanted while using <M-p>. If you type the first few
954 characters of a previous command and then type <M-p>, the most recent
955 shell input starting with those characters is inserted. This can be
956 very convenient when you are repeating a sequence of shell commands.
957 The variable `input-ring-size' controls how many commands are saved in
958 your input history. The default is 30.
961 File: xemacs.info, Node: Shell Mode, Next: Terminal emulator, Prev: Interactive Shell, Up: Shell
966 The shell buffer uses Shell mode, which defines several special keys
967 attached to the `C-c' prefix. They are chosen to resemble the usual
968 editing and job control characters present in shells that are not under
969 XEmacs, except that you must type `C-c' first. Here is a list of the
970 special key bindings of Shell mode:
973 At end of buffer send line as input; otherwise, copy current line
974 to end of buffer and send it (`send-shell-input'). When a line is
975 copied, any text at the beginning of the line that matches the
976 variable `shell-prompt-pattern' is left out; this variable's value
977 should be a regexp string that matches the prompts that you use in
981 Send end-of-file as input, probably causing the shell or its
982 current subjob to finish (`shell-send-eof').
985 If point is not at the end of the buffer, delete the next
986 character just like most other modes. If point is at the end of
987 the buffer, send end-of-file as input, instead of generating an
988 error as in other modes (`comint-delchar-or-maybe-eof').
991 Kill all text that has yet to be sent as input
992 (`kill-shell-input').
995 Kill a word before point (`backward-kill-word').
998 Interrupt the shell or its current subjob if any
999 (`interrupt-shell-subjob').
1002 Stop the shell or its current subjob if any (`stop-shell-subjob').
1005 Send quit signal to the shell or its current subjob if any
1006 (`quit-shell-subjob').
1009 Delete last batch of output from shell (`kill-output-from-shell').
1012 Scroll top of last batch of output to top of window
1013 (`show-output-from-shell').
1016 Copy the previous bunch of shell input and insert it into the
1017 buffer before point (`copy-last-shell-input'). No final newline
1018 is inserted, and the input copied is not resubmitted until you type
1022 Move backward through the input history. Search for a matching
1023 command if you have typed the beginning of a command
1024 (`comint-previous-input').
1027 Move forward through the input history. Useful when you are using
1028 <M-p> quickly and go past the desired command
1029 (`comint-next-input').
1032 Complete the file name preceding point (`comint-dynamic-complete').
1035 File: xemacs.info, Node: Terminal emulator, Next: Term Mode, Prev: Shell Mode, Up: Shell
1037 Interactive Inferior Shell with Terminal Emulator
1038 -------------------------------------------------
1040 To run a subshell in a terminal emulator, putting its typescript in
1041 an XEmacs buffer, use `M-x term'. This creates (or reuses) a buffer
1042 named `*term*' and runs a subshell with input coming from your keyboard
1043 and output going to that buffer.
1045 All the normal keys that you type are sent without any interpretation
1046 by XEmacs directly to the subshell, as "terminal input." Any "echo" of
1047 your input is the responsibility of the subshell. (The exception is
1048 the terminal escape character, which by default is `C-c'. *note Term
1049 Mode::.) Any "terminal output" from the subshell goes into the buffer,
1052 Some programs (such as XEmacs itself) need to control the appearance
1053 on the terminal screen in detail. They do this by sending special
1054 control codes. The exact control codes needed vary from terminal to
1055 terminal, but nowadays most terminals and terminal emulators (including
1056 xterm) understand the so-called "ANSI escape sequences" (first
1057 popularized by the Digital's VT100 family of terminal). The term mode
1058 also understands these escape sequences, and for each control code does
1059 the appropriate thing to change the buffer so that the appearance of
1060 the window will match what it would be on a real terminal. Thus you
1061 can actually run XEmacs inside an XEmacs Term window!
1063 XEmacs does not wait for the subshell to do anything. You can switch
1064 windows or buffers and edit them while the shell is waiting, or while
1065 it is running a command. Output from the subshell waits until XEmacs
1066 has time to process it; this happens whenever XEmacs is waiting for
1067 keyboard input or for time to elapse.
1069 To make multiple terminal emulators, rename the buffer `*term*' to
1070 something different using `M-x rename-uniquely', just as with Shell
1073 The file name used to load the subshell is determined the same way
1076 Unlike Shell mode, Term mode does not track the current directory by
1077 examining your input. Instead, if you use a programmable shell, you
1078 can have it tell Term what the current directory is. This is done
1079 automatically by bash for version 1.15 and later.
1082 File: xemacs.info, Node: Term Mode, Next: Paging in Term, Prev: Terminal emulator, Up: Shell
1087 Term uses Term mode, which has two input modes: In line mode, Term
1088 basically acts like Shell mode. *Note Shell Mode::. In Char mode,
1089 each character is sent directly to the inferior subshell, except for
1090 the Term escape character, normally `C-c'.
1092 To switch between line and char mode, use these commands:
1093 findex term-char-mode
1096 Switch to line mode. Do nothing if already in line mode.
1099 Switch to char mode. Do nothing if already in char mode.
1101 The following commands are only available in Char mode:
1103 Send a literal <C-c> to the sub-shell.
1106 A prefix command to conveniently access the global <C-x> commands.
1107 For example, `C-c C-x o' invokes the global binding of `C-x o',
1108 which is normally `other-window'.
1111 File: xemacs.info, Node: Paging in Term, Prev: Term Mode, Up: Shell
1113 Paging in the terminal emulator
1114 -------------------------------
1116 Term mode has a pager feature. When the pager is enabled, term mode
1117 will pause at the end of each screenful.
1120 Toggles the pager feature: Disables the pager if it is enabled,
1121 and vice versa. This works in both line and char modes. If the
1122 pager enabled, the mode-line contains the word `page'.
1124 If the pager is enabled, and Term receives more than a screenful of
1125 output since your last input, Term will enter More break mode. This is
1126 indicated by `**MORE**' in the mode-line. Type a `Space' to display
1127 the next screenful of output. Type `?' to see your other options. The
1128 interface is similar to the Unix `more' program.
1131 File: xemacs.info, Node: Narrowing, Next: Hardcopy, Prev: Shell, Up: Top
1136 "Narrowing" means focusing in on some portion of the buffer, making
1137 the rest temporarily invisible and inaccessible. Cancelling the
1138 narrowing and making the entire buffer once again visible is called
1139 "widening". The amount of narrowing in effect in a buffer at any time
1140 is called the buffer's "restriction".
1143 Narrow down to between point and mark (`narrow-to-region').
1146 Widen to make the entire buffer visible again (`widen').
1148 Narrowing sometimes makes it easier to concentrate on a single
1149 subroutine or paragraph by eliminating clutter. It can also be used to
1150 restrict the range of operation of a replace command or repeating
1151 keyboard macro. The word `Narrow' appears in the mode line whenever
1152 narrowing is in effect. When you have narrowed to a part of the
1153 buffer, that part appears to be all there is. You can't see the rest,
1154 can't move into it (motion commands won't go outside the visible part),
1155 and can't change it in any way. However, the invisible text is not
1156 gone; if you save the file, it will be saved.
1158 The primary narrowing command is `C-x n n' (`narrow-to-region'). It
1159 sets the current buffer's restrictions so that the text in the current
1160 region remains visible but all text before the region or after the
1161 region is invisible. Point and mark do not change.
1163 Because narrowing can easily confuse users who do not understand it,
1164 `narrow-to-region' is normally a disabled command. Attempting to use
1165 this command asks for confirmation and gives you the option of enabling
1166 it; once you enable the command, confirmation will no longer be
1167 required. *Note Disabling::.
1169 To undo narrowing, use `C-x n w' (`widen'). This makes all text in
1170 the buffer accessible again.
1172 Use the `C-x =' command to get information on what part of the
1173 buffer you narrowed down. *Note Position Info::.
1176 File: xemacs.info, Node: Hardcopy, Next: Recursive Edit, Prev: Narrowing, Up: Top
1181 The XEmacs commands for making hardcopy derive their names from the
1182 Unix commands `print' and `lpr'.
1185 Print hardcopy of current buffer using Unix command `print'
1186 (`lpr -p'). This command adds page headings containing the file
1187 name and page number.
1190 Print hardcopy of current buffer using Unix command `lpr'. This
1191 command does not add page headings.
1194 Like `print-buffer', but prints only the current region.
1197 Like `lpr-buffer', but prints only the current region.
1199 All the hardcopy commands pass extra switches to the `lpr' program
1200 based on the value of the variable `lpr-switches'. Its value should be
1201 a list of strings, each string a switch starting with `-'. For
1202 example, the value could be `("-Pfoo")' to print on printer `foo'.