-This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+This is ../info/xemacs.info, produced by makeinfo version 4.6 from
xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
translation approved by the author instead of in the original English.
\1f
-File: xemacs.info, Node: Options Menu, Next: Buffers Menu, Prev: Apps Menu, Up: Pull-down Menus
+File: xemacs.info, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Running
+
+Lisp Interaction Buffers
+========================
+
+The buffer `*scratch*', which is selected when Emacs starts up, is
+provided for evaluating Lisp expressions interactively inside Emacs.
+Both the expressions you evaluate and their output goes in the buffer.
+
+ The `*scratch*' buffer's major mode is Lisp Interaction mode, which
+is the same as Emacs-Lisp mode except for one command, <LFD>. In
+Emacs-Lisp mode, <LFD> is an indentation command. In Lisp Interaction
+mode, <LFD> is bound to `eval-print-last-sexp'. This function reads
+the Lisp expression before point, evaluates it, and inserts the value
+in printed representation before point.
+
+ The way to use the `*scratch*' buffer is to insert Lisp expressions
+at the end, ending each one with <LFD> so that it will be evaluated.
+The result is a complete typescript of the expressions you have
+evaluated and their values.
+
+ The rationale for this feature is that Emacs must have a buffer when
+it starts up, but that buffer is not useful for editing files since a
+new buffer is made for every file that you visit. The Lisp interpreter
+typescript is the most useful thing I can think of for the initial
+buffer to do. `M-x lisp-interaction-mode' will put any buffer in Lisp
+Interaction mode.
-The Options Menu
-----------------
+\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::.
- The Options pull-down menu contains the Read Only, Case Sensitive
-Search, Overstrike, Auto Delete Selection, Teach Extended Commands,
-Syntax Highlighting, Paren Highlighting, Font, Size, Weight, Buffers
-Menu Length..., Buffers Sub-Menus and Save Options menu items. When
-you select a menu item, Emacs executes the equivalent command. For
-some of the menu items, there are sub-menus which you will need to
-select.
-
-Read Only
- Selecting this item will cause the buffer to visit the file in a
- read-only mode. Changes to the file will not be allowed. This is
- equivalent to the Emacs command `toggle-read-only' (`C-x C-q').
-
-Case Sensitive Search
- Selecting this item will cause searches to be case-sensitive. If
- its not selected then searches will ignore case. This option is
- local to the buffer.
-
-Overstrike
- After selecting this item, when you type letters they will replace
- existing text on a one-to-one basis, rather than pushing it to the
- right. At the end of a line, such characters extend the line.
- Before a tab, such characters insert until the tab is filled in.
- This is the same as Emacs command `quoted-insert' (`C-q').
-
-Auto Delete Selection
- Selecting this item will cause automatic deletion of the selected
- region. The typed text will replace the selection if the selection
- is active (i.e. if its highlighted). If the option is not selected
- then the typed text is just inserted at the point.
-
-Teach Extended Commands
- After you select this item, any time you execute a command with
- `M-x'which has a shorter keybinding, you will be shown the
- alternate binding before the command executes.
-
-Syntax Highlighting
- You can customize your init file to include the font-lock mode so
- that when you select this item, the comments will be displayed in
- one face, strings in another, reserved words in another, and so
- on. *Note Init File::. When Fonts is selected, different parts of
- the program will appear in different Fonts. When Colors is
- selected, then the program will be displayed in different colors.
- Selecting None causes the program to appear in just one Font and
- Color. Selecting Less resets the Fonts and Colors to a fast,
- minimal set of decorations. Selecting More resets the Fonts and
- Colors to a larger set of decorations. For example, if Less is
- selected (which is the default setting) then you might have all
- comments in green color. Whereas, if More is selected then a
- function name in the comments themselves might appear in a
- different Color or Font.
-
-Paren Highlighting
- After selecting Blink from this item, if you place the cursor on a
- parenthesis, the matching parenthesis will blink. If you select
- Highlight and place the cursor on a parenthesis, the whole
- expression of the parenthesis under the cursor will be highlighted.
- Selecting None will turn off the options (regarding Paren
- Highlighting) which you had selected earlier.
-
-Font
- You can select any Font for your program by choosing from one of
- the available Fonts.
-
-Size
- You can select any size ranging from 2 to 24 by selecting the
- appropriate option.
-
-Weight
- You can choose either Bold or Medium for the weight.
-
-Buffers Menu Length...
- Prompts you for the number of buffers to display. Then it will
- display that number of most recently selected buffers.
-
-Buffers Sub-Menus
- After selection of this item the Buffers menu will contain several
- commands, as submenus of each buffer line. If this item is
- unselected, then there are no submenus for each buffer line, the
- only command available will be selecting that buffer.
-
-Save Options
- Selecting this item will save the current settings of your Options
- menu to your init file. *Note Init File::.
-
-\1f
-File: xemacs.info, Node: Buffers Menu, Next: Tools Menu, Prev: Options Menu, Up: Pull-down Menus
-
-The Buffers Menu
-----------------
+\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:
- The Buffers menu provides a selection of up to ten buffers and the
-item List All Buffers, which provides a Buffer List. *Note List
-Buffers::, for more information.
+* 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: Tools Menu, Next: Help Menu, Prev: Buffers Menu, Up: Pull-down Menus
+File: xemacs.info, Node: Package Terminology, Next: Installing Packages, Up: Packages
-The Tools Menu
---------------
+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.
- The Tools pull-down menu contains the Grep..., Compile..., Shell
-Command..., Shell Command on Region..., Debug(GDB)... and
-Debug(DBX)... menu items, and the Compare, Merge, Apply Patch and Tags
-sub-menus. When you select a menu item, Emacs executes the equivalent
-command. For some of the menu items, there are sub-menus which you
-will need to select.
+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: Help Menu, Next: Menu Customization, Prev: Tools Menu, Up: Pull-down Menus
+File: xemacs.info, Node: Installing Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages
-The Help Menu
--------------
+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'
- The Help Menu gives you access to Emacs Info and provides a menu
-equivalent for each of the choices you have when using `C-h'. *Note
-Help::, for more information.
+ 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.
- The Help menu also gives access to UNIX online manual pages via the
-UNIX Manual Page option.
+ 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: Menu Customization, Prev: Help Menu, Up: Pull-down Menus
+File: xemacs.info, Node: Automatically, Next: Manually, Up: Installing Packages
-Customizing XEmacs Menus
-------------------------
+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.
- You can customize any of the pull-down menus by adding or removing
-menu items and disabling or enabling existing menu items.
+ After installing these by hand, fire up XEmacs and follow these
+steps.
- The following functions are available:
-`add-menu: (MENU-PATH MENU-NAME MENU-ITEMS &optional BEFORE)'
- Add a menu to the menu bar or one of its submenus.
+ 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)
-`add-menu-item: (MENU-PATH ITEM-NAME FUNCTION'
- ENABLED-P &optional BEFORE) Add a menu item to a menu, creating
- the menu first if necessary.
+ 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'
-`delete-menu-item: (PATH)'
- Remove the menu item defined by PATH from the menu hierarchy.
+ 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'
-`disable-menu-item: (PATH)'
- Disable the specified menu item.
+ XEmacs will now connect to the remote site and download the latest
+ package-index file.
-`enable-menu-item: (PATH)'
- Enable the specified previously disabled menu item.
+ 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:
-`relabel-menu-item: (PATH NEW-NAME)'
- Change the string of the menu item specified by PATH to NEW-NAME.
+ `-'
+ The package has not been installed.
- Use the function `add-menu' to add a new menu or submenu. If a menu
-or submenu of the given name exists already, it is changed.
+ `*'
+ The package has been installed, but a newer version is
+ available. The current version is out-of-date.
- MENU-PATH identifies the menu under which the new menu should be
-inserted. It is a list of strings; for example, `("File")' names the
-top-level File menu. `("File" "Foo")' names a hypothetical submenu of
-File. If MENU-PATH is `nil', the menu is added to the menu bar itself.
+ `+'
+ The package has been marked for installation/update.
- MENU-NAME is the string naming the menu to be added.
+ If there is no character in the first column, the package has been
+ installed and is up to date.
- MENU-ITEMS is a list of menu item descriptions. Each menu item
-should be a vector of three elements:
+ 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.
- * A string, which is the name of the menu item
+ Key summary:
- * A symbol naming a command, or a form to evaluate
+ `?'
+ Display simple help.
- * `t' or `nil' to indicate whether the item is selectable
+ `<RET>'
+ `<Mouse-2>'
+ Toggle between selecting and unselecting a package for
+ installation.
- The optional argument BEFORE is the name of the menu before which
-the new menu or submenu should be added. If the menu is already
-present, it is not moved.
+ `x'
+ Install selected packages.
- The function `add-menu-item' adds a menu item to the specified menu,
-creating the menu first if necessary. If the named item already
-exists, the menu remains unchanged.
+ `<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.
- MENU-PATH identifies the menu into which the new menu item should be
-inserted. It is a list of strings; for example, `("File")' names the
-top-level File menu. `("File" "Foo")' names a hypothetical submenu of
-File.
+ `v'
+ Toggle between verbose and non-verbose package display.
- ITEM-NAME is the string naming the menu item to add.
+ `g'
+ Refresh the package display.
- FUNCTION is the command to invoke when this menu item is selected.
-If it is a symbol, it is invoked with `call-interactively', in the same
-way that functions bound to keys are invoked. If it is a list, the
-list is simply evaluated.
+ `q'
+ Kill the package buffer.
- ENABLED-P controls whether the item is selectable or not. It should
-be `t', `nil', or a form to evaluate to decide. This form will be
-evaluated just before the menu is displayed, and the menu item will be
-selectable if that form returns non-`nil'.
+ 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.
- For example, to make the `rename-file' command available from the
-File menu, use the following code:
+ 3. Choose the packages you wish to install. mouse: Click button 2 on
+ the package name. keyb: `RET' on the package name
- (add-menu-item '("File") "Rename File" 'rename-file t)
+ 4. Make sure you have everything you need. menu: Packages -> Add
+ Required keyb: `r'
- To add a submenu of file management commands using a File Management
-item, use the following code:
+ 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.
- (add-menu-item '("File" "File Management") "Copy File" 'copy-file t)
- (add-menu-item '("File" "File Management") "Delete File" 'delete-file t)
- (add-menu-item '("File" "File Management") "Rename File" 'rename-file t)
+ For novices and gurus alike, this step can save your bacon. It's
+ easy to forget to install a critical package.
- The optional BEFORE argument is the name of a menu item before which
-the new item should be added. If the item is already present, it is
-not moved.
+ 5. Download and install the packages. menu: Packages ->
+ Install/Remove Selected keyb: `x'
- To remove a specified menu item from the menu hierarchy, use
-`delete-menu-item'.
+ You can also install packages using a semi-manual interface:
- PATH is a list of strings that identify the position of the menu
-item in the menu hierarchy. `("File" "Save")' means the menu item
-called Save under the top level File menu. `("Menu" "Foo" "Item")'
-means the menu item called Item under the Foo submenu of Menu.
+ M-x package-get-all <return>
- To disable a menu item, use `disable-menu-item'. The disabled menu
-item is grayed and can no longer be selected. To make the item
-selectable again, use `enable-menu-item'. `disable-menu-item' and
-`enable-menu-item' both have the argument PATH.
+ 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.
- To change the string of the specified menu item, use
-`relabel-menu-item'. This function also takes the argument PATH.
+Keeping Packages Up To Date:
+============================
- NEW-NAME is the string to which the menu item will be changed.
+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: Entering Emacs, Next: Exiting, Prev: Pull-down Menus, Up: Top
+File: xemacs.info, Node: Manually, Next: Sumo, Prev: Automatically, Up: Installing Packages
-Entering and Exiting Emacs
-**************************
+Manual Package Installation:
+============================
- The usual way to invoke XEmacs is to type `xemacs <RET>' at the
-shell. XEmacs clears the screen and then displays an initial advisory
-message and copyright notice. You can begin typing XEmacs commands
-immediately afterward.
+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.
- Some operating systems insist on discarding all type-ahead when
-XEmacs starts up; they give XEmacs no way to prevent this. Therefore,
-it is advisable to wait until XEmacs clears the screen before typing
-your first editing command.
+ Note: If you are upgrading packages already installed, it's best to
+remove the old package first *Note Removing Packages::.
- If you run XEmacs from a shell window under the X Window System, run
-it in the background with `xemacs&'. This way, XEmacs does not tie up
-the shell window, so you can use that to run other shell commands while
-XEmacs operates its own X windows. You can begin typing XEmacs commands
-as soon as you direct your keyboard input to the XEmacs frame.
+ For example if we are installing the `xemacs-base' package (version
+1.48):
- Before Emacs reads the first command, you have not had a chance to
-give a command to specify a file to edit. Since Emacs must always have
-a current buffer for editing, it presents a buffer, by default, a buffer
-named `*scratch*'. The buffer is in Lisp Interaction mode; you can use
-it to type Lisp expressions and evaluate them, or you can ignore that
-capability and simply doodle. (You can specify a different major mode
-for this buffer by setting the variable `initial-major-mode' in your
-init file. *Note Init File::.)
+ 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
- It is possible to specify files to be visited, Lisp files to be
-loaded, and functions to be called, by giving Emacs arguments in the
-shell command line. *Note Command Switches::. But we don't recommend
-doing this. The feature exists mainly for compatibility with other
-editors.
+ For MULE related packages, it is best to untar into the mule-packages
+hierarchy, i.e. for the `mule-base' package, version 1.37:
- Many other editors are designed to be started afresh each time you
-want to edit. You edit one file and then exit the editor. The next
-time you want to edit either another file or the same one, you must run
-the editor again. With these editors, it makes sense to use a
-command-line argument to say which file to edit.
-
- But starting a new Emacs each time you want to edit a different file
-does not make sense. For one thing, this would be annoyingly slow. For
-another, this would fail to take advantage of Emacs's ability to visit
-more than one file in a single editing session. And it would lose the
-other accumulated context, such as registers, undo history, and the mark
-ring.
-
- The recommended way to use XEmacs is to start it only once, just
-after you log in, and do all your editing in the same Emacs session.
-Each time you want to edit a different file, you visit it with the
-existing Emacs, which eventually comes to have many files in it ready
-for editing. Usually you do not kill the Emacs until you are about to
-log out. *Note Files::, for more information on visiting more than one
-file.
-
-\1f
-File: xemacs.info, Node: Exiting, Next: Command Switches, Prev: Entering Emacs, Up: Top
+ 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
-Exiting Emacs
-=============
+\1f
+File: xemacs.info, Node: Sumo, Next: Which Packages, Prev: Manually, Up: Installing Packages
- There are two commands for exiting Emacs because there are two kinds
-of exiting: "suspending" Emacs and "killing" Emacs.
-
- "Suspending" means stopping Emacs temporarily and returning control
-to its parent process (usually a shell), allowing you to resume editing
-later in the same Emacs job, with the same buffers, same kill ring,
-same undo history, and so on. This is the usual way to exit.
-
- "Killing" Emacs means destroying the Emacs job. You can run Emacs
-again later, but you will get a fresh Emacs; there is no way to resume
-the same editing session after it has been killed.
-
-`C-z'
- Suspend Emacs or iconify a frame
- (`suspend-emacs-or-iconify-frame'). If used under the X window
- system, shrink the X window containing the Emacs frame to an icon
- (see below).
-
-`C-x C-c'
- Kill Emacs (`save-buffers-kill-emacs').
-
- If you use XEmacs under the X window system, `C-z' shrinks the X
-window containing the Emacs frame to an icon. The Emacs process is
-stopped temporarily, and control is returned to the window manager. If
-more than one frame is associated with the Emacs process, only the
-frame from which you used `C-z' is iconified.
-
- To activate the "suspended" Emacs, use the appropriate window manager
-mouse gestures. Usually left-clicking on the icon reactivates and
-reopens the X window containing the Emacs frame, but the window manager
-you use determines what exactly happens. To actually kill the Emacs
-process, use `C-x C-c' or the Exit XEmacs item on the File menu.
-
- To suspend Emacs, type `C-z' (`suspend-emacs'). This takes you back
-to the shell from which you invoked Emacs. You can resume Emacs with
-the shell command `%xemacs' in most common shells.
-
- On systems that do not support suspending programs, `C-z' starts an
-inferior shell that communicates directly with the terminal. Emacs
-waits until you exit the subshell. (The way to do that is probably
-with `C-d' or `exit', but it depends on which shell you use.) The only
-way on these systems to get back to the shell from which Emacs was run
-(to log out, for example) is to kill Emacs.
-
- Suspending also fails if you run Emacs under a shell that doesn't
-support suspending programs, even if the system itself does support it.
-In such a case, you can set the variable `cannot-suspend' to a
-non-`nil' value to force `C-z' to start an inferior shell. (One might
-also describe Emacs's parent shell as "inferior" for failing to support
-job control properly, but that is a matter of taste.)
-
- When Emacs communicates directly with an X server and creates its own
-dedicated X windows, `C-z' has a different meaning. Suspending an
-applications that uses its own X windows is not meaningful or useful.
-Instead, `C-z' runs the command `iconify-or-deiconify-frame', which
-temporarily closes up the selected Emacs frame. The way to get back to
-a shell window is with the window manager.
-
- To kill Emacs, type `C-x C-c' (`save-buffers-kill-emacs'). A
-two-character key is used for this to make it harder to type. Selecting
-the Exit XEmacs option of the File menu is an alternate way of issuing
-the command.
-
- Unless a numeric argument is used, this command first offers to save
-any modified file-visiting buffers. If you do not save all buffers,
-you are asked for reconfirmation with `yes' before killing Emacs, since
-any changes not saved will be lost forever. If any subprocesses are
-still running, `C-x C-c' asks you to confirm killing them, since killing
-Emacs will kill the subprocesses immediately.
-
- There is no way to restart an Emacs session once you have killed it.
-You can, however, arrange for Emacs to record certain session
-information, such as which files are visited, when you kill it, so that
-the next time you restart Emacs it will try to visit the same files and
-so on.
-
- The operating system usually listens for certain special characters
-whose meaning is to kill or suspend the program you are running. This
-operating system feature is turned off while you are in Emacs. The
-meanings of `C-z' and `C-x C-c' as keys in Emacs were inspired by the
-use of `C-z' and `C-c' on several operating systems as the characters
-for stopping or killing a program, but that is their only relationship
-with the operating system. You can customize these keys to run any
-commands of your choice (*note Keymaps::).
-
-\1f
-File: xemacs.info, Node: Command Switches, Next: Startup Paths, Prev: Exiting, Up: Top
-
-Command Line Switches and Arguments
-===================================
-
- XEmacs supports command line arguments you can use to request
-various actions when invoking Emacs. The commands are for compatibility
-with other editors and for sophisticated activities. If you are using
-XEmacs under the X window system, you can also use a number of standard
-Xt command line arguments. Command line arguments are not usually
-needed for editing with Emacs; new users can skip this section.
-
- Many editors are designed to be started afresh each time you want to
-edit. You start the editor to edit one file; then exit the editor. The
-next time you want to edit either another file or the same one, you
-start the editor again. Under these circumstances, it makes sense to
-use a command line argument to say which file to edit.
-
- The recommended way to use XEmacs is to start it only once, just
-after you log in, and do all your editing in the same Emacs process.
-Each time you want to edit a file, you visit it using the existing
-Emacs. Emacs creates a new buffer for each file, and (unless you kill
-some of the buffers) Emacs eventually has many files in it ready for
-editing. Usually you do not kill the Emacs process until you are about
-to log out. Since you usually read files by typing commands to Emacs,
-command line arguments for specifying a file when Emacs is started are
-seldom needed.
-
- Emacs accepts command-line arguments that specify files to visit,
-functions to call, and other activities and operating modes. If you
-are running XEmacs under the X window system, a number of standard Xt
-command line arguments are available, as well as a few X parameters
-that are XEmacs-specific.
-
- Options with long names with a single initial hyphen are also
-recognized with the GNU double initial hyphen syntax. (The reverse is
-not true.)
-
- The following subsections list:
- * Command line arguments that you can always use
-
- * Command line arguments that have to appear at the beginning of the
- argument list
-
- * Command line arguments that are only relevant if you are running
- XEmacs under X
-
-Command Line Arguments for Any Position
----------------------------------------
+Installing the Sumo Packages:
+=============================
- Command line arguments are processed in the order they appear on the
-command line; however, certain arguments (the ones in the second table)
-must be at the front of the list if they are used.
-
- Here are the arguments allowed:
-
-`FILE'
- Visit FILE using `find-file'. *Note Visiting::.
-
-`+LINENUM FILE'
- Visit FILE using `find-file', then go to line number LINENUM in it.
-
-`-load FILE'
-`-l FILE'
- Load a file FILE of Lisp code with the function `load'. *Note
- Lisp Libraries::.
-
-`-funcall FUNCTION'
-`-f FUNCTION'
- Call Lisp function FUNCTION with no arguments.
+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'
-`-eval FUNCTION'
- Interpret the next argument as a Lisp expression, and evaluate it.
- You must be very careful of the shell quoting here.
+ For an XEmacs compiled with Mule you also need:
+`xemacs-mule-sumo.tar.gz'
-`-insert FILE'
-`-i FILE'
- Insert the contents of FILE into the current buffer. This is like
- what `M-x insert-buffer' does; *Note Misc File Ops::.
+ N.B. They are called 'Sumo Tarballs' for good reason. They are
+currently about 19MB and 4.5MB (gzipped) respectively.
-`-kill'
- Exit from Emacs without asking for confirmation. Always the last
- argument processed, no matter where it appears in the command line.
-
-`-version'
-`-V'
- Prints version information. This implies `-batch'.
-
- % xemacs -version
- XEmacs 19.13 of Mon Aug 21 1995 on willow (usg-unix-v) [formerly Lucid Emacs]
-
-`-help'
- Prints a summary of command-line options and then exits.
-
-Command Line Arguments (Beginning of Line Only)
------------------------------------------------
-
- The following arguments are recognized only at the beginning of the
-command line. If more than one of them appears, they must appear in the
-order in which they appear in this table.
-
-`--show-dump-id'
-`-sd'
- Print the ID for the new portable dumper's dump file on the
- terminal and exit. (Prints an error message and exits if XEmacs
- was not configured `--pdump'.)
+ Install them by:
-`--no-dump-file'
-`-nd'
- Don't load the dump file. Roughly equivalent to old temacs.
- (Ignored if XEmacs was not configured `--pdump'.)
-
-`--terminal FILE'
-`-t FILE'
- Use FILE instead of the terminal for input and output. This
- implies the `-nw' option, documented below.
-
-`-batch'
- Run Emacs in "batch mode", which means that the text being edited
- is not displayed and the standard Unix interrupt characters such as
- `C-z' and `C-c' continue to have their normal effect. Emacs in
- batch mode outputs to `stderr' only what would normally be printed
- in the echo area under program control.
-
- Batch mode is used for running programs written in Emacs Lisp from
- shell scripts, makefiles, and so on. Normally the `-l' switch or
- `-f' switch will be used as well, to invoke a Lisp program to do
- the batch processing.
-
- `-batch' implies `-q' (do not load an init file). It also causes
- Emacs to kill itself after all command switches have been
- processed. In addition, auto-saving is not done except in buffers
- for which it has been explicitly requested.
-
-`--no-windows'
-`-nw'
- Start up XEmacs in TTY mode (using the TTY XEmacs was started
- from), rather than trying to connect to an X display. Note that
- this happens automatically if the `DISPLAY' environment variable
- is not set.
-
-`-debug-init'
- Enter the debugger if an error in the init file occurs.
-
-`-debug-paths'
- Displays information on how XEmacs constructs the various paths
- into its hierarchy on startup. (See also *note Startup Paths::.)
-
-`-unmapped'
- Do not map the initial frame. This is useful if you want to start
- up XEmacs as a server (e.g. for gnuserv screens or external client
- widgets).
-
-`-no-init-file'
-`-q'
- Do not load your Emacs init file. *Note Init File::.
-
-`-no-site-file'
- Do not load the site-specific init file `lisp/site-start.el'.
-
-`-no-autoloads'
- Do not load global symbol files (`auto-autoloads') at startup.
- This implies `-vanilla'.
-
-`-no-early-packages'
- Do not process early packages. (For more information on startup
- issues concerning the package system, *Note Startup Paths::.)
-
-`-vanilla'
- This is equivalent to `-q -no-site-file -no-early-packages'.
-
-`-user-init-file FILE'
- Load FILE as your Emacs init file instead of
- `~/.xemacs/init.el'/`~/.emacs'.
-
-`-user-init-directory DIRECTORY'
- Use DIRECTORY as the location of your early package hierarchies
- and the various user-specific initialization files.
-
-`-user USER'
-`-u USER'
- Equivalent to `-user-init-file ~USER/.xemacs/init.el
- -user-init-directory ~USER/.xemacs', or `-user-init-file
- ~USER/.emacs -user-init-directory ~USER/.xemacs', whichever init
- file comes first. *Note Init File::.
-
- Note that the init file can get access to the command line argument
-values as the elements of a list in the variable `command-line-args'.
-(The arguments in the second table above will already have been
-processed and will not be in the list.) The init file can override the
-normal processing of the other arguments by setting this variable.
-
- One way to use command switches is to visit many files automatically:
-
- xemacs *.c
-
-passes each `.c' file as a separate argument to Emacs, so that Emacs
-visits each file (*note Visiting::).
-
- Here is an advanced example that assumes you have a Lisp program file
-called `hack-c-program.el' which, when loaded, performs some useful
-operation on the current buffer, expected to be a C program.
-
- xemacs -batch foo.c -l hack-c-program -f save-buffer -kill > log
-
-Here Emacs is told to visit `foo.c', load `hack-c-program.el' (which
-makes changes in the visited file), save `foo.c' (note that
-`save-buffer' is the function that `C-x C-s' is bound to), and then
-exit to the shell from which the command was executed. `-batch'
-guarantees there will be no problem redirecting output to `log',
-because Emacs will not assume that it has a display terminal to work
-with.
-
-Command Line Arguments (for XEmacs Under X)
--------------------------------------------
-
- If you are running XEmacs under X, a number of options are available
-to control color, border, and window title and icon name:
-
-`-title TITLE'
-`-wn TITLE'
-`-T TITLE'
- Use TITLE as the window title. This sets the `frame-title-format'
- variable, which controls the title of the X window corresponding
- to the selected frame. This is the same format as
- `mode-line-format'.
+ `cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xvf - RET'
-`-iconname TITLE'
-`-in TITLE'
- Use TITLE as the icon name. This sets the
- `frame-icon-title-format' variable, which controls the title of
- the icon corresponding to the selected frame.
+ Or, if you have GNU tar:
-`-mc COLOR'
- Use COLOR as the mouse color.
+ `cd $prefix/lib/xemacs ; tar zxvf /path/to/<tarballname> RET'
-`-cr COLOR'
- Use COLOR as the text-cursor foreground color.
+ 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.
-`-private'
- Install a private colormap for XEmacs.
+\1f
+File: xemacs.info, Node: Which Packages, Next: Removing Packages, Prev: Sumo, Up: Installing Packages
- In addition, XEmacs allows you to use a number of standard Xt
-command line arguments.
+Which Packages to Install:
+==========================
-`-background COLOR'
-`-bg COLOR'
- Use COLOR as the background color.
+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
-`-bordercolor COLOR'
-`-bd COLOR'
- Use COLOR as the border color.
+ 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
-`-borderwidth WIDTH'
-`-bw WIDTH'
- Use WIDTH as the border width.
+ If you are using the XEmacs package tools, don't forget to do:
-`-display DISPLAY'
-`-d DISPLAY'
- When running under the X window system, create the window
- containing the Emacs frame on the display named DISPLAY.
+ Packages -> Add Required
-`-foreground COLOR'
-`-fg COLOR'
- Use COLOR as the foreground color.
+ To make sure you have everything that the packages you have chosen to
+install need.
-`-font NAME'
-`-fn NAME'
- Use NAME as the default font.
+ See also *Note Available Packages:: for further descriptions of the
+individual packages.
-`-geometry SPEC'
-`-geom SPEC'
-`-g SPEC'
- Use the geometry (window size and/or position) specified by SPEC.
+\1f
+File: xemacs.info, Node: Removing Packages, Prev: Which Packages, Up: Installing Packages
-`-iconic'
- Start up iconified.
+Removing Packages:
+==================
-`-rv'
- Bring up Emacs in reverse video.
+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.
-`-name NAME'
- Use the resource manager resources specified by NAME. The default
- is to use the name of the program (`argv[0]') as the resource
- manager name.
+ 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'.
-`-xrm'
- Read something into the resource database for this invocation of
- Emacs only.
+ Note that the interactive package tools included with XEmacs already
+do this for you.
\1f
-File: xemacs.info, Node: Startup Paths, Next: Packages, Prev: Command Switches, Up: Top
+File: xemacs.info, Node: Building Packages, Next: Local.rules File, Prev: Installing Packages, Up: Packages
+
+Building Packages:
+==================
-How XEmacs finds Directories and Files
-======================================
+Currently, source packages are only available via anonymous CVS. See
+<http://cvs.xemacs.org/> for details of checking out the
+`xemacs-packages' module.
- XEmacs deals with a multitude of files during operation. These files
-are spread over many directories, and XEmacs determines the location of
-most of these directories at startup and organizes them into various
-paths. (A "path", for the purposes of this section, is simply a list
-of directories which XEmacs searches successively in order to locate a
-file.)
+Prerequisites for Building Source Packages
+------------------------------------------
-XEmacs Directory Hierarchies
-----------------------------
+`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'.
- Many of the files XEmacs looks for are located within the XEmacs
-installation itself. However, there are several views of what actually
-constitutes the "XEmacs installation": XEmacs may be run from the
-compilation directory, it may be installed into arbitrary directories,
-spread over several directories unrelated to each other. Moreover, it
-may subsequently be moved to a different place. (This last case is not
-as uncommon as it sounds. Binary kits work this way.) Consequently,
-XEmacs has quite complex procedures in place to find directories, no
-matter where they may be hidden.
-
- XEmacs will always respect directory options passed to `configure'.
-However, if it cannot locate a directory at the configured place, it
-will initiate a search for the directory in any of a number of
-"hierarchies" rooted under a directory which XEmacs assumes contain
-parts of the XEmacs installation; it may locate several such hierarchies
-and search across them. (Typically, there are just one or two
-hierarchies: the hierarchy where XEmacs was or will be installed, and
-the one where it is being built.) Such a directory containing a
-hierarchy is called a "root". Whenever this section refers to a
-directory using the shorthand `<root>', it means that XEmacs searches
-for it under all hierarchies XEmacs was able to scrounge up. In a
-running XEmacs, the hierarchy roots are stored in the variable
-`emacs-roots'.
-
-Package Hierarchies
+`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)
-------------------
- Many relevant directories and files XEmacs uses are actually not
-part of the core installation. They are part of any of the many
-packages usually installed on top of an XEmacs installation. (*Note
-Packages::.) Hence, they play a prominent role in the various paths
-XEmacs sets up.
-
- XEmacs locates packages in any of a number of package hierarchies.
-Package hierarchies fall into three groups: "early", "late", and "last",
-according to the relative location at which they show up in the various
-XEmacs paths. Early package hierarchies are at the very front, late
-ones somewhere in the middle, and last hierarchies are (you guessed it)
-last.
-
- By default, XEmacs expects an early package hierarchy in the
-subdirectory `.xemacs/xemacs-packages' of the user's home directory.
-
- Moreover, XEmacs expects late hierarchies in the subdirectories
-`site-packages', `mule-packages', and `xemacs-packages' (in that order)
-of the `<root>/lib/xemacs' subdirectory of one of the installation
-hierarchies. (If you run in-place, these are direct subdirectories of
-the build directory.) Furthermore, XEmacs will also search these
-subdirectories in the `<root>/lib/xemacs-<VERSION>' subdirectory and
-prefer directories found there.
-
- By default, XEmacs does not have a pre-configured last package
-hierarchy. Last hierarchies are primarily for using package hierarchies
-of outdated versions of XEmacs as a fallback option. For example, it is
-possible to run XEmacs 21 with the 20.4 package hierarchy as a last
-hierarchy.
+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.
- It is possible to specify at configure-time the location of the
-various package hierarchies with the `--package-path' option to
-configure. The early, late, and last components of the package path
-are separated by double instead of single colons. If all three
-components are present, they locate the early, late, and last package
-hierarchies respectively. If two components are present, they locate
-the early and late hierarchies. If only one component is present, it
-locates the late hierarchy. At run time, the package path may also be
-specified via the `EMACSPACKAGEPATH' environment variable.
+`edict'
+ Lisp Interface to EDICT, Kanji Dictionary.
- An XEmacs package is laid out just like a normal installed XEmacs
-lisp directory. It may have `lisp', `etc', `info', and `lib-src'
-subdirectories. XEmacs adds these at appropriate places within the
-various system-wide paths.
+`egg-its'
+ Wnn (4.2 and 6) support. SJ3 support. Must be installed prior to
+ XEmacs build.
- There may be any number of package hierarchy directories.
+`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.
-Directories and Paths
----------------------
+`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)
- Here is a list of the various directories and paths XEmacs tries to
-locate during startup. XEmacs distinguishes between directories and
-paths specific to "version", "site", and "architecture" when looking
-for them.
-
-`version-specific'
- directories are specific to the version of XEmacs they belong to
- and typically reside under `<root>/lib/xemacs-<VERSION>'.
-
-`site-specific'
- directories are independent of the version of XEmacs they belong
- to and typically reside under `<root>/lib/xemacs'
-
-`architecture-specific'
- directories are specific both to the version of XEmacs and the
- architecture it runs on and typically reside under
- `<root>/lib/xemacs-<VERSION>/<ARCHITECTURE>'.
-
- During installation, all of these directories may also reside
-directly under `<root>', because that is where they are in the XEmacs
-tarball.
-
- If XEmacs runs with the `-debug-paths' option (*note Command
-Switches::), it will print the values of these variables, hopefully
-aiding in debugging any problems which come up.
-
-`lisp-directory'
- Contains the version-specific location of the Lisp files that come
- with the core distribution of XEmacs. XEmacs will search it
- recursively to a depth of 1 when setting up `load-path'.
-
-`load-path'
- Is where XEmacs searches for XEmacs Lisp files with commands like
- `load-library'. It contains the package lisp directories (see
- further down) and the version-specific core Lisp directories. If
- the environment variable `EMACSLOADPATH' is set at startup, its
- directories are prepended to `load-path'.
-
-`Info-directory-list'
- Contains the location of info files. (See *Note (info)::.) It
- contains the package info directories and the version-specific core
- documentation. Moreover, XEmacs will add `/usr/info',
- `/usr/local/info' as well as the directories of the environment
- variable `INFOPATH' to `Info-directory-list'.
-
-`exec-directory'
- Is the directory of architecture-dependent files that come with
- XEmacs, especially executable programs intended for XEmacs to
- invoke.
-
-`exec-path'
- Is the path for executables which XEmacs may want to start. It
- contains the package executable paths as well as `exec-directory',
- and the directories of the environment variables `PATH' and
- `EMACSPATH'.
-
-`doc-directory'
- Is the directory containing the architecture-specific `DOC' file
- that contains documentation for XEmacs' commands.
-
-`data-directory'
- Is the version-specific directory that contains core data files
- XEmacs uses. It may be initialized from the `EMACSDATA'
- environment variable.
-
-`data-directory-list'
- Is the path where XEmacs looks for data files. It contains
- package data directories as well as `data-directory'.
-
-\1f
-File: xemacs.info, Node: Basic, Next: Undo, Prev: Packages, Up: Top
-
-Basic Editing Commands
-**********************
-
- We now give the basics of how to enter text, make corrections, and
-save the text in a file. If this material is new to you, you might
-learn it more easily by running the Emacs learn-by-doing tutorial. To
-use the tutorial, run Emacs and type `Control-h t'
-(`help-with-tutorial'). You can also use Tutorials item from the Help
-menu.
-
- XEmacs comes with many translations of tutorial. If your XEmacs is
-with MULE and you set up language environment correctly, XEmacs chooses
-right tutorial when available (*note Language Environments::). If you
-want specific translation, give `C-h t' a prefix argument, like `C-u
-C-h t'.
-
- To clear the screen and redisplay, type `C-l' (`recenter').
+`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.
-* Inserting Text:: Inserting text by simply typing it.
-* Moving Point:: How to move the cursor to the place where you want to
- change something.
-* Erasing:: Deleting and killing text.
-* Files: Basic Files. Visiting, creating, and saving files.
-* Help: Basic Help. Asking what a character does.
-* Blank Lines:: Commands to make or delete blank lines.
-* Continuation Lines:: Lines too wide for the screen.
-* Position Info:: What page, line, row, or column is point on?
-* Arguments:: Numeric arguments for repeating a command.
+\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: Inserting Text, Next: Moving Point, Up: Basic
+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.
-Inserting Text
-==============
+\1f
+File: xemacs.info, Node: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs
- To insert printing characters into the text you are editing, just
-type them. This inserts the characters you type into the buffer at the
-cursor (that is, at "point"; *note Point::). The cursor moves forward,
-and any text after the cursor moves forward too. If the text in the
-buffer is `FOOBAR', with the cursor before the `B', then if you type
-`XX', you get `FOOXXBAR', with the cursor still before the `B'.
-
- To "delete" text you have just inserted, use <BS>. <BS> deletes the
-character _before_ the cursor (not the one that the cursor is on top of
-or under; that is the character AFTER the cursor). The cursor and all
-characters after it move backwards. Therefore, if you type a printing
-character and then type <BS>, they cancel out.
-
- To end a line and start typing a new one, type <RET>. This inserts
-a newline character in the buffer. If point is in the middle of a
-line, <RET> splits the line. Typing <DEL> when the cursor is at the
-beginning of a line deletes the preceding newline, thus joining the
-line with the preceding line.
-
- Emacs can split lines automatically when they become too long, if you
-turn on a special minor mode called "Auto Fill" mode. *Note Filling::,
-for how to use Auto Fill mode.
-
- If you prefer to have text characters replace (overwrite) existing
-text rather than shove it to the right, you can enable Overwrite mode,
-a minor mode. *Note Minor Modes::.
-
- Direct insertion works for printing characters and <SPC>, but other
-characters act as editing commands and do not insert themselves. If you
-need to insert a control character or a character whose code is above
-200 octal, you must "quote" it by typing the character `Control-q'
-(`quoted-insert') first. (This character's name is normally written
-`C-q' for short.) There are two ways to use `C-q':
-
- * `C-q' followed by any non-graphic character (even `C-g') inserts
- that character.
-
- * `C-q' followed by a sequence of octal digits inserts the character
- with the specified octal character code. You can use any number of
- octal digits; any non-digit terminates the sequence. If the
- terminating character is <RET>, it serves only to terminate the
- sequence; any other non-digit is itself used as input after
- terminating the sequence. (The use of octal sequences is disabled
- in ordinary non-binary Overwrite mode, to give you a convenient
- way to insert a digit instead of overwriting with it.)
-
-A numeric argument to `C-q' specifies how many copies of the quoted
-character should be inserted (*note Arguments::).
-
- Customization information: <DEL>, in most modes, runs the command
-`backward-or-forward-delete-char'; <RET> runs the command `newline',
-and self-inserting printing characters run the command `self-insert',
-which inserts whatever character was typed to invoke it. Some major
-modes rebind <DEL> to other commands.
-
-\1f
-File: xemacs.info, Node: Moving Point, Next: Erasing, Prev: Inserting Text, Up: Basic
-
-Changing the Location of Point
-==============================
-
- To do more than insert characters, you have to know how to move point
-(*note Point::). The simplest way to do this is with arrow keys, or by
-clicking the left mouse button where you want to move to.
-
- NOTE: Many of the following commands have two versions, one that uses
-the function keys (e.g. <LEFT> or <END>) and one that doesn't. The
-former versions may only be available on X terminals (i.e. not on
-TTY's), but the latter are available on all terminals.
+Examining and Editing Abbrevs
+=============================
-`C-a'
-`HOME'
- Move to the beginning of the line (`beginning-of-line').
+`M-x list-abbrevs'
+ Print a list of all abbrev definitions.
-`C-e'
-`END'
- Move to the end of the line (`end-of-line').
+`M-x edit-abbrevs'
+ Edit a list of abbrevs; you can add, alter, or remove definitions.
-`C-f'
-`RIGHT'
- Move forward one character (`forward-char').
+ The output from `M-x list-abbrevs' looks like this:
-`C-b'
-`LEFT'
- Move backward one character (`backward-char').
+ (lisp-mode-abbrev-table)
+ "dk" 0 "define-key"
+ (global-abbrev-table)
+ "dfn" 0 "definition"
-`M-f'
-`C-RIGHT'
- Move forward one word (`forward-word').
+(Some blank lines of no semantic significance, and some other abbrev
+tables, have been omitted.)
-`M-b'
-`C-LEFT'
- Move backward one word (`backward-word').
+ 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.
-`C-n'
-`DOWN'
- Move down one line, vertically (`next-line'). This command
- attempts to keep the horizontal position unchanged, so if you
- start in the middle of one line, you end in the middle of the
- next. When on the last line of text, `C-n' creates a new line and
- moves onto it.
+ 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.
-`C-p'
-`UP'
- Move up one line, vertically (`previous-line').
+ `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.
-`C-v'
-`PGDN'
- Move down one page, vertically (`scroll-up').
+ `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.
-`M-v'
-`PGUP'
- Move up one page, vertically (`scroll-down').
+\1f
+File: xemacs.info, Node: Saving Abbrevs, Next: Dynamic Abbrevs, Prev: Editing Abbrevs, Up: Abbrevs
-`C-l'
- Clear the frame and reprint everything (`recenter'). Text moves
- on the frame to bring point to the center of the window.
+Saving Abbrevs
+==============
-`M-r'
- Move point to left margin, vertically centered in the window
- (`move-to-window-line'). Text does not move on the screen.
+These commands allow you to keep abbrev definitions between editing
+sessions.
- A numeric argument says which screen line to place point on. It
- counts screen lines down from the top of the window (zero for the
- top line). A negative argument counts lines from the bottom (-1
- for the bottom line).
+`M-x write-abbrev-file'
+ Write a file describing all defined abbrevs.
-`C-t'
- Transpose two characters, the ones before and after the cursor
- (`transpose-chars').
+`M-x read-abbrev-file'
+ Read such an abbrev file and define abbrevs as specified there.
-`M-<'
-`C-HOME'
- Move to the top of the buffer (`beginning-of-buffer'). With
- numeric argument N, move to N/10 of the way from the top. *Note
- Arguments::, for more information on numeric arguments.
+`M-x quietly-read-abbrev-file'
+ Similar, but do not display a message about what is going on.
-`M->'
-`C-END'
- Move to the end of the buffer (`end-of-buffer').
+`M-x define-abbrevs'
+ Define abbrevs from buffer.
-`M-x goto-char'
- Read a number N and move point to buffer position N. Position 1
- is the beginning of the buffer.
+`M-x insert-abbrevs'
+ Insert all abbrevs and their expansions into the buffer.
-`M-g'
- Read a number N and move point to line number N (`goto-line').
- Line 1 is the beginning of 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 set-goal-column'
- Use the current column of point as the "semi-permanent goal
- column" for `C-n' and `C-p' (`set-goal-column'). Henceforth, those
- commands always move to this column in each line moved into, or as
- close as possible given the contents of the line. This goal
- column remains in effect until canceled.
+ `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"'.
-`C-u M-x set-goal-column'
- Cancel the goal column. Henceforth, `C-n' and `C-p' once again
- try to avoid changing the horizontal position, as usual.
+ 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.
- If you set the variable `track-eol' to a non-`nil' value, then `C-n'
-and `C-p' when at the end of the starting line move to the end of
-another line. Normally, `track-eol' is `nil'. *Note Variables::, for
-how to set variables such as `track-eol'.
+ 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.
- Normally, `C-n' on the last line of a buffer appends a newline to
-it. If the variable `next-line-add-newlines' is `nil', then `C-n' gets
-an error instead (like `C-p' on the first line).
+\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: Erasing, Next: Basic Files, Prev: Moving Point, Up: Basic
+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'.
-Erasing Text
-============
+* Menu:
-`<DEL>'
- Delete the character before or after point
- (`backward-or-forward-delete-char'). You can customize this
- behavior by setting the variable `delete-key-deletes-forward'.
+* 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.
-`C-d'
- Delete the character after point (`delete-char').
+\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::).
-`C-k'
- Kill to the end of the line (`kill-line').
+\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').
-`M-d'
- Kill forward to the end of the next word (`kill-word').
+`C-c >'
+ Move right after insertion (`picture-movement-right').
-`M-<DEL>'
- Kill back to the beginning of the previous word
- (`backward-kill-word').
+`C-c ^'
+ Move up after insertion (`picture-movement-up').
- You already know about the <DEL> key which deletes the character
-before point (that is, before the cursor). Another key, `Control-d'
-(`C-d' for short), deletes the character after point (that is, the
-character that the cursor is on). This shifts the rest of the text on
-the line to the left. If you type `C-d' at the end of a line, it joins
-together that line and the next line.
+`C-c .'
+ Move down after insertion (`picture-movement-down').
- To erase a larger amount of text, use the `C-k' key, which kills a
-line at a time. If you type `C-k' at the beginning or middle of a
-line, it kills all the text up to the end of the line. If you type
-`C-k' at the end of a line, it joins that line and the next line.
+`C-c `'
+ Move up and left ("northwest") after insertion
+ (`picture-movement-nw').
- *Note Killing::, for more flexible ways of killing text.
+`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: Basic Files, Next: Basic Help, Prev: Erasing, Up: Basic
+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.
-Files
-=====
+\1f
+File: xemacs.info, Node: Rectangles in Picture, Prev: Tabs in Picture, Up: Picture
+
+Picture Mode Rectangle Commands
+===============================
- The commands described above are sufficient for creating and altering
-text in an Emacs buffer; the more advanced Emacs commands just make
-things easier. But to keep any text permanently you must put it in a
-"file". Files are named units of text which are stored by the
-operating system for you to retrieve later by name. To look at or use
-the contents of a file in any way, including editing the file with
-Emacs, you must specify the file name.
+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::).
- Consider a file named `/usr/rms/foo.c'. To begin editing this file
-from Emacs, type:
+`C-c C-k'
+ Clear out the region-rectangle (`picture-clear-rectangle'). With
+ argument, kill it.
- C-x C-f /usr/rms/foo.c <RET>
+`C-c C-w R'
+ Similar but save rectangle contents in register R first
+ (`picture-clear-rectangle-to-register').
-Here the file name is given as an "argument" to the command `C-x C-f'
-(`find-file'). That command uses the "minibuffer" to read the
-argument, and you type <RET> to terminate the argument (*note
-Minibuffer::).
+`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.
- You can also use the Open... menu item from the File menu, then type
-the name of the file to the prompt.
+`C-c C-x R'
+ Similar, but use the rectangle in register R
+ (`picture-yank-rectangle-from-register').
- Emacs obeys the command by "visiting" the file: creating a buffer,
-copying the contents of the file into the buffer, and then displaying
-the buffer for you to edit. If you alter the text, you can "save" the
-new text in the file by typing `C-x C-s' (`save-buffer') or choosing
-Save Buffer from the File menu. This makes the changes permanent by
-copying the altered buffer contents back into the file
-`/usr/rms/foo.c'. Until you save, the changes exist only inside Emacs,
-and the file `foo.c' is unaltered.
+ 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.
- To create a file, visit the file with `C-x C-f' as if it already
-existed or choose Open... from the File menu and provide the name for
-the new file. Emacs will create an empty buffer in which you can
-insert the text you want to put in the file. When you save the buffer
-with `C-x C-s', or by choosing Save Buffer from the File menu, the file
-is created.
+ However, deletion of rectangles can be useful in Picture mode, so
+these commands delete the rectangle if given a numeric argument.
- To learn more about using files, *Note Files::.
+ 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: Basic Help, Next: Blank Lines, Prev: Basic Files, Up: Basic
+File: xemacs.info, Node: Sending Mail, Next: Reading Mail, Prev: Picture, Up: Top
-Help
-====
+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').
- If you forget what a key does, you can find out with the Help
-character, which is `C-h' (or <F1>, which is an alias for `C-h'). Type
-`C-h k' followed by the key you want to know about; for example, `C-h k
-C-n' tells you all about what `C-n' does. `C-h' is a prefix key; `C-h
-k' is just one of its subcommands (the command `describe-key'). The
-other subcommands of `C-h' provide different kinds of help. Type `C-h'
-twice to get a description of all the help facilities. *Note Help::.
+ 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: Blank Lines, Next: Continuation Lines, Prev: Basic Help, Up: Basic
+File: xemacs.info, Node: Mail Format, Next: Mail Headers, Prev: Sending Mail, Up: Sending Mail
-Blank Lines
-===========
+The Format of the Mail Buffer
+=============================
- Here are special commands and techniques for putting in and taking
-out blank lines.
+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.
-`C-o'
- Insert one or more blank lines after the cursor (`open-line').
+ 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.
-`C-x C-o'
- Delete all but one of many consecutive blank lines
- (`delete-blank-lines').
+ The line in the buffer that says:
- When you want to insert a new line of text before an existing line,
-you can do it by typing the new line of text, followed by <RET>.
-However, it may be easier to see what you are doing if you first make a
-blank line and then insert the desired text into it. This is easy to do
-using the key `C-o' (`open-line'), which inserts a newline after point
-but leaves point in front of the newline. After `C-o', type the text
-for the new line. `C-o F O O' has the same effect as `F O O <RET>',
-except for the final location of point.
+ --text follows this line--
- You can make several blank lines by typing `C-o' several times, or
-by giving it a numeric argument to tell it how many blank lines to make.
-*Note Arguments::, for how. If you have a fill prefix, then `C-o'
-command inserts the fill prefix on the new line, when you use it at the
-beginning of a line. *Note Fill Prefix::.
+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'.
- The easy way to get rid of extra blank lines is with the command
-`C-x C-o' (`delete-blank-lines'). `C-x C-o' in a run of several blank
-lines deletes all but one of them. `C-x C-o' on a solitary blank line
-deletes that blank line. When point is on a nonblank line, `C-x C-o'
-deletes any blank lines following that nonblank line.
+ 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: Continuation Lines, Next: Position Info, Prev: Blank Lines, Up: Basic
+File: xemacs.info, Node: Mail Headers, Next: Mail Mode, Prev: Mail Format, Up: Sending Mail
-Continuation Lines
+Mail Header Fields
==================
- If you add too many characters to one line without breaking it with
-<RET>, the line will grow to occupy two (or more) lines on the screen,
-with a curved arrow at the extreme right margin of all but the last of
-them. The curved arrow says that the following screen line is not
-really a distinct line in the text, but just the "continuation" of a
-line too long to fit the screen. Continuation is also called "line
-wrapping".
-
- Sometimes it is nice to have Emacs insert newlines automatically when
-a line gets too long. Continuation on the screen does not do that. Use
-Auto Fill mode (*note Filling::) if that's what you want.
-
- Instead of continuation, long lines can be displayed by "truncation".
-This means that all the characters that do not fit in the width of the
-frame or window do not appear at all. They remain in the buffer,
-temporarily invisible. Right arrow in the last column (instead of the
-curved arrow) inform you that truncation is in effect.
-
- Truncation instead of continuation happens whenever horizontal
-scrolling is in use, and optionally in all side-by-side windows (*note
-Windows::). You can enable truncation for a particular buffer by
-setting the variable `truncate-lines' to non-`nil' in that buffer.
-(*Note Variables::.) Altering the value of `truncate-lines' makes it
-local to the current buffer; until that time, the default value is in
-effect. The default is initially `nil'. *Note Locals::.
-
- *Note Display Vars::, for additional variables that affect how text
-is displayed.
+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
+
+Keyboard Macros
+===============
+
+A "keyboard macro" is a command defined by the user to abbreviate a
+sequence of keys. For example, if you discover that you are about to
+type `C-n C-d' forty times, you can speed your work by defining a
+keyboard macro to invoke `C-n C-d' and calling it with a repeat count
+of forty.
+
+`C-x ('
+ Start defining a keyboard macro (`start-kbd-macro').
+
+`C-x )'
+ End the definition of a keyboard macro (`end-kbd-macro').
+
+`C-x e'
+ Execute the most recent keyboard macro (`call-last-kbd-macro').
+
+`C-u C-x ('
+ Re-execute last keyboard macro, then add more keys to its
+ definition.
+
+`C-x q'
+ When this point is reached during macro execution, ask for
+ confirmation (`kbd-macro-query').
+
+`M-x name-last-kbd-macro'
+ Give a command name (for the duration of the session) to the most
+ recently defined keyboard macro.
+
+`M-x insert-kbd-macro'
+ Insert in the buffer a keyboard macro's definition, as Lisp code.
+
+ Keyboard macros differ from other Emacs commands in that they are
+written in the Emacs command language rather than in Lisp. This makes
+it easier for the novice to write them and makes them more convenient as
+temporary hacks. However, the Emacs command language is not powerful
+enough as a programming language to be useful for writing anything
+general or complex. For such things, Lisp must be used.
+
+ You define a keyboard macro by executing the commands which are its
+definition. Put differently, as you are defining a keyboard macro, the
+definition is being executed for the first time. This way, you see
+what the effects of your commands are, and don't have to figure them
+out in your head. When you are finished, the keyboard macro is defined
+and also has been executed once. You can then execute the same set of
+commands again by invoking the macro.
+
+* Menu:
+
+* Basic Kbd Macro:: Defining and running keyboard macros.
+* Save Kbd Macro:: Giving keyboard macros names; saving them in files.
+* Kbd Macro Query:: Keyboard macros that do different things each use.
+
+\1f
+File: xemacs.info, Node: Basic Kbd Macro, Next: Save Kbd Macro, Up: Keyboard Macros
+
+Basic Use
+---------
+
+To start defining a keyboard macro, type `C-x (' (`start-kbd-macro').
+From then on, anything you type continues to be executed, but also
+becomes part of the definition of the macro. `Def' appears in the mode
+line to remind you of what is going on. When you are finished, the
+`C-x )' command (`end-kbd-macro') terminates the definition, without
+becoming part of it.
+
+ For example,
+
+ C-x ( M-f foo C-x )
+
+defines a macro to move forward a word and then insert `foo'.
+
+ You can give `C-x )' a repeat count as an argument, in which case it
+repeats the macro that many times right after defining it, but defining
+the macro counts as the first repetition (since it is executed as you
+define it). If you give `C-x )' an argument of 4, it executes the
+macro immediately 3 additional times. An argument of zero to `C-x e'
+or `C-x )' means repeat the macro indefinitely (until it gets an error
+or you type `C-g').
+
+ Once you have defined a macro, you can invoke it again with the `C-x
+e' command (`call-last-kbd-macro'). You can give the command a repeat
+count numeric argument to execute the macro many times.
+
+ To repeat an operation at regularly spaced places in the text,
+define a macro and include as part of the macro the commands to move to
+the next place you want to use it. For example, if you want to change
+each line, you should position point at the start of a line, and define
+a macro to change that line and leave point at the start of the next
+line. Repeating the macro will then operate on successive lines.
+
+ After you have terminated the definition of a keyboard macro, you
+can add to the end of its definition by typing `C-u C-x ('. This is
+equivalent to plain `C-x (' followed by retyping the whole definition
+so far. As a consequence it re-executes the macro as previously
+defined.
+
+\1f
+File: xemacs.info, Node: Save Kbd Macro, Next: Kbd Macro Query, Prev: Basic Kbd Macro, Up: Keyboard Macros
+
+Naming and Saving Keyboard Macros
+---------------------------------
+
+To save a keyboard macro for longer than until you define the next one,
+you must give it a name using `M-x name-last-kbd-macro'. This reads a
+name as an argument using the minibuffer and defines that name to
+execute the macro. The macro name is a Lisp symbol, and defining it in
+this way makes it a valid command name for calling with `M-x' or for
+binding a key to with `global-set-key' (*note Keymaps::). If you
+specify a name that has a prior definition other than another keyboard
+macro, Emacs prints an error message and nothing is changed.
+
+ Once a macro has a command name, you can save its definition in a
+file. You can then use it in another editing session. First visit the
+file you want to save the definition in. Then use the command:
+
+ M-x insert-kbd-macro <RET> MACRONAME <RET>
+
+This inserts some Lisp code that, when executed later, will define the
+same macro with the same definition it has now. You need not
+understand Lisp code to do this, because `insert-kbd-macro' writes the
+Lisp code for you. Then save the file. You can load the file with
+`load-file' (*note Lisp Libraries::). If the file you save in is your
+initialization file (*note Init File::), then the macro will be defined
+each time you run Emacs.
+
+ If you give `insert-kbd-macro' a prefix argument, it creates
+additional Lisp code to record the keys (if any) that you have bound to
+the keyboard macro, so that the macro is reassigned the same keys when
+you load the file.
+
+\1f
+File: xemacs.info, Node: Kbd Macro Query, Prev: Save Kbd Macro, Up: Keyboard Macros
+
+Executing Macros With Variations
+--------------------------------
+
+You can use `C-x q' (`kbd-macro-query'), to get an effect similar to
+that of `query-replace'. The macro asks you each time whether to make
+a change. When you are defining the macro, type `C-x q' at the point
+where you want the query to occur. During macro definition, the `C-x
+q' does nothing, but when you invoke the macro, `C-x q' reads a
+character from the terminal to decide whether to continue.
+
+ The special answers to a `C-x q' query are <SPC>, <DEL>, `C-d',
+`C-l', and `C-r'. Any other character terminates execution of the
+keyboard macro and is then read as a command. <SPC> means to continue.
+<DEL> means to skip the remainder of this repetition of the macro,
+starting again from the beginning in the next repetition. `C-d' means
+to skip the remainder of this repetition and cancel further repetition.
+`C-l' redraws the frame and asks you again for a character to specify
+what to do. `C-r' enters a recursive editing level, in which you can
+perform editing that is not part of the macro. When you exit the
+recursive edit using `C-M-c', you are asked again how to continue with
+the keyboard macro. If you type a <SPC> at this time, the rest of the
+macro definition is executed. It is up to you to leave point and the
+text in a state such that the rest of the macro will do what you want.
+
+ `C-u C-x q', which is `C-x q' with a numeric argument, performs a
+different function. It enters a recursive edit reading input from the
+keyboard, both when you type it during the definition of the macro and
+when it is executed from the macro. During definition, the editing you
+do inside the recursive edit does not become part of the macro. During
+macro execution, the recursive edit gives you a chance to do some
+particularized editing. *Note Recursive Edit::.
+
+\1f
+File: xemacs.info, Node: Key Bindings, Next: Syntax, Prev: Keyboard Macros, Up: Customization
+
+Customizing Key Bindings
+========================
+
+This section deals with the "keymaps" that define the bindings between
+keys and functions, and shows how you can customize these bindings.
+
+ A command is a Lisp function whose definition provides for
+interactive use. Like every Lisp function, a command has a function
+name, which is a Lisp symbol whose name usually consists of lower case
+letters and hyphens.
+
+* Menu:
+
+* Keymaps:: Definition of the keymap data structure.
+ Names of Emacs's standard keymaps.
+* Rebinding:: How to redefine one key's meaning conveniently.
+* Disabling:: Disabling a command means confirmation is required
+ before it can be executed. This is done to protect
+ beginners from surprises.
+
+\1f
+File: xemacs.info, Node: Keymaps, Next: Rebinding, Up: Key Bindings
+
+Keymaps
+-------
+
+The bindings between characters and command functions are recorded in
+data structures called "keymaps". Emacs has many of these. One, the
+"global" keymap, defines the meanings of the single-character keys that
+are defined regardless of major mode. It is the value of the variable
+`global-map'.
+
+ Each major mode has another keymap, its "local keymap", which
+contains overriding definitions for the single-character keys that are
+redefined in that mode. Each buffer records which local keymap is
+installed for it at any time, and the current buffer's local keymap is
+the only one that directly affects command execution. The local keymaps
+for Lisp mode, C mode, and many other major modes always exist even when
+not in use. They are the values of the variables `lisp-mode-map',
+`c-mode-map', and so on. For less frequently used major modes, the
+local keymap is sometimes constructed only when the mode is used for the
+first time in a session, to save space.
+
+ There are local keymaps for the minibuffer, too; they contain various
+completion and exit commands.
+
+ * `minibuffer-local-map' is used for ordinary input (no completion).
+
+ * `minibuffer-local-ns-map' is similar, except that <SPC> exits just
+ like <RET>. This is used mainly for Mocklisp compatibility.
+
+ * `minibuffer-local-completion-map' is for permissive completion.
+
+ * `minibuffer-local-must-match-map' is for strict completion and for
+ cautious completion.
+
+ * `repeat-complex-command-map' is for use in `C-x <ESC> <ESC>'.
+
+ * `isearch-mode-map' contains the bindings of the special keys which
+ are bound in the pseudo-mode entered with `C-s' and `C-r'.
+
+ Finally, each prefix key has a keymap which defines the key sequences
+that start with it. For example, `ctl-x-map' is the keymap used for
+characters following a `C-x'.
+
+ * `ctl-x-map' is the variable name for the map used for characters
+ that follow `C-x'.
+
+ * `help-map' is used for characters that follow `C-h'.
+
+ * `esc-map' is for characters that follow <ESC>. All Meta characters
+ are actually defined by this map.
+
+ * `ctl-x-4-map' is for characters that follow `C-x 4'.
+
+ * `mode-specific-map' is for characters that follow `C-c'.
+
+ The definition of a prefix key is the keymap to use for looking up
+the following character. Sometimes the definition is actually a Lisp
+symbol whose function definition is the following character keymap. The
+effect is the same, but it provides a command name for the prefix key
+that you can use as a description of what the prefix key is for. Thus
+the binding of `C-x' is the symbol `Ctl-X-Prefix', whose function
+definition is the keymap for `C-x' commands, the value of `ctl-x-map'.
+
+ Prefix key definitions can appear in either the global map or a
+local map. The definitions of `C-c', `C-x', `C-h', and <ESC> as prefix
+keys appear in the global map, so these prefix keys are always
+available. Major modes can locally redefine a key as a prefix by
+putting a prefix key definition for it in the local map.
+
+ A mode can also put a prefix definition of a global prefix character
+such as `C-x' into its local map. This is how major modes override the
+definitions of certain keys that start with `C-x'. This case is
+special, because the local definition does not entirely replace the
+global one. When both the global and local definitions of a key are
+other keymaps, the next character is looked up in both keymaps, with
+the local definition overriding the global one. The character after the
+`C-x' is looked up in both the major mode's own keymap for redefined
+`C-x' commands and in `ctl-x-map'. If the major mode's own keymap for
+`C-x' commands contains `nil', the definition from the global keymap
+for `C-x' commands is used.
+
+\1f
+File: xemacs.info, Node: Rebinding, Next: Disabling, Prev: Keymaps, Up: Key Bindings
+
+Changing Key Bindings
+---------------------
+
+You can redefine an Emacs key by changing its entry in a keymap. You
+can change the global keymap, in which case the change is effective in
+all major modes except those that have their own overriding local
+definitions for the same key. Or you can change the current buffer's
+local map, which affects all buffers using the same major mode.
+
+* Menu:
+
+* Interactive Rebinding:: Changing Key Bindings Interactively
+* Programmatic Rebinding:: Changing Key Bindings Programmatically
+* Key Bindings Using Strings:: Using Strings for Changing Key Bindings
+
+\1f
+File: xemacs.info, Node: Interactive Rebinding, Next: Programmatic Rebinding, Up: Rebinding
+
+Changing Key Bindings Interactively
+...................................
+
+`M-x global-set-key <RET> KEY CMD <RET>'
+ Defines KEY globally to run CMD.
+
+`M-x local-set-key <RET> KEYS CMD <RET>'
+ Defines KEY locally (in the major mode now in effect) to run CMD.
+
+`M-x local-unset-key <RET> KEYS <RET>'
+ Removes the local binding of KEY.
+
+ CMD is a symbol naming an interactively-callable function.
+
+ When called interactively, KEY is the next complete key sequence
+that you type. When called as a function, KEY is a string, a vector of
+events, or a vector of key-description lists as described in the
+`define-key' function description. The binding goes in the current
+buffer's local map, which is shared with other buffers in the same
+major mode.
+
+ The following example:
+
+ M-x global-set-key <RET> C-f next-line <RET>
+
+redefines `C-f' to move down a line. The fact that CMD is read second
+makes it serve as a kind of confirmation for KEY.
+
+ These functions offer no way to specify a particular prefix keymap as
+the one to redefine in, but that is not necessary, as you can include
+prefixes in KEY. KEY is read by reading characters one by one until
+they amount to a complete key (that is, not a prefix key). Thus, if
+you type `C-f' for KEY, Emacs enters the minibuffer immediately to read
+CMD. But if you type `C-x', another character is read; if that
+character is `4', another character is read, and so on. For example,
+
+ M-x global-set-key <RET> C-x 4 $ spell-other-window <RET>
+
+redefines `C-x 4 $' to run the (fictitious) command
+`spell-other-window'.
+
+ The most general way to modify a keymap is the function
+`define-key', used in Lisp code (such as your init file). `define-key'
+takes three arguments: the keymap, the key to modify in it, and the new
+definition. *Note Init File::, for an example.
+`substitute-key-definition' is used similarly; it takes three
+arguments, an old definition, a new definition, and a keymap, and
+redefines in that keymap all keys that were previously defined with the
+old definition to have the new definition instead.
+
+\1f
+File: xemacs.info, Node: Programmatic Rebinding, Next: Key Bindings Using Strings, Prev: Interactive Rebinding, Up: Rebinding
+
+Changing Key Bindings Programmatically
+......................................
+
+You can use the functions `global-set-key' and `define-key' to rebind
+keys under program control.
+
+``(global-set-key KEYS CMD)''
+ Defines KEYS globally to run CMD.
+
+``(define-key KEYMAP KEYS DEF)''
+ Defines KEYS to run DEF in the keymap KEYMAP.
+
+ KEYMAP is a keymap object.
+
+ KEYS is the sequence of keystrokes to bind.
+
+ DEF is anything that can be a key's definition:
+
+ * `nil', meaning key is undefined in this keymap
+
+ * A command, that is, a Lisp function suitable for interactive
+ calling
+
+ * A string or key sequence vector, which is treated as a keyboard
+ macro
+
+ * A keymap to define a prefix key
+
+ * A symbol so that when the key is looked up, the symbol stands for
+ its function definition, which should at that time be one of the
+ above, or another symbol whose function definition is used, and so
+ on
+
+ * A cons, `(string . defn)', meaning that DEFN is the definition
+ (DEFN should be a valid definition in its own right)
+
+ * A cons, `(keymap . char)', meaning use the definition of CHAR in
+ map KEYMAP
+
+ For backward compatibility, XEmacs allows you to specify key
+sequences as strings. However, the preferred method is to use the
+representations of key sequences as vectors of keystrokes. *Note
+Keystrokes::, for more information about the rules for constructing key
+sequences.
+
+ Emacs allows you to abbreviate representations for key sequences in
+most places where there is no ambiguity. Here are some rules for
+abbreviation:
+
+ * The keysym by itself is equivalent to a list of just that keysym,
+ i.e., `f1' is equivalent to `(f1)'.
+
+ * A keystroke by itself is equivalent to a vector containing just
+ that keystroke, i.e., `(control a)' is equivalent to `[(control
+ a)]'.
+
+ * You can use ASCII codes for keysyms that have them. i.e., `65' is
+ equivalent to `A'. (This is not so much an abbreviation as an
+ alternate representation.)
+
+ Here are some examples of programmatically binding keys:
+
+
+ ;;; Bind `my-command' to <f1>
+ (global-set-key 'f1 'my-command)
+
+ ;;; Bind `my-command' to Shift-f1
+ (global-set-key '(shift f1) 'my-command)
+
+ ;;; Bind `my-command' to C-c Shift-f1
+ (global-set-key '[(control c) (shift f1)] 'my-command)
+
+ ;;; Bind `my-command' to the middle mouse button.
+ (global-set-key 'button2 'my-command)
+
+ ;;; Bind `my-command' to <META> <CTL> <Right Mouse Button>
+ ;;; in the keymap that is in force when you are running `dired'.
+ (define-key dired-mode-map '(meta control button3) 'my-command)
+
+\1f
+File: xemacs.info, Node: Key Bindings Using Strings, Prev: Programmatic Rebinding, Up: Rebinding
+
+Using Strings for Changing Key Bindings
+.......................................
+
+For backward compatibility, you can still use strings to represent key
+sequences. Thus you can use commands like the following:
+
+ ;;; Bind `end-of-line' to C-f
+ (global-set-key "\C-f" 'end-of-line)
+
+ Note, however, that in some cases you may be binding more than one
+key sequence by using a single command. This situation can arise
+because in ASCII, `C-i' and <TAB> have the same representation.
+Therefore, when Emacs sees:
+
+ (global-set-key "\C-i" 'end-of-line)
+
+ it is unclear whether the user intended to bind `C-i' or <TAB>. The
+solution XEmacs adopts is to bind both of these key sequences.
+
+ After binding a command to two key sequences with a form like:
+
+ (define-key global-map "\^X\^I" 'command-1)
+
+ it is possible to redefine only one of those sequences like so:
+
+ (define-key global-map [(control x) (control i)] 'command-2)
+ (define-key global-map [(control x) tab] 'command-3)
+
+ This applies only when running under a window system. If you are
+talking to Emacs through an ASCII-only channel, you do not get any of
+these features.
+
+ Here is a table of pairs of key sequences that behave in a similar
+fashion:
+
+ control h backspace
+ control l clear
+ control i tab
+ control m return
+ control j linefeed
+ control [ escape
+ control @ control space
+
+\1f
+File: xemacs.info, Node: Disabling, Prev: Rebinding, Up: Key Bindings
+
+Disabling Commands
+------------------
+
+Disabling a command marks it as requiring confirmation before it can be
+executed. The purpose of disabling a command is to prevent beginning
+users from executing it by accident and being confused.
+
+ The direct mechanism for disabling a command is to have a non-`nil'
+`disabled' property on the Lisp symbol for the command. These
+properties are normally set by the user's init file with Lisp
+expressions such as:
+
+ (put 'delete-region 'disabled t)
+
+ *Note Init File::.
+
+ If the value of the `disabled' property is a string, that string is
+included in the message printed when the command is used:
+
+ (put 'delete-region 'disabled
+ "Text deleted this way cannot be yanked back!\n")
+
+ You can disable a command either by editing the init file directly
+or with the command `M-x disable-command', which edits the init file
+for you. *Note Init File::.
+
+ When you attempt to invoke a disabled command interactively in Emacs,
+a window is displayed containing the command's name, its documentation,
+and some instructions on what to do next; then Emacs asks for input
+saying whether to execute the command as requested, enable it and
+execute, or cancel it. If you decide to enable the command, you are
+asked whether to do this permanently or just for the current session.
+Enabling permanently works by automatically editing your init file.
+You can use `M-x enable-command' at any time to enable any command
+permanently.
+
+ Whether a command is disabled is independent of what key is used to
+invoke it; it also applies if the command is invoked using `M-x'.
+Disabling a command has no effect on calling it as a function from Lisp
+programs.
+
+\1f
+File: xemacs.info, Node: Syntax, Next: Init File, Prev: Key Bindings, Up: Customization
+
+The Syntax Table
+================
+
+All the Emacs commands which parse words or balance parentheses are
+controlled by the "syntax table". The syntax table specifies which
+characters are opening delimiters, which are parts of words, which are
+string quotes, and so on. Actually, each major mode has its own syntax
+table (though sometimes related major modes use the same one) which it
+installs in each buffer that uses that major mode. The syntax table
+installed in the current buffer is the one that all commands use, so we
+call it "the" syntax table. A syntax table is a Lisp object, a vector
+of length 256 whose elements are numbers.
+
+* Menu:
+
+* Entry: Syntax Entry. What the syntax table records for each character.
+* Change: Syntax Change. How to change the information.
+
+\1f
+File: xemacs.info, Node: Syntax Entry, Next: Syntax Change, Up: Syntax
+
+Information About Each Character
+--------------------------------
+
+The syntax table entry for a character is a number that encodes six
+pieces of information:
+
+ * The syntactic class of the character, represented as a small
+ integer
+
+ * The matching delimiter, for delimiter characters only (the
+ matching delimiter of `(' is `)', and vice versa)
+
+ * A flag saying whether the character is the first character of a
+ two-character comment starting sequence
+
+ * A flag saying whether the character is the second character of a
+ two-character comment starting sequence
+
+ * A flag saying whether the character is the first character of a
+ two-character comment ending sequence
+
+ * A flag saying whether the character is the second character of a
+ two-character comment ending sequence
+
+ The syntactic classes are stored internally as small integers, but
+are usually described to or by the user with characters. For example,
+`(' is used to specify the syntactic class of opening delimiters. Here
+is a table of syntactic classes, with the characters that specify them.
+
+`-'
+ The class of whitespace characters. Please don't use the formerly
+ advertised , which is not supported by GNU Emacs.
+
+`w'
+ The class of word-constituent characters.
+
+`_'
+ The class of characters that are part of symbol names but not
+ words. This class is represented by `_' because the character `_'
+ has this class in both C and Lisp.
+
+`.'
+ The class of punctuation characters that do not fit into any other
+ special class.
+
+`('
+ The class of opening delimiters.
+
+`)'
+ The class of closing delimiters.
+
+`''
+ The class of expression-adhering characters. These characters are
+ part of a symbol if found within or adjacent to one, and are part
+ of a following expression if immediately preceding one, but are
+ like whitespace if surrounded by whitespace.
+
+`"'
+ The class of string-quote characters. They match each other in
+ pairs, and the characters within the pair all lose their syntactic
+ significance except for the `\' and `/' classes of escape
+ characters, which can be used to include a string-quote inside the
+ string.
+
+`$'
+ The class of self-matching delimiters. This is intended for TeX's
+ `$', which is used both to enter and leave math mode. Thus, a
+ pair of matching `$' characters surround each piece of math mode
+ TeX input. A pair of adjacent `$' characters act like a single
+ one for purposes of matching.
+
+`/'
+ The class of escape characters that always just deny the following
+ character its special syntactic significance. The character after
+ one of these escapes is always treated as alphabetic.
+
+`\'
+ The class of C-style escape characters. In practice, these are
+ treated just like `/'-class characters, because the extra
+ possibilities for C escapes (such as being followed by digits)
+ have no effect on where the containing expression ends.
+
+`<'
+ The class of comment-starting characters. Only single-character
+ comment starters (such as `;' in Lisp mode) are represented this
+ way.
+
+`>'
+ The class of comment-ending characters. Newline has this syntax in
+ Lisp mode.
+
+ The characters flagged as part of two-character comment delimiters
+can have other syntactic functions most of the time. For example, `/'
+and `*' in C code, when found separately, have nothing to do with
+comments. The comment-delimiter significance overrides when the pair of
+characters occur together in the proper order. Only the list and sexp
+commands use the syntax table to find comments; the commands
+specifically for comments have other variables that tell them where to
+find comments. Moreover, the list and sexp commands notice comments
+only if `parse-sexp-ignore-comments' is non-`nil'. This variable is set
+to `nil' in modes where comment-terminator sequences are liable to
+appear where there is no comment, for example, in Lisp mode where the
+comment terminator is a newline but not every newline ends a comment.
+
+\1f
+File: xemacs.info, Node: Syntax Change, Prev: Syntax Entry, Up: Syntax
+
+Altering Syntax Information
+---------------------------
+
+It is possible to alter a character's syntax table entry by storing a
+new number in the appropriate element of the syntax table, but it would
+be hard to determine what number to use. Emacs therefore provides a
+command that allows you to specify the syntactic properties of a
+character in a convenient way.
+
+ `M-x modify-syntax-entry' is the command to change a character's
+syntax. It can be used interactively and is also used by major modes
+to initialize their own syntax tables. Its first argument is the
+character to change. The second argument is a string that specifies the
+new syntax. When called from Lisp code, there is a third, optional
+argument, which specifies the syntax table in which to make the change.
+If not supplied, or if this command is called interactively, the third
+argument defaults to the current buffer's syntax table.
+
+ 1. The first character in the string specifies the syntactic class.
+ It is one of the characters in the previous table (*note Syntax
+ Entry::).
+
+ 2. The second character is the matching delimiter. For a character
+ that is not an opening or closing delimiter, this should be a
+ space, and may be omitted if no following characters are needed.
+
+ 3. The remaining characters are flags. The flag characters allowed
+ are:
+
+ `1'
+ Flag this character as the first of a two-character comment
+ starting sequence.
+
+ `2'
+ Flag this character as the second of a two-character comment
+ starting sequence.
+
+ `3'
+ Flag this character as the first of a two-character comment
+ ending sequence.
+
+ `4'
+ Flag this character as the second of a two-character comment
+ ending sequence.
+
+ Use `C-h s' (`describe-syntax') to display a description of the
+contents of the current syntax table. The description of each
+character includes both the string you have to pass to
+`modify-syntax-entry' to set up that character's current syntax, and
+some English to explain that string if necessary.
+
+\1f
+File: xemacs.info, Node: Init File, Next: Audible Bell, Prev: Syntax, Up: Customization
+
+The Init File
+=============
+
+When you start Emacs, it normally loads either `.xemacs/init.el' or the
+file `.emacs' (whichever comes first) in your home directory. This
+file, if it exists, should contain Lisp code. It is called your
+initialization file or "init file". Use the command line switch `-q'
+to tell Emacs whether to load an init file (*note Entering Emacs::).
+Use the command line switch `-user-init-file' (*note Command
+Switches::) to tell Emacs to load a different file instead of
+`~/.xemacs/init.el'/`~/.emacs'.
+
+ When the init file is read, the variable `user-init-file' says which
+init file was loaded.
+
+ At some sites there is a "default init file", which is the library
+named `default.el', found via the standard search path for libraries.
+The Emacs distribution contains no such library; your site may create
+one for local customizations. If this library exists, it is loaded
+whenever you start Emacs. But your init file, if any, is loaded first;
+if it sets `inhibit-default-init' non-`nil', then `default' is not
+loaded.
+
+ If you have a large amount of code in your init file, you should
+byte-compile it to `~/.xemacs/init.elc' or `~/.emacs.elc'.
+
+* Menu:
+
+* Init Syntax:: Syntax of constants in Emacs Lisp.
+* Init Examples:: How to do some things with an init file.
+* Terminal Init:: Each terminal type can have an init file.
+
+\1f
+File: xemacs.info, Node: Init Syntax, Next: Init Examples, Up: Init File
+
+Init File Syntax
+----------------
+
+The init file contains one or more Lisp function call expressions.
+Each consists of a function name followed by arguments, all surrounded
+by parentheses. For example, `(setq fill-column 60)' represents a call
+to the function `setq' which is used to set the variable `fill-column'
+(*note Filling::) to 60.
+
+ The second argument to `setq' is an expression for the new value of
+the variable. This can be a constant, a variable, or a function call
+expression. In the init file, constants are used most of the time.
+They can be:
+
+Numbers
+ Integers are written in decimal, with an optional initial minus
+ sign.
+
+ If a sequence of digits is followed by a period and another
+ sequence of digits, it is interpreted as a floating point number.
+
+ The number prefixes `#b', `#o', and `#x' are supported to
+ represent numbers in binary, octal, and hexadecimal notation (or
+ radix).
+
+Strings
+ Lisp string syntax is the same as C string syntax with a few extra
+ features. Use a double-quote character to begin and end a string
+ constant.
+
+ Newlines and special characters may be present literally in
+ strings. They can also be represented as backslash sequences:
+ `\n' for newline, `\b' for backspace, `\r' for return, `\t' for
+ tab, `\f' for formfeed (control-l), `\e' for escape, `\\' for a
+ backslash, `\"' for a double-quote, or `\OOO' for the character
+ whose octal code is OOO. Backslash and double-quote are the only
+ characters for which backslash sequences are mandatory.
+
+ You can use `\C-' as a prefix for a control character, as in
+ `\C-s' for ASCII Control-S, and `\M-' as a prefix for a Meta
+ character, as in `\M-a' for Meta-A or `\M-\C-a' for Control-Meta-A.
+
+Characters
+ Lisp character constant syntax consists of a `?' followed by
+ either a character or an escape sequence starting with `\'.
+ Examples: `?x', `?\n', `?\"', `?\)'. Note that strings and
+ characters are not interchangeable in Lisp; some contexts require
+ one and some contexts require the other.
+
+True
+ `t' stands for `true'.
+
+False
+ `nil' stands for `false'.
+
+Other Lisp objects
+ Write a single-quote (') followed by the Lisp object you want.
+
+\1f
+File: xemacs.info, Node: Init Examples, Next: Terminal Init, Prev: Init Syntax, Up: Init File
+
+Init File Examples
+------------------
+
+Here are some examples of doing certain commonly desired things with
+Lisp expressions:
+
+ * Make <TAB> in C mode just insert a tab if point is in the middle
+ of a line.
+
+ (setq c-tab-always-indent nil)
+
+ Here we have a variable whose value is normally `t' for `true' and
+ the alternative is `nil' for `false'.
+
+ * Make searches case sensitive by default (in all buffers that do not
+ override this).
+
+ (setq-default case-fold-search nil)
+
+ This sets the default value, which is effective in all buffers
+ that do not have local values for the variable. Setting
+ `case-fold-search' with `setq' affects only the current buffer's
+ local value, which is probably not what you want to do in an init
+ file.
+
+ * Make Text mode the default mode for new buffers.
+
+ (setq default-major-mode 'text-mode)
+
+ Note that `text-mode' is used because it is the command for
+ entering the mode we want. A single-quote is written before it to
+ make a symbol constant; otherwise, `text-mode' would be treated as
+ a variable name.
+
+ * Turn on Auto Fill mode automatically in Text mode and related
+ modes.
+
+ (setq text-mode-hook
+ '(lambda () (auto-fill-mode 1)))
+
+ Here we have a variable whose value should be a Lisp function. The
+ function we supply is a list starting with `lambda', and a single
+ quote is written in front of it to make it (for the purpose of this
+ `setq') a list constant rather than an expression. Lisp functions
+ are not explained here; for mode hooks it is enough to know that
+ `(auto-fill-mode 1)' is an expression that will be executed when
+ Text mode is entered. You could replace it with any other
+ expression that you like, or with several expressions in a row.
+
+ (setq text-mode-hook 'turn-on-auto-fill)
+
+ This is another way to accomplish the same result.
+ `turn-on-auto-fill' is a symbol whose function definition is
+ `(lambda () (auto-fill-mode 1))'.
+
+ * Load the installed Lisp library named `foo' (actually a file
+ `foo.elc' or `foo.el' in a standard Emacs directory).
+
+ (load "foo")
+
+ When the argument to `load' is a relative pathname, not starting
+ with `/' or `~', `load' searches the directories in `load-path'
+ (*note Loading::).
+
+ * Load the compiled Lisp file `foo.elc' from your home directory.
+
+ (load "~/foo.elc")
+
+ Here an absolute file name is used, so no searching is done.
+
+ * Rebind the key `C-x l' to run the function `make-symbolic-link'.
+
+ (global-set-key "\C-xl" 'make-symbolic-link)
+
+ or
+
+ (define-key global-map "\C-xl" 'make-symbolic-link)
+
+ Note once again the single-quote used to refer to the symbol
+ `make-symbolic-link' instead of its value as a variable.
+
+ * Do the same thing for C mode only.
+
+ (define-key c-mode-map "\C-xl" 'make-symbolic-link)
+
+ * Bind the function key <F1> to a command in C mode. Note that the
+ names of function keys must be lower case.
+
+ (define-key c-mode-map 'f1 'make-symbolic-link)
+
+ * Bind the shifted version of <F1> to a command.
+
+ (define-key c-mode-map '(shift f1) 'make-symbolic-link)
+
+ * Redefine all keys which now run `next-line' in Fundamental mode to
+ run `forward-line' instead.
+
+ (substitute-key-definition 'next-line 'forward-line
+ global-map)
+
+ * Make `C-x C-v' undefined.
+
+ (global-unset-key "\C-x\C-v")
+
+ One reason to undefine a key is so that you can make it a prefix.
+ Simply defining `C-x C-v ANYTHING' would make `C-x C-v' a prefix,
+ but `C-x C-v' must be freed of any non-prefix definition first.
+
+ * Make `$' have the syntax of punctuation in Text mode. Note the
+ use of a character constant for `$'.
+
+ (modify-syntax-entry ?\$ "." text-mode-syntax-table)
+
+ * Enable the use of the command `eval-expression' without
+ confirmation.
+
+ (put 'eval-expression 'disabled nil)
+
+\1f
+File: xemacs.info, Node: Terminal Init, Prev: Init Examples, Up: Init File
+
+Terminal-Specific Initialization
+--------------------------------
+
+Each terminal type can have a Lisp library to be loaded into Emacs when
+it is run on that type of terminal. For a terminal type named
+TERMTYPE, the library is called `term/TERMTYPE' and it is found by
+searching the directories `load-path' as usual and trying the suffixes
+`.elc' and `.el'. Normally it appears in the subdirectory `term' of
+the directory where most Emacs libraries are kept.
+
+ The usual purpose of the terminal-specific library is to define the
+escape sequences used by the terminal's function keys using the library
+`keypad.el'. See the file `term/vt100.el' for an example of how this
+is done.
+
+ When the terminal type contains a hyphen, only the part of the name
+before the first hyphen is significant in choosing the library name.
+Thus, terminal types `aaa-48' and `aaa-30-rv' both use the library
+`term/aaa'. The code in the library can use `(getenv "TERM")' to find
+the full terminal type name.
+
+ The library's name is constructed by concatenating the value of the
+variable `term-file-prefix' and the terminal type. Your init file can
+prevent the loading of the terminal-specific library by setting
+`term-file-prefix' to `nil'. *Note Init File::.
+
+ The value of the variable `term-setup-hook', if not `nil', is called
+as a function of no arguments at the end of Emacs initialization, after
+both your init file and any terminal-specific library have been read.
+*Note Init File::. You can set the value in the init file to override
+part of any of the terminal-specific libraries and to define
+initializations for terminals that do not have a library.
+
+\1f
+File: xemacs.info, Node: Audible Bell, Next: Faces, Prev: Init File, Up: Customization
+
+Changing the Bell Sound
+=======================
+
+You can now change how the audible bell sounds using the variable
+`sound-alist'.
+
+ `sound-alist''s value is an list associating symbols with, among
+other things, strings of audio-data. When `ding' is called with one of
+the symbols, the associated sound data is played instead of the
+standard beep. This only works if you are logged in on the console of a
+machine with audio hardware. To listen to a sound of the provided type,
+call the function `play-sound' with the argument SOUND. You can also
+set the volume of the sound with the optional argument VOLUME.
+
+ Each element of `sound-alist' is a list describing a sound. The
+first element of the list is the name of the sound being defined.
+Subsequent elements of the list are alternating keyword/value pairs:
+
+`sound'
+ A string of raw sound data, or the name of another sound to play.
+ The symbol `t' here means use the default X beep.
+
+`volume'
+ An integer from 0-100, defaulting to `bell-volume'.
+
+`pitch'
+ If using the default X beep, the pitch (Hz) to generate.
+
+`duration'
+ If using the default X beep, the duration (milliseconds).
+
+ For compatibility, elements of `sound-alist' may also be of the form:
+
+ ( SOUND-NAME . <SOUND> )
+ ( SOUND-NAME <VOLUME> <SOUND> )
+
+ You should probably add things to this list by calling the function
+`load-sound-file'.
+
+ Note that you can only play audio data if running on the console
+screen of a machine with audio hardware which emacs understands, which
+at this time means a Sun SparcStation, SGI, or HP9000s700.
+
+ Also note that the pitch, duration, and volume options are available
+everywhere, but most X servers ignore the `pitch' option.
+
+ The variable `bell-volume' should be an integer from 0 to 100, with
+100 being loudest, which controls how loud the sounds emacs makes
+should be. Elements of the `sound-alist' may override this value.
+This variable applies to the standard X bell sound as well as sound
+files.
+
+ If the symbol `t' is in place of a sound-string, Emacs uses the
+default X beep. This allows you to define beep-types of different
+volumes even when not running on the console.
+
+ You can add things to this list by calling the function
+`load-sound-file', which reads in an audio-file and adds its data to
+the sound-alist. You can specify the sound with the SOUND-NAME argument
+and the file into which the sounds are loaded with the FILENAME
+argument. The optional VOLUME argument sets the volume.
+
+ `load-sound-file (FILENAME SOUND-NAME &optional VOLUME)'
+
+ To load and install some sound files as beep-types, use the function
+`load-default-sounds' (note that this only works if you are on display
+0 of a machine with audio hardware).
+
+ The following beep-types are used by Emacs itself. Other Lisp
+packages may use other beep types, but these are the ones that the C
+kernel of Emacs uses.
+
+`auto-save-error'
+ An auto-save does not succeed
+
+`command-error'
+ The Emacs command loop catches an error
+
+`undefined-key'
+ You type a key that is undefined
+
+`undefined-click'
+ You use an undefined mouse-click combination
+
+`no-completion'
+ Completion was not possible
+
+`y-or-n-p'
+ You type something other than the required `y' or `n'
+
+`yes-or-no-p'
+ You type something other than `yes' or `no'
+
+\1f
+File: xemacs.info, Node: Faces, Next: Frame Components, Prev: Audible Bell, Up: Customization
+
+Faces
+=====
+
+XEmacs has objects called extents and faces. An "extent" is a region
+of text and a "face" is a collection of textual attributes, such as
+fonts and colors. Every extent is displayed in some face; therefore,
+changing the properties of a face immediately updates the display of
+all associated extents. Faces can be frame-local: you can have a
+region of text that displays with completely different attributes when
+its buffer is viewed from a different X window.
+
+ The display attributes of faces may be specified either in Lisp or
+through the X resource manager.
+
+Customizing Faces
+-----------------
+
+You can change the face of an extent with the functions in this
+section. All the functions prompt for a FACE as an argument; use
+completion for a list of possible values.
+
+`M-x invert-face'
+ Swap the foreground and background colors of the given FACE.
+
+`M-x make-face-bold'
+ Make the font of the given FACE bold. When called from a program,
+ returns `nil' if this is not possible.
+
+`M-x make-face-bold-italic'
+ Make the font of the given FACE bold italic. When called from a
+ program, returns `nil' if not possible.
+
+`M-x make-face-italic'
+ Make the font of the given FACE italic. When called from a
+ program, returns `nil' if not possible.
+
+`M-x make-face-unbold'
+ Make the font of the given FACE non-bold. When called from a
+ program, returns `nil' if not possible.
+
+`M-x make-face-unitalic'
+ Make the font of the given FACE non-italic. When called from a
+ program, returns `nil' if not possible.
+
+`M-x make-face-larger'
+ Make the font of the given FACE a little larger. When called from
+ a program, returns `nil' if not possible.
+
+`M-x make-face-smaller'
+ Make the font of the given FACE a little smaller. When called
+ from a program, returns `nil' if not possible.
+
+`M-x set-face-background'
+ Change the background color of the given FACE.
+
+`M-x set-face-background-pixmap'
+ Change the background pixmap of the given FACE.
+
+`M-x set-face-font'
+ Change the font of the given FACE.
+
+`M-x set-face-foreground'
+ Change the foreground color of the given FACE.
+
+`M-x set-face-underline-p'
+ Change whether the given FACE is underlined.
+
+ You can exchange the foreground and background color of the selected
+FACE with the function `invert-face'. If the face does not specify both
+foreground and background, then its foreground and background are set
+to the background and foreground of the default face. When calling
+this from a program, you can supply the optional argument FRAME to
+specify which frame is affected; otherwise, all frames are affected.
+
+ The work of `make-face-bold', `make-face-bold-italic',
+`make-face-italic', `make-face-unbold', `make-face-unitalic' functions
+is affected by `face-frob-from-locale-first' variable. If it is `nil',
+those functions first try to manipulate device specific data like X
+font names to obtain the desired font face specification. This may be
+unsuitable in environments using different font face specifications for
+different frames, non-Mule environments in particular.
+
+ If the variable is non-`nil', those functions first try to figure
+out whether the face font is the same as one of predefined faces:
+`default', `bold', `italic', `bold-italic'. If it is the same, then
+the new face font specification is set to be the same as that of a
+corresponding predefined face. Thus if the predefined face is set up
+properly for different frames, the same will hold for the face being
+changed by the functions. This is the behavior one might desire in
+non-Mule environments mentioned above: face being changed still looks
+right in all frames.
+
+ How predefined faces might be set up for different frames in such an
+environments is described in *Note Face Resources::.
+
+ You can set the background color of the specified FACE with the
+function `set-face-background'. The argument `color' should be a
+string, the name of a color. When called from a program, if the
+optional FRAME argument is provided, the face is changed only in that
+frame; otherwise, it is changed in all frames.
+
+ You can set the background pixmap of the specified FACE with the
+function `set-face-background-pixmap'. The pixmap argument NAME should
+be a string, the name of a file of pixmap data. The directories listed
+in the `x-bitmap-file-path' variable are searched. The bitmap may also
+be a list of the form `(WIDTH HEIGHT DATA)', where WIDTH and HEIGHT are
+the size in pixels, and DATA is a string containing the raw bits of the
+bitmap. If the optional FRAME argument is provided, the face is
+changed only in that frame; otherwise, it is changed in all frames.
+
+ The variable `x-bitmap-file-path' takes as a value a list of the
+directories in which X bitmap files may be found. If the value is
+`nil', the list is initialized from the `*bitmapFilePath' resource.
+
+ If the environment variable XBMLANGPATH is set, then it is consulted
+before the `x-bitmap-file-path' variable.
+
+ You can set the font of the specified FACE with the function
+`set-face-font'. The FONT argument should be a string, the name of a
+font. When called from a program, if the optional FRAME argument is
+provided, the face is changed only in that frame; otherwise, it is
+changed in all frames.
+
+ You can set the foreground color of the specified FACE with the
+function `set-face-foreground'. The argument COLOR should be a string,
+the name of a color. If the optional FRAME argument is provided, the
+face is changed only in that frame; otherwise, it is changed in all
+frames.
+
+ You can set underline the specified FACE with the function
+`set-face-underline-p'. The argument UNDERLINE-P can be used to make
+underlining an attribute of the face or not. If the optional FRAME
+argument is provided, the face is changed only in that frame;
+otherwise, it is changed in all frames.
+
+\1f
+File: xemacs.info, Node: Frame Components, Next: X Resources, Prev: Faces, Up: Customization
+
+Frame Components
+================
+
+You can control the presence and position of most frame components, such
+as the menubar, toolbars, and gutters.
+
+ This section is not written yet. Try the Lisp Reference Manual:
+*Note Menubar: (lispref)Menubar, *Note Toolbar Intro: (lispref)Toolbar
+Intro, and *Note Gutter Intro: (lispref)Gutter Intro.
+
+\1f
+File: xemacs.info, Node: X Resources, Prev: Frame Components, Up: Customization
+
+X Resources
+===========
+
+Historically, XEmacs has used the X resource application class `Emacs'
+for its resources. Unfortunately, GNU Emacs uses the same application
+class, and resources are not compatible between the two Emacsen. This
+sharing of the application class often leads to trouble if you want to
+run both variants.
+
+ Starting with XEmacs 21, XEmacs uses the class `XEmacs' if it finds
+any XEmacs resources in the resource database when the X connection is
+initialized. Otherwise, it will use the class `Emacs' for backwards
+compatibility. The variable `x-emacs-application-class' may be
+consulted to determine the application class being used.
+
+ The examples in this section assume the application class is `Emacs'.
+
+ The Emacs resources are generally set per-frame. Each Emacs frame
+can have its own name or the same name as another, depending on the
+name passed to the `make-frame' function.
+
+ You can specify resources for all frames with the syntax:
+
+ Emacs*parameter: value
+
+or
+
+ Emacs*EmacsFrame.parameter:value
+
+You can specify resources for a particular frame with the syntax:
+
+ Emacs*FRAME-NAME.parameter: value
+
+* Menu:
+
+* Geometry Resources:: Controlling the size and position of frames.
+* Iconic Resources:: Controlling whether frames come up iconic.
+* Resource List:: List of resources settable on a frame or device.
+* Face Resources:: Controlling faces using resources.
+* Widgets:: The widget hierarchy for XEmacs.
+* Menubar Resources:: Specifying resources for the menubar.
+
+\1f
+File: xemacs.info, Node: Geometry Resources, Next: Iconic Resources, Up: X Resources
+
+Geometry Resources
+------------------
+
+To make the default size of all Emacs frames be 80 columns by 55 lines,
+do this:
+
+ Emacs*EmacsFrame.geometry: 80x55
+
+To set the geometry of a particular frame named `fred', do this:
+
+ Emacs*fred.geometry: 80x55
+
+Important! Do not use the following syntax:
+
+ Emacs*geometry: 80x55
+
+You should never use `*geometry' with any X application. It does not
+say "make the geometry of Emacs be 80 columns by 55 lines." It really
+says, "make Emacs and all subwindows thereof be 80x55 in whatever units
+they care to measure in." In particular, that is both telling the
+Emacs text pane to be 80x55 in characters, and telling the menubar pane
+to be 80x55 pixels, which is surely not what you want.
+
+ As a special case, this geometry specification also works (and sets
+the default size of all Emacs frames to 80 columns by 55 lines):
+
+ Emacs.geometry: 80x55
+
+since that is the syntax used with most other applications (since most
+other applications have only one top-level window, unlike Emacs). In
+general, however, the top-level shell (the unmapped ApplicationShell
+widget named `Emacs' that is the parent of the shell widgets that
+actually manage the individual frames) does not have any interesting
+resources on it, and you should set the resources on the frames instead.
+
+ The `-geometry' command-line argument sets only the geometry of the
+initial frame created by Emacs.
+
+ A more complete explanation of geometry-handling is
+
+ * The `-geometry' command-line option sets the `Emacs.geometry'
+ resource, that is, the geometry of the ApplicationShell.
+
+ * For the first frame created, the size of the frame is taken from
+ the ApplicationShell if it is specified, otherwise from the
+ geometry of the frame.
+
+ * For subsequent frames, the order is reversed: First the frame, and
+ then the ApplicationShell.
+
+ * For the first frame created, the position of the frame is taken
+ from the ApplicationShell (`Emacs.geometry') if it is specified,
+ otherwise from the geometry of the frame.
+
+ * For subsequent frames, the position is taken only from the frame,
+ and never from the ApplicationShell.
+
+ This is rather complicated, but it does seem to provide the most
+intuitive behavior with respect to the default sizes and positions of
+frames created in various ways.
+
+\1f
+File: xemacs.info, Node: Iconic Resources, Next: Resource List, Prev: Geometry Resources, Up: X Resources
+
+Iconic Resources
+----------------
+
+Analogous to `-geometry', the `-iconic' command-line option sets the
+iconic flag of the ApplicationShell (`Emacs.iconic') and always applies
+to the first frame created regardless of its name. However, it is
+possible to set the iconic flag on particular frames (by name) by using
+the `Emacs*FRAME-NAME.iconic' resource.
+
+\1f
+File: xemacs.info, Node: Resource List, Next: Face Resources, Prev: Iconic Resources, Up: X Resources
+
+Resource List
+-------------
+
+Emacs frames accept the following resources:
+
+`geometry' (class `Geometry'): string
+ Initial geometry for the frame. *Note Geometry Resources::, for a
+ complete discussion of how this works.
+
+`iconic' (class `Iconic'): boolean
+ Whether this frame should appear in the iconified state.
+
+`internalBorderWidth' (class `InternalBorderWidth'): int
+ How many blank pixels to leave between the text and the edge of the
+ window.
+
+`interline' (class `Interline'): int
+ How many pixels to leave between each line (may not be
+ implemented).
+
+`menubar' (class `Menubar'): boolean
+ Whether newly-created frames should initially have a menubar. Set
+ to true by default.
+
+`initiallyUnmapped' (class `InitiallyUnmapped'): boolean
+ Whether XEmacs should leave the initial frame unmapped when it
+ starts up. This is useful if you are starting XEmacs as a server
+ (e.g. in conjunction with gnuserv or the external client widget).
+ You can also control this with the `-unmapped' command-line option.
+
+`barCursor' (class `BarColor'): boolean
+ Whether the cursor should be displayed as a bar, or the
+ traditional box.
+
+`cursorColor' (class `CursorColor'): color-name
+ The color of the text cursor.
+
+`scrollBarWidth' (class `ScrollBarWidth'): integer
+ How wide the vertical scrollbars should be, in pixels; 0 means no
+ vertical scrollbars. You can also use a resource specification of
+ the form `*scrollbar.width', or the usual toolkit scrollbar
+ resources: `*XmScrollBar.width' (Motif), `*XlwScrollBar.width'
+ (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend
+ that you use the toolkit resources, though, because they're
+ dependent on how exactly your particular build of XEmacs was
+ configured.
+
+`scrollBarHeight' (class `ScrollBarHeight'): integer
+ How high the horizontal scrollbars should be, in pixels; 0 means no
+ horizontal scrollbars. You can also use a resource specification
+ of the form `*scrollbar.height', or the usual toolkit scrollbar
+ resources: `*XmScrollBar.height' (Motif), `*XlwScrollBar.height'
+ (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend
+ that you use the toolkit resources, though, because they're
+ dependent on how exactly your particular build of XEmacs was
+ configured.
+
+`scrollBarPlacement' (class `ScrollBarPlacement'): string
+ Where the horizontal and vertical scrollbars should be positioned.
+ This should be one of the four strings `BOTTOM_LEFT',
+ `BOTTOM_RIGHT', `TOP_LEFT', and `TOP_RIGHT'. Default is
+ `BOTTOM_RIGHT' for the Motif and Lucid scrollbars and
+ `BOTTOM_LEFT' for the Athena scrollbars.
+
+`topToolBarHeight' (class `TopToolBarHeight'): integer
+`bottomToolBarHeight' (class `BottomToolBarHeight'): integer
+`leftToolBarWidth' (class `LeftToolBarWidth'): integer
+`rightToolBarWidth' (class `RightToolBarWidth'): integer
+ Height and width of the four possible toolbars.
+
+`topToolBarShadowColor' (class `TopToolBarShadowColor'): color-name
+`bottomToolBarShadowColor' (class `BottomToolBarShadowColor'): color-name
+ Color of the top and bottom shadows for the toolbars. NOTE: These
+ resources do _not_ have anything to do with the top and bottom
+ toolbars (i.e. the toolbars at the top and bottom of the frame)!
+ Rather, they affect the top and bottom shadows around the edges of
+ all four kinds of toolbars.
+
+`topToolBarShadowPixmap' (class `TopToolBarShadowPixmap'): pixmap-name
+`bottomToolBarShadowPixmap' (class `BottomToolBarShadowPixmap'): pixmap-name
+ Pixmap of the top and bottom shadows for the toolbars. If set,
+ these resources override the corresponding color resources. NOTE:
+ These resources do _not_ have anything to do with the top and
+ bottom toolbars (i.e. the toolbars at the top and bottom of the
+ frame)! Rather, they affect the top and bottom shadows around the
+ edges of all four kinds of toolbars.
+
+`toolBarShadowThickness' (class `ToolBarShadowThickness'): integer
+ Thickness of the shadows around the toolbars, in pixels.
+
+`visualBell' (class `VisualBell'): boolean
+ Whether XEmacs should flash the screen rather than making an
+ audible beep.
+
+`bellVolume' (class `BellVolume'): integer
+ Volume of the audible beep.
+
+`useBackingStore' (class `UseBackingStore'): boolean
+ Whether XEmacs should set the backing-store attribute of the X
+ windows it creates. This increases the memory usage of the X
+ server but decreases the amount of X traffic necessary to update
+ the screen, and is useful when the connection to the X server goes
+ over a low-bandwidth line such as a modem connection.
+
+ Emacs devices accept the following resources:
+
+`textPointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over text. This resource is
+ used to initialize the variable `x-pointer-shape'.
+
+`selectionPointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over a selectable text region
+ (an extent with the `highlight' property; for example, an Info
+ cross-reference). This resource is used to initialize the variable
+ `x-selection-pointer-shape'.
+
+`spacePointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over a blank space in a buffer
+ (that is, after the end of a line or after the end-of-file). This
+ resource is used to initialize the variable
+ `x-nontext-pointer-shape'.
+
+`modeLinePointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over a modeline. This
+ resource is used to initialize the variable `x-mode-pointer-shape'.
+
+`gcPointer' (class `Cursor'): cursor-name
+ The cursor to display when a garbage-collection is in progress.
+ This resource is used to initialize the variable
+ `x-gc-pointer-shape'.
+
+`scrollbarPointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over the scrollbar. This
+ resource is used to initialize the variable
+ `x-scrollbar-pointer-shape'.
+
+`pointerColor' (class `Foreground'): color-name
+`pointerBackground' (class `Background'): color-name
+ The foreground and background colors of the mouse cursor. These
+ resources are used to initialize the variables
+ `x-pointer-foreground-color' and `x-pointer-background-color'.
+
+\1f
+File: xemacs.info, Node: Face Resources, Next: Widgets, Prev: Resource List, Up: X Resources
+
+Face Resources
+--------------
+
+The attributes of faces are also per-frame. They can be specified as:
+
+ Emacs.FACE_NAME.parameter: value
+
+or
+
+ Emacs*FRAME_NAME.FACE_NAME.parameter: value
+
+Faces accept the following resources:
+
+`attributeFont' (class `AttributeFont'): font-name
+ The font of this face.
+
+`attributeForeground' (class `AttributeForeground'): color-name
+`attributeBackground' (class `AttributeBackground'): color-name
+ The foreground and background colors of this face.
+
+`attributeBackgroundPixmap' (class `AttributeBackgroundPixmap'): file-name
+ The name of an XBM file (or XPM file, if your version of Emacs
+ supports XPM), to use as a background stipple.
+
+`attributeUnderline' (class `AttributeUnderline'): boolean
+ Whether text in this face should be underlined.
+
+ All text is displayed in some face, defaulting to the face named
+`default'. To set the font of normal text, use
+`Emacs*default.attributeFont'. To set it in the frame named `fred', use
+`Emacs*fred.default.attributeFont'.
+
+ These are the names of the predefined faces:
+
+`default'
+ Everything inherits from this.
+
+`bold'
+ If this is not specified in the resource database, Emacs tries to
+ find a bold version of the font of the default face.
+
+`italic'
+ If this is not specified in the resource database, Emacs tries to
+ find an italic version of the font of the default face.
+
+`bold-italic'
+ If this is not specified in the resource database, Emacs tries to
+ find a bold-italic version of the font of the default face.
+
+`modeline'
+ This is the face that the modeline is displayed in. If not
+ specified in the resource database, it is determined from the
+ default face by reversing the foreground and background colors.
+
+`highlight'
+ This is the face that highlighted extents (for example, Info
+ cross-references and possible completions, when the mouse passes
+ over them) are displayed in.
+
+`left-margin'
+`right-margin'
+ These are the faces that the left and right annotation margins are
+ displayed in.
+
+`zmacs-region'
+ This is the face that mouse selections are displayed in.
+
+`isearch'
+ This is the face that the matched text being searched for is
+ displayed in.
+
+`info-node'
+ This is the face of info menu items. If unspecified, it is copied
+ from `bold-italic'.
+
+`info-xref'
+ This is the face of info cross-references. If unspecified, it is
+ copied from `bold'. (Note that, when the mouse passes over a
+ cross-reference, the cross-reference's face is determined from a
+ combination of the `info-xref' and `highlight' faces.)
+
+ Other packages might define their own faces; to see a list of all
+faces, use any of the interactive face-manipulation commands such as
+`set-face-font' and type `?' when you are prompted for the name of a
+face.
+
+ If the `bold', `italic', and `bold-italic' faces are not specified
+in the resource database, then XEmacs attempts to derive them from the
+font of the default face. It can only succeed at this if you have
+specified the default font using the XLFD (X Logical Font Description)
+format, which looks like
+
+ *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+
+If you use any of the other, less strict font name formats, some of
+which look like
+
+ lucidasanstypewriter-12
+ fixed
+ 9x13
+
+ then XEmacs won't be able to guess the names of the bold and italic
+versions. All X fonts can be referred to via XLFD-style names, so you
+should use those forms. See the man pages for `X(1)', `xlsfonts(1)',
+and `xfontsel(1)'.
+
+\1f
+File: xemacs.info, Node: Widgets, Next: Menubar Resources, Prev: Face Resources, Up: X Resources
+
+Widgets
+-------
+
+There are several structural widgets between the terminal EmacsFrame
+widget and the top level ApplicationShell; the exact names and types of
+these widgets change from release to release (for example, they changed
+between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are
+subject to further change in the future, so you should avoid mentioning
+them in your resource database. The above-mentioned syntaxes should be
+forward- compatible. As of 19.13, the exact widget hierarchy is as
+follows:
+
+ INVOCATION-NAME "shell" "container" FRAME-NAME
+ x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame"
+
+ where INVOCATION-NAME is the terminal component of the name of the
+XEmacs executable (usually `xemacs'), and `x-emacs-application-class'
+is generally `Emacs'.
+
+\1f
+File: xemacs.info, Node: Menubar Resources, Prev: Widgets, Up: X Resources
+
+Menubar Resources
+-----------------
+
+As the menubar is implemented as a widget which is not a part of XEmacs
+proper, it does not use the face mechanism for specifying fonts and
+colors: It uses whatever resources are appropriate to the type of widget
+which is used to implement it.
+
+ If Emacs was compiled to use only the Lucid Motif-lookalike menu
+widgets, then one way to specify the font of the menubar would be
+
+ Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+
+ If both the Lucid Motif-lookalike menu widgets and X Font Sets are
+configured to allow multilingual menubars, then one uses
+
+ *menubar*FontSet: -*-helvetica-bold-r-*-*-*-120-*-*-*-*-iso8859-*, \
+ -*-*-*-*-*-*-*-120-*-jisx0208.1983-0
+
+ That would specify fonts for a Japanese menubar. Specifying only one
+XLFD is acceptable; specifying more than one for a given registry
+(language) is also allowed. When X Font Sets are configured, some .font
+resources (eg, menubars) are ignored in favor of the corresponding
+.fontSet resources.
+
+ If the Motif library is being used, then one would have to use
+
+ Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+
+ because the Motif library uses the `fontList' resource name instead
+of `font', which has subtly different semantics.
+
+ The same is true of the scrollbars: They accept whichever resources
+are appropriate for the toolkit in use.
+
+\1f
+File: xemacs.info, Node: Quitting, Next: Lossage, Prev: Customization, Up: Top
+
+Quitting and Aborting
+=====================
+
+`C-g'
+ Quit. Cancel running or partially typed command.
+
+`C-]'
+ Abort innermost recursive editing level and cancel the command
+ which invoked it (`abort-recursive-edit').
+
+`M-x top-level'
+ Abort all recursive editing levels that are currently executing.
+
+`C-x u'
+ Cancel an already-executed command, usually (`undo').
+
+ There are two ways of cancelling commands which are not finished
+executing: "quitting" with `C-g', and "aborting" with `C-]' or `M-x
+top-level'. Quitting is cancelling a partially typed command or one
+which is already running. Aborting is getting out of a recursive
+editing level and cancelling the command that invoked the recursive
+edit.
+
+ Quitting with `C-g' is used for getting rid of a partially typed
+command or a numeric argument that you don't want. It also stops a
+running command in the middle in a relatively safe way, so you can use
+it if you accidentally start executing a command that takes a long
+time. In particular, it is safe to quit out of killing; either your
+text will ALL still be there, or it will ALL be in the kill ring (or
+maybe both). Quitting an incremental search does special things
+documented under searching; in general, it may take two successive
+`C-g' characters to get out of a search. `C-g' works by setting the
+variable `quit-flag' to `t' the instant `C-g' is typed; Emacs Lisp
+checks this variable frequently and quits if it is non-`nil'. `C-g' is
+only actually executed as a command if it is typed while Emacs is
+waiting for input.
+
+ If you quit twice in a row before the first `C-g' is recognized, you
+activate the "emergency escape" feature and return to the shell. *Note
+Emergency Escape::.
+
+ You can use `C-]' (`abort-recursive-edit') to get out of a recursive
+editing level and cancel the command which invoked it. Quitting with
+`C-g' does not do this, and could not do this because it is used to
+cancel a partially typed command within the recursive editing level.
+Both operations are useful. For example, if you are in the Emacs
+debugger (*note Lisp Debug::) and have typed `C-u 8' to enter a numeric
+argument, you can cancel that argument with `C-g' and remain in the
+debugger.
+
+ The command `M-x top-level' is equivalent to "enough" `C-]' commands
+to get you out of all the levels of recursive edits that you are in.
+`C-]' only gets you out one level at a time, but `M-x top-level' goes
+out all levels at once. Both `C-]' and `M-x top-level' are like all
+other commands and unlike `C-g' in that they are effective only when
+Emacs is ready for a command. `C-]' is an ordinary key and has its
+meaning only because of its binding in the keymap. *Note Recursive
+Edit::.
+
+ `C-x u' (`undo') is not strictly speaking a way of cancelling a
+command, but you can think of it as cancelling a command already
+finished executing. *Note Undo::.
+
+\1f
+File: xemacs.info, Node: Lossage, Next: Bugs, Prev: Quitting, Up: Top
+
+Dealing With Emacs Trouble
+==========================
+
+This section describes various conditions in which Emacs fails to work,
+and how to recognize them and correct them.
+
+* Menu:
+
+* Stuck Recursive:: `[...]' in mode line around the parentheses.
+* Screen Garbled:: Garbage on the screen.
+* Text Garbled:: Garbage in the text.
+* Unasked-for Search:: Spontaneous entry to incremental search.
+* Emergency Escape:: Emergency escape---
+ What to do if Emacs stops responding.
+* Total Frustration:: When you are at your wits' end.
+
+\1f
+File: xemacs.info, Node: Stuck Recursive, Next: Screen Garbled, Prev: Lossage, Up: Lossage
+
+Recursive Editing Levels
+------------------------
+
+Recursive editing levels are important and useful features of Emacs, but
+they can seem like malfunctions to the user who does not understand
+them.
+
+ If the mode line has square brackets `[...]' around the parentheses
+that contain the names of the major and minor modes, you have entered a
+recursive editing level. If you did not do this on purpose, or if you
+don't understand what that means, you should just get out of the
+recursive editing level. To do so, type `M-x top-level'. This is
+called getting back to top level. *Note Recursive Edit::.
+
+\1f
+File: xemacs.info, Node: Screen Garbled, Next: Text Garbled, Prev: Stuck Recursive, Up: Lossage
+
+Garbage on the Screen
+---------------------
+
+If the data on the screen looks wrong, the first thing to do is see
+whether the text is actually wrong. Type `C-l', to redisplay the
+entire screen. If the text appears correct after this, the problem was
+entirely in the previous screen update.
+
+ Display updating problems often result from an incorrect termcap
+entry for the terminal you are using. The file `etc/TERMS' in the Emacs
+distribution gives the fixes for known problems of this sort.
+`INSTALL' contains general advice for these problems in one of its
+sections. Very likely there is simply insufficient padding for certain
+display operations. To investigate the possibility that you have this
+sort of problem, try Emacs on another terminal made by a different
+manufacturer. If problems happen frequently on one kind of terminal but
+not another kind, the real problem is likely to be a bad termcap entry,
+though it could also be due to a bug in Emacs that appears for terminals
+that have or lack specific features.
+
+\1f
+File: xemacs.info, Node: Text Garbled, Next: Unasked-for Search, Prev: Screen Garbled, Up: Lossage
+
+Garbage in the Text
+-------------------
+
+If `C-l' shows that the text is wrong, try undoing the changes to it
+using `C-x u' until it gets back to a state you consider correct. Also
+try `C-h l' to find out what command you typed to produce the observed
+results.
+
+ If a large portion of text appears to be missing at the beginning or
+end of the buffer, check for the word `Narrow' in the mode line. If it
+appears, the text is still present, but marked off-limits. To make it
+visible again, type `C-x n w'. *Note Narrowing::.
+
+\1f
+File: xemacs.info, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage
+
+Spontaneous Entry to Incremental Search
+---------------------------------------
+
+If Emacs spontaneously displays `I-search:' at the bottom of the
+screen, it means that the terminal is sending `C-s' and `C-q' according
+to the poorly designed xon/xoff "flow control" protocol. You should
+try to prevent this by putting the terminal in a mode where it will not
+use flow control, or by giving it enough padding that it will never
+send a `C-s'. If that cannot be done, you must tell Emacs to expect
+flow control to be used, until you can get a properly designed terminal.
+
+ Information on how to do these things can be found in the file
+`INSTALL' in the Emacs distribution.
+
+\1f
+File: xemacs.info, Node: Emergency Escape, Next: Total Frustration, Prev: Unasked-for Search, Up: Lossage
+
+Emergency Escape
+----------------
+
+Because at times there have been bugs causing Emacs to loop without
+checking `quit-flag', a special feature causes Emacs to be suspended
+immediately if you type a second `C-g' while the flag is already set,
+so you can always get out of XEmacs. Normally Emacs recognizes and
+clears `quit-flag' (and quits!) quickly enough to prevent this from
+happening.
+
+ When you resume Emacs after a suspension caused by multiple `C-g', it
+asks two questions before going back to what it had been doing:
+
+ Auto-save? (y or n)
+ Abort (and dump core)? (y or n)
+
+Answer each one with `y' or `n' followed by <RET>.
+
+ Saying `y' to `Auto-save?' causes immediate auto-saving of all
+modified buffers in which auto-saving is enabled.
+
+ Saying `y' to `Abort (and dump core)?' causes an illegal instruction
+to be executed, dumping core. This is to enable a wizard to figure out
+why Emacs was failing to quit in the first place. Execution does not
+continue after a core dump. If you answer `n', execution does
+continue. With luck, Emacs will ultimately check `quit-flag' and quit
+normally. If not, and you type another `C-g', it is suspended again.
+
+ If Emacs is not really hung, but is just being slow, you may invoke
+the double `C-g' feature without really meaning to. In that case,
+simply resume and answer `n' to both questions, and you will arrive at
+your former state. Presumably the quit you requested will happen soon.
+
+ The double-`C-g' feature may be turned off when Emacs is running
+under a window system, since the window system always enables you to
+kill Emacs or to create another window and run another program.
+
+\1f
+File: xemacs.info, Node: Total Frustration, Prev: Emergency Escape, Up: Lossage
+
+Help for Total Frustration
+--------------------------
+
+If using Emacs (or something else) becomes terribly frustrating and none
+of the techniques described above solve the problem, Emacs can still
+help you.
+
+ First, if the Emacs you are using is not responding to commands, type
+`C-g C-g' to get out of it and then start a new one.
+
+ Second, type `M-x doctor <RET>'.
+
+ The doctor will make you feel better. Each time you say something to
+the doctor, you must end it by typing <RET> <RET>. This lets the
+doctor know you are finished.
+
+\1f
+File: xemacs.info, Node: Bugs, Prev: Lossage, Up: Top
+
+Reporting Bugs
+==============
+
+Sometimes you will encounter a bug in Emacs. Although we cannot promise
+we can or will fix the bug, and we might not even agree that it is a
+bug, we want to hear about bugs you encounter in case we do want to fix
+them.
+
+ To make it possible for us to fix a bug, you must report it. In
+order to do so effectively, you must know when and how to do it.
+
+When Is There a Bug
+-------------------
+
+If Emacs executes an illegal instruction, or dies with an operating
+system error message that indicates a problem in the program (as
+opposed to something like "disk full"), then it is certainly a bug.
+
+ If Emacs updates the display in a way that does not correspond to
+what is in the buffer, then it is certainly a bug. If a command seems
+to do the wrong thing but the problem corrects itself if you type
+`C-l', it is a case of incorrect display updating.
+
+ Taking forever to complete a command can be a bug, but you must make
+certain that it was really Emacs's fault. Some commands simply take a
+long time. Type `C-g' and then `C-h l' to see whether the input Emacs
+received was what you intended to type; if the input was such that you
+KNOW it should have been processed quickly, report a bug. If you don't
+know whether the command should take a long time, find out by looking
+in the manual or by asking for assistance.
+
+ If a command you are familiar with causes an Emacs error message in a
+case where its usual definition ought to be reasonable, it is probably a
+bug.
+
+ If a command does the wrong thing, that is a bug. But be sure you
+know for certain what it ought to have done. If you aren't familiar
+with the command, or don't know for certain how the command is supposed
+to work, then it might actually be working right. Rather than jumping
+to conclusions, show the problem to someone who knows for certain.
+
+ Finally, a command's intended definition may not be best for editing
+with. This is a very important sort of problem, but it is also a
+matter of judgment. Also, it is easy to come to such a conclusion out
+of ignorance of some of the existing features. It is probably best not
+to complain about such a problem until you have checked the
+documentation in the usual ways, feel confident that you understand it,
+and know for certain that what you want is not available. If you are
+not sure what the command is supposed to do after a careful reading of
+the manual, check the index and glossary for any terms that may be
+unclear. If you still do not understand, this indicates a bug in the
+manual. The manual's job is to make everything clear. It is just as
+important to report documentation bugs as program bugs.
+
+ If the online documentation string of a function or variable
+disagrees with the manual, one of them must be wrong, so report the bug.
+
+How to Report a Bug
+-------------------
+
+When you decide that there is a bug, it is important to report it and to
+report it in a way which is useful. What is most useful is an exact
+description of what commands you type, starting with the shell command
+to run Emacs, until the problem happens. Always include the version
+number of Emacs that you are using; type `M-x emacs-version' to print
+this.
+
+ The most important principle in reporting a bug is to report FACTS,
+not hypotheses or categorizations. It is always easier to report the
+facts, but people seem to prefer to strain to posit explanations and
+report them instead. If the explanations are based on guesses about
+how Emacs is implemented, they will be useless; we will have to try to
+figure out what the facts must have been to lead to such speculations.
+Sometimes this is impossible. But in any case, it is unnecessary work
+for us.
+
+ For example, suppose that you type `C-x C-f /glorp/baz.ugh <RET>',
+visiting a file which (you know) happens to be rather large, and Emacs
+prints out `I feel pretty today'. The best way to report the bug is
+with a sentence like the preceding one, because it gives all the facts
+and nothing but the facts.
+
+ Do not assume that the problem is due to the size of the file and
+say, "When I visit a large file, Emacs prints out `I feel pretty
+today'." This is what we mean by "guessing explanations". The problem
+is just as likely to be due to the fact that there is a `z' in the file
+name. If this is so, then when we got your report, we would try out
+the problem with some "large file", probably with no `z' in its name,
+and not find anything wrong. There is no way in the world that we
+could guess that we should try visiting a file with a `z' in its name.
+
+ Alternatively, the problem might be due to the fact that the file
+starts with exactly 25 spaces. For this reason, you should make sure
+that you inform us of the exact contents of any file that is needed to
+reproduce the bug. What if the problem only occurs when you have typed
+the `C-x a l' command previously? This is why we ask you to give the
+exact sequence of characters you typed since starting to use Emacs.
+
+ You should not even say "visit a file" instead of `C-x C-f' unless
+you know that it makes no difference which visiting command is used.
+Similarly, rather than saying "if I have three characters on the line,"
+say "after I type `<RET> A B C <RET> C-p'," if that is the way you
+entered the text.
+
+ If you are not in Fundamental mode when the problem occurs, you
+should say what mode you are in.
+
+ If the manifestation of the bug is an Emacs error message, it is
+important to report not just the text of the error message but a
+backtrace showing how the Lisp program in Emacs arrived at the error.
+To make the backtrace, you must execute the Lisp expression `(setq
+debug-on-error t)' before the error happens (that is to say, you must
+execute that expression and then make the bug happen). This causes the
+Lisp debugger to run (*note Lisp Debug::). The debugger's backtrace
+can be copied as text into the bug report. This use of the debugger is
+possible only if you know how to make the bug happen again. Do note
+the error message the first time the bug happens, so if you can't make
+it happen again, you can report at least that.
+
+ Check whether any programs you have loaded into the Lisp world,
+including your init file, set any variables that may affect the
+functioning of Emacs. *Note Init File::. Also, see whether the
+problem happens in a freshly started Emacs without loading your init
+file (start Emacs with the `-q' switch to prevent loading the init
+file). If the problem does NOT occur then, it is essential that we
+know the contents of any programs that you must load into the Lisp
+world in order to cause the problem to occur.
+
+ If the problem does depend on an init file or other Lisp programs
+that are not part of the standard Emacs system, then you should make
+sure it is not a bug in those programs by complaining to their
+maintainers first. After they verify that they are using Emacs in a
+way that is supposed to work, they should report the bug.
+
+ If you can tell us a way to cause the problem without visiting any
+files, please do so. This makes it much easier to debug. If you do
+need files, make sure you arrange for us to see their exact contents.
+For example, it can often matter whether there are spaces at the ends
+of lines, or a newline after the last line in the buffer (nothing ought
+to care whether the last line is terminated, but tell that to the bugs).
+
+ The easy way to record the input to Emacs precisely is to write a
+dribble file; execute the Lisp expression:
+
+ (open-dribble-file "~/dribble")
+
+using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
+Emacs. From then on, all Emacs input will be written in the specified
+dribble file until the Emacs process is killed.
+
+ For possible display bugs, it is important to report the terminal
+type (the value of environment variable `TERM'), the complete termcap
+entry for the terminal from `/etc/termcap' (since that file is not
+identical on all machines), and the output that Emacs actually sent to
+the terminal. The way to collect this output is to execute the Lisp
+expression:
+
+ (open-termscript "~/termscript")
+
+using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
+Emacs. From then on, all output from Emacs to the terminal will be
+written in the specified termscript file as well, until the Emacs
+process is killed. If the problem happens when Emacs starts up, put
+this expression into your init file so that the termscript file will be
+open when Emacs displays the screen for the first time. *Note Init
+File::. Be warned: it is often difficult, and sometimes impossible, to
+fix a terminal-dependent bug without access to a terminal of the type
+that stimulates the bug.
+
+ The newsgroup `comp.emacs.xemacs' may be used for bug reports, other
+discussions and requests for assistance.
+
+ If you don't have access to this newgroup, you can subscribe to the
+mailing list version: the newsgroup is bidirectionally gatewayed into
+the mailing list `xemacs@xemacs.org'.
+
+ To be added or removed from this mailing list, send mail to
+`xemacs-request@xemacs.org'. Do not send requests for addition to the
+mailing list itself.
+
+ The mailing lists and newsgroups are archived on our anonymous FTP
+server, `ftp.xemacs.org', and at various other archive sites around the
+net. You should also check the `FAQ' in `/pub/xemacs' on our anonymous
+FTP server. It provides some introductory information and help for
+initial configuration problems.
projects / chise / xemacs-chise.git.1 / blobdiff