1 This is ../info/xemacs.info, produced by makeinfo version 4.8 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: Lisp Eval, Next: Lisp Debug, Prev: Lisp Libraries, Up: Running
35 22.4 Evaluating Emacs-Lisp Expressions
36 ======================================
38 Lisp programs intended to be run in Emacs should be edited in
39 Emacs-Lisp mode; this will happen automatically for file names ending in
40 `.el'. By contrast, Lisp mode itself should be used for editing Lisp
41 programs intended for other Lisp systems. Emacs-Lisp mode can be
42 selected with the command `M-x emacs-lisp-mode'.
44 For testing of Lisp programs to run in Emacs, it is useful to be able
45 to evaluate part of the program as it is found in the Emacs buffer. For
46 example, if you change the text of a Lisp function definition and then
47 evaluate the definition, Emacs installs the change for future calls to
48 the function. Evaluation of Lisp expressions is also useful in any
49 kind of editing task for invoking non-interactive functions (functions
50 that are not commands).
53 Read a Lisp expression in the minibuffer, evaluate it, and print
54 the value in the minibuffer (`eval-expression').
57 Evaluate the Lisp expression before point, and print the value in
58 the minibuffer (`eval-last-sexp').
61 Evaluate the defun containing point or after point, and print the
62 value in the minibuffer (`eval-defun').
65 Evaluate all the Lisp expressions in the region.
67 `M-x eval-current-buffer'
68 Evaluate all the Lisp expressions in the buffer.
70 `M-:' (`eval-expression') is the most basic command for evaluating a
71 Lisp expression interactively. It reads the expression using the
72 minibuffer, so you can execute any expression on a buffer regardless of
73 what the buffer contains. When evaluation is complete, the current
74 buffer is once again the buffer that was current when `M-:' was typed.
76 In Emacs-Lisp mode, the key `C-M-x' is bound to the function
77 `eval-defun', which parses the defun containing point or following point
78 as a Lisp expression and evaluates it. The value is printed in the echo
79 area. This command is convenient for installing in the Lisp environment
80 changes that you have just made in the text of a function definition.
82 The command `C-x C-e' (`eval-last-sexp') performs a similar job but
83 is available in all major modes, not just Emacs-Lisp mode. It finds
84 the sexp before point, reads it as a Lisp expression, evaluates it, and
85 prints the value in the echo area. It is sometimes useful to type in an
86 expression and then, with point still after it, type `C-x C-e'.
88 If `C-M-x' or `C-x C-e' are given a numeric argument, they print the
89 value by inserting it into the current buffer at point, rather than in
90 the echo area. The argument value does not matter.
92 The most general command for evaluating Lisp expressions from a
93 buffer is `eval-region'. `M-x eval-region' parses the text of the
94 region as one or more Lisp expressions, evaluating them one by one.
95 `M-x eval-current-buffer' is similar, but it evaluates the entire
96 buffer. This is a reasonable way to install the contents of a file of
97 Lisp code that you are just ready to test. After finding and fixing a
98 bug, use `C-M-x' on each function that you change, to keep the Lisp
99 world in step with the source file.
102 File: xemacs.info, Node: Lisp Debug, Next: Lisp Interaction, Prev: Lisp Eval, Up: Running
104 22.5 The Emacs-Lisp Debugger
105 ============================
107 XEmacs contains a debugger for Lisp programs executing inside it. This
108 debugger is normally not used; many commands frequently get Lisp errors
109 when invoked in inappropriate contexts (such as `C-f' at the end of the
110 buffer) and it would be unpleasant to enter a special debugging mode in
111 this case. When you want to make Lisp errors invoke the debugger, you
112 must set the variable `debug-on-error' to non-`nil'. Quitting with
113 `C-g' is not considered an error, and `debug-on-error' has no effect on
114 the handling of `C-g'. However, if you set `debug-on-quit' to be
115 non-`nil', `C-g' will invoke the debugger. This can be useful for
116 debugging an infinite loop; type `C-g' once the loop has had time to
117 reach its steady state. `debug-on-quit' has no effect on errors.
119 You can make Emacs enter the debugger when a specified function is
120 called or at a particular place in Lisp code. Use `M-x debug-on-entry'
121 with argument FUN-NAME to have Emacs enter the debugger as soon as
122 FUN-NAME is called. Use `M-x cancel-debug-on-entry' to make the
123 function stop entering the debugger when called. (Redefining the
124 function also does this.) To enter the debugger from some other place
125 in Lisp code, you must insert the expression `(debug)' there and
126 install the changed code with `C-M-x'. *Note Lisp Eval::.
128 When the debugger is entered, it displays the previously selected
129 buffer in one window and a buffer named `*Backtrace*' in another
130 window. The backtrace buffer contains one line for each level of Lisp
131 function execution currently going on. At the beginning of the buffer
132 is a message describing the reason that the debugger was invoked, for
133 example, an error message if it was invoked due to an error.
135 The backtrace buffer is read-only and is in Backtrace mode, a special
136 major mode in which letters are defined as debugger commands. The
137 usual Emacs editing commands are available; you can switch windows to
138 examine the buffer that was being edited at the time of the error, and
139 you can switch buffers, visit files, and perform any other editing
140 operations. However, the debugger is a recursive editing level (*note
141 Recursive Edit::); it is a good idea to return to the backtrace buffer
142 and explicitly exit the debugger when you don't want to use it any
143 more. Exiting the debugger kills the backtrace buffer.
145 The contents of the backtrace buffer show you the functions that are
146 executing and the arguments that were given to them. It also allows you
147 to specify a stack frame by moving point to the line describing that
148 frame. The frame whose line point is on is considered the "current
149 frame". Some of the debugger commands operate on the current frame.
150 Debugger commands are mainly used for stepping through code one
151 expression at a time. Here is a list of them:
154 Exit the debugger and continue execution. In most cases,
155 execution of the program continues as if the debugger had never
156 been entered (aside from the effect of any variables or data
157 structures you may have changed while inside the debugger). This
158 includes entry to the debugger due to function entry or exit,
159 explicit invocation, and quitting or certain errors. Most errors
160 cannot be continued; trying to continue an error usually causes
161 the same error to occur again.
164 Continue execution, but enter the debugger the next time a Lisp
165 function is called. This allows you to step through the
166 subexpressions of an expression, and see what the subexpressions
167 do and what values they compute.
169 When you enter the debugger this way, Emacs flags the stack frame
170 for the function call from which you entered. The same function
171 is then called when you exit the frame. To cancel this flag, use
175 Set up to enter the debugger when the current frame is exited.
176 Frames that invoke the debugger on exit are flagged with stars.
179 Don't enter the debugger when the current frame is exited. This
180 cancels a `b' command on a frame.
183 Read a Lisp expression in the minibuffer, evaluate it, and print
184 the value in the echo area. This is equivalent to the command
188 Terminate the program being debugged; return to top-level Emacs
191 If the debugger was entered due to a `C-g' but you really want to
192 quit, not to debug, use the `q' command.
195 Return a value from the debugger. The value is computed by
196 reading an expression with the minibuffer and evaluating it.
198 The value returned by the debugger makes a difference when the
199 debugger was invoked due to exit from a Lisp call frame (as
200 requested with `b'); then the value specified in the `r' command
201 is used as the value of that frame.
203 The debugger's return value also matters with many errors. For
204 example, `wrong-type-argument' errors will use the debugger's
205 return value instead of the invalid argument; `no-catch' errors
206 will use the debugger value as a throw tag instead of the tag that
207 was not found. If an error was signaled by calling the Lisp
208 function `signal', the debugger's return value is returned as the
212 File: xemacs.info, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Running
214 22.6 Lisp Interaction Buffers
215 =============================
217 The buffer `*scratch*', which is selected when Emacs starts up, is
218 provided for evaluating Lisp expressions interactively inside Emacs.
219 Both the expressions you evaluate and their output goes in the buffer.
221 The `*scratch*' buffer's major mode is Lisp Interaction mode, which
222 is the same as Emacs-Lisp mode except for one command, <LFD>. In
223 Emacs-Lisp mode, <LFD> is an indentation command. In Lisp Interaction
224 mode, <LFD> is bound to `eval-print-last-sexp'. This function reads
225 the Lisp expression before point, evaluates it, and inserts the value
226 in printed representation before point.
228 The way to use the `*scratch*' buffer is to insert Lisp expressions
229 at the end, ending each one with <LFD> so that it will be evaluated.
230 The result is a complete typescript of the expressions you have
231 evaluated and their values.
233 The rationale for this feature is that Emacs must have a buffer when
234 it starts up, but that buffer is not useful for editing files since a
235 new buffer is made for every file that you visit. The Lisp interpreter
236 typescript is the most useful thing I can think of for the initial
237 buffer to do. `M-x lisp-interaction-mode' will put any buffer in Lisp
241 File: xemacs.info, Node: External Lisp, Prev: Lisp Interaction, Up: Running
243 22.7 Running an External Lisp
244 =============================
246 Emacs has facilities for running programs in other Lisp systems. You
247 can run a Lisp process as an inferior of Emacs, and pass expressions to
248 it to be evaluated. You can also pass changed function definitions
249 directly from the Emacs buffers in which you edit the Lisp programs to
250 the inferior Lisp process.
252 To run an inferior Lisp process, type `M-x run-lisp'. This runs the
253 program named `lisp', the same program you would run by typing `lisp'
254 as a shell command, with both input and output going through an Emacs
255 buffer named `*lisp*'. In other words, any "terminal output" from Lisp
256 will go into the buffer, advancing point, and any "terminal input" for
257 Lisp comes from text in the buffer. To give input to Lisp, go to the
258 end of the buffer and type the input, terminated by <RET>. The
259 `*lisp*' buffer is in Inferior Lisp mode, which has all the special
260 characteristics of Lisp mode and Shell mode (*note Shell Mode::).
262 Use Lisp mode to run the source files of programs in external Lisps.
263 You can select this mode with `M-x lisp-mode'. It is used automatically
264 for files whose names end in `.l' or `.lisp', as most Lisp systems
267 When you edit a function in a Lisp program you are running, the
268 easiest way to send the changed definition to the inferior Lisp process
269 is the key `C-M-x'. In Lisp mode, this key runs the function
270 `lisp-send-defun', which finds the defun around or following point and
271 sends it as input to the Lisp process. (Emacs can send input to any
272 inferior process regardless of what buffer is current.)
274 Contrast the meanings of `C-M-x' in Lisp mode (for editing programs
275 to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
276 programs to be run in Emacs): in both modes it has the effect of
277 installing the function definition that point is in, but the way of
278 doing so is different according to where the relevant Lisp environment
279 is found. *Note Lisp Modes::.
282 File: xemacs.info, Node: Packages, Next: Basic, Prev: Startup Paths, Up: Top
287 The XEmacs 21 distribution comes only with a very basic set of built-in
288 modes and packages. Most of the packages that were part of the
289 distribution of earlier versions of XEmacs are now available
290 separately. The installer as well as the user can choose which
291 packages to install; the actual installation process is easy. This
292 gives an installer the ability to tailor an XEmacs installation for
293 local needs with safe removal of unnecessary code.
297 * Package Terminology:: Understanding different kinds of packages.
298 * Installing Packages:: How to install packages.
299 * Building Packages:: Building packages from CVS sources.
300 * Local.rules File:: This is an important file that you must create.
301 * Available Packages:: A brief directory of packaged LISP.
304 File: xemacs.info, Node: Package Terminology, Next: Installing Packages, Up: Packages
309 22.8.1 Package Flavors
310 ----------------------
312 There are two main flavors of packages.
314 * Regular Packages A regular package is one in which multiple files
315 are involved and one may not in general safely remove any of them.
317 * Single-File Packages A single-file package is an aggregate
318 collection of thematically related but otherwise independent lisp
319 files. These files are bundled together for download convenience
320 and individual files may be deleted at will without any loss of
321 functionality. However, we would recommend that you follow this
322 rule of thumb: "When in doubt, don't delete".
324 22.8.2 Package Distributions
325 ----------------------------
327 XEmacs Lisp packages are distributed in two ways, depending on the
328 intended use. Binary Packages are for installers and end-users that can
329 be installed directly into an XEmacs package directory. Source Packages
330 are for developers and include all files necessary for rebuilding
331 bytecompiled lisp and creating tarballs for distribution.
333 22.8.3 Binary Packages
334 ----------------------
336 Binary packages may be installed directly into an XEmacs package
339 22.8.4 Source Packages
340 ----------------------
342 Source packages contain all of the Package author's (where appropriate
343 in regular packages) source code plus all of the files necessary to
344 build distribution tarballs (Unix Tar format files, gzipped for space
347 Currently, source packages are only available via CVS. See
348 `http://cvs.xemacs.org/' for details.
351 File: xemacs.info, Node: Installing Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages
356 22.8.5 Getting Started
357 ----------------------
359 When you first download XEmacs 21, you will usually first grab the
360 "core distribution", a file called `xemacs-21.x.x.tar.gz'. (Replace the
361 21.x.x by the current version number.) The core distribution contains
362 the sources of XEmacs and a minimal set of Emacs Lisp files, which are
363 in the subdirectory named `lisp'. This subdirectory used to contain
364 all Emacs Lisp files distributed with XEmacs. Now, to conserve disk
365 space, most non-essential packages were made optional.
367 22.8.6 Choosing the Packages You Need
368 -------------------------------------
370 The *Note Available Packages:: can currently be found in the same ftp
371 directory where you grabbed the core distribution from, and are located
372 in the subdirectory `packages'. Package file names follow the naming
373 convention `<package-name>-<version>-pkg.tar.gz'.
375 If you have EFS *Note (EFS)::, packages can be installed over the
376 network. Alternatively, if you have copies of the packages locally,
377 you can install packages from a local disk or CDROM.
379 The file `etc/PACKAGES' in the core distribution contains a list of
380 the *Note Available Packages:: at the time of the XEmacs release.
382 You can also get a list of available packages, and whether or not
383 they are installed, using the visual package browser and installer.
384 You can access it via the menus:
386 Tools -> Packages -> List and Install
388 Or, you can get to it via the keyboard:
390 `M-x pui-list-packages'
392 Hint to system administrators of multi-user systems: it might be a
393 good idea to install all packages and not interfere with the wishes of
396 If you can't find which package provides the feature you require, try
397 using the `package-get-package-provider' function. Eg., if you know
398 that you need `thingatpt', type:
400 `M-x package-get-package-provider RET thingatpt'
402 which will return something like `(fsf-compat "1.08")'. You can the
403 use one of the methods above for installing the package you want.
405 22.8.7 XEmacs and Installing Packages
406 -------------------------------------
408 There are three main ways to install packages:
412 * Automatically:: Using the package tools from XEmacs.
413 * Manually:: Using individual package tarballs.
414 * Sumo:: All at once, using the 'Sumo Tarball'.
415 * Which Packages:: Which packages to install.
416 * Removing Packages:: Removing packages.
418 But regardless of the method you use to install packages, they can
419 only be used by XEmacs after a restart unless the package in question
420 has not been previously installed.
423 File: xemacs.info, Node: Automatically, Next: Manually, Up: Installing Packages
425 Automatic Package Installation:
426 ===============================
428 XEmacs comes with some tools to make the periodic updating and
429 installing easier. It will notice if new packages or versions are
430 available and will fetch them from the FTP site.
432 Unfortunately this requires that a few packages are already in place.
433 You will have to install them by hand as above or use a SUMO tarball.
434 This requirement will hopefully go away in the future. The packages you
437 efs - To fetch the files from the FTP site or mirrors.
438 xemacs-base - Needed by efs.
442 mailcrypt - To do PGP verification of the `package-index'
445 After installing these by hand, fire up XEmacs and follow these
448 1. Choose a download site. via menu: Tools -> Packages -> Set
449 Download Site via keyb: `M-x customize-variable RET
450 package-get-remote RET' (put in the details of remote host and
453 If the package tarballs _AND_ the package-index file are in a
454 local directory, you can: `M-x pui-set-local-package-get-directory
457 2. Obtain a list of packages and display the list in a buffer named
458 `*Packages*'. menu: Tools -> Packages -> List & Install keyb:
459 `M-x pui-list-packages RET'
461 XEmacs will now connect to the remote site and download the latest
464 The visual package browser will then display a list of all
465 packages. Help information will be displayed at the very bottom
466 of the buffer; you may have to scroll down to see it. You can
467 also press `?' to get the same help. From this buffer, you can
468 tell the package status by the character in the first column:
471 The package has not been installed.
474 The package has been installed, but a newer version is
475 available. The current version is out-of-date.
478 The package has been marked for installation/update.
480 If there is no character in the first column, the package has been
481 installed and is up to date.
483 From here, you can select or unselect packages for installation
484 using the <RET> key, the `Mouse-2' button or selecting "Select"
485 from the Popup `Mouse-3' Menu. Once you've finished selecting the
486 packages, you can press the `x' key (or use the menu) to actually
487 install the packages. Note that you will have to restart XEmacs
488 for XEmacs to recognize any new packages.
497 Toggle between selecting and unselecting a package for
501 Install selected packages.
504 View, in the minibuffer, additional information about the
505 package, such as the package date (not the build date) and
506 the package author. Moving the mouse over a package name
507 will also do the same thing.
510 Toggle between verbose and non-verbose package display.
513 Refresh the package display.
516 Kill the package buffer.
518 Moving the mouse over a package will also cause additional
519 information about the package to be displayed in the minibuffer.
520 If you have balloon-help enabled a balloon-help frame will pop up
521 and display additional package information also.
523 3. Choose the packages you wish to install. mouse: Click button 2 on
524 the package name. keyb: `RET' on the package name
526 4. Make sure you have everything you need. menu: Packages -> Add
529 XEmacs will now search for packages that are required by the ones
530 that you have chosen to install and offer to select those packages
533 For novices and gurus alike, this step can save your bacon. It's
534 easy to forget to install a critical package.
536 5. Download and install the packages. menu: Packages ->
537 Install/Remove Selected keyb: `x'
539 You can also install packages using a semi-manual interface:
541 M-x package-get-all <return>
543 Enter the name of the package (e.g., `prog-modes'), and XEmacs will
544 search for the latest version and install it and any packages that it
547 Keeping Packages Up To Date:
548 ============================
550 Once you have the packages you want installed (using any of the above
551 methods) you'll want to keep them up to date. You can do this easily
554 Tools -> Packages -> Set Download Site
555 Tools -> Packages -> Update Installed Packages
558 File: xemacs.info, Node: Manually, Next: Sumo, Prev: Automatically, Up: Installing Packages
560 Manual Package Installation:
561 ============================
563 Fetch the packages from the FTP site, CD-ROM whatever. The filenames
564 have the form `name-<version>-pkg.tar.gz' and are gzipped tar files. For
565 a fresh install it is sufficient to untar the file at the top of the
568 Note: If you are upgrading packages already installed, it's best to
569 remove the old package first *Note Removing Packages::.
571 For example if we are installing the `xemacs-base' package (version
574 mkdir $prefix/lib/xemacs/xemacs-packages RET # if it does not exist yet
575 cd $prefix/lib/xemacs/xemacs-packages RET
576 gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET
578 Or if you have GNU tar, the last step can be:
580 tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET
582 For MULE related packages, it is best to untar into the mule-packages
583 hierarchy, i.e. for the `mule-base' package, version 1.37:
585 mkdir $prefix/lib/xemacs/mule-packages RET # if it does not exist yet
586 cd $prefix/lib/xemacs/mule-packages RET
587 gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET
589 Or if you have GNU tar, the last step can be:
591 tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET
594 File: xemacs.info, Node: Sumo, Next: Which Packages, Prev: Manually, Up: Installing Packages
596 Installing the Sumo Packages:
597 =============================
599 Those with little time, cheap connections and plenty of disk space can
600 install all the packages at once using the sumo tarballs. Download the
601 file: `xemacs-sumo.tar.gz'
603 For an XEmacs compiled with Mule you also need:
604 `xemacs-mule-sumo.tar.gz'
606 N.B. They are called 'Sumo Tarballs' for good reason. They are
607 currently about 19MB and 4.5MB (gzipped) respectively.
611 `cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xvf - RET'
613 Or, if you have GNU tar:
615 `cd $prefix/lib/xemacs ; tar zxvf /path/to/<tarballname> RET'
617 As the Sumo tarballs are not regenerated as often as the individual
618 packages, it is recommended that you use the automatic package tools
619 afterwards to pick up any recent updates.
622 File: xemacs.info, Node: Which Packages, Next: Removing Packages, Prev: Sumo, Up: Installing Packages
624 Which Packages to Install:
625 ==========================
627 This is difficult to say. When in doubt install a package. If you
628 administrate a big site it might be a good idea to just install
629 everything. A good minimal set of packages for XEmacs-latin1 would be
631 xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs,
632 edit-utils, fsf-compat, mail-lib, net-utils, os-utils, prog-modes,
633 text-modes, time, mailcrypt
635 If you are using the XEmacs package tools, don't forget to do:
637 Packages -> Add Required
639 To make sure you have everything that the packages you have chosen to
642 See also *Note Available Packages:: for further descriptions of the
646 File: xemacs.info, Node: Removing Packages, Prev: Which Packages, Up: Installing Packages
651 Because the exact files and their locations contained in a package may
652 change it is recommended to remove a package first before installing a
653 new version. In order to facilitate removal each package contains an
654 `pgkinfo/MANIFEST.pkgname' file which list all the files belonging to
657 No need to panic, you don't have to go through the
658 `pkinfo/MANIFEST.pkgname' and manually delete the files. Instead, use
659 `M-x package-get-delete-package RET'.
661 Note that the interactive package tools included with XEmacs already
665 File: xemacs.info, Node: Building Packages, Next: Local.rules File, Prev: Installing Packages, Up: Packages
670 Currently, source packages are only available via anonymous CVS. See
671 `http://cvs.xemacs.org/' for details of checking out the
672 `xemacs-packages' module.
674 22.8.8 Prerequisites for Building Source Packages
675 -------------------------------------------------
680 (or a BSD compatible install program).
683 (3.75 or later preferred).
686 (4.2 from GNU texinfo 4.2 or later required).
694 `A properly configured `Local.rules' file.'
695 *Note Local.rules File::.
696 And of course, XEmacs 21.0 or higher.
698 22.8.9 What You Can Do With Source Packages
699 -------------------------------------------
701 The packages CVS sources are most useful for creating XEmacs package
702 tarballs for installation into your own XEmacs installations or for
703 distributing to others.
705 For a list and description of the different `Makefile' targets,
706 *Note Makefile Targets: (lispref)Makefile Targets.
709 File: xemacs.info, Node: Local.rules File, Next: Available Packages, Prev: Building Packages, Up: Packages
711 The Local.rules File:
712 =====================
714 This file is used when building and installing packages from source. In
715 the top level of the CVS module, `packages', contains the file,
716 `Local.rules.template'. Simply copy that to `Local.rules' and edit it
719 For a complete discussion of the `Local.rules' file, *Note
720 Local.rules File: (lispref)Local.rules File.
723 File: xemacs.info, Node: Available Packages, Prev: Local.rules File, Up: Packages
728 This section lists the Lisp packages that are currently available from
729 xemacs.org and it's mirrors. If a particular package that you are
730 looking for isn't here, please send a message to the XEmacs Beta list
731 <xemacs-beta@xemacs.org>.
733 This data is up to date as of June 27, 2003.
735 22.8.10 Normal Packages
736 -----------------------
738 A very broad selection of elisp packages.
741 Support for Sparcworks.
744 Ada language support.
747 A Portable Emacs Library. Used by XEmacs MIME support.
750 Basic TeX/LaTeX support.
753 The Big Brother Data Base: a rolodex-like database program.
756 Build XEmacs using custom widgets.
759 Basic single-file add-ons for editing C code.
765 Calendar and diary support.
768 C, C++ and Java language support.
771 Support for the Clearcase version control system.
774 "Fortune cookie"-style messages. Includes Spook (suspicious
775 phrases) and Yow (Zippy quotes).
778 Crisp/Brief emulation.
781 GUD, gdb, dbx debugging support.
784 Interface to RFC2229 dictionary servers.
787 The DIRectory EDitor is for manipulating, and running commands on
788 files in a directory.
791 DocBook editing support.
794 Crypto functionality in Emacs Lisp.
800 Interface over patch.
803 Single file lisp packages for various XEmacs goodies. Load this
804 and weed out the junk you don't want.
807 DEC EDIT/EDT emulation.
810 Treat files on remote systems the same as local files.
813 Enhanced Implementation of Emacs Interpreted Objects.
816 Portable Emacs Lisp utilities library.
819 Another interface over patch.
822 Command shell implemented entirely in Emacs Lisp.
825 ESS: Emacs Speaks Statistics.
831 Emacs Unified Directory Client (LDAP, PH).
834 Footnoting in mail message editing modes.
837 Forms editing support (obsolete, use the built-in Widget instead).
840 Fortran language support.
843 Provide a WM icon based on major mode.
846 GNU Emacs compatibility files.
849 Tetris, Sokoban, and Snake.
852 General documentation. Presently, empty.
858 The Gnus Newsreader and Mailreader.
861 Haskell language support.
867 Advanced replacement for buffer-menu.
870 Editing and Shell mode for the Interactive Data Language.
873 Enhanced front-end for Grep.
876 Front-end for interacting with Inferior Lisp (external lisps).
879 Spell-checking with ispell.
882 Java language and development support.
885 IRC (Internet Relay Chat) client for Emacs.
888 Fundamental lisp files for providing email support.
891 Support for messaging encryption with PGP.
894 Messaging in an Emacs World; a MIME-based email program.
897 Front end support for MH.
900 Elisp implementation of the game 'Minehunt'.
903 Other amusements and diversions.
906 Support for Multiple Major Modes within a single buffer.
909 Miscellaneous Networking Utilities. This is a single-file package
910 and files may be deleted at will.
913 Objective Caml editing support.
916 Miscellaneous single-file O/S utilities, for printing, archiving,
917 compression, remote shells, etc.
920 PC style interface emulation.
926 Provides programmatic completion.
929 Perl language support.
932 Emacs interface to various PGP implementations.
935 Miscellaneous single-file lisp files for various programming
939 Print buffers to PostScript printers.
942 Validated HTML/SGML editing.
945 A collection of DTDs for psgml. Note that this package is
946 deprecated and will be removed in the future, most likely Q2/2003.
947 Instead of using this, you should install needed DTDs yourself.
950 Python language support.
953 Emacs support for LaTeX cross-references, citations.
956 An obsolete Emacs mailer. If you do not already use it don't
960 Ruby language support.
963 Simple Authentication and Security Layer (SASL) library.
966 Front-end support for Inferior Scheme.
972 SGML/Linuxdoc-SGML editing.
975 Support for editing shell scripts.
978 Manage Sieve email filtering scripts.
984 Standard ML editing support.
987 XEmacs Sun sound files.
990 XEmacs Microsoft sound files.
993 Provides a separate frame with convenient references.
996 Mouse enhancement utility.
999 An Emacs citation tool. Useful with all Emacs Mailers and
1003 XEmacs TeXinfo support.
1006 Various single file lisp packages for editing text files.
1009 Single-file TeX support.
1012 Display time & date on the modeline.
1015 Emacs MIME support. Not needed for Gnus >= 5.8.0
1018 Support for building with Tooltalk.
1021 DEC EDIT/TPU support.
1024 Remote shell-based file editing. This is similar to EFS or
1025 Ange-FTP, but works with rsh/ssh and rcp/scp.
1028 Version Control for Free systems.
1031 Version Control for ClearCase. This package will shortly be
1032 replaced with clearcase.el
1038 A Unix process browsing tool.
1041 VI emulation support.
1050 Semi WYSIWYG for LaTeX, HTML, etc, using additional fonts.
1053 Fundamental XEmacs support. Install this unless you wish a totally
1057 XEmacs Lisp developer support. This package contains utilities for
1058 supporting Lisp development. It is a single-file package so it
1062 XSL editing support.
1065 A minor mode for (X)Emacs which allows running an XSLT processor
1071 22.8.11 Mule Support (mule)
1072 ---------------------------
1074 MULti-lingual Enhancement. Support for world scripts such as Latin,
1075 Arabic, Cyrillic, Chinese, Japanese, Greek, Hebrew etc. To use these
1076 packages your XEmacs must be compiled with Mule support.
1079 Lisp Interface to EDICT, Kanji Dictionary.
1082 Wnn (4.2 and 6) support. SJ3 support. Must be installed prior to
1086 Unify character sets in a buffer. When characters belong to
1087 disjoint character sets, this attempts to translate the characters
1088 so that they belong to one character set. If the buffer coding
1089 system is not sufficient, this suggests different coding systems.
1092 Quail. Used for everything other than English and Japanese.
1095 Used for localized menubars (French and Japanese) and localized
1096 splash screens (Japanese).
1099 Dictionary support. (This isn't an English dictionary program)
1102 Basic Mule support. Must be installed prior to building with Mule.
1105 Extended coding systems (including Unicode) for XEmacs.
1108 Another Japanese Language Input Method. Can be used without a
1109 separate process running as a dictionary server.
1112 File: xemacs.info, Node: Abbrevs, Next: Picture, Prev: Running, Up: Top
1117 An "abbrev" is a word which "expands" into some different text.
1118 Abbrevs are defined by the user to expand in specific ways. For
1119 example, you might define `foo' as an abbrev expanding to `find outer
1120 otter'. With this abbrev defined, you would be able to get `find outer
1121 otter ' into the buffer by typing `f o o <SPC>'.
1123 Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
1124 Disabling Abbrev mode does not cause abbrev definitions to be discarded,
1125 but they do not expand until Abbrev mode is enabled again. The command
1126 `M-x abbrev-mode' toggles Abbrev mode; with a numeric argument, it
1127 turns Abbrev mode on if the argument is positive, off otherwise. *Note
1128 Minor Modes::. `abbrev-mode' is also a variable; Abbrev mode is on
1129 when the variable is non-`nil'. The variable `abbrev-mode'
1130 automatically becomes local to the current buffer when it is set.
1132 Abbrev definitions can be "mode-specific"--active only in one major
1133 mode. Abbrevs can also have "global" definitions that are active in
1134 all major modes. The same abbrev can have a global definition and
1135 various mode-specific definitions for different major modes. A
1136 mode-specific definition for the current major mode overrides a global
1139 You can define Abbrevs interactively during an editing session. You
1140 can also save lists of abbrev definitions in files and reload them in
1141 later sessions. Some users keep extensive lists of abbrevs that they
1142 load in every session.
1144 A second kind of abbreviation facility is called the "dynamic
1145 expansion". Dynamic abbrev expansion happens only when you give an
1146 explicit command and the result of the expansion depends only on the
1147 current contents of the buffer. *Note Dynamic Abbrevs::.
1151 * Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
1152 * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
1153 * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
1154 * Saving Abbrevs:: Saving the entire list of abbrevs for another session.
1155 * Dynamic Abbrevs:: Abbreviations for words already in the buffer.
1158 File: xemacs.info, Node: Defining Abbrevs, Next: Expanding Abbrevs, Prev: Abbrevs, Up: Abbrevs
1160 23.1 Defining Abbrevs
1161 =====================
1164 Define an abbrev to expand into some text before point
1165 (`add-global-abbrev').
1168 Similar, but define an abbrev available only in the current major
1169 mode (`add-mode-abbrev').
1172 Define a word in the buffer as an abbrev
1173 (`inverse-add-global-abbrev').
1176 Define a word in the buffer as a mode-specific abbrev
1177 (`inverse-add-mode-abbrev').
1179 `M-x kill-all-abbrevs'
1180 After this command, no abbrev definitions remain in effect.
1182 The usual way to define an abbrev is to enter the text you want the
1183 abbrev to expand to, position point after it, and type `C-x a g'
1184 (`add-global-abbrev'). This reads the abbrev itself using the
1185 minibuffer, and then defines it as an abbrev for one or more words
1186 before point. Use a numeric argument to say how many words before point
1187 should be taken as the expansion. For example, to define the abbrev
1188 `foo' as in the example above, insert the text `find outer otter', then
1190 `C-u 3 C-x a g f o o <RET>'.
1192 An argument of zero to `C-x a g' means to use the contents of the
1193 region as the expansion of the abbrev being defined.
1195 The command `C-x a l' (`add-mode-abbrev') is similar, but defines a
1196 mode-specific abbrev. Mode-specific abbrevs are active only in a
1197 particular major mode. `C-x a l' defines an abbrev for the major mode
1198 in effect at the time `C-x a l' is typed. The arguments work the same
1199 way they do for `C-x a g'.
1201 If the text of an abbrev you want is already in the buffer instead of
1202 the expansion, use command `C-x a i g' (`inverse-add-global-abbrev')
1203 instead of `C-x a g', or use `C-x a i l' (`inverse-add-mode-abbrev')
1204 instead of `C-x a l'. These commands are called "inverse" because they
1205 invert the meaning of the argument found in the buffer and the argument
1206 read using the minibuffer.
1208 To change the definition of an abbrev, just add the new definition.
1209 You will be asked to confirm if the abbrev has a prior definition. To
1210 remove an abbrev definition, give a negative argument to `C-x a g' or
1211 `C-x a l'. You must choose the command to specify whether to kill a
1212 global definition or a mode-specific definition for the current mode,
1213 since those two definitions are independent for one abbrev.
1215 `M-x kill-all-abbrevs' removes all existing abbrev definitions.
1218 File: xemacs.info, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs
1220 23.2 Controlling Abbrev Expansion
1221 =================================
1223 An abbrev expands whenever it is in a buffer just before point and you
1224 type a self-inserting punctuation character (<SPC>, comma, etc.). Most
1225 often an abbrev is used by inserting the abbrev followed by punctuation.
1227 Abbrev expansion preserves case; thus, `foo' expands into `find
1228 outer otter', `Foo' into `Find outer otter', and `FOO' into `FIND OUTER
1229 OTTER' or `Find Outer Otter' according to the variable
1230 `abbrev-all-caps' (a non-`nil' value chooses the first of the two
1233 Two commands are available to control abbrev expansion:
1236 Separate a prefix from a following abbrev to be expanded
1237 (`abbrev-prefix-mark').
1240 Expand the abbrev before point (`expand-abbrev'). This is
1241 effective even when Abbrev mode is not enabled.
1243 `M-x unexpand-abbrev'
1244 Undo last abbrev expansion.
1246 `M-x expand-region-abbrevs'
1247 Expand some or all abbrevs found in the region.
1249 You may wish to expand an abbrev with a prefix attached. For
1250 example, if `cnst' expands into `construction', you may want to use it
1251 to enter `reconstruction'. It does not work to type `recnst', because
1252 that is not necessarily a defined abbrev. Instead, you can use the
1253 command `M-'' (`abbrev-prefix-mark') between the prefix `re' and the
1254 abbrev `cnst'. First, insert `re'. Then type `M-''; this inserts a
1255 minus sign in the buffer to indicate that it has done its work. Then
1256 insert the abbrev `cnst'. The buffer now contains `re-cnst'. Now
1257 insert a punctuation character to expand the abbrev `cnst' into
1258 `construction'. The minus sign is deleted at this point by `M-''. The
1259 resulting text is the desired `reconstruction'.
1261 If you actually want the text of the abbrev in the buffer, rather
1262 than its expansion, insert the following punctuation with `C-q'. Thus,
1263 `foo C-q -' leaves `foo-' in the buffer.
1265 If you expand an abbrev by mistake, you can undo the expansion
1266 (replace the expansion by the original abbrev text) with `M-x
1267 unexpand-abbrev'. You can also use `C-_' (`undo') to undo the
1268 expansion; but that will first undo the insertion of the punctuation
1271 `M-x expand-region-abbrevs' searches through the region for defined
1272 abbrevs, and offers to replace each one it finds with its expansion.
1273 This command is useful if you have typed text using abbrevs but forgot
1274 to turn on Abbrev mode first. It may also be useful together with a
1275 special set of abbrev definitions for making several global
1276 replacements at once. The command is effective even if Abbrev mode is
1280 File: xemacs.info, Node: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs
1282 23.3 Examining and Editing Abbrevs
1283 ==================================
1286 Print a list of all abbrev definitions.
1289 Edit a list of abbrevs; you can add, alter, or remove definitions.
1291 The output from `M-x list-abbrevs' looks like this:
1293 (lisp-mode-abbrev-table)
1295 (global-abbrev-table)
1296 "dfn" 0 "definition"
1298 (Some blank lines of no semantic significance, and some other abbrev
1299 tables, have been omitted.)
1301 A line containing a name in parentheses is the header for abbrevs in
1302 a particular abbrev table; `global-abbrev-table' contains all the global
1303 abbrevs, and the other abbrev tables that are named after major modes
1304 contain the mode-specific abbrevs.
1306 Within each abbrev table, each non-blank line defines one abbrev.
1307 The word at the beginning is the abbrev. The number that appears is
1308 the number of times the abbrev has been expanded. Emacs keeps track of
1309 this to help you see which abbrevs you actually use, in case you want
1310 to eliminate those that you don't use often. The string at the end of
1311 the line is the expansion.
1313 `M-x edit-abbrevs' allows you to add, change or kill abbrev
1314 definitions by editing a list of them in an Emacs buffer. The list has
1315 the format described above. The buffer of abbrevs is called
1316 `*Abbrevs*', and is in Edit-Abbrevs mode. This mode redefines the key
1317 `C-c C-c' to install the abbrev definitions as specified in the buffer.
1318 The `edit-abbrevs-redefine' command does this. Any abbrevs not
1319 described in the buffer are eliminated when this is done.
1321 `edit-abbrevs' is actually the same as `list-abbrevs', except that
1322 it selects the buffer `*Abbrevs*' whereas `list-abbrevs' merely
1323 displays it in another window.
1326 File: xemacs.info, Node: Saving Abbrevs, Next: Dynamic Abbrevs, Prev: Editing Abbrevs, Up: Abbrevs
1331 These commands allow you to keep abbrev definitions between editing
1334 `M-x write-abbrev-file'
1335 Write a file describing all defined abbrevs.
1337 `M-x read-abbrev-file'
1338 Read such an abbrev file and define abbrevs as specified there.
1340 `M-x quietly-read-abbrev-file'
1341 Similar, but do not display a message about what is going on.
1343 `M-x define-abbrevs'
1344 Define abbrevs from buffer.
1346 `M-x insert-abbrevs'
1347 Insert all abbrevs and their expansions into the buffer.
1349 Use `M-x write-abbrev-file' to save abbrev definitions for use in a
1350 later session. The command reads a file name using the minibuffer and
1351 writes a description of all current abbrev definitions into the
1352 specified file. The text stored in the file looks like the output of
1355 `M-x read-abbrev-file' prompts for a file name using the minibuffer
1356 and reads the specified file, defining abbrevs according to its
1357 contents. `M-x quietly-read-abbrev-file' is the same but does not
1358 display a message in the echo area; it is actually useful primarily in
1359 the init file. *Note Init File::. If you give an empty argument to
1360 either of these functions, the file name Emacs uses is the value of the
1361 variable `abbrev-file-name', which is by default `"~/.abbrev_defs"'.
1363 Emacs offers to save abbrevs automatically if you have changed any of
1364 them, whenever it offers to save all files (for `C-x s' or `C-x C-c').
1365 Set the variable `save-abbrevs' to `nil' to inhibit this feature.
1367 The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are
1368 similar to the previous commands but work on text in an Emacs buffer.
1369 `M-x insert-abbrevs' inserts text into the current buffer before point,
1370 describing all current abbrev definitions; `M-x define-abbrevs' parses
1371 the entire current buffer and defines abbrevs accordingly.
1374 File: xemacs.info, Node: Dynamic Abbrevs, Prev: Saving Abbrevs, Up: Abbrevs
1376 23.5 Dynamic Abbrev Expansion
1377 =============================
1379 The abbrev facility described above operates automatically as you insert
1380 text, but all abbrevs must be defined explicitly. By contrast,
1381 "dynamic abbrevs" allow the meanings of abbrevs to be determined
1382 automatically from the contents of the buffer, but dynamic abbrev
1383 expansion happens only when you request it explicitly.
1386 Expand the word in the buffer before point as a "dynamic abbrev",
1387 by searching in the buffer for words starting with that
1388 abbreviation (`dabbrev-expand').
1390 For example, if the buffer contains `does this follow ' and you type
1391 `f o M-/', the effect is to insert `follow' because that is the last
1392 word in the buffer that starts with `fo'. A numeric argument to `M-/'
1393 says to take the second, third, etc. distinct expansion found looking
1394 backward from point. Repeating `M-/' searches for an alternative
1395 expansion by looking farther back. After the entire buffer before
1396 point has been considered, the buffer after point is searched.
1398 Dynamic abbrev expansion is completely independent of Abbrev mode;
1399 the expansion of a word with `M-/' is completely independent of whether
1400 it has a definition as an ordinary abbrev.
1403 File: xemacs.info, Node: Picture, Next: Sending Mail, Prev: Abbrevs, Up: Top
1408 If you want to create a picture made out of text characters (for
1409 example, a picture of the division of a register into fields, as a
1410 comment in a program), use the command `edit-picture' to enter Picture
1413 In Picture mode, editing is based on the "quarter-plane" model of
1414 text. In this model, the text characters lie studded on an area that
1415 stretches infinitely far to the right and downward. The concept of the
1416 end of a line does not exist in this model; the most you can say is
1417 where the last non-blank character on the line is found.
1419 Of course, Emacs really always considers text as a sequence of
1420 characters, and lines really do have ends. But in Picture mode most
1421 frequently-used keys are rebound to commands that simulate the
1422 quarter-plane model of text. They do this by inserting spaces or by
1423 converting tabs to spaces.
1425 Most of the basic editing commands of Emacs are redefined by Picture
1426 mode to do essentially the same thing but in a quarter-plane way. In
1427 addition, Picture mode defines various keys starting with the `C-c'
1428 prefix to run special picture editing commands.
1430 One of these keys, `C-c C-c', is pretty important. Often a picture
1431 is part of a larger file that is usually edited in some other major
1432 mode. `M-x edit-picture' records the name of the previous major mode.
1433 You can then use the `C-c C-c' command (`picture-mode-exit') to restore
1434 that mode. `C-c C-c' also deletes spaces from the ends of lines,
1435 unless you give it a numeric argument.
1437 The commands used in Picture mode all work in other modes (provided
1438 the `picture' library is loaded), but are only bound to keys in
1439 Picture mode. Note that the descriptions below talk of moving "one
1440 column" and so on, but all the picture mode commands handle numeric
1441 arguments as their normal equivalents do.
1443 Turning on Picture mode calls the value of the variable
1444 `picture-mode-hook' as a function, with no arguments, if that value
1445 exists and is non-`nil'.
1449 * Basic Picture:: Basic concepts and simple commands of Picture Mode.
1450 * Insert in Picture:: Controlling direction of cursor motion
1451 after "self-inserting" characters.
1452 * Tabs in Picture:: Various features for tab stops and indentation.
1453 * Rectangles in Picture:: Clearing and superimposing rectangles.
1456 File: xemacs.info, Node: Basic Picture, Next: Insert in Picture, Prev: Picture, Up: Picture
1458 24.1 Basic Editing in Picture Mode
1459 ==================================
1461 Most keys do the same thing in Picture mode that they usually do, but do
1462 it in a quarter-plane style. For example, `C-f' is rebound to run
1463 `picture-forward-column', which moves point one column to the right, by
1464 inserting a space if necessary, so that the actual end of the line
1465 makes no difference. `C-b' is rebound to run
1466 `picture-backward-column', which always moves point left one column,
1467 converting a tab to multiple spaces if necessary. `C-n' and `C-p' are
1468 rebound to run `picture-move-down' and `picture-move-up', which can
1469 either insert spaces or convert tabs as necessary to make sure that
1470 point stays in exactly the same column. `C-e' runs
1471 `picture-end-of-line', which moves to after the last non-blank
1472 character on the line. There was no need to change `C-a', as the choice
1473 of screen model does not affect beginnings of lines.
1475 Insertion of text is adapted to the quarter-plane screen model
1476 through the use of Overwrite mode (*note Minor Modes::).
1477 Self-inserting characters replace existing text, column by column,
1478 rather than pushing existing text to the right. <RET> runs
1479 `picture-newline', which just moves to the beginning of the following
1480 line so that new text will replace that line.
1482 Text is erased instead of deleted and killed. <DEL>
1483 (`picture-backward-clear-column') replaces the preceding character with
1484 a space rather than removing it. `C-d' (`picture-clear-column') does
1485 the same in a forward direction. `C-k' (`picture-clear-line') really
1486 kills the contents of lines, but never removes the newlines from a
1489 To do actual insertion, you must use special commands. `C-o'
1490 (`picture-open-line') creates a blank line, but does so after the
1491 current line; it never splits a line. `C-M-o', `split-line', makes
1492 sense in Picture mode, so it remains unchanged. <LFD>
1493 (`picture-duplicate-line') inserts another line with the same contents
1494 below the current line.
1496 To actually delete parts of the picture, use `C-w', or with `C-c
1497 C-d' (which is defined as `delete-char', as `C-d' is in other modes),
1498 or with one of the picture rectangle commands (*note Rectangles in
1502 File: xemacs.info, Node: Insert in Picture, Next: Tabs in Picture, Prev: Basic Picture, Up: Picture
1504 24.2 Controlling Motion After Insert
1505 ====================================
1507 Since "self-inserting" characters just overwrite and move point in
1508 Picture mode, there is no essential restriction on how point should be
1509 moved. Normally point moves right, but you can specify any of the eight
1510 orthogonal or diagonal directions for motion after a "self-inserting"
1511 character. This is useful for drawing lines in the buffer.
1514 Move left after insertion (`picture-movement-left').
1517 Move right after insertion (`picture-movement-right').
1520 Move up after insertion (`picture-movement-up').
1523 Move down after insertion (`picture-movement-down').
1526 Move up and left ("northwest") after insertion
1527 (`picture-movement-nw').
1530 Move up and right ("northeast") after insertion
1531 (`picture-movement-ne').
1534 Move down and left ("southwest") after insertion
1535 (`picture-movement-sw').
1538 Move down and right ("southeast") after insertion
1539 (`picture-movement-se').
1541 Two motion commands move based on the current Picture insertion
1542 direction. The command `C-c C-f' (`picture-motion') moves in the same
1543 direction as motion after "insertion" currently does, while `C-c C-b'
1544 (`picture-motion-reverse') moves in the opposite direction.
1547 File: xemacs.info, Node: Tabs in Picture, Next: Rectangles in Picture, Prev: Insert in Picture, Up: Picture
1549 24.3 Picture Mode Tabs
1550 ======================
1552 Two kinds of tab-like action are provided in Picture mode.
1553 Context-based tabbing is done with `M-<TAB>' (`picture-tab-search').
1554 With no argument, it moves to a point underneath the next "interesting"
1555 character that follows whitespace in the previous non-blank line.
1556 "Next" here means "appearing at a horizontal position greater than the
1557 one point starts out at". With an argument, as in `C-u M-<TAB>', the
1558 command moves to the next such interesting character in the current
1559 line. `M-<TAB>' does not change the text; it only moves point.
1560 "Interesting" characters are defined by the variable
1561 `picture-tab-chars', which contains a string of characters considered
1562 interesting. Its default value is `"!-~"'.
1564 <TAB> itself runs `picture-tab', which operates based on the current
1565 tab stop settings; it is the Picture mode equivalent of
1566 `tab-to-tab-stop'. Without arguments it just moves point, but with a
1567 numeric argument it clears the text that it moves over.
1569 The context-based and tab-stop-based forms of tabbing are brought
1570 together by the command `C-c <TAB>' (`picture-set-tab-stops'.) This
1571 command sets the tab stops to the positions which `M-<TAB>' would
1572 consider significant in the current line. If you use this command with
1573 <TAB>, you can get the effect of context-based tabbing. But `M-<TAB>'
1574 is more convenient in the cases where it is sufficient.
1577 File: xemacs.info, Node: Rectangles in Picture, Prev: Tabs in Picture, Up: Picture
1579 24.4 Picture Mode Rectangle Commands
1580 ====================================
1582 Picture mode defines commands for working on rectangular pieces of the
1583 text in ways that fit with the quarter-plane model. The standard
1584 rectangle commands may also be useful (*note Rectangles::).
1587 Clear out the region-rectangle (`picture-clear-rectangle'). With
1591 Similar but save rectangle contents in register R first
1592 (`picture-clear-rectangle-to-register').
1595 Copy last killed rectangle into the buffer by overwriting, with
1596 upper left corner at point (`picture-yank-rectangle'). With
1597 argument, insert instead.
1600 Similar, but use the rectangle in register R
1601 (`picture-yank-rectangle-from-register').
1603 The picture rectangle commands `C-c C-k' (`picture-clear-rectangle')
1604 and `C-c C-w' (`picture-clear-rectangle-to-register') differ from the
1605 standard rectangle commands in that they normally clear the rectangle
1606 instead of deleting it; this is analogous with the way `C-d' is changed
1609 However, deletion of rectangles can be useful in Picture mode, so
1610 these commands delete the rectangle if given a numeric argument.
1612 The Picture mode commands for yanking rectangles differ from the
1613 standard ones in overwriting instead of inserting. This is the same
1614 way that Picture mode insertion of other text is different from other
1615 modes. `C-c C-y' (`picture-yank-rectangle') inserts (by overwriting)
1616 the rectangle that was most recently killed, while `C-c C-x'
1617 (`picture-yank-rectangle-from-register') does for the rectangle found
1618 in a specified register.
1620 Since most region commands in Picture mode operate on rectangles,
1621 when you select a region of text with the mouse in Picture mode, it is
1622 highlighted as a rectangle.
1625 File: xemacs.info, Node: Sending Mail, Next: Reading Mail, Prev: Picture, Up: Top
1630 To send a message in Emacs, start by typing the command (`C-x m') to
1631 select and initialize the `*mail*' buffer. You can then edit the text
1632 and headers of the message in the mail buffer, and type the command
1633 (`C-c C-c') to send the message.
1636 Begin composing a message to send (`mail').
1639 Likewise, but display the message in another window
1640 (`mail-other-window').
1643 In Mail mode, send the message and switch to another buffer
1644 (`mail-send-and-exit').
1646 The command `C-x m' (`mail') selects a buffer named `*mail*' and
1647 initializes it with the skeleton of an outgoing message. `C-x 4 m'
1648 (`mail-other-window') selects the `*mail*' buffer in a different
1649 window, leaving the previous current buffer visible.
1651 Because the buffer for mail composition is an ordinary Emacs buffer,
1652 you can switch to other buffers while in the middle of composing mail,
1653 and switch back later (or never). If you use the `C-x m' command again
1654 when you have been composing another message but have not sent it, a
1655 new mail buffer will be created; in this way, you can compose multiple
1656 messages at once. You can switch back to and complete an unsent
1657 message by using the normal buffer selection mechanisms.
1659 `C-u C-x m' is another way to switch back to a message in progress:
1660 it will search for an existing, unsent mail message buffer and select
1665 * Format: Mail Format. Format of the mail being composed.
1666 * Headers: Mail Headers. Details of allowed mail header fields.
1667 * Mode: Mail Mode. Special commands for editing mail being composed.
1670 File: xemacs.info, Node: Mail Format, Next: Mail Headers, Prev: Sending Mail, Up: Sending Mail
1672 25.1 The Format of the Mail Buffer
1673 ==================================
1675 In addition to the "text" or contents, a message has "header fields",
1676 which say who sent it, when, to whom, why, and so on. Some header
1677 fields, such as the date and sender, are created automatically after the
1678 message is sent. Others, such as the recipient names, must be
1679 specified by you in order to send the message properly.
1681 Mail mode provides a few commands to help you edit some header
1682 fields, and some are preinitialized in the buffer automatically at
1683 times. You can insert or edit any header fields using ordinary editing
1686 The line in the buffer that says:
1688 --text follows this line--
1690 is a special delimiter that separates the headers you have specified
1691 from the text. Whatever follows this line is the text of the message;
1692 the headers precede it. The delimiter line itself does not appear in
1693 the message actually sent. The text used for the delimiter line is
1694 controlled by the variable `mail-header-separator'.
1696 Here is an example of what the headers and text in the `*mail*'
1697 buffer might look like.
1701 Subject: The XEmacs User's Manual
1702 --Text follows this line--
1703 Please ignore this message.
1706 File: xemacs.info, Node: Mail Headers, Next: Mail Mode, Prev: Mail Format, Up: Sending Mail
1708 25.2 Mail Header Fields
1709 =======================
1711 There are several header fields you can use in the `*mail*' buffer.
1712 Each header field starts with a field name at the beginning of a line,
1713 terminated by a colon. It does not matter whether you use upper or
1714 lower case in the field name. After the colon and optional whitespace
1715 comes the contents of the field.
1718 This field contains the mailing addresses of the message.
1721 The contents of the `Subject' field should be a piece of text that
1722 says what the message is about. Subject fields are useful because
1723 most mail-reading programs can provide a summary of messages,
1724 listing the subject of each message but not its text.
1727 This field contains additional mailing addresses to send the
1728 message to, but whose readers should not regard the message as
1732 This field contains additional mailing addresses to send the
1733 message to, but which should not appear in the header of the
1734 message actually sent.
1737 This field contains the name of one file (in Unix mail file
1738 format) to which a copy of the message should be appended when the
1742 Use the `From' field to say who you are, when the account you are
1743 using to send the mail is not your own. The contents of the
1744 `From' field should be a valid mailing address, since replies will
1748 Use the `Reply-To' field to direct replies to a different address,
1749 not your own. `From' and `Reply-To' have the same effect on where
1750 replies go, but they convey a different meaning to the person who
1754 This field contains a piece of text describing a message you are
1755 replying to. Some mail systems can use the information to
1756 correlate related pieces of mail. This field is normally filled
1757 in by your mail handling package when you are replying to a
1758 message and you never need to think about it.
1760 The `To', `CC', `BCC' and `FCC' fields can appear any number of times,
1761 to specify many places to send the message.
1763 The `To', `CC', and `BCC', fields can have continuation lines. All the
1764 lines starting with whitespace, following the line on which the field
1765 starts, are considered part of the field. For example,
1767 To: foo@here, this@there,
1768 me@gnu.cambridge.mass.usa.earth.spiral3281
1770 If you have a `~/.mailrc' file, Emacs scans it for mail aliases the
1771 first time you try to send mail in an Emacs session. Emacs expands
1772 aliases found in the `To', `CC', and `BCC' fields where appropriate.
1773 You can set the variable `mail-abbrev-mailrc-file' to the name of the
1774 file with mail aliases. If `nil', `~/.mailrc' is used.
1776 Your `.mailrc' file ensures that word-abbrevs are defined for each
1777 of your mail aliases when point is in a `To', `CC', `BCC', or `From'
1778 field. The aliases are defined in your `.mailrc' file or in a file
1779 specified by the MAILRC environment variable if it exists. Your mail
1780 aliases expand any time you type a word-delimiter at the end of an
1783 In this version of Emacs, what you see is what you get: in contrast
1784 to some other versions, no abbreviations are expanded after you have
1785 sent the mail. This means you don't suffer the annoyance of having the
1786 system do things behind your back--if the system rewrites an address
1787 you typed, you know it immediately, instead of after the mail has been
1788 sent and it's too late to do anything about it. For example, you will
1789 never again be in trouble because you forgot to delete an old alias
1790 from your `.mailrc' and a new local user is given a userid which
1791 conflicts with one of your aliases.
1793 Your mail alias abbrevs are in effect only when point is in an
1794 appropriate header field. The mail aliases will not expand in the body
1795 of the message, or in other header fields. The default mode-specific
1796 abbrev table `mail-mode-abbrev-table' is used instead if defined. That
1797 means if you have been using mail-mode specific abbrevs, this code will
1798 not adversely affect you. You can control which header fields the
1799 abbrevs are used in by changing the variable `mail-abbrev-mode-regexp'.
1801 If auto-fill mode is on, abbrevs wrap at commas instead of at word
1802 boundaries, and header continuation lines will be properly indented.
1804 You can also insert a mail alias with
1805 `mail-interactive-insert-alias'. This function, which is bound to `C-c
1806 C-a', prompts you for an alias (with completion) and inserts its
1809 In this version of Emacs, it is possible to have lines like the
1810 following in your `.mailrc' file:
1812 alias someone "John Doe <doe@quux.com>"
1814 That is, if you want an address to have embedded spaces, simply
1815 surround it with double-quotes. The quotes are necessary because the
1816 format of the `.mailrc' file uses spaces as address delimiters.
1818 Aliases in the `.mailrc' file may be nested. For example, assume you
1819 define aliases like:
1820 alias group1 fred ethel
1821 alias group2 larry curly moe
1822 alias everybody group1 group2
1824 When you now type `everybody' on the `To' line, it will expand to:
1825 fred, ethyl, larry, curly, moe
1827 Aliases may contain forward references; the alias of `everybody' in
1828 the example above can precede the aliases of `group1' and `group2'.
1830 In this version of Emacs, you can use the `source' `.mailrc' command
1831 for reading aliases from some other file as well.
1833 Aliases may contain hyphens, as in `"alias foo-bar foo@bar"', even
1834 though word-abbrevs normally cannot contain hyphens.
1836 To read in the contents of another `.mailrc'-type file from Emacs,
1837 use the command `M-x merge-mail-aliases'. The `rebuild-mail-aliases'
1838 command is similar, but deletes existing aliases first.
1840 If you want multiple addresses separated by a string other than `,'
1841 (a comma), then set the variable `mail-alias-separator-string' to it.
1842 This has to be a comma bracketed by whitespace if you want any kind of
1843 reasonable behavior.
1845 If the variable `mail-archive-file-name' is non-`nil', it should be
1846 a string naming a file. Each time you start to edit a message to send,
1847 an `FCC' field is entered for that file. Unless you remove the `FCC'
1848 field, every message is written into that file when it is sent.
1851 File: xemacs.info, Node: Mail Mode, Prev: Mail Headers, Up: Sending Mail
1856 The major mode used in the `*mail*' buffer is Mail mode. Mail mode is
1857 similar to Text mode, but several commands are provided on the `C-c'
1858 prefix. These commands all deal specifically with editing or sending
1862 Send the message, and leave the `*mail*' buffer selected
1866 Send the message, and select some other buffer
1867 (`mail-send-and-exit').
1870 Move to the `To' header field, creating one if there is none
1874 Move to the `Subject' header field, creating one if there is none
1878 Move to the `CC' header field, creating one if there is none
1882 Insert the file `~/.signature' at the end of the message text
1886 Yank the selected message (`mail-yank-original').
1889 Fill all paragraphs of yanked old messages, each individually
1890 (`mail-fill-yanked-message').
1893 Pops up a menu of useful mail-mode commands.
1895 There are two ways to send a message. `C-c C-c'
1896 (`mail-send-and-exit') is the usual way to send the message. It sends
1897 the message and then deletes the window (if there is another window) or
1898 switches to another buffer. It puts the `*mail*' buffer at the lowest
1899 priority for automatic reselection, since you are finished with using
1900 it. `C-c C-s' (`mail-send') sends the message and marks the `*mail*'
1901 buffer unmodified, but leaves that buffer selected so that you can
1902 modify the message (perhaps with new recipients) and send it again.
1904 Mail mode provides some other special commands that are useful for
1905 editing the headers and text of the message before you send it. There
1906 are three commands defined to move point to particular header fields,
1907 all based on the prefix `C-c C-f' (`C-f' is for "field"). They are
1908 `C-c C-f C-t' (`mail-to') to move to the `To' field, `C-c C-f C-s'
1909 (`mail-subject') for the `Subject' field, and `C-c C-f C-c' (`mail-cc')
1910 for the `CC' field. These fields have special motion commands because
1911 they are edited most frequently.
1913 `C-c C-w' (`mail-signature') adds a standard piece of text at the
1914 end of the message to say more about who you are. The text comes from
1915 the file `.signature' in your home directory.
1917 When you use an Rmail command to send mail from the Rmail mail
1918 reader, you can use `C-c C-y' `mail-yank-original' inside the `*mail*'
1919 buffer to insert the text of the message you are replying to. Normally
1920 Rmail indents each line of that message four spaces and eliminates most
1921 header fields. A numeric argument specifies the number of spaces to
1922 indent. An argument of just `C-u' says not to indent at all and not to
1923 eliminate anything. `C-c C-y' always uses the current message from the
1924 `RMAIL' buffer, so you can insert several old messages by selecting one
1925 in `RMAIL', switching to `*mail*' and yanking it, then switching back
1926 to `RMAIL' to select another.
1928 After using `C-c C-y', you can use the command `C-c C-q'
1929 (`mail-fill-yanked-message') to fill the paragraphs of the yanked old
1930 message or messages. One use of `C-c C-q' fills all such paragraphs,
1931 each one separately.
1933 Clicking the right mouse button in a mail buffer pops up a menu of
1934 the above commands, for easy access.
1936 Turning on Mail mode (which `C-x m' does automatically) calls the
1937 value of `text-mode-hook', if it is not void or `nil', and then calls
1938 the value of `mail-mode-hook' if that is not void or `nil'.
1941 File: xemacs.info, Node: Reading Mail, Next: Calendar/Diary, Prev: Sending Mail, Up: Top
1946 XEmacs provides several mail-reading packages. Each one comes with its
1947 own manual, which is included in each package.
1949 The recommended mail-reading package for new users is VM. VM works
1950 with standard Unix-mail-format folders and was designed as a replacement
1951 for the older Rmail.
1953 XEmacs also provides a sophisticated and comfortable front-end to the
1954 MH mail-processing system, called `MH-E'. Unlike in other mail
1955 programs, folders in MH are stored as file-system directories, with
1956 each message occupying one (numbered) file. This facilitates working
1957 with mail using shell commands, and many other features of MH are also
1958 designed to integrate well with the shell and with shell scripts. Keep
1959 in mind, however, that in order to use MH-E you must have the MH
1960 mail-processing system installed on your computer.
1962 The "Everything including the kitchen sink" package `Gnus' is also
1963 available as an XEmacs package. Gnus also handles Usenet articles as
1966 `MEW' (Messaging in the Emacs World) is another mail-reading package
1967 available for XEmacs.
1969 Finally, XEmacs provides the Rmail package. Rmail is (currently)
1970 the only mail reading package distributed with FSF GNU Emacs, and is
1971 powerful in its own right. However, it stores mail folders in a
1972 special format called `Babyl', that is incompatible with all other
1973 frequently-used mail programs. A utility program is provided for
1974 converting Babyl folders to standard Unix-mail format; however, unless
1975 you already have mail in Babyl-format folders, you should consider
1976 using Gnus, VM, or MH-E instead.
1979 File: xemacs.info, Node: Calendar/Diary, Next: Sorting, Prev: Reading Mail, Up: Top
1981 26.1 Calendar Mode and the Diary
1982 ================================
1984 Emacs provides the functions of a desk calendar, with a diary of
1985 planned or past events. To enter the calendar, type `M-x calendar';
1986 this displays a three-month calendar centered on the current month, with
1987 point on the current date. With a numeric argument, as in `C-u M-x
1988 calendar', it prompts you for the month and year to be the center of the
1989 three-month calendar. The calendar uses its own buffer, whose major
1990 mode is Calendar mode.
1992 `Button2' in the calendar brings up a menu of operations on a
1993 particular date; `Buttons3' brings up a menu of commonly used calendar
1994 features that are independent of any particular date. To exit the
1995 calendar, type `q'. *Note Customizing the Calendar and Diary:
1996 (lispref)Calendar, for customization information about the calendar and
2001 * Calendar Motion:: Moving through the calendar; selecting a date.
2002 * Scroll Calendar:: Bringing earlier or later months onto the screen.
2003 * Mark and Region:: Remembering dates, the mark ring.
2004 * General Calendar:: Exiting or recomputing the calendar.
2005 * LaTeX Calendar:: Print a calendar using LaTeX.
2006 * Holidays:: Displaying dates of holidays.
2007 * Sunrise/Sunset:: Displaying local times of sunrise and sunset.
2008 * Lunar Phases:: Displaying phases of the moon.
2009 * Other Calendars:: Converting dates to other calendar systems.
2010 * Diary:: Displaying events from your diary.
2011 * Calendar Customization:: Altering the behavior of the features above.
2014 File: xemacs.info, Node: Calendar Motion, Next: Scroll Calendar, Prev: Calendar/Diary, Up: Calendar/Diary
2016 26.1.1 Movement in the Calendar
2017 -------------------------------
2019 Calendar mode lets you move through the calendar in logical units of
2020 time such as days, weeks, months, and years. If you move outside the
2021 three months originally displayed, the calendar display "scrolls"
2022 automatically through time to make the selected date visible. Moving to
2023 a date lets you view its holidays or diary entries, or convert it to
2024 other calendars; moving longer time periods is also useful simply to
2025 scroll the calendar.
2029 * Calendar Unit Motion:: Moving by days, weeks, months, and years.
2030 * Move to Beginning or End:: Moving to start/end of weeks, months, and years.
2031 * Specified Dates:: Moving to the current date or another
2035 File: xemacs.info, Node: Calendar Unit Motion, Next: Move to Beginning or End, Prev: Calendar Motion, Up: Calendar Motion
2037 26.1.1.1 Motion by Integral Days, Weeks, Months, Years
2038 ......................................................
2040 The commands for movement in the calendar buffer parallel the commands
2041 for movement in text. You can move forward and backward by days,
2042 weeks, months, and years.
2045 Move point one day forward (`calendar-forward-day').
2048 Move point one day backward (`calendar-backward-day').
2051 Move point one week forward (`calendar-forward-week').
2054 Move point one week backward (`calendar-backward-week').
2057 Move point one month forward (`calendar-forward-month').
2060 Move point one month backward (`calendar-backward-month').
2063 Move point one year forward (`calendar-forward-year').
2066 Move point one year backward (`calendar-backward-year').
2068 The day and week commands are natural analogues of the usual Emacs
2069 commands for moving by characters and by lines. Just as `C-n' usually
2070 moves to the same column in the following line, in Calendar mode it
2071 moves to the same day in the following week. And `C-p' moves to the
2072 same day in the previous week.
2074 The arrow keys are equivalent to `C-f', `C-b', `C-n' and `C-p', just
2075 as they normally are in other modes.
2077 The commands for motion by months and years work like those for
2078 weeks, but move a larger distance. The month commands `M-}' and `M-{'
2079 move forward or backward by an entire month's time. The year commands
2080 `C-x ]' and `C-x [' move forward or backward a whole year.
2082 The easiest way to remember these commands is to consider months and
2083 years analogous to paragraphs and pages of text, respectively. But the
2084 commands themselves are not quite analogous. The ordinary Emacs
2085 paragraph commands move to the beginning or end of a paragraph, whereas
2086 these month and year commands move by an entire month or an entire
2087 year, which usually involves skipping across the end of a month or year.
2089 All these commands accept a numeric argument as a repeat count. For
2090 convenience, the digit keys and the minus sign specify numeric
2091 arguments in Calendar mode even without the Meta modifier. For example,
2092 `100 C-f' moves point 100 days forward from its present location.
2095 File: xemacs.info, Node: Move to Beginning or End, Next: Specified Dates, Prev: Calendar Unit Motion, Up: Calendar Motion
2097 26.1.1.2 Beginning or End of Week, Month or Year
2098 ................................................
2100 A week (or month, or year) is not just a quantity of days; we think of
2101 weeks (months, years) as starting on particular dates. So Calendar mode
2102 provides commands to move to the beginning or end of a week, month or
2106 Move point to start of week (`calendar-beginning-of-week').
2109 Move point to end of week (`calendar-end-of-week').
2112 Move point to start of month (`calendar-beginning-of-month').
2115 Move point to end of month (`calendar-end-of-month').
2118 Move point to start of year (`calendar-beginning-of-year').
2121 Move point to end of year (`calendar-end-of-year').
2123 These commands also take numeric arguments as repeat counts, with the
2124 repeat count indicating how many weeks, months, or years to move
2125 backward or forward.
2127 By default, weeks begin on Sunday. To make them begin on Monday
2128 instead, set the variable `calendar-week-start-day' to 1.
2131 File: xemacs.info, Node: Specified Dates, Prev: Move to Beginning or End, Up: Calendar Motion
2133 26.1.1.3 Particular Dates
2134 .........................
2136 Calendar mode provides commands for moving to a particular date
2137 specified in various ways.
2140 Move point to specified date (`calendar-goto-date').
2143 Center calendar around specified month (`calendar-other-month').
2146 Move point to today's date (`calendar-goto-today').
2148 `g d' (`calendar-goto-date') prompts for a year, a month, and a day
2149 of the month, and then moves to that date. Because the calendar
2150 includes all dates from the beginning of the current era, you must type
2151 the year in its entirety; that is, type `1990', not `90'.
2153 `o' (`calendar-other-month') prompts for a month and year, then
2154 centers the three-month calendar around that month.
2156 You can return to today's date with `.' (`calendar-goto-today').
2159 File: xemacs.info, Node: Scroll Calendar, Next: Mark and Region, Prev: Calendar Motion, Up: Calendar/Diary
2161 26.1.2 Scrolling the Calendar through Time
2162 ------------------------------------------
2164 The calendar display scrolls automatically through time when you move
2165 out of the visible portion. You can also scroll it manually. Imagine
2166 that the calendar window contains a long strip of paper with the months
2167 on it. Scrolling it means moving the strip so that new months become
2168 visible in the window.
2171 Scroll calendar one month forward (`scroll-calendar-left').
2174 Scroll calendar one month backward (`scroll-calendar-right').
2178 Scroll calendar three months forward
2179 (`scroll-calendar-left-three-months').
2183 Scroll calendar three months backward
2184 (`scroll-calendar-right-three-months').
2186 The most basic calendar scroll commands scroll by one month at a
2187 time. This means that there are two months of overlap between the
2188 display before the command and the display after. `C-x <' scrolls the
2189 calendar contents one month to the left; that is, it moves the display
2190 forward in time. `C-x >' scrolls the contents to the right, which
2191 moves backwards in time.
2193 The commands `C-v' and `M-v' scroll the calendar by an entire
2194 "screenful"--three months--in analogy with the usual meaning of these
2195 commands. `C-v' makes later dates visible and `M-v' makes earlier
2196 dates visible. These commands take a numeric argument as a repeat
2197 count; in particular, since `C-u' multiplies the next command by four,
2198 typing `C-u C-v' scrolls the calendar forward by a year and typing `C-u
2199 M-v' scrolls the calendar backward by a year.
2201 The function keys <NEXT> and <PRIOR> are equivalent to `C-v' and
2202 `M-v', just as they are in other modes.
2205 File: xemacs.info, Node: Mark and Region, Next: General Calendar, Prev: Scroll Calendar, Up: Calendar/Diary
2207 26.1.3 The Mark and the Region
2208 ------------------------------
2210 The concept of the mark applies to the calendar just as to any other
2211 buffer, but it marks a _date_, not a _position_ in the buffer. The
2212 region consists of the days between the mark and point (including the
2213 starting and stopping dates).
2216 Set the mark to today's date (`calendar-set-mark').
2222 Interchange mark and point (`calendar-exchange-point-and-mark').
2225 Display the number of days in the current region
2226 (`calendar-count-days-region').
2228 You set the mark in the calendar, as in any other buffer, by using
2229 `C-@' or `C-SPC' (`calendar-set-mark'). You return to the marked date
2230 with the command `C-x C-x' (`calendar-exchange-point-and-mark') which
2231 puts the mark where point was and point where mark was. The calendar
2232 is scrolled as necessary, if the marked date was not visible on the
2233 screen. This does not change the extent of the region.
2235 To determine the number of days in the region, type `M-='
2236 (`calendar-count-days-region'). The numbers of days printed is
2237 _inclusive_; that is, it includes the days specified by mark and point.
2239 The main use of the mark in the calendar is to remember dates that
2240 you may want to go back to. To make this feature more useful, the mark
2241 ring (*note Mark Ring::) operates exactly as in other buffers: Emacs
2242 remembers 16 previous locations of the mark. To return to a marked
2243 date, type `C-u C-SPC' (or `C-u C-@'); this is the command
2244 `calendar-set-mark' given a numeric argument. It moves point to where
2245 the mark was, restores the mark from the ring of former marks, and
2246 stores the previous point at the end of the mark ring. So, repeated
2247 use of this command moves point through all the old marks on the ring,
2251 File: xemacs.info, Node: General Calendar, Next: LaTeX Calendar, Prev: Mark and Region, Up: Calendar/Diary
2253 26.1.4 Miscellaneous Calendar Commands
2254 --------------------------------------
2257 Display day-in-year (`calendar-print-day-of-year').
2260 Briefly describe calendar commands (`describe-calendar-mode').
2263 Regenerate the calendar window (`redraw-calendar').
2266 Scroll the next window (`scroll-other-window').
2269 Exit from calendar (`exit-calendar').
2271 If you want to know how many days have elapsed since the start of
2272 the year, or the number of days remaining in the year, type the `p d'
2273 command (`calendar-print-day-of-year'). This displays both of those
2274 numbers in the echo area.
2276 To display a brief description of the calendar commands, type `?'
2277 (`describe-calendar-mode'). For a fuller description, type `C-h m'.
2279 You can use `SPC' (`scroll-other-window') to scroll the other
2280 window. This is handy when you display a list of holidays or diary
2281 entries in another window.
2283 If the calendar window text gets corrupted, type `C-c C-l'
2284 (`redraw-calendar') to redraw it. (This can only happen if you use
2285 non-Calendar-mode editing commands.)
2287 In Calendar mode, you can use `SPC' (`scroll-other-window') to
2288 scroll the other window. This is handy when you display a list of
2289 holidays or diary entries in another window.
2291 To exit from the calendar, type `q' (`exit-calendar'). This buries
2292 all buffers related to the calendar, selecting other buffers. (If a
2293 frame contains a dedicated calendar window, exiting from the calendar
2294 iconifies that frame.)
2297 File: xemacs.info, Node: LaTeX Calendar, Next: Holidays, Prev: General Calendar, Up: Calendar/Diary
2302 The Calendar LaTeX commands produce a buffer of LaTeX code that prints
2303 as a calendar. Depending on the command you use, the printed calendar
2304 covers the day, week, month or year that point is in.
2307 Generate a one-month calendar (`cal-tex-cursor-month').
2310 Generate a sideways-printing one-month calendar
2311 (`cal-tex-cursor-month-landscape').
2314 Generate a one-day calendar (`cal-tex-cursor-day').
2317 Generate a one-page calendar for one week (`cal-tex-cursor-week').
2320 Generate a two-page calendar for one week (`cal-tex-cursor-week2').
2323 Generate an ISO-style calendar for one week
2324 (`cal-tex-cursor-week-iso').
2327 Generate a calendar for one Monday-starting week
2328 (`cal-tex-cursor-week-monday').
2331 Generate a Filofax-style two-weeks-at-a-glance calendar
2332 (`cal-tex-cursor-filofax-2week').
2335 Generate a Filofax-style one-week-at-a-glance calendar
2336 (`cal-tex-cursor-filofax-week').
2339 Generate a calendar for one year (`cal-tex-cursor-year').
2342 Generate a sideways-printing calendar for one year
2343 (`cal-tex-cursor-year-landscape').
2346 Generate a Filofax-style calendar for one year
2347 (`cal-tex-cursor-filofax-year').
2349 Some of these commands print the calendar sideways (in "landscape
2350 mode"), so it can be wider than it is long. Some of them use Filofax
2351 paper size (3.75in x 6.75in). All of these commands accept a prefix
2352 argument which specifies how many days, weeks, months or years to print
2353 (starting always with the selected one).
2355 If the variable `cal-tex-holidays' is non-`nil' (the default), then
2356 the printed calendars show the holidays in `calendar-holidays'. If the
2357 variable `cal-tex-diary' is non-`nil' (the default is `nil'), diary
2358 entries are included also (in weekly and monthly calendars only).
2361 File: xemacs.info, Node: Holidays, Next: Sunrise/Sunset, Prev: LaTeX Calendar, Up: Calendar/Diary
2366 The Emacs calendar knows about all major and many minor holidays, and
2370 Display holidays for the selected date
2371 (`calendar-cursor-holidays').
2374 Display any holidays for the date you click on.
2377 Mark holidays in the calendar window (`mark-calendar-holidays').
2380 Unmark calendar window (`calendar-unmark').
2383 List all holidays for the displayed three months in another window
2384 (`list-calendar-holidays').
2387 List all holidays for three months around today's date in another
2391 List holidays in another window for a specified range of years.
2393 To see if any holidays fall on a given date, position point on that
2394 date in the calendar window and use the `h' command. Alternatively,
2395 click on that date with `Button2' and then choose `Holidays' from the
2396 menu that appears. Either way, this displays the holidays for that
2397 date, in the echo area if they fit there, otherwise in a separate
2400 To view the distribution of holidays for all the dates shown in the
2401 calendar, use the `x' command. This displays the dates that are
2402 holidays in a different face (or places a `*' after these dates, if
2403 display with multiple faces is not available). The command applies both
2404 to the currently visible months and to other months that subsequently
2405 become visible by scrolling. To turn marking off and erase the current
2406 marks, type `u', which also erases any diary marks (*note Diary::).
2408 To get even more detailed information, use the `a' command, which
2409 displays a separate buffer containing a list of all holidays in the
2410 current three-month range. You can use <SPC> in the calendar window to
2413 The command `M-x holidays' displays the list of holidays for the
2414 current month and the preceding and succeeding months; this works even
2415 if you don't have a calendar window. If you want the list of holidays
2416 centered around a different month, use `C-u M-x holidays', which
2417 prompts for the month and year.
2419 The holidays known to Emacs include United States holidays and the
2420 major Christian, Jewish, and Islamic holidays; also the solstices and
2423 The command `M-x list-holidays' displays the list of holidays for a
2424 range of years. This function asks you for the starting and stopping
2425 years, and allows you to choose all the holidays or one of several
2426 categories of holidays. You can use this command even if you don't have
2429 The dates used by Emacs for holidays are based on _current
2430 practice_, not historical fact. Historically, for instance, the start
2431 of daylight savings time and even its existence have varied from year to
2432 year, but present United States law mandates that daylight savings time
2433 begins on the first Sunday in April. When the daylight savings rules
2434 are set up for the United States, Emacs always uses the present
2435 definition, even though it is wrong for some prior years.
2438 File: xemacs.info, Node: Sunrise/Sunset, Next: Lunar Phases, Prev: Holidays, Up: Calendar/Diary
2440 26.2.2 Times of Sunrise and Sunset
2441 ----------------------------------
2443 Special calendar commands can tell you, to within a minute or two, the
2444 times of sunrise and sunset for any date.
2447 Display times of sunrise and sunset for the selected date
2448 (`calendar-sunrise-sunset').
2450 `Button2 Sunrise/Sunset'
2451 Display times of sunrise and sunset for the date you click on.
2453 `M-x sunrise-sunset'
2454 Display times of sunrise and sunset for today's date.
2456 `C-u M-x sunrise-sunset'
2457 Display times of sunrise and sunset for a specified date.
2459 Within the calendar, to display the _local times_ of sunrise and
2460 sunset in the echo area, move point to the date you want, and type `S'.
2461 Alternatively, click `Button2' on the date, then choose
2462 `Sunrise/Sunset' from the menu that appears. The command `M-x
2463 sunrise-sunset' is available outside the calendar to display this
2464 information for today's date or a specified date. To specify a date
2465 other than today, use `C-u M-x sunrise-sunset', which prompts for the
2466 year, month, and day.
2468 You can display the times of sunrise and sunset for any location and
2469 any date with `C-u C-u M-x sunrise-sunset'. This asks you for a
2470 longitude, latitude, number of minutes difference from Coordinated
2471 Universal Time, and date, and then tells you the times of sunrise and
2472 sunset for that location on that date.
2474 Because the times of sunrise and sunset depend on the location on
2475 earth, you need to tell Emacs your latitude, longitude, and location
2476 name before using these commands. Here is an example of what to set:
2478 (setq calendar-latitude 40.1)
2479 (setq calendar-longitude -88.2)
2480 (setq calendar-location-name "Urbana, IL")
2482 Use one decimal place in the values of `calendar-latitude' and
2483 `calendar-longitude'.
2485 Your time zone also affects the local time of sunrise and sunset.
2486 Emacs usually gets time zone information from the operating system, but
2487 if these values are not what you want (or if the operating system does
2488 not supply them), you must set them yourself. Here is an example:
2490 (setq calendar-time-zone -360)
2491 (setq calendar-standard-time-zone-name "CST")
2492 (setq calendar-daylight-time-zone-name "CDT")
2494 The value of `calendar-time-zone' is the number of minutes difference
2495 between your local standard time and Coordinated Universal Time
2496 (Greenwich time). The values of `calendar-standard-time-zone-name' and
2497 `calendar-daylight-time-zone-name' are the abbreviations used in your
2498 time zone. Emacs displays the times of sunrise and sunset _corrected
2499 for daylight savings time_. *Note Daylight Savings::, for how daylight
2500 savings time is determined.
2502 As a user, you might find it convenient to set the calendar location
2503 variables for your usual physical location in your init file. And when
2504 you install Emacs on a machine, you can create a `default.el' file
2505 which sets them properly for the typical location of most users of that
2506 machine. *Note Init File::.
2509 File: xemacs.info, Node: Lunar Phases, Next: Other Calendars, Prev: Sunrise/Sunset, Up: Calendar/Diary
2511 26.2.3 Phases of the Moon
2512 -------------------------
2514 These calendar commands display the dates and times of the phases of
2515 the moon (new moon, first quarter, full moon, last quarter). This
2516 feature is useful for debugging problems that "depend on the phase of
2520 Display the dates and times for all the quarters of the moon for
2521 the three-month period shown (`calendar-phases-of-moon').
2523 `M-x phases-of-moon'
2524 Display dates and times of the quarters of the moon for three
2525 months around today's date.
2527 Within the calendar, use the `M' command to display a separate
2528 buffer of the phases of the moon for the current three-month range. The
2529 dates and times listed are accurate to within a few minutes.
2531 Outside the calendar, use the command `M-x phases-of-moon' to
2532 display the list of the phases of the moon for the current month and the
2533 preceding and succeeding months. For information about a different
2534 month, use `C-u M-x phases-of-moon', which prompts for the month and
2537 The dates and times given for the phases of the moon are given in
2538 local time (corrected for daylight savings, when appropriate); but if
2539 the variable `calendar-time-zone' is void, Coordinated Universal Time
2540 (the Greenwich time zone) is used. *Note Daylight Savings::.
2543 File: xemacs.info, Node: Other Calendars, Next: Calendar Systems, Prev: Lunar Phases, Up: Calendar/Diary
2545 26.2.4 Conversion To and From Other Calendars
2546 ---------------------------------------------
2548 The Emacs calendar displayed is _always_ the Gregorian calendar,
2549 sometimes called the "new style" calendar, which is used in most of the
2550 world today. However, this calendar did not exist before the sixteenth
2551 century and was not widely used before the eighteenth century; it did
2552 not fully displace the Julian calendar and gain universal acceptance
2553 until the early twentieth century. The Emacs calendar can display any
2554 month since January, year 1 of the current era, but the calendar
2555 displayed is the Gregorian, even for a date at which the Gregorian
2556 calendar did not exist.
2558 While Emacs cannot display other calendars, it can convert dates to
2559 and from several other calendars.
2563 * Calendar Systems:: The calendars Emacs understands
2564 (aside from Gregorian).
2565 * To Other Calendar:: Converting the selected date to various calendars.
2566 * From Other Calendar:: Moving to a date specified in another calendar.
2567 * Mayan Calendar:: Moving to a date specified in a Mayan calendar.
2569 If you are interested in these calendars, you can convert dates one
2570 at a time. Put point on the desired date of the Gregorian calendar and
2571 press the appropriate keys. The `p' is a mnemonic for "print" since
2572 Emacs "prints' the equivalent date in the echo area.
2575 File: xemacs.info, Node: Calendar Systems, Next: To Other Calendar, Prev: Other Calendars, Up: Other Calendars
2577 26.3 Supported Calendar Systems
2578 ===============================
2580 The ISO commercial calendar is used largely in Europe.
2582 The Julian calendar, named after Julius Caesar, was the one used in
2583 Europe throughout medieval times, and in many countries up until the
2586 Astronomers use a simple counting of days elapsed since noon, Monday,
2587 January 1, 4713 B.C. on the Julian calendar. The number of days elapsed
2588 is called the _Julian day number_ or the _Astronomical day number_.
2590 The Hebrew calendar is used by tradition in the Jewish religion. The
2591 Emacs calendar program uses the Hebrew calendar to determine the dates
2592 of Jewish holidays. Hebrew calendar dates begin and end at sunset.
2594 The Islamic calendar is used in many predominantly Islamic countries.
2595 Emacs uses it to determine the dates of Islamic holidays. There is no
2596 universal agreement in the Islamic world about the calendar; Emacs uses
2597 a widely accepted version, but the precise dates of Islamic holidays
2598 often depend on proclamation by religious authorities, not on
2599 calculations. As a consequence, the actual dates of observance can vary
2600 slightly from the dates computed by Emacs. Islamic calendar dates begin
2603 The French Revolutionary calendar was created by the Jacobins after
2604 the 1789 revolution, to represent a more secular and nature-based view
2605 of the annual cycle, and to install a 10-day week in a rationalization
2606 measure similar to the metric system. The French government officially
2607 abandoned this calendar at the end of 1805.
2609 The Maya of Central America used three separate, overlapping calendar
2610 systems, the _long count_, the _tzolkin_, and the _haab_. Emacs knows
2611 about all three of these calendars. Experts dispute the exact
2612 correlation between the Mayan calendar and our calendar; Emacs uses the
2613 Goodman-Martinez-Thompson correlation in its calculations.
2615 The Copts use a calendar based on the ancient Egyptian solar
2616 calendar. Their calendar consists of twelve 30-day months followed by
2617 an extra five-day period. Once every fourth year they add a leap day
2618 to this extra period to make it six days. The Ethiopic calendar is
2619 identical in structure, but has different year numbers and month names.
2621 The Persians use a solar calendar based on a design of Omar Khayyam.
2622 Their calendar consists of twelve months of which the first six have 31
2623 days, the next five have 30 days, and the last has 29 in ordinary years
2624 and 30 in leap years. Leap years occur in a complicated pattern every
2627 The Chinese calendar is a complicated system of lunar months arranged
2628 into solar years. The years go in cycles of sixty, each year containing
2629 either twelve months in an ordinary year or thirteen months in a leap
2630 year; each month has either 29 or 30 days. Years, ordinary months, and
2631 days are named by combining one of ten "celestial stems" with one of
2632 twelve "terrestrial branches" for a total of sixty names that are
2633 repeated in a cycle of sixty.
2636 File: xemacs.info, Node: To Other Calendar, Next: From Other Calendar, Prev: Calendar Systems, Up: Other Calendars
2638 26.4 Converting To Other Calendars
2639 ==================================
2641 The following commands describe the selected date (the date at point)
2642 in various other calendar systems:
2644 `Button2 Other Calendars'
2645 Display the date that you click on, expressed in various other
2649 Display ISO commercial calendar equivalent for selected day
2650 (`calendar-print-iso-date').
2653 Display Julian date for selected day
2654 (`calendar-print-julian-date').
2657 Display astronomical (Julian) day number for selected day
2658 (`calendar-print-astro-day-number').
2661 Display Hebrew date for selected day
2662 (`calendar-print-hebrew-date').
2665 Display Islamic date for selected day
2666 (`calendar-print-islamic-date').
2669 Display French Revolutionary date for selected day
2670 (`calendar-print-french-date').
2673 Display Chinese date for selected day
2674 (`calendar-print-chinese-date').
2677 Display Coptic date for selected day
2678 (`calendar-print-coptic-date').
2681 Display Ethiopic date for selected day
2682 (`calendar-print-ethiopic-date').
2685 Display Persian date for selected day
2686 (`calendar-print-persian-date').
2689 Display Mayan date for selected day (`calendar-print-mayan-date').
2691 If you are using X, the easiest way to translate a date into other
2692 calendars is to click on it with `Button2', then choose `Other
2693 Calendars' from the menu that appears. This displays the equivalent
2694 forms of the date in all the calendars Emacs understands, in the form of
2695 a menu. (Choosing an alternative from this menu doesn't actually do
2696 anything--the menu is used only for display.)
2698 Put point on the desired date of the Gregorian calendar, then type
2699 the appropriate keys. The `p' is a mnemonic for "print" since Emacs
2700 "prints" the equivalent date in the echo area.
2703 File: xemacs.info, Node: From Other Calendar, Next: Mayan Calendar, Prev: To Other Calendar, Up: Other Calendars
2705 26.5 Converting From Other Calendars
2706 ====================================
2708 You can use the other supported calendars to specify a date to move to.
2709 This section describes the commands for doing this using calendars
2710 other than Mayan; for the Mayan calendar, see the following section.
2713 Move to a date specified in the ISO commercial calendar
2714 (`calendar-goto-iso-date').
2717 Move to a date specified in the Julian calendar
2718 (`calendar-goto-julian-date').
2721 Move to a date specified in astronomical (Julian) day number
2722 (`calendar-goto-astro-day-number').
2725 Move to a date specified in the Hebrew calendar
2726 (`calendar-goto-hebrew-date').
2729 Move to a date specified in the Islamic calendar
2730 (`calendar-goto-islamic-date').
2733 Move to a date specified in the French Revolutionary calendar
2734 (`calendar-goto-french-date').
2737 Move to a date specified in the Chinese calendar
2738 (`calendar-goto-chinese-date').
2741 Move to a date specified in the Persian calendar
2742 (`calendar-goto-persian-date').
2745 Move to a date specified in the Coptic calendar
2746 (`calendar-goto-coptic-date').
2749 Move to a date specified in the Ethiopic calendar
2750 (`calendar-goto-ethiopic-date').
2752 These commands ask you for a date on the other calendar, move point
2753 to the Gregorian calendar date equivalent to that date, and display the
2754 other calendar's date in the echo area. Emacs uses strict completion
2755 (*note Completion::) whenever it asks you to type a month name, so you
2756 don't have to worry about the spelling of Hebrew, Islamic, or French
2759 One common question concerning the Hebrew calendar is the computation
2760 of the anniversary of a date of death, called a "yahrzeit." The Emacs
2761 calendar includes a facility for such calculations. If you are in the
2762 calendar, the command `M-x list-yahrzeit-dates' asks you for a range of
2763 years and then displays a list of the yahrzeit dates for those years
2764 for the date given by point. If you are not in the calendar, this
2765 command first asks you for the date of death and the range of years,
2766 and then displays the list of yahrzeit dates.
2769 File: xemacs.info, Node: Mayan Calendar, Next: Diary, Prev: From Other Calendar, Up: Other Calendars
2771 26.5.1 Converting from the Mayan Calendar
2772 -----------------------------------------
2774 Here are the commands to select dates based on the Mayan calendar:
2777 Move to a date specified by the long count calendar
2778 (`calendar-goto-mayan-long-count-date').
2781 Move to the next occurrence of a place in the tzolkin calendar
2782 (`calendar-next-tzolkin-date').
2785 Move to the previous occurrence of a place in the tzolkin calendar
2786 (`calendar-previous-tzolkin-date').
2789 Move to the next occurrence of a place in the haab calendar
2790 (`calendar-next-haab-date').
2793 Move to the previous occurrence of a place in the haab calendar
2794 (`calendar-previous-haab-date').
2797 Move to the next occurrence of a place in the calendar round
2798 (`calendar-next-calendar-round-date').
2801 Move to the previous occurrence of a place in the calendar round
2802 (`calendar-previous-calendar-round-date').
2804 To understand these commands, you need to understand the Mayan
2805 calendars. The "long count" is a counting of days with these units:
2807 1 kin = 1 day 1 uinal = 20 kin 1 tun = 18 uinal
2808 1 katun = 20 tun 1 baktun = 20 katun
2810 Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
2811 tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long
2812 count dates as early as 7.17.18.13.1, but no earlier. When you use the
2813 `g m l' command, type the Mayan long count date with the baktun, katun,
2814 tun, uinal, and kin separated by periods.
2816 The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
2817 independent cycles of 13 and 20 days. Since this cycle repeats
2818 endlessly, Emacs provides commands to move backward and forward to the
2819 previous or next point in the cycle. Type `g m p t' to go to the
2820 previous tzolkin date; Emacs asks you for a tzolkin date and moves point
2821 to the previous occurrence of that date. Similarly, type `g m n t' to
2822 go to the next occurrence of a tzolkin date.
2824 The Mayan haab calendar is a cycle of 365 days arranged as 18 months
2825 of 20 days each, followed a 5-day monthless period. Like the tzolkin
2826 cycle, this cycle repeats endlessly, and there are commands to move
2827 backward and forward to the previous or next point in the cycle. Type
2828 `g m p h' to go to the previous haab date; Emacs asks you for a haab
2829 date and moves point to the previous occurrence of that date.
2830 Similarly, type `g m n h' to go to the next occurrence of a haab date.
2832 The Maya also used the combination of the tzolkin date and the haab
2833 date. This combination is a cycle of about 52 years called a _calendar
2834 round_. If you type `g m p c', Emacs asks you for both a haab and a
2835 tzolkin date and then moves point to the previous occurrence of that
2836 combination. Use `g m n c' to move point to the next occurrence of a
2837 combination. These commands signal an error if the haab/tzolkin date
2838 combination you have typed is impossible.
2840 Emacs uses strict completion (*note Completion::) whenever it asks
2841 you to type a Mayan name, so you don't have to worry about spelling.
2844 File: xemacs.info, Node: Diary, Next: Calendar Customization, Prev: Mayan Calendar, Up: Calendar/Diary
2849 The Emacs diary keeps track of appointments or other events on a daily
2850 basis, in conjunction with the calendar. To use the diary feature, you
2851 must first create a "diary file" containing a list of events and their
2852 dates. Then Emacs can automatically pick out and display the events
2853 for today, for the immediate future, or for any specified date.
2855 By default, Emacs uses `~/diary' as the diary file. This is the
2856 same file that the `calendar' utility uses. A sample `~/diary' file is:
2858 12/22/1988 Twentieth wedding anniversary!!
2859 &1/1. Happy New Year!
2860 10/22 Ruth's birthday.
2862 Tuesday--weekly meeting with grad students at 10am
2863 Supowit, Shen, Bitner, and Kapoor to attend.
2864 1/13/89 Friday the thirteenth!!
2865 &thu 4pm squash game with Lloyd.
2866 mar 16 Dad's birthday
2867 April 15, 1989 Income tax due.
2868 &* 15 time cards due.
2870 This example uses extra spaces to align the event descriptions of most
2871 of the entries. Such formatting is purely a matter of taste.
2873 Although you probably will start by creating a diary manually, Emacs
2874 provides a number of commands to let you view, add, and change diary
2875 entries. You can also share diary entries with other users (*note
2876 Included Diary Files::).
2880 * Diary Commands:: Viewing diary entries and associated calendar dates.
2881 * Format of Diary File:: Entering events in your diary.
2882 * Date Formats:: Various ways you can specify dates.
2883 * Adding to Diary:: Commands to create diary entries.
2884 * Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.
2887 File: xemacs.info, Node: Diary Commands, Next: Format of Diary File, Prev: Diary, Up: Diary
2889 26.5.3 Commands Displaying Diary Entries
2890 ----------------------------------------
2892 Once you have created a `~/diary' file, you can use the calendar to
2893 view it. You can also view today's events outside of Calendar mode.
2896 Display all diary entries for the selected date
2897 (`view-diary-entries').
2900 Display all diary entries for the date you click on.
2903 Display the entire diary file (`show-all-diary-entries').
2906 Mark all visible dates that have diary entries
2907 (`mark-diary-entries').
2910 Unmark the calendar window (`calendar-unmark').
2912 `M-x print-diary-entries'
2913 Print hard copy of the diary display as it appears.
2916 Display all diary entries for today's date.
2918 `M-x diary-mail-entries'
2919 Mail yourself email reminders about upcoming diary entries.
2921 Displaying the diary entries with `d' shows in a separate window the
2922 diary entries for the selected date in the calendar. The mode line of
2923 the new window shows the date of the diary entries and any holidays
2924 that fall on that date. If you specify a numeric argument with `d', it
2925 shows all the diary entries for that many successive days. Thus, `2 d'
2926 displays all the entries for the selected date and for the following
2929 Another way to display the diary entries for a date is to click
2930 `Button2' on the date, and then choose `Diary' from the menu that
2933 To get a broader view of which days are mentioned in the diary, use
2934 the `m' command. This displays the dates that have diary entries in a
2935 different face (or places a `+' after these dates, if display with
2936 multiple faces is not available). The command applies both to the
2937 currently visible months and to other months that subsequently become
2938 visible by scrolling. To turn marking off and erase the current marks,
2939 type `u', which also turns off holiday marks (*note Holidays::).
2941 To see the full diary file, rather than just some of the entries, use
2944 Display of selected diary entries uses the selective display feature
2945 to hide entries that don't apply.
2947 The diary buffer as you see it is an illusion, so simply printing the
2948 buffer does not print what you see on your screen. There is a special
2949 command to print hard copy of the diary buffer _as it appears_; this
2950 command is `M-x print-diary-entries'. It sends the data directly to
2951 the printer. You can customize it like `lpr-region' (*note Hardcopy::).
2953 The command `M-x diary' displays the diary entries for the current
2954 date, independently of the calendar display, and optionally for the next
2955 few days as well; the variable `number-of-diary-entries' specifies how
2956 many days to include (*note Customization::).
2958 If you put `(diary)' in your init file, this automatically displays
2959 a window with the day's diary entries, when you enter Emacs. *Note
2960 Init File::. The mode line of the displayed window shows the date and
2961 any holidays that fall on that date.
2963 Many users like to receive notice of events in their diary as email.
2964 To send such mail to yourself, use the command `M-x
2965 diary-mail-entries'. A prefix argument specifies how many days
2966 (starting with today) to check; otherwise, the variable
2967 `diary-mail-days' says how many days.
2970 File: xemacs.info, Node: Format of Diary File, Next: Date Formats, Prev: Diary Commands, Up: Diary
2972 26.5.4 The Diary File
2973 ---------------------
2975 Your "diary file" is a file that records events associated with
2976 particular dates. The name of the diary file is specified by the
2977 variable `diary-file'; `~/diary' is the default. The `calendar'
2978 utility program supports a subset of the format allowed by the Emacs
2979 diary facilities, so you can use that utility to view the diary file,
2980 with reasonable results aside from the entries it cannot understand.
2982 Each entry in the diary file describes one event and consists of one
2983 or more lines. An entry always begins with a date specification at the
2984 left margin. The rest of the entry is simply text to describe the
2985 event. If the entry has more than one line, then the lines after the
2986 first must begin with whitespace to indicate they continue a previous
2987 entry. Lines that do not begin with valid dates and do not continue a
2988 preceding entry are ignored.
2990 You can inhibit the marking of certain diary entries in the calendar
2991 window; to do this, insert an ampersand (`&') at the beginning of the
2992 entry, before the date. This has no effect on display of the entry in
2993 the diary window; it affects only marks on dates in the calendar
2994 window. Nonmarking entries are especially useful for generic entries
2995 that would otherwise mark many different dates.
2997 If the first line of a diary entry consists only of the date or day
2998 name with no following blanks or punctuation, then the diary window
2999 display doesn't include that line; only the continuation lines appear.
3000 For example, this entry:
3003 Bill B. visits Princeton today
3004 2pm Cognitive Studies Committee meeting
3005 2:30-5:30 Liz at Lawrenceville
3007 7:30pm Dinner at George's
3008 8:00-10:00pm concert
3010 appears in the diary window without the date line at the beginning.
3011 This style of entry looks neater when you display just a single day's
3012 entries, but can cause confusion if you ask for more than one day's
3015 You can edit the diary entries as they appear in the window, but it
3016 is important to remember that the buffer displayed contains the _entire_
3017 diary file, with portions of it concealed from view. This means, for
3018 instance, that the `C-f' (`forward-char') command can put point at what
3019 appears to be the end of the line, but what is in reality the middle of
3020 some concealed line.
3022 _Be careful when editing the diary entries!_ Inserting additional
3023 lines or adding/deleting characters in the middle of a visible line
3024 cannot cause problems, but editing at the end of a line may not do what
3025 you expect. Deleting a line may delete other invisible entries that
3026 follow it. Before editing the diary, it is best to display the entire
3027 file with `s' (`show-all-diary-entries').
3030 File: xemacs.info, Node: Date Formats, Next: Adding to Diary, Prev: Format of Diary File, Up: Diary
3035 Here are some sample diary entries, illustrating different ways of
3036 formatting a date. The examples all show dates in American order
3037 (month, day, year), but Calendar mode supports European order (day,
3038 month, year) as an option.
3040 4/20/93 Switch-over to new tabulation system
3041 apr. 25 Start tabulating annual results
3042 4/30 Results for April are due
3043 */25 Monthly cycle finishes
3044 Friday Don't leave without backing up files
3046 The first entry appears only once, on April 20, 1993. The second and
3047 third appear every year on the specified dates, and the fourth uses a
3048 wildcard (asterisk) for the month, so it appears on the 25th of every
3049 month. The final entry appears every week on Friday.
3051 You can use just numbers to express a date, as in `MONTH/DAY' or
3052 `MONTH/DAY/YEAR'. This must be followed by a nondigit. In the date
3053 itself, MONTH and DAY are numbers of one or two digits. The optional
3054 YEAR is also a number, and may be abbreviated to the last two digits;
3055 that is, you can use `11/12/1989' or `11/12/89'.
3057 Dates can also have the form `MONTHNAME DAY' or `MONTHNAME DAY,
3058 YEAR', where the month's name can be spelled in full or abbreviated to
3059 three characters (with or without a period). Case is not significant.
3061 A date may be "generic"; that is, partially unspecified. Then the
3062 entry applies to all dates that match the specification. If the date
3063 does not contain a year, it is generic and applies to any year.
3064 Alternatively, MONTH, DAY, or YEAR can be a `*'; this matches any
3065 month, day, or year, respectively. Thus, a diary entry `3/*/*' matches
3066 any day in March of any year; so does `march *'.
3068 If you prefer the European style of writing dates--in which the day
3069 comes before the month--type `M-x european-calendar' while in the
3070 calendar, or set the variable `european-calendar-style' to `t' _before_
3071 using any calendar or diary command. This mode interprets all dates in
3072 the diary in the European manner, and also uses European style for
3073 displaying diary dates. (Note that there is no comma after the
3074 MONTHNAME in the European style.) To go back to the (default) American
3075 style of writing dates, type `M-x american-calendar'.
3077 You can use the name of a day of the week as a generic date which
3078 applies to any date falling on that day of the week. You can abbreviate
3079 the day of the week to three letters (with or without a period) or spell
3080 it in full; case is not significant.
3083 File: xemacs.info, Node: Adding to Diary, Next: Special Diary Entries, Prev: Date Formats, Up: Diary
3085 26.5.6 Commands to Add to the Diary
3086 -----------------------------------
3088 While in the calendar, there are several commands to create diary
3092 Add a diary entry for the selected date (`insert-diary-entry').
3095 Add a diary entry for the selected day of the week
3096 (`insert-weekly-diary-entry').
3099 Add a diary entry for the selected day of the month
3100 (`insert-monthly-diary-entry').
3103 Add a diary entry for the selected day of the year
3104 (`insert-yearly-diary-entry').
3106 You can make a diary entry for a specific date by selecting that date
3107 in the calendar window and typing the `i d' command. This command
3108 displays the end of your diary file in another window and inserts the
3109 date; you can then type the rest of the diary entry.
3111 If you want to make a diary entry that applies to a specific day of
3112 the week, select that day of the week (any occurrence will do) and type
3113 `i w'. This inserts the day-of-week as a generic date; you can then
3114 type the rest of the diary entry. You can make a monthly diary entry in
3115 the same fashion. Select the day of the month, use the `i m' command,
3116 and type rest of the entry. Similarly, you can insert a yearly diary
3117 entry with the `i y' command.
3119 All of the above commands make marking diary entries by default. To
3120 make a nonmarking diary entry, give a numeric argument to the command.
3121 For example, `C-u i w' makes a nonmarking weekly diary entry.
3123 When you modify the diary file, be sure to save the file before
3127 File: xemacs.info, Node: Special Diary Entries, Prev: Adding to Diary, Up: Diary
3129 26.5.7 Special Diary Entries
3130 ----------------------------
3132 In addition to entries based on calendar dates, the diary file can
3133 contain "sexp entries" for regular events such as anniversaries. These
3134 entries are based on Lisp expressions (sexps) that Emacs evaluates as
3135 it scans the diary file. Instead of a date, a sexp entry contains `%%'
3136 followed by a Lisp expression which must begin and end with
3137 parentheses. The Lisp expression determines which dates the entry
3140 Calendar mode provides commands to insert certain commonly used sexp
3144 Add an anniversary diary entry for the selected date
3145 (`insert-anniversary-diary-entry').
3148 Add a block diary entry for the current region
3149 (`insert-block-diary-entry').
3152 Add a cyclic diary entry starting at the date
3153 (`insert-cyclic-diary-entry').
3155 If you want to make a diary entry that applies to the anniversary of
3156 a specific date, move point to that date and use the `i a' command.
3157 This displays the end of your diary file in another window and inserts
3158 the anniversary description; you can then type the rest of the diary
3159 entry. The entry looks like this:
3161 The effect of `i a' is to add a `diary-anniversary' sexp to your
3162 diary file. You can also add one manually, for instance:
3164 %%(diary-anniversary 10 31 1948) Arthur's birthday
3166 This entry applies to October 31 in any year after 1948; `10 31 1948'
3167 specifies the date. (If you are using the European calendar style, the
3168 month and day are interchanged.) The reason this expression requires a
3169 beginning year is that advanced diary functions can use it to calculate
3170 the number of elapsed years.
3172 A "block" diary entry applies to a specified range of consecutive
3173 dates. Here is a block diary entry that applies to all dates from June
3174 24, 1990 through July 10, 1990:
3176 %%(diary-block 6 24 1990 7 10 1990) Vacation
3178 The `6 24 1990' indicates the starting date and the `7 10 1990'
3179 indicates the stopping date. (Again, if you are using the European
3180 calendar style, the month and day are interchanged.)
3182 To insert a block entry, place point and the mark on the two dates
3183 that begin and end the range, and type `i b'. This command displays
3184 the end of your diary file in another window and inserts the block
3185 description; you can then type the diary entry.
3187 "Cyclic" diary entries repeat after a fixed interval of days. To
3188 create one, select the starting date and use the `i c' command. The
3189 command prompts for the length of interval, then inserts the entry,
3190 which looks like this:
3192 %%(diary-cyclic 50 3 1 1990) Renew medication
3194 This entry applies to March 1, 1990 and every 50th day following; `3 1
3195 1990' specifies the starting date. (If you are using the European
3196 calendar style, the month and day are interchanged.)
3198 All three of these commands make marking diary entries. To insert a
3199 nonmarking entry, give a numeric argument to the command. For example,
3200 `C-u i a' makes a nonmarking anniversary diary entry.
3202 Marking sexp diary entries in the calendar is _extremely_
3203 time-consuming, since every date visible in the calendar window must be
3204 individually checked. So it's a good idea to make sexp diary entries
3205 nonmarking (with `&') when possible.
3207 Another sophisticated kind of sexp entry, a "floating" diary entry,
3208 specifies a regularly occurring event by offsets specified in days,
3209 weeks, and months. It is comparable to a crontab entry interpreted by
3210 the `cron' utility. Here is a nonmarking, floating diary entry that
3211 applies to the last Thursday in November:
3213 &%%(diary-float 11 4 -1) American Thanksgiving
3215 The 11 specifies November (the eleventh month), the 4 specifies Thursday
3216 (the fourth day of the week, where Sunday is numbered zero), and the -1
3217 specifies "last" (1 would mean "first", 2 would mean "second", -2 would
3218 mean "second-to-last", and so on). The month can be a single month or
3219 a list of months. Thus you could change the 11 above to `'(1 2 3)' and
3220 have the entry apply to the last Thursday of January, February, and
3221 March. If the month is `t', the entry applies to all months of the
3224 The sexp feature of the diary allows you to specify diary entries
3225 based on any Emacs Lisp expression. You can use the library of built-in
3226 functions or you can write your own functions. The built-in functions
3227 include the ones shown in this section, plus a few others (*note Sexp
3230 The generality of sexps lets you specify any diary entry that you can
3231 describe algorithmically. Suppose you get paid on the 21st of the month
3232 if it is a weekday, and to the Friday before if the 21st is on a
3233 weekend. The diary entry
3235 &%%(let ((dayname (calendar-day-of-week date))
3236 (day (car (cdr date))))
3237 (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
3238 (and (memq day '(19 20)) (= dayname 5)))
3239 ) Pay check deposited
3241 to just those dates. This example illustrates how the sexp can depend
3242 on the variable `date'; this variable is a list (MONTH DAY YEAR) that
3243 gives the Gregorian date for which the diary entries are being found.
3244 If the value of the sexp is `t', the entry applies to that date. If
3245 the sexp evaluates to `nil', the entry does _not_ apply to that date.
3248 File: xemacs.info, Node: Calendar Customization, Prev: Diary, Up: Calendar/Diary
3250 26.5.8 Customizing the Calendar and Diary
3251 -----------------------------------------
3253 There are many customizations that you can use to make the calendar and
3254 diary suit your personal tastes.
3258 * Calendar Customizing:: Defaults you can set.
3259 * Holiday Customizing:: Defining your own holidays.
3260 * Date Display Format:: Changing the format.
3261 * Time Display Format:: Changing the format.
3262 * Daylight Savings:: Changing the default.
3263 * Diary Customizing:: Defaults you can set.
3264 * Hebrew/Islamic Entries:: How to obtain them.
3265 * Fancy Diary Display:: Enhancing the diary display, sorting entries.
3266 * Included Diary Files:: Sharing a common diary file.
3267 * Sexp Diary Entries:: Fancy things you can do.
3268 * Appt Customizing:: Customizing appointment reminders.
3271 File: xemacs.info, Node: Calendar Customizing, Next: Holiday Customizing, Up: Calendar Customization
3273 26.5.8.1 Customizing the Calendar
3274 .................................
3276 If you set the variable `view-diary-entries-initially' to `t', calling
3277 up the calendar automatically displays the diary entries for the
3278 current date as well. The diary dates appear only if the current date
3279 is visible. If you add both of the following lines to your init file:
3281 (setq view-diary-entries-initially t)
3284 this displays both the calendar and diary windows whenever you start
3285 Emacs. *Note Init File::.
3287 Similarly, if you set the variable
3288 `view-calendar-holidays-initially' to `t', entering the calendar
3289 automatically displays a list of holidays for the current three-month
3290 period. The holiday list appears in a separate window.
3292 You can set the variable `mark-diary-entries-in-calendar' to `t' in
3293 order to mark any dates with diary entries. This takes effect whenever
3294 the calendar window contents are recomputed. There are two ways of
3295 marking these dates: by changing the face (*note Faces::), if the
3296 display supports that, or by placing a plus sign (`+') beside the date
3299 Similarly, setting the variable `mark-holidays-in-calendar' to `t'
3300 marks holiday dates, either with a change of face or with an asterisk
3303 The variable `calendar-holiday-marker' specifies how to mark a date
3304 as being a holiday. Its value may be a character to insert next to the
3305 date, or a face name to use for displaying the date. Likewise, the
3306 variable `diary-entry-marker' specifies how to mark a date that has
3307 diary entries. The calendar creates faces named `holiday-face' and
3308 `diary-face' for these purposes; those symbols are the default values
3309 of these variables, when Emacs supports multiple faces on your terminal.
3311 The variable `calendar-load-hook' is a normal hook run when the
3312 calendar package is first loaded (before actually starting to display
3315 Starting the calendar runs the normal hook
3316 `initial-calendar-window-hook'. Recomputation of the calendar display
3317 does not run this hook. But if you leave the calendar with the `q'
3318 command and reenter it, the hook runs again.
3320 The variable `today-visible-calendar-hook' is a normal hook run
3321 after the calendar buffer has been prepared with the calendar when the
3322 current date is visible in the window. One use of this hook is to
3323 replace today's date with asterisks; to do that, use the hook function
3324 `calendar-star-date'.
3326 (add-hook 'today-visible-calendar-hook 'calendar-star-date)
3328 Another standard hook function marks the current date, either by
3329 changing its face or by adding an asterisk. Here's how to use it:
3331 (add-hook 'today-visible-calendar-hook 'calendar-mark-today)
3333 The variable `calendar-today-marker' specifies how to mark today's
3334 date. Its value should be a character to insert next to the date or a
3335 face name to use for displaying the date. A face named
3336 `calendar-today-face' is provided for this purpose; that symbol is the
3337 default for this variable when Emacs supports multiple faces on your
3340 A similar normal hook, `today-invisible-calendar-hook' is run if the
3341 current date is _not_ visible in the window.
3344 File: xemacs.info, Node: Holiday Customizing, Next: Date Display Format, Prev: Calendar Customizing, Up: Calendar Customization
3346 26.5.8.2 Customizing the Holidays
3347 .................................
3349 Emacs knows about holidays defined by entries on one of several lists.
3350 You can customize these lists of holidays to your own needs, adding or
3351 deleting holidays. The lists of holidays that Emacs uses are for
3352 general holidays (`general-holidays'), local holidays
3353 (`local-holidays'), Christian holidays (`christian-holidays'), Hebrew
3354 (Jewish) holidays (`hebrew-holidays'), Islamic (Moslem) holidays
3355 (`islamic-holidays'), and other holidays (`other-holidays').
3357 The general holidays are, by default, holidays common throughout the
3358 United States. To eliminate these holidays, set `general-holidays' to
3361 There are no default local holidays (but sites may supply some). You
3362 can set the variable `local-holidays' to any list of holidays, as
3365 By default, Emacs does not include all the holidays of the religions
3366 that it knows, only those commonly found in secular calendars. For a
3367 more extensive collection of religious holidays, you can set any (or
3368 all) of the variables `all-christian-calendar-holidays',
3369 `all-hebrew-calendar-holidays', or `all-islamic-calendar-holidays' to
3370 `t'. If you want to eliminate the religious holidays, set any or all
3371 of the corresponding variables `christian-holidays', `hebrew-holidays',
3372 and `islamic-holidays' to `nil'.
3374 You can set the variable `other-holidays' to any list of holidays.
3375 This list, normally empty, is intended for individual use.
3377 Each of the lists (`general-holidays', `local-holidays',
3378 `christian-holidays', `hebrew-holidays', `islamic-holidays', and
3379 `other-holidays') is a list of "holiday forms", each holiday form
3380 describing a holiday (or sometimes a list of holidays).
3382 Here is a table of the possible kinds of holiday form. Day numbers
3383 and month numbers count starting from 1, but "dayname" numbers count
3384 Sunday as 0. The element STRING is always the name of the holiday, as
3387 `(holiday-fixed MONTH DAY STRING)'
3388 A fixed date on the Gregorian calendar. MONTH and DAY are
3389 numbers, STRING is the name of the holiday.
3391 `(holiday-float MONTH DAYNAME K STRING)'
3392 The Kth DAYNAME in MONTH on the Gregorian calendar (DAYNAME=0 for
3393 Sunday, and so on); negative K means count back from the end of
3394 the month. STRING is the name of the holiday.
3396 `(holiday-hebrew MONTH DAY STRING)'
3397 A fixed date on the Hebrew calendar. MONTH and DAY are numbers,
3398 STRING is the name of the holiday.
3400 `(holiday-islamic MONTH DAY STRING)'
3401 A fixed date on the Islamic calendar. MONTH and DAY are numbers,
3402 STRING is the name of the holiday.
3404 `(holiday-julian MONTH DAY STRING)'
3405 A fixed date on the Julian calendar. MONTH and DAY are numbers,
3406 STRING is the name of the holiday.
3408 `(holiday-sexp SEXP STRING)'
3409 A date calculated by the Lisp expression SEXP. The expression
3410 should use the variable `year' to compute and return the date of a
3411 holiday, or `nil' if the holiday doesn't happen this year. The
3412 value of SEXP must represent the date as a list of the form
3413 `(MONTH DAY YEAR)'. STRING is the name of the holiday.
3415 `(if CONDITION HOLIDAY-FORM &optional HOLIDAY-FORM)'
3416 A holiday that happens only if CONDITION is true.
3419 A list of dates calculated by the function FUNCTION, called with
3422 For example, suppose you want to add Bastille Day, celebrated in
3423 France on July 14. You can do this by adding the following line to
3426 (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
3430 The holiday form `(holiday-fixed 7 14 "Bastille Day")' specifies the
3431 fourteenth day of the seventh month (July).
3433 Many holidays occur on a specific day of the week, at a specific time
3434 of month. Here is a holiday form describing Hurricane Supplication Day,
3435 celebrated in the Virgin Islands on the fourth Monday in August:
3437 (holiday-float 8 1 4 "Hurricane Supplication Day")
3439 Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
3440 Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
3441 the month (1 specifies the first occurrence, 2 the second occurrence,
3442 -1 the last occurrence, -2 the second-to-last occurrence, and so on).
3444 You can specify holidays that occur on fixed days of the Hebrew,
3445 Islamic, and Julian calendars too. For example,
3447 (setq other-holidays
3448 '((holiday-hebrew 10 2 "Last day of Hanukkah")
3449 (holiday-islamic 3 12 "Mohammed's Birthday")
3450 (holiday-julian 4 2 "Jefferson's Birthday")))
3452 adds the last day of Hanukkah (since the Hebrew months are numbered with
3453 1 starting from Nisan), the Islamic feast celebrating Mohammed's
3454 birthday (since the Islamic months are numbered from 1 starting with
3455 Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
3458 To include a holiday conditionally, use either Emacs Lisp's `if' or
3459 the `holiday-sexp' form. For example, American presidential elections
3460 occur on the first Tuesday after the first Monday in November of years
3463 (holiday-sexp (if (= 0 (% year 4))
3464 (calendar-gregorian-from-absolute
3465 (1+ (calendar-dayname-on-or-before
3466 1 (+ 6 (calendar-absolute-from-gregorian
3467 (list 11 1 year))))))
3468 "US Presidential Election"))
3472 (if (= 0 (% displayed-year 4))
3474 (extract-calendar-day
3475 (calendar-gregorian-from-absolute
3476 (1+ (calendar-dayname-on-or-before
3477 1 (+ 6 (calendar-absolute-from-gregorian
3478 (list 11 1 displayed-year)))))))
3479 "US Presidential Election"))
3481 Some holidays just don't fit into any of these forms because special
3482 calculations are involved in their determination. In such cases you
3483 must write a Lisp function to do the calculation. To include eclipses,
3484 for example, add `(eclipses)' to `other-holidays' and write an Emacs
3485 Lisp function `eclipses' that returns a (possibly empty) list of the
3486 relevant Gregorian dates among the range visible in the calendar
3487 window, with descriptive strings, like this:
3489 (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
3492 File: xemacs.info, Node: Date Display Format, Next: Time Display Format, Prev: Holiday Customizing, Up: Calendar Customization
3494 26.5.8.3 Date Display Format
3495 ............................
3497 You can customize the manner of displaying dates in the diary, in mode
3498 lines, and in messages by setting `calendar-date-display-form'. This
3499 variable holds a list of expressions that can involve the variables
3500 `month', `day', and `year', which are all numbers in string form, and
3501 `monthname' and `dayname', which are both alphabetic strings. In the
3502 American style, the default value of this list is as follows:
3504 ((if dayname (concat dayname ", ")) monthname " " day ", " year)
3506 while in the European style this value is the default:
3508 ((if dayname (concat dayname ", ")) day " " monthname " " year)
3510 +The ISO standard date representation is this:
3512 (year "-" month "-" day)
3514 This specifies a typical American format:
3516 (month "/" day "/" (substring year -2))
3519 File: xemacs.info, Node: Time Display Format, Next: Daylight Savings, Prev: Date Display Format, Up: Calendar Customization
3521 26.5.8.4 Time Display Format
3522 ............................
3524 The calendar and diary by default display times of day in the
3525 conventional American style with the hours from 1 through 12, minutes,
3526 and either `am' or `pm'. If you prefer the European style, also known
3527 in the US as military, in which the hours go from 00 to 23, you can
3528 alter the variable `calendar-time-display-form'. This variable is a
3529 list of expressions that can involve the variables `12-hours',
3530 `24-hours', and `minutes', which are all numbers in string form, and
3531 `am-pm' and `time-zone', which are both alphabetic strings. The
3532 default value of `calendar-time-display-form' is as follows:
3534 (12-hours ":" minutes am-pm
3535 (if time-zone " (") time-zone (if time-zone ")"))
3537 Here is a value that provides European style times:
3539 (24-hours ":" minutes
3540 (if time-zone " (") time-zone (if time-zone ")"))
3542 gives military-style times like `21:07 (UT)' if time zone names are
3543 defined, and times like `21:07' if they are not.
3546 File: xemacs.info, Node: Daylight Savings, Next: Diary Customizing, Prev: Time Display Format, Up: Calendar Customization
3548 26.5.8.5 Daylight Savings Time
3549 ..............................
3551 Emacs understands the difference between standard time and daylight
3552 savings time--the times given for sunrise, sunset, solstices,
3553 equinoxes, and the phases of the moon take that into account. The rules
3554 for daylight savings time vary from place to place and have also varied
3555 historically from year to year. To do the job properly, Emacs needs to
3556 know which rules to use.
3558 Some operating systems keep track of the rules that apply to the
3559 place where you are; on these systems, Emacs gets the information it
3560 needs from the system automatically. If some or all of this
3561 information is missing, Emacs fills in the gaps with the rules
3562 currently used in Cambridge, Massachusetts. If the resulting rules are
3563 not what you want, you can tell Emacs the rules to use by setting
3566 If the default choice of rules is not appropriate for your location,
3567 you can tell Emacs the rules to use by setting the variables
3568 `calendar-daylight-savings-starts' and
3569 `calendar-daylight-savings-ends'. Their values should be Lisp
3570 expressions that refer to the variable `year', and evaluate to the
3571 Gregorian date on which daylight savings time starts or (respectively)
3572 ends, in the form of a list `(MONTH DAY YEAR)'. The values should be
3573 `nil' if your area does not use daylight savings time.
3575 Emacs uses these expressions to determine the starting date of
3576 daylight savings time for the holiday list and for correcting times of
3577 day in the solar and lunar calculations.
3579 The values for Cambridge, Massachusetts are as follows:
3581 (calendar-nth-named-day 1 0 4 year)
3582 (calendar-nth-named-day -1 0 10 year)
3584 That is, the first 0th day (Sunday) of the fourth month (April) in the
3585 year specified by `year', and the last Sunday of the tenth month
3586 (October) of that year. If daylight savings time were changed to start
3587 on October 1, you would set `calendar-daylight-savings-starts' to this:
3591 For a more complex example, suppose daylight savings time begins on
3592 the first of Nisan on the Hebrew calendar. You should set
3593 `calendar-daylight-savings-starts' to this value:
3595 (calendar-gregorian-from-absolute
3596 (calendar-absolute-from-hebrew
3597 (list 1 1 (+ year 3760))))
3599 because Nisan is the first month in the Hebrew calendar and the Hebrew
3600 year differs from the Gregorian year by 3760 at Nisan.
3602 If there is no daylight savings time at your location, or if you want
3603 all times in standard time, set `calendar-daylight-savings-starts' and
3604 `calendar-daylight-savings-ends' to `nil'.
3606 The variable `calendar-daylight-time-offset' specifies the
3607 difference between daylight savings time and standard time, measured in
3608 minutes. The value for Cambridge, Massachusetts is 60.
3610 The two variables `calendar-daylight-savings-starts-time' and
3611 `calendar-daylight-savings-ends-time' specify the number of minutes
3612 after midnight local time when the transition to and from daylight
3613 savings time should occur. For Cambridge, Massachusetts both variables'
3617 File: xemacs.info, Node: Diary Customizing, Next: Hebrew/Islamic Entries, Prev: Daylight Savings, Up: Calendar Customization
3619 26.5.8.6 Customizing the Diary
3620 ..............................
3622 Ordinarily, the mode line of the diary buffer window indicates any
3623 holidays that fall on the date of the diary entries. The process of
3624 checking for holidays can take several seconds, so including holiday
3625 information delays the display of the diary buffer noticeably. If you'd
3626 prefer to have a faster display of the diary buffer but without the
3627 holiday information, set the variable `holidays-in-diary-buffer' to
3630 The variable `number-of-diary-entries' controls the number of days
3631 of diary entries to be displayed at one time. It affects the initial
3632 display when `view-diary-entries-initially' is `t', as well as the
3633 command `M-x diary'. For example, the default value is 1, which says
3634 to display only the current day's diary entries. If the value is 2,
3635 both the current day's and the next day's entries are displayed. The
3636 value can also be a vector of seven elements: for example, if the value
3637 is `[0 2 2 2 2 4 1]' then no diary entries appear on Sunday, the
3638 current date's and the next day's diary entries appear Monday through
3639 Thursday, Friday through Monday's entries appear on Friday, while on
3640 Saturday only that day's entries appear.
3642 The variable `print-diary-entries-hook' is a normal hook run after
3643 preparation of a temporary buffer containing just the diary entries
3644 currently visible in the diary buffer. (The other, irrelevant diary
3645 entries are really absent from the temporary buffer; in the diary
3646 buffer, they are merely hidden.) The default value of this hook does
3647 the printing with the command `lpr-buffer'. If you want to use a
3648 different command to do the printing, just change the value of this
3649 hook. Other uses might include, for example, rearranging the lines into
3650 order by day and time.
3652 You can customize the form of dates in your diary file, if neither
3653 the standard American nor European styles suits your needs, by setting
3654 the variable `diary-date-forms'. This variable is a list of patterns
3655 for recognizing a date. Each date pattern is a list whose elements may
3656 be regular expressions (*note Regexps::) or the symbols `month', `day',
3657 `year', `monthname', and `dayname'. All these elements serve as
3658 patterns that match certain kinds of text in the diary file. In order
3659 for the date pattern, as a whole, to match, all of its elements must
3660 match consecutively.
3662 A regular expression in a date pattern matches in its usual fashion,
3663 using the standard syntax table altered so that `*' is a word
3666 The symbols `month', `day', `year', `monthname', and `dayname' match
3667 the month number, day number, year number, month name, and day name of
3668 the date being considered. The symbols that match numbers allow
3669 leading zeros; those that match names allow three-letter abbreviations
3670 and capitalization. All the symbols can match `*'; since `*' in a
3671 diary entry means "any day", "any month", and so on, it should match
3672 regardless of the date being considered.
3674 The default value of `diary-date-forms' in the American style is
3677 ((month "/" day "[^/0-9]")
3678 (month "/" day "/" year "[^0-9]")
3679 (monthname " *" day "[^,0-9]")
3680 (monthname " *" day ", *" year "[^0-9]")
3683 Emacs matches of the diary entries with the date forms is done with the
3684 standard syntax table from Fundamental mode (*note Syntax Tables:
3685 (lispref)Syntax Tables.), but with the `*' changed so that it is a word
3688 The date patterns in the list must be _mutually exclusive_ and must
3689 not match any portion of the diary entry itself, just the date and one
3690 character of whitespace. If, to be mutually exclusive, the pattern
3691 must match a portion of the diary entry text--beyond the whitespace
3692 that ends the date--then the first element of the date pattern _must_
3693 be `backup'. This causes the date recognizer to back up to the
3694 beginning of the current word of the diary entry, after finishing the
3695 match. Even if you use `backup', the date pattern must absolutely not
3696 match more than a portion of the first word of the diary entry. The
3697 default value of `diary-date-forms' in the European style is this list:
3699 ((day "/" month "[^/0-9]")
3700 (day "/" month "/" year "[^0-9]")
3701 (backup day " *" monthname "\\W+\\<[^*0-9]")
3702 (day " *" monthname " *" year "[^0-9]")
3705 Notice the use of `backup' in the third pattern, because it needs to
3706 match part of a word beyond the date itself to distinguish it from the
3710 File: xemacs.info, Node: Hebrew/Islamic Entries, Next: Fancy Diary Display, Prev: Diary Customizing, Up: Calendar Customization
3712 26.5.8.7 Hebrew- and Islamic-Date Diary Entries
3713 ...............................................
3715 Your diary file can have entries based on Hebrew or Islamic dates, as
3716 well as entries based on the world-standard Gregorian calendar.
3717 However, because recognition of such entries is time-consuming and most
3718 people don't use them, you must explicitly enable their use. If you
3719 want the diary to recognize Hebrew-date diary entries, for example, you
3722 (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
3723 (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
3725 If you want Islamic-date entries, do this:
3727 (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
3728 (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
3730 Hebrew- and Islamic-date diary entries have the same formats as
3731 Gregorian-date diary entries, except that `H' precedes a Hebrew date
3732 and `I' precedes an Islamic date. Moreover, because the Hebrew and
3733 Islamic month names are not uniquely specified by the first three
3734 letters, you may not abbreviate them. For example, a diary entry for
3735 the Hebrew date Heshvan 25 could look like this:
3737 HHeshvan 25 Happy Hebrew birthday!
3739 and would appear in the diary for any date that corresponds to Heshvan
3740 25 on the Hebrew calendar. And here is Islamic-date diary entry that
3741 matches Dhu al-Qada 25:
3743 IDhu al-Qada 25 Happy Islamic birthday!
3745 and would appear in the diary for any date that corresponds to Dhu
3746 al-Qada 25 on the Islamic calendar.
3748 As with Gregorian-date diary entries, Hebrew- and Islamic-date
3749 entries are nonmarking if they are preceded with an ampersand (`&').
3751 Here is a table of commands used in the calendar to create diary
3752 entries that match the selected date and other dates that are similar
3753 in the Hebrew or Islamic calendar:
3756 Add a diary entry for the Hebrew date corresponding to the
3757 selected date (`insert-hebrew-diary-entry').
3760 Add a diary entry for the day of the Hebrew month corresponding to
3761 the selected date (`insert-monthly-hebrew-diary-entry'). This
3762 diary entry matches any date that has the same Hebrew
3763 day-within-month as the selected date.
3766 Add a diary entry for the day of the Hebrew year corresponding to
3767 the selected date (`insert-yearly-hebrew-diary-entry'). This diary
3768 entry matches any date which has the same Hebrew month and
3769 day-within-month as the selected date.
3772 Add a diary entry for the Islamic date corresponding to the
3773 selected date (`insert-islamic-diary-entry').
3776 Add a diary entry for the day of the Islamic month corresponding
3777 to the selected date (`insert-monthly-islamic-diary-entry').
3780 Add a diary entry for the day of the Islamic year corresponding to
3781 the selected date (`insert-yearly-islamic-diary-entry').
3783 These commands work much like the corresponding commands for ordinary
3784 diary entries: they apply to the date that point is on in the calendar
3785 window, and what they do is insert just the date portion of a diary
3786 entry at the end of your diary file. You must then insert the rest of
3790 File: xemacs.info, Node: Fancy Diary Display, Next: Included Diary Files, Prev: Hebrew/Islamic Entries, Up: Calendar Customization
3792 26.5.8.8 Fancy Diary Display
3793 ............................
3795 Diary display works by preparing the diary buffer and then running the
3796 hook `diary-display-hook'. The default value of this hook
3797 (`simple-diary-display') hides the irrelevant diary entries and then
3798 displays the buffer. However, if you specify the hook as follows,
3800 (add-hook 'diary-display-hook 'fancy-diary-display)
3802 this enables fancy diary display. It displays diary entries and
3803 holidays by copying them into a special buffer that exists only for the
3804 sake of display. Copying to a separate buffer provides an opportunity
3805 to change the displayed text to make it prettier--for example, to sort
3806 the entries by the dates they apply to.
3808 As with simple diary display, you can print a hard copy of the buffer
3809 with `print-diary-entries'. To print a hard copy of a day-by-day diary
3810 for a week by positioning point on Sunday of that week, type `7 d' and
3811 then do `M-x print-diary-entries'. As usual, the inclusion of the
3812 holidays slows down the display slightly; you can speed things up by
3813 setting the variable `holidays-in-diary-buffer' to `nil'.
3815 Ordinarily, the fancy diary buffer does not show days for which
3816 there are no diary entries, even if that day is a holiday. If you want
3817 such days to be shown in the fancy diary buffer, set the variable
3818 `diary-list-include-blanks' to `t'.
3820 If you use the fancy diary display, you can use the normal hook
3821 `list-diary-entries-hook' to sort each day's diary entries by their
3822 time of day. Add this line to your init file:
3824 (add-hook 'list-diary-entries-hook 'sort-diary-entries t)
3828 For each day, this sorts diary entries that begin with a recognizable
3829 time of day according to their times. Diary entries without times come
3830 first within each day.
3833 File: xemacs.info, Node: Included Diary Files, Next: Sexp Diary Entries, Prev: Fancy Diary Display, Up: Calendar Customization
3835 26.5.8.9 Included Diary Files
3836 .............................
3838 Fancy diary display also has the ability to process included diary
3839 files. This permits a group of people to share a diary file for events
3840 that apply to all of them. Lines in the diary file of this form:
3844 includes the diary entries from the file FILENAME in the fancy diary
3845 buffer. The include mechanism is recursive, so that included files can
3846 include other files, and so on; you must be careful not to have a cycle
3847 of inclusions, of course. Here is how to enable the include facility:
3849 (add-hook 'list-diary-entries-hook 'include-other-diary-files)
3850 (add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
3852 The include mechanism works only with the fancy diary display,
3853 because ordinary diary display shows the entries directly from your
3857 File: xemacs.info, Node: Sexp Diary Entries, Next: Appt Customizing, Prev: Included Diary Files, Up: Calendar Customization
3859 26.5.8.10 Sexp Entries and the Fancy Diary Display
3860 ..................................................
3862 Sexp diary entries allow you to do more than just have complicated
3863 conditions under which a diary entry applies. If you use the fancy
3864 diary display, sexp entries can generate the text of the entry depending
3865 on the date itself. For example, an anniversary diary entry can insert
3866 the number of years since the anniversary date into the text of the
3867 diary entry. Thus the `%d' in this dairy entry:
3869 %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
3871 gets replaced by the age, so on October 31, 1990 the entry appears in
3872 the fancy diary buffer like this:
3874 Arthur's birthday (42 years old)
3876 If the diary file instead contains this entry:
3878 %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
3880 the entry in the fancy diary buffer for October 31, 1990 appears like
3883 Arthur's 42nd birthday
3885 Similarly, cyclic diary entries can interpolate the number of
3886 repetitions that have occurred:
3888 %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
3892 Renew medication (5th time)
3894 in the fancy diary display on September 8, 1990.
3896 The generality of sexp diary entries lets you specify any diary entry
3897 that you can describe algorithmically. A sexp diary entry contains an
3898 expression that computes whether the entry applies to any given date.
3899 If its value is non-`nil', the entry applies to that date; otherwise,
3900 it does not. The expression can use the variable `date' to find the
3901 date being considered; its value is a list (MONTH DAY YEAR) that refers
3902 to the Gregorian calendar.
3904 Suppose you get paid on the 21st of the month if it is a weekday, and
3905 on the Friday before if the 21st is on a weekend. Here is how to write
3906 a sexp diary entry that matches those dates:
3908 &%%(let ((dayname (calendar-day-of-week date))
3909 (day (car (cdr date))))
3910 (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
3911 (and (memq day '(19 20)) (= dayname 5)))
3912 ) Pay check deposited
3914 applies to just those dates. This example illustrates how the sexp can
3915 depend on the variable `date'; this variable is a list (MONTH DAY YEAR)
3916 that gives the Gregorian date for which the diary entries are being
3917 found. If the value of the expression is `t', the entry applies to
3918 that date. If the expression evaluates to `nil', the entry does _not_
3921 The following sexp diary entries take advantage of the ability (in
3922 the fancy diary display) to concoct diary entries whose text varies
3925 `%%(diary-sunrise-sunset)'
3926 Make a diary entry for the local times of today's sunrise and
3929 `%%(diary-phases-of-moon)'
3930 Make a diary entry for the phases (quarters) of the moon.
3932 `%%(diary-day-of-year)'
3933 Make a diary entry with today's day number in the current year and
3934 the number of days remaining in the current year.
3936 `%%(diary-iso-date)'
3937 Make a diary entry with today's equivalent ISO commercial date.
3939 `%%(diary-julian-date)'
3940 Make a diary entry with today's equivalent date on the Julian
3943 `%%(diary-astro-day-number)'
3944 Make a diary entry with today's equivalent astronomical (Julian)
3947 `%%(diary-hebrew-date)'
3948 Make a diary entry with today's equivalent date on the Hebrew
3951 `%%(diary-islamic-date)'
3952 Make a diary entry with today's equivalent date on the Islamic
3955 `%%(diary-french-date)'
3956 Make a diary entry with today's equivalent date on the French
3957 Revolutionary calendar.
3959 `%%(diary-mayan-date)'
3960 Make a diary entry with today's equivalent date on the Mayan
3963 Thus including the diary entry
3965 &%%(diary-hebrew-date)
3967 causes every day's diary display to contain the equivalent date on the
3968 Hebrew calendar, if you are using the fancy diary display. (With simple
3969 diary display, the line `&%%(diary-hebrew-date)' appears in the diary
3970 for any date, but does nothing particularly useful.)
3972 These functions can be used to construct sexp diary entries based on
3973 the Hebrew calendar in certain standard ways:
3975 `%%(diary-rosh-hodesh)'
3976 Make a diary entry that tells the occurrence and ritual
3977 announcement of each new Hebrew month.
3980 Make a Saturday diary entry that tells the weekly synagogue
3983 `%%(diary-sabbath-candles)'
3984 Make a Friday diary entry that tells the _local time_ of Sabbath
3988 Make a diary entry that gives the omer count, when appropriate.
3990 `%%(diary-yahrzeit MONTH DAY YEAR) NAME'
3991 Make a diary entry marking the anniversary of a date of death.
3992 The date is the _Gregorian_ (civil) date of death. The diary
3993 entry appears on the proper Hebrew calendar anniversary and on the
3994 day before. (In the European style, the order of the parameters
3995 is changed to DAY, MONTH, YEAR.)
3998 File: xemacs.info, Node: Appt Customizing, Prev: Sexp Diary Entries, Up: Calendar Customization
4000 26.5.8.11 Customizing Appointment Reminders
4001 ...........................................
4003 You can specify exactly how Emacs reminds you of an appointment, and
4004 how far in advance it begins doing so, by setting these variables:
4006 `appt-message-warning-time'
4007 The time in minutes before an appointment that the reminder
4008 begins. The default is 10 minutes.
4011 If this is `t' (the default), Emacs rings the terminal bell for
4012 appointment reminders.
4015 If this is `t' (the default), Emacs displays the appointment
4016 message in echo area.
4018 `appt-display-mode-line'
4019 If this is `t' (the default), Emacs displays the number of minutes
4020 to the appointment on the mode line.
4023 If this is `t' (the default), Emacs displays the appointment
4024 message in another window.
4026 `appt-display-duration'
4027 The number of seconds an appointment message is displayed. The
4028 default is 5 seconds.
4031 File: xemacs.info, Node: Sorting, Next: Shell, Prev: Calendar/Diary, Up: Top
4036 XEmacs provides several commands for sorting text in a buffer. All
4037 operate on the contents of the region (the text between point and the
4038 mark). They divide the text of the region into many "sort records",
4039 identify a "sort key" for each record, and then reorder the records
4040 using the order determined by the sort keys. The records are ordered so
4041 that their keys are in alphabetical order, or, for numerical sorting, in
4042 numerical order. In alphabetical sorting, all upper-case letters `A'
4043 through `Z' come before lower-case `a', in accordance with the ASCII
4046 The sort commands differ in how they divide the text into sort
4047 records and in which part of each record they use as the sort key.
4048 Most of the commands make each line a separate sort record, but some
4049 commands use paragraphs or pages as sort records. Most of the sort
4050 commands use each entire sort record as its own sort key, but some use
4051 only a portion of the record as the sort key.
4054 Divide the region into lines and sort by comparing the entire text
4055 of a line. A prefix argument means sort in descending order.
4057 `M-x sort-paragraphs'
4058 Divide the region into paragraphs and sort by comparing the entire
4059 text of a paragraph (except for leading blank lines). A prefix
4060 argument means sort in descending order.
4063 Divide the region into pages and sort by comparing the entire text
4064 of a page (except for leading blank lines). A prefix argument
4065 means sort in descending order.
4068 Divide the region into lines and sort by comparing the contents of
4069 one field in each line. Fields are defined as separated by
4070 whitespace, so the first run of consecutive non-whitespace
4071 characters in a line constitutes field 1, the second such run
4072 constitutes field 2, etc.
4074 You specify which field to sort by with a numeric argument: 1 to
4075 sort by field 1, etc. A negative argument means sort in descending
4076 order. Thus, minus 2 means sort by field 2 in reverse-alphabetical
4079 `M-x sort-numeric-fields'
4080 Like `M-x sort-fields', except the specified field is converted to
4081 a number for each line and the numbers are compared. `10' comes
4082 before `2' when considered as text, but after it when considered
4086 Like `M-x sort-fields', except that the text within each line used
4087 for comparison comes from a fixed range of columns. An explanation
4090 For example, if the buffer contains:
4092 On systems where clash detection (locking of files being edited) is
4093 implemented, XEmacs also checks the first time you modify a buffer
4094 whether the file has changed on disk since it was last visited or
4095 saved. If it has, you are asked to confirm that you want to change
4098 then if you apply `M-x sort-lines' to the entire buffer you get:
4100 On systems where clash detection (locking of files being edited) is
4101 implemented, XEmacs also checks the first time you modify a buffer
4102 saved. If it has, you are asked to confirm that you want to change
4104 whether the file has changed on disk since it was last visited or
4106 where the upper case `O' comes before all lower case letters. If you
4107 apply instead `C-u 2 M-x sort-fields' you get:
4109 saved. If it has, you are asked to confirm that you want to change
4110 implemented, XEmacs also checks the first time you modify a buffer
4112 On systems where clash detection (locking of files being edited) is
4113 whether the file has changed on disk since it was last visited or
4115 where the sort keys were `If', `XEmacs', `buffer', `systems', and `the'.
4117 `M-x sort-columns' requires more explanation. You specify the
4118 columns by putting point at one of the columns and the mark at the other
4119 column. Because this means you cannot put point or the mark at the
4120 beginning of the first line to sort, this command uses an unusual
4121 definition of `region': all of the line point is in is considered part
4122 of the region, and so is all of the line the mark is in.
4124 For example, to sort a table by information found in columns 10 to
4125 15, you could put the mark on column 10 in the first line of the table,
4126 and point on column 15 in the last line of the table, and then use this
4127 command. Or you could put the mark on column 15 in the first line and
4128 point on column 10 in the last line.
4130 This can be thought of as sorting the rectangle specified by point
4131 and the mark, except that the text on each line to the left or right of
4132 the rectangle moves along with the text inside the rectangle. *Note
4136 File: xemacs.info, Node: Shell, Next: Narrowing, Prev: Sorting, Up: Top
4138 26.7 Running Shell Commands from XEmacs
4139 =======================================
4141 XEmacs has commands for passing single command lines to inferior shell
4142 processes; it can also run a shell interactively with input and output
4143 to an XEmacs buffer `*shell*'.
4146 Run a specified shell command line and display the output
4150 Run a specified shell command line with region contents as input;
4151 optionally replace the region with the output
4152 (`shell-command-on-region').
4155 Run a subshell with input and output through an XEmacs buffer.
4156 You can then give commands interactively.
4159 Run a subshell with input and output through an XEmacs buffer.
4160 You can then give commands interactively. Full terminal emulation
4165 * Single Shell:: How to run one shell command and return.
4166 * Interactive Shell:: Permanent shell taking input via XEmacs.
4167 * Shell Mode:: Special XEmacs commands used with permanent shell.
4168 * Terminal emulator:: An XEmacs window as a terminal emulator.
4169 * Term Mode:: Special XEmacs commands used in Term mode.
4170 * Paging in Term:: Paging in the terminal emulator.
4173 File: xemacs.info, Node: Single Shell, Next: Interactive Shell, Prev: Shell, Up: Shell
4175 26.7.1 Single Shell Commands
4176 ----------------------------
4178 `M-!' (`shell-command') reads a line of text using the minibuffer and
4179 creates an inferior shell to execute the line as a command. Standard
4180 input from the command comes from the null device. If the shell
4181 command produces any output, the output goes to an XEmacs buffer named
4182 `*Shell Command Output*', which is displayed in another window but not
4183 selected. A numeric argument, as in `M-1 M-!', directs this command to
4184 insert any output into the current buffer. In that case, point is left
4185 before the output and the mark is set after the output.
4187 `M-|' (`shell-command-on-region') is like `M-!' but passes the
4188 contents of the region as input to the shell command, instead of no
4189 input. If a numeric argument is used to direct output to the current
4190 buffer, then the old region is deleted first and the output replaces it
4191 as the contents of the region.
4193 Both `M-!' and `M-|' use `shell-file-name' to specify the shell to
4194 use. This variable is initialized based on your `SHELL' environment
4195 variable when you start XEmacs. If the file name does not specify a
4196 directory, the directories in the list `exec-path' are searched; this
4197 list is initialized based on the `PATH' environment variable when you
4198 start XEmacs. You can override either or both of these default
4199 initializations in your init file. *Note Init File::.
4201 When you use `M-!' and `M-|', XEmacs has to wait until the shell
4202 command completes. You can quit with `C-g'; that terminates the shell
4206 File: xemacs.info, Node: Interactive Shell, Next: Shell Mode, Prev: Single Shell, Up: Shell
4208 26.7.2 Interactive Inferior Shell
4209 ---------------------------------
4211 To run a subshell interactively with its typescript in an XEmacs
4212 buffer, use `M-x shell'. This creates (or reuses) a buffer named
4213 `*shell*' and runs a subshell with input coming from and output going
4214 to that buffer. That is to say, any "terminal output" from the subshell
4215 will go into the buffer, advancing point, and any "terminal input" for
4216 the subshell comes from text in the buffer. To give input to the
4217 subshell, go to the end of the buffer and type the input, terminated by
4220 XEmacs does not wait for the subshell to do anything. You can switch
4221 windows or buffers and edit them while the shell is waiting, or while
4222 it is running a command. Output from the subshell waits until XEmacs
4223 has time to process it; this happens whenever XEmacs is waiting for
4224 keyboard input or for time to elapse.
4226 To get multiple subshells, change the name of buffer `*shell*' to
4227 something different by using `M-x rename-buffer'. The next use of `M-x
4228 shell' creates a new buffer `*shell*' with its own subshell. By
4229 renaming this buffer as well you can create a third one, and so on.
4230 All the subshells run independently and in parallel.
4232 The file name used to load the subshell is the value of the variable
4233 `explicit-shell-file-name', if that is non-`nil'. Otherwise, the
4234 environment variable `ESHELL' is used, or the environment variable
4235 `SHELL' if there is no `ESHELL'. If the file name specified is
4236 relative, the directories in the list `exec-path' are searched (*note
4237 Single Shell Commands: Single Shell.).
4239 As soon as the subshell is started, it is sent as input the contents
4240 of the file `~/.emacs_SHELLNAME', if that file exists, where SHELLNAME
4241 is the name of the file that the shell was loaded from. For example,
4242 if you use `csh', the file sent to it is `~/.emacs_csh'.
4244 `cd', `pushd', and `popd' commands given to the inferior shell are
4245 watched by XEmacs so it can keep the `*shell*' buffer's default
4246 directory the same as the shell's working directory. These commands
4247 are recognized syntactically by examining lines of input that are sent.
4248 If you use aliases for these commands, you can tell XEmacs to
4249 recognize them also. For example, if the value of the variable
4250 `shell-pushd-regexp' matches the beginning of a shell command line,
4251 that line is regarded as a `pushd' command. Change this variable when
4252 you add aliases for `pushd'. Likewise, `shell-popd-regexp' and
4253 `shell-cd-regexp' are used to recognize commands with the meaning of
4256 `M-x shell-resync-dirs' queries the shell and resynchronizes XEmacs'
4257 idea of what the current directory stack is. `M-x
4258 shell-dirtrack-toggle' turns directory tracking on and off.
4260 XEmacs keeps a history of the most recent commands you have typed in
4261 the `*shell*' buffer. If you are at the beginning of a shell command
4262 line and type <M-p>, the previous shell input is inserted into the
4263 buffer before point. Immediately typing <M-p> again deletes that input
4264 and inserts the one before it. By repeating <M-p> you can move
4265 backward through your commands until you find one you want to repeat.
4266 You may then edit the command before typing <RET> if you wish. <M-n>
4267 moves forward through the command history, in case you moved backward
4268 past the one you wanted while using <M-p>. If you type the first few
4269 characters of a previous command and then type <M-p>, the most recent
4270 shell input starting with those characters is inserted. This can be
4271 very convenient when you are repeating a sequence of shell commands.
4272 The variable `input-ring-size' controls how many commands are saved in
4273 your input history. The default is 30.
4276 File: xemacs.info, Node: Shell Mode, Next: Terminal emulator, Prev: Interactive Shell, Up: Shell
4281 The shell buffer uses Shell mode, which defines several special keys
4282 attached to the `C-c' prefix. They are chosen to resemble the usual
4283 editing and job control characters present in shells that are not under
4284 XEmacs, except that you must type `C-c' first. Here is a list of the
4285 special key bindings of Shell mode:
4288 At end of buffer send line as input; otherwise, copy current line
4289 to end of buffer and send it (`send-shell-input'). When a line is
4290 copied, any text at the beginning of the line that matches the
4291 variable `shell-prompt-pattern' is left out; this variable's value
4292 should be a regexp string that matches the prompts that you use in
4296 Send end-of-file as input, probably causing the shell or its
4297 current subjob to finish (`shell-send-eof').
4300 If point is not at the end of the buffer, delete the next
4301 character just like most other modes. If point is at the end of
4302 the buffer, send end-of-file as input, instead of generating an
4303 error as in other modes (`comint-delchar-or-maybe-eof').
4306 Kill all text that has yet to be sent as input
4307 (`kill-shell-input').
4310 Kill a word before point (`backward-kill-word').
4313 Interrupt the shell or its current subjob if any
4314 (`interrupt-shell-subjob').
4317 Stop the shell or its current subjob if any (`stop-shell-subjob').
4320 Send quit signal to the shell or its current subjob if any
4321 (`quit-shell-subjob').
4324 Delete last batch of output from shell (`kill-output-from-shell').
4327 Scroll top of last batch of output to top of window
4328 (`show-output-from-shell').
4331 Copy the previous bunch of shell input and insert it into the
4332 buffer before point (`copy-last-shell-input'). No final newline
4333 is inserted, and the input copied is not resubmitted until you type
4337 Move backward through the input history. Search for a matching
4338 command if you have typed the beginning of a command
4339 (`comint-previous-input').
4342 Move forward through the input history. Useful when you are using
4343 <M-p> quickly and go past the desired command
4344 (`comint-next-input').
4347 Complete the file name preceding point (`comint-dynamic-complete').
4350 File: xemacs.info, Node: Terminal emulator, Next: Term Mode, Prev: Shell Mode, Up: Shell
4352 26.7.4 Interactive Inferior Shell with Terminal Emulator
4353 --------------------------------------------------------
4355 To run a subshell in a terminal emulator, putting its typescript in an
4356 XEmacs buffer, use `M-x term'. This creates (or reuses) a buffer named
4357 `*term*' and runs a subshell with input coming from your keyboard and
4358 output going to that buffer.
4360 All the normal keys that you type are sent without any interpretation
4361 by XEmacs directly to the subshell, as "terminal input." Any "echo" of
4362 your input is the responsibility of the subshell. (The exception is
4363 the terminal escape character, which by default is `C-c'. *note Term
4364 Mode::.) Any "terminal output" from the subshell goes into the buffer,
4367 Some programs (such as XEmacs itself) need to control the appearance
4368 on the terminal screen in detail. They do this by sending special
4369 control codes. The exact control codes needed vary from terminal to
4370 terminal, but nowadays most terminals and terminal emulators (including
4371 xterm) understand the so-called "ANSI escape sequences" (first
4372 popularized by the Digital's VT100 family of terminal). The term mode
4373 also understands these escape sequences, and for each control code does
4374 the appropriate thing to change the buffer so that the appearance of
4375 the window will match what it would be on a real terminal. Thus you
4376 can actually run XEmacs inside an XEmacs Term window!
4378 XEmacs does not wait for the subshell to do anything. You can switch
4379 windows or buffers and edit them while the shell is waiting, or while
4380 it is running a command. Output from the subshell waits until XEmacs
4381 has time to process it; this happens whenever XEmacs is waiting for
4382 keyboard input or for time to elapse.
4384 To make multiple terminal emulators, rename the buffer `*term*' to
4385 something different using `M-x rename-uniquely', just as with Shell
4388 The file name used to load the subshell is determined the same way
4391 Unlike Shell mode, Term mode does not track the current directory by
4392 examining your input. Instead, if you use a programmable shell, you
4393 can have it tell Term what the current directory is. This is done
4394 automatically by bash for version 1.15 and later.
4397 File: xemacs.info, Node: Term Mode, Next: Paging in Term, Prev: Terminal emulator, Up: Shell
4402 Term uses Term mode, which has two input modes: In line mode, Term
4403 basically acts like Shell mode. *Note Shell Mode::. In Char mode,
4404 each character is sent directly to the inferior subshell, except for
4405 the Term escape character, normally `C-c'.
4407 To switch between line and char mode, use these commands:
4408 findex term-char-mode
4411 Switch to line mode. Do nothing if already in line mode.
4414 Switch to char mode. Do nothing if already in char mode.
4416 The following commands are only available in Char mode:
4418 Send a literal <C-c> to the sub-shell.
4421 A prefix command to conveniently access the global <C-x> commands.
4422 For example, `C-c C-x o' invokes the global binding of `C-x o',
4423 which is normally `other-window'.
4426 File: xemacs.info, Node: Paging in Term, Prev: Term Mode, Up: Shell
4428 26.7.6 Paging in the terminal emulator
4429 --------------------------------------
4431 Term mode has a pager feature. When the pager is enabled, term mode
4432 will pause at the end of each screenful.
4435 Toggles the pager feature: Disables the pager if it is enabled,
4436 and vice versa. This works in both line and char modes. If the
4437 pager enabled, the mode-line contains the word `page'.
4439 If the pager is enabled, and Term receives more than a screenful of
4440 output since your last input, Term will enter More break mode. This is
4441 indicated by `**MORE**' in the mode-line. Type a `Space' to display
4442 the next screenful of output. Type `?' to see your other options. The
4443 interface is similar to the Unix `more' program.
4446 File: xemacs.info, Node: Narrowing, Next: Hardcopy, Prev: Shell, Up: Top
4451 "Narrowing" means focusing in on some portion of the buffer, making the
4452 rest temporarily invisible and inaccessible. Cancelling the narrowing
4453 and making the entire buffer once again visible is called "widening".
4454 The amount of narrowing in effect in a buffer at any time is called the
4455 buffer's "restriction".
4458 Narrow down to between point and mark (`narrow-to-region').
4461 Widen to make the entire buffer visible again (`widen').
4463 Narrowing sometimes makes it easier to concentrate on a single
4464 subroutine or paragraph by eliminating clutter. It can also be used to
4465 restrict the range of operation of a replace command or repeating
4466 keyboard macro. The word `Narrow' appears in the mode line whenever
4467 narrowing is in effect. When you have narrowed to a part of the
4468 buffer, that part appears to be all there is. You can't see the rest,
4469 can't move into it (motion commands won't go outside the visible part),
4470 and can't change it in any way. However, the invisible text is not
4471 gone; if you save the file, it will be saved.
4473 The primary narrowing command is `C-x n n' (`narrow-to-region'). It
4474 sets the current buffer's restrictions so that the text in the current
4475 region remains visible but all text before the region or after the
4476 region is invisible. Point and mark do not change.
4478 Because narrowing can easily confuse users who do not understand it,
4479 `narrow-to-region' is normally a disabled command. Attempting to use
4480 this command asks for confirmation and gives you the option of enabling
4481 it; once you enable the command, confirmation will no longer be
4482 required. *Note Disabling::.
4484 To undo narrowing, use `C-x n w' (`widen'). This makes all text in
4485 the buffer accessible again.
4487 Use the `C-x =' command to get information on what part of the
4488 buffer you narrowed down. *Note Position Info::.
4491 File: xemacs.info, Node: Hardcopy, Next: Recursive Edit, Prev: Narrowing, Up: Top
4493 26.9 Hardcopy Output
4494 ====================
4496 The XEmacs commands for making hardcopy derive their names from the
4497 Unix commands `print' and `lpr'.
4500 Print hardcopy of current buffer using Unix command `print'
4501 (`lpr -p'). This command adds page headings containing the file
4502 name and page number.
4505 Print hardcopy of current buffer using Unix command `lpr'. This
4506 command does not add page headings.
4509 Like `print-buffer', but prints only the current region.
4512 Like `lpr-buffer', but prints only the current region.
4514 All the hardcopy commands pass extra switches to the `lpr' program
4515 based on the value of the variable `lpr-switches'. Its value should be
4516 a list of strings, each string a switch starting with `-'. For
4517 example, the value could be `("-Pfoo")' to print on printer `foo'.
4520 File: xemacs.info, Node: Recursive Edit, Next: Dissociated Press, Prev: Hardcopy, Up: Top
4522 26.10 Recursive Editing Levels
4523 ==============================
4525 A "recursive edit" is a situation in which you are using XEmacs
4526 commands to perform arbitrary editing while in the middle of another
4527 XEmacs command. For example, when you type `C-r' inside a
4528 `query-replace', you enter a recursive edit in which you can change the
4529 current buffer. When you exit from the recursive edit, you go back to
4530 the `query-replace'.
4532 "Exiting" a recursive edit means returning to the unfinished
4533 command, which continues execution. For example, exiting the recursive
4534 edit requested by `C-r' in `query-replace' causes query replacing to
4535 resume. Exiting is done with `C-M-c' (`exit-recursive-edit').
4537 You can also "abort" a recursive edit. This is like exiting, but
4538 also quits the unfinished command immediately. Use the command `C-]'
4539 (`abort-recursive-edit') for this. *Note Quitting::.
4541 The mode line shows you when you are in a recursive edit by
4542 displaying square brackets around the parentheses that always surround
4543 the major and minor mode names. Every window's mode line shows the
4544 square brackets, since XEmacs as a whole, rather than any particular
4545 buffer, is in a recursive edit.
4547 It is possible to be in recursive edits within recursive edits. For
4548 example, after typing `C-r' in a `query-replace', you might type a
4549 command that entered the debugger. In such a case, two or more sets of
4550 square brackets appear in the mode line(s). Exiting the inner
4551 recursive edit (here with the debugger `c' command) resumes the
4552 query-replace command where it called the debugger. After the end of
4553 the query-replace command, you would be able to exit the first
4554 recursive edit. Aborting exits only one level of recursive edit; it
4555 returns to the command level of the previous recursive edit. You can
4556 then abort that one as well.
4558 The command `M-x top-level' aborts all levels of recursive edits,
4559 returning immediately to the top level command reader.
4561 The text you edit inside the recursive edit need not be the same text
4562 that you were editing at top level. If the command that invokes the
4563 recursive edit selects a different buffer first, that is the buffer you
4564 will edit recursively. You can switch buffers within the recursive edit
4565 in the normal manner (as long as the buffer-switching keys have not been
4566 rebound). While you could theoretically do the rest of your editing
4567 inside the recursive edit, including visiting files, this could have
4568 surprising effects (such as stack overflow) from time to time. It is
4569 best if you always exit or abort a recursive edit when you no longer
4572 In general, XEmacs tries to avoid using recursive edits. It is
4573 usually preferable to allow users to switch among the possible editing
4574 modes in any order they like. With recursive edits, the only way to get
4575 to another state is to go "back" to the state that the recursive edit
4579 File: xemacs.info, Node: Dissociated Press, Next: CONX, Prev: Recursive Edit, Up: Top
4581 26.11 Dissociated Press
4582 =======================
4584 `M-x dissociated-press' is a command for scrambling a file of text
4585 either word by word or character by character. Starting from a buffer
4586 of straight English, it produces extremely amusing output. The input
4587 comes from the current XEmacs buffer. Dissociated Press writes its
4588 output in a buffer named `*Dissociation*', and redisplays that buffer
4589 after every couple of lines (approximately) to facilitate reading it.
4591 `dissociated-press' asks every so often whether to continue
4592 operating. Answer `n' to stop it. You can also stop at any time by
4593 typing `C-g'. The dissociation output remains in the `*Dissociation*'
4594 buffer for you to copy elsewhere if you wish.
4596 Dissociated Press operates by jumping at random from one point in the
4597 buffer to another. In order to produce plausible output rather than
4598 gibberish, it insists on a certain amount of overlap between the end of
4599 one run of consecutive words or characters and the start of the next.
4600 That is, if it has just printed out `president' and then decides to
4601 jump to a different point in the file, it might spot the `ent' in
4602 `pentagon' and continue from there, producing `presidentagon'. Long
4603 sample texts produce the best results.
4605 A positive argument to `M-x dissociated-press' tells it to operate
4606 character by character, and specifies the number of overlap characters.
4607 A negative argument tells it to operate word by word and specifies the
4608 number of overlap words. In this mode, whole words are treated as the
4609 elements to be permuted, rather than characters. No argument is
4610 equivalent to an argument of two. For your againformation, the output
4611 goes only into the buffer `*Dissociation*'. The buffer you start with
4614 Dissociated Press produces nearly the same results as a Markov chain
4615 based on a frequency table constructed from the sample text. It is,
4616 however, an independent, ignoriginal invention. Dissociated Press
4617 techniquitously copies several consecutive characters from the sample
4618 between random choices, whereas a Markov chain would choose randomly for
4619 each word or character. This makes for more plausible sounding results
4622 It is a mustatement that too much use of Dissociated Press can be a
4623 developediment to your real work. Sometimes to the point of outragedy.
4624 And keep dissociwords out of your documentation, if you want it to be
4625 well userenced and properbose. Have fun. Your buggestions are welcome.
4628 File: xemacs.info, Node: CONX, Next: Amusements, Prev: Dissociated Press, Up: Top
4633 Besides producing a file of scrambled text with Dissociated Press, you
4634 can generate random sentences by using CONX.
4637 Generate random sentences in the `*conx*' buffer.
4640 Absorb the text in the current buffer into the `conx' database.
4643 Forget the current word-frequency tree.
4646 Load a `conx' database that has been previously saved with `M-x
4650 Absorb the text in the current buffer into the `conx' database.
4653 Save the current `conx' database to a file for future retrieval.
4655 Copy text from a buffer using `M-x conx-buffer' or `M-x conx-region'
4656 and then type `M-x conx'. Output is continuously generated until you
4657 type <^G>. You can save the `conx' database to a file with `M-x
4658 conx-save', which you can retrieve with `M-x conx-load'. To clear the
4659 database, use `M-x conx-init'.
4662 File: xemacs.info, Node: Amusements, Next: Emulation, Prev: CONX, Up: Top
4664 26.13 Other Amusements
4665 ======================
4667 If you are a little bit bored, you can try `M-x hanoi'. If you are
4668 considerably bored, give it a numeric argument. If you are very, very
4669 bored, try an argument of 9. Sit back and watch.
4671 When you are frustrated, try the famous Eliza program. Just do `M-x
4672 doctor'. End each input by typing `RET' twice.
4674 When you are feeling strange, type `M-x yow'.
4677 File: xemacs.info, Node: Emulation, Next: Customization, Prev: Amusements, Up: Top
4682 XEmacs can be programmed to emulate (more or less) most other editors.
4683 Standard facilities can emulate these:
4685 Viper (a vi emulator)
4686 In XEmacs, Viper is the preferred emulation of vi within XEmacs.
4687 Viper is designed to allow you to take advantage of the best
4688 features of XEmacs while still doing your basic editing in a
4689 familiar, vi-like fashion. Viper provides various different
4690 levels of vi emulation, from a quite complete emulation that
4691 allows almost no access to native XEmacs commands, to an "expert"
4692 mode that combines the most useful vi commands with the most
4693 useful XEmacs commands.
4695 To start Viper, put the command
4699 in your init file. *Note Init File::.
4701 Viper comes with a separate manual that is provided standard with
4702 the XEmacs distribution.
4704 EDT (DEC VMS editor)
4705 Turn on EDT emulation with `M-x edt-emulation-on'. `M-x
4706 edt-emulation-off' restores normal Emacs command bindings.
4708 Most of the EDT emulation commands are keypad keys, and most
4709 standard Emacs key bindings are still available. The EDT
4710 emulation rebindings are done in the global keymap, so there is no
4711 problem switching buffers or major modes while in EDT emulation.
4714 Turn on emulation of Gosling Emacs (aka Unipress Emacs) with `M-x
4715 set-gosmacs-bindings'. This redefines many keys, mostly on the
4716 `C-x' and `ESC' prefixes, to work as they do in Gosmacs. `M-x
4717 set-gnu-bindings' returns to normal XEmacs by rebinding the same
4718 keys to the definitions they had at the time `M-x
4719 set-gosmacs-bindings' was done.
4721 It is also possible to run Mocklisp code written for Gosling Emacs.
4725 File: xemacs.info, Node: Customization, Next: Quitting, Prev: Emulation, Up: Top
4730 This chapter talks about various topics relevant to adapting the
4731 behavior of Emacs in minor ways.
4733 All kinds of customization affect only the particular Emacs job that
4734 you do them in. They are completely lost when you kill the Emacs job,
4735 and have no effect on other Emacs jobs you may run at the same time or
4736 later. The only way an Emacs job can affect anything outside of it is
4737 by writing a file; in particular, the only way to make a customization
4738 `permanent' is to put something in your init file or other appropriate
4739 file to do the customization in each session. *Note Init File::.
4743 * Minor Modes:: Each minor mode is one feature you can turn on
4744 independently of any others.
4745 * Variables:: Many Emacs commands examine Emacs variables
4746 to decide what to do; by setting variables,
4747 you can control their functioning.
4748 * Keyboard Macros:: A keyboard macro records a sequence of keystrokes
4749 to be replayed with a single command.
4750 * Key Bindings:: The keymaps say what command each key runs.
4751 By changing them, you can "redefine keys".
4752 * Syntax:: The syntax table controls how words and expressions
4754 * Init File:: How to write common customizations in the init file.
4755 * Audible Bell:: Changing how Emacs sounds the bell.
4756 * Faces:: Changing the fonts and colors of a region of text.
4757 * Frame Components:: Controlling the presence and positions of the
4758 menubar, toolbars, and gutters.
4759 * X Resources:: X resources controlling various aspects of the
4763 File: xemacs.info, Node: Minor Modes, Next: Variables, Up: Customization
4768 Minor modes are options which you can use or not. For example, Auto
4769 Fill mode is a minor mode in which <SPC> breaks lines between words as
4770 you type. All the minor modes are independent of each other and of the
4771 selected major mode. Most minor modes inform you in the mode line when
4772 they are on; for example, `Fill' in the mode line means that Auto Fill
4775 Append `-mode' to the name of a minor mode to get the name of a
4776 command function that turns the mode on or off. Thus, the command to
4777 enable or disable Auto Fill mode is called `M-x auto-fill-mode'. These
4778 commands are usually invoked with `M-x', but you can bind keys to them
4779 if you wish. With no argument, the function turns the mode on if it was
4780 off and off if it was on. This is known as "toggling". A positive
4781 argument always turns the mode on, and an explicit zero argument or a
4782 negative argument always turns it off.
4784 Auto Fill mode allows you to enter filled text without breaking lines
4785 explicitly. Emacs inserts newlines as necessary to prevent lines from
4786 becoming too long. *Note Filling::.
4788 Overwrite mode causes ordinary printing characters to replace
4789 existing text instead of moving it to the right. For example, if point
4790 is in front of the `B' in `FOOBAR', and you type a `G' in Overwrite
4791 mode, it changes to `FOOGAR', instead of `FOOGBAR'.
4793 Abbrev mode allows you to define abbreviations that automatically
4794 expand as you type them. For example, `amd' might expand to `abbrev
4795 mode'. *Note Abbrevs::, for full information.
4798 File: xemacs.info, Node: Variables, Next: Keyboard Macros, Prev: Minor Modes, Up: Customization
4803 A "variable" is a Lisp symbol which has a value. Variable names can
4804 contain any characters, but by convention they are words separated by
4805 hyphens. A variable can also have a documentation string, which
4806 describes what kind of value it should have and how the value will be
4809 Lisp allows any variable to have any kind of value, but most
4810 variables that Emacs uses require a value of a certain type. Often the
4811 value has to be a string or a number. Sometimes we say that a certain
4812 feature is turned on if a variable is "non-`nil'," meaning that if the
4813 variable's value is `nil', the feature is off, but the feature is on
4814 for any other value. The conventional value to turn on the
4815 feature--since you have to pick one particular value when you set the
4818 Emacs uses many Lisp variables for internal recordkeeping, as any
4819 Lisp program must, but the most interesting variables for you are the
4820 ones that exist for the sake of customization. Emacs does not
4821 (usually) change the values of these variables; instead, you set the
4822 values, and thereby alter and control the behavior of certain Emacs
4823 commands. These variables are called "options". Most options are
4824 documented in this manual and appear in the Variable Index (*note
4827 One example of a variable which is an option is `fill-column', which
4828 specifies the position of the right margin (as a number of characters
4829 from the left margin) to be used by the fill commands (*note Filling::).
4833 * Examining:: Examining or setting one variable's value.
4834 * Easy Customization:: Convenient and easy customization of variables.
4835 * Edit Options:: Examining or editing list of all variables' values.
4836 * Locals:: Per-buffer values of variables.
4837 * File Variables:: How files can specify variable values.
4840 File: xemacs.info, Node: Examining, Next: Easy Customization, Up: Variables
4842 27.2.1 Examining and Setting Variables
4843 --------------------------------------
4846 `M-x describe-variable'
4847 Print the value and documentation of a variable.
4850 Change the value of a variable.
4852 To examine the value of a single variable, use `C-h v'
4853 (`describe-variable'), which reads a variable name using the
4854 minibuffer, with completion. It prints both the value and the
4855 documentation of the variable.
4857 C-h v fill-column <RET>
4859 prints something like:
4861 fill-column's value is 75
4864 *Column beyond which automatic line-wrapping should happen.
4865 Automatically becomes local when set in any fashion.
4867 The star at the beginning of the documentation indicates that this
4868 variable is an option. `C-h v' is not restricted to options; it allows
4871 If you know which option you want to set, you can use `M-x
4872 set-variable' to set it. This prompts for the variable name in the
4873 minibuffer (with completion), and then prompts for a Lisp expression
4874 for the new value using the minibuffer a second time. For example,
4876 M-x set-variable <RET> fill-column <RET> 75 <RET>
4878 sets `fill-column' to 75, as if you had executed the Lisp expression
4879 `(setq fill-column 75)'.
4881 Setting variables in this way, like all means of customizing Emacs
4882 except where explicitly stated, affects only the current Emacs session.
4885 File: xemacs.info, Node: Easy Customization, Next: Edit Options, Prev: Examining, Up: Variables
4887 27.2.2 Easy Customization Interface
4888 -----------------------------------
4890 A convenient way to find the user option variables that you want to
4891 change, and then change them, is with `M-x customize' (or use a
4892 keyboard shortcut, `C-h C'. This command creates a "customization
4893 buffer" with which you can browse through the Emacs user options in a
4894 logically organized structure, then edit and set their values. You can
4895 also use the customization buffer to save settings permanently. (Not
4896 all Emacs user options are included in this structure as of yet, but we
4897 are adding the rest.)
4901 * Groups: Customization Groups.
4902 How options are classified in a structure.
4903 * Changing an Option:: How to edit a value and set an option.
4904 * Face Customization:: How to edit the attributes of a face.
4905 * Specific Customization:: Making a customization buffer for specific
4906 options, faces, or groups.
4909 File: xemacs.info, Node: Customization Groups, Next: Changing an Option, Up: Easy Customization
4911 27.2.2.1 Customization Groups
4912 .............................
4914 For customization purposes, user options are organized into "groups" to
4915 help you find them. Groups are collected into bigger groups, all the
4916 way up to a master group called `Emacs'.
4918 `M-x customize' (or `C-h C') creates a customization buffer that
4919 shows the top-level `Emacs' group and the second-level groups
4920 immediately under it. It looks like this, in part:
4922 /- Emacs group: ---------------------------------------------------\
4923 [State]: visible group members are all at standard settings.
4924 Customization of the One True Editor.
4927 [Open] Editing group
4928 Basic text editing facilities.
4930 [Open] External group
4931 Interfacing to external utilities.
4933 MORE SECOND-LEVEL GROUPS
4935 \- Emacs group end ------------------------------------------------/
4937 This says that the buffer displays the contents of the `Emacs' group.
4938 The other groups are listed because they are its contents. But they
4939 are listed differently, without indentation and dashes, because _their_
4940 contents are not included. Each group has a single-line documentation
4941 string; the `Emacs' group also has a `[State]' line.
4943 Most of the text in the customization buffer is read-only, but it
4944 typically includes some "editable fields" that you can edit. There are
4945 also "active fields"; this means a field that does something when you
4946 "invoke" it. To invoke an active field, either click on it with
4947 `Mouse-1', or move point to it and type <RET>.
4949 For example, the phrase `[Open]' that appears in a second-level
4950 group is an active field. Invoking the `[Open]' field for a group
4951 opens up a new customization buffer, which shows that group and its
4952 contents. This field is a kind of hypertext link to another group.
4954 The `Emacs' group does not include any user options itself, but
4955 other groups do. By examining various groups, you will eventually find
4956 the options and faces that belong to the feature you are interested in
4957 customizing. Then you can use the customization buffer to set them.
4959 You can view the structure of customization groups on a larger scale
4960 with `M-x customize-browse'. This command creates a special kind of
4961 customization buffer which shows only the names of the groups (and
4962 options and faces), and their structure.
4964 In this buffer, you can show the contents of a group by invoking
4965 `[+]'. When the group contents are visible, this button changes to
4966 `[-]'; invoking that hides the group contents.
4968 Each group, option or face name in this buffer has an active field
4969 which says `[Group]', `[Option]' or `[Face]'. Invoking that active
4970 field creates an ordinary customization buffer showing just that group
4971 and its contents, just that option, or just that face. This is the way
4972 to set values in it.
4975 File: xemacs.info, Node: Changing an Option, Next: Face Customization, Prev: Customization Groups, Up: Easy Customization
4977 27.2.2.2 Changing an Option
4978 ...........................
4980 Here is an example of what a user option looks like in the
4981 customization buffer:
4983 Kill Ring Max: [Hide] 30
4984 [State]: this option is unchanged from its standard setting.
4985 Maximum length of kill ring before oldest elements are thrown away.
4987 The text following `[Hide]', `30' in this case, indicates the
4988 current value of the option. If you see `[Show]' instead of `[Hide]',
4989 it means that the value is hidden; the customization buffer initially
4990 hides values that take up several lines. Invoke `[Show]' to show the
4993 The line after the option name indicates the "customization state"
4994 of the option: in the example above, it says you have not changed the
4995 option yet. The word `[State]' at the beginning of this line is
4996 active; you can get a menu of various operations by invoking it with
4997 `Mouse-1' or <RET>. These operations are essential for customizing the
5000 The line after the `[State]' line displays the beginning of the
5001 option's documentation string. If there are more lines of
5002 documentation, this line ends with `[More]'; invoke this to show the
5003 full documentation string.
5005 To enter a new value for `Kill Ring Max', move point to the value
5006 and edit it textually. For example, you can type `M-d', then insert
5009 When you begin to alter the text, you will see the `[State]' line
5010 change to say that you have edited the value:
5012 [State]: you have edited the value as text, but not set the option.
5014 Editing the value does not actually set the option variable. To do
5015 that, you must "set" the option. To do this, invoke the word `[State]'
5016 and choose `Set for Current Session'.
5018 The state of the option changes visibly when you set it:
5020 [State]: you have set this option, but not saved it for future sessions.
5022 You don't have to worry about specifying a value that is not valid;
5023 setting the option checks for validity and will not really install an
5026 While editing a value or field that is a file name, directory name,
5027 command name, or anything else for which completion is defined, you can
5028 type `M-<TAB>' (`widget-complete') to do completion.
5030 Some options have a small fixed set of possible legitimate values.
5031 These options don't let you edit the value textually. Instead, an
5032 active field `[Value Menu]' appears before the value; invoke this field
5033 to edit the value. For a boolean "on or off" value, the active field
5034 says `[Toggle]', and it changes to the other value. `[Value Menu]' and
5035 `[Toggle]' edit the buffer; the changes take effect when you use the
5036 `Set for Current Session' operation.
5038 Some options have values with complex structure. For example, the
5039 value of `load-path' is a list of directories. Here is how it appears
5040 in the customization buffer:
5043 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp
5044 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
5045 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim
5046 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp
5047 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp
5048 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus
5050 [State]: this item has been changed outside the customization buffer.
5051 List of directories to search for files to load....
5053 Each directory in the list appears on a separate line, and each line has
5054 several editable or active fields.
5056 You can edit any of the directory names. To delete a directory from
5057 the list, invoke `[DEL]' on that line. To insert a new directory in
5058 the list, invoke `[INS]' at the point where you want to insert it.
5060 You can also invoke `[Current dir?]' to switch between including a
5061 specific named directory in the path, and including `nil' in the path.
5062 (`nil' in a search path means "try the current directory.")
5064 Two special commands, <TAB> and `S-<TAB>', are useful for moving
5065 through the customization buffer. <TAB> (`widget-forward') moves
5066 forward to the next active or editable field; `S-<TAB>'
5067 (`widget-backward') moves backward to the previous active or editable
5070 Typing <RET> on an editable field also moves forward, just like
5071 <TAB>. The reason for this is that people have a tendency to type
5072 <RET> when they are finished editing a field. If you have occasion to
5073 insert a newline in an editable field, use `C-o' or `C-q C-j',
5075 Setting the option changes its value in the current Emacs session;
5076 "saving" the value changes it for future sessions as well. This works
5077 by writing code into your init file so as to set the option variable
5078 again each time you start Emacs. *Note Init File::. To save the
5079 option, invoke `[State]' and select the `Save for Future Sessions'
5082 You can also restore the option to its standard value by invoking
5083 `[State]' and selecting the `Reset' operation. There are actually
5084 three reset operations:
5087 If you have made some modifications and not yet set the option,
5088 this restores the text in the customization buffer to match the
5092 This restores the value of the option to the last saved value, and
5093 updates the text accordingly.
5095 `Reset to Standard Settings'
5096 This sets the option to its standard value, and updates the text
5097 accordingly. This also eliminates any saved value for the option,
5098 so that you will get the standard value in future Emacs sessions.
5100 The state of a group indicates whether anything in that group has
5101 been edited, set or saved. You can select `Set for Current Session',
5102 `Save for Future Sessions' and the various kinds of `Reset' operation
5103 for the group; these operations on the group apply to all options in
5104 the group and its subgroups.
5106 Near the top of the customization buffer there are two lines
5107 containing several active fields:
5109 [Set] [Save] [Reset] [Done]
5111 Invoking `[Done]' buries this customization buffer. Each of the other
5112 fields performs an operation--set, save or reset--on each of the items
5113 in the buffer that could meaningfully be set, saved or reset.
5116 File: xemacs.info, Node: Face Customization, Next: Specific Customization, Prev: Changing an Option, Up: Easy Customization
5118 27.2.2.3 Customizing Faces
5119 ..........................
5121 In addition to user options, some customization groups also include
5122 faces. When you show the contents of a group, both the user options and
5123 the faces in the group appear in the customization buffer. Here is an
5124 example of how a face looks:
5126 Custom Changed Face: (sample)
5127 [State]: this face is unchanged from its standard setting.
5128 Face used when the customize item has been changed.
5129 Parent groups: [Custom Magic Faces]
5130 Attributes: [ ] Bold: [Toggle] off (nil)
5131 [ ] Italic: [Toggle] off (nil)
5132 [ ] Underline: [Toggle] off (nil)
5133 [ ] Foreground: white (sample)
5134 [ ] Background: blue (sample)
5135 [ ] Inverse: [Toggle] off (nil)
5141 Each face attribute has its own line. The `[X]' field before the
5142 attribute name indicates whether the attribute is "enabled"; `X' means
5143 that it is. You can enable or disable the attribute by invoking that
5144 field. When the attribute is enabled, you can change the attribute
5145 value in the usual ways.
5147 *Note Faces::, for description of how `face-frob-from-locale-first'
5148 variable affects changing `Bold' and `Italic' attributes.
5150 Setting, saving and resetting a face work like the same operations
5151 for options (*note Changing an Option::).
5153 A face can specify different appearances for different types of
5154 display. For example, a face can make text red on a color display, but
5155 use a bold font on a monochrome display. To specify multiple
5156 appearances for a face, select `Show Display Types' in the menu you get
5157 from invoking `[State]'.
5160 File: xemacs.info, Node: Specific Customization, Prev: Face Customization, Up: Easy Customization
5162 27.2.2.4 Customizing Specific Items
5163 ...................................
5165 Instead of finding the options you want to change by moving down
5166 through the structure of groups, you can specify the particular option,
5167 face or group that you want to customize.
5169 `M-x customize-option <RET> OPTION <RET>'
5170 Set up a customization buffer with just one option, OPTION.
5172 `M-x customize-face <RET> FACE <RET>'
5173 Set up a customization buffer with just one face, FACE.
5175 `M-x customize-group <RET> GROUP <RET>'
5176 Set up a customization buffer with just one group, GROUP.
5178 `M-x customize-apropos <RET> REGEXP <RET>'
5179 Set up a customization buffer with all the options, faces and
5180 groups that match REGEXP.
5182 `M-x customize-saved'
5183 Set up a customization buffer containing all options and faces
5184 that you have saved with customization buffers.
5186 `M-x customize-customized'
5187 Set up a customization buffer containing all options and faces
5188 that you have customized but not saved.
5190 If you want to alter a particular user option variable with the
5191 customization buffer, and you know its name, you can use the command
5192 `M-x customize-option' and specify the option name. This sets up the
5193 customization buffer with just one option--the one that you asked for.
5194 Editing, setting and saving the value work as described above, but only
5195 for the specified option.
5197 Likewise, you can modify a specific face, chosen by name, using `M-x
5200 You can also set up the customization buffer with a specific group,
5201 using `M-x customize-group'. The immediate contents of the chosen
5202 group, including option variables, faces, and other groups, all appear
5203 as well. However, these subgroups' own contents start out hidden. You
5204 can show their contents in the usual way, by invoking `[Show]'.
5206 To control more precisely what to customize, you can use `M-x
5207 customize-apropos'. You specify a regular expression as argument; then
5208 all options, faces and groups whose names match this regular expression
5209 are set up in the customization buffer. If you specify an empty regular
5210 expression, this includes _all_ groups, options and faces in the
5211 customization buffer (but that takes a long time).
5213 If you change option values and then decide the change was a mistake,
5214 you can use two special commands to revisit your previous changes. Use
5215 `customize-saved' to look at the options and faces that you have saved.
5216 Use `M-x customize-customized' to look at the options and faces that
5217 you have set but not saved.
5220 File: xemacs.info, Node: Edit Options, Next: Locals, Prev: Easy Customization, Up: Variables
5222 27.2.3 Editing Variable Values
5223 ------------------------------
5226 Display a buffer listing names, values, and documentation of all
5230 Change option values by editing a list of options.
5232 `M-x list-options' displays a list of all Emacs option variables in
5233 an Emacs buffer named `*List Options*'. Each option is shown with its
5234 documentation and its current value. Here is what a portion of it might
5238 ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
5239 *List of directories to search programs to run in subprocesses.
5240 Each element is a string (directory name)
5241 or nil (try the default directory).
5245 *Column beyond which automatic line-wrapping should happen.
5246 Automatically becomes local when set in any fashion.
5249 `M-x edit-options' goes one step further and immediately selects the
5250 `*List Options*' buffer; this buffer uses the major mode Options mode,
5251 which provides commands that allow you to point at an option and change
5255 Set the variable point is in or near to a new value read using the
5259 Toggle the variable point is in or near: if the value was `nil',
5260 it becomes `t'; otherwise it becomes `nil'.
5263 Set the variable point is in or near to `t'.
5266 Set the variable point is in or near to `nil'.
5270 Move to the next or previous variable.
5273 File: xemacs.info, Node: Locals, Next: File Variables, Prev: Edit Options, Up: Variables
5275 27.2.4 Local Variables
5276 ----------------------
5278 `M-x make-local-variable'
5279 Make a variable have a local value in the current buffer.
5281 `M-x kill-local-variable'
5282 Make a variable use its global value in the current buffer.
5284 `M-x make-variable-buffer-local'
5285 Mark a variable so that setting it will make it local to the
5286 buffer that is current at that time.
5288 You can make any variable "local" to a specific Emacs buffer. This
5289 means that the variable's value in that buffer is independent of its
5290 value in other buffers. A few variables are always local in every
5291 buffer. All other Emacs variables have a "global" value which is in
5292 effect in all buffers that have not made the variable local.
5294 Major modes always make the variables they set local to the buffer.
5295 This is why changing major modes in one buffer has no effect on other
5298 `M-x make-local-variable' reads the name of a variable and makes it
5299 local to the current buffer. Further changes in this buffer will not
5300 affect others, and changes in the global value will not affect this
5303 `M-x make-variable-buffer-local' reads the name of a variable and
5304 changes the future behavior of the variable so that it automatically
5305 becomes local when it is set. More precisely, once you have marked a
5306 variable in this way, the usual ways of setting the variable will
5307 automatically invoke `make-local-variable' first. We call such
5308 variables "per-buffer" variables.
5310 Some important variables have been marked per-buffer already. They
5311 include `abbrev-mode', `auto-fill-function', `case-fold-search',
5312 `comment-column', `ctl-arrow', `fill-column', `fill-prefix',
5313 `indent-tabs-mode', `left-margin',
5314 `mode-line-format', `overwrite-mode', `selective-display-ellipses',
5315 `selective-display', `tab-width', and `truncate-lines'. Some other
5316 variables are always local in every buffer, but they are used for
5319 Note: the variable `auto-fill-function' was formerly named
5322 If you want a variable to cease to be local to the current buffer,
5323 call `M-x kill-local-variable' and provide the name of a variable to
5324 the prompt. The global value of the variable is again in effect in
5325 this buffer. Setting the major mode kills all the local variables of
5328 To set the global value of a variable, regardless of whether the
5329 variable has a local value in the current buffer, you can use the Lisp
5330 function `setq-default'. It works like `setq'. If there is a local
5331 value in the current buffer, the local value is not affected by
5332 `setq-default'; thus, the new global value may not be visible until you
5333 switch to another buffer, as in the case of:
5335 (setq-default fill-column 75)
5337 `setq-default' is the only way to set the global value of a variable
5338 that has been marked with `make-variable-buffer-local'.
5340 Programs can look at a variable's default value with `default-value'.
5341 This function takes a symbol as an argument and returns its default
5342 value. The argument is evaluated; usually you must quote it
5343 explicitly, as in the case of:
5345 (default-value 'fill-column)
5348 File: xemacs.info, Node: File Variables, Prev: Locals, Up: Variables
5350 27.2.5 Local Variables in Files
5351 -------------------------------
5353 A file can contain a "local variables list", which specifies the values
5354 to use for certain Emacs variables when that file is edited. Visiting
5355 the file checks for a local variables list and makes each variable in
5356 the list local to the buffer in which the file is visited, with the
5357 value specified in the file.
5359 A local variables list goes near the end of the file, in the last
5360 page. (It is often best to put it on a page by itself.) The local
5361 variables list starts with a line containing the string `Local
5362 Variables:', and ends with a line containing the string `End:'. In
5363 between come the variable names and values, one set per line, as
5364 `VARIABLE: VALUE'. The VALUEs are not evaluated; they are used
5367 The line which starts the local variables list does not have to say
5368 just `Local Variables:'. If there is other text before `Local
5369 Variables:', that text is called the "prefix", and if there is other
5370 text after, that is called the "suffix". If a prefix or suffix are
5371 present, each entry in the local variables list should have the prefix
5372 before it and the suffix after it. This includes the `End:' line. The
5373 prefix and suffix are included to disguise the local variables list as
5374 a comment so the compiler or text formatter will ignore it. If you do
5375 not need to disguise the local variables list as a comment in this way,
5376 there is no need to include a prefix or a suffix.
5378 Two "variable" names are special in a local variables list: a value
5379 for the variable `mode' sets the major mode, and a value for the
5380 variable `eval' is simply evaluated as an expression and the value is
5381 ignored. These are not real variables; setting them in any other
5382 context does not have the same effect. If `mode' is used in a local
5383 variables list, it should be the first entry in the list.
5385 Here is an example of a local variables list:
5386 ;;; Local Variables: ***
5388 ;;; comment-column:0 ***
5389 ;;; comment-start: ";;; " ***
5390 ;;; comment-end:"***" ***
5393 Note that the prefix is `;;; ' and the suffix is ` ***'. Note also
5394 that comments in the file begin with and end with the same strings.
5395 Presumably the file contains code in a language which is enough like
5396 Lisp for Lisp mode to be useful but in which comments start and end
5397 differently. The prefix and suffix are used in the local variables
5398 list to make the list look like several lines of comments when the
5399 compiler or interpreter for that language reads the file.
5401 The start of the local variables list must be no more than 3000
5402 characters from the end of the file, and must be in the last page if the
5403 file is divided into pages. Otherwise, Emacs will not notice it is
5404 there. The purpose is twofold: a stray `Local Variables:' not in the
5405 last page does not confuse Emacs, and Emacs never needs to search a
5406 long file that contains no page markers and has no local variables list.
5408 You may be tempted to turn on Auto Fill mode with a local variable
5409 list. That is inappropriate. Whether you use Auto Fill mode or not is
5410 a matter of personal taste, not a matter of the contents of particular
5411 files. If you want to use Auto Fill, set up major mode hooks with your
5412 init file to turn it on (when appropriate) for you alone (*note Init
5413 File::). Don't try to use a local variable list that would impose your
5414 taste on everyone working with the file.
5416 XEmacs allows you to specify local variables in the first line of a
5417 file, in addition to specifying them in the `Local Variables' section
5418 at the end of a file.
5420 If the first line of a file contains two occurrences of ``-*-'',
5421 XEmacs uses the information between them to determine what the major
5422 mode and variable settings should be. For example, these are all legal:
5424 ;;; -*- mode: emacs-lisp -*-
5425 ;;; -*- mode: postscript; version-control: never -*-
5426 ;;; -*- tags-file-name: "/foo/bar/TAGS" -*-
5428 For historical reasons, the syntax ``-*- modename -*-'' is allowed
5429 as well; for example, you can use:
5431 ;;; -*- emacs-lisp -*-
5433 The variable `enable-local-variables' controls the use of local
5434 variables lists in files you visit. The value can be `t', `nil', or
5435 something else. A value of `t' means local variables lists are obeyed;
5436 `nil' means they are ignored; anything else means query.
5438 The command `M-x normal-mode' always obeys local variables lists and
5439 ignores this variable.
5442 File: xemacs.info, Node: Keyboard Macros, Next: Key Bindings, Prev: Variables, Up: Customization
5444 27.3 Keyboard Macros
5445 ====================
5447 A "keyboard macro" is a command defined by the user to abbreviate a
5448 sequence of keys. For example, if you discover that you are about to
5449 type `C-n C-d' forty times, you can speed your work by defining a
5450 keyboard macro to invoke `C-n C-d' and calling it with a repeat count
5454 Start defining a keyboard macro (`start-kbd-macro').
5457 End the definition of a keyboard macro (`end-kbd-macro').
5460 Execute the most recent keyboard macro (`call-last-kbd-macro').
5463 Re-execute last keyboard macro, then add more keys to its
5467 When this point is reached during macro execution, ask for
5468 confirmation (`kbd-macro-query').
5470 `M-x name-last-kbd-macro'
5471 Give a command name (for the duration of the session) to the most
5472 recently defined keyboard macro.
5474 `M-x insert-kbd-macro'
5475 Insert in the buffer a keyboard macro's definition, as Lisp code.
5477 Keyboard macros differ from other Emacs commands in that they are
5478 written in the Emacs command language rather than in Lisp. This makes
5479 it easier for the novice to write them and makes them more convenient as
5480 temporary hacks. However, the Emacs command language is not powerful
5481 enough as a programming language to be useful for writing anything
5482 general or complex. For such things, Lisp must be used.
5484 You define a keyboard macro by executing the commands which are its
5485 definition. Put differently, as you are defining a keyboard macro, the
5486 definition is being executed for the first time. This way, you see
5487 what the effects of your commands are, and don't have to figure them
5488 out in your head. When you are finished, the keyboard macro is defined
5489 and also has been executed once. You can then execute the same set of
5490 commands again by invoking the macro.
5494 * Basic Kbd Macro:: Defining and running keyboard macros.
5495 * Save Kbd Macro:: Giving keyboard macros names; saving them in files.
5496 * Kbd Macro Query:: Keyboard macros that do different things each use.
5499 File: xemacs.info, Node: Basic Kbd Macro, Next: Save Kbd Macro, Up: Keyboard Macros
5504 To start defining a keyboard macro, type `C-x (' (`start-kbd-macro').
5505 From then on, anything you type continues to be executed, but also
5506 becomes part of the definition of the macro. `Def' appears in the mode
5507 line to remind you of what is going on. When you are finished, the
5508 `C-x )' command (`end-kbd-macro') terminates the definition, without
5509 becoming part of it.
5515 defines a macro to move forward a word and then insert `foo'.
5517 You can give `C-x )' a repeat count as an argument, in which case it
5518 repeats the macro that many times right after defining it, but defining
5519 the macro counts as the first repetition (since it is executed as you
5520 define it). If you give `C-x )' an argument of 4, it executes the
5521 macro immediately 3 additional times. An argument of zero to `C-x e'
5522 or `C-x )' means repeat the macro indefinitely (until it gets an error
5525 Once you have defined a macro, you can invoke it again with the `C-x
5526 e' command (`call-last-kbd-macro'). You can give the command a repeat
5527 count numeric argument to execute the macro many times.
5529 To repeat an operation at regularly spaced places in the text,
5530 define a macro and include as part of the macro the commands to move to
5531 the next place you want to use it. For example, if you want to change
5532 each line, you should position point at the start of a line, and define
5533 a macro to change that line and leave point at the start of the next
5534 line. Repeating the macro will then operate on successive lines.
5536 After you have terminated the definition of a keyboard macro, you
5537 can add to the end of its definition by typing `C-u C-x ('. This is
5538 equivalent to plain `C-x (' followed by retyping the whole definition
5539 so far. As a consequence it re-executes the macro as previously
5543 File: xemacs.info, Node: Save Kbd Macro, Next: Kbd Macro Query, Prev: Basic Kbd Macro, Up: Keyboard Macros
5545 27.3.2 Naming and Saving Keyboard Macros
5546 ----------------------------------------
5548 To save a keyboard macro for longer than until you define the next one,
5549 you must give it a name using `M-x name-last-kbd-macro'. This reads a
5550 name as an argument using the minibuffer and defines that name to
5551 execute the macro. The macro name is a Lisp symbol, and defining it in
5552 this way makes it a valid command name for calling with `M-x' or for
5553 binding a key to with `global-set-key' (*note Keymaps::). If you
5554 specify a name that has a prior definition other than another keyboard
5555 macro, Emacs prints an error message and nothing is changed.
5557 Once a macro has a command name, you can save its definition in a
5558 file. You can then use it in another editing session. First visit the
5559 file you want to save the definition in. Then use the command:
5561 M-x insert-kbd-macro <RET> MACRONAME <RET>
5563 This inserts some Lisp code that, when executed later, will define the
5564 same macro with the same definition it has now. You need not
5565 understand Lisp code to do this, because `insert-kbd-macro' writes the
5566 Lisp code for you. Then save the file. You can load the file with
5567 `load-file' (*note Lisp Libraries::). If the file you save in is your
5568 initialization file (*note Init File::), then the macro will be defined
5569 each time you run Emacs.
5571 If you give `insert-kbd-macro' a prefix argument, it creates
5572 additional Lisp code to record the keys (if any) that you have bound to
5573 the keyboard macro, so that the macro is reassigned the same keys when
5577 File: xemacs.info, Node: Kbd Macro Query, Prev: Save Kbd Macro, Up: Keyboard Macros
5579 27.3.3 Executing Macros With Variations
5580 ---------------------------------------
5582 You can use `C-x q' (`kbd-macro-query'), to get an effect similar to
5583 that of `query-replace'. The macro asks you each time whether to make
5584 a change. When you are defining the macro, type `C-x q' at the point
5585 where you want the query to occur. During macro definition, the `C-x
5586 q' does nothing, but when you invoke the macro, `C-x q' reads a
5587 character from the terminal to decide whether to continue.
5589 The special answers to a `C-x q' query are <SPC>, <DEL>, `C-d',
5590 `C-l', and `C-r'. Any other character terminates execution of the
5591 keyboard macro and is then read as a command. <SPC> means to continue.
5592 <DEL> means to skip the remainder of this repetition of the macro,
5593 starting again from the beginning in the next repetition. `C-d' means
5594 to skip the remainder of this repetition and cancel further repetition.
5595 `C-l' redraws the frame and asks you again for a character to specify
5596 what to do. `C-r' enters a recursive editing level, in which you can
5597 perform editing that is not part of the macro. When you exit the
5598 recursive edit using `C-M-c', you are asked again how to continue with
5599 the keyboard macro. If you type a <SPC> at this time, the rest of the
5600 macro definition is executed. It is up to you to leave point and the
5601 text in a state such that the rest of the macro will do what you want.
5603 `C-u C-x q', which is `C-x q' with a numeric argument, performs a
5604 different function. It enters a recursive edit reading input from the
5605 keyboard, both when you type it during the definition of the macro and
5606 when it is executed from the macro. During definition, the editing you
5607 do inside the recursive edit does not become part of the macro. During
5608 macro execution, the recursive edit gives you a chance to do some
5609 particularized editing. *Note Recursive Edit::.
5612 File: xemacs.info, Node: Key Bindings, Next: Syntax, Prev: Keyboard Macros, Up: Customization
5614 27.4 Customizing Key Bindings
5615 =============================
5617 This section deals with the "keymaps" that define the bindings between
5618 keys and functions, and shows how you can customize these bindings.
5620 A command is a Lisp function whose definition provides for
5621 interactive use. Like every Lisp function, a command has a function
5622 name, which is a Lisp symbol whose name usually consists of lower case
5623 letters and hyphens.
5627 * Keymaps:: Definition of the keymap data structure.
5628 Names of Emacs's standard keymaps.
5629 * Rebinding:: How to redefine one key's meaning conveniently.
5630 * Disabling:: Disabling a command means confirmation is required
5631 before it can be executed. This is done to protect
5632 beginners from surprises.
5635 File: xemacs.info, Node: Keymaps, Next: Rebinding, Up: Key Bindings
5640 The bindings between characters and command functions are recorded in
5641 data structures called "keymaps". Emacs has many of these. One, the
5642 "global" keymap, defines the meanings of the single-character keys that
5643 are defined regardless of major mode. It is the value of the variable
5646 Each major mode has another keymap, its "local keymap", which
5647 contains overriding definitions for the single-character keys that are
5648 redefined in that mode. Each buffer records which local keymap is
5649 installed for it at any time, and the current buffer's local keymap is
5650 the only one that directly affects command execution. The local keymaps
5651 for Lisp mode, C mode, and many other major modes always exist even when
5652 not in use. They are the values of the variables `lisp-mode-map',
5653 `c-mode-map', and so on. For less frequently used major modes, the
5654 local keymap is sometimes constructed only when the mode is used for the
5655 first time in a session, to save space.
5657 There are local keymaps for the minibuffer, too; they contain various
5658 completion and exit commands.
5660 * `minibuffer-local-map' is used for ordinary input (no completion).
5662 * `minibuffer-local-ns-map' is similar, except that <SPC> exits just
5663 like <RET>. This is used mainly for Mocklisp compatibility.
5665 * `minibuffer-local-completion-map' is for permissive completion.
5667 * `minibuffer-local-must-match-map' is for strict completion and for
5668 cautious completion.
5670 * `repeat-complex-command-map' is for use in `C-x <ESC> <ESC>'.
5672 * `isearch-mode-map' contains the bindings of the special keys which
5673 are bound in the pseudo-mode entered with `C-s' and `C-r'.
5675 Finally, each prefix key has a keymap which defines the key sequences
5676 that start with it. For example, `ctl-x-map' is the keymap used for
5677 characters following a `C-x'.
5679 * `ctl-x-map' is the variable name for the map used for characters
5682 * `help-map' is used for characters that follow `C-h'.
5684 * `esc-map' is for characters that follow <ESC>. All Meta characters
5685 are actually defined by this map.
5687 * `ctl-x-4-map' is for characters that follow `C-x 4'.
5689 * `mode-specific-map' is for characters that follow `C-c'.
5691 The definition of a prefix key is the keymap to use for looking up
5692 the following character. Sometimes the definition is actually a Lisp
5693 symbol whose function definition is the following character keymap. The
5694 effect is the same, but it provides a command name for the prefix key
5695 that you can use as a description of what the prefix key is for. Thus
5696 the binding of `C-x' is the symbol `Ctl-X-Prefix', whose function
5697 definition is the keymap for `C-x' commands, the value of `ctl-x-map'.
5699 Prefix key definitions can appear in either the global map or a
5700 local map. The definitions of `C-c', `C-x', `C-h', and <ESC> as prefix
5701 keys appear in the global map, so these prefix keys are always
5702 available. Major modes can locally redefine a key as a prefix by
5703 putting a prefix key definition for it in the local map.
5705 A mode can also put a prefix definition of a global prefix character
5706 such as `C-x' into its local map. This is how major modes override the
5707 definitions of certain keys that start with `C-x'. This case is
5708 special, because the local definition does not entirely replace the
5709 global one. When both the global and local definitions of a key are
5710 other keymaps, the next character is looked up in both keymaps, with
5711 the local definition overriding the global one. The character after the
5712 `C-x' is looked up in both the major mode's own keymap for redefined
5713 `C-x' commands and in `ctl-x-map'. If the major mode's own keymap for
5714 `C-x' commands contains `nil', the definition from the global keymap
5715 for `C-x' commands is used.
5718 File: xemacs.info, Node: Rebinding, Next: Disabling, Prev: Keymaps, Up: Key Bindings
5720 27.4.2 Changing Key Bindings
5721 ----------------------------
5723 You can redefine an Emacs key by changing its entry in a keymap. You
5724 can change the global keymap, in which case the change is effective in
5725 all major modes except those that have their own overriding local
5726 definitions for the same key. Or you can change the current buffer's
5727 local map, which affects all buffers using the same major mode.
5731 * Interactive Rebinding:: Changing Key Bindings Interactively
5732 * Programmatic Rebinding:: Changing Key Bindings Programmatically
5733 * Key Bindings Using Strings:: Using Strings for Changing Key Bindings
5736 File: xemacs.info, Node: Interactive Rebinding, Next: Programmatic Rebinding, Up: Rebinding
5738 27.4.2.1 Changing Key Bindings Interactively
5739 ............................................
5741 `M-x global-set-key <RET> KEY CMD <RET>'
5742 Defines KEY globally to run CMD.
5744 `M-x local-set-key <RET> KEYS CMD <RET>'
5745 Defines KEY locally (in the major mode now in effect) to run CMD.
5747 `M-x local-unset-key <RET> KEYS <RET>'
5748 Removes the local binding of KEY.
5750 CMD is a symbol naming an interactively-callable function.
5752 When called interactively, KEY is the next complete key sequence
5753 that you type. When called as a function, KEY is a string, a vector of
5754 events, or a vector of key-description lists as described in the
5755 `define-key' function description. The binding goes in the current
5756 buffer's local map, which is shared with other buffers in the same
5759 The following example:
5761 M-x global-set-key <RET> C-f next-line <RET>
5763 redefines `C-f' to move down a line. The fact that CMD is read second
5764 makes it serve as a kind of confirmation for KEY.
5766 These functions offer no way to specify a particular prefix keymap as
5767 the one to redefine in, but that is not necessary, as you can include
5768 prefixes in KEY. KEY is read by reading characters one by one until
5769 they amount to a complete key (that is, not a prefix key). Thus, if
5770 you type `C-f' for KEY, Emacs enters the minibuffer immediately to read
5771 CMD. But if you type `C-x', another character is read; if that
5772 character is `4', another character is read, and so on. For example,
5774 M-x global-set-key <RET> C-x 4 $ spell-other-window <RET>
5776 redefines `C-x 4 $' to run the (fictitious) command
5777 `spell-other-window'.
5779 The most general way to modify a keymap is the function
5780 `define-key', used in Lisp code (such as your init file). `define-key'
5781 takes three arguments: the keymap, the key to modify in it, and the new
5782 definition. *Note Init File::, for an example.
5783 `substitute-key-definition' is used similarly; it takes three
5784 arguments, an old definition, a new definition, and a keymap, and
5785 redefines in that keymap all keys that were previously defined with the
5786 old definition to have the new definition instead.
5789 File: xemacs.info, Node: Programmatic Rebinding, Next: Key Bindings Using Strings, Prev: Interactive Rebinding, Up: Rebinding
5791 27.4.2.2 Changing Key Bindings Programmatically
5792 ...............................................
5794 You can use the functions `global-set-key' and `define-key' to rebind
5795 keys under program control.
5797 ``(global-set-key KEYS CMD)''
5798 Defines KEYS globally to run CMD.
5800 ``(define-key KEYMAP KEYS DEF)''
5801 Defines KEYS to run DEF in the keymap KEYMAP.
5803 KEYMAP is a keymap object.
5805 KEYS is the sequence of keystrokes to bind.
5807 DEF is anything that can be a key's definition:
5809 * `nil', meaning key is undefined in this keymap
5811 * A command, that is, a Lisp function suitable for interactive
5814 * A string or key sequence vector, which is treated as a keyboard
5817 * A keymap to define a prefix key
5819 * A symbol so that when the key is looked up, the symbol stands for
5820 its function definition, which should at that time be one of the
5821 above, or another symbol whose function definition is used, and so
5824 * A cons, `(string . defn)', meaning that DEFN is the definition
5825 (DEFN should be a valid definition in its own right)
5827 * A cons, `(keymap . char)', meaning use the definition of CHAR in
5830 For backward compatibility, XEmacs allows you to specify key
5831 sequences as strings. However, the preferred method is to use the
5832 representations of key sequences as vectors of keystrokes. *Note
5833 Keystrokes::, for more information about the rules for constructing key
5836 Emacs allows you to abbreviate representations for key sequences in
5837 most places where there is no ambiguity. Here are some rules for
5840 * The keysym by itself is equivalent to a list of just that keysym,
5841 i.e., `f1' is equivalent to `(f1)'.
5843 * A keystroke by itself is equivalent to a vector containing just
5844 that keystroke, i.e., `(control a)' is equivalent to `[(control
5847 * You can use ASCII codes for keysyms that have them. i.e., `65' is
5848 equivalent to `A'. (This is not so much an abbreviation as an
5849 alternate representation.)
5851 Here are some examples of programmatically binding keys:
5854 ;;; Bind `my-command' to <f1>
5855 (global-set-key 'f1 'my-command)
5857 ;;; Bind `my-command' to Shift-f1
5858 (global-set-key '(shift f1) 'my-command)
5860 ;;; Bind `my-command' to C-c Shift-f1
5861 (global-set-key '[(control c) (shift f1)] 'my-command)
5863 ;;; Bind `my-command' to the middle mouse button.
5864 (global-set-key 'button2 'my-command)
5866 ;;; Bind `my-command' to <META> <CTL> <Right Mouse Button>
5867 ;;; in the keymap that is in force when you are running `dired'.
5868 (define-key dired-mode-map '(meta control button3) 'my-command)
5871 File: xemacs.info, Node: Key Bindings Using Strings, Prev: Programmatic Rebinding, Up: Rebinding
5873 27.4.2.3 Using Strings for Changing Key Bindings
5874 ................................................
5876 For backward compatibility, you can still use strings to represent key
5877 sequences. Thus you can use commands like the following:
5879 ;;; Bind `end-of-line' to C-f
5880 (global-set-key "\C-f" 'end-of-line)
5882 Note, however, that in some cases you may be binding more than one
5883 key sequence by using a single command. This situation can arise
5884 because in ASCII, `C-i' and <TAB> have the same representation.
5885 Therefore, when Emacs sees:
5887 (global-set-key "\C-i" 'end-of-line)
5889 it is unclear whether the user intended to bind `C-i' or <TAB>. The
5890 solution XEmacs adopts is to bind both of these key sequences.
5892 After binding a command to two key sequences with a form like:
5894 (define-key global-map "\^X\^I" 'command-1)
5896 it is possible to redefine only one of those sequences like so:
5898 (define-key global-map [(control x) (control i)] 'command-2)
5899 (define-key global-map [(control x) tab] 'command-3)
5901 This applies only when running under a window system. If you are
5902 talking to Emacs through an ASCII-only channel, you do not get any of
5905 Here is a table of pairs of key sequences that behave in a similar
5914 control @ control space
5917 File: xemacs.info, Node: Disabling, Prev: Rebinding, Up: Key Bindings
5919 27.4.3 Disabling Commands
5920 -------------------------
5922 Disabling a command marks it as requiring confirmation before it can be
5923 executed. The purpose of disabling a command is to prevent beginning
5924 users from executing it by accident and being confused.
5926 The direct mechanism for disabling a command is to have a non-`nil'
5927 `disabled' property on the Lisp symbol for the command. These
5928 properties are normally set by the user's init file with Lisp
5929 expressions such as:
5931 (put 'delete-region 'disabled t)
5935 If the value of the `disabled' property is a string, that string is
5936 included in the message printed when the command is used:
5938 (put 'delete-region 'disabled
5939 "Text deleted this way cannot be yanked back!\n")
5941 You can disable a command either by editing the init file directly
5942 or with the command `M-x disable-command', which edits the init file
5943 for you. *Note Init File::.
5945 When you attempt to invoke a disabled command interactively in Emacs,
5946 a window is displayed containing the command's name, its documentation,
5947 and some instructions on what to do next; then Emacs asks for input
5948 saying whether to execute the command as requested, enable it and
5949 execute, or cancel it. If you decide to enable the command, you are
5950 asked whether to do this permanently or just for the current session.
5951 Enabling permanently works by automatically editing your init file.
5952 You can use `M-x enable-command' at any time to enable any command
5955 Whether a command is disabled is independent of what key is used to
5956 invoke it; it also applies if the command is invoked using `M-x'.
5957 Disabling a command has no effect on calling it as a function from Lisp
5961 File: xemacs.info, Node: Syntax, Next: Init File, Prev: Key Bindings, Up: Customization
5963 27.5 The Syntax Table
5964 =====================
5966 All the Emacs commands which parse words or balance parentheses are
5967 controlled by the "syntax table". The syntax table specifies which
5968 characters are opening delimiters, which are parts of words, which are
5969 string quotes, and so on. Actually, each major mode has its own syntax
5970 table (though sometimes related major modes use the same one) which it
5971 installs in each buffer that uses that major mode. The syntax table
5972 installed in the current buffer is the one that all commands use, so we
5973 call it "the" syntax table. A syntax table is a Lisp object, a vector
5974 of length 256 whose elements are numbers.
5978 * Entry: Syntax Entry. What the syntax table records for each character.
5979 * Change: Syntax Change. How to change the information.
5982 File: xemacs.info, Node: Syntax Entry, Next: Syntax Change, Up: Syntax
5984 27.5.1 Information About Each Character
5985 ---------------------------------------
5987 The syntax table entry for a character is a number that encodes six
5988 pieces of information:
5990 * The syntactic class of the character, represented as a small
5993 * The matching delimiter, for delimiter characters only (the
5994 matching delimiter of `(' is `)', and vice versa)
5996 * A flag saying whether the character is the first character of a
5997 two-character comment starting sequence
5999 * A flag saying whether the character is the second character of a
6000 two-character comment starting sequence
6002 * A flag saying whether the character is the first character of a
6003 two-character comment ending sequence
6005 * A flag saying whether the character is the second character of a
6006 two-character comment ending sequence
6008 The syntactic classes are stored internally as small integers, but
6009 are usually described to or by the user with characters. For example,
6010 `(' is used to specify the syntactic class of opening delimiters. Here
6011 is a table of syntactic classes, with the characters that specify them.
6014 The class of whitespace characters. Please don't use the formerly
6015 advertised , which is not supported by GNU Emacs.
6018 The class of word-constituent characters.
6021 The class of characters that are part of symbol names but not
6022 words. This class is represented by `_' because the character `_'
6023 has this class in both C and Lisp.
6026 The class of punctuation characters that do not fit into any other
6030 The class of opening delimiters.
6033 The class of closing delimiters.
6036 The class of expression-adhering characters. These characters are
6037 part of a symbol if found within or adjacent to one, and are part
6038 of a following expression if immediately preceding one, but are
6039 like whitespace if surrounded by whitespace.
6042 The class of string-quote characters. They match each other in
6043 pairs, and the characters within the pair all lose their syntactic
6044 significance except for the `\' and `/' classes of escape
6045 characters, which can be used to include a string-quote inside the
6049 The class of self-matching delimiters. This is intended for TeX's
6050 `$', which is used both to enter and leave math mode. Thus, a
6051 pair of matching `$' characters surround each piece of math mode
6052 TeX input. A pair of adjacent `$' characters act like a single
6053 one for purposes of matching.
6056 The class of escape characters that always just deny the following
6057 character its special syntactic significance. The character after
6058 one of these escapes is always treated as alphabetic.
6061 The class of C-style escape characters. In practice, these are
6062 treated just like `/'-class characters, because the extra
6063 possibilities for C escapes (such as being followed by digits)
6064 have no effect on where the containing expression ends.
6067 The class of comment-starting characters. Only single-character
6068 comment starters (such as `;' in Lisp mode) are represented this
6072 The class of comment-ending characters. Newline has this syntax in
6075 The characters flagged as part of two-character comment delimiters
6076 can have other syntactic functions most of the time. For example, `/'
6077 and `*' in C code, when found separately, have nothing to do with
6078 comments. The comment-delimiter significance overrides when the pair of
6079 characters occur together in the proper order. Only the list and sexp
6080 commands use the syntax table to find comments; the commands
6081 specifically for comments have other variables that tell them where to
6082 find comments. Moreover, the list and sexp commands notice comments
6083 only if `parse-sexp-ignore-comments' is non-`nil'. This variable is set
6084 to `nil' in modes where comment-terminator sequences are liable to
6085 appear where there is no comment, for example, in Lisp mode where the
6086 comment terminator is a newline but not every newline ends a comment.
6089 File: xemacs.info, Node: Syntax Change, Prev: Syntax Entry, Up: Syntax
6091 27.5.2 Altering Syntax Information
6092 ----------------------------------
6094 It is possible to alter a character's syntax table entry by storing a
6095 new number in the appropriate element of the syntax table, but it would
6096 be hard to determine what number to use. Emacs therefore provides a
6097 command that allows you to specify the syntactic properties of a
6098 character in a convenient way.
6100 `M-x modify-syntax-entry' is the command to change a character's
6101 syntax. It can be used interactively and is also used by major modes
6102 to initialize their own syntax tables. Its first argument is the
6103 character to change. The second argument is a string that specifies the
6104 new syntax. When called from Lisp code, there is a third, optional
6105 argument, which specifies the syntax table in which to make the change.
6106 If not supplied, or if this command is called interactively, the third
6107 argument defaults to the current buffer's syntax table.
6109 1. The first character in the string specifies the syntactic class.
6110 It is one of the characters in the previous table (*note Syntax
6113 2. The second character is the matching delimiter. For a character
6114 that is not an opening or closing delimiter, this should be a
6115 space, and may be omitted if no following characters are needed.
6117 3. The remaining characters are flags. The flag characters allowed
6121 Flag this character as the first of a two-character comment
6125 Flag this character as the second of a two-character comment
6129 Flag this character as the first of a two-character comment
6133 Flag this character as the second of a two-character comment
6136 Use `C-h s' (`describe-syntax') to display a description of the
6137 contents of the current syntax table. The description of each
6138 character includes both the string you have to pass to
6139 `modify-syntax-entry' to set up that character's current syntax, and
6140 some English to explain that string if necessary.
6143 File: xemacs.info, Node: Init File, Next: Audible Bell, Prev: Syntax, Up: Customization
6148 When you start Emacs, it normally loads either `.xemacs/init.el' or the
6149 file `.emacs' (whichever comes first) in your home directory. This
6150 file, if it exists, should contain Lisp code. It is called your
6151 initialization file or "init file". Use the command line switch `-q'
6152 to tell Emacs whether to load an init file (*note Entering Emacs::).
6153 Use the command line switch `-user-init-file' (*note Command
6154 Switches::) to tell Emacs to load a different file instead of
6155 `~/.xemacs/init.el'/`~/.emacs'.
6157 When the init file is read, the variable `user-init-file' says which
6158 init file was loaded.
6160 At some sites there is a "default init file", which is the library
6161 named `default.el', found via the standard search path for libraries.
6162 The Emacs distribution contains no such library; your site may create
6163 one for local customizations. If this library exists, it is loaded
6164 whenever you start Emacs. But your init file, if any, is loaded first;
6165 if it sets `inhibit-default-init' non-`nil', then `default' is not
6168 If you have a large amount of code in your init file, you should
6169 byte-compile it to `~/.xemacs/init.elc' or `~/.emacs.elc'.
6173 * Init Syntax:: Syntax of constants in Emacs Lisp.
6174 * Init Examples:: How to do some things with an init file.
6175 * Terminal Init:: Each terminal type can have an init file.
6178 File: xemacs.info, Node: Init Syntax, Next: Init Examples, Up: Init File
6180 27.6.1 Init File Syntax
6181 -----------------------
6183 The init file contains one or more Lisp function call expressions.
6184 Each consists of a function name followed by arguments, all surrounded
6185 by parentheses. For example, `(setq fill-column 60)' represents a call
6186 to the function `setq' which is used to set the variable `fill-column'
6187 (*note Filling::) to 60.
6189 The second argument to `setq' is an expression for the new value of
6190 the variable. This can be a constant, a variable, or a function call
6191 expression. In the init file, constants are used most of the time.
6195 Integers are written in decimal, with an optional initial minus
6198 If a sequence of digits is followed by a period and another
6199 sequence of digits, it is interpreted as a floating point number.
6201 The number prefixes `#b', `#o', and `#x' are supported to
6202 represent numbers in binary, octal, and hexadecimal notation (or
6206 Lisp string syntax is the same as C string syntax with a few extra
6207 features. Use a double-quote character to begin and end a string
6210 Newlines and special characters may be present literally in
6211 strings. They can also be represented as backslash sequences:
6212 `\n' for newline, `\b' for backspace, `\r' for return, `\t' for
6213 tab, `\f' for formfeed (control-l), `\e' for escape, `\\' for a
6214 backslash, `\"' for a double-quote, or `\OOO' for the character
6215 whose octal code is OOO. Backslash and double-quote are the only
6216 characters for which backslash sequences are mandatory.
6218 You can use `\C-' as a prefix for a control character, as in
6219 `\C-s' for ASCII Control-S, and `\M-' as a prefix for a Meta
6220 character, as in `\M-a' for Meta-A or `\M-\C-a' for Control-Meta-A.
6223 Lisp character constant syntax consists of a `?' followed by
6224 either a character or an escape sequence starting with `\'.
6225 Examples: `?x', `?\n', `?\"', `?\)'. Note that strings and
6226 characters are not interchangeable in Lisp; some contexts require
6227 one and some contexts require the other.
6230 `t' stands for `true'.
6233 `nil' stands for `false'.
6236 Write a single-quote (') followed by the Lisp object you want.
6239 File: xemacs.info, Node: Init Examples, Next: Terminal Init, Prev: Init Syntax, Up: Init File
6241 27.6.2 Init File Examples
6242 -------------------------
6244 Here are some examples of doing certain commonly desired things with
6247 * Make <TAB> in C mode just insert a tab if point is in the middle
6250 (setq c-tab-always-indent nil)
6252 Here we have a variable whose value is normally `t' for `true' and
6253 the alternative is `nil' for `false'.
6255 * Make searches case sensitive by default (in all buffers that do not
6258 (setq-default case-fold-search nil)
6260 This sets the default value, which is effective in all buffers
6261 that do not have local values for the variable. Setting
6262 `case-fold-search' with `setq' affects only the current buffer's
6263 local value, which is probably not what you want to do in an init
6266 * Make Text mode the default mode for new buffers.
6268 (setq default-major-mode 'text-mode)
6270 Note that `text-mode' is used because it is the command for
6271 entering the mode we want. A single-quote is written before it to
6272 make a symbol constant; otherwise, `text-mode' would be treated as
6275 * Turn on Auto Fill mode automatically in Text mode and related
6278 (setq text-mode-hook
6279 '(lambda () (auto-fill-mode 1)))
6281 Here we have a variable whose value should be a Lisp function. The
6282 function we supply is a list starting with `lambda', and a single
6283 quote is written in front of it to make it (for the purpose of this
6284 `setq') a list constant rather than an expression. Lisp functions
6285 are not explained here; for mode hooks it is enough to know that
6286 `(auto-fill-mode 1)' is an expression that will be executed when
6287 Text mode is entered. You could replace it with any other
6288 expression that you like, or with several expressions in a row.
6290 (setq text-mode-hook 'turn-on-auto-fill)
6292 This is another way to accomplish the same result.
6293 `turn-on-auto-fill' is a symbol whose function definition is
6294 `(lambda () (auto-fill-mode 1))'.
6296 * Load the installed Lisp library named `foo' (actually a file
6297 `foo.elc' or `foo.el' in a standard Emacs directory).
6301 When the argument to `load' is a relative pathname, not starting
6302 with `/' or `~', `load' searches the directories in `load-path'
6305 * Load the compiled Lisp file `foo.elc' from your home directory.
6309 Here an absolute file name is used, so no searching is done.
6311 * Rebind the key `C-x l' to run the function `make-symbolic-link'.
6313 (global-set-key "\C-xl" 'make-symbolic-link)
6317 (define-key global-map "\C-xl" 'make-symbolic-link)
6319 Note once again the single-quote used to refer to the symbol
6320 `make-symbolic-link' instead of its value as a variable.
6322 * Do the same thing for C mode only.
6324 (define-key c-mode-map "\C-xl" 'make-symbolic-link)
6326 * Bind the function key <F1> to a command in C mode. Note that the
6327 names of function keys must be lower case.
6329 (define-key c-mode-map 'f1 'make-symbolic-link)
6331 * Bind the shifted version of <F1> to a command.
6333 (define-key c-mode-map '(shift f1) 'make-symbolic-link)
6335 * Redefine all keys which now run `next-line' in Fundamental mode to
6336 run `forward-line' instead.
6338 (substitute-key-definition 'next-line 'forward-line
6341 * Make `C-x C-v' undefined.
6343 (global-unset-key "\C-x\C-v")
6345 One reason to undefine a key is so that you can make it a prefix.
6346 Simply defining `C-x C-v ANYTHING' would make `C-x C-v' a prefix,
6347 but `C-x C-v' must be freed of any non-prefix definition first.
6349 * Make `$' have the syntax of punctuation in Text mode. Note the
6350 use of a character constant for `$'.
6352 (modify-syntax-entry ?\$ "." text-mode-syntax-table)
6354 * Enable the use of the command `eval-expression' without
6357 (put 'eval-expression 'disabled nil)
6360 File: xemacs.info, Node: Terminal Init, Prev: Init Examples, Up: Init File
6362 27.6.3 Terminal-Specific Initialization
6363 ---------------------------------------
6365 Each terminal type can have a Lisp library to be loaded into Emacs when
6366 it is run on that type of terminal. For a terminal type named
6367 TERMTYPE, the library is called `term/TERMTYPE' and it is found by
6368 searching the directories `load-path' as usual and trying the suffixes
6369 `.elc' and `.el'. Normally it appears in the subdirectory `term' of
6370 the directory where most Emacs libraries are kept.
6372 The usual purpose of the terminal-specific library is to define the
6373 escape sequences used by the terminal's function keys using the library
6374 `keypad.el'. See the file `term/vt100.el' for an example of how this
6377 When the terminal type contains a hyphen, only the part of the name
6378 before the first hyphen is significant in choosing the library name.
6379 Thus, terminal types `aaa-48' and `aaa-30-rv' both use the library
6380 `term/aaa'. The code in the library can use `(getenv "TERM")' to find
6381 the full terminal type name.
6383 The library's name is constructed by concatenating the value of the
6384 variable `term-file-prefix' and the terminal type. Your init file can
6385 prevent the loading of the terminal-specific library by setting
6386 `term-file-prefix' to `nil'. *Note Init File::.
6388 The value of the variable `term-setup-hook', if not `nil', is called
6389 as a function of no arguments at the end of Emacs initialization, after
6390 both your init file and any terminal-specific library have been read.
6391 *Note Init File::. You can set the value in the init file to override
6392 part of any of the terminal-specific libraries and to define
6393 initializations for terminals that do not have a library.
6396 File: xemacs.info, Node: Audible Bell, Next: Faces, Prev: Init File, Up: Customization
6398 27.7 Changing the Bell Sound
6399 ============================
6401 You can now change how the audible bell sounds using the variable
6404 `sound-alist''s value is an list associating symbols with, among
6405 other things, strings of audio-data. When `ding' is called with one of
6406 the symbols, the associated sound data is played instead of the
6407 standard beep. This only works if you are logged in on the console of a
6408 machine with audio hardware. To listen to a sound of the provided type,
6409 call the function `play-sound' with the argument SOUND. You can also
6410 set the volume of the sound with the optional argument VOLUME.
6412 Each element of `sound-alist' is a list describing a sound. The
6413 first element of the list is the name of the sound being defined.
6414 Subsequent elements of the list are alternating keyword/value pairs:
6417 A string of raw sound data, or the name of another sound to play.
6418 The symbol `t' here means use the default X beep.
6421 An integer from 0-100, defaulting to `bell-volume'.
6424 If using the default X beep, the pitch (Hz) to generate.
6427 If using the default X beep, the duration (milliseconds).
6429 For compatibility, elements of `sound-alist' may also be of the form:
6431 ( SOUND-NAME . <SOUND> )
6432 ( SOUND-NAME <VOLUME> <SOUND> )
6434 You should probably add things to this list by calling the function
6437 Note that you can only play audio data if running on the console
6438 screen of a machine with audio hardware which emacs understands, which
6439 at this time means a Sun SparcStation, SGI, or HP9000s700.
6441 Also note that the pitch, duration, and volume options are available
6442 everywhere, but most X servers ignore the `pitch' option.
6444 The variable `bell-volume' should be an integer from 0 to 100, with
6445 100 being loudest, which controls how loud the sounds emacs makes
6446 should be. Elements of the `sound-alist' may override this value.
6447 This variable applies to the standard X bell sound as well as sound
6450 If the symbol `t' is in place of a sound-string, Emacs uses the
6451 default X beep. This allows you to define beep-types of different
6452 volumes even when not running on the console.
6454 You can add things to this list by calling the function
6455 `load-sound-file', which reads in an audio-file and adds its data to
6456 the sound-alist. You can specify the sound with the SOUND-NAME argument
6457 and the file into which the sounds are loaded with the FILENAME
6458 argument. The optional VOLUME argument sets the volume.
6460 `load-sound-file (FILENAME SOUND-NAME &optional VOLUME)'
6462 To load and install some sound files as beep-types, use the function
6463 `load-default-sounds' (note that this only works if you are on display
6464 0 of a machine with audio hardware).
6466 The following beep-types are used by Emacs itself. Other Lisp
6467 packages may use other beep types, but these are the ones that the C
6468 kernel of Emacs uses.
6471 An auto-save does not succeed
6474 The Emacs command loop catches an error
6477 You type a key that is undefined
6480 You use an undefined mouse-click combination
6483 Completion was not possible
6486 You type something other than the required `y' or `n'
6489 You type something other than `yes' or `no'
6492 File: xemacs.info, Node: Faces, Next: Frame Components, Prev: Audible Bell, Up: Customization
6497 XEmacs has objects called extents and faces. An "extent" is a region
6498 of text and a "face" is a collection of textual attributes, such as
6499 fonts and colors. Every extent is displayed in some face; therefore,
6500 changing the properties of a face immediately updates the display of
6501 all associated extents. Faces can be frame-local: you can have a
6502 region of text that displays with completely different attributes when
6503 its buffer is viewed from a different X window.
6505 The display attributes of faces may be specified either in Lisp or
6506 through the X resource manager.
6508 27.8.1 Customizing Faces
6509 ------------------------
6511 You can change the face of an extent with the functions in this
6512 section. All the functions prompt for a FACE as an argument; use
6513 completion for a list of possible values.
6516 Swap the foreground and background colors of the given FACE.
6518 `M-x make-face-bold'
6519 Make the font of the given FACE bold. When called from a program,
6520 returns `nil' if this is not possible.
6522 `M-x make-face-bold-italic'
6523 Make the font of the given FACE bold italic. When called from a
6524 program, returns `nil' if not possible.
6526 `M-x make-face-italic'
6527 Make the font of the given FACE italic. When called from a
6528 program, returns `nil' if not possible.
6530 `M-x make-face-unbold'
6531 Make the font of the given FACE non-bold. When called from a
6532 program, returns `nil' if not possible.
6534 `M-x make-face-unitalic'
6535 Make the font of the given FACE non-italic. When called from a
6536 program, returns `nil' if not possible.
6538 `M-x make-face-larger'
6539 Make the font of the given FACE a little larger. When called from
6540 a program, returns `nil' if not possible.
6542 `M-x make-face-smaller'
6543 Make the font of the given FACE a little smaller. When called
6544 from a program, returns `nil' if not possible.
6546 `M-x set-face-background'
6547 Change the background color of the given FACE.
6549 `M-x set-face-background-pixmap'
6550 Change the background pixmap of the given FACE.
6553 Change the font of the given FACE.
6555 `M-x set-face-foreground'
6556 Change the foreground color of the given FACE.
6558 `M-x set-face-underline-p'
6559 Change whether the given FACE is underlined.
6561 You can exchange the foreground and background color of the selected
6562 FACE with the function `invert-face'. If the face does not specify both
6563 foreground and background, then its foreground and background are set
6564 to the background and foreground of the default face. When calling
6565 this from a program, you can supply the optional argument FRAME to
6566 specify which frame is affected; otherwise, all frames are affected.
6568 The work of `make-face-bold', `make-face-bold-italic',
6569 `make-face-italic', `make-face-unbold', `make-face-unitalic' functions
6570 is affected by `face-frob-from-locale-first' variable. If it is `nil',
6571 those functions first try to manipulate device specific data like X
6572 font names to obtain the desired font face specification. This may be
6573 unsuitable in environments using different font face specifications for
6574 different frames, non-Mule environments in particular.
6576 If the variable is non-`nil', those functions first try to figure
6577 out whether the face font is the same as one of predefined faces:
6578 `default', `bold', `italic', `bold-italic'. If it is the same, then
6579 the new face font specification is set to be the same as that of a
6580 corresponding predefined face. Thus if the predefined face is set up
6581 properly for different frames, the same will hold for the face being
6582 changed by the functions. This is the behavior one might desire in
6583 non-Mule environments mentioned above: face being changed still looks
6584 right in all frames.
6586 How predefined faces might be set up for different frames in such an
6587 environments is described in *Note Face Resources::.
6589 You can set the background color of the specified FACE with the
6590 function `set-face-background'. The argument `color' should be a
6591 string, the name of a color. When called from a program, if the
6592 optional FRAME argument is provided, the face is changed only in that
6593 frame; otherwise, it is changed in all frames.
6595 You can set the background pixmap of the specified FACE with the
6596 function `set-face-background-pixmap'. The pixmap argument NAME should
6597 be a string, the name of a file of pixmap data. The directories listed
6598 in the `x-bitmap-file-path' variable are searched. The bitmap may also
6599 be a list of the form `(WIDTH HEIGHT DATA)', where WIDTH and HEIGHT are
6600 the size in pixels, and DATA is a string containing the raw bits of the
6601 bitmap. If the optional FRAME argument is provided, the face is
6602 changed only in that frame; otherwise, it is changed in all frames.
6604 The variable `x-bitmap-file-path' takes as a value a list of the
6605 directories in which X bitmap files may be found. If the value is
6606 `nil', the list is initialized from the `*bitmapFilePath' resource.
6608 If the environment variable XBMLANGPATH is set, then it is consulted
6609 before the `x-bitmap-file-path' variable.
6611 You can set the font of the specified FACE with the function
6612 `set-face-font'. The FONT argument should be a string, the name of a
6613 font. When called from a program, if the optional FRAME argument is
6614 provided, the face is changed only in that frame; otherwise, it is
6615 changed in all frames.
6617 You can set the foreground color of the specified FACE with the
6618 function `set-face-foreground'. The argument COLOR should be a string,
6619 the name of a color. If the optional FRAME argument is provided, the
6620 face is changed only in that frame; otherwise, it is changed in all
6623 You can set underline the specified FACE with the function
6624 `set-face-underline-p'. The argument UNDERLINE-P can be used to make
6625 underlining an attribute of the face or not. If the optional FRAME
6626 argument is provided, the face is changed only in that frame;
6627 otherwise, it is changed in all frames.
6630 File: xemacs.info, Node: Frame Components, Next: X Resources, Prev: Faces, Up: Customization
6632 27.9 Frame Components
6633 =====================
6635 You can control the presence and position of most frame components, such
6636 as the menubar, toolbars, and gutters.
6638 This section is not written yet. Try the Lisp Reference Manual:
6639 *Note Menubar: (lispref)Menubar, *Note Toolbar Intro: (lispref)Toolbar
6640 Intro, and *Note Gutter Intro: (lispref)Gutter Intro.
6643 File: xemacs.info, Node: X Resources, Prev: Frame Components, Up: Customization
6648 Historically, XEmacs has used the X resource application class `Emacs'
6649 for its resources. Unfortunately, GNU Emacs uses the same application
6650 class, and resources are not compatible between the two Emacsen. This
6651 sharing of the application class often leads to trouble if you want to
6654 Starting with XEmacs 21, XEmacs uses the class `XEmacs' if it finds
6655 any XEmacs resources in the resource database when the X connection is
6656 initialized. Otherwise, it will use the class `Emacs' for backwards
6657 compatibility. The variable `x-emacs-application-class' may be
6658 consulted to determine the application class being used.
6660 The examples in this section assume the application class is `Emacs'.
6662 The Emacs resources are generally set per-frame. Each Emacs frame
6663 can have its own name or the same name as another, depending on the
6664 name passed to the `make-frame' function.
6666 You can specify resources for all frames with the syntax:
6668 Emacs*parameter: value
6671 Emacs*EmacsFrame.parameter:value
6672 You can specify resources for a particular frame with the syntax:
6674 Emacs*FRAME-NAME.parameter: value
6678 * Geometry Resources:: Controlling the size and position of frames.
6679 * Iconic Resources:: Controlling whether frames come up iconic.
6680 * Resource List:: List of resources settable on a frame or device.
6681 * Face Resources:: Controlling faces using resources.
6682 * Widgets:: The widget hierarchy for XEmacs.
6683 * Menubar Resources:: Specifying resources for the menubar.
6686 File: xemacs.info, Node: Geometry Resources, Next: Iconic Resources, Up: X Resources
6688 27.10.1 Geometry Resources
6689 --------------------------
6691 To make the default size of all Emacs frames be 80 columns by 55 lines,
6694 Emacs*EmacsFrame.geometry: 80x55
6695 To set the geometry of a particular frame named `fred', do this:
6697 Emacs*fred.geometry: 80x55
6698 Important! Do not use the following syntax:
6700 Emacs*geometry: 80x55
6701 You should never use `*geometry' with any X application. It does not
6702 say "make the geometry of Emacs be 80 columns by 55 lines." It really
6703 says, "make Emacs and all subwindows thereof be 80x55 in whatever units
6704 they care to measure in." In particular, that is both telling the
6705 Emacs text pane to be 80x55 in characters, and telling the menubar pane
6706 to be 80x55 pixels, which is surely not what you want.
6708 As a special case, this geometry specification also works (and sets
6709 the default size of all Emacs frames to 80 columns by 55 lines):
6711 Emacs.geometry: 80x55
6712 since that is the syntax used with most other applications (since
6713 most other applications have only one top-level window, unlike Emacs).
6714 In general, however, the top-level shell (the unmapped ApplicationShell
6715 widget named `Emacs' that is the parent of the shell widgets that
6716 actually manage the individual frames) does not have any interesting
6717 resources on it, and you should set the resources on the frames instead.
6719 The `-geometry' command-line argument sets only the geometry of the
6720 initial frame created by Emacs.
6722 A more complete explanation of geometry-handling is
6724 * The `-geometry' command-line option sets the `Emacs.geometry'
6725 resource, that is, the geometry of the ApplicationShell.
6727 * For the first frame created, the size of the frame is taken from
6728 the ApplicationShell if it is specified, otherwise from the
6729 geometry of the frame.
6731 * For subsequent frames, the order is reversed: First the frame, and
6732 then the ApplicationShell.
6734 * For the first frame created, the position of the frame is taken
6735 from the ApplicationShell (`Emacs.geometry') if it is specified,
6736 otherwise from the geometry of the frame.
6738 * For subsequent frames, the position is taken only from the frame,
6739 and never from the ApplicationShell.
6741 This is rather complicated, but it does seem to provide the most
6742 intuitive behavior with respect to the default sizes and positions of
6743 frames created in various ways.
6746 File: xemacs.info, Node: Iconic Resources, Next: Resource List, Prev: Geometry Resources, Up: X Resources
6748 27.10.2 Iconic Resources
6749 ------------------------
6751 Analogous to `-geometry', the `-iconic' command-line option sets the
6752 iconic flag of the ApplicationShell (`Emacs.iconic') and always applies
6753 to the first frame created regardless of its name. However, it is
6754 possible to set the iconic flag on particular frames (by name) by using
6755 the `Emacs*FRAME-NAME.iconic' resource.
6758 File: xemacs.info, Node: Resource List, Next: Face Resources, Prev: Iconic Resources, Up: X Resources
6760 27.10.3 Resource List
6761 ---------------------
6763 Emacs frames accept the following resources:
6765 `geometry' (class `Geometry'): string
6766 Initial geometry for the frame. *Note Geometry Resources::, for a
6767 complete discussion of how this works.
6769 `iconic' (class `Iconic'): boolean
6770 Whether this frame should appear in the iconified state.
6772 `internalBorderWidth' (class `InternalBorderWidth'): int
6773 How many blank pixels to leave between the text and the edge of the
6776 `interline' (class `Interline'): int
6777 How many pixels to leave between each line (may not be
6780 `menubar' (class `Menubar'): boolean
6781 Whether newly-created frames should initially have a menubar. Set
6784 `initiallyUnmapped' (class `InitiallyUnmapped'): boolean
6785 Whether XEmacs should leave the initial frame unmapped when it
6786 starts up. This is useful if you are starting XEmacs as a server
6787 (e.g. in conjunction with gnuserv or the external client widget).
6788 You can also control this with the `-unmapped' command-line option.
6790 `barCursor' (class `BarColor'): boolean
6791 Whether the cursor should be displayed as a bar, or the
6794 `cursorColor' (class `CursorColor'): color-name
6795 The color of the text cursor.
6797 `scrollBarWidth' (class `ScrollBarWidth'): integer
6798 How wide the vertical scrollbars should be, in pixels; 0 means no
6799 vertical scrollbars. You can also use a resource specification of
6800 the form `*scrollbar.width', or the usual toolkit scrollbar
6801 resources: `*XmScrollBar.width' (Motif), `*XlwScrollBar.width'
6802 (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend
6803 that you use the toolkit resources, though, because they're
6804 dependent on how exactly your particular build of XEmacs was
6807 `scrollBarHeight' (class `ScrollBarHeight'): integer
6808 How high the horizontal scrollbars should be, in pixels; 0 means no
6809 horizontal scrollbars. You can also use a resource specification
6810 of the form `*scrollbar.height', or the usual toolkit scrollbar
6811 resources: `*XmScrollBar.height' (Motif), `*XlwScrollBar.height'
6812 (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend
6813 that you use the toolkit resources, though, because they're
6814 dependent on how exactly your particular build of XEmacs was
6817 `scrollBarPlacement' (class `ScrollBarPlacement'): string
6818 Where the horizontal and vertical scrollbars should be positioned.
6819 This should be one of the four strings `BOTTOM_LEFT',
6820 `BOTTOM_RIGHT', `TOP_LEFT', and `TOP_RIGHT'. Default is
6821 `BOTTOM_RIGHT' for the Motif and Lucid scrollbars and
6822 `BOTTOM_LEFT' for the Athena scrollbars.
6824 `topToolBarHeight' (class `TopToolBarHeight'): integer
6825 `bottomToolBarHeight' (class `BottomToolBarHeight'): integer
6826 `leftToolBarWidth' (class `LeftToolBarWidth'): integer
6827 `rightToolBarWidth' (class `RightToolBarWidth'): integer
6828 Height and width of the four possible toolbars.
6830 `topToolBarShadowColor' (class `TopToolBarShadowColor'): color-name
6831 `bottomToolBarShadowColor' (class `BottomToolBarShadowColor'): color-name
6832 Color of the top and bottom shadows for the toolbars. NOTE: These
6833 resources do _not_ have anything to do with the top and bottom
6834 toolbars (i.e. the toolbars at the top and bottom of the frame)!
6835 Rather, they affect the top and bottom shadows around the edges of
6836 all four kinds of toolbars.
6838 `topToolBarShadowPixmap' (class `TopToolBarShadowPixmap'): pixmap-name
6839 `bottomToolBarShadowPixmap' (class `BottomToolBarShadowPixmap'): pixmap-name
6840 Pixmap of the top and bottom shadows for the toolbars. If set,
6841 these resources override the corresponding color resources. NOTE:
6842 These resources do _not_ have anything to do with the top and
6843 bottom toolbars (i.e. the toolbars at the top and bottom of the
6844 frame)! Rather, they affect the top and bottom shadows around the
6845 edges of all four kinds of toolbars.
6847 `toolBarShadowThickness' (class `ToolBarShadowThickness'): integer
6848 Thickness of the shadows around the toolbars, in pixels.
6850 `visualBell' (class `VisualBell'): boolean
6851 Whether XEmacs should flash the screen rather than making an
6854 `bellVolume' (class `BellVolume'): integer
6855 Volume of the audible beep.
6857 `useBackingStore' (class `UseBackingStore'): boolean
6858 Whether XEmacs should set the backing-store attribute of the X
6859 windows it creates. This increases the memory usage of the X
6860 server but decreases the amount of X traffic necessary to update
6861 the screen, and is useful when the connection to the X server goes
6862 over a low-bandwidth line such as a modem connection.
6864 Emacs devices accept the following resources:
6866 `textPointer' (class `Cursor'): cursor-name
6867 The cursor to use when the mouse is over text. This resource is
6868 used to initialize the variable `x-pointer-shape'.
6870 `selectionPointer' (class `Cursor'): cursor-name
6871 The cursor to use when the mouse is over a selectable text region
6872 (an extent with the `highlight' property; for example, an Info
6873 cross-reference). This resource is used to initialize the variable
6874 `x-selection-pointer-shape'.
6876 `spacePointer' (class `Cursor'): cursor-name
6877 The cursor to use when the mouse is over a blank space in a buffer
6878 (that is, after the end of a line or after the end-of-file). This
6879 resource is used to initialize the variable
6880 `x-nontext-pointer-shape'.
6882 `modeLinePointer' (class `Cursor'): cursor-name
6883 The cursor to use when the mouse is over a modeline. This
6884 resource is used to initialize the variable `x-mode-pointer-shape'.
6886 `gcPointer' (class `Cursor'): cursor-name
6887 The cursor to display when a garbage-collection is in progress.
6888 This resource is used to initialize the variable
6889 `x-gc-pointer-shape'.
6891 `scrollbarPointer' (class `Cursor'): cursor-name
6892 The cursor to use when the mouse is over the scrollbar. This
6893 resource is used to initialize the variable
6894 `x-scrollbar-pointer-shape'.
6896 `pointerColor' (class `Foreground'): color-name
6897 `pointerBackground' (class `Background'): color-name
6898 The foreground and background colors of the mouse cursor. These
6899 resources are used to initialize the variables
6900 `x-pointer-foreground-color' and `x-pointer-background-color'.
6903 File: xemacs.info, Node: Face Resources, Next: Widgets, Prev: Resource List, Up: X Resources
6905 27.10.4 Face Resources
6906 ----------------------
6908 The attributes of faces are also per-frame. They can be specified as:
6910 Emacs.FACE_NAME.parameter: value
6913 Emacs*FRAME_NAME.FACE_NAME.parameter: value
6914 Faces accept the following resources:
6916 `attributeFont' (class `AttributeFont'): font-name
6917 The font of this face.
6919 `attributeForeground' (class `AttributeForeground'): color-name
6920 `attributeBackground' (class `AttributeBackground'): color-name
6921 The foreground and background colors of this face.
6923 `attributeBackgroundPixmap' (class `AttributeBackgroundPixmap'): file-name
6924 The name of an XBM file (or XPM file, if your version of Emacs
6925 supports XPM), to use as a background stipple.
6927 `attributeUnderline' (class `AttributeUnderline'): boolean
6928 Whether text in this face should be underlined.
6930 All text is displayed in some face, defaulting to the face named
6931 `default'. To set the font of normal text, use
6932 `Emacs*default.attributeFont'. To set it in the frame named `fred', use
6933 `Emacs*fred.default.attributeFont'.
6935 These are the names of the predefined faces:
6938 Everything inherits from this.
6941 If this is not specified in the resource database, Emacs tries to
6942 find a bold version of the font of the default face.
6945 If this is not specified in the resource database, Emacs tries to
6946 find an italic version of the font of the default face.
6949 If this is not specified in the resource database, Emacs tries to
6950 find a bold-italic version of the font of the default face.
6953 This is the face that the modeline is displayed in. If not
6954 specified in the resource database, it is determined from the
6955 default face by reversing the foreground and background colors.
6958 This is the face that highlighted extents (for example, Info
6959 cross-references and possible completions, when the mouse passes
6960 over them) are displayed in.
6964 These are the faces that the left and right annotation margins are
6968 This is the face that mouse selections are displayed in.
6971 This is the face that the matched text being searched for is
6975 This is the face of info menu items. If unspecified, it is copied
6979 This is the face of info cross-references. If unspecified, it is
6980 copied from `bold'. (Note that, when the mouse passes over a
6981 cross-reference, the cross-reference's face is determined from a
6982 combination of the `info-xref' and `highlight' faces.)
6984 Other packages might define their own faces; to see a list of all
6985 faces, use any of the interactive face-manipulation commands such as
6986 `set-face-font' and type `?' when you are prompted for the name of a
6989 If the `bold', `italic', and `bold-italic' faces are not specified
6990 in the resource database, then XEmacs attempts to derive them from the
6991 font of the default face. It can only succeed at this if you have
6992 specified the default font using the XLFD (X Logical Font Description)
6993 format, which looks like
6995 *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
6996 If you use any of the other, less strict font name formats, some of
6999 lucidasanstypewriter-12
7003 then XEmacs won't be able to guess the names of the bold and italic
7004 versions. All X fonts can be referred to via XLFD-style names, so you
7005 should use those forms. See the man pages for `X(1)', `xlsfonts(1)',
7009 File: xemacs.info, Node: Widgets, Next: Menubar Resources, Prev: Face Resources, Up: X Resources
7014 There are several structural widgets between the terminal EmacsFrame
7015 widget and the top level ApplicationShell; the exact names and types of
7016 these widgets change from release to release (for example, they changed
7017 between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are
7018 subject to further change in the future, so you should avoid mentioning
7019 them in your resource database. The above-mentioned syntaxes should be
7020 forward- compatible. As of 19.13, the exact widget hierarchy is as
7023 INVOCATION-NAME "shell" "container" FRAME-NAME
7024 x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame"
7026 where INVOCATION-NAME is the terminal component of the name of the
7027 XEmacs executable (usually `xemacs'), and `x-emacs-application-class'
7028 is generally `Emacs'.
7031 File: xemacs.info, Node: Menubar Resources, Prev: Widgets, Up: X Resources
7033 27.10.6 Menubar Resources
7034 -------------------------
7036 As the menubar is implemented as a widget which is not a part of XEmacs
7037 proper, it does not use the face mechanism for specifying fonts and
7038 colors: It uses whatever resources are appropriate to the type of widget
7039 which is used to implement it.
7041 If Emacs was compiled to use only the Lucid Motif-lookalike menu
7042 widgets, then one way to specify the font of the menubar would be
7044 Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
7046 If both the Lucid Motif-lookalike menu widgets and X Font Sets are
7047 configured to allow multilingual menubars, then one uses
7049 *menubar*FontSet: -*-helvetica-bold-r-*-*-*-120-*-*-*-*-iso8859-*, \
7050 -*-*-*-*-*-*-*-120-*-jisx0208.1983-0
7052 That would specify fonts for a Japanese menubar. Specifying only one
7053 XLFD is acceptable; specifying more than one for a given registry
7054 (language) is also allowed. When X Font Sets are configured, some .font
7055 resources (eg, menubars) are ignored in favor of the corresponding
7058 If the Motif library is being used, then one would have to use
7060 Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
7062 because the Motif library uses the `fontList' resource name instead
7063 of `font', which has subtly different semantics.
7065 The same is true of the scrollbars: They accept whichever resources
7066 are appropriate for the toolkit in use.
7069 File: xemacs.info, Node: Quitting, Next: Lossage, Prev: Customization, Up: Top
7071 27.11 Quitting and Aborting
7072 ===========================
7075 Quit. Cancel running or partially typed command.
7078 Abort innermost recursive editing level and cancel the command
7079 which invoked it (`abort-recursive-edit').
7082 Abort all recursive editing levels that are currently executing.
7085 Cancel an already-executed command, usually (`undo').
7087 There are two ways of cancelling commands which are not finished
7088 executing: "quitting" with `C-g', and "aborting" with `C-]' or `M-x
7089 top-level'. Quitting is cancelling a partially typed command or one
7090 which is already running. Aborting is getting out of a recursive
7091 editing level and cancelling the command that invoked the recursive
7094 Quitting with `C-g' is used for getting rid of a partially typed
7095 command or a numeric argument that you don't want. It also stops a
7096 running command in the middle in a relatively safe way, so you can use
7097 it if you accidentally start executing a command that takes a long
7098 time. In particular, it is safe to quit out of killing; either your
7099 text will ALL still be there, or it will ALL be in the kill ring (or
7100 maybe both). Quitting an incremental search does special things
7101 documented under searching; in general, it may take two successive
7102 `C-g' characters to get out of a search. `C-g' works by setting the
7103 variable `quit-flag' to `t' the instant `C-g' is typed; Emacs Lisp
7104 checks this variable frequently and quits if it is non-`nil'. `C-g' is
7105 only actually executed as a command if it is typed while Emacs is
7108 If you quit twice in a row before the first `C-g' is recognized, you
7109 activate the "emergency escape" feature and return to the shell. *Note
7112 You can use `C-]' (`abort-recursive-edit') to get out of a recursive
7113 editing level and cancel the command which invoked it. Quitting with
7114 `C-g' does not do this, and could not do this because it is used to
7115 cancel a partially typed command within the recursive editing level.
7116 Both operations are useful. For example, if you are in the Emacs
7117 debugger (*note Lisp Debug::) and have typed `C-u 8' to enter a numeric
7118 argument, you can cancel that argument with `C-g' and remain in the
7121 The command `M-x top-level' is equivalent to "enough" `C-]' commands
7122 to get you out of all the levels of recursive edits that you are in.
7123 `C-]' only gets you out one level at a time, but `M-x top-level' goes
7124 out all levels at once. Both `C-]' and `M-x top-level' are like all
7125 other commands and unlike `C-g' in that they are effective only when
7126 Emacs is ready for a command. `C-]' is an ordinary key and has its
7127 meaning only because of its binding in the keymap. *Note Recursive
7130 `C-x u' (`undo') is not strictly speaking a way of cancelling a
7131 command, but you can think of it as cancelling a command already
7132 finished executing. *Note Undo::.
7135 File: xemacs.info, Node: Lossage, Next: Bugs, Prev: Quitting, Up: Top
7137 27.12 Dealing With Emacs Trouble
7138 ================================
7140 This section describes various conditions in which Emacs fails to work,
7141 and how to recognize them and correct them.
7145 * Stuck Recursive:: `[...]' in mode line around the parentheses.
7146 * Screen Garbled:: Garbage on the screen.
7147 * Text Garbled:: Garbage in the text.
7148 * Unasked-for Search:: Spontaneous entry to incremental search.
7149 * Emergency Escape:: Emergency escape---
7150 What to do if Emacs stops responding.
7151 * Total Frustration:: When you are at your wits' end.
7154 File: xemacs.info, Node: Stuck Recursive, Next: Screen Garbled, Prev: Lossage, Up: Lossage
7156 27.12.1 Recursive Editing Levels
7157 --------------------------------
7159 Recursive editing levels are important and useful features of Emacs, but
7160 they can seem like malfunctions to the user who does not understand
7163 If the mode line has square brackets `[...]' around the parentheses
7164 that contain the names of the major and minor modes, you have entered a
7165 recursive editing level. If you did not do this on purpose, or if you
7166 don't understand what that means, you should just get out of the
7167 recursive editing level. To do so, type `M-x top-level'. This is
7168 called getting back to top level. *Note Recursive Edit::.
7171 File: xemacs.info, Node: Screen Garbled, Next: Text Garbled, Prev: Stuck Recursive, Up: Lossage
7173 27.12.2 Garbage on the Screen
7174 -----------------------------
7176 If the data on the screen looks wrong, the first thing to do is see
7177 whether the text is actually wrong. Type `C-l', to redisplay the
7178 entire screen. If the text appears correct after this, the problem was
7179 entirely in the previous screen update.
7181 Display updating problems often result from an incorrect termcap
7182 entry for the terminal you are using. The file `etc/TERMS' in the Emacs
7183 distribution gives the fixes for known problems of this sort.
7184 `INSTALL' contains general advice for these problems in one of its
7185 sections. Very likely there is simply insufficient padding for certain
7186 display operations. To investigate the possibility that you have this
7187 sort of problem, try Emacs on another terminal made by a different
7188 manufacturer. If problems happen frequently on one kind of terminal but
7189 not another kind, the real problem is likely to be a bad termcap entry,
7190 though it could also be due to a bug in Emacs that appears for terminals
7191 that have or lack specific features.
7194 File: xemacs.info, Node: Text Garbled, Next: Unasked-for Search, Prev: Screen Garbled, Up: Lossage
7196 27.12.3 Garbage in the Text
7197 ---------------------------
7199 If `C-l' shows that the text is wrong, try undoing the changes to it
7200 using `C-x u' until it gets back to a state you consider correct. Also
7201 try `C-h l' to find out what command you typed to produce the observed
7204 If a large portion of text appears to be missing at the beginning or
7205 end of the buffer, check for the word `Narrow' in the mode line. If it
7206 appears, the text is still present, but marked off-limits. To make it
7207 visible again, type `C-x n w'. *Note Narrowing::.
7210 File: xemacs.info, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage
7212 27.12.4 Spontaneous Entry to Incremental Search
7213 -----------------------------------------------
7215 If Emacs spontaneously displays `I-search:' at the bottom of the
7216 screen, it means that the terminal is sending `C-s' and `C-q' according
7217 to the poorly designed xon/xoff "flow control" protocol. You should
7218 try to prevent this by putting the terminal in a mode where it will not
7219 use flow control, or by giving it enough padding that it will never
7220 send a `C-s'. If that cannot be done, you must tell Emacs to expect
7221 flow control to be used, until you can get a properly designed terminal.
7223 Information on how to do these things can be found in the file
7224 `INSTALL' in the Emacs distribution.
7227 File: xemacs.info, Node: Emergency Escape, Next: Total Frustration, Prev: Unasked-for Search, Up: Lossage
7229 27.12.5 Emergency Escape
7230 ------------------------
7232 Because at times there have been bugs causing Emacs to loop without
7233 checking `quit-flag', a special feature causes Emacs to be suspended
7234 immediately if you type a second `C-g' while the flag is already set,
7235 so you can always get out of XEmacs. Normally Emacs recognizes and
7236 clears `quit-flag' (and quits!) quickly enough to prevent this from
7239 When you resume Emacs after a suspension caused by multiple `C-g', it
7240 asks two questions before going back to what it had been doing:
7243 Abort (and dump core)? (y or n)
7245 Answer each one with `y' or `n' followed by <RET>.
7247 Saying `y' to `Auto-save?' causes immediate auto-saving of all
7248 modified buffers in which auto-saving is enabled.
7250 Saying `y' to `Abort (and dump core)?' causes an illegal instruction
7251 to be executed, dumping core. This is to enable a wizard to figure out
7252 why Emacs was failing to quit in the first place. Execution does not
7253 continue after a core dump. If you answer `n', execution does
7254 continue. With luck, Emacs will ultimately check `quit-flag' and quit
7255 normally. If not, and you type another `C-g', it is suspended again.
7257 If Emacs is not really hung, but is just being slow, you may invoke
7258 the double `C-g' feature without really meaning to. In that case,
7259 simply resume and answer `n' to both questions, and you will arrive at
7260 your former state. Presumably the quit you requested will happen soon.
7262 The double-`C-g' feature may be turned off when Emacs is running
7263 under a window system, since the window system always enables you to
7264 kill Emacs or to create another window and run another program.
7267 File: xemacs.info, Node: Total Frustration, Prev: Emergency Escape, Up: Lossage
7269 27.12.6 Help for Total Frustration
7270 ----------------------------------
7272 If using Emacs (or something else) becomes terribly frustrating and none
7273 of the techniques described above solve the problem, Emacs can still
7276 First, if the Emacs you are using is not responding to commands, type
7277 `C-g C-g' to get out of it and then start a new one.
7279 Second, type `M-x doctor <RET>'.
7281 The doctor will make you feel better. Each time you say something to
7282 the doctor, you must end it by typing <RET> <RET>. This lets the
7283 doctor know you are finished.