+\1f
+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 <RET>. 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::.
+
+\1f
+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.
+
+\1f
+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
+<http://cvs.xemacs.org/> for details.
+
+\1f
+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 `<package-name>-<version>-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.
+
+\1f
+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 <RET> 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.
+
+ `<RET>'
+ `<Mouse-2>'
+ Toggle between selecting and unselecting a package for
+ installation.
+
+ `x'
+ Install selected packages.
+
+ `<SPC>'
+ 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 <return>
+
+ 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
+
+\1f
+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-<version>-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
+
+\1f
+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 <tarballname> | tar xvf - RET'
+
+ Or, if you have GNU tar:
+
+ `cd $prefix/lib/xemacs ; tar zxvf /path/to/<tarballname> 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+<http://cvs.xemacs.org/> 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.
+
+\1f
+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.
+
+\1f
+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
+<xemacs-beta@xemacs.org>.
+
+ 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.
+
+\1f
+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 <SPC>'.
+
+ 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.
+
+\1f
+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 <RET>'.
+
+ 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.
+
+\1f
+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 (<SPC>, 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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. <RET> 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. <DEL>
+(`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. <LFD>
+(`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::).
+
+\1f
+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.
+
+\1f
+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-<TAB>' (`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-<TAB>', the
+command moves to the next such interesting character in the current
+line. `M-<TAB>' 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 `"!-~"'.
+
+ <TAB> 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 <TAB>' (`picture-set-tab-stops'.) This
+command sets the tab stops to the positions which `M-<TAB>' would
+consider significant in the current line. If you use this command with
+<TAB>, you can get the effect of context-based tabbing. But `M-<TAB>'
+is more convenient in the cases where it is sufficient.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <doe@quux.com>"
+
+ 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.
+
+\1f
+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').
+
+`<button3>'
+ 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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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').
+
+\1f
+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'
+`<NEXT>'
+ Scroll calendar three months forward
+ (`scroll-calendar-left-three-months').
+
+`M-v'
+`<PRIOR>'
+ 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 <NEXT> and <PRIOR> are equivalent to `C-v' and
+`M-v', just as they are in other modes.
+
+\1f
+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.
+
+\1f
+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.)
+
+\1f
+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).
+
+\1f
+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 <SPC> 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.
+
+\1f
+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::.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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').
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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") ... )
+
+\1f
+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))
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.)
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+<RET>.
+
+ 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 <M-p>, the previous shell input is inserted into the
+buffer before point. Immediately typing <M-p> again deletes that input
+and inserts the one before it. By repeating <M-p> you can move
+backward through your commands until you find one you want to repeat.
+You may then edit the command before typing <RET> if you wish. <M-n>
+moves forward through the command history, in case you moved backward
+past the one you wanted while using <M-p>. If you type the first few
+characters of a previous command and then type <M-p>, 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.
+
+\1f
+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:
+
+`<RET>'
+ 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
+ <RET>.
+
+`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
+ <M-p> quickly and go past the desired command
+ (`comint-next-input').
+
+`<TAB>'
+ Complete the file name preceding point (`comint-dynamic-complete').
+
+\1f
+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.
+
+\1f
+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 <C-c> to the sub-shell.
+
+`C-c C-x'
+ A prefix command to conveniently access the global <C-x> commands.
+ For example, `C-c C-x o' invokes the global binding of `C-x o',
+ which is normally `other-window'.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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'.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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 <SPC> 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.
+
+\1f
+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.
+
+\1f
+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 <RET>
+
+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 <RET> fill-column <RET> 75 <RET>
+
+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.
+
+\1f
+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.
+
+\1f
+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 <RET>.
+
+ 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.
+
+\1f
+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 <RET>. 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-<TAB>' (`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, <TAB> and `S-<TAB>', are useful for moving
+through the customization buffer. <TAB> (`widget-forward') moves
+forward to the next active or editable field; `S-<TAB>'
+(`widget-backward') moves backward to the previous active or editable
+field.
+
+ Typing <RET> on an editable field also moves forward, just like
+<TAB>. The reason for this is that people have a tendency to type
+<RET> 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.
+
+\1f
+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]'.
+
+\1f
+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 <RET> OPTION <RET>'
+ Set up a customization buffer with just one option, OPTION.
+
+`M-x customize-face <RET> FACE <RET>'
+ Set up a customization buffer with just one face, FACE.
+
+`M-x customize-group <RET> GROUP <RET>'
+ Set up a customization buffer with just one group, GROUP.
+
+`M-x customize-apropos <RET> REGEXP <RET>'
+ 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.
+
+\1f
+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.
+
+\1f
+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)
+
+\1f
+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.
+
+\1f
+File: xemacs.info, Node: Keyboard Macros, Next: Key Bindings, Prev: Variables, Up: Customization