X-Git-Url: http://git.chise.org/gitweb/?p=chise%2Fxemacs-chise.git.1;a=blobdiff_plain;f=info%2Fxemacs.info-3;h=a55d70b14657b7093c751925f7a4352a9be1710a;hp=80127b0b0e38f3d4aa181fba81f4f12d05aba10f;hb=79d2db7d65205bc85d471590726d0cf3af5598e0;hpb=59eec5f21669e81977b5b1fe9bf717cab49cf7fb diff --git a/info/xemacs.info-3 b/info/xemacs.info-3 index 80127b0..a55d70b 100644 --- a/info/xemacs.info-3 +++ b/info/xemacs.info-3 @@ -1,4 +1,4 @@ -This is ../info/xemacs.info, produced by makeinfo version 4.0 from +This is ../info/xemacs.info, produced by makeinfo version 4.6 from xemacs/xemacs.texi. INFO-DIR-SECTION XEmacs Editor @@ -30,1191 +30,7274 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  -File: xemacs.info, Node: Exiting, Next: Command Switches, Prev: Entering Emacs, Up: Top +File: xemacs.info, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Running + +Lisp Interaction Buffers +======================== + +The buffer `*scratch*', which is selected when Emacs starts up, is +provided for evaluating Lisp expressions interactively inside Emacs. +Both the expressions you evaluate and their output goes in the buffer. + + The `*scratch*' buffer's major mode is Lisp Interaction mode, which +is the same as Emacs-Lisp mode except for one command, . In +Emacs-Lisp mode, is an indentation command. In Lisp Interaction +mode, is bound to `eval-print-last-sexp'. This function reads +the Lisp expression before point, evaluates it, and inserts the value +in printed representation before point. + + The way to use the `*scratch*' buffer is to insert Lisp expressions +at the end, ending each one with so that it will be evaluated. +The result is a complete typescript of the expressions you have +evaluated and their values. + + The rationale for this feature is that Emacs must have a buffer when +it starts up, but that buffer is not useful for editing files since a +new buffer is made for every file that you visit. The Lisp interpreter +typescript is the most useful thing I can think of for the initial +buffer to do. `M-x lisp-interaction-mode' will put any buffer in Lisp +Interaction mode. -Exiting Emacs -============= + +File: xemacs.info, Node: External Lisp, Prev: Lisp Interaction, Up: Running + +Running an External Lisp +======================== + +Emacs has facilities for running programs in other Lisp systems. You +can run a Lisp process as an inferior of Emacs, and pass expressions to +it to be evaluated. You can also pass changed function definitions +directly from the Emacs buffers in which you edit the Lisp programs to +the inferior Lisp process. + + To run an inferior Lisp process, type `M-x run-lisp'. This runs the +program named `lisp', the same program you would run by typing `lisp' +as a shell command, with both input and output going through an Emacs +buffer named `*lisp*'. In other words, any "terminal output" from Lisp +will go into the buffer, advancing point, and any "terminal input" for +Lisp comes from text in the buffer. To give input to Lisp, go to the +end of the buffer and type the input, terminated by . The +`*lisp*' buffer is in Inferior Lisp mode, which has all the special +characteristics of Lisp mode and Shell mode (*note Shell Mode::). + + Use Lisp mode to run the source files of programs in external Lisps. +You can select this mode with `M-x lisp-mode'. It is used automatically +for files whose names end in `.l' or `.lisp', as most Lisp systems +usually expect. + + When you edit a function in a Lisp program you are running, the +easiest way to send the changed definition to the inferior Lisp process +is the key `C-M-x'. In Lisp mode, this key runs the function +`lisp-send-defun', which finds the defun around or following point and +sends it as input to the Lisp process. (Emacs can send input to any +inferior process regardless of what buffer is current.) + + Contrast the meanings of `C-M-x' in Lisp mode (for editing programs +to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp +programs to be run in Emacs): in both modes it has the effect of +installing the function definition that point is in, but the way of +doing so is different according to where the relevant Lisp environment +is found. *Note Lisp Modes::. + + +File: xemacs.info, Node: Packages, Next: Basic, Prev: Startup Paths, Up: Top + +Packages +======== + +The XEmacs 21 distribution comes only with a very basic set of built-in +modes and packages. Most of the packages that were part of the +distribution of earlier versions of XEmacs are now available +separately. The installer as well as the user can choose which +packages to install; the actual installation process is easy. This +gives an installer the ability to tailor an XEmacs installation for +local needs with safe removal of unnecessary code. + +* Menu: + +* Package Terminology:: Understanding different kinds of packages. +* Installing Packages:: How to install packages. +* Building Packages:: Building packages from CVS sources. +* Local.rules File:: This is an important file that you must create. +* Available Packages:: A brief directory of packaged LISP. + + +File: xemacs.info, Node: Package Terminology, Next: Installing Packages, Up: Packages + +Package Terminology: +==================== + +Package Flavors +--------------- + +There are two main flavors of packages. + + * Regular Packages A regular package is one in which multiple files + are involved and one may not in general safely remove any of them. + + * Single-File Packages A single-file package is an aggregate + collection of thematically related but otherwise independent lisp + files. These files are bundled together for download convenience + and individual files may be deleted at will without any loss of + functionality. However, we would recommend that you follow this + rule of thumb: "When in doubt, don't delete". + +Package Distributions +--------------------- + +XEmacs Lisp packages are distributed in two ways, depending on the +intended use. Binary Packages are for installers and end-users that can +be installed directly into an XEmacs package directory. Source Packages +are for developers and include all files necessary for rebuilding +bytecompiled lisp and creating tarballs for distribution. + +Binary Packages +--------------- + +Binary packages may be installed directly into an XEmacs package +hierarchy. + +Source Packages +--------------- + +Source packages contain all of the Package author's (where appropriate +in regular packages) source code plus all of the files necessary to +build distribution tarballs (Unix Tar format files, gzipped for space +savings). + + Currently, source packages are only available via CVS. See + for details. + + +File: xemacs.info, Node: Installing Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages + +Installing Packages: +==================== + +Getting Started +--------------- + +When you first download XEmacs 21, you will usually first grab the +"core distribution", a file called `xemacs-21.x.x.tar.gz'. (Replace the +21.x.x by the current version number.) The core distribution contains +the sources of XEmacs and a minimal set of Emacs Lisp files, which are +in the subdirectory named `lisp'. This subdirectory used to contain +all Emacs Lisp files distributed with XEmacs. Now, to conserve disk +space, most non-essential packages were made optional. + +Choosing the Packages You Need +------------------------------ + +The *Note Available Packages:: can currently be found in the same ftp +directory where you grabbed the core distribution from, and are located +in the subdirectory `packages'. Package file names follow the naming +convention `--pkg.tar.gz'. + + If you have EFS *Note (EFS)::, packages can be installed over the +network. Alternatively, if you have copies of the packages locally, +you can install packages from a local disk or CDROM. + + The file `etc/PACKAGES' in the core distribution contains a list of +the *Note Available Packages:: at the time of the XEmacs release. + + You can also get a list of available packages, and whether or not +they are installed, using the visual package browser and installer. +You can access it via the menus: + + Tools -> Packages -> List and Install + + Or, you can get to it via the keyboard: + + `M-x pui-list-packages' + + Hint to system administrators of multi-user systems: it might be a +good idea to install all packages and not interfere with the wishes of +your users. + + If you can't find which package provides the feature you require, try +using the `package-get-package-provider' function. Eg., if you know +that you need `thingatpt', type: + + `M-x package-get-package-provider RET thingatpt' + + which will return something like `(fsf-compat "1.08")'. You can the +use one of the methods above for installing the package you want. + +XEmacs and Installing Packages +------------------------------ + +There are three main ways to install packages: + +* Menu: + +* Automatically:: Using the package tools from XEmacs. +* Manually:: Using individual package tarballs. +* Sumo:: All at once, using the 'Sumo Tarball'. +* Which Packages:: Which packages to install. +* Removing Packages:: Removing packages. + + But regardless of the method you use to install packages, they can +only be used by XEmacs after a restart unless the package in question +has not been previously installed. + + +File: xemacs.info, Node: Automatically, Next: Manually, Up: Installing Packages + +Automatic Package Installation: +=============================== + +XEmacs comes with some tools to make the periodic updating and +installing easier. It will notice if new packages or versions are +available and will fetch them from the FTP site. + + Unfortunately this requires that a few packages are already in place. +You will have to install them by hand as above or use a SUMO tarball. +This requirement will hopefully go away in the future. The packages you +need are: + + efs - To fetch the files from the FTP site or mirrors. + xemacs-base - Needed by efs. + + and optionally: + + mailcrypt - To do PGP verification of the `package-index' + file. + + After installing these by hand, fire up XEmacs and follow these +steps. + + 1. Choose a download site. via menu: Tools -> Packages -> Set + Download Site via keyb: `M-x customize-variable RET + package-get-remote RET' (put in the details of remote host and + directory) + + If the package tarballs _AND_ the package-index file are in a + local directory, you can: `M-x pui-set-local-package-get-directory + RET' + + 2. Obtain a list of packages and display the list in a buffer named + `*Packages*'. menu: Tools -> Packages -> List & Install keyb: + `M-x pui-list-packages RET' + + XEmacs will now connect to the remote site and download the latest + package-index file. + + The visual package browser will then display a list of all + packages. Help information will be displayed at the very bottom + of the buffer; you may have to scroll down to see it. You can + also press `?' to get the same help. From this buffer, you can + tell the package status by the character in the first column: + + `-' + The package has not been installed. + + `*' + The package has been installed, but a newer version is + available. The current version is out-of-date. + + `+' + The package has been marked for installation/update. + + If there is no character in the first column, the package has been + installed and is up to date. + + From here, you can select or unselect packages for installation + using the key, the `Mouse-2' button or selecting "Select" + from the Popup `Mouse-3' Menu. Once you've finished selecting the + packages, you can press the `x' key (or use the menu) to actually + install the packages. Note that you will have to restart XEmacs + for XEmacs to recognize any new packages. + + Key summary: + + `?' + Display simple help. + + `' + `' + Toggle between selecting and unselecting a package for + installation. + + `x' + Install selected packages. + + `' + View, in the minibuffer, additional information about the + package, such as the package date (not the build date) and + the package author. Moving the mouse over a package name + will also do the same thing. + + `v' + Toggle between verbose and non-verbose package display. + + `g' + Refresh the package display. + + `q' + Kill the package buffer. + + Moving the mouse over a package will also cause additional + information about the package to be displayed in the minibuffer. + If you have balloon-help enabled a balloon-help frame will pop up + and display additional package information also. + + 3. Choose the packages you wish to install. mouse: Click button 2 on + the package name. keyb: `RET' on the package name + + 4. Make sure you have everything you need. menu: Packages -> Add + Required keyb: `r' + + XEmacs will now search for packages that are required by the ones + that you have chosen to install and offer to select those packages + also. + + For novices and gurus alike, this step can save your bacon. It's + easy to forget to install a critical package. + + 5. Download and install the packages. menu: Packages -> + Install/Remove Selected keyb: `x' + + You can also install packages using a semi-manual interface: + + M-x package-get-all + + Enter the name of the package (e.g., `prog-modes'), and XEmacs will +search for the latest version and install it and any packages that it +depends upon. + +Keeping Packages Up To Date: +============================ + +Once you have the packages you want installed (using any of the above +methods) you'll want to keep them up to date. You can do this easily +from the menubar: + + Tools -> Packages -> Set Download Site + Tools -> Packages -> Update Installed Packages + + +File: xemacs.info, Node: Manually, Next: Sumo, Prev: Automatically, Up: Installing Packages + +Manual Package Installation: +============================ + +Fetch the packages from the FTP site, CD-ROM whatever. The filenames +have the form `name--pkg.tar.gz' and are gzipped tar files. For +a fresh install it is sufficient to untar the file at the top of the +package hierarchy. + + Note: If you are upgrading packages already installed, it's best to +remove the old package first *Note Removing Packages::. + + For example if we are installing the `xemacs-base' package (version +1.48): + + mkdir $prefix/lib/xemacs/xemacs-packages RET # if it does not exist yet + cd $prefix/lib/xemacs/xemacs-packages RET + gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET + + Or if you have GNU tar, the last step can be: + + tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET + + For MULE related packages, it is best to untar into the mule-packages +hierarchy, i.e. for the `mule-base' package, version 1.37: + + mkdir $prefix/lib/xemacs/mule-packages RET # if it does not exist yet + cd $prefix/lib/xemacs/mule-packages RET + gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET + + Or if you have GNU tar, the last step can be: + + tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET + + +File: xemacs.info, Node: Sumo, Next: Which Packages, Prev: Manually, Up: Installing Packages + +Installing the Sumo Packages: +============================= + +Those with little time, cheap connections and plenty of disk space can +install all the packages at once using the sumo tarballs. Download the +file: `xemacs-sumo.tar.gz' + + For an XEmacs compiled with Mule you also need: +`xemacs-mule-sumo.tar.gz' + + N.B. They are called 'Sumo Tarballs' for good reason. They are +currently about 19MB and 4.5MB (gzipped) respectively. + + Install them by: + + `cd $prefix/lib/xemacs ; gunzip -c | tar xvf - RET' + + Or, if you have GNU tar: + + `cd $prefix/lib/xemacs ; tar zxvf /path/to/ RET' + + As the Sumo tarballs are not regenerated as often as the individual +packages, it is recommended that you use the automatic package tools +afterwards to pick up any recent updates. + + +File: xemacs.info, Node: Which Packages, Next: Removing Packages, Prev: Sumo, Up: Installing Packages + +Which Packages to Install: +========================== + +This is difficult to say. When in doubt install a package. If you +administrate a big site it might be a good idea to just install +everything. A good minimal set of packages for XEmacs-latin1 would be + + xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs, +edit-utils, fsf-compat, mail-lib, net-utils, os-utils, prog-modes, +text-modes, time, mailcrypt + + If you are using the XEmacs package tools, don't forget to do: + + Packages -> Add Required + + To make sure you have everything that the packages you have chosen to +install need. + + See also *Note Available Packages:: for further descriptions of the +individual packages. + + +File: xemacs.info, Node: Removing Packages, Prev: Which Packages, Up: Installing Packages + +Removing Packages: +================== + +Because the exact files and their locations contained in a package may +change it is recommended to remove a package first before installing a +new version. In order to facilitate removal each package contains an +`pgkinfo/MANIFEST.pkgname' file which list all the files belonging to +the package. + + No need to panic, you don't have to go through the +`pkinfo/MANIFEST.pkgname' and manually delete the files. Instead, use +`M-x package-get-delete-package RET'. + + Note that the interactive package tools included with XEmacs already +do this for you. + + +File: xemacs.info, Node: Building Packages, Next: Local.rules File, Prev: Installing Packages, Up: Packages + +Building Packages: +================== + +Currently, source packages are only available via anonymous CVS. See + for details of checking out the +`xemacs-packages' module. + +Prerequisites for Building Source Packages +------------------------------------------ + +`GNU cp' + +`GNU install' + (or a BSD compatible install program). + +`GNU make' + (3.75 or later preferred). + +`makeinfo' + (4.2 from GNU texinfo 4.2 or later required). + +`GNU tar' + (or equivalent). + +`GNU gzip' + (or equivalent). + +`A properly configured `Local.rules' file.' + *Note Local.rules File::. +And of course, XEmacs 21.0 or higher. + +What You Can Do With Source Packages +------------------------------------ + +The packages CVS sources are most useful for creating XEmacs package +tarballs for installation into your own XEmacs installations or for +distributing to others. + + For a list and description of the different `Makefile' targets, +*Note Makefile Targets: (lispref)Makefile Targets. + + +File: xemacs.info, Node: Local.rules File, Next: Available Packages, Prev: Building Packages, Up: Packages + +The Local.rules File: +===================== + +This file is used when building and installing packages from source. In +the top level of the CVS module, `packages', contains the file, +`Local.rules.template'. Simply copy that to `Local.rules' and edit it +to suit your needs. + + For a complete discussion of the `Local.rules' file, *Note +Local.rules File: (lispref)Local.rules File. + + +File: xemacs.info, Node: Available Packages, Prev: Local.rules File, Up: Packages + +Available Packages: +=================== + +This section lists the Lisp packages that are currently available from +xemacs.org and it's mirrors. If a particular package that you are +looking for isn't here, please send a message to the XEmacs Beta list +. + + This data is up to date as of June 27, 2003. + +Normal Packages +--------------- + +A very broad selection of elisp packages. + +`Sun' + Support for Sparcworks. + +`ada' + Ada language support. + +`apel' + A Portable Emacs Library. Used by XEmacs MIME support. + +`auctex' + Basic TeX/LaTeX support. + +`bbdb' + The Big Brother Data Base: a rolodex-like database program. + +`build' + Build XEmacs using custom widgets. + +`c-support' + Basic single-file add-ons for editing C code. + +`calc' + Emacs calculator. + +`calendar' + Calendar and diary support. + +`cc-mode' + C, C++ and Java language support. + +`clearcase' + Support for the Clearcase version control system. + +`cookie' + "Fortune cookie"-style messages. Includes Spook (suspicious + phrases) and Yow (Zippy quotes). + +`crisp' + Crisp/Brief emulation. + +`debug' + GUD, gdb, dbx debugging support. + +`dictionary' + Interface to RFC2229 dictionary servers. + +`dired' + The DIRectory EDitor is for manipulating, and running commands on + files in a directory. + +`docbookide' + DocBook editing support. + +`ecrypto' + Crypto functionality in Emacs Lisp. + +`edebug' + A Lisp debugger. + +`ediff' + Interface over patch. + +`edit-utils' + Single file lisp packages for various XEmacs goodies. Load this + and weed out the junk you don't want. + +`edt' + DEC EDIT/EDT emulation. + +`efs' + Treat files on remote systems the same as local files. + +`eieio' + Enhanced Implementation of Emacs Interpreted Objects. + +`elib' + Portable Emacs Lisp utilities library. + +`emerge' + Another interface over patch. + +`eshell' + Command shell implemented entirely in Emacs Lisp. + +`ess' + ESS: Emacs Speaks Statistics. + +`eterm' + Terminal emulator. + +`eudc' + Emacs Unified Directory Client (LDAP, PH). + +`footnote' + Footnoting in mail message editing modes. + +`forms' + Forms editing support (obsolete, use the built-in Widget instead). + +`fortran-modes' + Fortran language support. + +`frame-icon' + Provide a WM icon based on major mode. + +`fsf-compat' + GNU Emacs compatibility files. + +`games' + Tetris, Sokoban, and Snake. + +`general-docs' + General documentation. Presently, empty. + +`gnats' + XEmacs bug reports. + +`gnus' + The Gnus Newsreader and Mailreader. + +`haskell-mode' + Haskell language support. + +`hm--html-menus' + HTML editing. + +`ibuffer' + Advanced replacement for buffer-menu. + +`idlwave' + Editing and Shell mode for the Interactive Data Language. + +`igrep' + Enhanced front-end for Grep. + +`ilisp' + Front-end for interacting with Inferior Lisp (external lisps). + +`ispell' + Spell-checking with ispell. + +`jde' + Java language and development support. + +`liece' + IRC (Internet Relay Chat) client for Emacs. + +`mail-lib' + Fundamental lisp files for providing email support. + +`mailcrypt' + Support for messaging encryption with PGP. + +`mew' + Messaging in an Emacs World; a MIME-based email program. + +`mh-e' + Front end support for MH. + +`mine' + Elisp implementation of the game 'Minehunt'. + +`misc-games' + Other amusements and diversions. + +`mmm-mode' + Support for Multiple Major Modes within a single buffer. + +`net-utils' + Miscellaneous Networking Utilities. This is a single-file package + and files may be deleted at will. + +`ocaml' + Objective Caml editing support. + +`os-utils' + Miscellaneous single-file O/S utilities, for printing, archiving, + compression, remote shells, etc. + +`pc' + PC style interface emulation. + +`pcl-cvs' + CVS frontend. + +`pcomplete' + Provides programmatic completion. + +`perl-modes' + Perl language support. + +`pgg' + Emacs interface to various PGP implementations. + +`prog-modes' + Miscellaneous single-file lisp files for various programming + languages. + +`ps-print' + Print buffers to PostScript printers. + +`psgml' + Validated HTML/SGML editing. + +`psgml-dtds' + A collection of DTDs for psgml. Note that this package is + deprecated and will be removed in the future, most likely Q2/2003. + Instead of using this, you should install needed DTDs yourself. + +`python-modes' + Python language support. + +`reftex' + Emacs support for LaTeX cross-references, citations. + +`rmail' + An obsolete Emacs mailer. If you do not already use it don't + start. + +`ruby-modes' + Ruby language support. + +`sasl' + Simple Authentication and Security Layer (SASL) library. + +`scheme' + Front-end support for Inferior Scheme. + +`semantic' + Semantic bovinator. + +`sgml' + SGML/Linuxdoc-SGML editing. + +`sh-script' + Support for editing shell scripts. + +`sieve' + Manage Sieve email filtering scripts. + +`slider' + User interface tool. + +`sml-mode' + Standard ML editing support. + +`sounds-au' + XEmacs Sun sound files. + +`sounds-wav' + XEmacs Microsoft sound files. + +`speedbar' + Provides a separate frame with convenient references. + +`strokes' + Mouse enhancement utility. + +`supercite' + An Emacs citation tool. Useful with all Emacs Mailers and + Newsreaders. + +`texinfo' + XEmacs TeXinfo support. + +`text-modes' + Various single file lisp packages for editing text files. + +`textools' + Single-file TeX support. + +`time' + Display time & date on the modeline. + +`tm' + Emacs MIME support. Not needed for Gnus >= 5.8.0 + +`tooltalk' + Support for building with Tooltalk. + +`tpu' + DEC EDIT/TPU support. + +`tramp' + Remote shell-based file editing. This is similar to EFS or + Ange-FTP, but works with rsh/ssh and rcp/scp. + +`vc' + Version Control for Free systems. + +`vc-cc' + Version Control for ClearCase. This package will shortly be + replaced with clearcase.el + +`vhdl' + Support for VHDL. + +`view-process' + A Unix process browsing tool. + +`viper' + VI emulation support. + +`vm' + An Emacs mailer. + +`w3' + A Web browser. + +`x-symbol' + Semi WYSIWYG for LaTeX, HTML, etc, using additional fonts. + +`xemacs-base' + Fundamental XEmacs support. Install this unless you wish a totally + naked XEmacs. + +`xemacs-devel' + XEmacs Lisp developer support. This package contains utilities for + supporting Lisp development. It is a single-file package so it + may be tailored. + +`xslide' + XSL editing support. + +`xslt-process' + A minor mode for (X)Emacs which allows running an XSLT processor + on a buffer. + +`zenirc' + ZENIRC IRC Client. + +Mule Support (mule) +------------------- + +MULti-lingual Enhancement. Support for world scripts such as Latin, +Arabic, Cyrillic, Chinese, Japanese, Greek, Hebrew etc. To use these +packages your XEmacs must be compiled with Mule support. + +`edict' + Lisp Interface to EDICT, Kanji Dictionary. + +`egg-its' + Wnn (4.2 and 6) support. SJ3 support. Must be installed prior to + XEmacs build. + +`latin-unity' + Unify character sets in a buffer. When characters belong to + disjoint character sets, this attempts to translate the characters + so that they belong to one character set. If the buffer coding + system is not sufficient, this suggests different coding systems. + +`leim' + Quail. Used for everything other than English and Japanese. + +`locale' + Used for localized menubars (French and Japanese) and localized + splash screens (Japanese). + +`lookup' + Dictionary support. (This isn't an English dictionary program) + +`mule-base' + Basic Mule support. Must be installed prior to building with Mule. + +`mule-ucs' + Extended coding systems (including Unicode) for XEmacs. + +`skk' + Another Japanese Language Input Method. Can be used without a + separate process running as a dictionary server. + + +File: xemacs.info, Node: Abbrevs, Next: Picture, Prev: Running, Up: Top + +Abbrevs +******* + +An "abbrev" is a word which "expands" into some different text. +Abbrevs are defined by the user to expand in specific ways. For +example, you might define `foo' as an abbrev expanding to `find outer +otter'. With this abbrev defined, you would be able to get `find outer +otter ' into the buffer by typing `f o o '. + + Abbrevs expand only when Abbrev mode (a minor mode) is enabled. +Disabling Abbrev mode does not cause abbrev definitions to be discarded, +but they do not expand until Abbrev mode is enabled again. The command +`M-x abbrev-mode' toggles Abbrev mode; with a numeric argument, it +turns Abbrev mode on if the argument is positive, off otherwise. *Note +Minor Modes::. `abbrev-mode' is also a variable; Abbrev mode is on +when the variable is non-`nil'. The variable `abbrev-mode' +automatically becomes local to the current buffer when it is set. + + Abbrev definitions can be "mode-specific"--active only in one major +mode. Abbrevs can also have "global" definitions that are active in +all major modes. The same abbrev can have a global definition and +various mode-specific definitions for different major modes. A +mode-specific definition for the current major mode overrides a global +definition. + + You can define Abbrevs interactively during an editing session. You +can also save lists of abbrev definitions in files and reload them in +later sessions. Some users keep extensive lists of abbrevs that they +load in every session. + + A second kind of abbreviation facility is called the "dynamic +expansion". Dynamic abbrev expansion happens only when you give an +explicit command and the result of the expansion depends only on the +current contents of the buffer. *Note Dynamic Abbrevs::. + +* Menu: + +* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. +* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. +* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. +* Saving Abbrevs:: Saving the entire list of abbrevs for another session. +* Dynamic Abbrevs:: Abbreviations for words already in the buffer. + + +File: xemacs.info, Node: Defining Abbrevs, Next: Expanding Abbrevs, Prev: Abbrevs, Up: Abbrevs + +Defining Abbrevs +================ + +`C-x a g' + Define an abbrev to expand into some text before point + (`add-global-abbrev'). + +`C-x a l' + Similar, but define an abbrev available only in the current major + mode (`add-mode-abbrev'). + +`C-x a i g' + Define a word in the buffer as an abbrev + (`inverse-add-global-abbrev'). + +`C-x a i l' + Define a word in the buffer as a mode-specific abbrev + (`inverse-add-mode-abbrev'). + +`M-x kill-all-abbrevs' + After this command, no abbrev definitions remain in effect. + + The usual way to define an abbrev is to enter the text you want the +abbrev to expand to, position point after it, and type `C-x a g' +(`add-global-abbrev'). This reads the abbrev itself using the +minibuffer, and then defines it as an abbrev for one or more words +before point. Use a numeric argument to say how many words before point +should be taken as the expansion. For example, to define the abbrev +`foo' as in the example above, insert the text `find outer otter', then +type +`C-u 3 C-x a g f o o '. + + An argument of zero to `C-x a g' means to use the contents of the +region as the expansion of the abbrev being defined. + + The command `C-x a l' (`add-mode-abbrev') is similar, but defines a +mode-specific abbrev. Mode-specific abbrevs are active only in a +particular major mode. `C-x a l' defines an abbrev for the major mode +in effect at the time `C-x a l' is typed. The arguments work the same +way they do for `C-x a g'. + + If the text of an abbrev you want is already in the buffer instead of +the expansion, use command `C-x a i g' (`inverse-add-global-abbrev') +instead of `C-x a g', or use `C-x a i l' (`inverse-add-mode-abbrev') +instead of `C-x a l'. These commands are called "inverse" because they +invert the meaning of the argument found in the buffer and the argument +read using the minibuffer. + + To change the definition of an abbrev, just add the new definition. +You will be asked to confirm if the abbrev has a prior definition. To +remove an abbrev definition, give a negative argument to `C-x a g' or +`C-x a l'. You must choose the command to specify whether to kill a +global definition or a mode-specific definition for the current mode, +since those two definitions are independent for one abbrev. + + `M-x kill-all-abbrevs' removes all existing abbrev definitions. + + +File: xemacs.info, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs + +Controlling Abbrev Expansion +============================ + +An abbrev expands whenever it is in a buffer just before point and you +type a self-inserting punctuation character (, comma, etc.). Most +often an abbrev is used by inserting the abbrev followed by punctuation. + + Abbrev expansion preserves case; thus, `foo' expands into `find +outer otter', `Foo' into `Find outer otter', and `FOO' into `FIND OUTER +OTTER' or `Find Outer Otter' according to the variable +`abbrev-all-caps' (a non-`nil' value chooses the first of the two +expansions). + + Two commands are available to control abbrev expansion: + +`M-'' + Separate a prefix from a following abbrev to be expanded + (`abbrev-prefix-mark'). + +`C-x a e' + Expand the abbrev before point (`expand-abbrev'). This is + effective even when Abbrev mode is not enabled. + +`M-x unexpand-abbrev' + Undo last abbrev expansion. + +`M-x expand-region-abbrevs' + Expand some or all abbrevs found in the region. + + You may wish to expand an abbrev with a prefix attached. For +example, if `cnst' expands into `construction', you may want to use it +to enter `reconstruction'. It does not work to type `recnst', because +that is not necessarily a defined abbrev. Instead, you can use the +command `M-'' (`abbrev-prefix-mark') between the prefix `re' and the +abbrev `cnst'. First, insert `re'. Then type `M-''; this inserts a +minus sign in the buffer to indicate that it has done its work. Then +insert the abbrev `cnst'. The buffer now contains `re-cnst'. Now +insert a punctuation character to expand the abbrev `cnst' into +`construction'. The minus sign is deleted at this point by `M-''. The +resulting text is the desired `reconstruction'. + + If you actually want the text of the abbrev in the buffer, rather +than its expansion, insert the following punctuation with `C-q'. Thus, +`foo C-q -' leaves `foo-' in the buffer. + + If you expand an abbrev by mistake, you can undo the expansion +(replace the expansion by the original abbrev text) with `M-x +unexpand-abbrev'. You can also use `C-_' (`undo') to undo the +expansion; but that will first undo the insertion of the punctuation +character. + + `M-x expand-region-abbrevs' searches through the region for defined +abbrevs, and offers to replace each one it finds with its expansion. +This command is useful if you have typed text using abbrevs but forgot +to turn on Abbrev mode first. It may also be useful together with a +special set of abbrev definitions for making several global +replacements at once. The command is effective even if Abbrev mode is +not enabled. + + +File: xemacs.info, Node: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs + +Examining and Editing Abbrevs +============================= + +`M-x list-abbrevs' + Print a list of all abbrev definitions. + +`M-x edit-abbrevs' + Edit a list of abbrevs; you can add, alter, or remove definitions. + + The output from `M-x list-abbrevs' looks like this: + + (lisp-mode-abbrev-table) + "dk" 0 "define-key" + (global-abbrev-table) + "dfn" 0 "definition" + +(Some blank lines of no semantic significance, and some other abbrev +tables, have been omitted.) + + A line containing a name in parentheses is the header for abbrevs in +a particular abbrev table; `global-abbrev-table' contains all the global +abbrevs, and the other abbrev tables that are named after major modes +contain the mode-specific abbrevs. + + Within each abbrev table, each non-blank line defines one abbrev. +The word at the beginning is the abbrev. The number that appears is +the number of times the abbrev has been expanded. Emacs keeps track of +this to help you see which abbrevs you actually use, in case you want +to eliminate those that you don't use often. The string at the end of +the line is the expansion. + + `M-x edit-abbrevs' allows you to add, change or kill abbrev +definitions by editing a list of them in an Emacs buffer. The list has +the format described above. The buffer of abbrevs is called +`*Abbrevs*', and is in Edit-Abbrevs mode. This mode redefines the key +`C-c C-c' to install the abbrev definitions as specified in the buffer. +The `edit-abbrevs-redefine' command does this. Any abbrevs not +described in the buffer are eliminated when this is done. + + `edit-abbrevs' is actually the same as `list-abbrevs', except that +it selects the buffer `*Abbrevs*' whereas `list-abbrevs' merely +displays it in another window. + + +File: xemacs.info, Node: Saving Abbrevs, Next: Dynamic Abbrevs, Prev: Editing Abbrevs, Up: Abbrevs + +Saving Abbrevs +============== + +These commands allow you to keep abbrev definitions between editing +sessions. + +`M-x write-abbrev-file' + Write a file describing all defined abbrevs. + +`M-x read-abbrev-file' + Read such an abbrev file and define abbrevs as specified there. + +`M-x quietly-read-abbrev-file' + Similar, but do not display a message about what is going on. + +`M-x define-abbrevs' + Define abbrevs from buffer. + +`M-x insert-abbrevs' + Insert all abbrevs and their expansions into the buffer. + + Use `M-x write-abbrev-file' to save abbrev definitions for use in a +later session. The command reads a file name using the minibuffer and +writes a description of all current abbrev definitions into the +specified file. The text stored in the file looks like the output of +`M-x list-abbrevs'. + + `M-x read-abbrev-file' prompts for a file name using the minibuffer +and reads the specified file, defining abbrevs according to its +contents. `M-x quietly-read-abbrev-file' is the same but does not +display a message in the echo area; it is actually useful primarily in +the init file. *Note Init File::. If you give an empty argument to +either of these functions, the file name Emacs uses is the value of the +variable `abbrev-file-name', which is by default `"~/.abbrev_defs"'. + + Emacs offers to save abbrevs automatically if you have changed any of +them, whenever it offers to save all files (for `C-x s' or `C-x C-c'). +Set the variable `save-abbrevs' to `nil' to inhibit this feature. + + The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are +similar to the previous commands but work on text in an Emacs buffer. +`M-x insert-abbrevs' inserts text into the current buffer before point, +describing all current abbrev definitions; `M-x define-abbrevs' parses +the entire current buffer and defines abbrevs accordingly. + + +File: xemacs.info, Node: Dynamic Abbrevs, Prev: Saving Abbrevs, Up: Abbrevs + +Dynamic Abbrev Expansion +======================== + +The abbrev facility described above operates automatically as you insert +text, but all abbrevs must be defined explicitly. By contrast, +"dynamic abbrevs" allow the meanings of abbrevs to be determined +automatically from the contents of the buffer, but dynamic abbrev +expansion happens only when you request it explicitly. + +`M-/' + Expand the word in the buffer before point as a "dynamic abbrev", + by searching in the buffer for words starting with that + abbreviation (`dabbrev-expand'). + + For example, if the buffer contains `does this follow ' and you type +`f o M-/', the effect is to insert `follow' because that is the last +word in the buffer that starts with `fo'. A numeric argument to `M-/' +says to take the second, third, etc. distinct expansion found looking +backward from point. Repeating `M-/' searches for an alternative +expansion by looking farther back. After the entire buffer before +point has been considered, the buffer after point is searched. + + Dynamic abbrev expansion is completely independent of Abbrev mode; +the expansion of a word with `M-/' is completely independent of whether +it has a definition as an ordinary abbrev. + + +File: xemacs.info, Node: Picture, Next: Sending Mail, Prev: Abbrevs, Up: Top + +Editing Pictures +**************** + +If you want to create a picture made out of text characters (for +example, a picture of the division of a register into fields, as a +comment in a program), use the command `edit-picture' to enter Picture +mode. + + In Picture mode, editing is based on the "quarter-plane" model of +text. In this model, the text characters lie studded on an area that +stretches infinitely far to the right and downward. The concept of the +end of a line does not exist in this model; the most you can say is +where the last non-blank character on the line is found. + + Of course, Emacs really always considers text as a sequence of +characters, and lines really do have ends. But in Picture mode most +frequently-used keys are rebound to commands that simulate the +quarter-plane model of text. They do this by inserting spaces or by +converting tabs to spaces. + + Most of the basic editing commands of Emacs are redefined by Picture +mode to do essentially the same thing but in a quarter-plane way. In +addition, Picture mode defines various keys starting with the `C-c' +prefix to run special picture editing commands. + + One of these keys, `C-c C-c', is pretty important. Often a picture +is part of a larger file that is usually edited in some other major +mode. `M-x edit-picture' records the name of the previous major mode. +You can then use the `C-c C-c' command (`picture-mode-exit') to restore +that mode. `C-c C-c' also deletes spaces from the ends of lines, +unless you give it a numeric argument. + + The commands used in Picture mode all work in other modes (provided +the `picture' library is loaded), but are only bound to keys in +Picture mode. Note that the descriptions below talk of moving "one +column" and so on, but all the picture mode commands handle numeric +arguments as their normal equivalents do. + + Turning on Picture mode calls the value of the variable +`picture-mode-hook' as a function, with no arguments, if that value +exists and is non-`nil'. + +* Menu: + +* Basic Picture:: Basic concepts and simple commands of Picture Mode. +* Insert in Picture:: Controlling direction of cursor motion + after "self-inserting" characters. +* Tabs in Picture:: Various features for tab stops and indentation. +* Rectangles in Picture:: Clearing and superimposing rectangles. + + +File: xemacs.info, Node: Basic Picture, Next: Insert in Picture, Prev: Picture, Up: Picture + +Basic Editing in Picture Mode +============================= + +Most keys do the same thing in Picture mode that they usually do, but do +it in a quarter-plane style. For example, `C-f' is rebound to run +`picture-forward-column', which moves point one column to the right, by +inserting a space if necessary, so that the actual end of the line +makes no difference. `C-b' is rebound to run +`picture-backward-column', which always moves point left one column, +converting a tab to multiple spaces if necessary. `C-n' and `C-p' are +rebound to run `picture-move-down' and `picture-move-up', which can +either insert spaces or convert tabs as necessary to make sure that +point stays in exactly the same column. `C-e' runs +`picture-end-of-line', which moves to after the last non-blank +character on the line. There was no need to change `C-a', as the choice +of screen model does not affect beginnings of lines. + + Insertion of text is adapted to the quarter-plane screen model +through the use of Overwrite mode (*note Minor Modes::). +Self-inserting characters replace existing text, column by column, +rather than pushing existing text to the right. runs +`picture-newline', which just moves to the beginning of the following +line so that new text will replace that line. + + Text is erased instead of deleted and killed. +(`picture-backward-clear-column') replaces the preceding character with +a space rather than removing it. `C-d' (`picture-clear-column') does +the same in a forward direction. `C-k' (`picture-clear-line') really +kills the contents of lines, but never removes the newlines from a +buffer. + + To do actual insertion, you must use special commands. `C-o' +(`picture-open-line') creates a blank line, but does so after the +current line; it never splits a line. `C-M-o', `split-line', makes +sense in Picture mode, so it remains unchanged. +(`picture-duplicate-line') inserts another line with the same contents +below the current line. + + To actually delete parts of the picture, use `C-w', or with `C-c +C-d' (which is defined as `delete-char', as `C-d' is in other modes), +or with one of the picture rectangle commands (*note Rectangles in +Picture::). + + +File: xemacs.info, Node: Insert in Picture, Next: Tabs in Picture, Prev: Basic Picture, Up: Picture + +Controlling Motion After Insert +=============================== + +Since "self-inserting" characters just overwrite and move point in +Picture mode, there is no essential restriction on how point should be +moved. Normally point moves right, but you can specify any of the eight +orthogonal or diagonal directions for motion after a "self-inserting" +character. This is useful for drawing lines in the buffer. + +`C-c <' + Move left after insertion (`picture-movement-left'). + +`C-c >' + Move right after insertion (`picture-movement-right'). + +`C-c ^' + Move up after insertion (`picture-movement-up'). + +`C-c .' + Move down after insertion (`picture-movement-down'). + +`C-c `' + Move up and left ("northwest") after insertion + (`picture-movement-nw'). + +`C-c '' + Move up and right ("northeast") after insertion + (`picture-movement-ne'). + +`C-c /' + Move down and left ("southwest") after insertion + (`picture-movement-sw'). + +`C-c \' + Move down and right ("southeast") after insertion + (`picture-movement-se'). + + Two motion commands move based on the current Picture insertion +direction. The command `C-c C-f' (`picture-motion') moves in the same +direction as motion after "insertion" currently does, while `C-c C-b' +(`picture-motion-reverse') moves in the opposite direction. + + +File: xemacs.info, Node: Tabs in Picture, Next: Rectangles in Picture, Prev: Insert in Picture, Up: Picture + +Picture Mode Tabs +================= + +Two kinds of tab-like action are provided in Picture mode. +Context-based tabbing is done with `M-' (`picture-tab-search'). +With no argument, it moves to a point underneath the next "interesting" +character that follows whitespace in the previous non-blank line. +"Next" here means "appearing at a horizontal position greater than the +one point starts out at". With an argument, as in `C-u M-', the +command moves to the next such interesting character in the current +line. `M-' does not change the text; it only moves point. +"Interesting" characters are defined by the variable +`picture-tab-chars', which contains a string of characters considered +interesting. Its default value is `"!-~"'. + + itself runs `picture-tab', which operates based on the current +tab stop settings; it is the Picture mode equivalent of +`tab-to-tab-stop'. Without arguments it just moves point, but with a +numeric argument it clears the text that it moves over. + + The context-based and tab-stop-based forms of tabbing are brought +together by the command `C-c ' (`picture-set-tab-stops'.) This +command sets the tab stops to the positions which `M-' would +consider significant in the current line. If you use this command with +, you can get the effect of context-based tabbing. But `M-' +is more convenient in the cases where it is sufficient. + + +File: xemacs.info, Node: Rectangles in Picture, Prev: Tabs in Picture, Up: Picture + +Picture Mode Rectangle Commands +=============================== + +Picture mode defines commands for working on rectangular pieces of the +text in ways that fit with the quarter-plane model. The standard +rectangle commands may also be useful (*note Rectangles::). + +`C-c C-k' + Clear out the region-rectangle (`picture-clear-rectangle'). With + argument, kill it. + +`C-c C-w R' + Similar but save rectangle contents in register R first + (`picture-clear-rectangle-to-register'). + +`C-c C-y' + Copy last killed rectangle into the buffer by overwriting, with + upper left corner at point (`picture-yank-rectangle'). With + argument, insert instead. + +`C-c C-x R' + Similar, but use the rectangle in register R + (`picture-yank-rectangle-from-register'). + + The picture rectangle commands `C-c C-k' (`picture-clear-rectangle') +and `C-c C-w' (`picture-clear-rectangle-to-register') differ from the +standard rectangle commands in that they normally clear the rectangle +instead of deleting it; this is analogous with the way `C-d' is changed +in Picture mode. + + However, deletion of rectangles can be useful in Picture mode, so +these commands delete the rectangle if given a numeric argument. + + The Picture mode commands for yanking rectangles differ from the +standard ones in overwriting instead of inserting. This is the same +way that Picture mode insertion of other text is different from other +modes. `C-c C-y' (`picture-yank-rectangle') inserts (by overwriting) +the rectangle that was most recently killed, while `C-c C-x' +(`picture-yank-rectangle-from-register') does for the rectangle found +in a specified register. + + Since most region commands in Picture mode operate on rectangles, +when you select a region of text with the mouse in Picture mode, it is +highlighted as a rectangle. + + +File: xemacs.info, Node: Sending Mail, Next: Reading Mail, Prev: Picture, Up: Top + +Sending Mail +************ + +To send a message in Emacs, start by typing the command (`C-x m') to +select and initialize the `*mail*' buffer. You can then edit the text +and headers of the message in the mail buffer, and type the command +(`C-c C-c') to send the message. + +`C-x m' + Begin composing a message to send (`mail'). + +`C-x 4 m' + Likewise, but display the message in another window + (`mail-other-window'). + +`C-c C-c' + In Mail mode, send the message and switch to another buffer + (`mail-send-and-exit'). + + The command `C-x m' (`mail') selects a buffer named `*mail*' and +initializes it with the skeleton of an outgoing message. `C-x 4 m' +(`mail-other-window') selects the `*mail*' buffer in a different +window, leaving the previous current buffer visible. + + Because the buffer for mail composition is an ordinary Emacs buffer, +you can switch to other buffers while in the middle of composing mail, +and switch back later (or never). If you use the `C-x m' command again +when you have been composing another message but have not sent it, a +new mail buffer will be created; in this way, you can compose multiple +messages at once. You can switch back to and complete an unsent +message by using the normal buffer selection mechanisms. + + `C-u C-x m' is another way to switch back to a message in progress: +it will search for an existing, unsent mail message buffer and select +it. + +* Menu: + +* Format: Mail Format. Format of the mail being composed. +* Headers: Mail Headers. Details of allowed mail header fields. +* Mode: Mail Mode. Special commands for editing mail being composed. + + +File: xemacs.info, Node: Mail Format, Next: Mail Headers, Prev: Sending Mail, Up: Sending Mail + +The Format of the Mail Buffer +============================= + +In addition to the "text" or contents, a message has "header fields", +which say who sent it, when, to whom, why, and so on. Some header +fields, such as the date and sender, are created automatically after the +message is sent. Others, such as the recipient names, must be +specified by you in order to send the message properly. + + Mail mode provides a few commands to help you edit some header +fields, and some are preinitialized in the buffer automatically at +times. You can insert or edit any header fields using ordinary editing +commands. + + The line in the buffer that says: + + --text follows this line-- + +is a special delimiter that separates the headers you have specified +from the text. Whatever follows this line is the text of the message; +the headers precede it. The delimiter line itself does not appear in +the message actually sent. The text used for the delimiter line is +controlled by the variable `mail-header-separator'. + + Here is an example of what the headers and text in the `*mail*' +buffer might look like. + + To: rms@mc + CC: mly@mc, rg@oz + Subject: The XEmacs User's Manual + --Text follows this line-- + Please ignore this message. + + +File: xemacs.info, Node: Mail Headers, Next: Mail Mode, Prev: Mail Format, Up: Sending Mail + +Mail Header Fields +================== + +There are several header fields you can use in the `*mail*' buffer. +Each header field starts with a field name at the beginning of a line, +terminated by a colon. It does not matter whether you use upper or +lower case in the field name. After the colon and optional whitespace +comes the contents of the field. + +`To' + This field contains the mailing addresses of the message. + +`Subject' + The contents of the `Subject' field should be a piece of text that + says what the message is about. Subject fields are useful because + most mail-reading programs can provide a summary of messages, + listing the subject of each message but not its text. + +`CC' + This field contains additional mailing addresses to send the + message to, but whose readers should not regard the message as + addressed to them. + +`BCC' + This field contains additional mailing addresses to send the + message to, but which should not appear in the header of the + message actually sent. + +`FCC' + This field contains the name of one file (in Unix mail file + format) to which a copy of the message should be appended when the + message is sent. + +`From' + Use the `From' field to say who you are, when the account you are + using to send the mail is not your own. The contents of the + `From' field should be a valid mailing address, since replies will + normally go there. + +`Reply-To' + Use the `Reply-To' field to direct replies to a different address, + not your own. `From' and `Reply-To' have the same effect on where + replies go, but they convey a different meaning to the person who + reads the message. + +`In-Reply-To' + This field contains a piece of text describing a message you are + replying to. Some mail systems can use the information to + correlate related pieces of mail. This field is normally filled + in by your mail handling package when you are replying to a + message and you never need to think about it. + +The `To', `CC', `BCC' and `FCC' fields can appear any number of times, +to specify many places to send the message. + +The `To', `CC', and `BCC', fields can have continuation lines. All the +lines starting with whitespace, following the line on which the field +starts, are considered part of the field. For example, + + To: foo@here, this@there, + me@gnu.cambridge.mass.usa.earth.spiral3281 + +If you have a `~/.mailrc' file, Emacs scans it for mail aliases the +first time you try to send mail in an Emacs session. Emacs expands +aliases found in the `To', `CC', and `BCC' fields where appropriate. +You can set the variable `mail-abbrev-mailrc-file' to the name of the +file with mail aliases. If `nil', `~/.mailrc' is used. + + Your `.mailrc' file ensures that word-abbrevs are defined for each +of your mail aliases when point is in a `To', `CC', `BCC', or `From' +field. The aliases are defined in your `.mailrc' file or in a file +specified by the MAILRC environment variable if it exists. Your mail +aliases expand any time you type a word-delimiter at the end of an +abbreviation. + + In this version of Emacs, what you see is what you get: in contrast +to some other versions, no abbreviations are expanded after you have +sent the mail. This means you don't suffer the annoyance of having the +system do things behind your back--if the system rewrites an address +you typed, you know it immediately, instead of after the mail has been +sent and it's too late to do anything about it. For example, you will +never again be in trouble because you forgot to delete an old alias +from your `.mailrc' and a new local user is given a userid which +conflicts with one of your aliases. + + Your mail alias abbrevs are in effect only when point is in an +appropriate header field. The mail aliases will not expand in the body +of the message, or in other header fields. The default mode-specific +abbrev table `mail-mode-abbrev-table' is used instead if defined. That +means if you have been using mail-mode specific abbrevs, this code will +not adversely affect you. You can control which header fields the +abbrevs are used in by changing the variable `mail-abbrev-mode-regexp'. + + If auto-fill mode is on, abbrevs wrap at commas instead of at word +boundaries, and header continuation lines will be properly indented. + + You can also insert a mail alias with +`mail-interactive-insert-alias'. This function, which is bound to `C-c +C-a', prompts you for an alias (with completion) and inserts its +expansion at point. + + In this version of Emacs, it is possible to have lines like the +following in your `.mailrc' file: + + alias someone "John Doe " + + That is, if you want an address to have embedded spaces, simply +surround it with double-quotes. The quotes are necessary because the +format of the `.mailrc' file uses spaces as address delimiters. + + Aliases in the `.mailrc' file may be nested. For example, assume you +define aliases like: + alias group1 fred ethel + alias group2 larry curly moe + alias everybody group1 group2 + + When you now type `everybody' on the `To' line, it will expand to: + fred, ethyl, larry, curly, moe + + Aliases may contain forward references; the alias of `everybody' in +the example above can precede the aliases of `group1' and `group2'. + + In this version of Emacs, you can use the `source' `.mailrc' command +for reading aliases from some other file as well. + + Aliases may contain hyphens, as in `"alias foo-bar foo@bar"', even +though word-abbrevs normally cannot contain hyphens. + + To read in the contents of another `.mailrc'-type file from Emacs, +use the command `M-x merge-mail-aliases'. The `rebuild-mail-aliases' +command is similar, but deletes existing aliases first. + + If you want multiple addresses separated by a string other than `,' +(a comma), then set the variable `mail-alias-separator-string' to it. +This has to be a comma bracketed by whitespace if you want any kind of +reasonable behavior. + + If the variable `mail-archive-file-name' is non-`nil', it should be +a string naming a file. Each time you start to edit a message to send, +an `FCC' field is entered for that file. Unless you remove the `FCC' +field, every message is written into that file when it is sent. + + +File: xemacs.info, Node: Mail Mode, Prev: Mail Headers, Up: Sending Mail + +Mail Mode +========= + +The major mode used in the `*mail*' buffer is Mail mode. Mail mode is +similar to Text mode, but several commands are provided on the `C-c' +prefix. These commands all deal specifically with editing or sending +the message. + +`C-c C-s' + Send the message, and leave the `*mail*' buffer selected + (`mail-send'). + +`C-c C-c' + Send the message, and select some other buffer + (`mail-send-and-exit'). + +`C-c C-f C-t' + Move to the `To' header field, creating one if there is none + (`mail-to'). + +`C-c C-f C-s' + Move to the `Subject' header field, creating one if there is none + (`mail-subject'). + +`C-c C-f C-c' + Move to the `CC' header field, creating one if there is none + (`mail-cc'). + +`C-c C-w' + Insert the file `~/.signature' at the end of the message text + (`mail-signature'). + +`C-c C-y' + Yank the selected message (`mail-yank-original'). + +`C-c C-q' + Fill all paragraphs of yanked old messages, each individually + (`mail-fill-yanked-message'). + +`' + Pops up a menu of useful mail-mode commands. + + There are two ways to send a message. `C-c C-c' +(`mail-send-and-exit') is the usual way to send the message. It sends +the message and then deletes the window (if there is another window) or +switches to another buffer. It puts the `*mail*' buffer at the lowest +priority for automatic reselection, since you are finished with using +it. `C-c C-s' (`mail-send') sends the message and marks the `*mail*' +buffer unmodified, but leaves that buffer selected so that you can +modify the message (perhaps with new recipients) and send it again. + + Mail mode provides some other special commands that are useful for +editing the headers and text of the message before you send it. There +are three commands defined to move point to particular header fields, +all based on the prefix `C-c C-f' (`C-f' is for "field"). They are +`C-c C-f C-t' (`mail-to') to move to the `To' field, `C-c C-f C-s' +(`mail-subject') for the `Subject' field, and `C-c C-f C-c' (`mail-cc') +for the `CC' field. These fields have special motion commands because +they are edited most frequently. + + `C-c C-w' (`mail-signature') adds a standard piece of text at the +end of the message to say more about who you are. The text comes from +the file `.signature' in your home directory. + + When you use an Rmail command to send mail from the Rmail mail +reader, you can use `C-c C-y' `mail-yank-original' inside the `*mail*' +buffer to insert the text of the message you are replying to. Normally +Rmail indents each line of that message four spaces and eliminates most +header fields. A numeric argument specifies the number of spaces to +indent. An argument of just `C-u' says not to indent at all and not to +eliminate anything. `C-c C-y' always uses the current message from the +`RMAIL' buffer, so you can insert several old messages by selecting one +in `RMAIL', switching to `*mail*' and yanking it, then switching back +to `RMAIL' to select another. + + After using `C-c C-y', you can use the command `C-c C-q' +(`mail-fill-yanked-message') to fill the paragraphs of the yanked old +message or messages. One use of `C-c C-q' fills all such paragraphs, +each one separately. + + Clicking the right mouse button in a mail buffer pops up a menu of +the above commands, for easy access. + + Turning on Mail mode (which `C-x m' does automatically) calls the +value of `text-mode-hook', if it is not void or `nil', and then calls +the value of `mail-mode-hook' if that is not void or `nil'. + + +File: xemacs.info, Node: Reading Mail, Next: Calendar/Diary, Prev: Sending Mail, Up: Top + +Reading Mail +************ + +XEmacs provides several mail-reading packages. Each one comes with its +own manual, which is included in each package. + + The recommended mail-reading package for new users is VM. VM works +with standard Unix-mail-format folders and was designed as a replacement +for the older Rmail. + + XEmacs also provides a sophisticated and comfortable front-end to the +MH mail-processing system, called `MH-E'. Unlike in other mail +programs, folders in MH are stored as file-system directories, with +each message occupying one (numbered) file. This facilitates working +with mail using shell commands, and many other features of MH are also +designed to integrate well with the shell and with shell scripts. Keep +in mind, however, that in order to use MH-E you must have the MH +mail-processing system installed on your computer. + + The "Everything including the kitchen sink" package `Gnus' is also +available as an XEmacs package. Gnus also handles Usenet articles as +well as mail. + + `MEW' (Messaging in the Emacs World) is another mail-reading package +available for XEmacs. + + Finally, XEmacs provides the Rmail package. Rmail is (currently) +the only mail reading package distributed with FSF GNU Emacs, and is +powerful in its own right. However, it stores mail folders in a +special format called `Babyl', that is incompatible with all other +frequently-used mail programs. A utility program is provided for +converting Babyl folders to standard Unix-mail format; however, unless +you already have mail in Babyl-format folders, you should consider +using Gnus, VM, or MH-E instead. + + +File: xemacs.info, Node: Calendar/Diary, Next: Sorting, Prev: Reading Mail, Up: Top + +Calendar Mode and the Diary +=========================== + +Emacs provides the functions of a desk calendar, with a diary of +planned or past events. To enter the calendar, type `M-x calendar'; +this displays a three-month calendar centered on the current month, with +point on the current date. With a numeric argument, as in `C-u M-x +calendar', it prompts you for the month and year to be the center of the +three-month calendar. The calendar uses its own buffer, whose major +mode is Calendar mode. + + `Button2' in the calendar brings up a menu of operations on a +particular date; `Buttons3' brings up a menu of commonly used calendar +features that are independent of any particular date. To exit the +calendar, type `q'. *Note Customizing the Calendar and Diary: +(lispref)Calendar, for customization information about the calendar and +diary. + +* Menu: + +* Calendar Motion:: Moving through the calendar; selecting a date. +* Scroll Calendar:: Bringing earlier or later months onto the screen. +* Mark and Region:: Remembering dates, the mark ring. +* General Calendar:: Exiting or recomputing the calendar. +* LaTeX Calendar:: Print a calendar using LaTeX. +* Holidays:: Displaying dates of holidays. +* Sunrise/Sunset:: Displaying local times of sunrise and sunset. +* Lunar Phases:: Displaying phases of the moon. +* Other Calendars:: Converting dates to other calendar systems. +* Diary:: Displaying events from your diary. +* Calendar Customization:: Altering the behavior of the features above. + + +File: xemacs.info, Node: Calendar Motion, Next: Scroll Calendar, Prev: Calendar/Diary, Up: Calendar/Diary + +Movement in the Calendar +------------------------ + +Calendar mode lets you move through the calendar in logical units of +time such as days, weeks, months, and years. If you move outside the +three months originally displayed, the calendar display "scrolls" +automatically through time to make the selected date visible. Moving to +a date lets you view its holidays or diary entries, or convert it to +other calendars; moving longer time periods is also useful simply to +scroll the calendar. + +* Menu: + +* Calendar Unit Motion:: Moving by days, weeks, months, and years. +* Move to Beginning or End:: Moving to start/end of weeks, months, and years. +* Specified Dates:: Moving to the current date or another + specific date. + + +File: xemacs.info, Node: Calendar Unit Motion, Next: Move to Beginning or End, Prev: Calendar Motion, Up: Calendar Motion + +Motion by Integral Days, Weeks, Months, Years +............................................. + +The commands for movement in the calendar buffer parallel the commands +for movement in text. You can move forward and backward by days, +weeks, months, and years. + +`C-f' + Move point one day forward (`calendar-forward-day'). + +`C-b' + Move point one day backward (`calendar-backward-day'). + +`C-n' + Move point one week forward (`calendar-forward-week'). + +`C-p' + Move point one week backward (`calendar-backward-week'). + +`M-}' + Move point one month forward (`calendar-forward-month'). + +`M-{' + Move point one month backward (`calendar-backward-month'). + +`C-x ]' + Move point one year forward (`calendar-forward-year'). + +`C-x [' + Move point one year backward (`calendar-backward-year'). + + The day and week commands are natural analogues of the usual Emacs +commands for moving by characters and by lines. Just as `C-n' usually +moves to the same column in the following line, in Calendar mode it +moves to the same day in the following week. And `C-p' moves to the +same day in the previous week. + + The arrow keys are equivalent to `C-f', `C-b', `C-n' and `C-p', just +as they normally are in other modes. + + The commands for motion by months and years work like those for +weeks, but move a larger distance. The month commands `M-}' and `M-{' +move forward or backward by an entire month's time. The year commands +`C-x ]' and `C-x [' move forward or backward a whole year. + + The easiest way to remember these commands is to consider months and +years analogous to paragraphs and pages of text, respectively. But the +commands themselves are not quite analogous. The ordinary Emacs +paragraph commands move to the beginning or end of a paragraph, whereas +these month and year commands move by an entire month or an entire +year, which usually involves skipping across the end of a month or year. + + All these commands accept a numeric argument as a repeat count. For +convenience, the digit keys and the minus sign specify numeric +arguments in Calendar mode even without the Meta modifier. For example, +`100 C-f' moves point 100 days forward from its present location. + + +File: xemacs.info, Node: Move to Beginning or End, Next: Specified Dates, Prev: Calendar Unit Motion, Up: Calendar Motion + +Beginning or End of Week, Month or Year +....................................... + +A week (or month, or year) is not just a quantity of days; we think of +weeks (months, years) as starting on particular dates. So Calendar mode +provides commands to move to the beginning or end of a week, month or +year: + +`C-a' + Move point to start of week (`calendar-beginning-of-week'). + +`C-e' + Move point to end of week (`calendar-end-of-week'). + +`M-a' + Move point to start of month (`calendar-beginning-of-month'). + +`M-e' + Move point to end of month (`calendar-end-of-month'). + +`M-<' + Move point to start of year (`calendar-beginning-of-year'). + +`M->' + Move point to end of year (`calendar-end-of-year'). + + These commands also take numeric arguments as repeat counts, with the +repeat count indicating how many weeks, months, or years to move +backward or forward. + + By default, weeks begin on Sunday. To make them begin on Monday +instead, set the variable `calendar-week-start-day' to 1. + + +File: xemacs.info, Node: Specified Dates, Prev: Move to Beginning or End, Up: Calendar Motion + +Particular Dates +................ + +Calendar mode provides commands for moving to a particular date +specified in various ways. + +`g d' + Move point to specified date (`calendar-goto-date'). + +`o' + Center calendar around specified month (`calendar-other-month'). + +`.' + Move point to today's date (`calendar-goto-today'). + + `g d' (`calendar-goto-date') prompts for a year, a month, and a day +of the month, and then moves to that date. Because the calendar +includes all dates from the beginning of the current era, you must type +the year in its entirety; that is, type `1990', not `90'. + + `o' (`calendar-other-month') prompts for a month and year, then +centers the three-month calendar around that month. + + You can return to today's date with `.' (`calendar-goto-today'). + + +File: xemacs.info, Node: Scroll Calendar, Next: Mark and Region, Prev: Calendar Motion, Up: Calendar/Diary + +Scrolling the Calendar through Time +----------------------------------- + +The calendar display scrolls automatically through time when you move +out of the visible portion. You can also scroll it manually. Imagine +that the calendar window contains a long strip of paper with the months +on it. Scrolling it means moving the strip so that new months become +visible in the window. + +`C-x <' + Scroll calendar one month forward (`scroll-calendar-left'). + +`C-x >' + Scroll calendar one month backward (`scroll-calendar-right'). + +`C-v' +`' + Scroll calendar three months forward + (`scroll-calendar-left-three-months'). + +`M-v' +`' + Scroll calendar three months backward + (`scroll-calendar-right-three-months'). + + The most basic calendar scroll commands scroll by one month at a +time. This means that there are two months of overlap between the +display before the command and the display after. `C-x <' scrolls the +calendar contents one month to the left; that is, it moves the display +forward in time. `C-x >' scrolls the contents to the right, which +moves backwards in time. + + The commands `C-v' and `M-v' scroll the calendar by an entire +"screenful"--three months--in analogy with the usual meaning of these +commands. `C-v' makes later dates visible and `M-v' makes earlier +dates visible. These commands take a numeric argument as a repeat +count; in particular, since `C-u' multiplies the next command by four, +typing `C-u C-v' scrolls the calendar forward by a year and typing `C-u +M-v' scrolls the calendar backward by a year. + + The function keys and are equivalent to `C-v' and +`M-v', just as they are in other modes. + + +File: xemacs.info, Node: Mark and Region, Next: General Calendar, Prev: Scroll Calendar, Up: Calendar/Diary + +The Mark and the Region +----------------------- + +The concept of the mark applies to the calendar just as to any other +buffer, but it marks a _date_, not a _position_ in the buffer. The +region consists of the days between the mark and point (including the +starting and stopping dates). + +`C-SPC' + Set the mark to today's date (`calendar-set-mark'). + +`C-@' + The same. + +`C-x C-x' + Interchange mark and point (`calendar-exchange-point-and-mark'). + +`M-=' + Display the number of days in the current region + (`calendar-count-days-region'). + + You set the mark in the calendar, as in any other buffer, by using +`C-@' or `C-SPC' (`calendar-set-mark'). You return to the marked date +with the command `C-x C-x' (`calendar-exchange-point-and-mark') which +puts the mark where point was and point where mark was. The calendar +is scrolled as necessary, if the marked date was not visible on the +screen. This does not change the extent of the region. + + To determine the number of days in the region, type `M-=' +(`calendar-count-days-region'). The numbers of days printed is +_inclusive_; that is, it includes the days specified by mark and point. + + The main use of the mark in the calendar is to remember dates that +you may want to go back to. To make this feature more useful, the mark +ring (*note Mark Ring::) operates exactly as in other buffers: Emacs +remembers 16 previous locations of the mark. To return to a marked +date, type `C-u C-SPC' (or `C-u C-@'); this is the command +`calendar-set-mark' given a numeric argument. It moves point to where +the mark was, restores the mark from the ring of former marks, and +stores the previous point at the end of the mark ring. So, repeated +use of this command moves point through all the old marks on the ring, +one by one. + + +File: xemacs.info, Node: General Calendar, Next: LaTeX Calendar, Prev: Mark and Region, Up: Calendar/Diary + +Miscellaneous Calendar Commands +------------------------------- + +`p d' + Display day-in-year (`calendar-print-day-of-year'). + +`?' + Briefly describe calendar commands (`describe-calendar-mode'). + +`C-c C-l' + Regenerate the calendar window (`redraw-calendar'). + +`SPC' + Scroll the next window (`scroll-other-window'). + +`q' + Exit from calendar (`exit-calendar'). + + If you want to know how many days have elapsed since the start of +the year, or the number of days remaining in the year, type the `p d' +command (`calendar-print-day-of-year'). This displays both of those +numbers in the echo area. + + To display a brief description of the calendar commands, type `?' +(`describe-calendar-mode'). For a fuller description, type `C-h m'. + + You can use `SPC' (`scroll-other-window') to scroll the other +window. This is handy when you display a list of holidays or diary +entries in another window. + + If the calendar window text gets corrupted, type `C-c C-l' +(`redraw-calendar') to redraw it. (This can only happen if you use +non-Calendar-mode editing commands.) + + In Calendar mode, you can use `SPC' (`scroll-other-window') to +scroll the other window. This is handy when you display a list of +holidays or diary entries in another window. + + To exit from the calendar, type `q' (`exit-calendar'). This buries +all buffers related to the calendar, selecting other buffers. (If a +frame contains a dedicated calendar window, exiting from the calendar +iconifies that frame.) + + +File: xemacs.info, Node: LaTeX Calendar, Next: Holidays, Prev: General Calendar, Up: Calendar/Diary + +LaTeX Calendar +============== + +The Calendar LaTeX commands produce a buffer of LaTeX code that prints +as a calendar. Depending on the command you use, the printed calendar +covers the day, week, month or year that point is in. + +`t m' + Generate a one-month calendar (`cal-tex-cursor-month'). + +`t M' + Generate a sideways-printing one-month calendar + (`cal-tex-cursor-month-landscape'). + +`t d' + Generate a one-day calendar (`cal-tex-cursor-day'). + +`t w 1' + Generate a one-page calendar for one week (`cal-tex-cursor-week'). + +`t w 2' + Generate a two-page calendar for one week (`cal-tex-cursor-week2'). + +`t w 3' + Generate an ISO-style calendar for one week + (`cal-tex-cursor-week-iso'). + +`t w 4' + Generate a calendar for one Monday-starting week + (`cal-tex-cursor-week-monday'). + +`t f w' + Generate a Filofax-style two-weeks-at-a-glance calendar + (`cal-tex-cursor-filofax-2week'). + +`t f W' + Generate a Filofax-style one-week-at-a-glance calendar + (`cal-tex-cursor-filofax-week'). + +`t y' + Generate a calendar for one year (`cal-tex-cursor-year'). + +`t Y' + Generate a sideways-printing calendar for one year + (`cal-tex-cursor-year-landscape'). + +`t f y' + Generate a Filofax-style calendar for one year + (`cal-tex-cursor-filofax-year'). + + Some of these commands print the calendar sideways (in "landscape +mode"), so it can be wider than it is long. Some of them use Filofax +paper size (3.75in x 6.75in). All of these commands accept a prefix +argument which specifies how many days, weeks, months or years to print +(starting always with the selected one). + + If the variable `cal-tex-holidays' is non-`nil' (the default), then +the printed calendars show the holidays in `calendar-holidays'. If the +variable `cal-tex-diary' is non-`nil' (the default is `nil'), diary +entries are included also (in weekly and monthly calendars only). + + +File: xemacs.info, Node: Holidays, Next: Sunrise/Sunset, Prev: LaTeX Calendar, Up: Calendar/Diary + +Holidays +-------- + +The Emacs calendar knows about all major and many minor holidays, and +can display them. + +`h' + Display holidays for the selected date + (`calendar-cursor-holidays'). + +`Button2 Holidays' + Display any holidays for the date you click on. + +`x' + Mark holidays in the calendar window (`mark-calendar-holidays'). + +`u' + Unmark calendar window (`calendar-unmark'). + +`a' + List all holidays for the displayed three months in another window + (`list-calendar-holidays'). + +`M-x holidays' + List all holidays for three months around today's date in another + window. + +`M-x list-holidays' + List holidays in another window for a specified range of years. + + To see if any holidays fall on a given date, position point on that +date in the calendar window and use the `h' command. Alternatively, +click on that date with `Button2' and then choose `Holidays' from the +menu that appears. Either way, this displays the holidays for that +date, in the echo area if they fit there, otherwise in a separate +window. + + To view the distribution of holidays for all the dates shown in the +calendar, use the `x' command. This displays the dates that are +holidays in a different face (or places a `*' after these dates, if +display with multiple faces is not available). The command applies both +to the currently visible months and to other months that subsequently +become visible by scrolling. To turn marking off and erase the current +marks, type `u', which also erases any diary marks (*note Diary::). + + To get even more detailed information, use the `a' command, which +displays a separate buffer containing a list of all holidays in the +current three-month range. You can use in the calendar window to +scroll that list. + + The command `M-x holidays' displays the list of holidays for the +current month and the preceding and succeeding months; this works even +if you don't have a calendar window. If you want the list of holidays +centered around a different month, use `C-u M-x holidays', which +prompts for the month and year. + + The holidays known to Emacs include United States holidays and the +major Christian, Jewish, and Islamic holidays; also the solstices and +equinoxes. + + The command `M-x list-holidays' displays the list of holidays for a +range of years. This function asks you for the starting and stopping +years, and allows you to choose all the holidays or one of several +categories of holidays. You can use this command even if you don't have +a calendar window. + + The dates used by Emacs for holidays are based on _current +practice_, not historical fact. Historically, for instance, the start +of daylight savings time and even its existence have varied from year to +year, but present United States law mandates that daylight savings time +begins on the first Sunday in April. When the daylight savings rules +are set up for the United States, Emacs always uses the present +definition, even though it is wrong for some prior years. + + +File: xemacs.info, Node: Sunrise/Sunset, Next: Lunar Phases, Prev: Holidays, Up: Calendar/Diary + +Times of Sunrise and Sunset +--------------------------- + +Special calendar commands can tell you, to within a minute or two, the +times of sunrise and sunset for any date. + +`S' + Display times of sunrise and sunset for the selected date + (`calendar-sunrise-sunset'). + +`Button2 Sunrise/Sunset' + Display times of sunrise and sunset for the date you click on. + +`M-x sunrise-sunset' + Display times of sunrise and sunset for today's date. + +`C-u M-x sunrise-sunset' + Display times of sunrise and sunset for a specified date. + + Within the calendar, to display the _local times_ of sunrise and +sunset in the echo area, move point to the date you want, and type `S'. +Alternatively, click `Button2' on the date, then choose +`Sunrise/Sunset' from the menu that appears. The command `M-x +sunrise-sunset' is available outside the calendar to display this +information for today's date or a specified date. To specify a date +other than today, use `C-u M-x sunrise-sunset', which prompts for the +year, month, and day. + + You can display the times of sunrise and sunset for any location and +any date with `C-u C-u M-x sunrise-sunset'. This asks you for a +longitude, latitude, number of minutes difference from Coordinated +Universal Time, and date, and then tells you the times of sunrise and +sunset for that location on that date. + + Because the times of sunrise and sunset depend on the location on +earth, you need to tell Emacs your latitude, longitude, and location +name before using these commands. Here is an example of what to set: + + (setq calendar-latitude 40.1) + (setq calendar-longitude -88.2) + (setq calendar-location-name "Urbana, IL") + +Use one decimal place in the values of `calendar-latitude' and +`calendar-longitude'. + + Your time zone also affects the local time of sunrise and sunset. +Emacs usually gets time zone information from the operating system, but +if these values are not what you want (or if the operating system does +not supply them), you must set them yourself. Here is an example: + + (setq calendar-time-zone -360) + (setq calendar-standard-time-zone-name "CST") + (setq calendar-daylight-time-zone-name "CDT") + +The value of `calendar-time-zone' is the number of minutes difference +between your local standard time and Coordinated Universal Time +(Greenwich time). The values of `calendar-standard-time-zone-name' and +`calendar-daylight-time-zone-name' are the abbreviations used in your +time zone. Emacs displays the times of sunrise and sunset _corrected +for daylight savings time_. *Note Daylight Savings::, for how daylight +savings time is determined. + + As a user, you might find it convenient to set the calendar location +variables for your usual physical location in your init file. And when +you install Emacs on a machine, you can create a `default.el' file +which sets them properly for the typical location of most users of that +machine. *Note Init File::. + + +File: xemacs.info, Node: Lunar Phases, Next: Other Calendars, Prev: Sunrise/Sunset, Up: Calendar/Diary + +Phases of the Moon +------------------ + +These calendar commands display the dates and times of the phases of +the moon (new moon, first quarter, full moon, last quarter). This +feature is useful for debugging problems that "depend on the phase of +the moon." + +`M' + Display the dates and times for all the quarters of the moon for + the three-month period shown (`calendar-phases-of-moon'). + +`M-x phases-of-moon' + Display dates and times of the quarters of the moon for three + months around today's date. + + Within the calendar, use the `M' command to display a separate +buffer of the phases of the moon for the current three-month range. The +dates and times listed are accurate to within a few minutes. + + Outside the calendar, use the command `M-x phases-of-moon' to +display the list of the phases of the moon for the current month and the +preceding and succeeding months. For information about a different +month, use `C-u M-x phases-of-moon', which prompts for the month and +year. + + The dates and times given for the phases of the moon are given in +local time (corrected for daylight savings, when appropriate); but if +the variable `calendar-time-zone' is void, Coordinated Universal Time +(the Greenwich time zone) is used. *Note Daylight Savings::. + + +File: xemacs.info, Node: Other Calendars, Next: Calendar Systems, Prev: Lunar Phases, Up: Calendar/Diary + +Conversion To and From Other Calendars +-------------------------------------- + +The Emacs calendar displayed is _always_ the Gregorian calendar, +sometimes called the "new style" calendar, which is used in most of the +world today. However, this calendar did not exist before the sixteenth +century and was not widely used before the eighteenth century; it did +not fully displace the Julian calendar and gain universal acceptance +until the early twentieth century. The Emacs calendar can display any +month since January, year 1 of the current era, but the calendar +displayed is the Gregorian, even for a date at which the Gregorian +calendar did not exist. + + While Emacs cannot display other calendars, it can convert dates to +and from several other calendars. + +* Menu: + +* Calendar Systems:: The calendars Emacs understands + (aside from Gregorian). +* To Other Calendar:: Converting the selected date to various calendars. +* From Other Calendar:: Moving to a date specified in another calendar. +* Mayan Calendar:: Moving to a date specified in a Mayan calendar. + + If you are interested in these calendars, you can convert dates one +at a time. Put point on the desired date of the Gregorian calendar and +press the appropriate keys. The `p' is a mnemonic for "print" since +Emacs "prints' the equivalent date in the echo area. + + +File: xemacs.info, Node: Calendar Systems, Next: To Other Calendar, Prev: Other Calendars, Up: Other Calendars + +Supported Calendar Systems +========================== + +The ISO commercial calendar is used largely in Europe. + + The Julian calendar, named after Julius Caesar, was the one used in +Europe throughout medieval times, and in many countries up until the +nineteenth century. + + Astronomers use a simple counting of days elapsed since noon, Monday, +January 1, 4713 B.C. on the Julian calendar. The number of days elapsed +is called the _Julian day number_ or the _Astronomical day number_. + + The Hebrew calendar is used by tradition in the Jewish religion. The +Emacs calendar program uses the Hebrew calendar to determine the dates +of Jewish holidays. Hebrew calendar dates begin and end at sunset. + + The Islamic calendar is used in many predominantly Islamic countries. +Emacs uses it to determine the dates of Islamic holidays. There is no +universal agreement in the Islamic world about the calendar; Emacs uses +a widely accepted version, but the precise dates of Islamic holidays +often depend on proclamation by religious authorities, not on +calculations. As a consequence, the actual dates of observance can vary +slightly from the dates computed by Emacs. Islamic calendar dates begin +and end at sunset. + + The French Revolutionary calendar was created by the Jacobins after +the 1789 revolution, to represent a more secular and nature-based view +of the annual cycle, and to install a 10-day week in a rationalization +measure similar to the metric system. The French government officially +abandoned this calendar at the end of 1805. + + The Maya of Central America used three separate, overlapping calendar +systems, the _long count_, the _tzolkin_, and the _haab_. Emacs knows +about all three of these calendars. Experts dispute the exact +correlation between the Mayan calendar and our calendar; Emacs uses the +Goodman-Martinez-Thompson correlation in its calculations. + + The Copts use a calendar based on the ancient Egyptian solar +calendar. Their calendar consists of twelve 30-day months followed by +an extra five-day period. Once every fourth year they add a leap day +to this extra period to make it six days. The Ethiopic calendar is +identical in structure, but has different year numbers and month names. + + The Persians use a solar calendar based on a design of Omar Khayyam. +Their calendar consists of twelve months of which the first six have 31 +days, the next five have 30 days, and the last has 29 in ordinary years +and 30 in leap years. Leap years occur in a complicated pattern every +four or five years. + + The Chinese calendar is a complicated system of lunar months arranged +into solar years. The years go in cycles of sixty, each year containing +either twelve months in an ordinary year or thirteen months in a leap +year; each month has either 29 or 30 days. Years, ordinary months, and +days are named by combining one of ten "celestial stems" with one of +twelve "terrestrial branches" for a total of sixty names that are +repeated in a cycle of sixty. + + +File: xemacs.info, Node: To Other Calendar, Next: From Other Calendar, Prev: Calendar Systems, Up: Other Calendars + +Converting To Other Calendars +============================= + +The following commands describe the selected date (the date at point) +in various other calendar systems: + +`Button2 Other Calendars' + Display the date that you click on, expressed in various other + calendars. + +`p c' + Display ISO commercial calendar equivalent for selected day + (`calendar-print-iso-date'). + +`p j' + Display Julian date for selected day + (`calendar-print-julian-date'). + +`p a' + Display astronomical (Julian) day number for selected day + (`calendar-print-astro-day-number'). + +`p h' + Display Hebrew date for selected day + (`calendar-print-hebrew-date'). + +`p i' + Display Islamic date for selected day + (`calendar-print-islamic-date'). + +`p f' + Display French Revolutionary date for selected day + (`calendar-print-french-date'). + +`p C' + Display Chinese date for selected day + (`calendar-print-chinese-date'). + +`p k' + Display Coptic date for selected day + (`calendar-print-coptic-date'). + +`p e' + Display Ethiopic date for selected day + (`calendar-print-ethiopic-date'). + +`p p' + Display Persian date for selected day + (`calendar-print-persian-date'). + +`p m' + Display Mayan date for selected day (`calendar-print-mayan-date'). + + If you are using X, the easiest way to translate a date into other +calendars is to click on it with `Button2', then choose `Other +Calendars' from the menu that appears. This displays the equivalent +forms of the date in all the calendars Emacs understands, in the form of +a menu. (Choosing an alternative from this menu doesn't actually do +anything--the menu is used only for display.) + + Put point on the desired date of the Gregorian calendar, then type +the appropriate keys. The `p' is a mnemonic for "print" since Emacs +"prints" the equivalent date in the echo area. + + +File: xemacs.info, Node: From Other Calendar, Next: Mayan Calendar, Prev: To Other Calendar, Up: Other Calendars + +Converting From Other Calendars +=============================== + +You can use the other supported calendars to specify a date to move to. +This section describes the commands for doing this using calendars +other than Mayan; for the Mayan calendar, see the following section. + +`g c' + Move to a date specified in the ISO commercial calendar + (`calendar-goto-iso-date'). + +`g j' + Move to a date specified in the Julian calendar + (`calendar-goto-julian-date'). + +`g a' + Move to a date specified in astronomical (Julian) day number + (`calendar-goto-astro-day-number'). + +`g h' + Move to a date specified in the Hebrew calendar + (`calendar-goto-hebrew-date'). + +`g i' + Move to a date specified in the Islamic calendar + (`calendar-goto-islamic-date'). + +`g f' + Move to a date specified in the French Revolutionary calendar + (`calendar-goto-french-date'). + +`g C' + Move to a date specified in the Chinese calendar + (`calendar-goto-chinese-date'). + +`g p' + Move to a date specified in the Persian calendar + (`calendar-goto-persian-date'). + +`g k' + Move to a date specified in the Coptic calendar + (`calendar-goto-coptic-date'). + +`g e' + Move to a date specified in the Ethiopic calendar + (`calendar-goto-ethiopic-date'). + + These commands ask you for a date on the other calendar, move point +to the Gregorian calendar date equivalent to that date, and display the +other calendar's date in the echo area. Emacs uses strict completion +(*note Completion::) whenever it asks you to type a month name, so you +don't have to worry about the spelling of Hebrew, Islamic, or French +names. + + One common question concerning the Hebrew calendar is the computation +of the anniversary of a date of death, called a "yahrzeit." The Emacs +calendar includes a facility for such calculations. If you are in the +calendar, the command `M-x list-yahrzeit-dates' asks you for a range of +years and then displays a list of the yahrzeit dates for those years +for the date given by point. If you are not in the calendar, this +command first asks you for the date of death and the range of years, +and then displays the list of yahrzeit dates. + + +File: xemacs.info, Node: Mayan Calendar, Next: Diary, Prev: From Other Calendar, Up: Other Calendars + +Converting from the Mayan Calendar +---------------------------------- + +Here are the commands to select dates based on the Mayan calendar: + +`g m l' + Move to a date specified by the long count calendar + (`calendar-goto-mayan-long-count-date'). + +`g m n t' + Move to the next occurrence of a place in the tzolkin calendar + (`calendar-next-tzolkin-date'). + +`g m p t' + Move to the previous occurrence of a place in the tzolkin calendar + (`calendar-previous-tzolkin-date'). + +`g m n h' + Move to the next occurrence of a place in the haab calendar + (`calendar-next-haab-date'). + +`g m p h' + Move to the previous occurrence of a place in the haab calendar + (`calendar-previous-haab-date'). + +`g m n c' + Move to the next occurrence of a place in the calendar round + (`calendar-next-calendar-round-date'). + +`g m p c' + Move to the previous occurrence of a place in the calendar round + (`calendar-previous-calendar-round-date'). + + To understand these commands, you need to understand the Mayan +calendars. The "long count" is a counting of days with these units: + + 1 kin = 1 day 1 uinal = 20 kin 1 tun = 18 uinal + 1 katun = 20 tun 1 baktun = 20 katun + +Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 +tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long +count dates as early as 7.17.18.13.1, but no earlier. When you use the +`g m l' command, type the Mayan long count date with the baktun, katun, +tun, uinal, and kin separated by periods. + + The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of +independent cycles of 13 and 20 days. Since this cycle repeats +endlessly, Emacs provides commands to move backward and forward to the +previous or next point in the cycle. Type `g m p t' to go to the +previous tzolkin date; Emacs asks you for a tzolkin date and moves point +to the previous occurrence of that date. Similarly, type `g m n t' to +go to the next occurrence of a tzolkin date. + + The Mayan haab calendar is a cycle of 365 days arranged as 18 months +of 20 days each, followed a 5-day monthless period. Like the tzolkin +cycle, this cycle repeats endlessly, and there are commands to move +backward and forward to the previous or next point in the cycle. Type +`g m p h' to go to the previous haab date; Emacs asks you for a haab +date and moves point to the previous occurrence of that date. +Similarly, type `g m n h' to go to the next occurrence of a haab date. + + The Maya also used the combination of the tzolkin date and the haab +date. This combination is a cycle of about 52 years called a _calendar +round_. If you type `g m p c', Emacs asks you for both a haab and a +tzolkin date and then moves point to the previous occurrence of that +combination. Use `g m n c' to move point to the next occurrence of a +combination. These commands signal an error if the haab/tzolkin date +combination you have typed is impossible. + + Emacs uses strict completion (*note Completion::) whenever it asks +you to type a Mayan name, so you don't have to worry about spelling. + + +File: xemacs.info, Node: Diary, Next: Calendar Customization, Prev: Mayan Calendar, Up: Calendar/Diary + +The Diary +--------- + +The Emacs diary keeps track of appointments or other events on a daily +basis, in conjunction with the calendar. To use the diary feature, you +must first create a "diary file" containing a list of events and their +dates. Then Emacs can automatically pick out and display the events +for today, for the immediate future, or for any specified date. + + By default, Emacs uses `~/diary' as the diary file. This is the +same file that the `calendar' utility uses. A sample `~/diary' file is: + + 12/22/1988 Twentieth wedding anniversary!! + &1/1. Happy New Year! + 10/22 Ruth's birthday. + * 21, *: Payday + Tuesday--weekly meeting with grad students at 10am + Supowit, Shen, Bitner, and Kapoor to attend. + 1/13/89 Friday the thirteenth!! + &thu 4pm squash game with Lloyd. + mar 16 Dad's birthday + April 15, 1989 Income tax due. + &* 15 time cards due. + +This example uses extra spaces to align the event descriptions of most +of the entries. Such formatting is purely a matter of taste. + + Although you probably will start by creating a diary manually, Emacs +provides a number of commands to let you view, add, and change diary +entries. You can also share diary entries with other users (*note +Included Diary Files::). + +* Menu: + +* Diary Commands:: Viewing diary entries and associated calendar dates. +* Format of Diary File:: Entering events in your diary. +* Date Formats:: Various ways you can specify dates. +* Adding to Diary:: Commands to create diary entries. +* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. + + +File: xemacs.info, Node: Diary Commands, Next: Format of Diary File, Prev: Diary, Up: Diary + +Commands Displaying Diary Entries +--------------------------------- + +Once you have created a `~/diary' file, you can use the calendar to +view it. You can also view today's events outside of Calendar mode. + +`d' + Display all diary entries for the selected date + (`view-diary-entries'). + +`Button2 Diary' + Display all diary entries for the date you click on. + +`s' + Display the entire diary file (`show-all-diary-entries'). + +`m' + Mark all visible dates that have diary entries + (`mark-diary-entries'). + +`u' + Unmark the calendar window (`calendar-unmark'). + +`M-x print-diary-entries' + Print hard copy of the diary display as it appears. + +`M-x diary' + Display all diary entries for today's date. + +`M-x diary-mail-entries' + Mail yourself email reminders about upcoming diary entries. + + Displaying the diary entries with `d' shows in a separate window the +diary entries for the selected date in the calendar. The mode line of +the new window shows the date of the diary entries and any holidays +that fall on that date. If you specify a numeric argument with `d', it +shows all the diary entries for that many successive days. Thus, `2 d' +displays all the entries for the selected date and for the following +day. + + Another way to display the diary entries for a date is to click +`Button2' on the date, and then choose `Diary' from the menu that +appears. + + To get a broader view of which days are mentioned in the diary, use +the `m' command. This displays the dates that have diary entries in a +different face (or places a `+' after these dates, if display with +multiple faces is not available). The command applies both to the +currently visible months and to other months that subsequently become +visible by scrolling. To turn marking off and erase the current marks, +type `u', which also turns off holiday marks (*note Holidays::). + + To see the full diary file, rather than just some of the entries, use +the `s' command. + + Display of selected diary entries uses the selective display feature +to hide entries that don't apply. + + The diary buffer as you see it is an illusion, so simply printing the +buffer does not print what you see on your screen. There is a special +command to print hard copy of the diary buffer _as it appears_; this +command is `M-x print-diary-entries'. It sends the data directly to +the printer. You can customize it like `lpr-region' (*note Hardcopy::). + + The command `M-x diary' displays the diary entries for the current +date, independently of the calendar display, and optionally for the next +few days as well; the variable `number-of-diary-entries' specifies how +many days to include (*note Customization::). + + If you put `(diary)' in your init file, this automatically displays +a window with the day's diary entries, when you enter Emacs. *Note +Init File::. The mode line of the displayed window shows the date and +any holidays that fall on that date. + + Many users like to receive notice of events in their diary as email. +To send such mail to yourself, use the command `M-x +diary-mail-entries'. A prefix argument specifies how many days +(starting with today) to check; otherwise, the variable +`diary-mail-days' says how many days. + + +File: xemacs.info, Node: Format of Diary File, Next: Date Formats, Prev: Diary Commands, Up: Diary + +The Diary File +-------------- + +Your "diary file" is a file that records events associated with +particular dates. The name of the diary file is specified by the +variable `diary-file'; `~/diary' is the default. The `calendar' +utility program supports a subset of the format allowed by the Emacs +diary facilities, so you can use that utility to view the diary file, +with reasonable results aside from the entries it cannot understand. + + Each entry in the diary file describes one event and consists of one +or more lines. An entry always begins with a date specification at the +left margin. The rest of the entry is simply text to describe the +event. If the entry has more than one line, then the lines after the +first must begin with whitespace to indicate they continue a previous +entry. Lines that do not begin with valid dates and do not continue a +preceding entry are ignored. + + You can inhibit the marking of certain diary entries in the calendar +window; to do this, insert an ampersand (`&') at the beginning of the +entry, before the date. This has no effect on display of the entry in +the diary window; it affects only marks on dates in the calendar +window. Nonmarking entries are especially useful for generic entries +that would otherwise mark many different dates. + + If the first line of a diary entry consists only of the date or day +name with no following blanks or punctuation, then the diary window +display doesn't include that line; only the continuation lines appear. +For example, this entry: + + 02/11/1989 + Bill B. visits Princeton today + 2pm Cognitive Studies Committee meeting + 2:30-5:30 Liz at Lawrenceville + 4:00pm Dentist appt + 7:30pm Dinner at George's + 8:00-10:00pm concert + +appears in the diary window without the date line at the beginning. +This style of entry looks neater when you display just a single day's +entries, but can cause confusion if you ask for more than one day's +entries. + + You can edit the diary entries as they appear in the window, but it +is important to remember that the buffer displayed contains the _entire_ +diary file, with portions of it concealed from view. This means, for +instance, that the `C-f' (`forward-char') command can put point at what +appears to be the end of the line, but what is in reality the middle of +some concealed line. + + _Be careful when editing the diary entries!_ Inserting additional +lines or adding/deleting characters in the middle of a visible line +cannot cause problems, but editing at the end of a line may not do what +you expect. Deleting a line may delete other invisible entries that +follow it. Before editing the diary, it is best to display the entire +file with `s' (`show-all-diary-entries'). + + +File: xemacs.info, Node: Date Formats, Next: Adding to Diary, Prev: Format of Diary File, Up: Diary + +Date Formats +------------ + +Here are some sample diary entries, illustrating different ways of +formatting a date. The examples all show dates in American order +(month, day, year), but Calendar mode supports European order (day, +month, year) as an option. + + 4/20/93 Switch-over to new tabulation system + apr. 25 Start tabulating annual results + 4/30 Results for April are due + */25 Monthly cycle finishes + Friday Don't leave without backing up files + + The first entry appears only once, on April 20, 1993. The second and +third appear every year on the specified dates, and the fourth uses a +wildcard (asterisk) for the month, so it appears on the 25th of every +month. The final entry appears every week on Friday. + + You can use just numbers to express a date, as in `MONTH/DAY' or +`MONTH/DAY/YEAR'. This must be followed by a nondigit. In the date +itself, MONTH and DAY are numbers of one or two digits. The optional +YEAR is also a number, and may be abbreviated to the last two digits; +that is, you can use `11/12/1989' or `11/12/89'. + + Dates can also have the form `MONTHNAME DAY' or `MONTHNAME DAY, +YEAR', where the month's name can be spelled in full or abbreviated to +three characters (with or without a period). Case is not significant. + + A date may be "generic"; that is, partially unspecified. Then the +entry applies to all dates that match the specification. If the date +does not contain a year, it is generic and applies to any year. +Alternatively, MONTH, DAY, or YEAR can be a `*'; this matches any +month, day, or year, respectively. Thus, a diary entry `3/*/*' matches +any day in March of any year; so does `march *'. + + If you prefer the European style of writing dates--in which the day +comes before the month--type `M-x european-calendar' while in the +calendar, or set the variable `european-calendar-style' to `t' _before_ +using any calendar or diary command. This mode interprets all dates in +the diary in the European manner, and also uses European style for +displaying diary dates. (Note that there is no comma after the +MONTHNAME in the European style.) To go back to the (default) American +style of writing dates, type `M-x american-calendar'. + + You can use the name of a day of the week as a generic date which +applies to any date falling on that day of the week. You can abbreviate +the day of the week to three letters (with or without a period) or spell +it in full; case is not significant. + + +File: xemacs.info, Node: Adding to Diary, Next: Special Diary Entries, Prev: Date Formats, Up: Diary + +Commands to Add to the Diary +---------------------------- + +While in the calendar, there are several commands to create diary +entries: + +`i d' + Add a diary entry for the selected date (`insert-diary-entry'). + +`i w' + Add a diary entry for the selected day of the week + (`insert-weekly-diary-entry'). + +`i m' + Add a diary entry for the selected day of the month + (`insert-monthly-diary-entry'). + +`i y' + Add a diary entry for the selected day of the year + (`insert-yearly-diary-entry'). + + You can make a diary entry for a specific date by selecting that date +in the calendar window and typing the `i d' command. This command +displays the end of your diary file in another window and inserts the +date; you can then type the rest of the diary entry. + + If you want to make a diary entry that applies to a specific day of +the week, select that day of the week (any occurrence will do) and type +`i w'. This inserts the day-of-week as a generic date; you can then +type the rest of the diary entry. You can make a monthly diary entry in +the same fashion. Select the day of the month, use the `i m' command, +and type rest of the entry. Similarly, you can insert a yearly diary +entry with the `i y' command. + + All of the above commands make marking diary entries by default. To +make a nonmarking diary entry, give a numeric argument to the command. +For example, `C-u i w' makes a nonmarking weekly diary entry. + + When you modify the diary file, be sure to save the file before +exiting Emacs. + + +File: xemacs.info, Node: Special Diary Entries, Prev: Adding to Diary, Up: Diary + +Special Diary Entries +--------------------- + +In addition to entries based on calendar dates, the diary file can +contain "sexp entries" for regular events such as anniversaries. These +entries are based on Lisp expressions (sexps) that Emacs evaluates as +it scans the diary file. Instead of a date, a sexp entry contains `%%' +followed by a Lisp expression which must begin and end with +parentheses. The Lisp expression determines which dates the entry +applies to. + + Calendar mode provides commands to insert certain commonly used sexp +entries: + +`i a' + Add an anniversary diary entry for the selected date + (`insert-anniversary-diary-entry'). + +`i b' + Add a block diary entry for the current region + (`insert-block-diary-entry'). + +`i c' + Add a cyclic diary entry starting at the date + (`insert-cyclic-diary-entry'). + + If you want to make a diary entry that applies to the anniversary of +a specific date, move point to that date and use the `i a' command. +This displays the end of your diary file in another window and inserts +the anniversary description; you can then type the rest of the diary +entry. The entry looks like this: + + The effect of `i a' is to add a `diary-anniversary' sexp to your +diary file. You can also add one manually, for instance: + + %%(diary-anniversary 10 31 1948) Arthur's birthday + +This entry applies to October 31 in any year after 1948; `10 31 1948' +specifies the date. (If you are using the European calendar style, the +month and day are interchanged.) The reason this expression requires a +beginning year is that advanced diary functions can use it to calculate +the number of elapsed years. + + A "block" diary entry applies to a specified range of consecutive +dates. Here is a block diary entry that applies to all dates from June +24, 1990 through July 10, 1990: + + %%(diary-block 6 24 1990 7 10 1990) Vacation + +The `6 24 1990' indicates the starting date and the `7 10 1990' +indicates the stopping date. (Again, if you are using the European +calendar style, the month and day are interchanged.) + + To insert a block entry, place point and the mark on the two dates +that begin and end the range, and type `i b'. This command displays +the end of your diary file in another window and inserts the block +description; you can then type the diary entry. + + "Cyclic" diary entries repeat after a fixed interval of days. To +create one, select the starting date and use the `i c' command. The +command prompts for the length of interval, then inserts the entry, +which looks like this: + + %%(diary-cyclic 50 3 1 1990) Renew medication + +This entry applies to March 1, 1990 and every 50th day following; `3 1 +1990' specifies the starting date. (If you are using the European +calendar style, the month and day are interchanged.) + + All three of these commands make marking diary entries. To insert a +nonmarking entry, give a numeric argument to the command. For example, +`C-u i a' makes a nonmarking anniversary diary entry. + + Marking sexp diary entries in the calendar is _extremely_ +time-consuming, since every date visible in the calendar window must be +individually checked. So it's a good idea to make sexp diary entries +nonmarking (with `&') when possible. + + Another sophisticated kind of sexp entry, a "floating" diary entry, +specifies a regularly occurring event by offsets specified in days, +weeks, and months. It is comparable to a crontab entry interpreted by +the `cron' utility. Here is a nonmarking, floating diary entry that +applies to the last Thursday in November: + + &%%(diary-float 11 4 -1) American Thanksgiving + +The 11 specifies November (the eleventh month), the 4 specifies Thursday +(the fourth day of the week, where Sunday is numbered zero), and the -1 +specifies "last" (1 would mean "first", 2 would mean "second", -2 would +mean "second-to-last", and so on). The month can be a single month or +a list of months. Thus you could change the 11 above to `'(1 2 3)' and +have the entry apply to the last Thursday of January, February, and +March. If the month is `t', the entry applies to all months of the +year. + + The sexp feature of the diary allows you to specify diary entries +based on any Emacs Lisp expression. You can use the library of built-in +functions or you can write your own functions. The built-in functions +include the ones shown in this section, plus a few others (*note Sexp +Diary Entries::). + + The generality of sexps lets you specify any diary entry that you can +describe algorithmically. Suppose you get paid on the 21st of the month +if it is a weekday, and to the Friday before if the 21st is on a +weekend. The diary entry + + &%%(let ((dayname (calendar-day-of-week date)) + (day (car (cdr date)))) + (or (and (= day 21) (memq dayname '(1 2 3 4 5))) + (and (memq day '(19 20)) (= dayname 5))) + ) Pay check deposited + +to just those dates. This example illustrates how the sexp can depend +on the variable `date'; this variable is a list (MONTH DAY YEAR) that +gives the Gregorian date for which the diary entries are being found. +If the value of the sexp is `t', the entry applies to that date. If +the sexp evaluates to `nil', the entry does _not_ apply to that date. + + +File: xemacs.info, Node: Calendar Customization, Prev: Diary, Up: Calendar/Diary + +Customizing the Calendar and Diary +---------------------------------- + +There are many customizations that you can use to make the calendar and +diary suit your personal tastes. + +* Menu: + +* Calendar Customizing:: Defaults you can set. +* Holiday Customizing:: Defining your own holidays. +* Date Display Format:: Changing the format. +* Time Display Format:: Changing the format. +* Daylight Savings:: Changing the default. +* Diary Customizing:: Defaults you can set. +* Hebrew/Islamic Entries:: How to obtain them. +* Fancy Diary Display:: Enhancing the diary display, sorting entries. +* Included Diary Files:: Sharing a common diary file. +* Sexp Diary Entries:: Fancy things you can do. +* Appt Customizing:: Customizing appointment reminders. + + +File: xemacs.info, Node: Calendar Customizing, Next: Holiday Customizing, Up: Calendar Customization + +Customizing the Calendar +........................ + +If you set the variable `view-diary-entries-initially' to `t', calling +up the calendar automatically displays the diary entries for the +current date as well. The diary dates appear only if the current date +is visible. If you add both of the following lines to your init file: + + (setq view-diary-entries-initially t) + (calendar) + +this displays both the calendar and diary windows whenever you start +Emacs. *Note Init File::. + + Similarly, if you set the variable +`view-calendar-holidays-initially' to `t', entering the calendar +automatically displays a list of holidays for the current three-month +period. The holiday list appears in a separate window. + + You can set the variable `mark-diary-entries-in-calendar' to `t' in +order to mark any dates with diary entries. This takes effect whenever +the calendar window contents are recomputed. There are two ways of +marking these dates: by changing the face (*note Faces::), if the +display supports that, or by placing a plus sign (`+') beside the date +otherwise. + + Similarly, setting the variable `mark-holidays-in-calendar' to `t' +marks holiday dates, either with a change of face or with an asterisk +(`*'). + + The variable `calendar-holiday-marker' specifies how to mark a date +as being a holiday. Its value may be a character to insert next to the +date, or a face name to use for displaying the date. Likewise, the +variable `diary-entry-marker' specifies how to mark a date that has +diary entries. The calendar creates faces named `holiday-face' and +`diary-face' for these purposes; those symbols are the default values +of these variables, when Emacs supports multiple faces on your terminal. + + The variable `calendar-load-hook' is a normal hook run when the +calendar package is first loaded (before actually starting to display +the calendar). + + Starting the calendar runs the normal hook +`initial-calendar-window-hook'. Recomputation of the calendar display +does not run this hook. But if you leave the calendar with the `q' +command and reenter it, the hook runs again. + + The variable `today-visible-calendar-hook' is a normal hook run +after the calendar buffer has been prepared with the calendar when the +current date is visible in the window. One use of this hook is to +replace today's date with asterisks; to do that, use the hook function +`calendar-star-date'. + + (add-hook 'today-visible-calendar-hook 'calendar-star-date) + +Another standard hook function marks the current date, either by +changing its face or by adding an asterisk. Here's how to use it: + + (add-hook 'today-visible-calendar-hook 'calendar-mark-today) + +The variable `calendar-today-marker' specifies how to mark today's +date. Its value should be a character to insert next to the date or a +face name to use for displaying the date. A face named +`calendar-today-face' is provided for this purpose; that symbol is the +default for this variable when Emacs supports multiple faces on your +terminal. + +A similar normal hook, `today-invisible-calendar-hook' is run if the +current date is _not_ visible in the window. + + +File: xemacs.info, Node: Holiday Customizing, Next: Date Display Format, Prev: Calendar Customizing, Up: Calendar Customization + +Customizing the Holidays +........................ + +Emacs knows about holidays defined by entries on one of several lists. +You can customize these lists of holidays to your own needs, adding or +deleting holidays. The lists of holidays that Emacs uses are for +general holidays (`general-holidays'), local holidays +(`local-holidays'), Christian holidays (`christian-holidays'), Hebrew +(Jewish) holidays (`hebrew-holidays'), Islamic (Moslem) holidays +(`islamic-holidays'), and other holidays (`other-holidays'). + + The general holidays are, by default, holidays common throughout the +United States. To eliminate these holidays, set `general-holidays' to +`nil'. + + There are no default local holidays (but sites may supply some). You +can set the variable `local-holidays' to any list of holidays, as +described below. + + By default, Emacs does not include all the holidays of the religions +that it knows, only those commonly found in secular calendars. For a +more extensive collection of religious holidays, you can set any (or +all) of the variables `all-christian-calendar-holidays', +`all-hebrew-calendar-holidays', or `all-islamic-calendar-holidays' to +`t'. If you want to eliminate the religious holidays, set any or all +of the corresponding variables `christian-holidays', `hebrew-holidays', +and `islamic-holidays' to `nil'. + + You can set the variable `other-holidays' to any list of holidays. +This list, normally empty, is intended for individual use. + + Each of the lists (`general-holidays', `local-holidays', +`christian-holidays', `hebrew-holidays', `islamic-holidays', and +`other-holidays') is a list of "holiday forms", each holiday form +describing a holiday (or sometimes a list of holidays). + + Here is a table of the possible kinds of holiday form. Day numbers +and month numbers count starting from 1, but "dayname" numbers count +Sunday as 0. The element STRING is always the name of the holiday, as +a string. + +`(holiday-fixed MONTH DAY STRING)' + A fixed date on the Gregorian calendar. MONTH and DAY are + numbers, STRING is the name of the holiday. + +`(holiday-float MONTH DAYNAME K STRING)' + The Kth DAYNAME in MONTH on the Gregorian calendar (DAYNAME=0 for + Sunday, and so on); negative K means count back from the end of + the month. STRING is the name of the holiday. + +`(holiday-hebrew MONTH DAY STRING)' + A fixed date on the Hebrew calendar. MONTH and DAY are numbers, + STRING is the name of the holiday. + +`(holiday-islamic MONTH DAY STRING)' + A fixed date on the Islamic calendar. MONTH and DAY are numbers, + STRING is the name of the holiday. + +`(holiday-julian MONTH DAY STRING)' + A fixed date on the Julian calendar. MONTH and DAY are numbers, + STRING is the name of the holiday. + +`(holiday-sexp SEXP STRING)' + A date calculated by the Lisp expression SEXP. The expression + should use the variable `year' to compute and return the date of a + holiday, or `nil' if the holiday doesn't happen this year. The + value of SEXP must represent the date as a list of the form + `(MONTH DAY YEAR)'. STRING is the name of the holiday. + +`(if CONDITION HOLIDAY-FORM &optional HOLIDAY-FORM)' + A holiday that happens only if CONDITION is true. + +`(FUNCTION [ARGS])' + A list of dates calculated by the function FUNCTION, called with + arguments ARGS. + + For example, suppose you want to add Bastille Day, celebrated in +France on July 14. You can do this by adding the following line to +your init file: + + (setq other-holidays '((holiday-fixed 7 14 "Bastille Day"))) + + *Note Init File::. + +The holiday form `(holiday-fixed 7 14 "Bastille Day")' specifies the +fourteenth day of the seventh month (July). + + Many holidays occur on a specific day of the week, at a specific time +of month. Here is a holiday form describing Hurricane Supplication Day, +celebrated in the Virgin Islands on the fourth Monday in August: + + (holiday-float 8 1 4 "Hurricane Supplication Day") + +Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, +Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in +the month (1 specifies the first occurrence, 2 the second occurrence, +-1 the last occurrence, -2 the second-to-last occurrence, and so on). + + You can specify holidays that occur on fixed days of the Hebrew, +Islamic, and Julian calendars too. For example, + + (setq other-holidays + '((holiday-hebrew 10 2 "Last day of Hanukkah") + (holiday-islamic 3 12 "Mohammed's Birthday") + (holiday-julian 4 2 "Jefferson's Birthday"))) + +adds the last day of Hanukkah (since the Hebrew months are numbered with +1 starting from Nisan), the Islamic feast celebrating Mohammed's +birthday (since the Islamic months are numbered from 1 starting with +Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the +Julian calendar. + + To include a holiday conditionally, use either Emacs Lisp's `if' or +the `holiday-sexp' form. For example, American presidential elections +occur on the first Tuesday after the first Monday in November of years +divisible by 4: + + (holiday-sexp (if (= 0 (% year 4)) + (calendar-gregorian-from-absolute + (1+ (calendar-dayname-on-or-before + 1 (+ 6 (calendar-absolute-from-gregorian + (list 11 1 year)))))) + "US Presidential Election")) + +or + + (if (= 0 (% displayed-year 4)) + (fixed 11 + (extract-calendar-day + (calendar-gregorian-from-absolute + (1+ (calendar-dayname-on-or-before + 1 (+ 6 (calendar-absolute-from-gregorian + (list 11 1 displayed-year))))))) + "US Presidential Election")) + + Some holidays just don't fit into any of these forms because special +calculations are involved in their determination. In such cases you +must write a Lisp function to do the calculation. To include eclipses, +for example, add `(eclipses)' to `other-holidays' and write an Emacs +Lisp function `eclipses' that returns a (possibly empty) list of the +relevant Gregorian dates among the range visible in the calendar +window, with descriptive strings, like this: + + (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... ) + + +File: xemacs.info, Node: Date Display Format, Next: Time Display Format, Prev: Holiday Customizing, Up: Calendar Customization + +Date Display Format +................... + +You can customize the manner of displaying dates in the diary, in mode +lines, and in messages by setting `calendar-date-display-form'. This +variable holds a list of expressions that can involve the variables +`month', `day', and `year', which are all numbers in string form, and +`monthname' and `dayname', which are both alphabetic strings. In the +American style, the default value of this list is as follows: + + ((if dayname (concat dayname ", ")) monthname " " day ", " year) + +while in the European style this value is the default: + + ((if dayname (concat dayname ", ")) day " " monthname " " year) + + + The ISO standard date representation is this: + + (year "-" month "-" day) + +This specifies a typical American format: + + (month "/" day "/" (substring year -2)) + + +File: xemacs.info, Node: Time Display Format, Next: Daylight Savings, Prev: Date Display Format, Up: Calendar Customization + +Time Display Format +................... + +The calendar and diary by default display times of day in the +conventional American style with the hours from 1 through 12, minutes, +and either `am' or `pm'. If you prefer the European style, also known +in the US as military, in which the hours go from 00 to 23, you can +alter the variable `calendar-time-display-form'. This variable is a +list of expressions that can involve the variables `12-hours', +`24-hours', and `minutes', which are all numbers in string form, and +`am-pm' and `time-zone', which are both alphabetic strings. The +default value of `calendar-time-display-form' is as follows: + + (12-hours ":" minutes am-pm + (if time-zone " (") time-zone (if time-zone ")")) + +Here is a value that provides European style times: + + (24-hours ":" minutes + (if time-zone " (") time-zone (if time-zone ")")) + +gives military-style times like `21:07 (UT)' if time zone names are +defined, and times like `21:07' if they are not. + + +File: xemacs.info, Node: Daylight Savings, Next: Diary Customizing, Prev: Time Display Format, Up: Calendar Customization + +Daylight Savings Time +..................... + +Emacs understands the difference between standard time and daylight +savings time--the times given for sunrise, sunset, solstices, +equinoxes, and the phases of the moon take that into account. The rules +for daylight savings time vary from place to place and have also varied +historically from year to year. To do the job properly, Emacs needs to +know which rules to use. + + Some operating systems keep track of the rules that apply to the +place where you are; on these systems, Emacs gets the information it +needs from the system automatically. If some or all of this +information is missing, Emacs fills in the gaps with the rules +currently used in Cambridge, Massachusetts. If the resulting rules are +not what you want, you can tell Emacs the rules to use by setting +certain variables. + + If the default choice of rules is not appropriate for your location, +you can tell Emacs the rules to use by setting the variables +`calendar-daylight-savings-starts' and +`calendar-daylight-savings-ends'. Their values should be Lisp +expressions that refer to the variable `year', and evaluate to the +Gregorian date on which daylight savings time starts or (respectively) +ends, in the form of a list `(MONTH DAY YEAR)'. The values should be +`nil' if your area does not use daylight savings time. + + Emacs uses these expressions to determine the starting date of +daylight savings time for the holiday list and for correcting times of +day in the solar and lunar calculations. + + The values for Cambridge, Massachusetts are as follows: + + (calendar-nth-named-day 1 0 4 year) + (calendar-nth-named-day -1 0 10 year) + +That is, the first 0th day (Sunday) of the fourth month (April) in the +year specified by `year', and the last Sunday of the tenth month +(October) of that year. If daylight savings time were changed to start +on October 1, you would set `calendar-daylight-savings-starts' to this: + + (list 10 1 year) + + For a more complex example, suppose daylight savings time begins on +the first of Nisan on the Hebrew calendar. You should set +`calendar-daylight-savings-starts' to this value: + + (calendar-gregorian-from-absolute + (calendar-absolute-from-hebrew + (list 1 1 (+ year 3760)))) + +because Nisan is the first month in the Hebrew calendar and the Hebrew +year differs from the Gregorian year by 3760 at Nisan. + + If there is no daylight savings time at your location, or if you want +all times in standard time, set `calendar-daylight-savings-starts' and +`calendar-daylight-savings-ends' to `nil'. + + The variable `calendar-daylight-time-offset' specifies the +difference between daylight savings time and standard time, measured in +minutes. The value for Cambridge, Massachusetts is 60. + + The two variables `calendar-daylight-savings-starts-time' and +`calendar-daylight-savings-ends-time' specify the number of minutes +after midnight local time when the transition to and from daylight +savings time should occur. For Cambridge, Massachusetts both variables' +values are 120. + + +File: xemacs.info, Node: Diary Customizing, Next: Hebrew/Islamic Entries, Prev: Daylight Savings, Up: Calendar Customization + +Customizing the Diary +..................... + +Ordinarily, the mode line of the diary buffer window indicates any +holidays that fall on the date of the diary entries. The process of +checking for holidays can take several seconds, so including holiday +information delays the display of the diary buffer noticeably. If you'd +prefer to have a faster display of the diary buffer but without the +holiday information, set the variable `holidays-in-diary-buffer' to +`nil'. + + The variable `number-of-diary-entries' controls the number of days +of diary entries to be displayed at one time. It affects the initial +display when `view-diary-entries-initially' is `t', as well as the +command `M-x diary'. For example, the default value is 1, which says +to display only the current day's diary entries. If the value is 2, +both the current day's and the next day's entries are displayed. The +value can also be a vector of seven elements: for example, if the value +is `[0 2 2 2 2 4 1]' then no diary entries appear on Sunday, the +current date's and the next day's diary entries appear Monday through +Thursday, Friday through Monday's entries appear on Friday, while on +Saturday only that day's entries appear. + + The variable `print-diary-entries-hook' is a normal hook run after +preparation of a temporary buffer containing just the diary entries +currently visible in the diary buffer. (The other, irrelevant diary +entries are really absent from the temporary buffer; in the diary +buffer, they are merely hidden.) The default value of this hook does +the printing with the command `lpr-buffer'. If you want to use a +different command to do the printing, just change the value of this +hook. Other uses might include, for example, rearranging the lines into +order by day and time. + + You can customize the form of dates in your diary file, if neither +the standard American nor European styles suits your needs, by setting +the variable `diary-date-forms'. This variable is a list of patterns +for recognizing a date. Each date pattern is a list whose elements may +be regular expressions (*note Regexps::) or the symbols `month', `day', +`year', `monthname', and `dayname'. All these elements serve as +patterns that match certain kinds of text in the diary file. In order +for the date pattern, as a whole, to match, all of its elements must +match consecutively. + + A regular expression in a date pattern matches in its usual fashion, +using the standard syntax table altered so that `*' is a word +constituent. + + The symbols `month', `day', `year', `monthname', and `dayname' match +the month number, day number, year number, month name, and day name of +the date being considered. The symbols that match numbers allow +leading zeros; those that match names allow three-letter abbreviations +and capitalization. All the symbols can match `*'; since `*' in a +diary entry means "any day", "any month", and so on, it should match +regardless of the date being considered. + + The default value of `diary-date-forms' in the American style is +this: + + ((month "/" day "[^/0-9]") + (month "/" day "/" year "[^0-9]") + (monthname " *" day "[^,0-9]") + (monthname " *" day ", *" year "[^0-9]") + (dayname "\\W")) + +Emacs matches of the diary entries with the date forms is done with the +standard syntax table from Fundamental mode (*note Syntax Tables: +(lispref)Syntax Tables.), but with the `*' changed so that it is a word +constituent. + + The date patterns in the list must be _mutually exclusive_ and must +not match any portion of the diary entry itself, just the date and one +character of whitespace. If, to be mutually exclusive, the pattern +must match a portion of the diary entry text--beyond the whitespace +that ends the date--then the first element of the date pattern _must_ +be `backup'. This causes the date recognizer to back up to the +beginning of the current word of the diary entry, after finishing the +match. Even if you use `backup', the date pattern must absolutely not +match more than a portion of the first word of the diary entry. The +default value of `diary-date-forms' in the European style is this list: + + ((day "/" month "[^/0-9]") + (day "/" month "/" year "[^0-9]") + (backup day " *" monthname "\\W+\\<[^*0-9]") + (day " *" monthname " *" year "[^0-9]") + (dayname "\\W")) + +Notice the use of `backup' in the third pattern, because it needs to +match part of a word beyond the date itself to distinguish it from the +fourth pattern. + + +File: xemacs.info, Node: Hebrew/Islamic Entries, Next: Fancy Diary Display, Prev: Diary Customizing, Up: Calendar Customization + +Hebrew- and Islamic-Date Diary Entries +...................................... + +Your diary file can have entries based on Hebrew or Islamic dates, as +well as entries based on the world-standard Gregorian calendar. +However, because recognition of such entries is time-consuming and most +people don't use them, you must explicitly enable their use. If you +want the diary to recognize Hebrew-date diary entries, for example, you +must do this: + + (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries) + (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries) + +If you want Islamic-date entries, do this: + + (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries) + (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries) + + Hebrew- and Islamic-date diary entries have the same formats as +Gregorian-date diary entries, except that `H' precedes a Hebrew date +and `I' precedes an Islamic date. Moreover, because the Hebrew and +Islamic month names are not uniquely specified by the first three +letters, you may not abbreviate them. For example, a diary entry for +the Hebrew date Heshvan 25 could look like this: + + HHeshvan 25 Happy Hebrew birthday! + +and would appear in the diary for any date that corresponds to Heshvan +25 on the Hebrew calendar. And here is Islamic-date diary entry that +matches Dhu al-Qada 25: + + IDhu al-Qada 25 Happy Islamic birthday! + +and would appear in the diary for any date that corresponds to Dhu +al-Qada 25 on the Islamic calendar. + + As with Gregorian-date diary entries, Hebrew- and Islamic-date +entries are nonmarking if they are preceded with an ampersand (`&'). + + Here is a table of commands used in the calendar to create diary +entries that match the selected date and other dates that are similar +in the Hebrew or Islamic calendar: + +`i h d' + Add a diary entry for the Hebrew date corresponding to the + selected date (`insert-hebrew-diary-entry'). + +`i h m' + Add a diary entry for the day of the Hebrew month corresponding to + the selected date (`insert-monthly-hebrew-diary-entry'). This + diary entry matches any date that has the same Hebrew + day-within-month as the selected date. + +`i h y' + Add a diary entry for the day of the Hebrew year corresponding to + the selected date (`insert-yearly-hebrew-diary-entry'). This diary + entry matches any date which has the same Hebrew month and + day-within-month as the selected date. + +`i i d' + Add a diary entry for the Islamic date corresponding to the + selected date (`insert-islamic-diary-entry'). + +`i i m' + Add a diary entry for the day of the Islamic month corresponding + to the selected date (`insert-monthly-islamic-diary-entry'). + +`i i y' + Add a diary entry for the day of the Islamic year corresponding to + the selected date (`insert-yearly-islamic-diary-entry'). + + These commands work much like the corresponding commands for ordinary +diary entries: they apply to the date that point is on in the calendar +window, and what they do is insert just the date portion of a diary +entry at the end of your diary file. You must then insert the rest of +the diary entry. + + +File: xemacs.info, Node: Fancy Diary Display, Next: Included Diary Files, Prev: Hebrew/Islamic Entries, Up: Calendar Customization + +Fancy Diary Display +................... + +Diary display works by preparing the diary buffer and then running the +hook `diary-display-hook'. The default value of this hook +(`simple-diary-display') hides the irrelevant diary entries and then +displays the buffer. However, if you specify the hook as follows, + + (add-hook 'diary-display-hook 'fancy-diary-display) + +this enables fancy diary display. It displays diary entries and +holidays by copying them into a special buffer that exists only for the +sake of display. Copying to a separate buffer provides an opportunity +to change the displayed text to make it prettier--for example, to sort +the entries by the dates they apply to. + + As with simple diary display, you can print a hard copy of the buffer +with `print-diary-entries'. To print a hard copy of a day-by-day diary +for a week by positioning point on Sunday of that week, type `7 d' and +then do `M-x print-diary-entries'. As usual, the inclusion of the +holidays slows down the display slightly; you can speed things up by +setting the variable `holidays-in-diary-buffer' to `nil'. + + Ordinarily, the fancy diary buffer does not show days for which +there are no diary entries, even if that day is a holiday. If you want +such days to be shown in the fancy diary buffer, set the variable +`diary-list-include-blanks' to `t'. + + If you use the fancy diary display, you can use the normal hook +`list-diary-entries-hook' to sort each day's diary entries by their +time of day. Add this line to your init file: + + (add-hook 'list-diary-entries-hook 'sort-diary-entries t) + + *Note Init File::. + +For each day, this sorts diary entries that begin with a recognizable +time of day according to their times. Diary entries without times come +first within each day. + + +File: xemacs.info, Node: Included Diary Files, Next: Sexp Diary Entries, Prev: Fancy Diary Display, Up: Calendar Customization + +Included Diary Files +.................... + +Fancy diary display also has the ability to process included diary +files. This permits a group of people to share a diary file for events +that apply to all of them. Lines in the diary file of this form: + + #include "FILENAME" + +includes the diary entries from the file FILENAME in the fancy diary +buffer. The include mechanism is recursive, so that included files can +include other files, and so on; you must be careful not to have a cycle +of inclusions, of course. Here is how to enable the include facility: + + (add-hook 'list-diary-entries-hook 'include-other-diary-files) + (add-hook 'mark-diary-entries-hook 'mark-included-diary-files) + + The include mechanism works only with the fancy diary display, +because ordinary diary display shows the entries directly from your +diary file. + + +File: xemacs.info, Node: Sexp Diary Entries, Next: Appt Customizing, Prev: Included Diary Files, Up: Calendar Customization + +Sexp Entries and the Fancy Diary Display +........................................ + +Sexp diary entries allow you to do more than just have complicated +conditions under which a diary entry applies. If you use the fancy +diary display, sexp entries can generate the text of the entry depending +on the date itself. For example, an anniversary diary entry can insert +the number of years since the anniversary date into the text of the +diary entry. Thus the `%d' in this dairy entry: + + %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) + +gets replaced by the age, so on October 31, 1990 the entry appears in +the fancy diary buffer like this: + + Arthur's birthday (42 years old) + +If the diary file instead contains this entry: + + %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday + +the entry in the fancy diary buffer for October 31, 1990 appears like +this: + + Arthur's 42nd birthday + + Similarly, cyclic diary entries can interpolate the number of +repetitions that have occurred: + + %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time) + +looks like this: + + Renew medication (5th time) + +in the fancy diary display on September 8, 1990. + + The generality of sexp diary entries lets you specify any diary entry +that you can describe algorithmically. A sexp diary entry contains an +expression that computes whether the entry applies to any given date. +If its value is non-`nil', the entry applies to that date; otherwise, +it does not. The expression can use the variable `date' to find the +date being considered; its value is a list (MONTH DAY YEAR) that refers +to the Gregorian calendar. + + Suppose you get paid on the 21st of the month if it is a weekday, and +on the Friday before if the 21st is on a weekend. Here is how to write +a sexp diary entry that matches those dates: + + &%%(let ((dayname (calendar-day-of-week date)) + (day (car (cdr date)))) + (or (and (= day 21) (memq dayname '(1 2 3 4 5))) + (and (memq day '(19 20)) (= dayname 5))) + ) Pay check deposited + +applies to just those dates. This example illustrates how the sexp can +depend on the variable `date'; this variable is a list (MONTH DAY YEAR) +that gives the Gregorian date for which the diary entries are being +found. If the value of the expression is `t', the entry applies to +that date. If the expression evaluates to `nil', the entry does _not_ +apply to that date. + + The following sexp diary entries take advantage of the ability (in +the fancy diary display) to concoct diary entries whose text varies +based on the date: + +`%%(diary-sunrise-sunset)' + Make a diary entry for the local times of today's sunrise and + sunset. + +`%%(diary-phases-of-moon)' + Make a diary entry for the phases (quarters) of the moon. + +`%%(diary-day-of-year)' + Make a diary entry with today's day number in the current year and + the number of days remaining in the current year. + +`%%(diary-iso-date)' + Make a diary entry with today's equivalent ISO commercial date. + +`%%(diary-julian-date)' + Make a diary entry with today's equivalent date on the Julian + calendar. + +`%%(diary-astro-day-number)' + Make a diary entry with today's equivalent astronomical (Julian) + day number. + +`%%(diary-hebrew-date)' + Make a diary entry with today's equivalent date on the Hebrew + calendar. + +`%%(diary-islamic-date)' + Make a diary entry with today's equivalent date on the Islamic + calendar. + +`%%(diary-french-date)' + Make a diary entry with today's equivalent date on the French + Revolutionary calendar. + +`%%(diary-mayan-date)' + Make a diary entry with today's equivalent date on the Mayan + calendar. + +Thus including the diary entry + + &%%(diary-hebrew-date) + +causes every day's diary display to contain the equivalent date on the +Hebrew calendar, if you are using the fancy diary display. (With simple +diary display, the line `&%%(diary-hebrew-date)' appears in the diary +for any date, but does nothing particularly useful.) + + These functions can be used to construct sexp diary entries based on +the Hebrew calendar in certain standard ways: + +`%%(diary-rosh-hodesh)' + Make a diary entry that tells the occurrence and ritual + announcement of each new Hebrew month. + +`%%(diary-parasha)' + Make a Saturday diary entry that tells the weekly synagogue + scripture reading. + +`%%(diary-sabbath-candles)' + Make a Friday diary entry that tells the _local time_ of Sabbath + candle lighting. + +`%%(diary-omer)' + Make a diary entry that gives the omer count, when appropriate. + +`%%(diary-yahrzeit MONTH DAY YEAR) NAME' + Make a diary entry marking the anniversary of a date of death. + The date is the _Gregorian_ (civil) date of death. The diary + entry appears on the proper Hebrew calendar anniversary and on the + day before. (In the European style, the order of the parameters + is changed to DAY, MONTH, YEAR.) + + +File: xemacs.info, Node: Appt Customizing, Prev: Sexp Diary Entries, Up: Calendar Customization + +Customizing Appointment Reminders +................................. + +You can specify exactly how Emacs reminds you of an appointment, and +how far in advance it begins doing so, by setting these variables: + +`appt-message-warning-time' + The time in minutes before an appointment that the reminder + begins. The default is 10 minutes. + +`appt-audible' + If this is `t' (the default), Emacs rings the terminal bell for + appointment reminders. + +`appt-visible' + If this is `t' (the default), Emacs displays the appointment + message in echo area. + +`appt-display-mode-line' + If this is `t' (the default), Emacs displays the number of minutes + to the appointment on the mode line. + +`appt-msg-window' + If this is `t' (the default), Emacs displays the appointment + message in another window. + +`appt-display-duration' + The number of seconds an appointment message is displayed. The + default is 5 seconds. + + +File: xemacs.info, Node: Sorting, Next: Shell, Prev: Calendar/Diary, Up: Top + +Sorting Text +============ + +XEmacs provides several commands for sorting text in a buffer. All +operate on the contents of the region (the text between point and the +mark). They divide the text of the region into many "sort records", +identify a "sort key" for each record, and then reorder the records +using the order determined by the sort keys. The records are ordered so +that their keys are in alphabetical order, or, for numerical sorting, in +numerical order. In alphabetical sorting, all upper-case letters `A' +through `Z' come before lower-case `a', in accordance with the ASCII +character sequence. + + The sort commands differ in how they divide the text into sort +records and in which part of each record they use as the sort key. +Most of the commands make each line a separate sort record, but some +commands use paragraphs or pages as sort records. Most of the sort +commands use each entire sort record as its own sort key, but some use +only a portion of the record as the sort key. + +`M-x sort-lines' + Divide the region into lines and sort by comparing the entire text + of a line. A prefix argument means sort in descending order. + +`M-x sort-paragraphs' + Divide the region into paragraphs and sort by comparing the entire + text of a paragraph (except for leading blank lines). A prefix + argument means sort in descending order. + +`M-x sort-pages' + Divide the region into pages and sort by comparing the entire text + of a page (except for leading blank lines). A prefix argument + means sort in descending order. + +`M-x sort-fields' + Divide the region into lines and sort by comparing the contents of + one field in each line. Fields are defined as separated by + whitespace, so the first run of consecutive non-whitespace + characters in a line constitutes field 1, the second such run + constitutes field 2, etc. + + You specify which field to sort by with a numeric argument: 1 to + sort by field 1, etc. A negative argument means sort in descending + order. Thus, minus 2 means sort by field 2 in reverse-alphabetical + order. + +`M-x sort-numeric-fields' + Like `M-x sort-fields', except the specified field is converted to + a number for each line and the numbers are compared. `10' comes + before `2' when considered as text, but after it when considered + as a number. + +`M-x sort-columns' + Like `M-x sort-fields', except that the text within each line used + for comparison comes from a fixed range of columns. An explanation + is given below. + + For example, if the buffer contains: + + On systems where clash detection (locking of files being edited) is + implemented, XEmacs also checks the first time you modify a buffer + whether the file has changed on disk since it was last visited or + saved. If it has, you are asked to confirm that you want to change + the buffer. + +then if you apply `M-x sort-lines' to the entire buffer you get: + + On systems where clash detection (locking of files being edited) is + implemented, XEmacs also checks the first time you modify a buffer + saved. If it has, you are asked to confirm that you want to change + the buffer. + whether the file has changed on disk since it was last visited or + +where the upper case `O' comes before all lower case letters. If you +apply instead `C-u 2 M-x sort-fields' you get: + + saved. If it has, you are asked to confirm that you want to change + implemented, XEmacs also checks the first time you modify a buffer + the buffer. + On systems where clash detection (locking of files being edited) is + whether the file has changed on disk since it was last visited or + +where the sort keys were `If', `XEmacs', `buffer', `systems', and `the'. + + `M-x sort-columns' requires more explanation. You specify the +columns by putting point at one of the columns and the mark at the other +column. Because this means you cannot put point or the mark at the +beginning of the first line to sort, this command uses an unusual +definition of `region': all of the line point is in is considered part +of the region, and so is all of the line the mark is in. + + For example, to sort a table by information found in columns 10 to +15, you could put the mark on column 10 in the first line of the table, +and point on column 15 in the last line of the table, and then use this +command. Or you could put the mark on column 15 in the first line and +point on column 10 in the last line. + + This can be thought of as sorting the rectangle specified by point +and the mark, except that the text on each line to the left or right of +the rectangle moves along with the text inside the rectangle. *Note +Rectangles::. + + +File: xemacs.info, Node: Shell, Next: Narrowing, Prev: Sorting, Up: Top + +Running Shell Commands from XEmacs +================================== + +XEmacs has commands for passing single command lines to inferior shell +processes; it can also run a shell interactively with input and output +to an XEmacs buffer `*shell*'. + +`M-!' + Run a specified shell command line and display the output + (`shell-command'). + +`M-|' + Run a specified shell command line with region contents as input; + optionally replace the region with the output + (`shell-command-on-region'). + +`M-x shell' + Run a subshell with input and output through an XEmacs buffer. + You can then give commands interactively. + +`M-x term' + Run a subshell with input and output through an XEmacs buffer. + You can then give commands interactively. Full terminal emulation + is available. + +* Menu: + +* Single Shell:: How to run one shell command and return. +* Interactive Shell:: Permanent shell taking input via XEmacs. +* Shell Mode:: Special XEmacs commands used with permanent shell. +* Terminal emulator:: An XEmacs window as a terminal emulator. +* Term Mode:: Special XEmacs commands used in Term mode. +* Paging in Term:: Paging in the terminal emulator. + + +File: xemacs.info, Node: Single Shell, Next: Interactive Shell, Prev: Shell, Up: Shell + +Single Shell Commands +--------------------- + +`M-!' (`shell-command') reads a line of text using the minibuffer and +creates an inferior shell to execute the line as a command. Standard +input from the command comes from the null device. If the shell +command produces any output, the output goes to an XEmacs buffer named +`*Shell Command Output*', which is displayed in another window but not +selected. A numeric argument, as in `M-1 M-!', directs this command to +insert any output into the current buffer. In that case, point is left +before the output and the mark is set after the output. + + `M-|' (`shell-command-on-region') is like `M-!' but passes the +contents of the region as input to the shell command, instead of no +input. If a numeric argument is used to direct output to the current +buffer, then the old region is deleted first and the output replaces it +as the contents of the region. + + Both `M-!' and `M-|' use `shell-file-name' to specify the shell to +use. This variable is initialized based on your `SHELL' environment +variable when you start XEmacs. If the file name does not specify a +directory, the directories in the list `exec-path' are searched; this +list is initialized based on the `PATH' environment variable when you +start XEmacs. You can override either or both of these default +initializations in your init file. *Note Init File::. + + When you use `M-!' and `M-|', XEmacs has to wait until the shell +command completes. You can quit with `C-g'; that terminates the shell +command. + + +File: xemacs.info, Node: Interactive Shell, Next: Shell Mode, Prev: Single Shell, Up: Shell + +Interactive Inferior Shell +-------------------------- + +To run a subshell interactively with its typescript in an XEmacs +buffer, use `M-x shell'. This creates (or reuses) a buffer named +`*shell*' and runs a subshell with input coming from and output going +to that buffer. That is to say, any "terminal output" from the subshell +will go into the buffer, advancing point, and any "terminal input" for +the subshell comes from text in the buffer. To give input to the +subshell, go to the end of the buffer and type the input, terminated by +. + + XEmacs does not wait for the subshell to do anything. You can switch +windows or buffers and edit them while the shell is waiting, or while +it is running a command. Output from the subshell waits until XEmacs +has time to process it; this happens whenever XEmacs is waiting for +keyboard input or for time to elapse. + + To get multiple subshells, change the name of buffer `*shell*' to +something different by using `M-x rename-buffer'. The next use of `M-x +shell' creates a new buffer `*shell*' with its own subshell. By +renaming this buffer as well you can create a third one, and so on. +All the subshells run independently and in parallel. + + The file name used to load the subshell is the value of the variable +`explicit-shell-file-name', if that is non-`nil'. Otherwise, the +environment variable `ESHELL' is used, or the environment variable +`SHELL' if there is no `ESHELL'. If the file name specified is +relative, the directories in the list `exec-path' are searched (*note +Single Shell Commands: Single Shell.). + + As soon as the subshell is started, it is sent as input the contents +of the file `~/.emacs_SHELLNAME', if that file exists, where SHELLNAME +is the name of the file that the shell was loaded from. For example, +if you use `csh', the file sent to it is `~/.emacs_csh'. + + `cd', `pushd', and `popd' commands given to the inferior shell are +watched by XEmacs so it can keep the `*shell*' buffer's default +directory the same as the shell's working directory. These commands +are recognized syntactically by examining lines of input that are sent. +If you use aliases for these commands, you can tell XEmacs to +recognize them also. For example, if the value of the variable +`shell-pushd-regexp' matches the beginning of a shell command line, +that line is regarded as a `pushd' command. Change this variable when +you add aliases for `pushd'. Likewise, `shell-popd-regexp' and +`shell-cd-regexp' are used to recognize commands with the meaning of +`popd' and `cd'. + + `M-x shell-resync-dirs' queries the shell and resynchronizes XEmacs' +idea of what the current directory stack is. `M-x +shell-dirtrack-toggle' turns directory tracking on and off. + + XEmacs keeps a history of the most recent commands you have typed in +the `*shell*' buffer. If you are at the beginning of a shell command +line and type , the previous shell input is inserted into the +buffer before point. Immediately typing again deletes that input +and inserts the one before it. By repeating you can move +backward through your commands until you find one you want to repeat. +You may then edit the command before typing if you wish. +moves forward through the command history, in case you moved backward +past the one you wanted while using . If you type the first few +characters of a previous command and then type , the most recent +shell input starting with those characters is inserted. This can be +very convenient when you are repeating a sequence of shell commands. +The variable `input-ring-size' controls how many commands are saved in +your input history. The default is 30. + + +File: xemacs.info, Node: Shell Mode, Next: Terminal emulator, Prev: Interactive Shell, Up: Shell + +Shell Mode +---------- + +The shell buffer uses Shell mode, which defines several special keys +attached to the `C-c' prefix. They are chosen to resemble the usual +editing and job control characters present in shells that are not under +XEmacs, except that you must type `C-c' first. Here is a list of the +special key bindings of Shell mode: + +`' + At end of buffer send line as input; otherwise, copy current line + to end of buffer and send it (`send-shell-input'). When a line is + copied, any text at the beginning of the line that matches the + variable `shell-prompt-pattern' is left out; this variable's value + should be a regexp string that matches the prompts that you use in + your subshell. + +`C-c C-d' + Send end-of-file as input, probably causing the shell or its + current subjob to finish (`shell-send-eof'). + +`C-d' + If point is not at the end of the buffer, delete the next + character just like most other modes. If point is at the end of + the buffer, send end-of-file as input, instead of generating an + error as in other modes (`comint-delchar-or-maybe-eof'). + +`C-c C-u' + Kill all text that has yet to be sent as input + (`kill-shell-input'). + +`C-c C-w' + Kill a word before point (`backward-kill-word'). + +`C-c C-c' + Interrupt the shell or its current subjob if any + (`interrupt-shell-subjob'). + +`C-c C-z' + Stop the shell or its current subjob if any (`stop-shell-subjob'). + +`C-c C-\' + Send quit signal to the shell or its current subjob if any + (`quit-shell-subjob'). + +`C-c C-o' + Delete last batch of output from shell (`kill-output-from-shell'). + +`C-c C-r' + Scroll top of last batch of output to top of window + (`show-output-from-shell'). + +`C-c C-y' + Copy the previous bunch of shell input and insert it into the + buffer before point (`copy-last-shell-input'). No final newline + is inserted, and the input copied is not resubmitted until you type + . + +`M-p' + Move backward through the input history. Search for a matching + command if you have typed the beginning of a command + (`comint-previous-input'). + +`M-n' + Move forward through the input history. Useful when you are using + quickly and go past the desired command + (`comint-next-input'). + +`' + Complete the file name preceding point (`comint-dynamic-complete'). + + +File: xemacs.info, Node: Terminal emulator, Next: Term Mode, Prev: Shell Mode, Up: Shell + +Interactive Inferior Shell with Terminal Emulator +------------------------------------------------- + +To run a subshell in a terminal emulator, putting its typescript in an +XEmacs buffer, use `M-x term'. This creates (or reuses) a buffer named +`*term*' and runs a subshell with input coming from your keyboard and +output going to that buffer. + + All the normal keys that you type are sent without any interpretation +by XEmacs directly to the subshell, as "terminal input." Any "echo" of +your input is the responsibility of the subshell. (The exception is +the terminal escape character, which by default is `C-c'. *note Term +Mode::.) Any "terminal output" from the subshell goes into the buffer, +advancing point. + + Some programs (such as XEmacs itself) need to control the appearance +on the terminal screen in detail. They do this by sending special +control codes. The exact control codes needed vary from terminal to +terminal, but nowadays most terminals and terminal emulators (including +xterm) understand the so-called "ANSI escape sequences" (first +popularized by the Digital's VT100 family of terminal). The term mode +also understands these escape sequences, and for each control code does +the appropriate thing to change the buffer so that the appearance of +the window will match what it would be on a real terminal. Thus you +can actually run XEmacs inside an XEmacs Term window! + + XEmacs does not wait for the subshell to do anything. You can switch +windows or buffers and edit them while the shell is waiting, or while +it is running a command. Output from the subshell waits until XEmacs +has time to process it; this happens whenever XEmacs is waiting for +keyboard input or for time to elapse. + + To make multiple terminal emulators, rename the buffer `*term*' to +something different using `M-x rename-uniquely', just as with Shell +mode. + + The file name used to load the subshell is determined the same way +as for Shell mode. + + Unlike Shell mode, Term mode does not track the current directory by +examining your input. Instead, if you use a programmable shell, you +can have it tell Term what the current directory is. This is done +automatically by bash for version 1.15 and later. + + +File: xemacs.info, Node: Term Mode, Next: Paging in Term, Prev: Terminal emulator, Up: Shell + +Term Mode +--------- + +Term uses Term mode, which has two input modes: In line mode, Term +basically acts like Shell mode. *Note Shell Mode::. In Char mode, +each character is sent directly to the inferior subshell, except for +the Term escape character, normally `C-c'. + + To switch between line and char mode, use these commands: + findex term-char-mode + +`C-c C-j' + Switch to line mode. Do nothing if already in line mode. + +`C-c C-k' + Switch to char mode. Do nothing if already in char mode. + + The following commands are only available in Char mode: +`C-c C-c' + Send a literal to the sub-shell. + +`C-c C-x' + A prefix command to conveniently access the global commands. + For example, `C-c C-x o' invokes the global binding of `C-x o', + which is normally `other-window'. + + +File: xemacs.info, Node: Paging in Term, Prev: Term Mode, Up: Shell + +Paging in the terminal emulator +------------------------------- + +Term mode has a pager feature. When the pager is enabled, term mode +will pause at the end of each screenful. + +`C-c C-q' + Toggles the pager feature: Disables the pager if it is enabled, + and vice versa. This works in both line and char modes. If the + pager enabled, the mode-line contains the word `page'. + + If the pager is enabled, and Term receives more than a screenful of +output since your last input, Term will enter More break mode. This is +indicated by `**MORE**' in the mode-line. Type a `Space' to display +the next screenful of output. Type `?' to see your other options. The +interface is similar to the Unix `more' program. + + +File: xemacs.info, Node: Narrowing, Next: Hardcopy, Prev: Shell, Up: Top + +Narrowing +========= + +"Narrowing" means focusing in on some portion of the buffer, making the +rest temporarily invisible and inaccessible. Cancelling the narrowing +and making the entire buffer once again visible is called "widening". +The amount of narrowing in effect in a buffer at any time is called the +buffer's "restriction". + +`C-x n n' + Narrow down to between point and mark (`narrow-to-region'). + +`C-x n w' + Widen to make the entire buffer visible again (`widen'). + + Narrowing sometimes makes it easier to concentrate on a single +subroutine or paragraph by eliminating clutter. It can also be used to +restrict the range of operation of a replace command or repeating +keyboard macro. The word `Narrow' appears in the mode line whenever +narrowing is in effect. When you have narrowed to a part of the +buffer, that part appears to be all there is. You can't see the rest, +can't move into it (motion commands won't go outside the visible part), +and can't change it in any way. However, the invisible text is not +gone; if you save the file, it will be saved. + + The primary narrowing command is `C-x n n' (`narrow-to-region'). It +sets the current buffer's restrictions so that the text in the current +region remains visible but all text before the region or after the +region is invisible. Point and mark do not change. + + Because narrowing can easily confuse users who do not understand it, +`narrow-to-region' is normally a disabled command. Attempting to use +this command asks for confirmation and gives you the option of enabling +it; once you enable the command, confirmation will no longer be +required. *Note Disabling::. + + To undo narrowing, use `C-x n w' (`widen'). This makes all text in +the buffer accessible again. + + Use the `C-x =' command to get information on what part of the +buffer you narrowed down. *Note Position Info::. + + +File: xemacs.info, Node: Hardcopy, Next: Recursive Edit, Prev: Narrowing, Up: Top + +Hardcopy Output +=============== + +The XEmacs commands for making hardcopy derive their names from the +Unix commands `print' and `lpr'. + +`M-x print-buffer' + Print hardcopy of current buffer using Unix command `print' + (`lpr -p'). This command adds page headings containing the file + name and page number. + +`M-x lpr-buffer' + Print hardcopy of current buffer using Unix command `lpr'. This + command does not add page headings. + +`M-x print-region' + Like `print-buffer', but prints only the current region. + +`M-x lpr-region' + Like `lpr-buffer', but prints only the current region. + + All the hardcopy commands pass extra switches to the `lpr' program +based on the value of the variable `lpr-switches'. Its value should be +a list of strings, each string a switch starting with `-'. For +example, the value could be `("-Pfoo")' to print on printer `foo'. + + +File: xemacs.info, Node: Recursive Edit, Next: Dissociated Press, Prev: Hardcopy, Up: Top + +Recursive Editing Levels +======================== + +A "recursive edit" is a situation in which you are using XEmacs +commands to perform arbitrary editing while in the middle of another +XEmacs command. For example, when you type `C-r' inside a +`query-replace', you enter a recursive edit in which you can change the +current buffer. When you exit from the recursive edit, you go back to +the `query-replace'. + + "Exiting" a recursive edit means returning to the unfinished +command, which continues execution. For example, exiting the recursive +edit requested by `C-r' in `query-replace' causes query replacing to +resume. Exiting is done with `C-M-c' (`exit-recursive-edit'). + + You can also "abort" a recursive edit. This is like exiting, but +also quits the unfinished command immediately. Use the command `C-]' +(`abort-recursive-edit') for this. *Note Quitting::. + + The mode line shows you when you are in a recursive edit by +displaying square brackets around the parentheses that always surround +the major and minor mode names. Every window's mode line shows the +square brackets, since XEmacs as a whole, rather than any particular +buffer, is in a recursive edit. + + It is possible to be in recursive edits within recursive edits. For +example, after typing `C-r' in a `query-replace', you might type a +command that entered the debugger. In such a case, two or more sets of +square brackets appear in the mode line(s). Exiting the inner +recursive edit (here with the debugger `c' command) resumes the +query-replace command where it called the debugger. After the end of +the query-replace command, you would be able to exit the first +recursive edit. Aborting exits only one level of recursive edit; it +returns to the command level of the previous recursive edit. You can +then abort that one as well. + + The command `M-x top-level' aborts all levels of recursive edits, +returning immediately to the top level command reader. + + The text you edit inside the recursive edit need not be the same text +that you were editing at top level. If the command that invokes the +recursive edit selects a different buffer first, that is the buffer you +will edit recursively. You can switch buffers within the recursive edit +in the normal manner (as long as the buffer-switching keys have not been +rebound). While you could theoretically do the rest of your editing +inside the recursive edit, including visiting files, this could have +surprising effects (such as stack overflow) from time to time. It is +best if you always exit or abort a recursive edit when you no longer +need it. + + In general, XEmacs tries to avoid using recursive edits. It is +usually preferable to allow users to switch among the possible editing +modes in any order they like. With recursive edits, the only way to get +to another state is to go "back" to the state that the recursive edit +was invoked from. + + +File: xemacs.info, Node: Dissociated Press, Next: CONX, Prev: Recursive Edit, Up: Top + +Dissociated Press +================= + +`M-x dissociated-press' is a command for scrambling a file of text +either word by word or character by character. Starting from a buffer +of straight English, it produces extremely amusing output. The input +comes from the current XEmacs buffer. Dissociated Press writes its +output in a buffer named `*Dissociation*', and redisplays that buffer +after every couple of lines (approximately) to facilitate reading it. + + `dissociated-press' asks every so often whether to continue +operating. Answer `n' to stop it. You can also stop at any time by +typing `C-g'. The dissociation output remains in the `*Dissociation*' +buffer for you to copy elsewhere if you wish. + + Dissociated Press operates by jumping at random from one point in the +buffer to another. In order to produce plausible output rather than +gibberish, it insists on a certain amount of overlap between the end of +one run of consecutive words or characters and the start of the next. +That is, if it has just printed out `president' and then decides to +jump to a different point in the file, it might spot the `ent' in +`pentagon' and continue from there, producing `presidentagon'. Long +sample texts produce the best results. + + A positive argument to `M-x dissociated-press' tells it to operate +character by character, and specifies the number of overlap characters. +A negative argument tells it to operate word by word and specifies the +number of overlap words. In this mode, whole words are treated as the +elements to be permuted, rather than characters. No argument is +equivalent to an argument of two. For your againformation, the output +goes only into the buffer `*Dissociation*'. The buffer you start with +is not changed. + + Dissociated Press produces nearly the same results as a Markov chain +based on a frequency table constructed from the sample text. It is, +however, an independent, ignoriginal invention. Dissociated Press +techniquitously copies several consecutive characters from the sample +between random choices, whereas a Markov chain would choose randomly for +each word or character. This makes for more plausible sounding results +and runs faster. + + It is a mustatement that too much use of Dissociated Press can be a +developediment to your real work. Sometimes to the point of outragedy. +And keep dissociwords out of your documentation, if you want it to be +well userenced and properbose. Have fun. Your buggestions are welcome. + + +File: xemacs.info, Node: CONX, Next: Amusements, Prev: Dissociated Press, Up: Top + +CONX +==== + +Besides producing a file of scrambled text with Dissociated Press, you +can generate random sentences by using CONX. + +`M-x conx' + Generate random sentences in the `*conx*' buffer. + +`M-x conx-buffer' + Absorb the text in the current buffer into the `conx' database. + +`M-x conx-init' + Forget the current word-frequency tree. + +`M-x conx-load' + Load a `conx' database that has been previously saved with `M-x + conx-save'. + +`M-x conx-region' + Absorb the text in the current buffer into the `conx' database. + +`M-x conx-save' + Save the current `conx' database to a file for future retrieval. + + Copy text from a buffer using `M-x conx-buffer' or `M-x conx-region' +and then type `M-x conx'. Output is continuously generated until you +type <^G>. You can save the `conx' database to a file with `M-x +conx-save', which you can retrieve with `M-x conx-load'. To clear the +database, use `M-x conx-init'. + + +File: xemacs.info, Node: Amusements, Next: Emulation, Prev: CONX, Up: Top + +Other Amusements +================ + +If you are a little bit bored, you can try `M-x hanoi'. If you are +considerably bored, give it a numeric argument. If you are very, very +bored, try an argument of 9. Sit back and watch. + + When you are frustrated, try the famous Eliza program. Just do `M-x +doctor'. End each input by typing `RET' twice. + + When you are feeling strange, type `M-x yow'. + + +File: xemacs.info, Node: Emulation, Next: Customization, Prev: Amusements, Up: Top + +Emulation +========= + +XEmacs can be programmed to emulate (more or less) most other editors. +Standard facilities can emulate these: + +Viper (a vi emulator) + In XEmacs, Viper is the preferred emulation of vi within XEmacs. + Viper is designed to allow you to take advantage of the best + features of XEmacs while still doing your basic editing in a + familiar, vi-like fashion. Viper provides various different + levels of vi emulation, from a quite complete emulation that + allows almost no access to native XEmacs commands, to an "expert" + mode that combines the most useful vi commands with the most + useful XEmacs commands. + + To start Viper, put the command + + (viper-mode) + + in your init file. *Note Init File::. + + Viper comes with a separate manual that is provided standard with + the XEmacs distribution. + +EDT (DEC VMS editor) + Turn on EDT emulation with `M-x edt-emulation-on'. `M-x + edt-emulation-off' restores normal Emacs command bindings. + + Most of the EDT emulation commands are keypad keys, and most + standard Emacs key bindings are still available. The EDT + emulation rebindings are done in the global keymap, so there is no + problem switching buffers or major modes while in EDT emulation. + +Gosling Emacs + Turn on emulation of Gosling Emacs (aka Unipress Emacs) with `M-x + set-gosmacs-bindings'. This redefines many keys, mostly on the + `C-x' and `ESC' prefixes, to work as they do in Gosmacs. `M-x + set-gnu-bindings' returns to normal XEmacs by rebinding the same + keys to the definitions they had at the time `M-x + set-gosmacs-bindings' was done. + + It is also possible to run Mocklisp code written for Gosling Emacs. + *Note Mocklisp::. + + +File: xemacs.info, Node: Customization, Next: Quitting, Prev: Emulation, Up: Top + +Customization +************* + +This chapter talks about various topics relevant to adapting the +behavior of Emacs in minor ways. + + All kinds of customization affect only the particular Emacs job that +you do them in. They are completely lost when you kill the Emacs job, +and have no effect on other Emacs jobs you may run at the same time or +later. The only way an Emacs job can affect anything outside of it is +by writing a file; in particular, the only way to make a customization +`permanent' is to put something in your init file or other appropriate +file to do the customization in each session. *Note Init File::. + +* Menu: + +* Minor Modes:: Each minor mode is one feature you can turn on + independently of any others. +* Variables:: Many Emacs commands examine Emacs variables + to decide what to do; by setting variables, + you can control their functioning. +* Keyboard Macros:: A keyboard macro records a sequence of keystrokes + to be replayed with a single command. +* Key Bindings:: The keymaps say what command each key runs. + By changing them, you can "redefine keys". +* Syntax:: The syntax table controls how words and expressions + are parsed. +* Init File:: How to write common customizations in the init file. +* Audible Bell:: Changing how Emacs sounds the bell. +* Faces:: Changing the fonts and colors of a region of text. +* Frame Components:: Controlling the presence and positions of the + menubar, toolbars, and gutters. +* X Resources:: X resources controlling various aspects of the + behavior of XEmacs. + + +File: xemacs.info, Node: Minor Modes, Next: Variables, Up: Customization + +Minor Modes +=========== + +Minor modes are options which you can use or not. For example, Auto +Fill mode is a minor mode in which breaks lines between words as +you type. All the minor modes are independent of each other and of the +selected major mode. Most minor modes inform you in the mode line when +they are on; for example, `Fill' in the mode line means that Auto Fill +mode is on. + + Append `-mode' to the name of a minor mode to get the name of a +command function that turns the mode on or off. Thus, the command to +enable or disable Auto Fill mode is called `M-x auto-fill-mode'. These +commands are usually invoked with `M-x', but you can bind keys to them +if you wish. With no argument, the function turns the mode on if it was +off and off if it was on. This is known as "toggling". A positive +argument always turns the mode on, and an explicit zero argument or a +negative argument always turns it off. + + Auto Fill mode allows you to enter filled text without breaking lines +explicitly. Emacs inserts newlines as necessary to prevent lines from +becoming too long. *Note Filling::. + + Overwrite mode causes ordinary printing characters to replace +existing text instead of moving it to the right. For example, if point +is in front of the `B' in `FOOBAR', and you type a `G' in Overwrite +mode, it changes to `FOOGAR', instead of `FOOGBAR'. + + Abbrev mode allows you to define abbreviations that automatically +expand as you type them. For example, `amd' might expand to `abbrev +mode'. *Note Abbrevs::, for full information. + + +File: xemacs.info, Node: Variables, Next: Keyboard Macros, Prev: Minor Modes, Up: Customization + +Variables +========= + +A "variable" is a Lisp symbol which has a value. Variable names can +contain any characters, but by convention they are words separated by +hyphens. A variable can also have a documentation string, which +describes what kind of value it should have and how the value will be +used. + + Lisp allows any variable to have any kind of value, but most +variables that Emacs uses require a value of a certain type. Often the +value has to be a string or a number. Sometimes we say that a certain +feature is turned on if a variable is "non-`nil'," meaning that if the +variable's value is `nil', the feature is off, but the feature is on +for any other value. The conventional value to turn on the +feature--since you have to pick one particular value when you set the +variable--is `t'. + + Emacs uses many Lisp variables for internal recordkeeping, as any +Lisp program must, but the most interesting variables for you are the +ones that exist for the sake of customization. Emacs does not +(usually) change the values of these variables; instead, you set the +values, and thereby alter and control the behavior of certain Emacs +commands. These variables are called "options". Most options are +documented in this manual and appear in the Variable Index (*note +Variable Index::). + + One example of a variable which is an option is `fill-column', which +specifies the position of the right margin (as a number of characters +from the left margin) to be used by the fill commands (*note Filling::). + +* Menu: + +* Examining:: Examining or setting one variable's value. +* Easy Customization:: Convenient and easy customization of variables. +* Edit Options:: Examining or editing list of all variables' values. +* Locals:: Per-buffer values of variables. +* File Variables:: How files can specify variable values. + + +File: xemacs.info, Node: Examining, Next: Easy Customization, Up: Variables + +Examining and Setting Variables +------------------------------- + +`C-h v' +`M-x describe-variable' + Print the value and documentation of a variable. + +`M-x set-variable' + Change the value of a variable. + + To examine the value of a single variable, use `C-h v' +(`describe-variable'), which reads a variable name using the +minibuffer, with completion. It prints both the value and the +documentation of the variable. + + C-h v fill-column + +prints something like: + + fill-column's value is 75 + + Documentation: + *Column beyond which automatic line-wrapping should happen. + Automatically becomes local when set in any fashion. + +The star at the beginning of the documentation indicates that this +variable is an option. `C-h v' is not restricted to options; it allows +any variable name. + + If you know which option you want to set, you can use `M-x +set-variable' to set it. This prompts for the variable name in the +minibuffer (with completion), and then prompts for a Lisp expression +for the new value using the minibuffer a second time. For example, + + M-x set-variable fill-column 75 + +sets `fill-column' to 75, as if you had executed the Lisp expression +`(setq fill-column 75)'. + + Setting variables in this way, like all means of customizing Emacs +except where explicitly stated, affects only the current Emacs session. + + +File: xemacs.info, Node: Easy Customization, Next: Edit Options, Prev: Examining, Up: Variables + +Easy Customization Interface +---------------------------- + +A convenient way to find the user option variables that you want to +change, and then change them, is with `M-x customize' (or use a +keyboard shortcut, `C-h C'. This command creates a "customization +buffer" with which you can browse through the Emacs user options in a +logically organized structure, then edit and set their values. You can +also use the customization buffer to save settings permanently. (Not +all Emacs user options are included in this structure as of yet, but we +are adding the rest.) + +* Menu: + +* Groups: Customization Groups. + How options are classified in a structure. +* Changing an Option:: How to edit a value and set an option. +* Face Customization:: How to edit the attributes of a face. +* Specific Customization:: Making a customization buffer for specific + options, faces, or groups. + + +File: xemacs.info, Node: Customization Groups, Next: Changing an Option, Up: Easy Customization + +Customization Groups +.................... + +For customization purposes, user options are organized into "groups" to +help you find them. Groups are collected into bigger groups, all the +way up to a master group called `Emacs'. + + `M-x customize' (or `C-h C') creates a customization buffer that +shows the top-level `Emacs' group and the second-level groups +immediately under it. It looks like this, in part: + + /- Emacs group: ---------------------------------------------------\ + [State]: visible group members are all at standard settings. + Customization of the One True Editor. + See also [Manual]. + + [Open] Editing group + Basic text editing facilities. + + [Open] External group + Interfacing to external utilities. + + MORE SECOND-LEVEL GROUPS + + \- Emacs group end ------------------------------------------------/ + +This says that the buffer displays the contents of the `Emacs' group. +The other groups are listed because they are its contents. But they +are listed differently, without indentation and dashes, because _their_ +contents are not included. Each group has a single-line documentation +string; the `Emacs' group also has a `[State]' line. + + Most of the text in the customization buffer is read-only, but it +typically includes some "editable fields" that you can edit. There are +also "active fields"; this means a field that does something when you +"invoke" it. To invoke an active field, either click on it with +`Mouse-1', or move point to it and type . + + For example, the phrase `[Open]' that appears in a second-level +group is an active field. Invoking the `[Open]' field for a group +opens up a new customization buffer, which shows that group and its +contents. This field is a kind of hypertext link to another group. + + The `Emacs' group does not include any user options itself, but +other groups do. By examining various groups, you will eventually find +the options and faces that belong to the feature you are interested in +customizing. Then you can use the customization buffer to set them. + + You can view the structure of customization groups on a larger scale +with `M-x customize-browse'. This command creates a special kind of +customization buffer which shows only the names of the groups (and +options and faces), and their structure. + + In this buffer, you can show the contents of a group by invoking +`[+]'. When the group contents are visible, this button changes to +`[-]'; invoking that hides the group contents. + + Each group, option or face name in this buffer has an active field +which says `[Group]', `[Option]' or `[Face]'. Invoking that active +field creates an ordinary customization buffer showing just that group +and its contents, just that option, or just that face. This is the way +to set values in it. + + +File: xemacs.info, Node: Changing an Option, Next: Face Customization, Prev: Customization Groups, Up: Easy Customization + +Changing an Option +.................. + +Here is an example of what a user option looks like in the +customization buffer: + + Kill Ring Max: [Hide] 30 + [State]: this option is unchanged from its standard setting. + Maximum length of kill ring before oldest elements are thrown away. + + The text following `[Hide]', `30' in this case, indicates the +current value of the option. If you see `[Show]' instead of `[Hide]', +it means that the value is hidden; the customization buffer initially +hides values that take up several lines. Invoke `[Show]' to show the +value. + + The line after the option name indicates the "customization state" +of the option: in the example above, it says you have not changed the +option yet. The word `[State]' at the beginning of this line is +active; you can get a menu of various operations by invoking it with +`Mouse-1' or . These operations are essential for customizing the +variable. + + The line after the `[State]' line displays the beginning of the +option's documentation string. If there are more lines of +documentation, this line ends with `[More]'; invoke this to show the +full documentation string. + + To enter a new value for `Kill Ring Max', move point to the value +and edit it textually. For example, you can type `M-d', then insert +another number. + + When you begin to alter the text, you will see the `[State]' line +change to say that you have edited the value: + + [State]: you have edited the value as text, but not set the option. + + Editing the value does not actually set the option variable. To do +that, you must "set" the option. To do this, invoke the word `[State]' +and choose `Set for Current Session'. + + The state of the option changes visibly when you set it: + + [State]: you have set this option, but not saved it for future sessions. + + You don't have to worry about specifying a value that is not valid; +setting the option checks for validity and will not really install an +unacceptable value. + + While editing a value or field that is a file name, directory name, +command name, or anything else for which completion is defined, you can +type `M-' (`widget-complete') to do completion. + + Some options have a small fixed set of possible legitimate values. +These options don't let you edit the value textually. Instead, an +active field `[Value Menu]' appears before the value; invoke this field +to edit the value. For a boolean "on or off" value, the active field +says `[Toggle]', and it changes to the other value. `[Value Menu]' and +`[Toggle]' edit the buffer; the changes take effect when you use the +`Set for Current Session' operation. + + Some options have values with complex structure. For example, the +value of `load-path' is a list of directories. Here is how it appears +in the customization buffer: + + Load Path: + [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp + [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp + [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim + [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp + [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp + [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus + [INS] + [State]: this item has been changed outside the customization buffer. + List of directories to search for files to load.... + +Each directory in the list appears on a separate line, and each line has +several editable or active fields. + + You can edit any of the directory names. To delete a directory from +the list, invoke `[DEL]' on that line. To insert a new directory in +the list, invoke `[INS]' at the point where you want to insert it. + + You can also invoke `[Current dir?]' to switch between including a +specific named directory in the path, and including `nil' in the path. +(`nil' in a search path means "try the current directory.") + + Two special commands, and `S-', are useful for moving +through the customization buffer. (`widget-forward') moves +forward to the next active or editable field; `S-' +(`widget-backward') moves backward to the previous active or editable +field. + + Typing on an editable field also moves forward, just like +. The reason for this is that people have a tendency to type + when they are finished editing a field. If you have occasion to +insert a newline in an editable field, use `C-o' or `C-q C-j', + + Setting the option changes its value in the current Emacs session; +"saving" the value changes it for future sessions as well. This works +by writing code into your init file so as to set the option variable +again each time you start Emacs. *Note Init File::. To save the +option, invoke `[State]' and select the `Save for Future Sessions' +operation. + + You can also restore the option to its standard value by invoking +`[State]' and selecting the `Reset' operation. There are actually +three reset operations: + +`Reset to Current' + If you have made some modifications and not yet set the option, + this restores the text in the customization buffer to match the + actual value. + +`Reset to Saved' + This restores the value of the option to the last saved value, and + updates the text accordingly. + +`Reset to Standard Settings' + This sets the option to its standard value, and updates the text + accordingly. This also eliminates any saved value for the option, + so that you will get the standard value in future Emacs sessions. + + The state of a group indicates whether anything in that group has +been edited, set or saved. You can select `Set for Current Session', +`Save for Future Sessions' and the various kinds of `Reset' operation +for the group; these operations on the group apply to all options in +the group and its subgroups. + + Near the top of the customization buffer there are two lines +containing several active fields: + + [Set] [Save] [Reset] [Done] + +Invoking `[Done]' buries this customization buffer. Each of the other +fields performs an operation--set, save or reset--on each of the items +in the buffer that could meaningfully be set, saved or reset. + + +File: xemacs.info, Node: Face Customization, Next: Specific Customization, Prev: Changing an Option, Up: Easy Customization + +Customizing Faces +................. + +In addition to user options, some customization groups also include +faces. When you show the contents of a group, both the user options and +the faces in the group appear in the customization buffer. Here is an +example of how a face looks: + + Custom Changed Face: (sample) + [State]: this face is unchanged from its standard setting. + Face used when the customize item has been changed. + Parent groups: [Custom Magic Faces] + Attributes: [ ] Bold: [Toggle] off (nil) + [ ] Italic: [Toggle] off (nil) + [ ] Underline: [Toggle] off (nil) + [ ] Foreground: white (sample) + [ ] Background: blue (sample) + [ ] Inverse: [Toggle] off (nil) + [ ] Stipple: + [ ] Font Family: + [ ] Size: + [ ] Strikethru: off + + Each face attribute has its own line. The `[X]' field before the +attribute name indicates whether the attribute is "enabled"; `X' means +that it is. You can enable or disable the attribute by invoking that +field. When the attribute is enabled, you can change the attribute +value in the usual ways. + + *Note Faces::, for description of how `face-frob-from-locale-first' +variable affects changing `Bold' and `Italic' attributes. + + Setting, saving and resetting a face work like the same operations +for options (*note Changing an Option::). + + A face can specify different appearances for different types of +display. For example, a face can make text red on a color display, but +use a bold font on a monochrome display. To specify multiple +appearances for a face, select `Show Display Types' in the menu you get +from invoking `[State]'. + + +File: xemacs.info, Node: Specific Customization, Prev: Face Customization, Up: Easy Customization + +Customizing Specific Items +.......................... + +Instead of finding the options you want to change by moving down +through the structure of groups, you can specify the particular option, +face or group that you want to customize. + +`M-x customize-option OPTION ' + Set up a customization buffer with just one option, OPTION. + +`M-x customize-face FACE ' + Set up a customization buffer with just one face, FACE. + +`M-x customize-group GROUP ' + Set up a customization buffer with just one group, GROUP. + +`M-x customize-apropos REGEXP ' + Set up a customization buffer with all the options, faces and + groups that match REGEXP. + +`M-x customize-saved' + Set up a customization buffer containing all options and faces + that you have saved with customization buffers. + +`M-x customize-customized' + Set up a customization buffer containing all options and faces + that you have customized but not saved. + + If you want to alter a particular user option variable with the +customization buffer, and you know its name, you can use the command +`M-x customize-option' and specify the option name. This sets up the +customization buffer with just one option--the one that you asked for. +Editing, setting and saving the value work as described above, but only +for the specified option. + + Likewise, you can modify a specific face, chosen by name, using `M-x +customize-face'. + + You can also set up the customization buffer with a specific group, +using `M-x customize-group'. The immediate contents of the chosen +group, including option variables, faces, and other groups, all appear +as well. However, these subgroups' own contents start out hidden. You +can show their contents in the usual way, by invoking `[Show]'. + + To control more precisely what to customize, you can use `M-x +customize-apropos'. You specify a regular expression as argument; then +all options, faces and groups whose names match this regular expression +are set up in the customization buffer. If you specify an empty regular +expression, this includes _all_ groups, options and faces in the +customization buffer (but that takes a long time). + + If you change option values and then decide the change was a mistake, +you can use two special commands to revisit your previous changes. Use +`customize-saved' to look at the options and faces that you have saved. +Use `M-x customize-customized' to look at the options and faces that +you have set but not saved. + + +File: xemacs.info, Node: Edit Options, Next: Locals, Prev: Easy Customization, Up: Variables + +Editing Variable Values +----------------------- + +`M-x list-options' + Display a buffer listing names, values, and documentation of all + options. + +`M-x edit-options' + Change option values by editing a list of options. + + `M-x list-options' displays a list of all Emacs option variables in +an Emacs buffer named `*List Options*'. Each option is shown with its +documentation and its current value. Here is what a portion of it might +look like: + + ;; exec-path: + ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc") + *List of directories to search programs to run in subprocesses. + Each element is a string (directory name) + or nil (try the default directory). + ;; + ;; fill-column: + 75 + *Column beyond which automatic line-wrapping should happen. + Automatically becomes local when set in any fashion. + ;; + + `M-x edit-options' goes one step further and immediately selects the +`*List Options*' buffer; this buffer uses the major mode Options mode, +which provides commands that allow you to point at an option and change +its value: + +`s' + Set the variable point is in or near to a new value read using the + minibuffer. + +`x' + Toggle the variable point is in or near: if the value was `nil', + it becomes `t'; otherwise it becomes `nil'. + +`1' + Set the variable point is in or near to `t'. + +`0' + Set the variable point is in or near to `nil'. + +`n' +`p' + Move to the next or previous variable. + + +File: xemacs.info, Node: Locals, Next: File Variables, Prev: Edit Options, Up: Variables + +Local Variables +--------------- + +`M-x make-local-variable' + Make a variable have a local value in the current buffer. + +`M-x kill-local-variable' + Make a variable use its global value in the current buffer. + +`M-x make-variable-buffer-local' + Mark a variable so that setting it will make it local to the + buffer that is current at that time. + + You can make any variable "local" to a specific Emacs buffer. This +means that the variable's value in that buffer is independent of its +value in other buffers. A few variables are always local in every +buffer. All other Emacs variables have a "global" value which is in +effect in all buffers that have not made the variable local. + + Major modes always make the variables they set local to the buffer. +This is why changing major modes in one buffer has no effect on other +buffers. + + `M-x make-local-variable' reads the name of a variable and makes it +local to the current buffer. Further changes in this buffer will not +affect others, and changes in the global value will not affect this +buffer. + + `M-x make-variable-buffer-local' reads the name of a variable and +changes the future behavior of the variable so that it automatically +becomes local when it is set. More precisely, once you have marked a +variable in this way, the usual ways of setting the variable will +automatically invoke `make-local-variable' first. We call such +variables "per-buffer" variables. + + Some important variables have been marked per-buffer already. They +include `abbrev-mode', `auto-fill-function', `case-fold-search', +`comment-column', `ctl-arrow', `fill-column', `fill-prefix', +`indent-tabs-mode', `left-margin', +`mode-line-format', `overwrite-mode', `selective-display-ellipses', +`selective-display', `tab-width', and `truncate-lines'. Some other +variables are always local in every buffer, but they are used for +internal purposes. + + Note: the variable `auto-fill-function' was formerly named +`auto-fill-hook'. + + If you want a variable to cease to be local to the current buffer, +call `M-x kill-local-variable' and provide the name of a variable to +the prompt. The global value of the variable is again in effect in +this buffer. Setting the major mode kills all the local variables of +the buffer. + + To set the global value of a variable, regardless of whether the +variable has a local value in the current buffer, you can use the Lisp +function `setq-default'. It works like `setq'. If there is a local +value in the current buffer, the local value is not affected by +`setq-default'; thus, the new global value may not be visible until you +switch to another buffer, as in the case of: + + (setq-default fill-column 75) + +`setq-default' is the only way to set the global value of a variable +that has been marked with `make-variable-buffer-local'. + + Programs can look at a variable's default value with `default-value'. +This function takes a symbol as an argument and returns its default +value. The argument is evaluated; usually you must quote it +explicitly, as in the case of: + + (default-value 'fill-column) + + +File: xemacs.info, Node: File Variables, Prev: Locals, Up: Variables + +Local Variables in Files +------------------------ + +A file can contain a "local variables list", which specifies the values +to use for certain Emacs variables when that file is edited. Visiting +the file checks for a local variables list and makes each variable in +the list local to the buffer in which the file is visited, with the +value specified in the file. + + A local variables list goes near the end of the file, in the last +page. (It is often best to put it on a page by itself.) The local +variables list starts with a line containing the string `Local +Variables:', and ends with a line containing the string `End:'. In +between come the variable names and values, one set per line, as +`VARIABLE: VALUE'. The VALUEs are not evaluated; they are used +literally. + + The line which starts the local variables list does not have to say +just `Local Variables:'. If there is other text before `Local +Variables:', that text is called the "prefix", and if there is other +text after, that is called the "suffix". If a prefix or suffix are +present, each entry in the local variables list should have the prefix +before it and the suffix after it. This includes the `End:' line. The +prefix and suffix are included to disguise the local variables list as +a comment so the compiler or text formatter will ignore it. If you do +not need to disguise the local variables list as a comment in this way, +there is no need to include a prefix or a suffix. + + Two "variable" names are special in a local variables list: a value +for the variable `mode' sets the major mode, and a value for the +variable `eval' is simply evaluated as an expression and the value is +ignored. These are not real variables; setting them in any other +context does not have the same effect. If `mode' is used in a local +variables list, it should be the first entry in the list. + + Here is an example of a local variables list: + ;;; Local Variables: *** + ;;; mode:lisp *** + ;;; comment-column:0 *** + ;;; comment-start: ";;; " *** + ;;; comment-end:"***" *** + ;;; End: *** + + Note that the prefix is `;;; ' and the suffix is ` ***'. Note also +that comments in the file begin with and end with the same strings. +Presumably the file contains code in a language which is enough like +Lisp for Lisp mode to be useful but in which comments start and end +differently. The prefix and suffix are used in the local variables +list to make the list look like several lines of comments when the +compiler or interpreter for that language reads the file. + + The start of the local variables list must be no more than 3000 +characters from the end of the file, and must be in the last page if the +file is divided into pages. Otherwise, Emacs will not notice it is +there. The purpose is twofold: a stray `Local Variables:' not in the +last page does not confuse Emacs, and Emacs never needs to search a +long file that contains no page markers and has no local variables list. + + You may be tempted to turn on Auto Fill mode with a local variable +list. That is inappropriate. Whether you use Auto Fill mode or not is +a matter of personal taste, not a matter of the contents of particular +files. If you want to use Auto Fill, set up major mode hooks with your +init file to turn it on (when appropriate) for you alone (*note Init +File::). Don't try to use a local variable list that would impose your +taste on everyone working with the file. + + XEmacs allows you to specify local variables in the first line of a +file, in addition to specifying them in the `Local Variables' section +at the end of a file. + + If the first line of a file contains two occurrences of ``-*-'', +XEmacs uses the information between them to determine what the major +mode and variable settings should be. For example, these are all legal: + + ;;; -*- mode: emacs-lisp -*- + ;;; -*- mode: postscript; version-control: never -*- + ;;; -*- tags-file-name: "/foo/bar/TAGS" -*- + + For historical reasons, the syntax ``-*- modename -*-'' is allowed +as well; for example, you can use: + + ;;; -*- emacs-lisp -*- + + The variable `enable-local-variables' controls the use of local +variables lists in files you visit. The value can be `t', `nil', or +something else. A value of `t' means local variables lists are obeyed; +`nil' means they are ignored; anything else means query. + + The command `M-x normal-mode' always obeys local variables lists and +ignores this variable. + + +File: xemacs.info, Node: Keyboard Macros, Next: Key Bindings, Prev: Variables, Up: Customization - There are two commands for exiting Emacs because there are two kinds -of exiting: "suspending" Emacs and "killing" Emacs. - - "Suspending" means stopping Emacs temporarily and returning control -to its parent process (usually a shell), allowing you to resume editing -later in the same Emacs job, with the same buffers, same kill ring, -same undo history, and so on. This is the usual way to exit. - - "Killing" Emacs means destroying the Emacs job. You can run Emacs -again later, but you will get a fresh Emacs; there is no way to resume -the same editing session after it has been killed. - -`C-z' - Suspend Emacs or iconify a frame - (`suspend-emacs-or-iconify-frame'). If used under the X window - system, shrink the X window containing the Emacs frame to an icon - (see below). - -`C-x C-c' - Kill Emacs (`save-buffers-kill-emacs'). - - If you use XEmacs under the X window system, `C-z' shrinks the X -window containing the Emacs frame to an icon. The Emacs process is -stopped temporarily, and control is returned to the window manager. If -more than one frame is associated with the Emacs process, only the -frame from which you used `C-z' is iconified. - - To activate the "suspended" Emacs, use the appropriate window manager -mouse gestures. Usually left-clicking on the icon reactivates and -reopens the X window containing the Emacs frame, but the window manager -you use determines what exactly happens. To actually kill the Emacs -process, use `C-x C-c' or the Exit XEmacs item on the File menu. - - To suspend Emacs, type `C-z' (`suspend-emacs'). This takes you back -to the shell from which you invoked Emacs. You can resume Emacs with -the shell command `%xemacs' in most common shells. - - On systems that do not support suspending programs, `C-z' starts an -inferior shell that communicates directly with the terminal. Emacs -waits until you exit the subshell. (The way to do that is probably -with `C-d' or `exit', but it depends on which shell you use.) The only -way on these systems to get back to the shell from which Emacs was run -(to log out, for example) is to kill Emacs. - - Suspending also fails if you run Emacs under a shell that doesn't -support suspending programs, even if the system itself does support it. -In such a case, you can set the variable `cannot-suspend' to a -non-`nil' value to force `C-z' to start an inferior shell. (One might -also describe Emacs's parent shell as "inferior" for failing to support -job control properly, but that is a matter of taste.) - - When Emacs communicates directly with an X server and creates its own -dedicated X windows, `C-z' has a different meaning. Suspending an -applications that uses its own X windows is not meaningful or useful. -Instead, `C-z' runs the command `iconify-or-deiconify-frame', which -temporarily closes up the selected Emacs frame. The way to get back to -a shell window is with the window manager. - - To kill Emacs, type `C-x C-c' (`save-buffers-kill-emacs'). A -two-character key is used for this to make it harder to type. Selecting -the Exit XEmacs option of the File menu is an alternate way of issuing -the command. - - Unless a numeric argument is used, this command first offers to save -any modified file-visiting buffers. If you do not save all buffers, -you are asked for reconfirmation with `yes' before killing Emacs, since -any changes not saved will be lost forever. If any subprocesses are -still running, `C-x C-c' asks you to confirm killing them, since killing -Emacs will kill the subprocesses immediately. - - There is no way to restart an Emacs session once you have killed it. -You can, however, arrange for Emacs to record certain session -information, such as which files are visited, when you kill it, so that -the next time you restart Emacs it will try to visit the same files and -so on. - - The operating system usually listens for certain special characters -whose meaning is to kill or suspend the program you are running. This -operating system feature is turned off while you are in Emacs. The -meanings of `C-z' and `C-x C-c' as keys in Emacs were inspired by the -use of `C-z' and `C-c' on several operating systems as the characters -for stopping or killing a program, but that is their only relationship -with the operating system. You can customize these keys to run any -commands of your choice (*note Keymaps::). - - -File: xemacs.info, Node: Command Switches, Next: Startup Paths, Prev: Exiting, Up: Top - -Command Line Switches and Arguments -=================================== - - XEmacs supports command line arguments you can use to request -various actions when invoking Emacs. The commands are for compatibility -with other editors and for sophisticated activities. If you are using -XEmacs under the X window system, you can also use a number of standard -Xt command line arguments. Command line arguments are not usually -needed for editing with Emacs; new users can skip this section. - - Many editors are designed to be started afresh each time you want to -edit. You start the editor to edit one file; then exit the editor. The -next time you want to edit either another file or the same one, you -start the editor again. Under these circumstances, it makes sense to -use a command line argument to say which file to edit. - - The recommended way to use XEmacs is to start it only once, just -after you log in, and do all your editing in the same Emacs process. -Each time you want to edit a file, you visit it using the existing -Emacs. Emacs creates a new buffer for each file, and (unless you kill -some of the buffers) Emacs eventually has many files in it ready for -editing. Usually you do not kill the Emacs process until you are about -to log out. Since you usually read files by typing commands to Emacs, -command line arguments for specifying a file when Emacs is started are -seldom needed. - - Emacs accepts command-line arguments that specify files to visit, -functions to call, and other activities and operating modes. If you are -running XEmacs under the X window system, a number of standard Xt -command line arguments are available as well. - - The following subsections list: - * Command line arguments that you can always use - - * Command line arguments that have to appear at the beginning of the - argument list - - * Command line arguments that are only relevant if you are running - XEmacs under X - -Command Line Arguments for Any Position ---------------------------------------- +Keyboard Macros +=============== + +A "keyboard macro" is a command defined by the user to abbreviate a +sequence of keys. For example, if you discover that you are about to +type `C-n C-d' forty times, you can speed your work by defining a +keyboard macro to invoke `C-n C-d' and calling it with a repeat count +of forty. + +`C-x (' + Start defining a keyboard macro (`start-kbd-macro'). - Command line arguments are processed in the order they appear on the -command line; however, certain arguments (the ones in the second table) -must be at the front of the list if they are used. +`C-x )' + End the definition of a keyboard macro (`end-kbd-macro'). - Here are the arguments allowed: +`C-x e' + Execute the most recent keyboard macro (`call-last-kbd-macro'). -`FILE' - Visit FILE using `find-file'. *Note Visiting::. +`C-u C-x (' + Re-execute last keyboard macro, then add more keys to its + definition. -`+LINENUM FILE' - Visit FILE using `find-file', then go to line number LINENUM in it. +`C-x q' + When this point is reached during macro execution, ask for + confirmation (`kbd-macro-query'). -`-load FILE' -`-l FILE' - Load a file FILE of Lisp code with the function `load'. *Note - Lisp Libraries::. +`M-x name-last-kbd-macro' + Give a command name (for the duration of the session) to the most + recently defined keyboard macro. -`-funcall FUNCTION' -`-f FUNCTION' - Call Lisp function FUNCTION with no arguments. +`M-x insert-kbd-macro' + Insert in the buffer a keyboard macro's definition, as Lisp code. -`-eval FUNCTION' - Interpret the next argument as a Lisp expression, and evaluate it. - You must be very careful of the shell quoting here. + Keyboard macros differ from other Emacs commands in that they are +written in the Emacs command language rather than in Lisp. This makes +it easier for the novice to write them and makes them more convenient as +temporary hacks. However, the Emacs command language is not powerful +enough as a programming language to be useful for writing anything +general or complex. For such things, Lisp must be used. -`-insert FILE' -`-i FILE' - Insert the contents of FILE into the current buffer. This is like - what `M-x insert-buffer' does; *Note Misc File Ops::. + You define a keyboard macro by executing the commands which are its +definition. Put differently, as you are defining a keyboard macro, the +definition is being executed for the first time. This way, you see +what the effects of your commands are, and don't have to figure them +out in your head. When you are finished, the keyboard macro is defined +and also has been executed once. You can then execute the same set of +commands again by invoking the macro. -`-kill' - Exit from Emacs without asking for confirmation. +* Menu: + +* Basic Kbd Macro:: Defining and running keyboard macros. +* Save Kbd Macro:: Giving keyboard macros names; saving them in files. +* Kbd Macro Query:: Keyboard macros that do different things each use. -`-version' -`-V' - Prints version information. This implies `-batch'. + +File: xemacs.info, Node: Basic Kbd Macro, Next: Save Kbd Macro, Up: Keyboard Macros - % xemacs -version - XEmacs 19.13 of Mon Aug 21 1995 on willow (usg-unix-v) [formerly Lucid Emacs] +Basic Use +--------- -`-help' - Prints a summary of command-line options and then exits. +To start defining a keyboard macro, type `C-x (' (`start-kbd-macro'). +From then on, anything you type continues to be executed, but also +becomes part of the definition of the macro. `Def' appears in the mode +line to remind you of what is going on. When you are finished, the +`C-x )' command (`end-kbd-macro') terminates the definition, without +becoming part of it. -Command Line Arguments (Beginning of Line Only) ------------------------------------------------ + For example, - The following arguments are recognized only at the beginning of the -command line. If more than one of them appears, they must appear in the -order in which they appear in this table. + C-x ( M-f foo C-x ) -`-t FILE' - Use FILE instead of the terminal for input and output. This - implies the `-nw' option, documented below. +defines a macro to move forward a word and then insert `foo'. -`-batch' - Run Emacs in "batch mode", which means that the text being edited - is not displayed and the standard Unix interrupt characters such as - `C-z' and `C-c' continue to have their normal effect. Emacs in - batch mode outputs to `stderr' only what would normally be printed - in the echo area under program control. + You can give `C-x )' a repeat count as an argument, in which case it +repeats the macro that many times right after defining it, but defining +the macro counts as the first repetition (since it is executed as you +define it). If you give `C-x )' an argument of 4, it executes the +macro immediately 3 additional times. An argument of zero to `C-x e' +or `C-x )' means repeat the macro indefinitely (until it gets an error +or you type `C-g'). - Batch mode is used for running programs written in Emacs Lisp from - shell scripts, makefiles, and so on. Normally the `-l' switch or - `-f' switch will be used as well, to invoke a Lisp program to do - the batch processing. + Once you have defined a macro, you can invoke it again with the `C-x +e' command (`call-last-kbd-macro'). You can give the command a repeat +count numeric argument to execute the macro many times. - `-batch' implies `-q' (do not load an init file). It also causes - Emacs to kill itself after all command switches have been - processed. In addition, auto-saving is not done except in buffers - for which it has been explicitly requested. - -`-nw' - Start up XEmacs in TTY mode (using the TTY XEmacs was started - from), rather than trying to connect to an X display. Note that - this happens automatically if the `DISPLAY' environment variable - is not set. + To repeat an operation at regularly spaced places in the text, +define a macro and include as part of the macro the commands to move to +the next place you want to use it. For example, if you want to change +each line, you should position point at the start of a line, and define +a macro to change that line and leave point at the start of the next +line. Repeating the macro will then operate on successive lines. -`-debug-init' - Enter the debugger if an error in the init file occurs. + After you have terminated the definition of a keyboard macro, you +can add to the end of its definition by typing `C-u C-x ('. This is +equivalent to plain `C-x (' followed by retyping the whole definition +so far. As a consequence it re-executes the macro as previously +defined. -`-debug-paths' - Displays information on how XEmacs constructs the various paths - into its hierarchy on startup. (See also *note Startup Paths::.) + +File: xemacs.info, Node: Save Kbd Macro, Next: Kbd Macro Query, Prev: Basic Kbd Macro, Up: Keyboard Macros + +Naming and Saving Keyboard Macros +--------------------------------- + +To save a keyboard macro for longer than until you define the next one, +you must give it a name using `M-x name-last-kbd-macro'. This reads a +name as an argument using the minibuffer and defines that name to +execute the macro. The macro name is a Lisp symbol, and defining it in +this way makes it a valid command name for calling with `M-x' or for +binding a key to with `global-set-key' (*note Keymaps::). If you +specify a name that has a prior definition other than another keyboard +macro, Emacs prints an error message and nothing is changed. + + Once a macro has a command name, you can save its definition in a +file. You can then use it in another editing session. First visit the +file you want to save the definition in. Then use the command: + + M-x insert-kbd-macro MACRONAME + +This inserts some Lisp code that, when executed later, will define the +same macro with the same definition it has now. You need not +understand Lisp code to do this, because `insert-kbd-macro' writes the +Lisp code for you. Then save the file. You can load the file with +`load-file' (*note Lisp Libraries::). If the file you save in is your +initialization file (*note Init File::), then the macro will be defined +each time you run Emacs. + + If you give `insert-kbd-macro' a prefix argument, it creates +additional Lisp code to record the keys (if any) that you have bound to +the keyboard macro, so that the macro is reassigned the same keys when +you load the file. -`-unmapped' - Do not map the initial frame. This is useful if you want to start - up XEmacs as a server (e.g. for gnuserv screens or external client - widgets). + +File: xemacs.info, Node: Kbd Macro Query, Prev: Save Kbd Macro, Up: Keyboard Macros + +Executing Macros With Variations +-------------------------------- + +You can use `C-x q' (`kbd-macro-query'), to get an effect similar to +that of `query-replace'. The macro asks you each time whether to make +a change. When you are defining the macro, type `C-x q' at the point +where you want the query to occur. During macro definition, the `C-x +q' does nothing, but when you invoke the macro, `C-x q' reads a +character from the terminal to decide whether to continue. + + The special answers to a `C-x q' query are , , `C-d', +`C-l', and `C-r'. Any other character terminates execution of the +keyboard macro and is then read as a command. means to continue. + means to skip the remainder of this repetition of the macro, +starting again from the beginning in the next repetition. `C-d' means +to skip the remainder of this repetition and cancel further repetition. +`C-l' redraws the frame and asks you again for a character to specify +what to do. `C-r' enters a recursive editing level, in which you can +perform editing that is not part of the macro. When you exit the +recursive edit using `C-M-c', you are asked again how to continue with +the keyboard macro. If you type a at this time, the rest of the +macro definition is executed. It is up to you to leave point and the +text in a state such that the rest of the macro will do what you want. + + `C-u C-x q', which is `C-x q' with a numeric argument, performs a +different function. It enters a recursive edit reading input from the +keyboard, both when you type it during the definition of the macro and +when it is executed from the macro. During definition, the editing you +do inside the recursive edit does not become part of the macro. During +macro execution, the recursive edit gives you a chance to do some +particularized editing. *Note Recursive Edit::. -`-no-init-file' -`-q' - Do not load your Emacs init file. *Note Init File::. + +File: xemacs.info, Node: Key Bindings, Next: Syntax, Prev: Keyboard Macros, Up: Customization -`-no-site-file' - Do not load the site-specific init file `lisp/site-start.el'. +Customizing Key Bindings +======================== -`-no-autoloads' - Do not load global symbol files (`auto-autoloads') at startup. - This implies `-vanilla'. +This section deals with the "keymaps" that define the bindings between +keys and functions, and shows how you can customize these bindings. -`-no-early-packages' - Do not process early packages. (For more information on startup - issues concerning the package system, *Note Startup Paths::.) + A command is a Lisp function whose definition provides for +interactive use. Like every Lisp function, a command has a function +name, which is a Lisp symbol whose name usually consists of lower case +letters and hyphens. -`-vanilla' - This is equivalent to `-q -no-site-file -no-early-packages'. - -`-user-init-file FILE' - Load FILE as your Emacs init file instead of - `~/.xemacs/init.el'/`~/.emacs'. - -`-user-init-directory DIRECTORY' - Use DIRECTORY as the location of your early package hierarchies - and the various user-specific initialization files. - -`-user USER' -`-u USER' - Equivalent to `-user-init-file ~USER/.xemacs/init.el - -user-init-directory ~USER/.xemacs', or `-user-init-file - ~USER/.emacs -user-init-directory ~USER/.xemacs'. whichever init - file comes first. *Note Init File::. - - Note that the init file can get access to the command line argument -values as the elements of a list in the variable `command-line-args'. -(The arguments in the second table above will already have been -processed and will not be in the list.) The init file can override the -normal processing of the other arguments by setting this variable. +* Menu: - One way to use command switches is to visit many files automatically: +* Keymaps:: Definition of the keymap data structure. + Names of Emacs's standard keymaps. +* Rebinding:: How to redefine one key's meaning conveniently. +* Disabling:: Disabling a command means confirmation is required + before it can be executed. This is done to protect + beginners from surprises. - xemacs *.c + +File: xemacs.info, Node: Keymaps, Next: Rebinding, Up: Key Bindings -passes each `.c' file as a separate argument to Emacs, so that Emacs -visits each file (*note Visiting::). +Keymaps +------- - Here is an advanced example that assumes you have a Lisp program file -called `hack-c-program.el' which, when loaded, performs some useful -operation on the current buffer, expected to be a C program. +The bindings between characters and command functions are recorded in +data structures called "keymaps". Emacs has many of these. One, the +"global" keymap, defines the meanings of the single-character keys that +are defined regardless of major mode. It is the value of the variable +`global-map'. - xemacs -batch foo.c -l hack-c-program -f save-buffer -kill > log - -Here Emacs is told to visit `foo.c', load `hack-c-program.el' (which -makes changes in the visited file), save `foo.c' (note that -`save-buffer' is the function that `C-x C-s' is bound to), and then -exit to the shell from which the command was executed. `-batch' -guarantees there will be no problem redirecting output to `log', -because Emacs will not assume that it has a display terminal to work -with. - -Command Line Arguments (for XEmacs Under X) -------------------------------------------- - - If you are running XEmacs under X, a number of options are available -to control color, border, and window title and icon name: - -`-title TITLE' -`-wn TITLE' -`-T TITLE' - Use TITLE as the window title. This sets the `frame-title-format' - variable, which controls the title of the X window corresponding - to the selected frame. This is the same format as - `mode-line-format'. + Each major mode has another keymap, its "local keymap", which +contains overriding definitions for the single-character keys that are +redefined in that mode. Each buffer records which local keymap is +installed for it at any time, and the current buffer's local keymap is +the only one that directly affects command execution. The local keymaps +for Lisp mode, C mode, and many other major modes always exist even when +not in use. They are the values of the variables `lisp-mode-map', +`c-mode-map', and so on. For less frequently used major modes, the +local keymap is sometimes constructed only when the mode is used for the +first time in a session, to save space. -`-iconname TITLE' -`-in TITLE' - Use TITLE as the icon name. This sets the - `frame-icon-title-format' variable, which controls the title of - the icon corresponding to the selected frame. + There are local keymaps for the minibuffer, too; they contain various +completion and exit commands. -`-mc COLOR' - Use COLOR as the mouse color. + * `minibuffer-local-map' is used for ordinary input (no completion). -`-cr COLOR' - Use COLOR as the text-cursor foreground color. + * `minibuffer-local-ns-map' is similar, except that exits just + like . This is used mainly for Mocklisp compatibility. -`-private' - Install a private colormap for XEmacs. + * `minibuffer-local-completion-map' is for permissive completion. - In addition, XEmacs allows you to use a number of standard Xt -command line arguments. + * `minibuffer-local-must-match-map' is for strict completion and for + cautious completion. -`-background COLOR' -`-bg COLOR' - Use COLOR as the background color. + * `repeat-complex-command-map' is for use in `C-x '. -`-bordercolor COLOR' -`-bd COLOR' - Use COLOR as the border color. + * `isearch-mode-map' contains the bindings of the special keys which + are bound in the pseudo-mode entered with `C-s' and `C-r'. -`-borderwidth WIDTH' -`-bw WIDTH' - Use WIDTH as the border width. + Finally, each prefix key has a keymap which defines the key sequences +that start with it. For example, `ctl-x-map' is the keymap used for +characters following a `C-x'. -`-display DISPLAY' -`-d DISPLAY' - When running under the X window system, create the window - containing the Emacs frame on the display named DISPLAY. + * `ctl-x-map' is the variable name for the map used for characters + that follow `C-x'. -`-foreground COLOR' -`-fg COLOR' - Use COLOR as the foreground color. + * `help-map' is used for characters that follow `C-h'. -`-font NAME' -`-fn NAME' - Use NAME as the default font. + * `esc-map' is for characters that follow . All Meta characters + are actually defined by this map. -`-geometry SPEC' -`-geom SPEC' -`-g SPEC' - Use the geometry (window size and/or position) specified by SPEC. + * `ctl-x-4-map' is for characters that follow `C-x 4'. -`-iconic' - Start up iconified. + * `mode-specific-map' is for characters that follow `C-c'. -`-rv' - Bring up Emacs in reverse video. + The definition of a prefix key is the keymap to use for looking up +the following character. Sometimes the definition is actually a Lisp +symbol whose function definition is the following character keymap. The +effect is the same, but it provides a command name for the prefix key +that you can use as a description of what the prefix key is for. Thus +the binding of `C-x' is the symbol `Ctl-X-Prefix', whose function +definition is the keymap for `C-x' commands, the value of `ctl-x-map'. -`-name NAME' - Use the resource manager resources specified by NAME. The default - is to use the name of the program (`argv[0]') as the resource - manager name. + Prefix key definitions can appear in either the global map or a +local map. The definitions of `C-c', `C-x', `C-h', and as prefix +keys appear in the global map, so these prefix keys are always +available. Major modes can locally redefine a key as a prefix by +putting a prefix key definition for it in the local map. -`-xrm' - Read something into the resource database for this invocation of - Emacs only. + A mode can also put a prefix definition of a global prefix character +such as `C-x' into its local map. This is how major modes override the +definitions of certain keys that start with `C-x'. This case is +special, because the local definition does not entirely replace the +global one. When both the global and local definitions of a key are +other keymaps, the next character is looked up in both keymaps, with +the local definition overriding the global one. The character after the +`C-x' is looked up in both the major mode's own keymap for redefined +`C-x' commands and in `ctl-x-map'. If the major mode's own keymap for +`C-x' commands contains `nil', the definition from the global keymap +for `C-x' commands is used.  -File: xemacs.info, Node: Startup Paths, Next: Basic, Prev: Command Switches, Up: Top +File: xemacs.info, Node: Rebinding, Next: Disabling, Prev: Keymaps, Up: Key Bindings -How XEmacs finds Directories and Files -====================================== +Changing Key Bindings +--------------------- - XEmacs deals with a multitude of files during operation. These files -are spread over many directories, and XEmacs determines the location of -most of these directories at startup and organizes them into various -paths. (A "path", for the purposes of this section, is simply a list -of directories which XEmacs searches successively in order to locate a -file.) +You can redefine an Emacs key by changing its entry in a keymap. You +can change the global keymap, in which case the change is effective in +all major modes except those that have their own overriding local +definitions for the same key. Or you can change the current buffer's +local map, which affects all buffers using the same major mode. -XEmacs Directory Hierarchies ----------------------------- +* Menu: - Many of the files XEmacs looks for are located within the XEmacs -installation itself. However, there are several views of what actually -constitutes the "XEmacs installation": XEmacs may be run from the -compilation directory, it may be installed into arbitrary directories, -spread over several directories unrelated to each other. Moreover, it -may subsequently be moved to a different place. (This last case is not -as uncommon as it sounds. Binary kits work this way.) Consequently, -XEmacs has quite complex procedures in place to find directories, no -matter where they may be hidden. - - XEmacs will always respect directory options passed to `configure'. -However, if it cannot locate a directory at the configured place, it -will initiate a search for the directory in any of a number of -"hierarchies" rooted under a directory which XEmacs assumes contain -parts of the XEmacs installation; it may locate several such hierarchies -and search across them. (Typically, there are just one or two -hierarchies: the hierarchy where XEmacs was or will be installed, and -the one where it is being built.) Such a directory containing a -hierarchy is called a "root". Whenever this section refers to a -directory using the shorthand `', it means that XEmacs searches -for it under all hierarchies XEmacs was able to scrounge up. In a -running XEmacs, the hierarchy roots are stored in the variable -`emacs-roots'. - -Package Hierarchies -------------------- +* Interactive Rebinding:: Changing Key Bindings Interactively +* Programmatic Rebinding:: Changing Key Bindings Programmatically +* Key Bindings Using Strings:: Using Strings for Changing Key Bindings - Many relevant directories and files XEmacs uses are actually not -part of the core installation. They are part of any of the many -packages usually installed on top of an XEmacs installation. (*Note -Packages::.) Hence, they play a prominent role in the various paths -XEmacs sets up. - - XEmacs locates packages in any of a number of package hierarchies. -Package hierarchies fall into three groups: "early", "late", and "last", -according to the relative location at which they show up in the various -XEmacs paths. Early package hierarchies are at the very front, late -ones somewhere in the middle, and last hierarchies are (you guessed it) -last. - - By default, XEmacs expects an early package hierarchy in the -subdirectory `.xemacs/xemacs-packages' of the user's home directory. - - Moreover, XEmacs expects late hierarchies in the subdirectories -`site-packages', `mule-packages', and `xemacs-packages' (in that order) -of the `/lib/xemacs' subdirectory of one of the installation -hierarchies. (If you run in-place, these are direct subdirectories of -the build directory.) Furthermore, XEmacs will also search these -subdirectories in the `/lib/xemacs-' subdirectory and -prefer directories found there. - - By default, XEmacs does not have a pre-configured last package -hierarchy. Last hierarchies are primarily for using package hierarchies -of outdated versions of XEmacs as a fallback option. For example, it is -possible to run XEmacs 21 with the 20.4 package hierarchy as a last -hierarchy. + +File: xemacs.info, Node: Interactive Rebinding, Next: Programmatic Rebinding, Up: Rebinding - It is possible to specify at configure-time the location of the -various package hierarchies with the `--package-path' option to -configure. The early, late, and last components of the package path -are separated by double instead of single colons. If all three -components are present, they locate the early, late, and last package -hierarchies respectively. If two components are present, they locate -the early and late hierarchies. If only one component is present, it -locates the late hierarchy. At run time, the package path may also be -specified via the `EMACSPACKAGEPATH' environment variable. +Changing Key Bindings Interactively +................................... - An XEmacs package is laid out just like a normal installed XEmacs -lisp directory. It may have `lisp', `etc', `info', and `lib-src' -subdirectories. XEmacs adds these at appropriate places within the -various system-wide paths. +`M-x global-set-key KEY CMD ' + Defines KEY globally to run CMD. - There may be any number of package hierarchy directories. +`M-x local-set-key KEYS CMD ' + Defines KEY locally (in the major mode now in effect) to run CMD. -Directories and Paths ---------------------- +`M-x local-unset-key KEYS ' + Removes the local binding of KEY. - Here is a list of the various directories and paths XEmacs tries to -locate during startup. XEmacs distinguishes between directories and -paths specific to "version", "site", and "architecture" when looking -for them. - -`version-specific' - directories are specific to the version of XEmacs they belong to - and typically reside under `/lib/xemacs-'. - -`site-specific' - directories are independent of the version of XEmacs they belong - to and typically reside under `/lib/xemacs' - -`architecture-specific' - directories are specific both to the version of XEmacs and the - architecture it runs on and typically reside under - `/lib/xemacs-/'. - - During installation, all of these directories may also reside -directly under `', because that is where they are in the XEmacs -tarball. - - If XEmacs runs with the `-debug-paths' option (*note Command -Switches::), it will print the values of these variables, hopefully -aiding in debugging any problems which come up. - -`lisp-directory' - Contains the version-specific location of the Lisp files that come - with the core distribution of XEmacs. XEmacs will search it - recursively to a depth of 1 when setting up `load-path'. - -`load-path' - Is where XEmacs searches for XEmacs Lisp files with commands like - `load-library'. It contains the package lisp directories (see - further down) and the version-specific core Lisp directories. If - the environment variable `EMACSLOADPATH' is set at startup, its - directories are prepended to `load-path'. - -`Info-directory-list' - Contains the location of info files. (See *Note (info)::.) It - contains the package info directories and the version-specific core - documentation. Moreover, XEmacs will add `/usr/info', - `/usr/local/info' as well as the directories of the environment - variable `INFOPATH' to `Info-directory-list'. - -`exec-directory' - Is the directory of architecture-dependent files that come with - XEmacs, especially executable programs intended for XEmacs to - invoke. - -`exec-path' - Is the path for executables which XEmacs may want to start. It - contains the package executable paths as well as `exec-directory', - and the directories of the environment variables `PATH' and - `EMACSPATH'. - -`doc-directory' - Is the directory containing the architecture-specific `DOC' file - that contains documentation for XEmacs' commands. - -`data-directory' - Is the version-specific directory that contains core data files - XEmacs uses. It may be initialized from the `EMACSDATA' - environment variable. - -`data-directory-list' - Is the path where XEmacs looks for data files. It contains - package data directories as well as `data-directory'. - - -File: xemacs.info, Node: Basic, Next: Undo, Prev: Startup Paths, Up: Top - -Basic Editing Commands -********************** - - We now give the basics of how to enter text, make corrections, and -save the text in a file. If this material is new to you, you might -learn it more easily by running the Emacs learn-by-doing tutorial. To -use the tutorial, run Emacs and type `Control-h t' -(`help-with-tutorial'). You can also use Tutorials item from the Help -menu. - - XEmacs comes with many translations of tutorial. If your XEmacs is -with MULE and you set up language environment correctly, XEmacs chooses -right tutorial when available (*note Language Environments::). If you -want specific translation, give `C-h t' a prefix argument, like `C-u -C-h t'. - - To clear the screen and redisplay, type `C-l' (`recenter'). + CMD is a symbol naming an interactively-callable function. -* Menu: + When called interactively, KEY is the next complete key sequence +that you type. When called as a function, KEY is a string, a vector of +events, or a vector of key-description lists as described in the +`define-key' function description. The binding goes in the current +buffer's local map, which is shared with other buffers in the same +major mode. + + The following example: + + M-x global-set-key C-f next-line + +redefines `C-f' to move down a line. The fact that CMD is read second +makes it serve as a kind of confirmation for KEY. + + These functions offer no way to specify a particular prefix keymap as +the one to redefine in, but that is not necessary, as you can include +prefixes in KEY. KEY is read by reading characters one by one until +they amount to a complete key (that is, not a prefix key). Thus, if +you type `C-f' for KEY, Emacs enters the minibuffer immediately to read +CMD. But if you type `C-x', another character is read; if that +character is `4', another character is read, and so on. For example, + M-x global-set-key C-x 4 $ spell-other-window -* Inserting Text:: Inserting text by simply typing it. -* Moving Point:: How to move the cursor to the place where you want to - change something. -* Erasing:: Deleting and killing text. -* Files: Basic Files. Visiting, creating, and saving files. -* Help: Basic Help. Asking what a character does. -* Blank Lines:: Commands to make or delete blank lines. -* Continuation Lines:: Lines too wide for the screen. -* Position Info:: What page, line, row, or column is point on? -* Arguments:: Numeric arguments for repeating a command. +redefines `C-x 4 $' to run the (fictitious) command +`spell-other-window'. + + The most general way to modify a keymap is the function +`define-key', used in Lisp code (such as your init file). `define-key' +takes three arguments: the keymap, the key to modify in it, and the new +definition. *Note Init File::, for an example. +`substitute-key-definition' is used similarly; it takes three +arguments, an old definition, a new definition, and a keymap, and +redefines in that keymap all keys that were previously defined with the +old definition to have the new definition instead.  -File: xemacs.info, Node: Inserting Text, Next: Moving Point, Up: Basic +File: xemacs.info, Node: Programmatic Rebinding, Next: Key Bindings Using Strings, Prev: Interactive Rebinding, Up: Rebinding -Inserting Text -============== +Changing Key Bindings Programmatically +...................................... - To insert printing characters into the text you are editing, just -type them. This inserts the characters you type into the buffer at the -cursor (that is, at "point"; *note Point::). The cursor moves forward, -and any text after the cursor moves forward too. If the text in the -buffer is `FOOBAR', with the cursor before the `B', then if you type -`XX', you get `FOOXXBAR', with the cursor still before the `B'. - - To "delete" text you have just inserted, use . deletes the -character _before_ the cursor (not the one that the cursor is on top of -or under; that is the character AFTER the cursor). The cursor and all -characters after it move backwards. Therefore, if you type a printing -character and then type , they cancel out. - - To end a line and start typing a new one, type . This inserts -a newline character in the buffer. If point is in the middle of a -line, splits the line. Typing when the cursor is at the -beginning of a line deletes the preceding newline, thus joining the -line with the preceding line. - - Emacs can split lines automatically when they become too long, if you -turn on a special minor mode called "Auto Fill" mode. *Note Filling::, -for how to use Auto Fill mode. - - If you prefer to have text characters replace (overwrite) existing -text rather than shove it to the right, you can enable Overwrite mode, -a minor mode. *Note Minor Modes::. - - Direct insertion works for printing characters and , but other -characters act as editing commands and do not insert themselves. If you -need to insert a control character or a character whose code is above -200 octal, you must "quote" it by typing the character `Control-q' -(`quoted-insert') first. (This character's name is normally written -`C-q' for short.) There are two ways to use `C-q': - - * `C-q' followed by any non-graphic character (even `C-g') inserts - that character. - - * `C-q' followed by a sequence of octal digits inserts the character - with the specified octal character code. You can use any number of - octal digits; any non-digit terminates the sequence. If the - terminating character is , it serves only to terminate the - sequence; any other non-digit is itself used as input after - terminating the sequence. (The use of octal sequences is disabled - in ordinary non-binary Overwrite mode, to give you a convenient - way to insert a digit instead of overwriting with it.) - -A numeric argument to `C-q' specifies how many copies of the quoted -character should be inserted (*note Arguments::). - - Customization information: , in most modes, runs the command -`backward-or-forward-delete-char'; runs the command `newline', -and self-inserting printing characters run the command `self-insert', -which inserts whatever character was typed to invoke it. Some major -modes rebind to other commands. - - -File: xemacs.info, Node: Moving Point, Next: Erasing, Prev: Inserting Text, Up: Basic - -Changing the Location of Point -============================== - - To do more than insert characters, you have to know how to move point -(*note Point::). The simplest way to do this is with arrow keys, or by -clicking the left mouse button where you want to move to. - - NOTE: Many of the following commands have two versions, one that uses -the function keys (e.g. or ) and one that doesn't. The -former versions may only be available on X terminals (i.e. not on -TTY's), but the latter are available on all terminals. +You can use the functions `global-set-key' and `define-key' to rebind +keys under program control. -`C-a' -`HOME' - Move to the beginning of the line (`beginning-of-line'). +``(global-set-key KEYS CMD)'' + Defines KEYS globally to run CMD. -`C-e' -`END' - Move to the end of the line (`end-of-line'). +``(define-key KEYMAP KEYS DEF)'' + Defines KEYS to run DEF in the keymap KEYMAP. -`C-f' -`RIGHT' - Move forward one character (`forward-char'). + KEYMAP is a keymap object. -`C-b' -`LEFT' - Move backward one character (`backward-char'). + KEYS is the sequence of keystrokes to bind. -`M-f' -`C-RIGHT' - Move forward one word (`forward-word'). + DEF is anything that can be a key's definition: -`M-b' -`C-LEFT' - Move backward one word (`backward-word'). + * `nil', meaning key is undefined in this keymap -`C-n' -`DOWN' - Move down one line, vertically (`next-line'). This command - attempts to keep the horizontal position unchanged, so if you - start in the middle of one line, you end in the middle of the - next. When on the last line of text, `C-n' creates a new line and - moves onto it. + * A command, that is, a Lisp function suitable for interactive + calling -`C-p' -`UP' - Move up one line, vertically (`previous-line'). + * A string or key sequence vector, which is treated as a keyboard + macro -`C-v' -`PGDN' - Move down one page, vertically (`scroll-up'). + * A keymap to define a prefix key -`M-v' -`PGUP' - Move up one page, vertically (`scroll-down'). + * A symbol so that when the key is looked up, the symbol stands for + its function definition, which should at that time be one of the + above, or another symbol whose function definition is used, and so + on -`C-l' - Clear the frame and reprint everything (`recenter'). Text moves - on the frame to bring point to the center of the window. + * A cons, `(string . defn)', meaning that DEFN is the definition + (DEFN should be a valid definition in its own right) -`M-r' - Move point to left margin, vertically centered in the window - (`move-to-window-line'). Text does not move on the screen. + * A cons, `(keymap . char)', meaning use the definition of CHAR in + map KEYMAP - A numeric argument says which screen line to place point on. It - counts screen lines down from the top of the window (zero for the - top line). A negative argument counts lines from the bottom (-1 - for the bottom line). + For backward compatibility, XEmacs allows you to specify key +sequences as strings. However, the preferred method is to use the +representations of key sequences as vectors of keystrokes. *Note +Keystrokes::, for more information about the rules for constructing key +sequences. -`C-t' - Transpose two characters, the ones before and after the cursor - (`transpose-chars'). + Emacs allows you to abbreviate representations for key sequences in +most places where there is no ambiguity. Here are some rules for +abbreviation: -`M-<' -`C-HOME' - Move to the top of the buffer (`beginning-of-buffer'). With - numeric argument N, move to N/10 of the way from the top. *Note - Arguments::, for more information on numeric arguments. + * The keysym by itself is equivalent to a list of just that keysym, + i.e., `f1' is equivalent to `(f1)'. -`M->' -`C-END' - Move to the end of the buffer (`end-of-buffer'). + * A keystroke by itself is equivalent to a vector containing just + that keystroke, i.e., `(control a)' is equivalent to `[(control + a)]'. + + * You can use ASCII codes for keysyms that have them. i.e., `65' is + equivalent to `A'. (This is not so much an abbreviation as an + alternate representation.) + + Here are some examples of programmatically binding keys: + + + ;;; Bind `my-command' to + (global-set-key 'f1 'my-command) + + ;;; Bind `my-command' to Shift-f1 + (global-set-key '(shift f1) 'my-command) + + ;;; Bind `my-command' to C-c Shift-f1 + (global-set-key '[(control c) (shift f1)] 'my-command) + + ;;; Bind `my-command' to the middle mouse button. + (global-set-key 'button2 'my-command) + + ;;; Bind `my-command' to + ;;; in the keymap that is in force when you are running `dired'. + (define-key dired-mode-map '(meta control button3) 'my-command) + + +File: xemacs.info, Node: Key Bindings Using Strings, Prev: Programmatic Rebinding, Up: Rebinding + +Using Strings for Changing Key Bindings +....................................... + +For backward compatibility, you can still use strings to represent key +sequences. Thus you can use commands like the following: + + ;;; Bind `end-of-line' to C-f + (global-set-key "\C-f" 'end-of-line) + + Note, however, that in some cases you may be binding more than one +key sequence by using a single command. This situation can arise +because in ASCII, `C-i' and have the same representation. +Therefore, when Emacs sees: + + (global-set-key "\C-i" 'end-of-line) + + it is unclear whether the user intended to bind `C-i' or . The +solution XEmacs adopts is to bind both of these key sequences. -`M-x goto-char' - Read a number N and move point to buffer position N. Position 1 - is the beginning of the buffer. + After binding a command to two key sequences with a form like: -`M-g' - Read a number N and move point to line number N (`goto-line'). - Line 1 is the beginning of the buffer. + (define-key global-map "\^X\^I" 'command-1) -`M-x set-goal-column' - Use the current column of point as the "semi-permanent goal - column" for `C-n' and `C-p' (`set-goal-column'). Henceforth, those - commands always move to this column in each line moved into, or as - close as possible given the contents of the line. This goal - column remains in effect until canceled. + it is possible to redefine only one of those sequences like so: -`C-u M-x set-goal-column' - Cancel the goal column. Henceforth, `C-n' and `C-p' once again - try to avoid changing the horizontal position, as usual. + (define-key global-map [(control x) (control i)] 'command-2) + (define-key global-map [(control x) tab] 'command-3) - If you set the variable `track-eol' to a non-`nil' value, then `C-n' -and `C-p' when at the end of the starting line move to the end of -another line. Normally, `track-eol' is `nil'. *Note Variables::, for -how to set variables such as `track-eol'. + This applies only when running under a window system. If you are +talking to Emacs through an ASCII-only channel, you do not get any of +these features. - Normally, `C-n' on the last line of a buffer appends a newline to -it. If the variable `next-line-add-newlines' is `nil', then `C-n' gets -an error instead (like `C-p' on the first line). + Here is a table of pairs of key sequences that behave in a similar +fashion: + + control h backspace + control l clear + control i tab + control m return + control j linefeed + control [ escape + control @ control space  -File: xemacs.info, Node: Erasing, Next: Basic Files, Prev: Moving Point, Up: Basic +File: xemacs.info, Node: Disabling, Prev: Rebinding, Up: Key Bindings -Erasing Text -============ +Disabling Commands +------------------ -`' - Delete the character before or after point - (`backward-or-forward-delete-char'). You can customize this - behavior by setting the variable `delete-key-deletes-forward'. +Disabling a command marks it as requiring confirmation before it can be +executed. The purpose of disabling a command is to prevent beginning +users from executing it by accident and being confused. -`C-d' - Delete the character after point (`delete-char'). + The direct mechanism for disabling a command is to have a non-`nil' +`disabled' property on the Lisp symbol for the command. These +properties are normally set by the user's init file with Lisp +expressions such as: + + (put 'delete-region 'disabled t) -`C-k' - Kill to the end of the line (`kill-line'). + *Note Init File::. -`M-d' - Kill forward to the end of the next word (`kill-word'). + If the value of the `disabled' property is a string, that string is +included in the message printed when the command is used: -`M-' - Kill back to the beginning of the previous word - (`backward-kill-word'). + (put 'delete-region 'disabled + "Text deleted this way cannot be yanked back!\n") - You already know about the key which deletes the character -before point (that is, before the cursor). Another key, `Control-d' -(`C-d' for short), deletes the character after point (that is, the -character that the cursor is on). This shifts the rest of the text on -the line to the left. If you type `C-d' at the end of a line, it joins -together that line and the next line. + You can disable a command either by editing the init file directly +or with the command `M-x disable-command', which edits the init file +for you. *Note Init File::. - To erase a larger amount of text, use the `C-k' key, which kills a -line at a time. If you type `C-k' at the beginning or middle of a -line, it kills all the text up to the end of the line. If you type -`C-k' at the end of a line, it joins that line and the next line. + When you attempt to invoke a disabled command interactively in Emacs, +a window is displayed containing the command's name, its documentation, +and some instructions on what to do next; then Emacs asks for input +saying whether to execute the command as requested, enable it and +execute, or cancel it. If you decide to enable the command, you are +asked whether to do this permanently or just for the current session. +Enabling permanently works by automatically editing your init file. +You can use `M-x enable-command' at any time to enable any command +permanently. - *Note Killing::, for more flexible ways of killing text. + Whether a command is disabled is independent of what key is used to +invoke it; it also applies if the command is invoked using `M-x'. +Disabling a command has no effect on calling it as a function from Lisp +programs.  -File: xemacs.info, Node: Basic Files, Next: Basic Help, Prev: Erasing, Up: Basic +File: xemacs.info, Node: Syntax, Next: Init File, Prev: Key Bindings, Up: Customization -Files -===== +The Syntax Table +================ + +All the Emacs commands which parse words or balance parentheses are +controlled by the "syntax table". The syntax table specifies which +characters are opening delimiters, which are parts of words, which are +string quotes, and so on. Actually, each major mode has its own syntax +table (though sometimes related major modes use the same one) which it +installs in each buffer that uses that major mode. The syntax table +installed in the current buffer is the one that all commands use, so we +call it "the" syntax table. A syntax table is a Lisp object, a vector +of length 256 whose elements are numbers. + +* Menu: - The commands described above are sufficient for creating and altering -text in an Emacs buffer; the more advanced Emacs commands just make -things easier. But to keep any text permanently you must put it in a -"file". Files are named units of text which are stored by the -operating system for you to retrieve later by name. To look at or use -the contents of a file in any way, including editing the file with -Emacs, you must specify the file name. +* Entry: Syntax Entry. What the syntax table records for each character. +* Change: Syntax Change. How to change the information. - Consider a file named `/usr/rms/foo.c'. To begin editing this file -from Emacs, type: + +File: xemacs.info, Node: Syntax Entry, Next: Syntax Change, Up: Syntax + +Information About Each Character +-------------------------------- + +The syntax table entry for a character is a number that encodes six +pieces of information: + + * The syntactic class of the character, represented as a small + integer + + * The matching delimiter, for delimiter characters only (the + matching delimiter of `(' is `)', and vice versa) + + * A flag saying whether the character is the first character of a + two-character comment starting sequence + + * A flag saying whether the character is the second character of a + two-character comment starting sequence + + * A flag saying whether the character is the first character of a + two-character comment ending sequence + + * A flag saying whether the character is the second character of a + two-character comment ending sequence + + The syntactic classes are stored internally as small integers, but +are usually described to or by the user with characters. For example, +`(' is used to specify the syntactic class of opening delimiters. Here +is a table of syntactic classes, with the characters that specify them. + +`-' + The class of whitespace characters. Please don't use the formerly + advertised , which is not supported by GNU Emacs. + +`w' + The class of word-constituent characters. + +`_' + The class of characters that are part of symbol names but not + words. This class is represented by `_' because the character `_' + has this class in both C and Lisp. + +`.' + The class of punctuation characters that do not fit into any other + special class. + +`(' + The class of opening delimiters. + +`)' + The class of closing delimiters. + +`'' + The class of expression-adhering characters. These characters are + part of a symbol if found within or adjacent to one, and are part + of a following expression if immediately preceding one, but are + like whitespace if surrounded by whitespace. + +`"' + The class of string-quote characters. They match each other in + pairs, and the characters within the pair all lose their syntactic + significance except for the `\' and `/' classes of escape + characters, which can be used to include a string-quote inside the + string. + +`$' + The class of self-matching delimiters. This is intended for TeX's + `$', which is used both to enter and leave math mode. Thus, a + pair of matching `$' characters surround each piece of math mode + TeX input. A pair of adjacent `$' characters act like a single + one for purposes of matching. + +`/' + The class of escape characters that always just deny the following + character its special syntactic significance. The character after + one of these escapes is always treated as alphabetic. + +`\' + The class of C-style escape characters. In practice, these are + treated just like `/'-class characters, because the extra + possibilities for C escapes (such as being followed by digits) + have no effect on where the containing expression ends. + +`<' + The class of comment-starting characters. Only single-character + comment starters (such as `;' in Lisp mode) are represented this + way. + +`>' + The class of comment-ending characters. Newline has this syntax in + Lisp mode. + + The characters flagged as part of two-character comment delimiters +can have other syntactic functions most of the time. For example, `/' +and `*' in C code, when found separately, have nothing to do with +comments. The comment-delimiter significance overrides when the pair of +characters occur together in the proper order. Only the list and sexp +commands use the syntax table to find comments; the commands +specifically for comments have other variables that tell them where to +find comments. Moreover, the list and sexp commands notice comments +only if `parse-sexp-ignore-comments' is non-`nil'. This variable is set +to `nil' in modes where comment-terminator sequences are liable to +appear where there is no comment, for example, in Lisp mode where the +comment terminator is a newline but not every newline ends a comment. + + +File: xemacs.info, Node: Syntax Change, Prev: Syntax Entry, Up: Syntax + +Altering Syntax Information +--------------------------- + +It is possible to alter a character's syntax table entry by storing a +new number in the appropriate element of the syntax table, but it would +be hard to determine what number to use. Emacs therefore provides a +command that allows you to specify the syntactic properties of a +character in a convenient way. + + `M-x modify-syntax-entry' is the command to change a character's +syntax. It can be used interactively and is also used by major modes +to initialize their own syntax tables. Its first argument is the +character to change. The second argument is a string that specifies the +new syntax. When called from Lisp code, there is a third, optional +argument, which specifies the syntax table in which to make the change. +If not supplied, or if this command is called interactively, the third +argument defaults to the current buffer's syntax table. + + 1. The first character in the string specifies the syntactic class. + It is one of the characters in the previous table (*note Syntax + Entry::). + + 2. The second character is the matching delimiter. For a character + that is not an opening or closing delimiter, this should be a + space, and may be omitted if no following characters are needed. + + 3. The remaining characters are flags. The flag characters allowed + are: + + `1' + Flag this character as the first of a two-character comment + starting sequence. + + `2' + Flag this character as the second of a two-character comment + starting sequence. + + `3' + Flag this character as the first of a two-character comment + ending sequence. + + `4' + Flag this character as the second of a two-character comment + ending sequence. + + Use `C-h s' (`describe-syntax') to display a description of the +contents of the current syntax table. The description of each +character includes both the string you have to pass to +`modify-syntax-entry' to set up that character's current syntax, and +some English to explain that string if necessary. - C-x C-f /usr/rms/foo.c + +File: xemacs.info, Node: Init File, Next: Audible Bell, Prev: Syntax, Up: Customization -Here the file name is given as an "argument" to the command `C-x C-f' -(`find-file'). That command uses the "minibuffer" to read the -argument, and you type to terminate the argument (*note -Minibuffer::). +The Init File +============= - You can also use the Open... menu item from the File menu, then type -the name of the file to the prompt. +When you start Emacs, it normally loads either `.xemacs/init.el' or the +file `.emacs' (whichever comes first) in your home directory. This +file, if it exists, should contain Lisp code. It is called your +initialization file or "init file". Use the command line switch `-q' +to tell Emacs whether to load an init file (*note Entering Emacs::). +Use the command line switch `-user-init-file' (*note Command +Switches::) to tell Emacs to load a different file instead of +`~/.xemacs/init.el'/`~/.emacs'. + + When the init file is read, the variable `user-init-file' says which +init file was loaded. + + At some sites there is a "default init file", which is the library +named `default.el', found via the standard search path for libraries. +The Emacs distribution contains no such library; your site may create +one for local customizations. If this library exists, it is loaded +whenever you start Emacs. But your init file, if any, is loaded first; +if it sets `inhibit-default-init' non-`nil', then `default' is not +loaded. + + If you have a large amount of code in your init file, you should +byte-compile it to `~/.xemacs/init.elc' or `~/.emacs.elc'. - Emacs obeys the command by "visiting" the file: creating a buffer, -copying the contents of the file into the buffer, and then displaying -the buffer for you to edit. If you alter the text, you can "save" the -new text in the file by typing `C-x C-s' (`save-buffer') or choosing -Save Buffer from the File menu. This makes the changes permanent by -copying the altered buffer contents back into the file -`/usr/rms/foo.c'. Until you save, the changes exist only inside Emacs, -and the file `foo.c' is unaltered. +* Menu: - To create a file, visit the file with `C-x C-f' as if it already -existed or choose Open... from the File menu and provide the name for -the new file. Emacs will create an empty buffer in which you can -insert the text you want to put in the file. When you save the buffer -with `C-x C-s', or by choosing Save Buffer from the File menu, the file -is created. +* Init Syntax:: Syntax of constants in Emacs Lisp. +* Init Examples:: How to do some things with an init file. +* Terminal Init:: Each terminal type can have an init file. - To learn more about using files, *Note Files::. + +File: xemacs.info, Node: Init Syntax, Next: Init Examples, Up: Init File + +Init File Syntax +---------------- + +The init file contains one or more Lisp function call expressions. +Each consists of a function name followed by arguments, all surrounded +by parentheses. For example, `(setq fill-column 60)' represents a call +to the function `setq' which is used to set the variable `fill-column' +(*note Filling::) to 60. + + The second argument to `setq' is an expression for the new value of +the variable. This can be a constant, a variable, or a function call +expression. In the init file, constants are used most of the time. +They can be: + +Numbers + Integers are written in decimal, with an optional initial minus + sign. + + If a sequence of digits is followed by a period and another + sequence of digits, it is interpreted as a floating point number. + + The number prefixes `#b', `#o', and `#x' are supported to + represent numbers in binary, octal, and hexadecimal notation (or + radix). + +Strings + Lisp string syntax is the same as C string syntax with a few extra + features. Use a double-quote character to begin and end a string + constant. + + Newlines and special characters may be present literally in + strings. They can also be represented as backslash sequences: + `\n' for newline, `\b' for backspace, `\r' for return, `\t' for + tab, `\f' for formfeed (control-l), `\e' for escape, `\\' for a + backslash, `\"' for a double-quote, or `\OOO' for the character + whose octal code is OOO. Backslash and double-quote are the only + characters for which backslash sequences are mandatory. + + You can use `\C-' as a prefix for a control character, as in + `\C-s' for ASCII Control-S, and `\M-' as a prefix for a Meta + character, as in `\M-a' for Meta-A or `\M-\C-a' for Control-Meta-A. + +Characters + Lisp character constant syntax consists of a `?' followed by + either a character or an escape sequence starting with `\'. + Examples: `?x', `?\n', `?\"', `?\)'. Note that strings and + characters are not interchangeable in Lisp; some contexts require + one and some contexts require the other. + +True + `t' stands for `true'. + +False + `nil' stands for `false'. + +Other Lisp objects + Write a single-quote (') followed by the Lisp object you want.  -File: xemacs.info, Node: Basic Help, Next: Blank Lines, Prev: Basic Files, Up: Basic +File: xemacs.info, Node: Init Examples, Next: Terminal Init, Prev: Init Syntax, Up: Init File -Help -==== +Init File Examples +------------------ + +Here are some examples of doing certain commonly desired things with +Lisp expressions: + + * Make in C mode just insert a tab if point is in the middle + of a line. + + (setq c-tab-always-indent nil) + + Here we have a variable whose value is normally `t' for `true' and + the alternative is `nil' for `false'. + + * Make searches case sensitive by default (in all buffers that do not + override this). + + (setq-default case-fold-search nil) + + This sets the default value, which is effective in all buffers + that do not have local values for the variable. Setting + `case-fold-search' with `setq' affects only the current buffer's + local value, which is probably not what you want to do in an init + file. + + * Make Text mode the default mode for new buffers. + + (setq default-major-mode 'text-mode) + + Note that `text-mode' is used because it is the command for + entering the mode we want. A single-quote is written before it to + make a symbol constant; otherwise, `text-mode' would be treated as + a variable name. + + * Turn on Auto Fill mode automatically in Text mode and related + modes. + + (setq text-mode-hook + '(lambda () (auto-fill-mode 1))) + + Here we have a variable whose value should be a Lisp function. The + function we supply is a list starting with `lambda', and a single + quote is written in front of it to make it (for the purpose of this + `setq') a list constant rather than an expression. Lisp functions + are not explained here; for mode hooks it is enough to know that + `(auto-fill-mode 1)' is an expression that will be executed when + Text mode is entered. You could replace it with any other + expression that you like, or with several expressions in a row. + + (setq text-mode-hook 'turn-on-auto-fill) + + This is another way to accomplish the same result. + `turn-on-auto-fill' is a symbol whose function definition is + `(lambda () (auto-fill-mode 1))'. + + * Load the installed Lisp library named `foo' (actually a file + `foo.elc' or `foo.el' in a standard Emacs directory). + + (load "foo") + + When the argument to `load' is a relative pathname, not starting + with `/' or `~', `load' searches the directories in `load-path' + (*note Loading::). + + * Load the compiled Lisp file `foo.elc' from your home directory. + + (load "~/foo.elc") + + Here an absolute file name is used, so no searching is done. + + * Rebind the key `C-x l' to run the function `make-symbolic-link'. + + (global-set-key "\C-xl" 'make-symbolic-link) + + or + + (define-key global-map "\C-xl" 'make-symbolic-link) + + Note once again the single-quote used to refer to the symbol + `make-symbolic-link' instead of its value as a variable. + + * Do the same thing for C mode only. + + (define-key c-mode-map "\C-xl" 'make-symbolic-link) + + * Bind the function key to a command in C mode. Note that the + names of function keys must be lower case. + + (define-key c-mode-map 'f1 'make-symbolic-link) + + * Bind the shifted version of to a command. + + (define-key c-mode-map '(shift f1) 'make-symbolic-link) + + * Redefine all keys which now run `next-line' in Fundamental mode to + run `forward-line' instead. + + (substitute-key-definition 'next-line 'forward-line + global-map) + + * Make `C-x C-v' undefined. + + (global-unset-key "\C-x\C-v") + + One reason to undefine a key is so that you can make it a prefix. + Simply defining `C-x C-v ANYTHING' would make `C-x C-v' a prefix, + but `C-x C-v' must be freed of any non-prefix definition first. + + * Make `$' have the syntax of punctuation in Text mode. Note the + use of a character constant for `$'. + + (modify-syntax-entry ?\$ "." text-mode-syntax-table) + + * Enable the use of the command `eval-expression' without + confirmation. + + (put 'eval-expression 'disabled nil) + + +File: xemacs.info, Node: Terminal Init, Prev: Init Examples, Up: Init File + +Terminal-Specific Initialization +-------------------------------- + +Each terminal type can have a Lisp library to be loaded into Emacs when +it is run on that type of terminal. For a terminal type named +TERMTYPE, the library is called `term/TERMTYPE' and it is found by +searching the directories `load-path' as usual and trying the suffixes +`.elc' and `.el'. Normally it appears in the subdirectory `term' of +the directory where most Emacs libraries are kept. + + The usual purpose of the terminal-specific library is to define the +escape sequences used by the terminal's function keys using the library +`keypad.el'. See the file `term/vt100.el' for an example of how this +is done. + + When the terminal type contains a hyphen, only the part of the name +before the first hyphen is significant in choosing the library name. +Thus, terminal types `aaa-48' and `aaa-30-rv' both use the library +`term/aaa'. The code in the library can use `(getenv "TERM")' to find +the full terminal type name. + + The library's name is constructed by concatenating the value of the +variable `term-file-prefix' and the terminal type. Your init file can +prevent the loading of the terminal-specific library by setting +`term-file-prefix' to `nil'. *Note Init File::. + + The value of the variable `term-setup-hook', if not `nil', is called +as a function of no arguments at the end of Emacs initialization, after +both your init file and any terminal-specific library have been read. +*Note Init File::. You can set the value in the init file to override +part of any of the terminal-specific libraries and to define +initializations for terminals that do not have a library. + + +File: xemacs.info, Node: Audible Bell, Next: Faces, Prev: Init File, Up: Customization + +Changing the Bell Sound +======================= + +You can now change how the audible bell sounds using the variable +`sound-alist'. + + `sound-alist''s value is an list associating symbols with, among +other things, strings of audio-data. When `ding' is called with one of +the symbols, the associated sound data is played instead of the +standard beep. This only works if you are logged in on the console of a +machine with audio hardware. To listen to a sound of the provided type, +call the function `play-sound' with the argument SOUND. You can also +set the volume of the sound with the optional argument VOLUME. + + Each element of `sound-alist' is a list describing a sound. The +first element of the list is the name of the sound being defined. +Subsequent elements of the list are alternating keyword/value pairs: + +`sound' + A string of raw sound data, or the name of another sound to play. + The symbol `t' here means use the default X beep. + +`volume' + An integer from 0-100, defaulting to `bell-volume'. + +`pitch' + If using the default X beep, the pitch (Hz) to generate. + +`duration' + If using the default X beep, the duration (milliseconds). + + For compatibility, elements of `sound-alist' may also be of the form: + + ( SOUND-NAME . ) + ( SOUND-NAME ) + + You should probably add things to this list by calling the function +`load-sound-file'. + + Note that you can only play audio data if running on the console +screen of a machine with audio hardware which emacs understands, which +at this time means a Sun SparcStation, SGI, or HP9000s700. + + Also note that the pitch, duration, and volume options are available +everywhere, but most X servers ignore the `pitch' option. + + The variable `bell-volume' should be an integer from 0 to 100, with +100 being loudest, which controls how loud the sounds emacs makes +should be. Elements of the `sound-alist' may override this value. +This variable applies to the standard X bell sound as well as sound +files. + + If the symbol `t' is in place of a sound-string, Emacs uses the +default X beep. This allows you to define beep-types of different +volumes even when not running on the console. + + You can add things to this list by calling the function +`load-sound-file', which reads in an audio-file and adds its data to +the sound-alist. You can specify the sound with the SOUND-NAME argument +and the file into which the sounds are loaded with the FILENAME +argument. The optional VOLUME argument sets the volume. + + `load-sound-file (FILENAME SOUND-NAME &optional VOLUME)' + + To load and install some sound files as beep-types, use the function +`load-default-sounds' (note that this only works if you are on display +0 of a machine with audio hardware). + + The following beep-types are used by Emacs itself. Other Lisp +packages may use other beep types, but these are the ones that the C +kernel of Emacs uses. - If you forget what a key does, you can find out with the Help -character, which is `C-h' (or , which is an alias for `C-h'). Type -`C-h k' followed by the key you want to know about; for example, `C-h k -C-n' tells you all about what `C-n' does. `C-h' is a prefix key; `C-h -k' is just one of its subcommands (the command `describe-key'). The -other subcommands of `C-h' provide different kinds of help. Type `C-h' -twice to get a description of all the help facilities. *Note Help::. +`auto-save-error' + An auto-save does not succeed + +`command-error' + The Emacs command loop catches an error + +`undefined-key' + You type a key that is undefined + +`undefined-click' + You use an undefined mouse-click combination + +`no-completion' + Completion was not possible + +`y-or-n-p' + You type something other than the required `y' or `n' + +`yes-or-no-p' + You type something other than `yes' or `no' + + +File: xemacs.info, Node: Faces, Next: Frame Components, Prev: Audible Bell, Up: Customization + +Faces +===== + +XEmacs has objects called extents and faces. An "extent" is a region +of text and a "face" is a collection of textual attributes, such as +fonts and colors. Every extent is displayed in some face; therefore, +changing the properties of a face immediately updates the display of +all associated extents. Faces can be frame-local: you can have a +region of text that displays with completely different attributes when +its buffer is viewed from a different X window. + + The display attributes of faces may be specified either in Lisp or +through the X resource manager. + +Customizing Faces +----------------- + +You can change the face of an extent with the functions in this +section. All the functions prompt for a FACE as an argument; use +completion for a list of possible values. + +`M-x invert-face' + Swap the foreground and background colors of the given FACE. + +`M-x make-face-bold' + Make the font of the given FACE bold. When called from a program, + returns `nil' if this is not possible. + +`M-x make-face-bold-italic' + Make the font of the given FACE bold italic. When called from a + program, returns `nil' if not possible. + +`M-x make-face-italic' + Make the font of the given FACE italic. When called from a + program, returns `nil' if not possible. + +`M-x make-face-unbold' + Make the font of the given FACE non-bold. When called from a + program, returns `nil' if not possible. + +`M-x make-face-unitalic' + Make the font of the given FACE non-italic. When called from a + program, returns `nil' if not possible. + +`M-x make-face-larger' + Make the font of the given FACE a little larger. When called from + a program, returns `nil' if not possible. + +`M-x make-face-smaller' + Make the font of the given FACE a little smaller. When called + from a program, returns `nil' if not possible. + +`M-x set-face-background' + Change the background color of the given FACE. + +`M-x set-face-background-pixmap' + Change the background pixmap of the given FACE. + +`M-x set-face-font' + Change the font of the given FACE. + +`M-x set-face-foreground' + Change the foreground color of the given FACE. + +`M-x set-face-underline-p' + Change whether the given FACE is underlined. + + You can exchange the foreground and background color of the selected +FACE with the function `invert-face'. If the face does not specify both +foreground and background, then its foreground and background are set +to the background and foreground of the default face. When calling +this from a program, you can supply the optional argument FRAME to +specify which frame is affected; otherwise, all frames are affected. + + The work of `make-face-bold', `make-face-bold-italic', +`make-face-italic', `make-face-unbold', `make-face-unitalic' functions +is affected by `face-frob-from-locale-first' variable. If it is `nil', +those functions first try to manipulate device specific data like X +font names to obtain the desired font face specification. This may be +unsuitable in environments using different font face specifications for +different frames, non-Mule environments in particular. + + If the variable is non-`nil', those functions first try to figure +out whether the face font is the same as one of predefined faces: +`default', `bold', `italic', `bold-italic'. If it is the same, then +the new face font specification is set to be the same as that of a +corresponding predefined face. Thus if the predefined face is set up +properly for different frames, the same will hold for the face being +changed by the functions. This is the behavior one might desire in +non-Mule environments mentioned above: face being changed still looks +right in all frames. + + How predefined faces might be set up for different frames in such an +environments is described in *Note Face Resources::. + + You can set the background color of the specified FACE with the +function `set-face-background'. The argument `color' should be a +string, the name of a color. When called from a program, if the +optional FRAME argument is provided, the face is changed only in that +frame; otherwise, it is changed in all frames. + + You can set the background pixmap of the specified FACE with the +function `set-face-background-pixmap'. The pixmap argument NAME should +be a string, the name of a file of pixmap data. The directories listed +in the `x-bitmap-file-path' variable are searched. The bitmap may also +be a list of the form `(WIDTH HEIGHT DATA)', where WIDTH and HEIGHT are +the size in pixels, and DATA is a string containing the raw bits of the +bitmap. If the optional FRAME argument is provided, the face is +changed only in that frame; otherwise, it is changed in all frames. + + The variable `x-bitmap-file-path' takes as a value a list of the +directories in which X bitmap files may be found. If the value is +`nil', the list is initialized from the `*bitmapFilePath' resource. + + If the environment variable XBMLANGPATH is set, then it is consulted +before the `x-bitmap-file-path' variable. + + You can set the font of the specified FACE with the function +`set-face-font'. The FONT argument should be a string, the name of a +font. When called from a program, if the optional FRAME argument is +provided, the face is changed only in that frame; otherwise, it is +changed in all frames. + + You can set the foreground color of the specified FACE with the +function `set-face-foreground'. The argument COLOR should be a string, +the name of a color. If the optional FRAME argument is provided, the +face is changed only in that frame; otherwise, it is changed in all +frames. + + You can set underline the specified FACE with the function +`set-face-underline-p'. The argument UNDERLINE-P can be used to make +underlining an attribute of the face or not. If the optional FRAME +argument is provided, the face is changed only in that frame; +otherwise, it is changed in all frames. + + +File: xemacs.info, Node: Frame Components, Next: X Resources, Prev: Faces, Up: Customization + +Frame Components +================ + +You can control the presence and position of most frame components, such +as the menubar, toolbars, and gutters. + + This section is not written yet. Try the Lisp Reference Manual: +*Note Menubar: (lispref)Menubar, *Note Toolbar Intro: (lispref)Toolbar +Intro, and *Note Gutter Intro: (lispref)Gutter Intro.  -File: xemacs.info, Node: Blank Lines, Next: Continuation Lines, Prev: Basic Help, Up: Basic +File: xemacs.info, Node: X Resources, Prev: Frame Components, Up: Customization -Blank Lines +X Resources =========== - Here are special commands and techniques for putting in and taking -out blank lines. +Historically, XEmacs has used the X resource application class `Emacs' +for its resources. Unfortunately, GNU Emacs uses the same application +class, and resources are not compatible between the two Emacsen. This +sharing of the application class often leads to trouble if you want to +run both variants. -`C-o' - Insert one or more blank lines after the cursor (`open-line'). + Starting with XEmacs 21, XEmacs uses the class `XEmacs' if it finds +any XEmacs resources in the resource database when the X connection is +initialized. Otherwise, it will use the class `Emacs' for backwards +compatibility. The variable `x-emacs-application-class' may be +consulted to determine the application class being used. -`C-x C-o' - Delete all but one of many consecutive blank lines - (`delete-blank-lines'). + The examples in this section assume the application class is `Emacs'. - When you want to insert a new line of text before an existing line, -you can do it by typing the new line of text, followed by . -However, it may be easier to see what you are doing if you first make a -blank line and then insert the desired text into it. This is easy to do -using the key `C-o' (`open-line'), which inserts a newline after point -but leaves point in front of the newline. After `C-o', type the text -for the new line. `C-o F O O' has the same effect as `F O O ', -except for the final location of point. + The Emacs resources are generally set per-frame. Each Emacs frame +can have its own name or the same name as another, depending on the +name passed to the `make-frame' function. - You can make several blank lines by typing `C-o' several times, or -by giving it a numeric argument to tell it how many blank lines to make. -*Note Arguments::, for how. If you have a fill prefix, then `C-o' -command inserts the fill prefix on the new line, when you use it at the -beginning of a line. *Note Fill Prefix::. + You can specify resources for all frames with the syntax: - The easy way to get rid of extra blank lines is with the command -`C-x C-o' (`delete-blank-lines'). `C-x C-o' in a run of several blank -lines deletes all but one of them. `C-x C-o' on a solitary blank line -deletes that blank line. When point is on a nonblank line, `C-x C-o' -deletes any blank lines following that nonblank line. + Emacs*parameter: value + +or + + Emacs*EmacsFrame.parameter:value + +You can specify resources for a particular frame with the syntax: + + Emacs*FRAME-NAME.parameter: value + +* Menu: + +* Geometry Resources:: Controlling the size and position of frames. +* Iconic Resources:: Controlling whether frames come up iconic. +* Resource List:: List of resources settable on a frame or device. +* Face Resources:: Controlling faces using resources. +* Widgets:: The widget hierarchy for XEmacs. +* Menubar Resources:: Specifying resources for the menubar.  -File: xemacs.info, Node: Continuation Lines, Next: Position Info, Prev: Blank Lines, Up: Basic +File: xemacs.info, Node: Geometry Resources, Next: Iconic Resources, Up: X Resources -Continuation Lines -================== +Geometry Resources +------------------ + +To make the default size of all Emacs frames be 80 columns by 55 lines, +do this: + + Emacs*EmacsFrame.geometry: 80x55 + +To set the geometry of a particular frame named `fred', do this: + + Emacs*fred.geometry: 80x55 + +Important! Do not use the following syntax: + + Emacs*geometry: 80x55 + +You should never use `*geometry' with any X application. It does not +say "make the geometry of Emacs be 80 columns by 55 lines." It really +says, "make Emacs and all subwindows thereof be 80x55 in whatever units +they care to measure in." In particular, that is both telling the +Emacs text pane to be 80x55 in characters, and telling the menubar pane +to be 80x55 pixels, which is surely not what you want. + + As a special case, this geometry specification also works (and sets +the default size of all Emacs frames to 80 columns by 55 lines): - If you add too many characters to one line without breaking it with -, the line will grow to occupy two (or more) lines on the screen, -with a curved arrow at the extreme right margin of all but the last of -them. The curved arrow says that the following screen line is not -really a distinct line in the text, but just the "continuation" of a -line too long to fit the screen. Continuation is also called "line -wrapping". + Emacs.geometry: 80x55 - Sometimes it is nice to have Emacs insert newlines automatically when -a line gets too long. Continuation on the screen does not do that. Use -Auto Fill mode (*note Filling::) if that's what you want. +since that is the syntax used with most other applications (since most +other applications have only one top-level window, unlike Emacs). In +general, however, the top-level shell (the unmapped ApplicationShell +widget named `Emacs' that is the parent of the shell widgets that +actually manage the individual frames) does not have any interesting +resources on it, and you should set the resources on the frames instead. - Instead of continuation, long lines can be displayed by "truncation". -This means that all the characters that do not fit in the width of the -frame or window do not appear at all. They remain in the buffer, -temporarily invisible. Right arrow in the last column (instead of the -curved arrow) inform you that truncation is in effect. + The `-geometry' command-line argument sets only the geometry of the +initial frame created by Emacs. - Truncation instead of continuation happens whenever horizontal -scrolling is in use, and optionally in all side-by-side windows (*note -Windows::). You can enable truncation for a particular buffer by -setting the variable `truncate-lines' to non-`nil' in that buffer. -(*Note Variables::.) Altering the value of `truncate-lines' makes it -local to the current buffer; until that time, the default value is in -effect. The default is initially `nil'. *Note Locals::. + A more complete explanation of geometry-handling is - *Note Display Vars::, for additional variables that affect how text -is displayed. + * The `-geometry' command-line option sets the `Emacs.geometry' + resource, that is, the geometry of the ApplicationShell. + + * For the first frame created, the size of the frame is taken from + the ApplicationShell if it is specified, otherwise from the + geometry of the frame. + + * For subsequent frames, the order is reversed: First the frame, and + then the ApplicationShell. + + * For the first frame created, the position of the frame is taken + from the ApplicationShell (`Emacs.geometry') if it is specified, + otherwise from the geometry of the frame. + + * For subsequent frames, the position is taken only from the frame, + and never from the ApplicationShell. + + This is rather complicated, but it does seem to provide the most +intuitive behavior with respect to the default sizes and positions of +frames created in various ways.  -File: xemacs.info, Node: Position Info, Next: Arguments, Prev: Continuation Lines, Up: Basic +File: xemacs.info, Node: Iconic Resources, Next: Resource List, Prev: Geometry Resources, Up: X Resources -Cursor Position Information -=========================== +Iconic Resources +---------------- + +Analogous to `-geometry', the `-iconic' command-line option sets the +iconic flag of the ApplicationShell (`Emacs.iconic') and always applies +to the first frame created regardless of its name. However, it is +possible to set the iconic flag on particular frames (by name) by using +the `Emacs*FRAME-NAME.iconic' resource. + + +File: xemacs.info, Node: Resource List, Next: Face Resources, Prev: Iconic Resources, Up: X Resources + +Resource List +------------- + +Emacs frames accept the following resources: + +`geometry' (class `Geometry'): string + Initial geometry for the frame. *Note Geometry Resources::, for a + complete discussion of how this works. + +`iconic' (class `Iconic'): boolean + Whether this frame should appear in the iconified state. + +`internalBorderWidth' (class `InternalBorderWidth'): int + How many blank pixels to leave between the text and the edge of the + window. + +`interline' (class `Interline'): int + How many pixels to leave between each line (may not be + implemented). + +`menubar' (class `Menubar'): boolean + Whether newly-created frames should initially have a menubar. Set + to true by default. + +`initiallyUnmapped' (class `InitiallyUnmapped'): boolean + Whether XEmacs should leave the initial frame unmapped when it + starts up. This is useful if you are starting XEmacs as a server + (e.g. in conjunction with gnuserv or the external client widget). + You can also control this with the `-unmapped' command-line option. + +`barCursor' (class `BarColor'): boolean + Whether the cursor should be displayed as a bar, or the + traditional box. + +`cursorColor' (class `CursorColor'): color-name + The color of the text cursor. + +`scrollBarWidth' (class `ScrollBarWidth'): integer + How wide the vertical scrollbars should be, in pixels; 0 means no + vertical scrollbars. You can also use a resource specification of + the form `*scrollbar.width', or the usual toolkit scrollbar + resources: `*XmScrollBar.width' (Motif), `*XlwScrollBar.width' + (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend + that you use the toolkit resources, though, because they're + dependent on how exactly your particular build of XEmacs was + configured. + +`scrollBarHeight' (class `ScrollBarHeight'): integer + How high the horizontal scrollbars should be, in pixels; 0 means no + horizontal scrollbars. You can also use a resource specification + of the form `*scrollbar.height', or the usual toolkit scrollbar + resources: `*XmScrollBar.height' (Motif), `*XlwScrollBar.height' + (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend + that you use the toolkit resources, though, because they're + dependent on how exactly your particular build of XEmacs was + configured. + +`scrollBarPlacement' (class `ScrollBarPlacement'): string + Where the horizontal and vertical scrollbars should be positioned. + This should be one of the four strings `BOTTOM_LEFT', + `BOTTOM_RIGHT', `TOP_LEFT', and `TOP_RIGHT'. Default is + `BOTTOM_RIGHT' for the Motif and Lucid scrollbars and + `BOTTOM_LEFT' for the Athena scrollbars. + +`topToolBarHeight' (class `TopToolBarHeight'): integer +`bottomToolBarHeight' (class `BottomToolBarHeight'): integer +`leftToolBarWidth' (class `LeftToolBarWidth'): integer +`rightToolBarWidth' (class `RightToolBarWidth'): integer + Height and width of the four possible toolbars. + +`topToolBarShadowColor' (class `TopToolBarShadowColor'): color-name +`bottomToolBarShadowColor' (class `BottomToolBarShadowColor'): color-name + Color of the top and bottom shadows for the toolbars. NOTE: These + resources do _not_ have anything to do with the top and bottom + toolbars (i.e. the toolbars at the top and bottom of the frame)! + Rather, they affect the top and bottom shadows around the edges of + all four kinds of toolbars. + +`topToolBarShadowPixmap' (class `TopToolBarShadowPixmap'): pixmap-name +`bottomToolBarShadowPixmap' (class `BottomToolBarShadowPixmap'): pixmap-name + Pixmap of the top and bottom shadows for the toolbars. If set, + these resources override the corresponding color resources. NOTE: + These resources do _not_ have anything to do with the top and + bottom toolbars (i.e. the toolbars at the top and bottom of the + frame)! Rather, they affect the top and bottom shadows around the + edges of all four kinds of toolbars. + +`toolBarShadowThickness' (class `ToolBarShadowThickness'): integer + Thickness of the shadows around the toolbars, in pixels. + +`visualBell' (class `VisualBell'): boolean + Whether XEmacs should flash the screen rather than making an + audible beep. + +`bellVolume' (class `BellVolume'): integer + Volume of the audible beep. + +`useBackingStore' (class `UseBackingStore'): boolean + Whether XEmacs should set the backing-store attribute of the X + windows it creates. This increases the memory usage of the X + server but decreases the amount of X traffic necessary to update + the screen, and is useful when the connection to the X server goes + over a low-bandwidth line such as a modem connection. + + Emacs devices accept the following resources: + +`textPointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over text. This resource is + used to initialize the variable `x-pointer-shape'. + +`selectionPointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over a selectable text region + (an extent with the `highlight' property; for example, an Info + cross-reference). This resource is used to initialize the variable + `x-selection-pointer-shape'. + +`spacePointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over a blank space in a buffer + (that is, after the end of a line or after the end-of-file). This + resource is used to initialize the variable + `x-nontext-pointer-shape'. + +`modeLinePointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over a modeline. This + resource is used to initialize the variable `x-mode-pointer-shape'. + +`gcPointer' (class `Cursor'): cursor-name + The cursor to display when a garbage-collection is in progress. + This resource is used to initialize the variable + `x-gc-pointer-shape'. + +`scrollbarPointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over the scrollbar. This + resource is used to initialize the variable + `x-scrollbar-pointer-shape'. + +`pointerColor' (class `Foreground'): color-name +`pointerBackground' (class `Background'): color-name + The foreground and background colors of the mouse cursor. These + resources are used to initialize the variables + `x-pointer-foreground-color' and `x-pointer-background-color'. + + +File: xemacs.info, Node: Face Resources, Next: Widgets, Prev: Resource List, Up: X Resources - If you are accustomed to other display editors, you may be surprised -that Emacs does not always display the page number or line number of -point in the mode line. In Emacs, this information is only rarely -needed, and a number of commands are available to compute and print it. -Since text is stored in a way that makes it difficult to compute the -information, it is not displayed all the time. +Face Resources +-------------- -`M-x what-page' - Print page number of point, and line number within page. +The attributes of faces are also per-frame. They can be specified as: -`M-x what-line' - Print line number of point in the buffer. + Emacs.FACE_NAME.parameter: value -`M-x line-number-mode' - Toggle automatic display of current line number. +or -`M-=' - Print number of lines and characters in the current region - (`count-lines-region'). *Note Mark::, for information about the - region. + Emacs*FRAME_NAME.FACE_NAME.parameter: value + +Faces accept the following resources: + +`attributeFont' (class `AttributeFont'): font-name + The font of this face. + +`attributeForeground' (class `AttributeForeground'): color-name +`attributeBackground' (class `AttributeBackground'): color-name + The foreground and background colors of this face. + +`attributeBackgroundPixmap' (class `AttributeBackgroundPixmap'): file-name + The name of an XBM file (or XPM file, if your version of Emacs + supports XPM), to use as a background stipple. -`C-x =' - Print character code of character after point, character position - of point, and column of point (`what-cursor-position'). +`attributeUnderline' (class `AttributeUnderline'): boolean + Whether text in this face should be underlined. - There are several commands for printing line numbers: + All text is displayed in some face, defaulting to the face named +`default'. To set the font of normal text, use +`Emacs*default.attributeFont'. To set it in the frame named `fred', use +`Emacs*fred.default.attributeFont'. - * `M-x what-line' counts lines from the beginning of the file and - prints the line number point is on. The first line of the file is - line number 1. You can use these numbers as arguments to `M-x - goto-line'. + These are the names of the predefined faces: - * `M-x what-page' counts pages from the beginning of the file, and - counts lines within the page, printing both of them. *Note - Pages::, for the command `C-x l', which counts the lines in the - current page. +`default' + Everything inherits from this. - * `M-=' (`count-lines-region') prints the number of lines in the - region (*note Mark::). *Note Pages::, for the command `C-x l' - which counts the lines in the +`bold' + If this is not specified in the resource database, Emacs tries to + find a bold version of the font of the default face. - The command `C-x =' (`what-cursor-position') can be used to find out -the column that the cursor is in, and other miscellaneous information -about point. It prints a line in the echo area that looks like this: +`italic' + If this is not specified in the resource database, Emacs tries to + find an italic version of the font of the default face. - Char: c (0143, 99, 0x63) point=18862 of 24800(76%) column 53 +`bold-italic' + If this is not specified in the resource database, Emacs tries to + find a bold-italic version of the font of the default face. -(In fact, this is the output produced when point is before `column 53' -in the example.) +`modeline' + This is the face that the modeline is displayed in. If not + specified in the resource database, it is determined from the + default face by reversing the foreground and background colors. - The four values after `Char:' describe the character that follows -point, first by showing it and then by giving its character code in -octal, decimal and hex. +`highlight' + This is the face that highlighted extents (for example, Info + cross-references and possible completions, when the mouse passes + over them) are displayed in. - `point=' is followed by the position of point expressed as a -character count. The front of the buffer counts as position 1, one -character later as 2, and so on. The next, larger number is the total -number of characters in the buffer. Afterward in parentheses comes the -position expressed as a percentage of the total size. +`left-margin' +`right-margin' + These are the faces that the left and right annotation margins are + displayed in. - `column' is followed by the horizontal position of point, in columns -from the left edge of the window. +`zmacs-region' + This is the face that mouse selections are displayed in. - If the buffer has been narrowed, making some of the text at the -beginning and the end temporarily invisible, `C-x =' prints additional -text describing the current visible range. For example, it might say: +`isearch' + This is the face that the matched text being searched for is + displayed in. - Char: c (0143, 99, 0x63) point=19674 of 24575(80%) <19591 - 19703> column 69 +`info-node' + This is the face of info menu items. If unspecified, it is copied + from `bold-italic'. -where the two extra numbers give the smallest and largest character -position that point is allowed to assume. The characters between those -two positions are the visible ones. *Note Narrowing::. +`info-xref' + This is the face of info cross-references. If unspecified, it is + copied from `bold'. (Note that, when the mouse passes over a + cross-reference, the cross-reference's face is determined from a + combination of the `info-xref' and `highlight' faces.) - If point is at the end of the buffer (or the end of the visible -part), `C-x =' omits any description of the character after point. The -output looks like + Other packages might define their own faces; to see a list of all +faces, use any of the interactive face-manipulation commands such as +`set-face-font' and type `?' when you are prompted for the name of a +face. - point=563026 of 563025(100%) column 0 + If the `bold', `italic', and `bold-italic' faces are not specified +in the resource database, then XEmacs attempts to derive them from the +font of the default face. It can only succeed at this if you have +specified the default font using the XLFD (X Logical Font Description) +format, which looks like + + *-courier-medium-r-*-*-*-120-*-*-*-*-*-* + +If you use any of the other, less strict font name formats, some of +which look like + + lucidasanstypewriter-12 + fixed + 9x13 + + then XEmacs won't be able to guess the names of the bold and italic +versions. All X fonts can be referred to via XLFD-style names, so you +should use those forms. See the man pages for `X(1)', `xlsfonts(1)', +and `xfontsel(1)'.  -File: xemacs.info, Node: Arguments, Prev: Position Info, Up: Basic +File: xemacs.info, Node: Widgets, Next: Menubar Resources, Prev: Face Resources, Up: X Resources -Numeric Arguments -================= +Widgets +------- + +There are several structural widgets between the terminal EmacsFrame +widget and the top level ApplicationShell; the exact names and types of +these widgets change from release to release (for example, they changed +between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are +subject to further change in the future, so you should avoid mentioning +them in your resource database. The above-mentioned syntaxes should be +forward- compatible. As of 19.13, the exact widget hierarchy is as +follows: + + INVOCATION-NAME "shell" "container" FRAME-NAME + x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame" + + where INVOCATION-NAME is the terminal component of the name of the +XEmacs executable (usually `xemacs'), and `x-emacs-application-class' +is generally `Emacs'. + + +File: xemacs.info, Node: Menubar Resources, Prev: Widgets, Up: X Resources + +Menubar Resources +----------------- + +As the menubar is implemented as a widget which is not a part of XEmacs +proper, it does not use the face mechanism for specifying fonts and +colors: It uses whatever resources are appropriate to the type of widget +which is used to implement it. + + If Emacs was compiled to use only the Lucid Motif-lookalike menu +widgets, then one way to specify the font of the menubar would be + + Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-* + + If both the Lucid Motif-lookalike menu widgets and X Font Sets are +configured to allow multilingual menubars, then one uses + + *menubar*FontSet: -*-helvetica-bold-r-*-*-*-120-*-*-*-*-iso8859-*, \ + -*-*-*-*-*-*-*-120-*-jisx0208.1983-0 - In mathematics and computer usage, the word "argument" means "data -provided to a function or operation." Any Emacs command can be given a -"numeric argument" (also called a "prefix argument"). Some commands -interpret the argument as a repetition count. For example, giving an -argument of ten to the key `C-f' (the command `forward-char', move -forward one character) moves forward ten characters. With these -commands, no argument is equivalent to an argument of one. Negative -arguments are allowed. Often they tell a command to move or act in -the opposite direction. - - If your keyboard has a key (labelled with a diamond on -Sun-type keyboards and labelled `Alt' on some other keyboards), the -easiest way to specify a numeric argument is to type digits and/or a -minus sign while holding down the key. For example, - M-5 C-n - -would move down five lines. The characters `Meta-1', `Meta-2', and so -on, as well as `Meta--', do this because they are keys bound to -commands (`digit-argument' and `negative-argument') that are defined to -contribute to an argument for the next command. Digits and `-' -modified with Control, or Control and Meta, also specify numeric -arguments. - - Another way of specifying an argument is to use the `C-u' -(`universal-argument') command followed by the digits of the argument. -With `C-u', you can type the argument digits without holding down -modifier keys; `C-u' works on all terminals. To type a negative -argument, type a minus sign after `C-u'. Just a minus sign without -digits normally means -1. - - `C-u' followed by a character which is neither a digit nor a minus -sign has the special meaning of "multiply by four". It multiplies the -argument for the next command by four. `C-u' twice multiplies it by -sixteen. Thus, `C-u C-u C-f' moves forward sixteen characters. This -is a good way to move forward "fast", since it moves about 1/5 of a line -in the usual size frame. Other useful combinations are `C-u C-n', `C-u -C-u C-n' (move down a good fraction of a frame), `C-u C-u C-o' (make "a -lot" of blank lines), and `C-u C-k' (kill four lines). - - Some commands care only about whether there is an argument and not -about its value. For example, the command `M-q' (`fill-paragraph') with -no argument fills text; with an argument, it justifies the text as well. -(*Note Filling::, for more information on `M-q'.) Just `C-u' is a -handy way of providing an argument for such commands. - - Some commands use the value of the argument as a repeat count, but do -something peculiar when there is no argument. For example, the command -`C-k' (`kill-line') with argument N kills N lines, including their -terminating newlines. But `C-k' with no argument is special: it kills -the text up to the next newline, or, if point is right at the end of -the line, it kills the newline itself. Thus, two `C-k' commands with -no arguments can kill a non-blank line, just like `C-k' with an -argument of one. (*Note Killing::, for more information on `C-k'.) - - A few commands treat a plain `C-u' differently from an ordinary -argument. A few others may treat an argument of just a minus sign -differently from an argument of -1. These unusual cases are described -when they come up; they are always for reasons of convenience of use of -the individual command. - - You can use a numeric argument to insert multiple copies of a -character. This is straightforward unless the character is a digit; for -example, `C-u 6 4 a' inserts 64 copies of the character `a'. But this -does not work for inserting digits; `C-u 6 4 1' specifies an argument -of 641, rather than inserting anything. To separate the digit to -insert from the argument, type another `C-u'; for example, `C-u 6 4 C-u -1' does insert 64 copies of the character `1'. - - We use the term "prefix argument" as well as "numeric argument" to -emphasize that you type the argument before the command, and to -distinguish these arguments from minibuffer arguments that come after -the command. - - -File: xemacs.info, Node: Undo, Next: Minibuffer, Prev: Basic, Up: Top - -Undoing Changes -*************** - - Emacs allows you to undo all changes you make to the text of a -buffer, up to a certain amount of change (8000 characters). Each -buffer records changes individually, and the undo command always -applies to the current buffer. Usually each editing command makes a -separate entry in the undo records, but some commands such as -`query-replace' make many entries, and very simple commands such as -self-inserting characters are often grouped to make undoing less -tedious. + That would specify fonts for a Japanese menubar. Specifying only one +XLFD is acceptable; specifying more than one for a given registry +(language) is also allowed. When X Font Sets are configured, some .font +resources (eg, menubars) are ignored in favor of the corresponding +.fontSet resources. + + If the Motif library is being used, then one would have to use + + Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-* + + because the Motif library uses the `fontList' resource name instead +of `font', which has subtly different semantics. + + The same is true of the scrollbars: They accept whichever resources +are appropriate for the toolkit in use. + + +File: xemacs.info, Node: Quitting, Next: Lossage, Prev: Customization, Up: Top + +Quitting and Aborting +===================== + +`C-g' + Quit. Cancel running or partially typed command. + +`C-]' + Abort innermost recursive editing level and cancel the command + which invoked it (`abort-recursive-edit'). + +`M-x top-level' + Abort all recursive editing levels that are currently executing. `C-x u' - Undo one batch of changes (usually, one command's worth) (`undo'). + Cancel an already-executed command, usually (`undo'). + + There are two ways of cancelling commands which are not finished +executing: "quitting" with `C-g', and "aborting" with `C-]' or `M-x +top-level'. Quitting is cancelling a partially typed command or one +which is already running. Aborting is getting out of a recursive +editing level and cancelling the command that invoked the recursive +edit. + + Quitting with `C-g' is used for getting rid of a partially typed +command or a numeric argument that you don't want. It also stops a +running command in the middle in a relatively safe way, so you can use +it if you accidentally start executing a command that takes a long +time. In particular, it is safe to quit out of killing; either your +text will ALL still be there, or it will ALL be in the kill ring (or +maybe both). Quitting an incremental search does special things +documented under searching; in general, it may take two successive +`C-g' characters to get out of a search. `C-g' works by setting the +variable `quit-flag' to `t' the instant `C-g' is typed; Emacs Lisp +checks this variable frequently and quits if it is non-`nil'. `C-g' is +only actually executed as a command if it is typed while Emacs is +waiting for input. + + If you quit twice in a row before the first `C-g' is recognized, you +activate the "emergency escape" feature and return to the shell. *Note +Emergency Escape::. + + You can use `C-]' (`abort-recursive-edit') to get out of a recursive +editing level and cancel the command which invoked it. Quitting with +`C-g' does not do this, and could not do this because it is used to +cancel a partially typed command within the recursive editing level. +Both operations are useful. For example, if you are in the Emacs +debugger (*note Lisp Debug::) and have typed `C-u 8' to enter a numeric +argument, you can cancel that argument with `C-g' and remain in the +debugger. + + The command `M-x top-level' is equivalent to "enough" `C-]' commands +to get you out of all the levels of recursive edits that you are in. +`C-]' only gets you out one level at a time, but `M-x top-level' goes +out all levels at once. Both `C-]' and `M-x top-level' are like all +other commands and unlike `C-g' in that they are effective only when +Emacs is ready for a command. `C-]' is an ordinary key and has its +meaning only because of its binding in the keymap. *Note Recursive +Edit::. + + `C-x u' (`undo') is not strictly speaking a way of cancelling a +command, but you can think of it as cancelling a command already +finished executing. *Note Undo::. -`C-_' - The same. + +File: xemacs.info, Node: Lossage, Next: Bugs, Prev: Quitting, Up: Top - The command `C-x u' or `C-_' allows you to undo changes. The first -time you give this command, it undoes the last change. Point moves to -the text affected by the undo, so you can see what was undone. - - Consecutive repetitions of the `C-_' or `C-x u' commands undo -earlier and earlier changes, back to the limit of what has been -recorded. If all recorded changes have already been undone, the undo -command prints an error message and does nothing. - - Any command other than an undo command breaks the sequence of undo -commands. Starting at this moment, the previous undo commands are -considered ordinary changes that can themselves be undone. Thus, you -can redo changes you have undone by typing `C-f' or any other command -that have no important effect, and then using more undo commands. - - If you notice that a buffer has been modified accidentally, the -easiest way to recover is to type `C-_' repeatedly until the stars -disappear from the front of the mode line. When that happens, all the -modifications you made have been canceled. If you do not remember -whether you changed the buffer deliberately, type `C-_' once. When you -see Emacs undo the last change you made, you probably remember why you -made it. If the change was an accident, leave it undone. If it was -deliberate, redo the change as described in the preceding paragraph. - - Whenever an undo command makes the stars disappear from the mode -line, the buffer contents is the same as it was when the file was last -read in or saved. - - Not all buffers record undo information. Buffers whose names start -with spaces don't; these buffers are used internally by Emacs and its -extensions to hold text that users don't normally look at or edit. -Minibuffers, help buffers, and documentation buffers also don't record -undo information. - - Emacs can remember at most 8000 or so characters of deleted or -modified text in any one buffer for reinsertion by the undo command. -There is also a limit on the number of individual insert, delete, or -change actions that Emacs can remember. - - There are two keys to run the `undo' command, `C-x u' and `C-_', -because on some keyboards, it is not obvious how to type `C-_'. `C-x u' -is an alternative you can type in the same fashion on any terminal. - - -File: xemacs.info, Node: Minibuffer, Next: M-x, Prev: Undo, Up: Top - -The Minibuffer -************** - - The "minibuffer" is the facility used by XEmacs commands to read -arguments more complicated than a single number. Minibuffer arguments -can be file names, buffer names, Lisp function names, XEmacs command -names, Lisp expressions, and many other things, depending on the command -reading the argument. You can use the usual XEmacs editing commands in -the minibuffer to edit the argument text. - - When the minibuffer is in use, it appears in the echo area, and the -cursor moves there. The beginning of the minibuffer line displays a -"prompt" which says what kind of input you should supply and how it -will be used. Often this prompt is derived from the name of the command -that the argument is for. The prompt normally ends with a colon. - - Sometimes a "default argument" appears in parentheses after the -colon; it, too, is part of the prompt. The default is used as the -argument value if you enter an empty argument (e.g., by just typing -). For example, commands that read buffer names always show a -default, which is the name of the buffer that will be used if you type -just . - - The simplest way to enter a minibuffer argument is to type the text -you want, terminated by which exits the minibuffer. You can -cancel the command that wants the argument, and get out of the -minibuffer, by typing `C-g'. - - Since the minibuffer uses the screen space of the echo area, it can -conflict with other ways XEmacs customarily uses the echo area. Here is -how XEmacs handles such conflicts: - - * If a command gets an error while you are in the minibuffer, this - does not cancel the minibuffer. However, the echo area is needed - for the error message and therefore the minibuffer itself is - hidden for a while. It comes back after a few seconds, or as soon - as you type anything. - - * If in the minibuffer you use a command whose purpose is to print a - message in the echo area, such as `C-x =', the message is printed - normally, and the minibuffer is hidden for a while. It comes back - after a few seconds, or as soon as you type anything. - - * Echoing of keystrokes does not take place while the minibuffer is - in use. +Dealing With Emacs Trouble +========================== + +This section describes various conditions in which Emacs fails to work, +and how to recognize them and correct them. * Menu: -* File: Minibuffer File. Entering file names with the minibuffer. -* Edit: Minibuffer Edit. How to edit in the minibuffer. -* Completion:: An abbreviation facility for minibuffer input. -* Minibuffer History:: Reusing recent minibuffer arguments. -* Repetition:: Re-executing commands that used the minibuffer. +* Stuck Recursive:: `[...]' in mode line around the parentheses. +* Screen Garbled:: Garbage on the screen. +* Text Garbled:: Garbage in the text. +* Unasked-for Search:: Spontaneous entry to incremental search. +* Emergency Escape:: Emergency escape--- + What to do if Emacs stops responding. +* Total Frustration:: When you are at your wits' end. + + +File: xemacs.info, Node: Stuck Recursive, Next: Screen Garbled, Prev: Lossage, Up: Lossage + +Recursive Editing Levels +------------------------ + +Recursive editing levels are important and useful features of Emacs, but +they can seem like malfunctions to the user who does not understand +them. + + If the mode line has square brackets `[...]' around the parentheses +that contain the names of the major and minor modes, you have entered a +recursive editing level. If you did not do this on purpose, or if you +don't understand what that means, you should just get out of the +recursive editing level. To do so, type `M-x top-level'. This is +called getting back to top level. *Note Recursive Edit::. + + +File: xemacs.info, Node: Screen Garbled, Next: Text Garbled, Prev: Stuck Recursive, Up: Lossage + +Garbage on the Screen +--------------------- + +If the data on the screen looks wrong, the first thing to do is see +whether the text is actually wrong. Type `C-l', to redisplay the +entire screen. If the text appears correct after this, the problem was +entirely in the previous screen update. + + Display updating problems often result from an incorrect termcap +entry for the terminal you are using. The file `etc/TERMS' in the Emacs +distribution gives the fixes for known problems of this sort. +`INSTALL' contains general advice for these problems in one of its +sections. Very likely there is simply insufficient padding for certain +display operations. To investigate the possibility that you have this +sort of problem, try Emacs on another terminal made by a different +manufacturer. If problems happen frequently on one kind of terminal but +not another kind, the real problem is likely to be a bad termcap entry, +though it could also be due to a bug in Emacs that appears for terminals +that have or lack specific features. + + +File: xemacs.info, Node: Text Garbled, Next: Unasked-for Search, Prev: Screen Garbled, Up: Lossage + +Garbage in the Text +------------------- + +If `C-l' shows that the text is wrong, try undoing the changes to it +using `C-x u' until it gets back to a state you consider correct. Also +try `C-h l' to find out what command you typed to produce the observed +results. + + If a large portion of text appears to be missing at the beginning or +end of the buffer, check for the word `Narrow' in the mode line. If it +appears, the text is still present, but marked off-limits. To make it +visible again, type `C-x n w'. *Note Narrowing::. + + +File: xemacs.info, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage + +Spontaneous Entry to Incremental Search +--------------------------------------- + +If Emacs spontaneously displays `I-search:' at the bottom of the +screen, it means that the terminal is sending `C-s' and `C-q' according +to the poorly designed xon/xoff "flow control" protocol. You should +try to prevent this by putting the terminal in a mode where it will not +use flow control, or by giving it enough padding that it will never +send a `C-s'. If that cannot be done, you must tell Emacs to expect +flow control to be used, until you can get a properly designed terminal. + + Information on how to do these things can be found in the file +`INSTALL' in the Emacs distribution. + + +File: xemacs.info, Node: Emergency Escape, Next: Total Frustration, Prev: Unasked-for Search, Up: Lossage + +Emergency Escape +---------------- + +Because at times there have been bugs causing Emacs to loop without +checking `quit-flag', a special feature causes Emacs to be suspended +immediately if you type a second `C-g' while the flag is already set, +so you can always get out of XEmacs. Normally Emacs recognizes and +clears `quit-flag' (and quits!) quickly enough to prevent this from +happening. + + When you resume Emacs after a suspension caused by multiple `C-g', it +asks two questions before going back to what it had been doing: + + Auto-save? (y or n) + Abort (and dump core)? (y or n) + +Answer each one with `y' or `n' followed by . + + Saying `y' to `Auto-save?' causes immediate auto-saving of all +modified buffers in which auto-saving is enabled. + + Saying `y' to `Abort (and dump core)?' causes an illegal instruction +to be executed, dumping core. This is to enable a wizard to figure out +why Emacs was failing to quit in the first place. Execution does not +continue after a core dump. If you answer `n', execution does +continue. With luck, Emacs will ultimately check `quit-flag' and quit +normally. If not, and you type another `C-g', it is suspended again. + + If Emacs is not really hung, but is just being slow, you may invoke +the double `C-g' feature without really meaning to. In that case, +simply resume and answer `n' to both questions, and you will arrive at +your former state. Presumably the quit you requested will happen soon. + + The double-`C-g' feature may be turned off when Emacs is running +under a window system, since the window system always enables you to +kill Emacs or to create another window and run another program. + + +File: xemacs.info, Node: Total Frustration, Prev: Emergency Escape, Up: Lossage + +Help for Total Frustration +-------------------------- + +If using Emacs (or something else) becomes terribly frustrating and none +of the techniques described above solve the problem, Emacs can still +help you. + + First, if the Emacs you are using is not responding to commands, type +`C-g C-g' to get out of it and then start a new one. + + Second, type `M-x doctor '. + + The doctor will make you feel better. Each time you say something to +the doctor, you must end it by typing . This lets the +doctor know you are finished. + + +File: xemacs.info, Node: Bugs, Prev: Lossage, Up: Top + +Reporting Bugs +============== + +Sometimes you will encounter a bug in Emacs. Although we cannot promise +we can or will fix the bug, and we might not even agree that it is a +bug, we want to hear about bugs you encounter in case we do want to fix +them. + + To make it possible for us to fix a bug, you must report it. In +order to do so effectively, you must know when and how to do it. + +When Is There a Bug +------------------- + +If Emacs executes an illegal instruction, or dies with an operating +system error message that indicates a problem in the program (as +opposed to something like "disk full"), then it is certainly a bug. + + If Emacs updates the display in a way that does not correspond to +what is in the buffer, then it is certainly a bug. If a command seems +to do the wrong thing but the problem corrects itself if you type +`C-l', it is a case of incorrect display updating. + + Taking forever to complete a command can be a bug, but you must make +certain that it was really Emacs's fault. Some commands simply take a +long time. Type `C-g' and then `C-h l' to see whether the input Emacs +received was what you intended to type; if the input was such that you +KNOW it should have been processed quickly, report a bug. If you don't +know whether the command should take a long time, find out by looking +in the manual or by asking for assistance. + + If a command you are familiar with causes an Emacs error message in a +case where its usual definition ought to be reasonable, it is probably a +bug. + + If a command does the wrong thing, that is a bug. But be sure you +know for certain what it ought to have done. If you aren't familiar +with the command, or don't know for certain how the command is supposed +to work, then it might actually be working right. Rather than jumping +to conclusions, show the problem to someone who knows for certain. + + Finally, a command's intended definition may not be best for editing +with. This is a very important sort of problem, but it is also a +matter of judgment. Also, it is easy to come to such a conclusion out +of ignorance of some of the existing features. It is probably best not +to complain about such a problem until you have checked the +documentation in the usual ways, feel confident that you understand it, +and know for certain that what you want is not available. If you are +not sure what the command is supposed to do after a careful reading of +the manual, check the index and glossary for any terms that may be +unclear. If you still do not understand, this indicates a bug in the +manual. The manual's job is to make everything clear. It is just as +important to report documentation bugs as program bugs. + + If the online documentation string of a function or variable +disagrees with the manual, one of them must be wrong, so report the bug. + +How to Report a Bug +------------------- + +When you decide that there is a bug, it is important to report it and to +report it in a way which is useful. What is most useful is an exact +description of what commands you type, starting with the shell command +to run Emacs, until the problem happens. Always include the version +number of Emacs that you are using; type `M-x emacs-version' to print +this. + + The most important principle in reporting a bug is to report FACTS, +not hypotheses or categorizations. It is always easier to report the +facts, but people seem to prefer to strain to posit explanations and +report them instead. If the explanations are based on guesses about +how Emacs is implemented, they will be useless; we will have to try to +figure out what the facts must have been to lead to such speculations. +Sometimes this is impossible. But in any case, it is unnecessary work +for us. + + For example, suppose that you type `C-x C-f /glorp/baz.ugh ', +visiting a file which (you know) happens to be rather large, and Emacs +prints out `I feel pretty today'. The best way to report the bug is +with a sentence like the preceding one, because it gives all the facts +and nothing but the facts. + + Do not assume that the problem is due to the size of the file and +say, "When I visit a large file, Emacs prints out `I feel pretty +today'." This is what we mean by "guessing explanations". The problem +is just as likely to be due to the fact that there is a `z' in the file +name. If this is so, then when we got your report, we would try out +the problem with some "large file", probably with no `z' in its name, +and not find anything wrong. There is no way in the world that we +could guess that we should try visiting a file with a `z' in its name. + + Alternatively, the problem might be due to the fact that the file +starts with exactly 25 spaces. For this reason, you should make sure +that you inform us of the exact contents of any file that is needed to +reproduce the bug. What if the problem only occurs when you have typed +the `C-x a l' command previously? This is why we ask you to give the +exact sequence of characters you typed since starting to use Emacs. + + You should not even say "visit a file" instead of `C-x C-f' unless +you know that it makes no difference which visiting command is used. +Similarly, rather than saying "if I have three characters on the line," +say "after I type ` A B C C-p'," if that is the way you +entered the text. + + If you are not in Fundamental mode when the problem occurs, you +should say what mode you are in. + + If the manifestation of the bug is an Emacs error message, it is +important to report not just the text of the error message but a +backtrace showing how the Lisp program in Emacs arrived at the error. +To make the backtrace, you must execute the Lisp expression `(setq +debug-on-error t)' before the error happens (that is to say, you must +execute that expression and then make the bug happen). This causes the +Lisp debugger to run (*note Lisp Debug::). The debugger's backtrace +can be copied as text into the bug report. This use of the debugger is +possible only if you know how to make the bug happen again. Do note +the error message the first time the bug happens, so if you can't make +it happen again, you can report at least that. + + Check whether any programs you have loaded into the Lisp world, +including your init file, set any variables that may affect the +functioning of Emacs. *Note Init File::. Also, see whether the +problem happens in a freshly started Emacs without loading your init +file (start Emacs with the `-q' switch to prevent loading the init +file). If the problem does NOT occur then, it is essential that we +know the contents of any programs that you must load into the Lisp +world in order to cause the problem to occur. + + If the problem does depend on an init file or other Lisp programs +that are not part of the standard Emacs system, then you should make +sure it is not a bug in those programs by complaining to their +maintainers first. After they verify that they are using Emacs in a +way that is supposed to work, they should report the bug. + + If you can tell us a way to cause the problem without visiting any +files, please do so. This makes it much easier to debug. If you do +need files, make sure you arrange for us to see their exact contents. +For example, it can often matter whether there are spaces at the ends +of lines, or a newline after the last line in the buffer (nothing ought +to care whether the last line is terminated, but tell that to the bugs). + + The easy way to record the input to Emacs precisely is to write a +dribble file; execute the Lisp expression: + + (open-dribble-file "~/dribble") + +using `Meta-' or from the `*scratch*' buffer just after starting +Emacs. From then on, all Emacs input will be written in the specified +dribble file until the Emacs process is killed. + + For possible display bugs, it is important to report the terminal +type (the value of environment variable `TERM'), the complete termcap +entry for the terminal from `/etc/termcap' (since that file is not +identical on all machines), and the output that Emacs actually sent to +the terminal. The way to collect this output is to execute the Lisp +expression: + + (open-termscript "~/termscript") + +using `Meta-' or from the `*scratch*' buffer just after starting +Emacs. From then on, all output from Emacs to the terminal will be +written in the specified termscript file as well, until the Emacs +process is killed. If the problem happens when Emacs starts up, put +this expression into your init file so that the termscript file will be +open when Emacs displays the screen for the first time. *Note Init +File::. Be warned: it is often difficult, and sometimes impossible, to +fix a terminal-dependent bug without access to a terminal of the type +that stimulates the bug. + + The newsgroup `comp.emacs.xemacs' may be used for bug reports, other +discussions and requests for assistance. + + If you don't have access to this newgroup, you can subscribe to the +mailing list version: the newsgroup is bidirectionally gatewayed into +the mailing list `xemacs@xemacs.org'. + + To be added or removed from this mailing list, send mail to +`xemacs-request@xemacs.org'. Do not send requests for addition to the +mailing list itself. + + The mailing lists and newsgroups are archived on our anonymous FTP +server, `ftp.xemacs.org', and at various other archive sites around the +net. You should also check the `FAQ' in `/pub/xemacs' on our anonymous +FTP server. It provides some introductory information and help for +initial configuration problems.