XEmacs 21.4.19 (Constant Variable).

[chise/xemacs-chise.git.1] / info / lispref.info-4

This is ../info/lispref.info, produced by makeinfo version 4.8 from
lispref/lispref.texi.

INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* Lispref: (lispref).           XEmacs Lisp Reference Manual.
END-INFO-DIR-ENTRY

   Edition History:

   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
Copyright (C) 1995, 1996 Ben Wing.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.

\1f
File: lispref.info,  Node: Peeking and Discarding,  Prev: Quoted Character Input,  Up: Reading Input

25.6.5 Miscellaneous Event Input Features
-----------------------------------------

This section describes how to "peek ahead" at events without using them
up, how to check for pending input, and how to discard pending input.

   See also the variables `last-command-event' and `last-command-char'
(*Note Command Loop Info::).

 -- Variable: unread-command-events
     This variable holds a list of events waiting to be read as command
     input.  The events are used in the order they appear in the list,
     and removed one by one as they are used.

     The variable is needed because in some cases a function reads an
     event and then decides not to use it.  Storing the event in this
     variable causes it to be processed normally, by the command loop
     or by the functions to read command input.

     For example, the function that implements numeric prefix arguments
     reads any number of digits.  When it finds a non-digit event, it
     must unread the event so that it can be read normally by the
     command loop.  Likewise, incremental search uses this feature to
     unread events with no special meaning in a search, because these
     events should exit the search and then execute normally.


 -- Variable: unread-command-event
     This variable holds a single event to be read as command input.

     This variable is mostly obsolete now that you can use
     `unread-command-events' instead; it exists only to support programs
     written for versions of XEmacs prior to 19.12.

 -- Function: input-pending-p
     This function determines whether any command input is currently
     available to be read.  It returns immediately, with value `t' if
     there is available input, `nil' otherwise.  On rare occasions it
     may return `t' when no input is available.

 -- Variable: last-input-event
     This variable is set to the last keyboard or mouse button event
     received.

     This variable is off limits: you may not set its value or modify
     the event that is its value, as it is destructively modified by
     `read-key-sequence'.  If you want to keep a pointer to this value,
     you must use `copy-event'.

     Note that this variable is an alias for `last-input-char' in FSF
     Emacs.

     In the example below, a character is read (the character `1').  It
     becomes the value of `last-input-event', while `C-e' (from the
     `C-x C-e' command used to evaluate this expression) remains the
     value of `last-command-event'.

          (progn (print (next-command-event))
                 (print last-command-event)
                 last-input-event)
               -| #<keypress-event 1>
               -| #<keypress-event control-E>
               => #<keypress-event 1>

 -- Variable: last-input-char
     If the value of `last-input-event' is a keyboard event, then this
     is the nearest ASCII equivalent to it.  Remember that there is
     _not_ a 1:1 mapping between keyboard events and ASCII characters:
     the set of keyboard events is much larger, so writing code that
     examines this variable to determine what key has been typed is bad
     practice, unless you are certain that it will be one of a small
     set of characters.

     This function exists for compatibility with Emacs version 18.

 -- Function: discard-input
     This function discards the contents of the terminal input buffer
     and cancels any keyboard macro that might be in the process of
     definition.  It returns `nil'.

     In the following example, the user may type a number of characters
     right after starting the evaluation of the form.  After the
     `sleep-for' finishes sleeping, `discard-input' discards any
     characters typed during the sleep.

          (progn (sleep-for 2)
                 (discard-input))
               => nil

\1f
File: lispref.info,  Node: Waiting,  Next: Quitting,  Prev: Reading Input,  Up: Command Loop

25.7 Waiting for Elapsed Time or Input
======================================

The wait functions are designed to wait for a certain amount of time to
pass or until there is input.  For example, you may wish to pause in
the middle of a computation to allow the user time to view the display.
`sit-for' pauses and updates the screen, and returns immediately if
input comes in, while `sleep-for' pauses without updating the screen.

   Note that in FSF Emacs, the commands `sit-for' and `sleep-for' take
two arguments to specify the time (one integer and one float value),
instead of a single argument that can be either an integer or a float.

 -- Function: sit-for seconds &optional nodisplay
     This function performs redisplay (provided there is no pending
     input from the user), then waits SECONDS seconds, or until input is
     available.  The result is `t' if `sit-for' waited the full time
     with no input arriving (see `input-pending-p' in *Note Peeking and
     Discarding::).  Otherwise, the value is `nil'.

     The argument SECONDS need not be an integer.  If it is a floating
     point number, `sit-for' waits for a fractional number of seconds.

     Redisplay is normally preempted if input arrives, and does not
     happen at all if input is available before it starts. (You can
     force screen updating in such a case by using `force-redisplay'.
     *Note Refresh Screen::.) If there is no input pending, you can
     force an update with no delay by using `(sit-for 0)'.

     If NODISPLAY is non-`nil', then `sit-for' does not redisplay, but
     it still returns as soon as input is available (or when the
     timeout elapses).

     The usual purpose of `sit-for' is to give the user time to read
     text that you display.

 -- Function: sleep-for seconds
     This function simply pauses for SECONDS seconds without updating
     the display.  This function pays no attention to available input.
     It returns `nil'.

     The argument SECONDS need not be an integer.  If it is a floating
     point number, `sleep-for' waits for a fractional number of seconds.

     Use `sleep-for' when you wish to guarantee a delay.

   *Note Time of Day::, for functions to get the current time.

\1f
File: lispref.info,  Node: Quitting,  Next: Prefix Command Arguments,  Prev: Waiting,  Up: Command Loop

25.8 Quitting
=============

Typing `C-g' while a Lisp function is running causes XEmacs to "quit"
whatever it is doing.  This means that control returns to the innermost
active command loop.

   Typing `C-g' while the command loop is waiting for keyboard input
does not cause a quit; it acts as an ordinary input character.  In the
simplest case, you cannot tell the difference, because `C-g' normally
runs the command `keyboard-quit', whose effect is to quit.  However,
when `C-g' follows a prefix key, the result is an undefined key.  The
effect is to cancel the prefix key as well as any prefix argument.

   In the minibuffer, `C-g' has a different definition: it aborts out
of the minibuffer.  This means, in effect, that it exits the minibuffer
and then quits.  (Simply quitting would return to the command loop
_within_ the minibuffer.)  The reason why `C-g' does not quit directly
when the command reader is reading input is so that its meaning can be
redefined in the minibuffer in this way.  `C-g' following a prefix key
is not redefined in the minibuffer, and it has its normal effect of
canceling the prefix key and prefix argument.  This too would not be
possible if `C-g' always quit directly.

   When `C-g' does directly quit, it does so by setting the variable
`quit-flag' to `t'.  XEmacs checks this variable at appropriate times
and quits if it is not `nil'.  Setting `quit-flag' non-`nil' in any way
thus causes a quit.

   At the level of C code, quitting cannot happen just anywhere; only
at the special places that check `quit-flag'.  The reason for this is
that quitting at other places might leave an inconsistency in XEmacs's
internal state.  Because quitting is delayed until a safe place,
quitting cannot make XEmacs crash.

   Certain functions such as `read-key-sequence' or `read-quoted-char'
prevent quitting entirely even though they wait for input.  Instead of
quitting, `C-g' serves as the requested input.  In the case of
`read-key-sequence', this serves to bring about the special behavior of
`C-g' in the command loop.  In the case of `read-quoted-char', this is
so that `C-q' can be used to quote a `C-g'.

   You can prevent quitting for a portion of a Lisp function by binding
the variable `inhibit-quit' to a non-`nil' value.  Then, although `C-g'
still sets `quit-flag' to `t' as usual, the usual result of this--a
quit--is prevented.  Eventually, `inhibit-quit' will become `nil'
again, such as when its binding is unwound at the end of a `let' form.
At that time, if `quit-flag' is still non-`nil', the requested quit
happens immediately.  This behavior is ideal when you wish to make sure
that quitting does not happen within a "critical section" of the
program.

   In some functions (such as `read-quoted-char'), `C-g' is handled in
a special way that does not involve quitting.  This is done by reading
the input with `inhibit-quit' bound to `t', and setting `quit-flag' to
`nil' before `inhibit-quit' becomes `nil' again.  This excerpt from the
definition of `read-quoted-char' shows how this is done; it also shows
that normal quitting is permitted after the first character of input.

     (defun read-quoted-char (&optional prompt)
       "...DOCUMENTATION..."
       (let ((count 0) (code 0) char)
         (while (< count 3)
           (let ((inhibit-quit (zerop count))
                 (help-form nil))
             (and prompt (message "%s-" prompt))
             (setq char (read-char))
             (if inhibit-quit (setq quit-flag nil)))
           ...)
         (logand 255 code)))

 -- Variable: quit-flag
     If this variable is non-`nil', then XEmacs quits immediately,
     unless `inhibit-quit' is non-`nil'.  Typing `C-g' ordinarily sets
     `quit-flag' non-`nil', regardless of `inhibit-quit'.

 -- Variable: inhibit-quit
     This variable determines whether XEmacs should quit when
     `quit-flag' is set to a value other than `nil'.  If `inhibit-quit'
     is non-`nil', then `quit-flag' has no special effect.

 -- Command: keyboard-quit
     This function signals the `quit' condition with `(signal 'quit
     nil)'.  This is the same thing that quitting does.  (See `signal'
     in *Note Errors::.)

   You can specify a character other than `C-g' to use for quitting.
See the function `set-input-mode' in *Note Terminal Input::.

\1f
File: lispref.info,  Node: Prefix Command Arguments,  Next: Recursive Editing,  Prev: Quitting,  Up: Command Loop

25.9 Prefix Command Arguments
=============================

Most XEmacs commands can use a "prefix argument", a number specified
before the command itself.  (Don't confuse prefix arguments with prefix
keys.)  The prefix argument is at all times represented by a value,
which may be `nil', meaning there is currently no prefix argument.
Each command may use the prefix argument or ignore it.

   There are two representations of the prefix argument: "raw" and
"numeric".  The editor command loop uses the raw representation
internally, and so do the Lisp variables that store the information, but
commands can request either representation.

   Here are the possible values of a raw prefix argument:

   * `nil', meaning there is no prefix argument.  Its numeric value is
     1, but numerous commands make a distinction between `nil' and the
     integer 1.

   * An integer, which stands for itself.

   * A list of one element, which is an integer.  This form of prefix
     argument results from one or a succession of `C-u''s with no
     digits.  The numeric value is the integer in the list, but some
     commands make a distinction between such a list and an integer
     alone.

   * The symbol `-'.  This indicates that `M--' or `C-u -' was typed,
     without following digits.  The equivalent numeric value is -1, but
     some commands make a distinction between the integer -1 and the
     symbol `-'.

   We illustrate these possibilities by calling the following function
with various prefixes:

     (defun display-prefix (arg)
       "Display the value of the raw prefix arg."
       (interactive "P")
       (message "%s" arg))

Here are the results of calling `display-prefix' with various raw
prefix arguments:

             M-x display-prefix  -| nil

     C-u     M-x display-prefix  -| (4)

     C-u C-u M-x display-prefix  -| (16)

     C-u 3   M-x display-prefix  -| 3

     M-3     M-x display-prefix  -| 3      ; (Same as `C-u 3'.)

     C-3     M-x display-prefix  -| 3      ; (Same as `C-u 3'.)

     C-u -   M-x display-prefix  -| -

     M--     M-x display-prefix  -| -      ; (Same as `C-u -'.)

     C--     M-x display-prefix  -| -      ; (Same as `C-u -'.)

     C-u - 7 M-x display-prefix  -| -7

     M-- 7   M-x display-prefix  -| -7     ; (Same as `C-u -7'.)

     C-- 7   M-x display-prefix  -| -7     ; (Same as `C-u -7'.)

   XEmacs uses two variables to store the prefix argument: `prefix-arg'
and `current-prefix-arg'.  Commands such as `universal-argument' that
set up prefix arguments for other commands store them in `prefix-arg'.
In contrast, `current-prefix-arg' conveys the prefix argument to the
current command, so setting it has no effect on the prefix arguments
for future commands.

   Normally, commands specify which representation to use for the prefix
argument, either numeric or raw, in the `interactive' declaration.
(*Note Using Interactive::.)  Alternatively, functions may look at the
value of the prefix argument directly in the variable
`current-prefix-arg', but this is less clean.

 -- Function: prefix-numeric-value raw
     This function returns the numeric meaning of a valid raw prefix
     argument value, RAW.  The argument may be a symbol, a number, or a
     list.  If it is `nil', the value 1 is returned; if it is `-', the
     value -1 is returned; if it is a number, that number is returned;
     if it is a list, the CAR of that list (which should be a number) is
     returned.

 -- Variable: current-prefix-arg
     This variable holds the raw prefix argument for the _current_
     command.  Commands may examine it directly, but the usual way to
     access it is with `(interactive "P")'.

 -- Variable: prefix-arg
     The value of this variable is the raw prefix argument for the
     _next_ editing command.  Commands that specify prefix arguments for
     the following command work by setting this variable.

   Do not call the functions `universal-argument', `digit-argument', or
`negative-argument' unless you intend to let the user enter the prefix
argument for the _next_ command.

 -- Command: universal-argument
     This command reads input and specifies a prefix argument for the
     following command.  Don't call this command yourself unless you
     know what you are doing.

 -- Command: digit-argument arg
     This command adds to the prefix argument for the following
     command.  The argument ARG is the raw prefix argument as it was
     before this command; it is used to compute the updated prefix
     argument.  Don't call this command yourself unless you know what
     you are doing.

 -- Command: negative-argument arg
     This command adds to the numeric argument for the next command.
     The argument ARG is the raw prefix argument as it was before this
     command; its value is negated to form the new prefix argument.
     Don't call this command yourself unless you know what you are
     doing.

\1f
File: lispref.info,  Node: Recursive Editing,  Next: Disabling Commands,  Prev: Prefix Command Arguments,  Up: Command Loop

25.10 Recursive Editing
=======================

The XEmacs command loop is entered automatically when XEmacs starts up.
This top-level invocation of the command loop never exits; it keeps
running as long as XEmacs does.  Lisp programs can also invoke the
command loop.  Since this makes more than one activation of the command
loop, we call it "recursive editing".  A recursive editing level has
the effect of suspending whatever command invoked it and permitting the
user to do arbitrary editing before resuming that command.

   The commands available during recursive editing are the same ones
available in the top-level editing loop and defined in the keymaps.
Only a few special commands exit the recursive editing level; the others
return to the recursive editing level when they finish.  (The special
commands for exiting are always available, but they do nothing when
recursive editing is not in progress.)

   All command loops, including recursive ones, set up all-purpose error
handlers so that an error in a command run from the command loop will
not exit the loop.

   Minibuffer input is a special kind of recursive editing.  It has a
few special wrinkles, such as enabling display of the minibuffer and the
minibuffer window, but fewer than you might suppose.  Certain keys
behave differently in the minibuffer, but that is only because of the
minibuffer's local map; if you switch windows, you get the usual XEmacs
commands.

   To invoke a recursive editing level, call the function
`recursive-edit'.  This function contains the command loop; it also
contains a call to `catch' with tag `exit', which makes it possible to
exit the recursive editing level by throwing to `exit' (*note Catch and
Throw::).  If you throw a value other than `t', then `recursive-edit'
returns normally to the function that called it.  The command `C-M-c'
(`exit-recursive-edit') does this.  Throwing a `t' value causes
`recursive-edit' to quit, so that control returns to the command loop
one level up.  This is called "aborting", and is done by `C-]'
(`abort-recursive-edit').

   Most applications should not use recursive editing, except as part of
using the minibuffer.  Usually it is more convenient for the user if you
change the major mode of the current buffer temporarily to a special
major mode, which should have a command to go back to the previous mode.
(The `e' command in Rmail uses this technique.)  Or, if you wish to
give the user different text to edit "recursively", create and select a
new buffer in a special mode.  In this mode, define a command to
complete the processing and go back to the previous buffer.  (The `m'
command in Rmail does this.)

   Recursive edits are useful in debugging.  You can insert a call to
`debug' into a function definition as a sort of breakpoint, so that you
can look around when the function gets there.  `debug' invokes a
recursive edit but also provides the other features of the debugger.

   Recursive editing levels are also used when you type `C-r' in
`query-replace' or use `C-x q' (`kbd-macro-query').

 -- Command: recursive-edit
     This function invokes the editor command loop.  It is called
     automatically by the initialization of XEmacs, to let the user
     begin editing.  When called from a Lisp program, it enters a
     recursive editing level.

     In the following example, the function `simple-rec' first advances
     point one word, then enters a recursive edit, printing out a
     message in the echo area.  The user can then do any editing
     desired, and then type `C-M-c' to exit and continue executing
     `simple-rec'.

          (defun simple-rec ()
            (forward-word 1)
            (message "Recursive edit in progress")
            (recursive-edit)
            (forward-word 1))
               => simple-rec
          (simple-rec)
               => nil

 -- Command: exit-recursive-edit
     This function exits from the innermost recursive edit (including
     minibuffer input).  Its definition is effectively `(throw 'exit
     nil)'.

 -- Command: abort-recursive-edit
     This function aborts the command that requested the innermost
     recursive edit (including minibuffer input), by signaling `quit'
     after exiting the recursive edit.  Its definition is effectively
     `(throw 'exit t)'.  *Note Quitting::.

 -- Command: top-level
     This function exits all recursive editing levels; it does not
     return a value, as it jumps completely out of any computation
     directly back to the main command loop.

 -- Function: recursion-depth
     This function returns the current depth of recursive edits.  When
     no recursive edit is active, it returns 0.

\1f
File: lispref.info,  Node: Disabling Commands,  Next: Command History,  Prev: Recursive Editing,  Up: Command Loop

25.11 Disabling Commands
========================

"Disabling a command" marks the command as requiring user confirmation
before it can be executed.  Disabling is used for commands which might
be confusing to beginning users, to prevent them from using the
commands by accident.

   The low-level mechanism for disabling a command is to put a
non-`nil' `disabled' property on the Lisp symbol for the command.
These properties are normally set up by the user's `.emacs' file with
Lisp expressions such as this:

     (put 'upcase-region 'disabled t)

For a few commands, these properties are present by default and may be
removed by the `.emacs' file.

   If the value of the `disabled' property is a string, the message
saying the command is disabled includes that string.  For example:

     (put 'delete-region 'disabled
          "Text deleted this way cannot be yanked back!\n")

   *Note Disabling: (xemacs)Disabling, for the details on what happens
when a disabled command is invoked interactively.  Disabling a command
has no effect on calling it as a function from Lisp programs.

 -- Command: enable-command command
     Allow COMMAND to be executed without special confirmation from now
     on, and (if the user confirms) alter the user's `.emacs' file so
     that this will apply to future sessions.

 -- Command: disable-command command
     Require special confirmation to execute COMMAND from now on, and
     (if the user confirms) alter the user's `.emacs' file so that this
     will apply to future sessions.

 -- Variable: disabled-command-hook
     This normal hook is run instead of a disabled command, when the
     user invokes the disabled command interactively.  The hook
     functions can use `this-command-keys' to determine what the user
     typed to run the command, and thus find the command itself.  *Note
     Hooks::.

     By default, `disabled-command-hook' contains a function that asks
     the user whether to proceed.

\1f
File: lispref.info,  Node: Command History,  Next: Keyboard Macros,  Prev: Disabling Commands,  Up: Command Loop

25.12 Command History
=====================

The command loop keeps a history of the complex commands that have been
executed, to make it convenient to repeat these commands.  A "complex
command" is one for which the interactive argument reading uses the
minibuffer.  This includes any `M-x' command, any `M-:' command, and
any command whose `interactive' specification reads an argument from
the minibuffer.  Explicit use of the minibuffer during the execution of
the command itself does not cause the command to be considered complex.

 -- Variable: command-history
     This variable's value is a list of recent complex commands, each
     represented as a form to evaluate.  It continues to accumulate all
     complex commands for the duration of the editing session, but all
     but the first (most recent) thirty elements are deleted when a
     garbage collection takes place (*note Garbage Collection::).

          command-history
          => ((switch-to-buffer "chistory.texi")
              (describe-key "^X^[")
              (visit-tags-table "~/emacs/src/")
              (find-tag "repeat-complex-command"))

   This history list is actually a special case of minibuffer history
(*note Minibuffer History::), with one special twist: the elements are
expressions rather than strings.

   There are a number of commands devoted to the editing and recall of
previous commands.  The commands `repeat-complex-command', and
`list-command-history' are described in the user manual (*note
Repetition: (xemacs)Repetition.).  Within the minibuffer, the history
commands used are the same ones available in any minibuffer.

\1f
File: lispref.info,  Node: Keyboard Macros,  Prev: Command History,  Up: Command Loop

25.13 Keyboard Macros
=====================

A "keyboard macro" is a canned sequence of input events that can be
considered a command and made the definition of a key.  The Lisp
representation of a keyboard macro is a string or vector containing the
events.  Don't confuse keyboard macros with Lisp macros (*note
Macros::).

 -- Function: execute-kbd-macro macro &optional count
     This function executes MACRO as a sequence of events.  If MACRO is
     a string or vector, then the events in it are executed exactly as
     if they had been input by the user.  The sequence is _not_
     expected to be a single key sequence; normally a keyboard macro
     definition consists of several key sequences concatenated.

     If MACRO is a symbol, then its function definition is used in
     place of MACRO.  If that is another symbol, this process repeats.
     Eventually the result should be a string or vector.  If the result
     is not a symbol, string, or vector, an error is signaled.

     The argument COUNT is a repeat count; MACRO is executed that many
     times.  If COUNT is omitted or `nil', MACRO is executed once.  If
     it is 0, MACRO is executed over and over until it encounters an
     error or a failing search.

 -- Variable: executing-macro
     This variable contains the string or vector that defines the
     keyboard macro that is currently executing.  It is `nil' if no
     macro is currently executing.  A command can test this variable to
     behave differently when run from an executing macro.  Do not set
     this variable yourself.

 -- Variable: defining-kbd-macro
     This variable indicates whether a keyboard macro is being defined.
     A command can test this variable to behave differently while a
     macro is being defined.  The commands `start-kbd-macro' and
     `end-kbd-macro' set this variable--do not set it yourself.

 -- Variable: last-kbd-macro
     This variable is the definition of the most recently defined
     keyboard macro.  Its value is a string or vector, or `nil'.

   The commands are described in the user's manual (*note Keyboard
Macros: (xemacs)Keyboard Macros.).

\1f
File: lispref.info,  Node: Keymaps,  Next: Menus,  Prev: Command Loop,  Up: Top

26 Keymaps
**********

The bindings between input events and commands are recorded in data
structures called "keymaps".  Each binding in a keymap associates (or
"binds") an individual event type either with another keymap or with a
command.  When an event is bound to a keymap, that keymap is used to
look up the next input event; this continues until a command is found.
The whole process is called "key lookup".

* Menu:

* Keymap Terminology::       Definitions of terms pertaining to keymaps.
* Format of Keymaps::        What a keymap looks like as a Lisp object.
* Creating Keymaps::         Functions to create and copy keymaps.
* Inheritance and Keymaps::  How one keymap can inherit the bindings
                                of another keymap.
* Key Sequences::            How to specify key sequences.
* Prefix Keys::              Defining a key with a keymap as its definition.
* Active Keymaps::           Each buffer has a local keymap
                                to override the standard (global) bindings.
                                A minor mode can also override them.
* Key Lookup::               How extracting elements from keymaps works.
* Functions for Key Lookup:: How to request key lookup.
* Changing Key Bindings::    Redefining a key in a keymap.
* Key Binding Commands::     Interactive interfaces for redefining keys.
* Scanning Keymaps::         Looking through all keymaps, for printing help.
* Other Keymap Functions::   Miscellaneous keymap functions.

\1f
File: lispref.info,  Node: Keymap Terminology,  Next: Format of Keymaps,  Up: Keymaps

26.1 Keymap Terminology
=======================

A "keymap" is a table mapping event types to definitions (which can be
any Lisp objects, though only certain types are meaningful for
execution by the command loop).  Given an event (or an event type) and a
keymap, XEmacs can get the event's definition.  Events mapped in keymaps
include keypresses, button presses, and button releases (*note
Events::).

   A sequence of input events that form a unit is called a "key
sequence", or "key" for short.  A sequence of one event is always a key
sequence, and so are some multi-event sequences.

   A keymap determines a binding or definition for any key sequence.  If
the key sequence is a single event, its binding is the definition of the
event in the keymap.  The binding of a key sequence of more than one
event is found by an iterative process: the binding of the first event
is found, and must be a keymap; then the second event's binding is found
in that keymap, and so on until all the events in the key sequence are
used up.

   If the binding of a key sequence is a keymap, we call the key
sequence a "prefix key".  Otherwise, we call it a "complete key"
(because no more events can be added to it).  If the binding is `nil',
we call the key "undefined".  Examples of prefix keys are `C-c', `C-x',
and `C-x 4'.  Examples of defined complete keys are `X', <RET>, and
`C-x 4 C-f'.  Examples of undefined complete keys are `C-x C-g', and
`C-c 3'.  *Note Prefix Keys::, for more details.

   The rule for finding the binding of a key sequence assumes that the
intermediate bindings (found for the events before the last) are all
keymaps; if this is not so, the sequence of events does not form a
unit--it is not really a key sequence.  In other words, removing one or
more events from the end of any valid key must always yield a prefix
key.  For example, `C-f C-n' is not a key; `C-f' is not a prefix key,
so a longer sequence starting with `C-f' cannot be a key.

   Note that the set of possible multi-event key sequences depends on
the bindings for prefix keys; therefore, it can be different for
different keymaps, and can change when bindings are changed.  However,
a one-event sequence is always a key sequence, because it does not
depend on any prefix keys for its well-formedness.

   At any time, several primary keymaps are "active"--that is, in use
for finding key bindings.  These are the "global map", which is shared
by all buffers; the "local keymap", which is usually associated with a
specific major mode; and zero or more "minor mode keymaps", which
belong to currently enabled minor modes.  (Not all minor modes have
keymaps.)  The local keymap bindings shadow (i.e., take precedence
over) the corresponding global bindings.  The minor mode keymaps shadow
both local and global keymaps.  *Note Active Keymaps::, for details.

\1f
File: lispref.info,  Node: Format of Keymaps,  Next: Creating Keymaps,  Prev: Keymap Terminology,  Up: Keymaps

26.2 Format of Keymaps
======================

A keymap is a primitive type that associates events with their
bindings.  Note that this is different from Emacs 18 and FSF Emacs,
where keymaps are lists.

 -- Function: keymapp object
     This function returns `t' if OBJECT is a keymap, `nil' otherwise.

\1f
File: lispref.info,  Node: Creating Keymaps,  Next: Inheritance and Keymaps,  Prev: Format of Keymaps,  Up: Keymaps

26.3 Creating Keymaps
=====================

Here we describe the functions for creating keymaps.

 -- Function: make-keymap &optional name
     This function constructs and returns a new keymap object.  All
     entries in it are `nil', meaning "command undefined".

     Optional argument NAME specifies a name to assign to the keymap,
     as in `set-keymap-name'.  This name is only a debugging
     convenience; it is not used except when printing the keymap.

 -- Function: make-sparse-keymap &optional name
     This function constructs and returns a new keymap object.  All
     entries in it are `nil', meaning "command undefined".  The only
     difference between this function and `make-keymap' is that this
     function returns a "smaller" keymap (one that is expected to
     contain fewer entries).  As keymaps dynamically resize, this
     distinction is not great.

     Optional argument NAME specifies a name to assign to the keymap,
     as in `set-keymap-name'.  This name is only a debugging
     convenience; it is not used except when printing the keymap.

 -- Function: set-keymap-name keymap new-name
     This function assigns a "name" to a keymap.  The name is only a
     debugging convenience; it is not used except when printing the
     keymap.

 -- Function: keymap-name keymap
     This function returns the "name" of a keymap, as assigned using
     `set-keymap-name'.

 -- Function: copy-keymap keymap
     This function returns a copy of KEYMAP.  Any keymaps that appear
     directly as bindings in KEYMAP are also copied recursively, and so
     on to any number of levels.  However, recursive copying does not
     take place when the definition of a character is a symbol whose
     function definition is a keymap; the same symbol appears in the
     new copy.

          (setq map (copy-keymap (current-local-map)))
          => #<keymap 3 entries 0x21f80>

          (eq map (current-local-map))
              => nil

\1f
File: lispref.info,  Node: Inheritance and Keymaps,  Next: Key Sequences,  Prev: Creating Keymaps,  Up: Keymaps

26.4 Inheritance and Keymaps
============================

A keymap can inherit the bindings of other keymaps.  The other keymaps
are called the keymap's "parents", and are set with
`set-keymap-parents'.  When searching for a binding for a key sequence
in a particular keymap, that keymap itself will first be searched;
then, if no binding was found in the map and it has parents, the first
parent keymap will be searched; then that keymap's parent will be
searched, and so on, until either a binding for the key sequence is
found, or a keymap without a parent is encountered.  At this point, the
search will continue with the next parent of the most recently
encountered keymap that has another parent, etc.  Essentially, a
depth-first search of all the ancestors of the keymap is conducted.

   `(current-global-map)' is the default parent of all keymaps.

 -- Function: set-keymap-parents keymap parents
     This function sets the parent keymaps of KEYMAP to the list
     PARENTS.

     If you change the bindings in one of the keymaps in PARENTS using
     `define-key' or other key-binding functions, these changes are
     visible in KEYMAP unless shadowed by bindings in that map or in
     earlier-searched ancestors.  The converse is not true: if you use
     `define-key' to change KEYMAP, that affects the bindings in that
     map, but has no effect on any of the keymaps in PARENTS.

 -- Function: keymap-parents keymap
     This function returns the list of parent keymaps of KEYMAP, or
     `nil' if KEYMAP has no parents.

   As an alternative to specifying a parent, you can also specify a
"default binding" that is used whenever a key is not otherwise bound in
the keymap.  This is useful for terminal emulators, for example, which
may want to trap all keystrokes and pass them on in some modified
format.  Note that if you specify a default binding for a keymap,
neither the keymap's parents nor the current global map are searched for
key bindings.

 -- Function: set-keymap-default-binding keymap command
     This function sets the default binding of KEYMAP to COMMAND, or
     `nil' if no default is desired.

 -- Function: keymap-default-binding keymap
     This function returns the default binding of KEYMAP, or `nil' if
     it has none.

\1f
File: lispref.info,  Node: Key Sequences,  Next: Prefix Keys,  Prev: Inheritance and Keymaps,  Up: Keymaps

26.5 Key Sequences
==================

Contrary to popular belief, the world is not ASCII.  When running under
a window manager, XEmacs can tell the difference between, for example,
the keystrokes `control-h', `control-shift-h', and `backspace'.  You
can, in fact, bind different commands to each of these.

   A "key sequence" is a set of keystrokes.  A "keystroke" is a keysym
and some set of modifiers (such as <CONTROL> and <META>).  A "keysym"
is what is printed on the keys on your keyboard.

   A keysym may be represented by a symbol, or (if and only if it is
equivalent to an ASCII character in the range 32 - 255) by a character
or its equivalent ASCII code.  The `A' key may be represented by the
symbol `A', the character `?A', or by the number 65.  The `break' key
may be represented only by the symbol `break'.

   A keystroke may be represented by a list: the last element of the
list is the key (a symbol, character, or number, as above) and the
preceding elements are the symbolic names of modifier keys (<CONTROL>,
<META>, <SUPER>, <HYPER>, <ALT>, and <SHIFT>).  Thus, the sequence
`control-b' is represented by the forms `(control b)', `(control ?b)',
and `(control 98)'.  A keystroke may also be represented by an event
object, as returned by the `next-command-event' and `read-key-sequence'
functions.

   Note that in this context, the keystroke `control-b' is _not_
represented by the number 2 (the ASCII code for `^B') or the character
`?\^B'.  See below.

   The <SHIFT> modifier is somewhat of a special case.  You should not
(and cannot) use `(meta shift a)' to mean `(meta A)', since for
characters that have ASCII equivalents, the state of the shift key is
implicit in the keysym (`a' vs. `A').  You also cannot say `(shift =)'
to mean `+', as that sort of thing varies from keyboard to keyboard.
The <SHIFT> modifier is for use only with characters that do not have a
second keysym on the same key, such as `backspace' and `tab'.

   A key sequence is a vector of keystrokes.  As a degenerate case,
elements of this vector may also be keysyms if they have no modifiers.
That is, the `A' keystroke is represented by all of these forms:

             A       ?A      65      (A)     (?A)    (65)
             [A]     [?A]    [65]    [(A)]   [(?A)]  [(65)]

   the `control-a' keystroke is represented by these forms:

             (control A)     (control ?A)    (control 65)
             [(control A)]   [(control ?A)]  [(control 65)]

   the key sequence `control-c control-a' is represented by these forms:

             [(control c) (control a)]       [(control ?c) (control ?a)]
             [(control 99) (control 65)]     etc.

   Mouse button clicks work just like keypresses: `(control button1)'
means pressing the left mouse button while holding down the control
key.  `[(control c) (shift button3)]' means `control-c', hold <SHIFT>,
click right.

   Commands may be bound to the mouse-button up-stroke rather than the
down-stroke as well.  `button1' means the down-stroke, and `button1up'
means the up-stroke.  Different commands may be bound to the up and
down strokes, though that is probably not what you want, so be careful.

   For backward compatibility, a key sequence may also be represented by
a string.  In this case, it represents the key sequence(s) that would
produce that sequence of ASCII characters in a purely ASCII world.  For
example, a string containing the ASCII backspace character, `"\^H"',
would represent two key sequences: `(control h)' and `backspace'.
Binding a command to this will actually bind both of those key
sequences.  Likewise for the following pairs:

                     control h       backspace
                     control i       tab
                     control m       return
                     control j       linefeed
                     control [       escape
                     control @      control space

   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)

   Of course, all of this applies only when running under a window
system.  If you're talking to XEmacs through a TTY connection, you
don't get any of these features.

 -- Function: event-matches-key-specifier-p event key-specifier
     This function returns non-`nil' if EVENT matches KEY-SPECIFIER,
     which can be any valid form representing a key sequence.  This can
     be useful, e.g., to determine if the user pressed `help-char' or
     `quit-char'.

\1f
File: lispref.info,  Node: Prefix Keys,  Next: Active Keymaps,  Prev: Key Sequences,  Up: Keymaps

26.6 Prefix Keys
================

A "prefix key" has an associated keymap that defines what to do with
key sequences that start with the prefix key.  For example, `C-x' is a
prefix key, and it uses a keymap that is also stored in the variable
`ctl-x-map'.  Here is a list of the standard prefix keys of XEmacs and
their keymaps:

   * `help-map' is used for events that follow `C-h'.

   * `mode-specific-map' is for events that follow `C-c'.  This map is
     not actually mode specific; its name was chosen to be informative
     for the user in `C-h b' (`display-bindings'), where it describes
     the main use of the `C-c' prefix key.

   * `ctl-x-map' is the map used for events that follow `C-x'.  This
     map is also the function definition of `Control-X-prefix'.

   * `ctl-x-4-map' is used for events that follow `C-x 4'.

   * `ctl-x-5-map' is used for events that follow `C-x 5'.

   * The prefix keys `C-x n', `C-x r' and `C-x a' use keymaps that have
     no special name.

   * `esc-map' is an evil hack that is present for compatibility
     purposes with Emacs 18.  Defining a key in `esc-map' is equivalent
     to defining the same key in `global-map' but with the <META>
     prefix added.  You should _not_ use this in your code. (This map is
     also the function definition of `ESC-prefix'.)

   The binding of a prefix key is the keymap to use for looking up the
events that follow the prefix key.  (It may instead be a symbol whose
function definition is a keymap.  The effect is the same, but the symbol
serves as a name for the prefix key.)  Thus, the binding of `C-x' is
the symbol `Control-X-prefix', whose function definition is the keymap
for `C-x' commands.  (The same keymap is also the value of `ctl-x-map'.)

   Prefix key definitions can appear in any active keymap.  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 and
minor modes can redefine a key as a prefix by putting a prefix key
definition for it in the local map or the minor mode's map.  *Note
Active Keymaps::.

   If a key is defined as a prefix in more than one active map, then its
various definitions are in effect merged: the commands defined in the
minor mode keymaps come first, followed by those in the local map's
prefix definition, and then by those from the global map.

   In the following example, we make `C-p' a prefix key in the local
keymap, in such a way that `C-p' is identical to `C-x'.  Then the
binding for `C-p C-f' is the function `find-file', just like `C-x C-f'.
The key sequence `C-p 6' is not found in any active keymap.

     (use-local-map (make-sparse-keymap))
         => nil
     (local-set-key "\C-p" ctl-x-map)
         => nil
     (key-binding "\C-p\C-f")
         => find-file

     (key-binding "\C-p6")
         => nil

 -- Function: define-prefix-command symbol &optional mapvar
     This function defines SYMBOL as a prefix command: it creates a
     keymap and stores it as SYMBOL's function definition.  Storing the
     symbol as the binding of a key makes the key a prefix key that has
     a name.  If optional argument MAPVAR is not specified, it also
     sets SYMBOL as a variable, to have the keymap as its value. (If
     MAPVAR is given and is not `t', its value is stored as the value
     of SYMBOL.) The function returns SYMBOL.

     In Emacs version 18, only the function definition of SYMBOL was
     set, not the value as a variable.

\1f
File: lispref.info,  Node: Active Keymaps,  Next: Key Lookup,  Prev: Prefix Keys,  Up: Keymaps

26.7 Active Keymaps
===================

XEmacs normally contains many keymaps; at any given time, just a few of
them are "active" in that they participate in the interpretation of
user input.  These are the global keymap, the current buffer's local
keymap, and the keymaps of any enabled minor modes.

   The "global keymap" holds the bindings of keys that are defined
regardless of the current buffer, such as `C-f'.  The variable
`global-map' holds this keymap, which is always active.

   Each buffer may have another keymap, its "local keymap", which may
contain new or overriding definitions for keys.  The current buffer's
local keymap is always active except when `overriding-local-map' or
`overriding-terminal-local-map' overrides it.  Extents and text
properties can specify an alternative local map for certain parts of the
buffer; see *Note Extents and Events::.

   Each minor mode may have a keymap; if it does, the keymap is active
when the minor mode is enabled.

   The variable `overriding-local-map' and
`overriding-terminal-local-map', if non-`nil', specify other local
keymaps that override the buffer's local map and all the minor mode
keymaps.

   All the active keymaps are used together to determine what command to
execute when a key is entered.  XEmacs searches these maps one by one,
in order of decreasing precedence, until it finds a binding in one of
the maps.

   More specifically:

   For key-presses, the order of keymaps searched is:

   * the `keymap' property of any extent(s) or text properties at point;

   * any applicable minor-mode maps;

   * the current local map of the current buffer;

   * the current global map.

   For mouse-clicks, the order of keymaps searched is:

   * the current local map of the `mouse-grabbed-buffer' if any;

   * the `keymap' property of any extent(s) at the position of the click
     (this includes modeline extents);

   * the `modeline-map' of the buffer corresponding to the modeline
     under the mouse (if the click happened over a modeline);

   * the value of `toolbar-map' in the current buffer (if the click
     happened over a toolbar);

   * the current local map of the buffer under the mouse (does not
     apply to toolbar clicks);

   * any applicable minor-mode maps;

   * the current global map.

   Note that if `overriding-local-map' or
`overriding-terminal-local-map' is non-`nil', _only_ those two maps and
the current global map are searched.

   The procedure for searching a single keymap is called "key lookup";
see *Note Key Lookup::.

   Since every buffer that uses the same major mode normally uses the
same local keymap, you can think of the keymap as local to the mode.  A
change to the local keymap of a buffer (using `local-set-key', for
example) is seen also in the other buffers that share that keymap.

   The local keymaps that are used for Lisp mode, C mode, and several
other major modes exist even if they have not yet been used.  These
local maps are the values of the variables `lisp-mode-map',
`c-mode-map', and so on.  For most other modes, which are less
frequently used, the local keymap is constructed only when the mode is
used for the first time in a session.

   The minibuffer has local keymaps, too; they contain various
completion and exit commands.  *Note Intro to Minibuffers::.

   *Note Standard Keymaps::, for a list of standard keymaps.

 -- Function: current-keymaps &optional event-or-keys
     This function returns a list of the current keymaps that will be
     searched for bindings.  This lists keymaps such as the current
     local map and the minor-mode maps, but does not list the parents
     of those keymaps.  EVENT-OR-KEYS controls which keymaps will be
     listed.  If EVENT-OR-KEYS is a mouse event (or a vector whose last
     element is a mouse event), the keymaps for that mouse event will
     be listed.  Otherwise, the keymaps for key presses will be listed.

 -- Variable: global-map
     This variable contains the default global keymap that maps XEmacs
     keyboard input to commands.  The global keymap is normally this
     keymap.  The default global keymap is a full keymap that binds
     `self-insert-command' to all of the printing characters.

     It is normal practice to change the bindings in the global map,
     but you should not assign this variable any value other than the
     keymap it starts out with.

 -- Function: current-global-map
     This function returns the current global keymap.  This is the same
     as the value of `global-map' unless you change one or the other.

          (current-global-map)
          => #<keymap global-map 639 entries 0x221>

 -- Function: current-local-map &optional buffer
     This function returns BUFFER's local keymap, or `nil' if it has
     none.  BUFFER defaults to the current buffer.

     In the following example, the keymap for the `*scratch*' buffer
     (using Lisp Interaction mode) has a number of entries, including
     one prefix key, `C-x'.

          (current-local-map)
          => #<keymap lisp-interaction-mode-map 5 entries 0x558>
          (describe-bindings-internal (current-local-map))
          =>  ; Inserted into the buffer:
          backspace       backward-delete-char-untabify
          linefeed        eval-print-last-sexp
          delete          delete-char
          C-j             eval-print-last-sexp
          C-x             << Prefix Command >>
          M-tab           lisp-complete-symbol
          M-;             lisp-indent-for-comment
          M-C-i           lisp-complete-symbol
          M-C-q           indent-sexp
          M-C-x           eval-defun
          Alt-backspace   backward-kill-sexp
          Alt-delete      kill-sexp

          C-x x           edebug-defun

 -- Function: current-minor-mode-maps
     This function returns a list of the keymaps of currently enabled
     minor modes.

 -- Function: use-global-map keymap
     This function makes KEYMAP the new current global keymap.  It
     returns `nil'.

     It is very unusual to change the global keymap.

 -- Function: use-local-map keymap &optional buffer
     This function makes KEYMAP the new local keymap of BUFFER.  BUFFER
     defaults to the current buffer.  If KEYMAP is `nil', then the
     buffer has no local keymap.  `use-local-map' returns `nil'.  Most
     major mode commands use this function.

 -- Variable: minor-mode-map-alist
     This variable is an alist describing keymaps that may or may not be
     active according to the values of certain variables.  Its elements
     look like this:

          (VARIABLE . KEYMAP)

     The keymap KEYMAP is active whenever VARIABLE has a non-`nil'
     value.  Typically VARIABLE is the variable that enables or
     disables a minor mode.  *Note Keymaps and Minor Modes::.

     Note that elements of `minor-mode-map-alist' do not have the same
     structure as elements of `minor-mode-alist'.  The map must be the
     CDR of the element; a list with the map as the second element will
     not do.

     What's more, the keymap itself must appear in the CDR.  It does not
     work to store a variable in the CDR and make the map the value of
     that variable.

     When more than one minor mode keymap is active, their order of
     priority is the order of `minor-mode-map-alist'.  But you should
     design minor modes so that they don't interfere with each other.
     If you do this properly, the order will not matter.

     See also `minor-mode-key-binding', above.  See *Note Keymaps and
     Minor Modes::, for more information about minor modes.

 -- Variable: modeline-map
     This variable holds the keymap consulted for mouse-clicks on the
     modeline of a window.  This variable may be buffer-local; its
     value will be looked up in the buffer of the window whose modeline
     was clicked upon.

 -- Variable: toolbar-map
     This variable holds the keymap consulted for mouse-clicks over a
     toolbar.

 -- Variable: mouse-grabbed-buffer
     If non-`nil', a buffer which should be consulted first for all
     mouse activity.  When a mouse-click is processed, it will first be
     looked up in the local-map of this buffer, and then through the
     normal mechanism if there is no binding for that click.  This
     buffer's value of `mode-motion-hook' will be consulted instead of
     the `mode-motion-hook' of the buffer of the window under the mouse.
     You should _bind_ this, not set it.

 -- Variable: overriding-local-map
     If non-`nil', this variable holds a keymap to use instead of the
     buffer's local keymap and instead of all the minor mode keymaps.
     This keymap, if any, overrides all other maps that would have been
     active, except for the current global map.

 -- Variable: overriding-terminal-local-map
     If non-`nil', this variable holds a keymap to use instead of the
     buffer's local keymap and instead of all the minor mode keymaps,
     but for the selected console only. (In other words, this variable
     is always console-local; putting a keymap here only applies to
     keystrokes coming from the selected console.  *Note Consoles and
     Devices::.) This keymap, if any, overrides all other maps that
     would have been active, except for the current global map.

\1f
File: lispref.info,  Node: Key Lookup,  Next: Functions for Key Lookup,  Prev: Active Keymaps,  Up: Keymaps

26.8 Key Lookup
===============

"Key lookup" is the process of finding the binding of a key sequence
from a given keymap.  Actual execution of the binding is not part of
key lookup.

   Key lookup uses just the event type of each event in the key
sequence; the rest of the event is ignored.  In fact, a key sequence
used for key lookup may designate mouse events with just their types
(symbols) instead of with entire mouse events (lists).  *Note Events::.
Such a pseudo-key-sequence is insufficient for `command-execute', but
it is sufficient for looking up or rebinding a key.

   When the key sequence consists of multiple events, key lookup
processes the events sequentially: the binding of the first event is
found, and must be a keymap; then the second event's binding is found in
that keymap, and so on until all the events in the key sequence are used
up.  (The binding thus found for the last event may or may not be a
keymap.)  Thus, the process of key lookup is defined in terms of a
simpler process for looking up a single event in a keymap.  How that is
done depends on the type of object associated with the event in that
keymap.

   Let's use the term "keymap entry" to describe the value found by
looking up an event type in a keymap.  (This doesn't include the item
string and other extra elements in menu key bindings because
`lookup-key' and other key lookup functions don't include them in the
returned value.)  While any Lisp object may be stored in a keymap as a
keymap entry, not all make sense for key lookup.  Here is a list of the
meaningful kinds of keymap entries:

`nil'
     `nil' means that the events used so far in the lookup form an
     undefined key.  When a keymap fails to mention an event type at
     all, and has no default binding, that is equivalent to a binding
     of `nil' for that event type.

KEYMAP
     The events used so far in the lookup form a prefix key.  The next
     event of the key sequence is looked up in KEYMAP.

COMMAND
     The events used so far in the lookup form a complete key, and
     COMMAND is its binding.  *Note What Is a Function::.

ARRAY
     The array (either a string or a vector) is a keyboard macro.  The
     events used so far in the lookup form a complete key, and the
     array is its binding.  See *Note Keyboard Macros::, for more
     information. (Note that you cannot use a shortened form of a key
     sequence here, such as `(control y)'; you must use the full form
     `[(control y)]'.  *Note Key Sequences::.)

LIST
     The meaning of a list depends on the types of the elements of the
     list.

        * If the CAR of LIST is `lambda', then the list is a lambda
          expression.  This is presumed to be a command, and is treated
          as such (see above).

        * If the CAR of LIST is a keymap and the CDR is an event type,
          then this is an "indirect entry":

               (OTHERMAP . OTHERTYPE)

          When key lookup encounters an indirect entry, it looks up
          instead the binding of OTHERTYPE in OTHERMAP and uses that.

          This feature permits you to define one key as an alias for
          another key.  For example, an entry whose CAR is the keymap
          called `esc-map' and whose CDR is 32 (the code for <SPC>)
          means, "Use the global binding of `Meta-<SPC>', whatever that
          may be."

SYMBOL
     The function definition of SYMBOL is used in place of SYMBOL.  If
     that too is a symbol, then this process is repeated, any number of
     times.  Ultimately this should lead to an object that is a keymap,
     a command or a keyboard macro.  A list is allowed if it is a
     keymap or a command, but indirect entries are not understood when
     found via symbols.

     Note that keymaps and keyboard macros (strings and vectors) are not
     valid functions, so a symbol with a keymap, string, or vector as
     its function definition is invalid as a function.  It is, however,
     valid as a key binding.  If the definition is a keyboard macro,
     then the symbol is also valid as an argument to `command-execute'
     (*note Interactive Call::).

     The symbol `undefined' is worth special mention: it means to treat
     the key as undefined.  Strictly speaking, the key is defined, and
     its binding is the command `undefined'; but that command does the
     same thing that is done automatically for an undefined key: it
     rings the bell (by calling `ding') but does not signal an error.

     `undefined' is used in local keymaps to override a global key
     binding and make the key "undefined" locally.  A local binding of
     `nil' would fail to do this because it would not override the
     global binding.

ANYTHING ELSE
     If any other type of object is found, the events used so far in the
     lookup form a complete key, and the object is its binding, but the
     binding is not executable as a command.

   In short, a keymap entry may be a keymap, a command, a keyboard
macro, a symbol that leads to one of them, or an indirection or `nil'.

\1f
File: lispref.info,  Node: Functions for Key Lookup,  Next: Changing Key Bindings,  Prev: Key Lookup,  Up: Keymaps

26.9 Functions for Key Lookup
=============================

Here are the functions and variables pertaining to key lookup.

 -- Function: lookup-key keymap key &optional accept-defaults
     This function returns the definition of KEY in KEYMAP.  If the
     string or vector KEY is not a valid key sequence according to the
     prefix keys specified in KEYMAP (which means it is "too long" and
     has extra events at the end), then the value is a number, the
     number of events at the front of KEY that compose a complete key.

     If ACCEPT-DEFAULTS is non-`nil', then `lookup-key' considers
     default bindings as well as bindings for the specific events in
     KEY.  Otherwise, `lookup-key' reports only bindings for the
     specific sequence KEY, ignoring default bindings except when you
     explicitly ask about them.

     All the other functions described in this chapter that look up
     keys use `lookup-key'.

          (lookup-key (current-global-map) "\C-x\C-f")
              => find-file
          (lookup-key (current-global-map) "\C-x\C-f12345")
              => 2

     If KEY begins with the character whose value is contained in
     `meta-prefix-char', that character is implicitly removed and the
     <META> modifier added to the key.  Thus, the first example below is
     handled by conversion into the second example.

          (lookup-key (current-global-map) "\ef")
              => forward-word
          (lookup-key (current-global-map) "\M-f")
              => forward-word

     Unlike `read-key-sequence', this function does not modify the
     specified events in ways that discard information (*note Key
     Sequence Input::).  In particular, it does not convert letters to
     lower case.

 -- Command: undefined
     Used in keymaps to undefine keys.  If a key sequence is defined to
     this, invoking this key sequence causes a "key undefined" error,
     just as if the key sequence had no binding.

 -- Function: key-binding key &optional accept-defaults
     This function returns the binding for KEY in the current keymaps,
     trying all the active keymaps.  The result is `nil' if KEY is
     undefined in the keymaps.

     The argument ACCEPT-DEFAULTS controls checking for default
     bindings, as in `lookup-key' (above).

          (key-binding "\C-x\C-f")
              => find-file
          (key-binding '(control home))
              => beginning-of-buffer
          (key-binding [escape escape escape])
              => keyboard-escape-quit

 -- Function: local-key-binding keys &optional accept-defaults
     This function returns the binding for KEYS in the current local
     keymap, or `nil' if it is undefined there.

     The argument ACCEPT-DEFAULTS controls checking for default
     bindings, as in `lookup-key' (above).

 -- Function: global-key-binding keys &optional accept-defaults
     This function returns the binding for command KEYS in the current
     global keymap, or `nil' if it is undefined there.

     The argument ACCEPT-DEFAULTS controls checking for default
     bindings, as in `lookup-key' (above).

 -- Function: minor-mode-key-binding key &optional accept-defaults
     This function returns a list of all the active minor mode bindings
     of KEY.  More precisely, it returns an alist of pairs `(MODENAME .
     BINDING)', where MODENAME is the variable that enables the minor
     mode, and BINDING is KEY's binding in that mode.  If KEY has no
     minor-mode bindings, the value is `nil'.

     If the first binding is not a prefix command, all subsequent
     bindings from other minor modes are omitted, since they would be
     completely shadowed.  Similarly, the list omits non-prefix
     bindings that follow prefix bindings.

     The argument ACCEPT-DEFAULTS controls checking for default
     bindings, as in `lookup-key' (above).

 -- Variable: meta-prefix-char
     This variable is the meta-prefix character code.  It is used when
     translating a two-character sequence to a meta character so it can
     be looked up in a keymap.  For useful results, the value should be
     a prefix event (*note Prefix Keys::).  The default value is `?\^['
     (integer 27), which is the ASCII character usually produced by the
     <ESC> key.

     As long as the value of `meta-prefix-char' remains `?\^[', key
     lookup translates `<ESC> b' into `M-b', which is normally defined
     as the `backward-word' command.  However, if you set
     `meta-prefix-char' to `?\^X' (i.e. the keystroke `C-x') or its
     equivalent ASCII code `24', then XEmacs will translate `C-x b'
     (whose standard binding is the `switch-to-buffer' command) into
     `M-b'.

          meta-prefix-char                    ; The default value.
               => ?\^[   ; Under XEmacs 20.
               => 27     ; Under XEmacs 19.
          (key-binding "\eb")
               => backward-word
          ?\C-x                               ; The print representation
                                                     ;   of a character.
               => ?\^X   ; Under XEmacs 20.
               => 24     ; Under XEmacs 19.
          (setq meta-prefix-char 24)
               => 24
          (key-binding "\C-xb")
               => backward-word            ; Now, typing `C-x b' is
                                              ;   like typing `M-b'.

          (setq meta-prefix-char ?\e)          ; Avoid confusion!
                                               ; Restore the default value!
               => ?\^[   ; Under XEmacs 20.
               => 27     ; Under XEmacs 19.

\1f
File: lispref.info,  Node: Changing Key Bindings,  Next: Key Binding Commands,  Prev: Functions for Key Lookup,  Up: Keymaps

26.10 Changing Key Bindings
===========================

The way to rebind a key is to change its entry in a keymap.  If you
change a binding in the global keymap, the change is effective in all
buffers (though it has no direct effect in buffers that shadow the
global binding with a local one).  If you change the current buffer's
local map, that usually affects all buffers using the same major mode.
The `global-set-key' and `local-set-key' functions are convenient
interfaces for these operations (*note Key Binding Commands::).  You
can also use `define-key', a more general function; then you must
specify explicitly the map to change.

   The way to specify the key sequence that you want to rebind is
described above (*note Key Sequences::).

   For the functions below, an error is signaled if KEYMAP is not a
keymap or if KEY is not a string or vector representing a key sequence.
You can use event types (symbols) as shorthand for events that are
lists.

 -- Function: define-key keymap key binding
     This function sets the binding for KEY in KEYMAP.  (If KEY is more
     than one event long, the change is actually made in another keymap
     reached from KEYMAP.)  The argument BINDING can be any Lisp
     object, but only certain types are meaningful.  (For a list of
     meaningful types, see *Note Key Lookup::.)  The value returned by
     `define-key' is BINDING.

     Every prefix of KEY must be a prefix key (i.e., bound to a keymap)
     or undefined; otherwise an error is signaled.

     If some prefix of KEY is undefined, then `define-key' defines it
     as a prefix key so that the rest of KEY may be defined as
     specified.

   Here is an example that creates a sparse keymap and makes a number of
bindings in it:

     (setq map (make-sparse-keymap))
         => #<keymap 0 entries 0xbee>
     (define-key map "\C-f" 'forward-char)
         => forward-char
     map
         => #<keymap 1 entry 0xbee>
     (describe-bindings-internal map)
     =>   ; (Inserted in buffer)
     C-f             forward-char

     ;; Build sparse submap for `C-x' and bind `f' in that.
     (define-key map "\C-xf" 'forward-word)
         => forward-word
     map
         => #<keymap 2 entries 0xbee>
     (describe-bindings-internal map)
     =>   ; (Inserted in buffer)
     C-f             forward-char
     C-x             << Prefix Command >>

     C-x f           forward-word

     ;; Bind `C-p' to the `ctl-x-map'.
     (define-key map "\C-p" ctl-x-map)
     ;; `ctl-x-map'
     => #<keymap Control-X-prefix 77 entries 0x3bf>

     ;; Bind `C-f' to `foo' in the `ctl-x-map'.
     (define-key map "\C-p\C-f" 'foo)
     => foo
     map
         => #<keymap 3 entries 0xbee>
     (describe-bindings-internal map)
     =>   ; (Inserted in buffer)
     C-f             forward-char
     C-p             << Prefix command Control-X-prefix >>
     C-x             << Prefix Command >>

     C-p tab         indent-rigidly
     C-p $           set-selective-display
     C-p '           expand-abbrev
     C-p (           start-kbd-macro
     C-p )           end-kbd-macro
        ...
     C-p C-x         exchange-point-and-mark
     C-p C-z         suspend-or-iconify-emacs
     C-p M-escape    repeat-complex-command
     C-p M-C-[       repeat-complex-command

     C-x f           forward-word

     C-p 4 .         find-tag-other-window
        ...
     C-p 4 C-o       display-buffer

     C-p 5 0         delete-frame
        ...
     C-p 5 C-f       find-file-other-frame

        ...

     C-p a i g       inverse-add-global-abbrev
     C-p a i l       inverse-add-mode-abbrev

Note that storing a new binding for `C-p C-f' actually works by
changing an entry in `ctl-x-map', and this has the effect of changing
the bindings of both `C-p C-f' and `C-x C-f' in the default global map.

 -- Function: substitute-key-definition olddef newdef keymap &optional
          oldmap prefix
     This function replaces OLDDEF with NEWDEF for any keys in KEYMAP
     that were bound to OLDDEF.  In other words, OLDDEF is replaced
     with NEWDEF wherever it appears.  Prefix keymaps are checked
     recursively.

     The function returns `nil'.

     For example, this redefines `C-x C-f', if you do it in an XEmacs
     with standard bindings:

          (substitute-key-definition
           'find-file 'find-file-read-only (current-global-map))

     If OLDMAP is non-`nil', then its bindings determine which keys to
     rebind.  The rebindings still happen in KEYMAP, not in OLDMAP.
     Thus, you can change one map under the control of the bindings in
     another.  For example,

          (substitute-key-definition
            'delete-backward-char 'my-funny-delete
            my-map global-map)

     puts the special deletion command in `my-map' for whichever keys
     are globally bound to the standard deletion command.

     If argument PREFIX is non-`nil', then only those occurrences of
     OLDDEF found in keymaps accessible through the keymap bound to
     PREFIX in KEYMAP are redefined.  See also `accessible-keymaps'.


 -- Function: suppress-keymap keymap &optional nodigits
     This function changes the contents of the full keymap KEYMAP by
     making all the printing characters undefined.  More precisely, it
     binds them to the command `undefined'.  This makes ordinary
     insertion of text impossible.  `suppress-keymap' returns `nil'.

     If NODIGITS is `nil', then `suppress-keymap' defines digits to run
     `digit-argument', and `-' to run `negative-argument'.  Otherwise
     it makes them undefined like the rest of the printing characters.

     The `suppress-keymap' function does not make it impossible to
     modify a buffer, as it does not suppress commands such as `yank'
     and `quoted-insert'.  To prevent any modification of a buffer, make
     it read-only (*note Read Only Buffers::).

     Since this function modifies KEYMAP, you would normally use it on
     a newly created keymap.  Operating on an existing keymap that is
     used for some other purpose is likely to cause trouble; for
     example, suppressing `global-map' would make it impossible to use
     most of XEmacs.

     Most often, `suppress-keymap' is used to initialize local keymaps
     of modes such as Rmail and Dired where insertion of text is not
     desirable and the buffer is read-only.  Here is an example taken
     from the file `emacs/lisp/dired.el', showing how the local keymap
     for Dired mode is set up:

            ...
            (setq dired-mode-map (make-keymap))
            (suppress-keymap dired-mode-map)
            (define-key dired-mode-map "r" 'dired-rename-file)
            (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
            (define-key dired-mode-map "d" 'dired-flag-file-deleted)
            (define-key dired-mode-map "v" 'dired-view-file)
            (define-key dired-mode-map "e" 'dired-find-file)
            (define-key dired-mode-map "f" 'dired-find-file)
            ...

\1f
File: lispref.info,  Node: Key Binding Commands,  Next: Scanning Keymaps,  Prev: Changing Key Bindings,  Up: Keymaps

26.11 Commands for Binding Keys
===============================

This section describes some convenient interactive interfaces for
changing key bindings.  They work by calling `define-key'.

   People often use `global-set-key' in their `.emacs' file for simple
customization.  For example,

     (global-set-key "\C-x\C-\\" 'next-line)

or

     (global-set-key [(control ?x) (control ?\\)] 'next-line)

or

     (global-set-key [?\C-x ?\C-\\] 'next-line)

redefines `C-x C-\' to move down a line.

     (global-set-key [(meta button1)] 'mouse-set-point)

redefines the first (leftmost) mouse button, typed with the Meta key, to
set point where you click.

 -- Command: global-set-key key definition
     This function sets the binding of KEY in the current global map to
     DEFINITION.

          (global-set-key KEY DEFINITION)
          ==
          (define-key (current-global-map) KEY DEFINITION)

 -- Command: global-unset-key key
     This function removes the binding of KEY from the current global
     map.

     One use of this function is in preparation for defining a longer
     key that uses KEY as a prefix--which would not be allowed if KEY
     has a non-prefix binding.  For example:

          (global-unset-key "\C-l")
              => nil
          (global-set-key "\C-l\C-l" 'redraw-display)
              => nil

     This function is implemented simply using `define-key':

          (global-unset-key KEY)
          ==
          (define-key (current-global-map) KEY nil)

 -- Command: local-set-key key definition
     This function sets the binding of KEY in the current local keymap
     to DEFINITION.

          (local-set-key KEY DEFINITION)
          ==
          (define-key (current-local-map) KEY DEFINITION)

 -- Command: local-unset-key key
     This function removes the binding of KEY from the current local
     map.

          (local-unset-key KEY)
          ==
          (define-key (current-local-map) KEY nil)

\1f
File: lispref.info,  Node: Scanning Keymaps,  Next: Other Keymap Functions,  Prev: Key Binding Commands,  Up: Keymaps

26.12 Scanning Keymaps
======================

This section describes functions used to scan all the current keymaps,
or all keys within a keymap, for the sake of printing help information.

 -- Function: accessible-keymaps keymap &optional prefix
     This function returns a list of all the keymaps that can be
     accessed (via prefix keys) from KEYMAP.  The value is an
     association list with elements of the form `(KEY . MAP)', where
     KEY is a prefix key whose definition in KEYMAP is MAP.

     The elements of the alist are ordered so that the KEY increases in
     length.  The first element is always `([] . KEYMAP)', because the
     specified keymap is accessible from itself with a prefix of no
     events.

     If PREFIX is given, it should be a prefix key sequence; then
     `accessible-keymaps' includes only the submaps whose prefixes start
     with PREFIX.  These elements look just as they do in the value of
     `(accessible-keymaps)'; the only difference is that some elements
     are omitted.

     In the example below, the returned alist indicates that the key
     `C-x', which is displayed as `[(control x)]', is a prefix key
     whose definition is the keymap `#<keymap ((control x) #<keymap
     emacs-lisp-mode-map 8 entries 0x546>) 1 entry 0x8a2>'. (The strange
     notation for the keymap's name indicates that this is an internal
     submap of `emacs-lisp-mode-map'.  This is because
     `lisp-interaction-mode-map' has set up `emacs-lisp-mode-map' as
     its parent, and `lisp-interaction-mode-map' defines no key
     sequences beginning with `C-x'.)

          (current-local-map)
          => #<keymap lisp-interaction-mode-map 5 entries 0x558>
          (accessible-keymaps (current-local-map))
          =>(([] . #<keymap lisp-interaction-mode-map 5 entries 0x558>)
              ([(control x)] .
               #<keymap ((control x) #<keymap emacs-lisp-mode-map 8 entries 0x546>)
                        1 entry 0x8a2>))

     The following example shows the results of calling
     `accessible-keymaps' on a large, complex keymap.  Notice how some
     keymaps were given explicit names using `set-keymap-name'; those
     submaps without explicit names are given descriptive names
     indicating their relationship to their enclosing keymap.

          (accessible-keymaps (current-global-map))
          => (([] . #<keymap global-map 639 entries 0x221>)
             ([(control c)] . #<keymap mode-specific-command-prefix 1 entry 0x3cb>)
             ([(control h)] . #<keymap help-map 33 entries 0x4ec>)
             ([(control x)] . #<keymap Control-X-prefix 77 entries 0x3bf>)
             ([(meta escape)] .
                #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
                         3 entries 0x3e0>)
             ([(meta control \[)] .
                #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
                         3 entries 0x3e0>)
             ([f1] . #<keymap help-map 33 entries 0x4ec>)
             ([(control x) \4] . #<keymap ctl-x-4-prefix 9 entries 0x3c5>)
             ([(control x) \5] . #<keymap ctl-x-5-prefix 8 entries 0x3c8>)
             ([(control x) \6] . #<keymap 13 entries 0x4d2>)
             ([(control x) a] .
                #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
                         8 entries 0x3ef>)
             ([(control x) n] . #<keymap narrowing-prefix 3 entries 0x3dd>)
             ([(control x) r] . #<keymap rectangle-prefix 18 entries 0x3e9>)
             ([(control x) v] . #<keymap vc-prefix-map 13 entries 0x60e>)
             ([(control x) a i] .
               #<keymap (i #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
                                    8 entries 0x3ef>)
                        2 entries 0x3f5>))

 -- Function: map-keymap function keymap &optional sort-first
     This function applies FUNCTION to each element of KEYMAP.
     FUNCTION will be called with two arguments: a key-description
     list, and the binding.  The order in which the elements of the
     keymap are passed to the function is unspecified.  If the function
     inserts new elements into the keymap, it may or may not be called
     with them later.  No element of the keymap will ever be passed to
     the function more than once.

     The function will not be called on elements of this keymap's
     parents (*note Inheritance and Keymaps::) or upon keymaps which
     are contained within this keymap (multi-character definitions).
     It will be called on <META> characters since they are not really
     two-character sequences.

     If the optional third argument SORT-FIRST is non-`nil', then the
     elements of the keymap will be passed to the mapper function in a
     canonical order.  Otherwise, they will be passed in hash (that is,
     random) order, which is faster.

 -- Function: keymap-fullness keymap
     This function returns the number of bindings in the keymap.

 -- Function: where-is-internal definition &optional keymaps firstonly
          noindirect event-or-keys
     This function returns a list of key sequences (of any length) that
     are bound to DEFINITION in a set of keymaps.

     The argument DEFINITION can be any object; it is compared with all
     keymap entries using `eq'.

     KEYMAPS can be either a keymap (meaning search in that keymap and
     the current global keymap) or a list of keymaps (meaning search in
     exactly those keymaps and no others).  If KEYMAPS is nil, search
     in the currently applicable maps for EVENT-OR-KEYS.

     If KEYMAPS is a keymap, then the maps searched are KEYMAPS and the
     global keymap.  If KEYMAPS is a list of keymaps, then the maps
     searched are exactly those keymaps, and no others.  If KEYMAPS is
     `nil', then the maps used are the current active keymaps for
     EVENT-OR-KEYS (this is equivalent to specifying `(current-keymaps
     EVENT-OR-KEYS)' as the argument to KEYMAPS).

     If FIRSTONLY is non-`nil', then the value is a single vector
     representing the first key sequence found, rather than a list of
     all possible key sequences.

     If NOINDIRECT is non-`nil', `where-is-internal' doesn't follow
     indirect keymap bindings.  This makes it possible to search for an
     indirect definition itself.

     This function is used by `where-is' (*note Help: (xemacs)Help.).

          (where-is-internal 'describe-function)
              => ([(control h) d] [(control h) f] [f1 d] [f1 f])

 -- Function: describe-bindings-internal map &optional all shadow
          prefix mouse-only-p
     This function inserts (into the current buffer) a list of all
     defined keys and their definitions in MAP.  Optional second
     argument ALL says whether to include even "uninteresting"
     definitions, i.e.  symbols with a non-`nil' `suppress-keymap'
     property.  Third argument SHADOW is a list of keymaps whose
     bindings shadow those of map; if a binding is present in any
     shadowing map, it is not printed.  Fourth argument PREFIX, if
     non-`nil', should be a key sequence; only bindings which start
     with that key sequence will be printed.  Fifth argument
     MOUSE-ONLY-P says to only print bindings for mouse clicks.

   `describe-bindings-internal' is used to implement the help command
`describe-bindings'.

 -- Command: describe-bindings &optional prefix mouse-only-p
     This function creates a listing of all defined keys and their
     definitions.  It writes the listing in a buffer named `*Help*' and
     displays it in a window.

     If optional argument PREFIX is non-`nil', it should be a prefix
     key; then the listing includes only keys that start with PREFIX.

     When several characters with consecutive ASCII codes have the same
     definition, they are shown together, as `FIRSTCHAR..LASTCHAR'.  In
     this instance, you need to know the ASCII codes to understand
     which characters this means.  For example, in the default global
     map, the characters `<SPC> .. ~' are described by a single line.
     <SPC> is ASCII 32, `~' is ASCII 126, and the characters between
     them include all the normal printing characters, (e.g., letters,
     digits, punctuation, etc.); all these characters are bound to
     `self-insert-command'.

     If the second optional argument MOUSE-ONLY-P (prefix arg,
     interactively) is non-`nil' then only the mouse bindings are
     displayed.

\1f
File: lispref.info,  Node: Other Keymap Functions,  Prev: Scanning Keymaps,  Up: Keymaps

26.13 Other Keymap Functions
============================

 -- Function: set-keymap-prompt keymap new-prompt
     This function sets the "prompt" of KEYMAP to string NEW-PROMPT, or
     `nil' if no prompt is desired.  The prompt is shown in the
     echo-area when reading a key-sequence to be looked-up in this
     keymap.

 -- Function: keymap-prompt keymap &optional use-inherited
     This function returns the "prompt" of the given keymap.  If
     USE-INHERITED is non-`nil', any parent keymaps will also be
     searched for a prompt.

\1f
File: lispref.info,  Node: Menus,  Next: Dialog Boxes,  Prev: Keymaps,  Up: Top

27 Menus
********

* Menu:

* Menu Format::         Format of a menu description.
* Menubar Format::      How to specify a menubar.
* Menubar::             Functions for controlling the menubar.
* Modifying Menus::     Modifying a menu description.
* Pop-Up Menus::        Functions for specifying pop-up menus.
* Menu Filters::        Filter functions for the default menubar.
* Menu Accelerators::   Using and controlling menu accelerator keys
* Buffers Menu::        The menu that displays the list of buffers.

\1f
File: lispref.info,  Node: Menu Format,  Next: Menubar Format,  Up: Menus

27.1 Format of Menus
====================

A menu is described using a "menu description", which is a list of menu
items, keyword-value pairs, strings, and submenus.  The menu
description specifies which items are present in the menu, what function
each item invokes, and whether the item is selectable or not.  Pop-up
menus are directly described with a menu description, while menubars are
described slightly differently (see below).

   The first element of a menu must be a string, which is the name of
the menu.  This is the string that will be displayed in the parent menu
or menubar, if any.  This string is not displayed in the menu itself,
except in the case of the top level pop-up menu, where there is no
parent.  In this case, the string will be displayed at the top of the
menu if `popup-menu-titles' is non-`nil'.

   Immediately following the first element there may optionally be up
to four keyword-value pairs, as follows:

`:included FORM'
     This can be used to control the visibility of a menu.  The form is
     evaluated and the menu will be omitted if the result is `nil'.

`:config SYMBOL'
     This is an efficient shorthand for `:included (memq SYMBOL
     menubar-configuration)'.  See the variable `menubar-configuration'.

`:filter FUNCTION'
     A menu filter is used to sensitize or incrementally create a
     submenu only when it is selected by the user and not every time
     the menubar is activated.  The filter function is passed the list
     of menu items in the submenu and must return a list of menu items
     to be used for the menu.  It is called only when the menu is about
     to be displayed, so other menus may already be displayed.  Vile
     and terrible things will happen if a menu filter function changes
     the current buffer, window, or frame.  It also should not raise,
     lower, or iconify any frames.  Basically, the filter function
     should have no side-effects.

`:accelerator KEY'
     A menu accelerator is a keystroke which can be pressed while the
     menu is visible which will immediately activate the item.  KEY
     must be a char or the symbol name of a key.  *Note Menu
     Accelerators::.

   The rest of the menu consists of elements as follows:

   * A "menu item", which is a vector in the following form:

          `[ NAME CALLBACK :KEYWORD VALUE :KEYWORD VALUE ... ]'

     NAME is a string, the name of the menu item; it is the string to
     display on the menu.  It is filtered through the resource
     database, so it is possible for resources to override what string
     is actually displayed.

     CALLBACK is a form that will be invoked when the menu item is
     selected.  If the callback of a menu item is a symbol, then it
     must name a command.  It will be invoked with
     `call-interactively'.  If it is a list, then it is evaluated with
     `eval'.

     The valid keywords and their meanings are described below.

     Note that for compatibility purposes, the form

          `[ NAME CALLBACK ACTIVE-P ]'

     is also accepted and is equivalent to

          `[ NAME CALLBACK :active ACTIVE-P ]'

     and the form

          `[ NAME CALLBACK ACTIVE-P SUFFIX]'

     is accepted and is equivalent to

          `[ NAME CALLBACK :active ACTIVE-P :suffix SUFFIX]'

     However, these older forms are deprecated and should generally not
     be used.

   * If an element of a menu is a string, then that string will be
     presented in the menu as unselectable text.

   * If an element of a menu is a string consisting solely of hyphens,
     then that item will be presented as a solid horizontal line.

   * If an element of a menu is a string beginning with `--:', then a
     particular sort of horizontal line will be displayed, as follows:

    `"--:singleLine"'
          A solid horizontal line.  This is equivalent to a string
          consisting solely of hyphens.

    `"--:doubleLine"'
          A solid double horizontal line.

    `"--:singleDashedLine"'
          A dashed horizontal line.

    `"--:doubleDashedLine"'
          A dashed double horizontal line.

    `"--:noLine"'
          No line (but a small space is left).

    `"--:shadowEtchedIn"'
          A solid horizontal line with a 3-d recessed appearance.

    `"--:shadowEtchedOut"'
          A solid horizontal line with a 3-d pushed-out appearance.

    `"--:shadowDoubleEtchedIn"'
          A solid double horizontal line with a 3-d recessed appearance.

    `"--:shadowDoubleEtchedOut"'
          A solid double horizontal line with a 3-d pushed-out
          appearance.

    `"--:shadowEtchedInDash"'
          A dashed horizontal line with a 3-d recessed appearance.

    `"--:shadowEtchedOutDash"'
          A dashed horizontal line with a 3-d pushed-out appearance.

    `"--:shadowDoubleEtchedInDash"'
          A dashed double horizontal line with a 3-d recessed
          appearance.

    `"--:shadowDoubleEtchedOutDash"'
          A dashed double horizontal line with a 3-d pushed-out
          appearance.

   * If an element of a menu is a list, it is treated as a submenu.
     The name of that submenu (the first element in the list) will be
     used as the name of the item representing this menu on the parent.

   The possible keywords are as follows:

:active FORM
     FORM will be evaluated when the menu that this item is a part of
     is about to be displayed, and the item will be selectable only if
     the result is non-`nil'.  If the item is unselectable, it will
     usually be displayed grayed-out to indicate this.

:suffix FORM
     FORM will be evaluated when the menu that this item is a part of
     is about to be displayed, and the resulting string is appended to
     the displayed name.  This provides a convenient way of adding the
     name of a command's "argument" to the menu, like `Kill Buffer
     NAME'.

:keys STRING
     Normally, the keyboard equivalents of commands in menus are
     displayed when the "callback" is a symbol.  This can be used to
     specify keys for more complex menu items.  It is passed through
     `substitute-command-keys' first.

:style STYLE
     Specifies what kind of object this menu item is.  STYLE be one of
     the symbols

    `nil'
          A normal menu item.

    `toggle'
          A toggle button.

    `radio'
          A radio button.

    `button'
          A menubar button.

     The only difference between toggle and radio buttons is how they
     are displayed.  But for consistency, a toggle button should be
     used when there is one option whose value can be turned on or off,
     and radio buttons should be used when there is a set of mutually
     exclusive options.  When using a group of radio buttons, you
     should arrange for no more than one to be marked as selected at a
     time.

:selected FORM
     Meaningful only when STYLE is `toggle', `radio' or `button'.  This
     specifies whether the button will be in the selected or unselected
     state.  FORM is evaluated, as for `:active'.

:included FORM
     This can be used to control the visibility of a menu item.  The
     form is evaluated and the menu item is only displayed if the
     result is non-`nil'.  Note that this is different from `:active':
     If `:active' evaluates to `nil', the item will be displayed grayed
     out, while if `:included' evaluates to `nil', the item will be
     omitted entirely.

:config SYMBOL
     This is an efficient shorthand for `:included (memq SYMBOL
     menubar-configuration)'.  See the variable `menubar-configuration'.

:accelerator KEY
     A menu accelerator is a keystroke which can be pressed while the
     menu is visible which will immediately activate the item.  KEY
     must be a char or the symbol name of a key.  *Note Menu
     Accelerators::.

 -- Variable: menubar-configuration
     This variable holds a list of symbols, against which the value of
     the `:config' tag for each menubar item will be compared.  If a
     menubar item has a `:config' tag, then it is omitted from the
     menubar if that tag is not a member of the `menubar-configuration'
     list.

   For example:

      ("File"
       :filter file-menu-filter      ; file-menu-filter is a function that takes
                                     ; one argument (a list of menu items) and
                                     ; returns a list of menu items
       [ "Save As..."    write-file]
       [ "Revert Buffer" revert-buffer :active (buffer-modified-p) ]
       [ "Read Only"     toggle-read-only :style toggle :selected buffer-read-only ]
       )

\1f
File: lispref.info,  Node: Menubar Format,  Next: Menubar,  Prev: Menu Format,  Up: Menus

27.2 Format of the Menubar
==========================

A menubar is a list of menus, menu items, and strings.  The format is
similar to that of a menu, except:

   * The first item need not be a string, and is not treated specially.

   * A string consisting solely of hyphens is not treated specially.

   * If an element of a menubar is `nil', then it is used to represent
     the division between the set of menubar items which are flush-left
     and those which are flush-right.  (Note: this isn't completely
     implemented yet.)

\1f
File: lispref.info,  Node: Menubar,  Next: Modifying Menus,  Prev: Menubar Format,  Up: Menus

27.3 Menubar
============

 -- Variable: current-menubar
     This variable holds the description of the current menubar.  This
     may be buffer-local.  When the menubar is changed, the function
     `set-menubar-dirty-flag' has to be called in order for the menubar
     to be updated on the screen.

 -- Constant: default-menubar
     This variable holds the menubar description of the menubar that is
     visible at startup.  This is the value that `current-menubar' has
     at startup.

 -- Function: set-menubar-dirty-flag
     This function tells XEmacs that the menubar widget has to be
     updated.  Changes to the menubar will generally not be visible
     until this function is called.

   The following convenience functions are provided for setting the
menubar.  They are equivalent to doing the appropriate action to change
`current-menubar', and then calling `set-menubar-dirty-flag'.  Note
that these functions copy their argument using `copy-sequence'.

 -- Function: set-menubar menubar
     This function sets the default menubar to be MENUBAR (*note Menu
     Format::).  This is the menubar that will be visible in buffers
     that have not defined their own, buffer-local menubar.

 -- Function: set-buffer-menubar menubar
     This function sets the buffer-local menubar to be MENUBAR.  This
     does not change the menubar in any buffers other than the current
     one.

   Miscellaneous:

 -- Variable: menubar-show-keybindings
     If true, the menubar will display keyboard equivalents.  If false,
     only the command names will be displayed.

 -- Variable: activate-menubar-hook
     Function or functions called before a menubar menu is pulled down.
     These functions are called with no arguments, and should
     interrogate and modify the value of `current-menubar' as desired.

     The functions on this hook are invoked after the mouse goes down,
     but before the menu is mapped, and may be used to activate,
     deactivate, add, or delete items from the menus.  However, using a
     filter (with the `:filter' keyword in a menu description) is
     generally a more efficient way of accomplishing the same thing,
     because the filter is invoked only when the actual menu goes down.
     With a complex menu, there can be a quite noticeable and
     sometimes aggravating delay if all menu modification is
     implemented using the `activate-menubar-hook'.  See above.

     These functions may return the symbol `t' to assert that they have
     made no changes to the menubar.  If any other value is returned,
     the menubar is recomputed.  If `t' is returned but the menubar has
     been changed, then the changes may not show up right away.
     Returning `nil' when the menubar has not changed is not so bad;
     more computation will be done, but redisplay of the menubar will
     still be performed optimally.

 -- Variable: menu-no-selection-hook
     Function or functions to call when a menu or dialog box is
     dismissed without a selection having been made.

\1f
File: lispref.info,  Node: Modifying Menus,  Next: Pop-Up Menus,  Prev: Menubar,  Up: Menus

27.4 Modifying Menus
====================

The following functions are provided to modify the menubar of one of its
submenus.  Note that these functions modify the menu in-place, rather
than copying it and making a new menu.

   Some of these functions take a "menu path", which is a list of
strings identifying the menu to be modified.  For example, `("File")'
names the top-level "File" menu.  `("File" "Foo")' names a hypothetical
submenu of "File".

   Others take a "menu item path", which is similar to a menu path but
also specifies a particular item to be modified.  For example, `("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".

 -- Function: add-submenu menu-path submenu &optional before in-menu
     This function adds a menu to the menubar or one of its submenus.
     If the named menu exists already, it is changed.

     MENU-PATH identifies the menu under which the new menu should be
     inserted.  If MENU-PATH is `nil', then the menu will be added to
     the menubar itself.

     SUBMENU is the new menu to add (*note Menu Format::).

     BEFORE, if provided, is the name of a menu before which this menu
     should be added, if this menu is not on its parent already.  If
     the menu is already present, it will not be moved.

     If IN-MENU is present use that instead of `current-menubar' as the
     menu to change.

 -- Function: add-menu-button menu-path menu-leaf &optional before
          in-menu
     This function adds a menu item to some menu, creating the menu
     first if necessary.  If the named item exists already, it is
     changed.

     MENU-PATH identifies the menu under which the new menu item should
     be inserted.

     MENU-LEAF is a menubar leaf node (*note Menu Format::).

     BEFORE, if provided, is the name of a menu before which this item
     should be added, if this item is not on the menu already.  If the
     item is already present, it will not be moved.

     If IN-MENU is present use that instead of `current-menubar' as the
     menu to change.

 -- Function: delete-menu-item menu-item-path &optional from-menu
     This function removes the menu item specified by MENU-ITEM-PATH
     from the menu hierarchy.

     If FROM-MENU is present use that instead of `current-menubar' as
     the menu to change.

 -- Function: enable-menu-item menu-item-path
     This function makes the menu item specified by MENU-ITEM-PATH be
     selectable.

 -- Function: disable-menu-item menu-item-path
     This function makes the menu item specified by MENU-ITEM-PATH be
     unselectable.

 -- Function: relabel-menu-item menu-item-path new-name
     This function changes the string of the menu item specified by
     MENU-ITEM-PATH.  NEW-NAME is the string that the menu item will be
     printed as from now on.

   The following function can be used to search for a particular item in
a menubar specification, given a path to the item.

 -- Function: find-menu-item menubar menu-item-path &optional parent
     This function searches MENUBAR for the item given by
     MENU-ITEM-PATH starting from PARENT (`nil' means start at the top
     of MENUBAR).  This function returns `(ITEM . PARENT)', where
     PARENT is the immediate parent of the item found (a menu
     description), and ITEM is either a vector, list, or string,
     depending on the nature of the menu item.

     This function signals an error if the item is not found.

   The following deprecated functions are also documented, so that
existing code can be understood.  You should not use these functions in
new code.

 -- Function: add-menu menu-path menu-name menu-items &optional before
     This function adds a menu to the menubar or one of its submenus.
     If the named menu exists already, it is changed.  This is
     obsolete; use `add-submenu' instead.

     MENU-PATH identifies the menu under which the new menu should be
     inserted.  If MENU-PATH is `nil', then the menu will be added to
     the menubar itself.

     MENU-NAME is the string naming the menu to be added; MENU-ITEMS is
     a list of menu items, strings, and submenus.  These two arguments
     are the same as the first and following elements of a menu
     description (*note Menu Format::).

     BEFORE, if provided, is the name of a menu before which this menu
     should be added, if this menu is not on its parent already.  If the
     menu is already present, it will not be moved.

 -- Function: add-menu-item menu-path item-name function enabled-p
          &optional before
     This function adds a menu item to some menu, creating the menu
     first if necessary.  If the named item exists already, it is
     changed.  This is obsolete; use `add-menu-button' instead.

     MENU-PATH identifies the menu under which the new menu item should
     be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first,
     second, and third elements of a menu item vector (*note Menu
     Format::).

     BEFORE, if provided, is the name of a menu item before which this
     item should be added, if this item is not on the menu already.  If
     the item is already present, it will not be moved.

\1f
File: lispref.info,  Node: Menu Filters,  Next: Menu Accelerators,  Prev: Pop-Up Menus,  Up: Menus

27.5 Menu Filters
=================

The following filter functions are provided for use in
`default-menubar'.  You may want to use them in your own menubar
description.

 -- Function: file-menu-filter menu-items
     This function changes the arguments and sensitivity of these File
     menu items:

    `Delete Buffer'
          Has the name of the current buffer appended to it.

    `Print Buffer'
          Has the name of the current buffer appended to it.

    `Pretty-Print Buffer'
          Has the name of the current buffer appended to it.

    `Save Buffer'
          Has the name of the current buffer appended to it, and is
          sensitive only when the current buffer is modified.

    `Revert Buffer'
          Has the name of the current buffer appended to it, and is
          sensitive only when the current buffer has a file.

    `Delete Frame'
          Sensitive only when there is more than one visible frame.

 -- Function: edit-menu-filter menu-items
     This function changes the arguments and sensitivity of these Edit
     menu items:

    `Cut'
          Sensitive only when XEmacs owns the primary X Selection (if
          `zmacs-regions' is `t', this is equivalent to saying that
          there is a region selected).

    `Copy'
          Sensitive only when XEmacs owns the primary X Selection.

    `Clear'
          Sensitive only when XEmacs owns the primary X Selection.

    `Paste'
          Sensitive only when there is an owner for the X Clipboard
          Selection.

    `Undo'
          Sensitive only when there is undo information.  While in the
          midst of an undo, this is changed to `Undo More'.

 -- Function: buffers-menu-filter menu-items
     This function sets up the Buffers menu.  *Note Buffers Menu::, for
     more information.

\1f
File: lispref.info,  Node: Pop-Up Menus,  Next: Menu Filters,  Prev: Modifying Menus,  Up: Menus

27.6 Pop-Up Menus
=================

 -- Function: popup-menu menu-description &optional event
     This function pops up a menu specified by MENU-DESCRIPTION, which
     is a menu description (*note Menu Format::).  The menu is
     displayed at the current mouse position.

 -- Function: popup-menu-up-p
     This function returns `t' if a pop-up menu is up, `nil' otherwise.

 -- Variable: popup-menu-titles
     If true (the default), pop-up menus will have title bars at the
     top.

   Some machinery is provided that attempts to provide a higher-level
mechanism onto pop-up menus.  This only works if you do not redefine
the binding for button3.

 -- Command: popup-mode-menu
     This function pops up a menu of global and mode-specific commands.
     The menu is computed by combining `global-popup-menu' and
     `mode-popup-menu'.  This is the default binding for button3.  You
     should generally not change this binding.

 -- Variable: global-popup-menu
     This holds the global popup menu.  This is present in all modes.
     (This is `nil' by default.)

 -- Variable: mode-popup-menu
     The mode-specific popup menu.  Automatically buffer local.  This
     is appended to the default items in `global-popup-menu'.

 -- Constant: default-popup-menu
     This holds the default value of `mode-popup-menu'.

 -- Variable: activate-popup-menu-hook
     Function or functions run before a mode-specific popup menu is made
     visible.  These functions are called with no arguments, and should
     interrogate and modify the value of `global-popup-menu' or
     `mode-popup-menu' as desired.  Note: this hook is only run if you
     use `popup-mode-menu' for activating the global and mode-specific
     commands; if you have your own binding for button3, this hook
     won't be run.

   The following convenience functions are provided for displaying
pop-up menus.

 -- Command: popup-buffer-menu event
     This function pops up a copy of the `Buffers' menu (from the
     menubar) where the mouse is clicked.  It should be bound to a
     mouse button event.

 -- Command: popup-menubar-menu event
     This function pops up a copy of menu that also appears in the
     menubar.  It should be bound to a mouse button event.

\1f
File: lispref.info,  Node: Menu Accelerators,  Next: Buffers Menu,  Prev: Menu Filters,  Up: Menus

27.7 Menu Accelerators
======================

Menu accelerators are keyboard shortcuts for accessing the menubar.
Accelerator keys can be specified for menus as well as for menu items.
An accelerator key for a menu is used to activate that menu when it
appears as a submenu of another menu.  An accelerator key for a menu
item is used to activate that item.

* Menu:

* Creating Menu Accelerators::  How to add accelerator keys to a menu.
* Keyboard Menu Traversal::     How to use and modify the keys which are used
                                to traverse the menu structure.
* Menu Accelerator Functions::  Functions for working with menu accelerators.

\1f
File: lispref.info,  Node: Creating Menu Accelerators,  Next: Keyboard Menu Traversal,  Up: Menu Accelerators

27.7.1 Creating Menu Accelerators
---------------------------------

Menu accelerators are specified as part of the menubar format using the
:accelerator tag to specify a key or by placing "%_" in the menu or
menu item name prior to the letter which is to be used as the
accelerator key.  The advantage of the second method is that the menu
rendering code then knows to draw an underline under that character,
which is the canonical way of indicating an accelerator key to a user.

   For example, the command

     (add-submenu nil '("%_Test"
                        ["One" (insert "1") :accelerator ?1 :active t]
                        ["%_Two" (insert "2")]
                        ["%_3" (insert "3")]))

   will add a new menu to the top level menubar.  The new menu can be
reached by pressing "t" while the top level menubar is active.  When
the menu is active, pressing "1" will activate the first item and
insert the character "1" into the buffer.  Pressing "2" will activate
the second item and insert the character "2" into the buffer.  Pressing
"3" will activate the third item and insert the character "3" into the
buffer.

   It is possible to activate the top level menubar itself using
accelerator keys.  *Note Menu Accelerator Functions::.

\1f
File: lispref.info,  Node: Keyboard Menu Traversal,  Next: Menu Accelerator Functions,  Prev: Creating Menu Accelerators,  Up: Menu Accelerators

27.7.2 Keyboard Menu Traversal
------------------------------

In addition to immediately activating a menu or menu item, the keyboard
can be used to traverse the menus without activating items.  The
keyboard arrow keys, the return key and the escape key are defined to
traverse the menus in a way that should be familiar to users of any of
a certain family of popular PC operating systems.

   This behavior can be changed by modifying the bindings in
menu-accelerator-map.  At this point, the online help is your best bet
for more information about how to modify the menu traversal keys.

\1f
File: lispref.info,  Node: Menu Accelerator Functions,  Prev: Keyboard Menu Traversal,  Up: Menu Accelerators

27.7.3 Menu Accelerator Functions
---------------------------------

 -- Command: accelerate-menu
     Make the menubar immediately active and place the cursor on the
     left most entry in the top level menu.  Menu items can be selected
     as usual.

 -- Variable: menu-accelerator-enabled
     Whether menu accelerator keys can cause the menubar to become
     active.

     If `menu-force' or `menu-fallback', then menu accelerator keys can
     be used to activate the top level menu.  Once the menubar becomes
     active, the accelerator keys can be used regardless of the value
     of this variable.

     `menu-force' is used to indicate that the menu accelerator key
     takes precedence over bindings in the current keymap(s).
     `menu-fallback' means that bindings in the current keymap take
     precedence over menu accelerator keys.  Thus a top level menu with
     an accelerator of "T" would be activated on a keypress of Meta-t
     if `menu-accelerator-enabled' is `menu-force'.  However, if
     `menu-accelerator-enabled' is `menu-fallback', then Meta-t will
     not activate the menubar and will instead run the function
     transpose-words, to which it is normally bound.

     The default value is `nil'.

     See also `menu-accelerator-modifiers' and
     `menu-accelerator-prefix'.

 -- Variable: menu-accelerator-map
     Keymap consulted to determine the commands to run in response to
     keypresses occurring while the menubar is active.  *Note Keyboard
     Menu Traversal::.

 -- Variable: menu-accelerator-modifiers
     A list of modifier keys which must be pressed in addition to a
     valid menu accelerator in order for the top level menu to be
     activated in response to a keystroke.  The default value of
     `(meta)' mirrors the usage of the alt key as a menu accelerator in
     popular PC operating systems.

     The modifier keys in `menu-accelerator-modifiers' must match
     exactly the modifiers present in the keypress.  The only exception
     is that the shift modifier is accepted in conjunction with
     alphabetic keys even if it is not a menu accelerator modifier.

     See also `menu-accelerator-enabled' and `menu-accelerator-prefix'.

 -- Variable: menu-accelerator-prefix
     Prefix key(s) that must be typed before menu accelerators will be
     activated.  Must be a valid key descriptor.

     The default value is `nil'.

     (setq menu-accelerator-prefix ?\C-x)
     (setq menu-accelerator-modifiers '(meta control))
     (setq menu-accelerator-enabled 'menu-force)
     (add-submenu nil '("%_Test"
                        ["One" (insert "1") :accelerator ?1 :active t]
                        ["%_Two" (insert "2")]
                        ["%_3" (insert "3")]))

   will add the menu "Test" to the top level menubar.  Pressing C-x
followed by C-M-T will activate the menubar and display the "Test"
menu.  Pressing C-M-T by itself will not activate the menubar.  Neither
will pressing C-x followed by anything else.

\1f
File: lispref.info,  Node: Buffers Menu,  Prev: Menu Accelerators,  Up: Menus

27.8 Buffers Menu
=================

The following options control how the `Buffers' menu is displayed.
This is a list of all (or a subset of) the buffers currently in
existence, and is updated dynamically.

 -- User Option: buffers-menu-max-size
     This user option holds the maximum number of entries which may
     appear on the `Buffers' menu.  If this is 10, then only the ten
     most-recently-selected buffers will be shown.  If this is `nil',
     then all buffers will be shown.  Setting this to a large number or
     `nil' will slow down menu responsiveness.

 -- Function: format-buffers-menu-line buffer
     This function returns a string to represent BUFFER in the
     `Buffers' menu.  `nil' means the buffer shouldn't be listed.  You
     can redefine this.

 -- User Option: complex-buffers-menu-p
     If true, the `Buffers' menu will contain several commands, as
     submenus of each buffer line.  If this is false, then there will
     be only one command: select that buffer.

 -- User Option: buffers-menu-switch-to-buffer-function
     This user option holds the function to call to select a buffer
     from the `Buffers' menu.  `switch-to-buffer' is a good choice, as
     is `pop-to-buffer'.

\1f
File: lispref.info,  Node: Dialog Boxes,  Next: Toolbar,  Prev: Menus,  Up: Top

28 Dialog Boxes
***************

* Menu:

* Dialog Box Format::
* Dialog Box Functions::

\1f
File: lispref.info,  Node: Dialog Box Format,  Next: Dialog Box Functions,  Up: Dialog Boxes

28.1 Dialog Box Format
======================

A dialog box description is a list.

   * The first element of the list is a string to display in the dialog
     box.

   * The rest of the elements are descriptions of the dialog box's
     buttons.  Each one is a vector of three elements:
        - The first element is the text of the button.

        - The second element is the "callback".

        - The third element is `t' or `nil', whether this button is
          selectable.

   If the callback of a button is a symbol, then it must name a command.
It will be invoked with `call-interactively'.  If it is a list, then it
is evaluated with `eval'.

   One (and only one) of the buttons may be `nil'.  This marker means
that all following buttons should be flushright instead of flushleft.

   The syntax, more precisely:

        form         :=  <something to pass to `eval'>
        command      :=  <a symbol or string, to pass to `call-interactively'>
        callback     :=  command | form
        active-p     :=  <t, nil, or a form to evaluate to decide whether this
                         button should be selectable>
        name         :=  <string>
        partition    :=  'nil'
        button       :=  '['  name callback active-p ']'
        dialog       :=  '(' name [ button ]+ [ partition [ button ]+ ] ')'

\1f
File: lispref.info,  Node: Dialog Box Functions,  Prev: Dialog Box Format,  Up: Dialog Boxes

28.2 Dialog Box Functions
=========================

 -- Function: popup-dialog-box dbox-desc
     This function pops up a dialog box.  DBOX-DESC describes how the
     dialog box will appear (*note Dialog Box Format::).

   *Note Yes-or-No Queries::, for functions to ask a yes/no question
using a dialog box.

\1f
File: lispref.info,  Node: Toolbar,  Next: Gutter,  Prev: Dialog Boxes,  Up: Top

29 Toolbar
**********

* Menu:

* Toolbar Intro::               An introduction.
* Creating Toolbar::            How to create a toolbar.
* Toolbar Descriptor Format::   Accessing and modifying a toolbar's
                                  properties.
* Specifying the Toolbar::      Setting a toolbar's contents.
* Other Toolbar Variables::     Controlling the size of toolbars.

\1f
File: lispref.info,  Node: Toolbar Intro,  Next: Creating Toolbar,  Up: Toolbar

29.1 Toolbar Intro
==================

A "toolbar" is a bar of icons displayed along one edge of a frame.  You
can view a toolbar as a series of menu shortcuts--the most common menu
options can be accessed with a single click rather than a series of
clicks and/or drags to select the option from a menu.  Consistent with
this, a help string (called the "help-echo") describing what an icon in
the toolbar (called a "toolbar button") does, is displayed in the
minibuffer when the mouse is over the button.

   In XEmacs, a toolbar can be displayed along any of the four edges of
the frame, and two or more different edges can be displaying toolbars
simultaneously.  The contents, thickness, and visibility of the
toolbars can be controlled separately, and the values can be
per-buffer, per-frame, etc., using specifiers (*note Specifiers::).

   Normally, there is one toolbar displayed in a frame.  Usually, this
is the standard toolbar, but certain modes will override this and
substitute their own toolbar.  In some cases (e.g. the VM package), a
package will supply its own toolbar along a different edge from the
standard toolbar, so that both can be visible at once.  This standard
toolbar is usually positioned along the top of the frame, but this can
be changed using `set-default-toolbar-position'.

   Note that, for each of the toolbar properties (contents, thickness,
and visibility), there is a separate specifier for each of the four
toolbar positions (top, bottom, left, and right), and an additional
specifier for the "default" toolbar, i.e. the toolbar whose position is
controlled by `set-default-toolbar-position'.  The way this works is
that `set-default-toolbar-position' arranges things so that the
appropriate position-specific specifiers for the default position
inherit from the corresponding default specifiers.  That way, if the
position-specific specifier does not give a value (which it usually
doesn't), then the value from the default specifier applies.  If you
want to control the default toolbar, you just change the default
specifiers, and everything works.  A package such as VM that wants to
put its own toolbar in a different location from the default just sets
the position-specific specifiers, and if the user sets the default
toolbar to the same position, it will just not be visible.

\1f
File: lispref.info,  Node: Creating Toolbar,  Next: Toolbar Descriptor Format,  Prev: Toolbar Intro,  Up: Toolbar

29.2 Creating Toolbar
=====================

 -- Function: make-toolbar-specifier spec-list
     Return a new `toolbar' specifier object with the given
     specification list.  SPEC-LIST can be a list of specifications
     (each of which is a cons of a locale and a list of instantiators),
     a single instantiator, or a list of instantiators.  *Note
     Specifiers::, for more information about specifiers.

     Toolbar specifiers are used to specify the format of a toolbar.
     The values of the variables `default-toolbar', `top-toolbar',
     `left-toolbar', `right-toolbar', and `bottom-toolbar' are always
     toolbar specifiers.

     Valid toolbar instantiators are called "toolbar descriptors" and
     are lists of vectors.  See `default-toolbar' for a description of
     the exact format.

\1f
File: lispref.info,  Node: Toolbar Descriptor Format,  Next: Specifying the Toolbar,  Prev: Creating Toolbar,  Up: Toolbar

29.3 Toolbar Descriptor Format
==============================

The contents of a toolbar are specified using a "toolbar descriptor".
The format of a toolbar descriptor is a list of "toolbar button
descriptors".  Each toolbar button descriptor is a vector in one of the
following formats:

   * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'

   * `[:style 2D-OR-3D]'

   * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'

   * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'

   Optionally, one of the toolbar button descriptors may be `nil'
instead of a vector; this signifies the division between the toolbar
buttons that are to be displayed flush-left, and the buttons to be
displayed flush-right.

   The first vector format above specifies a normal toolbar button; the
others specify blank areas in the toolbar.

   For the first vector format:

   * GLYPH-LIST should be a list of one to six glyphs (as created by
     `make-glyph') or a symbol whose value is such a list.  The first
     glyph, which must be provided, is the glyph used to display the
     toolbar button when it is in the "up" (not pressed) state.  The
     optional second glyph is for displaying the button when it is in
     the "down" (pressed) state.  The optional third glyph is for when
     the button is disabled.  The last three glyphs are for displaying
     the button in the "up", "down", and "disabled" states,
     respectively, but are used when the user has called for captioned
     toolbar buttons (using `toolbar-buttons-captioned-p').  The
     function `toolbar-make-button-list' is useful in creating these
     glyph lists.

   * Even if you do not provide separate down-state and disabled-state
     glyphs, the user will still get visual feedback to indicate which
     state the button is in.  Buttons in the up-state are displayed
     with a shadowed border that gives a raised appearance to the
     button.  Buttons in the down-state are displayed with shadows that
     give a recessed appearance.  Buttons in the disabled state are
     displayed with no shadows, giving a 2-d effect.

   * If some of the toolbar glyphs are not provided, they inherit as
     follows:

               UP:                up
               DOWN:              down -> up
               DISABLED:          disabled -> up
               CAP-UP:            cap-up -> up
               CAP-DOWN:          cap-down -> cap-up -> down -> up
               CAP-DISABLED:      cap-disabled -> cap-up -> disabled -> up

   * The second element FUNCTION is a function to be called when the
     toolbar button is activated (i.e. when the mouse is released over
     the toolbar button, if the press occurred in the toolbar).  It can
     be any form accepted by `call-interactively', since this is how it
     is invoked.

   * The third element ENABLED-P specifies whether the toolbar button
     is enabled (disabled buttons do nothing when they are activated,
     and are displayed differently; see above).  It should be either a
     boolean or a form that evaluates to a boolean.

   * The fourth element HELP, if non-`nil', should be a string.  This
     string is displayed in the echo area when the mouse passes over the
     toolbar button.

   For the other vector formats (specifying blank areas of the toolbar):

   * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
     whether the area is displayed with shadows (giving it a raised,
     3-d appearance) or without shadows (giving it a flat appearance).

   * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
     area.  If omitted, it defaults to a device-specific value (8
     pixels for X devices).

 -- Function: toolbar-make-button-list up &optional down disabled
          cap-up cap-down cap-disabled
     This function calls `make-glyph' on each arg and returns a list of
     the results.  This is useful for setting the first argument of a
     toolbar button descriptor (typically, the result of this function
     is assigned to a symbol, which is specified as the first argument
     of the toolbar button descriptor).

 -- Function: check-toolbar-button-syntax button &optional noerror
     Verify the syntax of entry BUTTON in a toolbar description list.
     If you want to verify the syntax of a toolbar description list as a
     whole, use `check-valid-instantiator' with a specifier type of
     `toolbar'.

\1f
File: lispref.info,  Node: Specifying the Toolbar,  Next: Other Toolbar Variables,  Prev: Toolbar Descriptor Format,  Up: Toolbar

29.4 Specifying the Toolbar
===========================

In order to specify the contents of a toolbar, set one of the specifier
variables `default-toolbar', `top-toolbar', `bottom-toolbar',
`left-toolbar', or `right-toolbar'.  These are specifiers, which means
you set them with `set-specifier' and query them with `specifier-specs'
or `specifier-instance'.  You will get an error if you try to set them
using `setq'.  The valid instantiators for these specifiers are toolbar
descriptors, as described above.  *Note Specifiers::, for more
information.

   Most of the time, you will set `default-toolbar', which allows the
user to choose where the toolbar should go.

 -- Specifier: default-toolbar
     The position of this toolbar is specified in the function
     `default-toolbar-position'.  If the corresponding
     position-specific toolbar (e.g. `top-toolbar' if
     `default-toolbar-position' is `top') does not specify a toolbar in
     a particular domain, then the value of `default-toolbar' in that
     domain, of any, will be used instead.

   Note that the toolbar at any particular position will not be
displayed unless its thickness (width or height, depending on
orientation) is non-zero and its visibility status is true.  The
thickness is controlled by the specifiers `top-toolbar-height',
`bottom-toolbar-height', `left-toolbar-width', and
`right-toolbar-width', and the visibility status is controlled by the
specifiers `top-toolbar-visible-p', `bottom-toolbar-visible-p',
`left-toolbar-visible-p', and `right-toolbar-visible-p' (*note Other
Toolbar Variables::).

 -- Function: set-default-toolbar-position position
     This function sets the position that the `default-toolbar' will be
     displayed at.  Valid positions are the symbols `top', `bottom',
     `left' and `right'.  What this actually does is set the fallback
     specifier for the position-specific specifier corresponding to the
     given position to `default-toolbar', and set the fallbacks for the
     other position-specific specifiers to `nil'.  It also does the
     same thing for the position-specific thickness and visibility
     specifiers, which inherit from one of `default-toolbar-height' or
     `default-toolbar-width', and from `default-toolbar-visible-p',
     respectively (*note Other Toolbar Variables::).

 -- Function: default-toolbar-position
     This function returns the position that the `default-toolbar' will
     be displayed at.

   You can also explicitly set a toolbar at a particular position.  When
redisplay determines what to display at a particular position in a
particular domain (i.e. window), it first consults the position-specific
toolbar.  If that does not yield a toolbar descriptor, the
`default-toolbar' is consulted if `default-toolbar-position' indicates
this position.

 -- Specifier: top-toolbar
     Specifier for the toolbar at the top of the frame.

 -- Specifier: bottom-toolbar
     Specifier for the toolbar at the bottom of the frame.

 -- Specifier: left-toolbar
     Specifier for the toolbar at the left edge of the frame.

 -- Specifier: right-toolbar
     Specifier for the toolbar at the right edge of the frame.

 -- Function: toolbar-specifier-p object
     This function returns non-`nil' if OBJECT is a toolbar specifier.
     Toolbar specifiers are the actual objects contained in the toolbar
     variables described above, and their valid instantiators are
     toolbar descriptors (*note Toolbar Descriptor Format::).

\1f
File: lispref.info,  Node: Other Toolbar Variables,  Prev: Specifying the Toolbar,  Up: Toolbar

29.5 Other Toolbar Variables
============================

The variables to control the toolbar thickness, visibility status, and
captioned status are all specifiers.  *Note Specifiers::.

 -- Specifier: default-toolbar-height
     This specifies the height of the default toolbar, if it's oriented
     horizontally.  The position of the default toolbar is specified by
     the function `set-default-toolbar-position'.  If the corresponding
     position-specific toolbar thickness specifier (e.g.
     `top-toolbar-height' if `default-toolbar-position' is `top') does
     not specify a thickness in a particular domain (a window or a
     frame), then the value of `default-toolbar-height' or
     `default-toolbar-width' (depending on the toolbar orientation) in
     that domain, if any, will be used instead.

 -- Specifier: default-toolbar-width
     This specifies the width of the default toolbar, if it's oriented
     vertically.  This behaves like `default-toolbar-height'.

   Note that `default-toolbar-height' is only used when
`default-toolbar-position' is `top' or `bottom', and
`default-toolbar-width' is only used when `default-toolbar-position' is
`left' or `right'.

 -- Specifier: top-toolbar-height
     This specifies the height of the top toolbar.

 -- Specifier: bottom-toolbar-height
     This specifies the height of the bottom toolbar.

 -- Specifier: left-toolbar-width
     This specifies the width of the left toolbar.

 -- Specifier: right-toolbar-width
     This specifies the width of the right toolbar.

   Note that all of the position-specific toolbar thickness specifiers
have a fallback value of zero when they do not correspond to the
default toolbar.  Therefore, you will have to set a non-zero thickness
value if you want a position-specific toolbar to be displayed.

 -- Specifier: default-toolbar-visible-p
     This specifies whether the default toolbar is visible.  The
     position of the default toolbar is specified by the function
     `set-default-toolbar-position'.  If the corresponding
     position-specific toolbar visibility specifier (e.g.
     `top-toolbar-visible-p' if `default-toolbar-position' is `top')
     does not specify a visible-p value in a particular domain (a
     window or a frame), then the value of `default-toolbar-visible-p'
     in that domain, if any, will be used instead.

 -- Specifier: top-toolbar-visible-p
     This specifies whether the top toolbar is visible.

 -- Specifier: bottom-toolbar-visible-p
     This specifies whether the bottom toolbar is visible.

 -- Specifier: left-toolbar-visible-p
     This specifies whether the left toolbar is visible.

 -- Specifier: right-toolbar-visible-p
     This specifies whether the right toolbar is visible.

   `default-toolbar-visible-p' and all of the position-specific toolbar
visibility specifiers have a fallback value of true.

   Internally, toolbar thickness and visibility specifiers are
instantiated in both window and frame domains, for different purposes.
The value in the domain of a frame's selected window specifies the
actual toolbar thickness or visibility that you will see in that frame.
The value in the domain of a frame itself specifies the toolbar
thickness or visibility that is used in frame geometry calculations.

   Thus, for example, if you set the frame width to 80 characters and
the left toolbar width for that frame to 68 pixels, then the frame will
be sized to fit 80 characters plus a 68-pixel left toolbar.  If you then
set the left toolbar width to 0 for a particular buffer (or if that
buffer does not specify a left toolbar or has a `nil' value specified
for `left-toolbar-visible-p'), you will find that, when that buffer is
displayed in the selected window, the window will have a width of 86 or
87 characters--the frame is sized for a 68-pixel left toolbar but the
selected window specifies that the left toolbar is not visible, so it is
expanded to take up the slack.

 -- Specifier: toolbar-buttons-captioned-p
     Whether toolbar buttons are captioned.  This affects which glyphs
     from a toolbar button descriptor are chosen.  *Note Toolbar
     Descriptor Format::.

   You can also reset the toolbar to what it was when XEmacs started up.

 -- Constant: initial-toolbar-spec
     The toolbar descriptor used to initialize `default-toolbar' at
     startup.

\1f
File: lispref.info,  Node: Gutter,  Next: Scrollbars,  Prev: Toolbar,  Up: Top

30 Gutter
*********

A gutter is a rectangle displayed along one edge of a frame.  It can
contain arbitrary text or graphics.

* Menu:

* Gutter Intro::                An introduction.
* Creating Gutter::             How to create a gutter.
* Gutter Descriptor Format::    Accessing and modifying a gutter's
                                  properties.
* Specifying a Gutter::         Setting a gutter's contents.
* Other Gutter Variables::      Controlling the size of gutters.
* Common Gutter Widgets::       Things to put in gutters.

\1f
File: lispref.info,  Node: Gutter Intro,  Next: Creating Gutter,  Prev: Gutter,  Up: Gutter

30.1 Gutter Intro
=================

A "gutter" is a rectangle displayed along one edge of a frame.  It can
contain arbitrary text or graphics.  It could be considered a
generalization of a toolbar, although toolbars are not currently
implemented using gutters.

   In XEmacs, a gutter can be displayed along any of the four edges of
the frame, and two or more different edges can be displaying gutters
simultaneously.  The contents, thickness, and visibility of the gutters
can be controlled separately, and the values can be per-buffer,
per-frame, etc., using specifiers (*note Specifiers::).

   Normally, there is one gutter displayed in a frame.  Usually, this is
the default gutter, containing buffer tabs, but modes cab override this
and substitute their own gutter.  This default gutter is usually
positioned along the top of the frame, but this can be changed using
`set-default-gutter-position'.

   Note that, for each of the gutter properties (contents, thickness,
and visibility), there is a separate specifier for each of the four
gutter positions (top, bottom, left, and right), and an additional
specifier for the "default" gutter, i.e. the gutter whose position is
controlled by `set-default-gutter-position'.  The way this works is
that `set-default-gutter-position' arranges things so that the
appropriate position-specific specifiers for the default position
inherit from the corresponding default specifiers.  That way, if the
position-specific specifier does not give a value (which it usually
doesn't), then the value from the default specifier applies.  If you
want to control the default gutter, you just change the default
specifiers, and everything works.  A package such as VM that wants to
put its own gutter in a different location from the default just sets
the position-specific specifiers, and if the user sets the default
gutter to the same position, it will just not be visible.

\1f
File: lispref.info,  Node: Creating Gutter,  Next: Gutter Descriptor Format,  Prev: Gutter Intro,  Up: Gutter

30.2 Creating Gutter
====================

 -- Function: make-gutter-specifier spec-list
     Return a new `gutter' specifier object with the given specification
     list.  SPEC-LIST can be a list of specifications (each of which is
     a cons of a locale and a list of instantiators), a single
     instantiator, or a list of instantiators.  *Note Specifiers::, for
     more information about specifiers.

     Gutter specifiers are used to specify the format of a gutter.  The
     values of the variables `default-gutter', `top-gutter',
     `left-gutter', `right-gutter', and `bottom-gutter' are always
     gutter specifiers.

     Valid gutter instantiators are called "gutter descriptors" and are
     either strings or property-lists of strings.  See `default-gutter'
     for a description of the exact format.

 -- Function: make-gutter-size-specifier spec-list
     Return a new `gutter-size' specifier object with the given spec
     list.  SPEC-LIST can be a list of specifications (each of which is
     a cons of a locale and a list of instantiators), a single
     instantiator, or a list of instantiators.  *Note Specifiers::, for
     more information about specifiers.

     Gutter-size specifiers are used to specify the size of a gutter.
     The values of the variables `default-gutter-size',
     `top-gutter-size', `left-gutter-size', `right-gutter-size', and
     `bottom-gutter-size' are always gutter-size specifiers.

     Valid gutter-size instantiators are either integers or the special
     symbol `autodetect'. If a gutter-size is set to `autodetect' them
     the size of the gutter will be adjusted to just accommodate the
     gutters contents. `autodetect' only works for top and bottom
     gutters.

 -- Function: make-gutter-visible-specifier spec-list
     Return a new `gutter-visible' specifier object with the given spec
     list.  SPEC-LIST can be a list of specifications (each of which is
     a cons of a locale and a list of instantiators), a single
     instantiator, or a list of instantiators.  *Note Specifiers::, for
     more information about specifiers.

     Gutter-visible specifiers are used to specify the visibility of a
     gutter.  The values of the variables `default-gutter-visible-p',
     `top-gutter-visible-p', `left-gutter-visible-p',
     `right-gutter-visible-p', and `bottom-gutter-visible-p' are always
     gutter-visible specifiers.

     Valid gutter-visible instantiators are `t', `nil' or a list of
     symbols.  If a gutter-visible instantiator is set to a list of
     symbols, and the corresponding gutter specification is a
     property-list strings, then elements of the gutter specification
     will only be visible if the corresponding symbol occurs in the
     gutter-visible instantiator.

\1f
File: lispref.info,  Node: Gutter Descriptor Format,  Next: Specifying a Gutter,  Prev: Creating Gutter,  Up: Gutter

30.3 Gutter Descriptor Format
=============================

The contents of a gutter are specified using a "gutter descriptor".
The format of a gutter descriptor is a list of "gutter button
descriptors".  Each gutter button descriptor is a vector in one of the
following formats:

   * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'

   * `[:style 2D-OR-3D]'

   * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'

   * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'

   Optionally, one of the gutter button descriptors may be `nil'
instead of a vector; this signifies the division between the gutter
buttons that are to be displayed flush-left, and the buttons to be
displayed flush-right.

   The first vector format above specifies a normal gutter button; the
others specify blank areas in the gutter.

   For the first vector format:

   * GLYPH-LIST should be a list of one to six glyphs (as created by
     `make-glyph') or a symbol whose value is such a list.  The first
     glyph, which must be provided, is the glyph used to display the
     gutter button when it is in the "up" (not pressed) state.  The
     optional second glyph is for displaying the button when it is in
     the "down" (pressed) state.  The optional third glyph is for when
     the button is disabled.  The last three glyphs are for displaying
     the button in the "up", "down", and "disabled" states,
     respectively, but are used when the user has called for captioned
     gutter buttons (using `gutter-buttons-captioned-p').  The function
     `gutter-make-button-list' is useful in creating these glyph lists.

   * Even if you do not provide separate down-state and disabled-state
     glyphs, the user will still get visual feedback to indicate which
     state the button is in.  Buttons in the up-state are displayed
     with a shadowed border that gives a raised appearance to the
     button.  Buttons in the down-state are displayed with shadows that
     give a recessed appearance.  Buttons in the disabled state are
     displayed with no shadows, giving a 2-d effect.

   * If some of the gutter glyphs are not provided, they inherit as
     follows:

               UP:                up
               DOWN:              down -> up
               DISABLED:          disabled -> up
               CAP-UP:            cap-up -> up
               CAP-DOWN:          cap-down -> cap-up -> down -> up
               CAP-DISABLED:      cap-disabled -> cap-up -> disabled -> up

   * The second element FUNCTION is a function to be called when the
     gutter button is activated (i.e. when the mouse is released over
     the gutter button, if the press occurred in the gutter).  It can
     be any form accepted by `call-interactively', since this is how it
     is invoked.

   * The third element ENABLED-P specifies whether the gutter button is
     enabled (disabled buttons do nothing when they are activated, and
     are displayed differently; see above).  It should be either a
     boolean or a form that evaluates to a boolean.

   * The fourth element HELP, if non-`nil', should be a string.  This
     string is displayed in the echo area when the mouse passes over the
     gutter button.

   For the other vector formats (specifying blank areas of the gutter):

   * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
     whether the area is displayed with shadows (giving it a raised,
     3-d appearance) or without shadows (giving it a flat appearance).

   * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
     area.  If omitted, it defaults to a device-specific value (8
     pixels for X devices).

 -- Function: gutter-make-button-list up &optional down disabled cap-up
          cap-down cap-disabled
     This function calls `make-glyph' on each arg and returns a list of
     the results.  This is useful for setting the first argument of a
     gutter button descriptor (typically, the result of this function
     is assigned to a symbol, which is specified as the first argument
     of the gutter button descriptor).

 -- Function: check-gutter-button-syntax button &optional noerror
     Verify the syntax of entry BUTTON in a gutter description list.
     If you want to verify the syntax of a gutter description list as a
     whole, use `check-valid-instantiator' with a specifier type of
     `gutter'.

\1f
File: lispref.info,  Node: Specifying a Gutter,  Next: Other Gutter Variables,  Prev: Gutter Descriptor Format,  Up: Gutter

30.4 Specifying a Gutter
========================

In order to specify the contents of a gutter, set one of the specifier
variables `default-gutter', `top-gutter', `bottom-gutter',
`left-gutter', or `right-gutter'.  These are specifiers, which means
you set them with `set-specifier' and query them with `specifier-specs'
or `specifier-instance'.  You will get an error if you try to set them
using `setq'.  The valid instantiators for these specifiers are gutter
descriptors, as described above.  *Note Specifiers::, for more
information.

   Most of the time, you will set `default-gutter', which allows the
user to choose where the gutter should go.

 -- Specifier: default-gutter
     The position of this gutter is specified in the function
     `default-gutter-position'.  If the corresponding position-specific
     gutter (e.g. `top-gutter' if `default-gutter-position' is `top')
     does not specify a gutter in a particular domain, then the value
     of `default-gutter' in that domain, of any, will be used instead.

   Note that the gutter at any particular position will not be displayed
unless its thickness (width or height, depending on orientation) is
non-zero and its visibility status is true.  The thickness is controlled
by the specifiers `top-gutter-height', `bottom-gutter-height',
`left-gutter-width', and `right-gutter-width', and the visibility
status is controlled by the specifiers `top-gutter-visible-p',
`bottom-gutter-visible-p', `left-gutter-visible-p', and
`right-gutter-visible-p' (*note Other Gutter Variables::).

 -- Function: set-default-gutter-position position
     This function sets the position that the `default-gutter' will be
     displayed at.  Valid positions are the symbols `top', `bottom',
     `left' and `right'.  What this actually does is set the fallback
     specifier for the position-specific specifier corresponding to the
     given position to `default-gutter', and set the fallbacks for the
     other position-specific specifiers to `nil'.  It also does the
     same thing for the position-specific thickness and visibility
     specifiers, which inherit from one of `default-gutter-height' or
     `default-gutter-width', and from `default-gutter-visible-p',
     respectively (*note Other Gutter Variables::).

 -- Function: default-gutter-position
     This function returns the position that the `default-gutter' will
     be displayed at.

   You can also explicitly set a gutter at a particular position.  When
redisplay determines what to display at a particular position in a
particular domain (i.e. window), it first consults the position-specific
gutter.  If that does not yield a gutter descriptor, the
`default-gutter' is consulted if `default-gutter-position' indicates
this position.

 -- Specifier: top-gutter
     Specifier for the gutter at the top of the frame.

 -- Specifier: bottom-gutter
     Specifier for the gutter at the bottom of the frame.

 -- Specifier: left-gutter
     Specifier for the gutter at the left edge of the frame.

 -- Specifier: right-gutter
     Specifier for the gutter at the right edge of the frame.

 -- Function: gutter-specifier-p object
     This function returns non-`nil' if OBJECT is a gutter specifier.
     Gutter specifiers are the actual objects contained in the gutter
     variables described above, and their valid instantiators are
     gutter descriptors (*note Gutter Descriptor Format::).

\1f
File: lispref.info,  Node: Other Gutter Variables,  Next: Common Gutter Widgets,  Prev: Specifying a Gutter,  Up: Gutter

30.5 Other Gutter Variables
===========================

The variables to control the gutter thickness, visibility status, and
captioned status are all specifiers.  *Note Specifiers::.

 -- Specifier: default-gutter-height
     This specifies the height of the default gutter, if it's oriented
     horizontally.  The position of the default gutter is specified by
     the function `set-default-gutter-position'.  If the corresponding
     position-specific gutter thickness specifier (e.g.
     `top-gutter-height' if `default-gutter-position' is `top') does
     not specify a thickness in a particular domain (a window or a
     frame), then the value of `default-gutter-height' or
     `default-gutter-width' (depending on the gutter orientation) in
     that domain, if any, will be used instead.

 -- Specifier: default-gutter-width
     This specifies the width of the default gutter, if it's oriented
     vertically.  This behaves like `default-gutter-height'.

   Note that `default-gutter-height' is only used when
`default-gutter-position' is `top' or `bottom', and
`default-gutter-width' is only used when `default-gutter-position' is
`left' or `right'.

 -- Specifier: top-gutter-height
     This specifies the height of the top gutter.

 -- Specifier: bottom-gutter-height
     This specifies the height of the bottom gutter.

 -- Specifier: left-gutter-width
     This specifies the width of the left gutter.

 -- Specifier: right-gutter-width
     This specifies the width of the right gutter.

   Note that all of the position-specific gutter thickness specifiers
have a fallback value of zero when they do not correspond to the
default gutter.  Therefore, you will have to set a non-zero thickness
value if you want a position-specific gutter to be displayed.

 -- Specifier: default-gutter-visible-p
     This specifies whether the default gutter is visible.  The
     position of the default gutter is specified by the function
     `set-default-gutter-position'.  If the corresponding
     position-specific gutter visibility specifier (e.g.
     `top-gutter-visible-p' if `default-gutter-position' is `top') does
     not specify a visible-p value in a particular domain (a window or
     a frame), then the value of `default-gutter-visible-p' in that
     domain, if any, will be used instead.

 -- Specifier: top-gutter-visible-p
     This specifies whether the top gutter is visible.

 -- Specifier: bottom-gutter-visible-p
     This specifies whether the bottom gutter is visible.

 -- Specifier: left-gutter-visible-p
     This specifies whether the left gutter is visible.

 -- Specifier: right-gutter-visible-p
     This specifies whether the right gutter is visible.

   `default-gutter-visible-p' and all of the position-specific gutter
visibility specifiers have a fallback value of true.

   Internally, gutter thickness and visibility specifiers are
instantiated in both window and frame domains, for different purposes.
The value in the domain of a frame's selected window specifies the
actual gutter thickness or visibility that you will see in that frame.
The value in the domain of a frame itself specifies the gutter
thickness or visibility that is used in frame geometry calculations.

   Thus, for example, if you set the frame width to 80 characters and
the left gutter width for that frame to 68 pixels, then the frame will
be sized to fit 80 characters plus a 68-pixel left gutter.  If you then
set the left gutter width to 0 for a particular buffer (or if that
buffer does not specify a left gutter or has a `nil' value specified for
`left-gutter-visible-p'), you will find that, when that buffer is
displayed in the selected window, the window will have a width of 86 or
87 characters - the frame is sized for a 68-pixel left gutter but the
selected window specifies that the left gutter is not visible, so it is
expanded to take up the slack.

 -- Specifier: gutter-buttons-captioned-p
     Whether gutter buttons are captioned.  This affects which glyphs
     from a gutter button descriptor are chosen.  *Note Gutter
     Descriptor Format::.

   You can also reset the gutter to what it was when XEmacs started up.

 -- Constant: initial-gutter-spec
     The gutter descriptor used to initialize `default-gutter' at
     startup.

\1f
File: lispref.info,  Node: Common Gutter Widgets,  Prev: Other Gutter Variables,  Up: Gutter

30.6 Common Gutter Widgets
==========================

A gutter can contain arbitrary text.  So, for example, in an Info
buffer you could put the title of the current node in the top gutter,
and it would not scroll out of view in a long node.  (This is an
artificial example, since usually the node name is sufficiently
descriptive, and Info puts that in the mode line.)

   A more common use for the gutter is to hold some kind of active
widget.  The buffer-tab facility, available in all XEmacs frames,
creates an array of file-folder-like tabs, which the user can click with
the mouse to switch buffers.  W3 uses a progress-bar widget in the
bottom gutter to give a visual indication of the progress of
time-consuming operations like downloading.

* Menu:

* Buffer Tabs::         Tabbed divider index metaphor for switching buffers.
* Progress Bars::       Visual indication of operation progress.

\1f
File: lispref.info,  Node: Buffer Tabs,  Next: Progress Bars,  Up: Common Gutter Widgets

30.6.1 Buffer Tabs
------------------

Not documented yet.

\1f
File: lispref.info,  Node: Progress Bars,  Prev: Buffer Tabs,  Up: Common Gutter Widgets

30.6.2 Progress Bars
--------------------

Not documented yet.

\1f
File: lispref.info,  Node: Scrollbars,  Next: Drag and Drop,  Prev: Gutter,  Up: Top

31 Scrollbars
*************

Not yet documented.

\1f
File: lispref.info,  Node: Drag and Drop,  Next: Modes,  Prev: Scrollbars,  Up: Top

32 Drag and Drop
****************

_WARNING_: the Drag'n'Drop API is still under development and the
interface may change! The current implementation is considered
experimental.

   Drag'n'drop is a way to transfer information between multiple
applications.  To do this several GUIs define their own protocols.
Examples are OffiX, CDE, Motif, KDE, MSWindows, GNOME, and many more.
To catch all these protocols, XEmacs provides a generic API.

   One prime idea behind the API is to use a data interface that is
transparent for all systems. The author thinks that this is best
archived by using URL and MIME data, cause any internet enabled system
must support these for email already. XEmacs also already provides
powerful interfaces to support these types of data (tm and w3).

* Menu:

* Supported Protocols:: Which low-level protocols are supported.
* Drop Interface::      How XEmacs handles a drop from another application.
* Drag Interface::      Calls to initiate a drag from XEmacs.

\1f
File: lispref.info,  Node: Supported Protocols,  Next: Drop Interface,  Up: Drag and Drop

32.1 Supported Protocols
========================

The current release of XEmacs only support a small set of Drag'n'drop
protocols. Some of these only support limited options available in the
API.

* Menu:

* OffiX DND::           A generic X based protocol.
* CDE dt::              Common Desktop Environment used on suns.
* MSWindows OLE::       Mr. Gates way of live.
* Loose ends::          The other protocols.

\1f
File: lispref.info,  Node: OffiX DND,  Next: CDE dt,  Up: Supported Protocols

32.1.1 OffiX DND
----------------

_WARNING_: If you compile in OffiX, you may not be able to use multiple
X displays successfully.  If the two servers are from different
vendors, the results may be unpredictable.

   The OffiX Drag'n'Drop protocol is part of a X API/Widget library
created by Cesar Crusius. It is based on X-Atoms and ClientMessage
events, and works with any X platform supporting them.

   OffiX is supported if 'offix is member of the variable
dragdrop-protocols, or the feature 'offix is defined.

   Unfortunately it uses it's own data types. Examples are: File, Files,
Exe, Link, URL, MIME. The API tries to choose the right type for the
data that is dragged from XEmacs (well, not yet...).

   XEmacs supports both MIME and URL drags and drops using this API. No
application interaction is possible while dragging is in progress.

   For information about the OffiX project have a look at
http://leb.net/~offix/

\1f
File: lispref.info,  Node: CDE dt,  Next: MSWindows OLE,  Prev: OffiX DND,  Up: Supported Protocols

32.1.2 CDE dt
-------------

CDE stands for Common Desktop Environment. It is based on the Motif
widget library. It's drag'n'drop protocol is also an abstraction of the
Motif protocol (so it might be possible, that XEmacs will also support
the Motif protocol soon).

   CDE has three different types: file, buffer, and text. XEmacs only
uses file and buffer drags. The API will disallow full URL drags, only
file method URLs are passed through.

   Buffer drags are always converted to plain text.

\1f
File: lispref.info,  Node: MSWindows OLE,  Next: Loose ends,  Prev: CDE dt,  Up: Supported Protocols

32.1.3 MSWindows OLE
--------------------

Only allows file drags and drops.

\1f
File: lispref.info,  Node: Loose ends,  Prev: MSWindows OLE,  Up: Supported Protocols

32.1.4 Loose ends
-----------------

The following protocols will be supported soon: Xdnd, Motif, Xde (if I
get some specs), KDE OffiX (if KDE can find XEmacs windows).

   In particular Xdnd will be one of the protocols that can benefit from
the XEmacs API, cause it also uses MIME types to encode dragged data.

\1f
File: lispref.info,  Node: Drop Interface,  Next: Drag Interface,  Prev: Supported Protocols,  Up: Drag and Drop

32.2 Drop Interface
===================

For each activated low-level protocol, an internal routine will catch
incoming drops and convert them to a dragdrop-drop type misc-user-event.

   This misc-user-event has its function argument set to
`dragdrop-drop-dispatch' and the object contains the data of the drop
(converted to URL/MIME specific data). This function will search the
variable `experimental-dragdrop-drop-functions' for a function that can
handle the dropped data.

   To modify the drop behavior, the user can modify the variable
`experimental-dragdrop-drop-functions'. Each element of this list
specifies a possible handler for dropped data. The first one that can
handle the data will return `t' and exit. Another possibility is to set
a extent-property with the same name. Extents are checked prior to the
variable.

   The customization group `drag-n-drop' shows all variables of user
interest.

\1f
File: lispref.info,  Node: Drag Interface,  Prev: Drop Interface,  Up: Drag and Drop

32.3 Drag Interface
===================

This describes the drag API (not implemented yet).

\1f
File: lispref.info,  Node: Modes,  Next: Documentation,  Prev: Drag and Drop,  Up: Top

33 Major and Minor Modes
************************

A "mode" is a set of definitions that customize XEmacs and can be
turned on and off while you edit.  There are two varieties of modes:
"major modes", which are mutually exclusive and used for editing
particular kinds of text, and "minor modes", which provide features
that users can enable individually.

   This chapter describes how to write both major and minor modes, how
to indicate them in the modeline, and how they run hooks supplied by the
user.  For related topics such as keymaps and syntax tables, see *Note
Keymaps::, and *Note Syntax Tables::.

* Menu:

* Major Modes::        Defining major modes.
* Minor Modes::        Defining minor modes.
* Modeline Format::    Customizing the text that appears in the modeline.
* Hooks::              How to use hooks; how to write code that provides hooks.

\1f
File: lispref.info,  Node: Major Modes,  Next: Minor Modes,  Up: Modes

33.1 Major Modes
================

Major modes specialize XEmacs for editing particular kinds of text.
Each buffer has only one major mode at a time.  For each major mode
there is a function to switch to that mode in the current buffer; its
name should end in `-mode'.  These functions work by setting
buffer-local variable bindings and other data associated with the
buffer, such as a local keymap.  The effect lasts until you switch to
another major mode in the same buffer.

   The least specialized major mode is called "Fundamental mode".  This
mode has no mode-specific definitions or variable settings, so each
XEmacs command behaves in its default manner, and each option is in its
default state.  All other major modes redefine various keys and options.
For example, Lisp Interaction mode provides special key bindings for
<LFD> (`eval-print-last-sexp'), <TAB> (`lisp-indent-line'), and other
keys.

   When you need to write several editing commands to help you perform a
specialized editing task, creating a new major mode is usually a good
idea.  In practice, writing a major mode is easy (in contrast to
writing a minor mode, which is often difficult).

   If the new mode is similar to an old one, it is often unwise to
modify the old one to serve two purposes, since it may become harder to
use and maintain.  Instead, copy and rename an existing major mode
definition and alter the copy--or define a "derived mode" (*note
Derived Modes::).  For example, Rmail Edit mode, which is in
`emacs/lisp/rmailedit.el', is a major mode that is very similar to Text
mode except that it provides three additional commands.  Its definition
is distinct from that of Text mode, but was derived from it.

   Even if the new mode is not an obvious derivative of any other mode,
it is convenient to use `define-derived-mode' with a `nil' parent
argument, since it automatically enforces the most important coding
conventions for you.

   Rmail Edit mode is an example of a case where one piece of text is
put temporarily into a different major mode so it can be edited in a
different way (with ordinary XEmacs commands rather than Rmail).  In
such cases, the temporary major mode usually has a command to switch
back to the buffer's usual mode (Rmail mode, in this case).  You might
be tempted to present the temporary redefinitions inside a recursive
edit and restore the usual ones when the user exits; but this is a bad
idea because it constrains the user's options when it is done in more
than one buffer: recursive edits must be exited most-recently-entered
first.  Using alternative major modes avoids this limitation.  *Note
Recursive Editing::.

   The standard XEmacs Lisp library directory contains the code for
several major modes, in files including `text-mode.el', `texinfo.el',
`lisp-mode.el', `c-mode.el', and `rmail.el'.  You can look at these
libraries to see how modes are written.  Text mode is perhaps the
simplest major mode aside from Fundamental mode.  Rmail mode is a
complicated and specialized mode.

* Menu:

* Major Mode Conventions::  Coding conventions for keymaps, etc.
* Example Major Modes::     Text mode and Lisp modes.
* Auto Major Mode::         How XEmacs chooses the major mode automatically.
* Mode Help::               Finding out how to use a mode.
* Derived Modes::           Defining a new major mode based on another major
                              mode.

\1f
File: lispref.info,  Node: Major Mode Conventions,  Next: Example Major Modes,  Up: Major Modes

33.1.1 Major Mode Conventions
-----------------------------

The code for existing major modes follows various coding conventions,
including conventions for local keymap and syntax table initialization,
global names, and hooks.  Please follow these conventions when you
define a new major mode:

   * Define a command whose name ends in `-mode', with no arguments,
     that switches to the new mode in the current buffer.  This command
     should set up the keymap, syntax table, and local variables in an
     existing buffer without changing the buffer's text.

   * Write a documentation string for this command that describes the
     special commands available in this mode.  `C-h m'
     (`describe-mode') in your mode will display this string.

     The documentation string may include the special documentation
     substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that
     enable the documentation to adapt automatically to the user's own
     key bindings.  *Note Keys in Documentation::.

   * The major mode command should start by calling
     `kill-all-local-variables'.  This is what gets rid of the local
     variables of the major mode previously in effect.

   * The major mode command should set the variable `major-mode' to the
     major mode command symbol.  This is how `describe-mode' discovers
     which documentation to print.

   * The major mode command should set the variable `mode-name' to the
     "pretty" name of the mode, as a string.  This appears in the mode
     line.

   * Since all global names are in the same name space, all the global
     variables, constants, and functions that are part of the mode
     should have names that start with the major mode name (or with an
     abbreviation of it if the name is long).  *Note Style Tips::.

   * The major mode should usually have its own keymap, which is used
     as the local keymap in all buffers in that mode.  The major mode
     function should call `use-local-map' to install this local map.
     *Note Active Keymaps::, for more information.

     This keymap should be kept in a global variable named
     `MODENAME-mode-map'.  Normally the library that defines the mode
     sets this variable.

   * The mode may have its own syntax table or may share one with other
     related modes.  If it has its own syntax table, it should store
     this in a variable named `MODENAME-mode-syntax-table'.  *Note
     Syntax Tables::.

   * The mode may have its own abbrev table or may share one with other
     related modes.  If it has its own abbrev table, it should store
     this in a variable named `MODENAME-mode-abbrev-table'.  *Note
     Abbrev Tables::.

   * Use `defvar' to set mode-related variables, so that they are not
     reinitialized if they already have a value.  (Such reinitialization
     could discard customizations made by the user.)

   * To make a buffer-local binding for an Emacs customization
     variable, use `make-local-variable' in the major mode command, not
     `make-variable-buffer-local'.  The latter function would make the
     variable local to every buffer in which it is subsequently set,
     which would affect buffers that do not use this mode.  It is
     undesirable for a mode to have such global effects.  *Note
     Buffer-Local Variables::.

     It's ok to use `make-variable-buffer-local', if you wish, for a
     variable used only within a single Lisp package.

   * Each major mode should have a "mode hook" named
     `MODENAME-mode-hook'.  The major mode command should run that
     hook, with `run-hooks', as the very last thing it does. *Note
     Hooks::.

   * The major mode command may also run the hooks of some more basic
     modes.  For example, `indented-text-mode' runs `text-mode-hook' as
     well as `indented-text-mode-hook'.  It may run these other hooks
     immediately before the mode's own hook (that is, after everything
     else), or it may run them earlier.

   * The major mode command may start by calling some other major mode
     command (called the "parent mode") and then alter some of its
     settings.  A mode that does this is called a "derived mode".  The
     recommended way to define one is to use `define-derived-mode', but
     this is not required.  Such a mode should use `delay-mode-hooks'
     around its entire body, including the call to the parent mode
     command and the final call to `run-mode-hooks'.  (Using
     `define-derived-mode' does this automatically.)

   * If something special should be done if the user switches a buffer
     from this mode to any other major mode, the mode can set a local
     value for `change-major-mode-hook'.

   * If this mode is appropriate only for specially-prepared text, then
     the major mode command symbol should have a property named
     `mode-class' with value `special', put on as follows:

          (put 'funny-mode 'mode-class 'special)

     This tells XEmacs that new buffers created while the current
     buffer has Funny mode should not inherit Funny mode.  Modes such
     as Dired, Rmail, and Buffer List use this feature.

   * If you want to make the new mode the default for files with certain
     recognizable names, add an element to `auto-mode-alist' to select
     the mode for those file names.  If you define the mode command to
     autoload, you should add this element in the same file that calls
     `autoload'.  Otherwise, it is sufficient to add the element in the
     file that contains the mode definition.  *Note Auto Major Mode::.

   * In the documentation, you should provide a sample `autoload' form
     and an example of how to add to `auto-mode-alist', that users can
     include in their `.emacs' files.

   * The top-level forms in the file defining the mode should be
     written so that they may be evaluated more than once without
     adverse consequences.  Even if you never load the file more than
     once, someone else will.

 -- Variable: change-major-mode-hook
     This normal hook is run by `kill-all-local-variables' before it
     does anything else.  This gives major modes a way to arrange for
     something special to be done if the user switches to a different
     major mode.  For best results, make this variable buffer-local, so
     that it will disappear after doing its job and will not interfere
     with the subsequent major mode.  *Note Hooks::.

\1f
File: lispref.info,  Node: Example Major Modes,  Next: Auto Major Mode,  Prev: Major Mode Conventions,  Up: Major Modes

33.1.2 Major Mode Examples
--------------------------

Text mode is perhaps the simplest mode besides Fundamental mode.  Here
are excerpts from  `text-mode.el' that illustrate many of the
conventions listed above:

     ;; Create mode-specific tables.
     (defvar text-mode-syntax-table nil
       "Syntax table used while in text mode.")

     (if text-mode-syntax-table
         ()              ; Do not change the table if it is already set up.
       (setq text-mode-syntax-table (make-syntax-table))
       (modify-syntax-entry ?\" ".   " text-mode-syntax-table)
       (modify-syntax-entry ?\\ ".   " text-mode-syntax-table)
       (modify-syntax-entry ?' "w   " text-mode-syntax-table))

     (defvar text-mode-abbrev-table nil
       "Abbrev table used while in text mode.")
     (define-abbrev-table 'text-mode-abbrev-table ())

     (defvar text-mode-map nil)   ; Create a mode-specific keymap.

     (if text-mode-map
         ()              ; Do not change the keymap if it is already set up.
       (setq text-mode-map (make-sparse-keymap))
       (define-key text-mode-map "\t" 'tab-to-tab-stop)
       (define-key text-mode-map "\es" 'center-line)
       (define-key text-mode-map "\eS" 'center-paragraph))

   Here is the complete major mode function definition for Text mode:

     (defun text-mode ()
       "Major mode for editing text intended for humans to read.
      Special commands: \\{text-mode-map}
     Turning on text-mode runs the hook `text-mode-hook'."
       (interactive)
       (kill-all-local-variables)
       (use-local-map text-mode-map)     ; This provides the local keymap.
       (setq mode-name "Text")           ; This name goes into the modeline.
       (setq major-mode 'text-mode)      ; This is how `describe-mode'
                                         ;   finds the doc string to print.
       (setq local-abbrev-table text-mode-abbrev-table)
       (set-syntax-table text-mode-syntax-table)
       (run-hooks 'text-mode-hook))      ; Finally, this permits the user to
                                         ;   customize the mode with a hook.

   The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
Interaction mode) have more features than Text mode and the code is
correspondingly more complicated.  Here are excerpts from
`lisp-mode.el' that illustrate how these modes are written.

     ;; Create mode-specific table variables.
     (defvar lisp-mode-syntax-table nil "")
     (defvar emacs-lisp-mode-syntax-table nil "")
     (defvar lisp-mode-abbrev-table nil "")

     (if (not emacs-lisp-mode-syntax-table) ; Do not change the table
                                            ;   if it is already set.
         (let ((i 0))
           (setq emacs-lisp-mode-syntax-table (make-syntax-table))

           ;; Set syntax of chars up to 0 to class of chars that are
           ;;   part of symbol names but not words.
           ;;   (The number 0 is `48' in the ASCII character set.)
           (while (< i ?0)
             (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
             (setq i (1+ i)))
           ...
           ;; Set the syntax for other characters.
           (modify-syntax-entry ?  "    " emacs-lisp-mode-syntax-table)
           (modify-syntax-entry ?\t "    " emacs-lisp-mode-syntax-table)
           ...
           (modify-syntax-entry ?\( "()  " emacs-lisp-mode-syntax-table)
           (modify-syntax-entry ?\) ")(  " emacs-lisp-mode-syntax-table)
           ...))
     ;; Create an abbrev table for lisp-mode.
     (define-abbrev-table 'lisp-mode-abbrev-table ())

   Much code is shared among the three Lisp modes.  The following
function sets various variables; it is called by each of the major Lisp
mode functions:

     (defun lisp-mode-variables (lisp-syntax)
       ;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode,
       ;;   and `t' in the other two Lisp modes.
       (cond (lisp-syntax
              (if (not lisp-mode-syntax-table)
                  ;; The Emacs Lisp mode syntax table always exists, but
                  ;;   the Lisp Mode syntax table is created the first time a
                  ;;   mode that needs it is called.  This is to save space.
                  (progn (setq lisp-mode-syntax-table
                            (copy-syntax-table emacs-lisp-mode-syntax-table))
                         ;; Change some entries for Lisp mode.
                         (modify-syntax-entry ?\| "\"   "
                                              lisp-mode-syntax-table)
                         (modify-syntax-entry ?\[ "_   "
                                              lisp-mode-syntax-table)
                         (modify-syntax-entry ?\] "_   "
                                              lisp-mode-syntax-table)))
               (set-syntax-table lisp-mode-syntax-table)))
       (setq local-abbrev-table lisp-mode-abbrev-table)
       ...)

   Functions such as `forward-paragraph' use the value of the
`paragraph-start' variable.  Since Lisp code is different from ordinary
text, the `paragraph-start' variable needs to be set specially to
handle Lisp.  Also, comments are indented in a special fashion in Lisp
and the Lisp modes need their own mode-specific
`comment-indent-function'.  The code to set these variables is the rest
of `lisp-mode-variables'.

       (make-local-variable 'paragraph-start)
       ;; Having `^' is not clean, but `page-delimiter'
       ;; has them too, and removing those is a pain.
       (setq paragraph-start (concat "^$\\|" page-delimiter))
       ...
       (make-local-variable 'comment-indent-function)
       (setq comment-indent-function 'lisp-comment-indent))

   Each of the different Lisp modes has a slightly different keymap.
For example, Lisp mode binds `C-c C-l' to `run-lisp', but the other
Lisp modes do not.  However, all Lisp modes have some commands in
common.  The following function adds these common commands to a given
keymap.

     (defun lisp-mode-commands (map)
       (define-key map "\e\C-q" 'indent-sexp)
       (define-key map "\177" 'backward-delete-char-untabify)
       (define-key map "\t" 'lisp-indent-line))

   Here is an example of using `lisp-mode-commands' to initialize a
keymap, as part of the code for Emacs Lisp mode.  First we declare a
variable with `defvar' to hold the mode-specific keymap.  When this
`defvar' executes, it sets the variable to `nil' if it was void.  Then
we set up the keymap if the variable is `nil'.

   This code avoids changing the keymap or the variable if it is already
set up.  This lets the user customize the keymap.

     (defvar emacs-lisp-mode-map () "")
     (if emacs-lisp-mode-map
         ()
       (setq emacs-lisp-mode-map (make-sparse-keymap))
       (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
       (lisp-mode-commands emacs-lisp-mode-map))

   Finally, here is the complete major mode function definition for
Emacs Lisp mode.

     (defun emacs-lisp-mode ()
       "Major mode for editing Lisp code to run in XEmacs.
     Commands:
     Delete converts tabs to spaces as it moves back.
     Blank lines separate paragraphs.  Semicolons start comments.
     \\{emacs-lisp-mode-map}
     Entry to this mode runs the hook `emacs-lisp-mode-hook'."
       (interactive)
       (kill-all-local-variables)
       (use-local-map emacs-lisp-mode-map)    ; This provides the local keymap.
       (set-syntax-table emacs-lisp-mode-syntax-table)
       (setq major-mode 'emacs-lisp-mode)     ; This is how `describe-mode'
                                              ;   finds out what to describe.
       (setq mode-name "Emacs-Lisp")          ; This goes into the modeline.
       (lisp-mode-variables nil)              ; This defines various variables.
       (run-hooks 'emacs-lisp-mode-hook))     ; This permits the user to use a
                                              ;   hook to customize the mode.

\1f
File: lispref.info,  Node: Auto Major Mode,  Next: Mode Help,  Prev: Example Major Modes,  Up: Major Modes

33.1.3 How XEmacs Chooses a Major Mode
--------------------------------------

Based on information in the file name or in the file itself, XEmacs
automatically selects a major mode for the new buffer when a file is
visited.

 -- Command: fundamental-mode
     Fundamental mode is a major mode that is not specialized for
     anything in particular.  Other major modes are defined in effect
     by comparison with this one--their definitions say what to change,
     starting from Fundamental mode.  The `fundamental-mode' function
     does _not_ run any hooks; you're not supposed to customize it.
     (If you want Emacs to behave differently in Fundamental mode,
     change the _global_ state of Emacs.)

 -- Command: normal-mode &optional find-file
     This function establishes the proper major mode and local variable
     bindings for the current buffer.  First it calls `set-auto-mode',
     then it runs `hack-local-variables' to parse, and bind or evaluate
     as appropriate, any local variables.

     If the FIND-FILE argument to `normal-mode' is non-`nil',
     `normal-mode' assumes that the `find-file' function is calling it.
     In this case, it may process a local variables list at the end of
     the file and in the `-*-' line.  The variable
     `enable-local-variables' controls whether to do so.

     If you run `normal-mode' interactively, the argument FIND-FILE is
     normally `nil'.  In this case, `normal-mode' unconditionally
     processes any local variables list.  *Note Local Variables in
     Files: (xemacs)File variables, for the syntax of the local
     variables section of a file.

     `normal-mode' uses `condition-case' around the call to the major
     mode function, so errors are caught and reported as a `File mode
     specification error',  followed by the original error message.

 -- User Option: enable-local-variables
     This variable controls processing of local variables lists in files
     being visited.  A value of `t' means process the local variables
     lists unconditionally; `nil' means ignore them; anything else means
     ask the user what to do for each file.  The default value is `t'.

 -- Variable: ignored-local-variables
     This variable holds a list of variables that should not be set by
     a local variables list.  Any value specified for one of these
     variables is ignored.

   In addition to this list, any variable whose name has a non-`nil'
`risky-local-variable' property is also ignored.

 -- User Option: enable-local-eval
     This variable controls processing of `Eval:' in local variables
     lists in files being visited.  A value of `t' means process them
     unconditionally; `nil' means ignore them; anything else means ask
     the user what to do for each file.  The default value is `maybe'.

 -- Function: set-auto-mode
     This function selects the major mode that is appropriate for the
     current buffer.  It may base its decision on the value of the `-*-'
     line, on the visited file name (using `auto-mode-alist'), or on the
     value of a local variable.  However, this function does not look
     for the `mode:' local variable near the end of a file; the
     `hack-local-variables' function does that.  *Note How Major Modes
     are Chosen: (xemacs)Choosing Modes.

 -- User Option: default-major-mode
     This variable holds the default major mode for new buffers.  The
     standard value is `fundamental-mode'.

     If the value of `default-major-mode' is `nil', XEmacs uses the
     (previously) current buffer's major mode for the major mode of a
     new buffer.  However, if the major mode symbol has a `mode-class'
     property with value `special', then it is not used for new buffers;
     Fundamental mode is used instead.  The modes that have this
     property are those such as Dired and Rmail that are useful only
     with text that has been specially prepared.

 -- Function: set-buffer-major-mode buffer
     This function sets the major mode of BUFFER to the value of
     `default-major-mode'.  If that variable is `nil', it uses the
     current buffer's major mode (if that is suitable).

     The low-level primitives for creating buffers do not use this
     function, but medium-level commands such as `switch-to-buffer' and
     `find-file-noselect' use it whenever they create buffers.

 -- Variable: initial-major-mode
     The value of this variable determines the major mode of the initial
     `*scratch*' buffer.  The value should be a symbol that is a major
     mode command name.  The default value is `lisp-interaction-mode'.

 -- Variable: auto-mode-alist
     This variable contains an association list of file name patterns
     (regular expressions; *note Regular Expressions::) and
     corresponding major mode functions.  Usually, the file name
     patterns test for suffixes, such as `.el' and `.c', but this need
     not be the case.  An ordinary element of the alist looks like
     `(REGEXP .  MODE-FUNCTION)'.

     For example,

          (("^/tmp/fol/" . text-mode)
           ("\\.texinfo\\'" . texinfo-mode)
           ("\\.texi\\'" . texinfo-mode)
           ("\\.el\\'" . emacs-lisp-mode)
           ("\\.c\\'" . c-mode)
           ("\\.h\\'" . c-mode)
           ...)

     When you visit a file whose expanded file name (*note File Name
     Expansion::) matches a REGEXP, `set-auto-mode' calls the
     corresponding MODE-FUNCTION.  This feature enables XEmacs to select
     the proper major mode for most files.

     If an element of `auto-mode-alist' has the form `(REGEXP FUNCTION
     t)', then after calling FUNCTION, XEmacs searches
     `auto-mode-alist' again for a match against the portion of the file
     name that did not match before.

     This match-again feature is useful for uncompression packages: an
     entry of the form `("\\.gz\\'" . FUNCTION)' can uncompress the file
     and then put the uncompressed file in the proper mode according to
     the name sans `.gz'.

     Here is an example of how to prepend several pattern pairs to
     `auto-mode-alist'.  (You might use this sort of expression in your
     `.emacs' file.)

          (setq auto-mode-alist
            (append
             ;; File name starts with a dot.
             '(("/\\.[^/]*\\'" . fundamental-mode)
               ;; File name has no dot.
               ("[^\\./]*\\'" . fundamental-mode)
               ;; File name ends in `.C'.
               ("\\.C\\'" . c++-mode))
             auto-mode-alist))

 -- Variable: interpreter-mode-alist
     This variable specifies major modes to use for scripts that
     specify a command interpreter in an `#!' line.  Its value is a
     list of elements of the form `(INTERPRETER . MODE)'; for example,
     `("perl" . perl-mode)' is one element present by default.  The
     element says to use mode MODE if the file specifies INTERPRETER.

     This variable is applicable only when the `auto-mode-alist' does
     not indicate which major mode to use.

 -- Function: hack-local-variables &optional force
     This function parses, and binds or evaluates as appropriate, any
     local variables for the current buffer.

     The handling of `enable-local-variables' documented for
     `normal-mode' actually takes place here.  The argument FORCE
     usually comes from the argument FIND-FILE given to `normal-mode'.

\1f
File: lispref.info,  Node: Mode Help,  Next: Derived Modes,  Prev: Auto Major Mode,  Up: Major Modes

33.1.4 Getting Help about a Major Mode
--------------------------------------

The `describe-mode' function is used to provide information about major
modes.  It is normally called with `C-h m'.  The `describe-mode'
function uses the value of `major-mode', which is why every major mode
function needs to set the `major-mode' variable.

 -- Command: describe-mode
     This function displays the documentation of the current major mode.

     The `describe-mode' function calls the `documentation' function
     using the value of `major-mode' as an argument.  Thus, it displays
     the documentation string of the major mode function.  (*Note
     Accessing Documentation::.)

 -- Variable: major-mode
     This variable holds the symbol for the current buffer's major mode.
     This symbol should have a function definition that is the command
     to switch to that major mode.  The `describe-mode' function uses
     the documentation string of the function as the documentation of
     the major mode.

\1f
File: lispref.info,  Node: Derived Modes,  Prev: Mode Help,  Up: Major Modes

33.1.5 Defining Derived Modes
-----------------------------

It's often useful to define a new major mode in terms of an existing
one.  An easy way to do this is to use `define-derived-mode'.

 -- Macro: define-derived-mode variant parent name docstring body...
     This construct defines VARIANT as a major mode command, using NAME
     as the string form of the mode name.

     The new command VARIANT is defined to call the function PARENT,
     then override certain aspects of that parent mode:

        * The new mode has its own keymap, named `VARIANT-map'.
          `define-derived-mode' initializes this map to inherit from
          `PARENT-map', if it is not already set.

        * The new mode has its own syntax table, kept in the variable
          `VARIANT-syntax-table'.  `define-derived-mode' initializes
          this variable by copying `PARENT-syntax-table', if it is not
          already set.

        * The new mode has its own abbrev table, kept in the variable
          `VARIANT-abbrev-table'.  `define-derived-mode' initializes
          this variable by copying `PARENT-abbrev-table', if it is not
          already set.

        * The new mode has its own mode hook, `VARIANT-hook', which it
          runs in standard fashion as the very last thing that it does.
          (The new mode also runs the mode hook of PARENT as part of
          calling PARENT.)

     In addition, you can specify how to override other aspects of
     PARENT with BODY.  The command VARIANT evaluates the forms in BODY
     after setting up all its usual overrides, just before running
     `VARIANT-hook'.

     The argument DOCSTRING specifies the documentation string for the
     new mode.  If you omit DOCSTRING, `define-derived-mode' generates
     a documentation string.

     Here is a hypothetical example:

          (define-derived-mode hypertext-mode
            text-mode "Hypertext"
            "Major mode for hypertext.
          \\{hypertext-mode-map}"
            (setq case-fold-search nil))

          (define-key hypertext-mode-map
            [down-mouse-3] 'do-hyper-link)

     Do not write an `interactive' spec in the definition;
     `define-derived-mode' does that automatically.

\1f
File: lispref.info,  Node: Minor Modes,  Next: Modeline Format,  Prev: Major Modes,  Up: Modes

33.2 Minor Modes
================

A "minor mode" provides features that users may enable or disable
independently of the choice of major mode.  Minor modes can be enabled
individually or in combination.  Minor modes would be better named
"Generally available, optional feature modes" except that such a name is
unwieldy.

   A minor mode is not usually a modification of single major mode.  For
example, Auto Fill mode may be used in any major mode that permits text
insertion.  To be general, a minor mode must be effectively independent
of the things major modes do.

   A minor mode is often much more difficult to implement than a major
mode.  One reason is that you should be able to activate and deactivate
minor modes in any order.  A minor mode should be able to have its
desired effect regardless of the major mode and regardless of the other
minor modes in effect.

   Often the biggest problem in implementing a minor mode is finding a
way to insert the necessary hook into the rest of XEmacs.  Minor mode
keymaps make this easier than it used to be.

* Menu:

* Minor Mode Conventions::      Tips for writing a minor mode.
* Keymaps and Minor Modes::     How a minor mode can have its own keymap.

\1f
File: lispref.info,  Node: Minor Mode Conventions,  Next: Keymaps and Minor Modes,  Up: Minor Modes

33.2.1 Conventions for Writing Minor Modes
------------------------------------------

There are conventions for writing minor modes just as there are for
major modes.  Several of the major mode conventions apply to minor
modes as well: those regarding the name of the mode initialization
function, the names of global symbols, and the use of keymaps and other
tables.

   In addition, there are several conventions that are specific to
minor modes.

   * Make a variable whose name ends in `-mode' to represent the minor
     mode.  Its value should enable or disable the mode (`nil' to
     disable; anything else to enable.)  We call this the "mode
     variable".

     This variable is used in conjunction with the `minor-mode-alist' to
     display the minor mode name in the modeline.  It can also enable
     or disable a minor mode keymap.  Individual commands or hooks can
     also check the variable's value.

     If you want the minor mode to be enabled separately in each buffer,
     make the variable buffer-local.

   * Define a command whose name is the same as the mode variable.  Its
     job is to enable and disable the mode by setting the variable.

     The command should accept one optional argument.  If the argument
     is `nil', it should toggle the mode (turn it on if it is off, and
     off if it is on).  Otherwise, it should turn the mode on if the
     argument is a positive integer, a symbol other than `nil' or `-',
     or a list whose CAR is such an integer or symbol; it should turn
     the mode off otherwise.

     Here is an example taken from the definition of
     `transient-mark-mode'.  It shows the use of `transient-mark-mode'
     as a variable that enables or disables the mode's behavior, and
     also shows the proper way to toggle, enable or disable the minor
     mode based on the raw prefix argument value.

          (setq transient-mark-mode
                (if (null arg) (not transient-mark-mode)
                  (> (prefix-numeric-value arg) 0)))

   * Add an element to `minor-mode-alist' for each minor mode (*note
     Modeline Variables::).  This element should be a list of the
     following form:

          (MODE-VARIABLE STRING)

     Here MODE-VARIABLE is the variable that controls enabling of the
     minor mode, and STRING is a short string, starting with a space,
     to represent the mode in the modeline.  These strings must be
     short so that there is room for several of them at once.

     When you add an element to `minor-mode-alist', use `assq' to check
     for an existing element, to avoid duplication.  For example:

          (or (assq 'leif-mode minor-mode-alist)
              (setq minor-mode-alist
                    (cons '(leif-mode " Leif") minor-mode-alist)))

\1f
File: lispref.info,  Node: Keymaps and Minor Modes,  Prev: Minor Mode Conventions,  Up: Minor Modes

33.2.2 Keymaps and Minor Modes
------------------------------

Each minor mode can have its own keymap, which is active when the mode
is enabled.  To set up a keymap for a minor mode, add an element to the
alist `minor-mode-map-alist'.  *Note Active Keymaps::.

   One use of minor mode keymaps is to modify the behavior of certain
self-inserting characters so that they do something else as well as
self-insert.  In general, this is the only way to do that, since the
facilities for customizing `self-insert-command' are limited to special
cases (designed for abbrevs and Auto Fill mode).  (Do not try
substituting your own definition of `self-insert-command' for the
standard one.  The editor command loop handles this function specially.)

\1f
File: lispref.info,  Node: Modeline Format,  Next: Hooks,  Prev: Minor Modes,  Up: Modes

33.3 Modeline Format
====================

Each Emacs window (aside from minibuffer windows) includes a modeline,
which displays status information about the buffer displayed in the
window.  The modeline contains information about the buffer, such as its
name, associated file, depth of recursive editing, and the major and
minor modes.

   This section describes how the contents of the modeline are
controlled.  It is in the chapter on modes because much of the
information displayed in the modeline relates to the enabled major and
minor modes.

   `modeline-format' is a buffer-local variable that holds a template
used to display the modeline of the current buffer.  All windows for
the same buffer use the same `modeline-format' and their modelines
appear the same (except for scrolling percentages and line numbers).

   The modeline of a window is normally updated whenever a different
buffer is shown in the window, or when the buffer's modified-status
changes from `nil' to `t' or vice-versa.  If you modify any of the
variables referenced by `modeline-format' (*note Modeline Variables::),
you may want to force an update of the modeline so as to display the
new information.

 -- Function: redraw-modeline &optional all
     Force redisplay of the current buffer's modeline.  If ALL is
     non-`nil', then force redisplay of all modelines.

   The modeline is usually displayed in inverse video.  This is
controlled using the `modeline' face.  *Note Faces::.

* Menu:

* Modeline Data::         The data structure that controls the modeline.
* Modeline Variables::    Variables used in that data structure.
* %-Constructs::          Putting information into a modeline.

\1f
File: lispref.info,  Node: Modeline Data,  Next: Modeline Variables,  Up: Modeline Format

33.3.1 The Data Structure of the Modeline
-----------------------------------------

The modeline contents are controlled by a data structure of lists,
strings, symbols, and numbers kept in the buffer-local variable
`modeline-format'.  The data structure is called a "modeline
construct", and it is built in recursive fashion out of simpler modeline
constructs.  The same data structure is used for constructing frame
titles (*note Frame Titles::).

 -- Variable: modeline-format
     The value of this variable is a modeline construct with overall
     responsibility for the modeline format.  The value of this variable
     controls which other variables are used to form the modeline text,
     and where they appear.

   A modeline construct may be as simple as a fixed string of text, but
it usually specifies how to use other variables to construct the text.
Many of these variables are themselves defined to have modeline
constructs as their values.

   The default value of `modeline-format' incorporates the values of
variables such as `mode-name' and `minor-mode-alist'.  Because of this,
very few modes need to alter `modeline-format'.  For most purposes, it
is sufficient to alter the variables referenced by `modeline-format'.

   A modeline construct may be a string, symbol, glyph, generic
specifier, list or cons cell.

`STRING'
     A string as a modeline construct is displayed verbatim in the mode
     line except for "`%'-constructs".  Decimal digits after the `%'
     specify the field width for space filling on the right (i.e., the
     data is left justified).  *Note %-Constructs::.

`SYMBOL'
     A symbol as a modeline construct stands for its value.  The value
     of SYMBOL is processed as a modeline construct, in place of
     SYMBOL.  However, the symbols `t' and `nil' are ignored; so is any
     symbol whose value is void.

     There is one exception: if the value of SYMBOL is a string, it is
     displayed verbatim: the `%'-constructs are not recognized.

`GLYPH'
     A glyph is displayed as is.

`GENERIC-SPECIFIER'
     A GENERIC-SPECIFIER (i.e. a specifier of type `generic') stands
     for its instance.  The instance of GENERIC-SPECIFIER is computed
     in the current window using the equivalent of `specifier-instance'
     and the value is processed.

`(STRING REST...) or (LIST REST...)'
     A list whose first element is a string or list means to process
     all the elements recursively and concatenate the results.  This is
     the most common form of mode line construct.

`(SYMBOL THEN ELSE)'
     A list whose first element is a symbol is a conditional.  Its
     meaning depends on the value of SYMBOL.  If the value is non-`nil',
     the second element, THEN, is processed recursively as a modeline
     element.  But if the value of SYMBOL is `nil', the third element,
     ELSE, is processed recursively.  You may omit ELSE; then the mode
     line element displays nothing if the value of SYMBOL is `nil'.

`(WIDTH REST...)'
     A list whose first element is an integer specifies truncation or
     padding of the results of REST.  The remaining elements REST are
     processed recursively as modeline constructs and concatenated
     together.  Then the result is space filled (if WIDTH is positive)
     or truncated (to -WIDTH columns, if WIDTH is negative) on the
     right.

     For example, the usual way to show what percentage of a buffer is
     above the top of the window is to use a list like this: `(-3
     "%p")'.

`(EXTENT REST...)'
     A list whose car is an extent means the cdr of the list is
     processed normally but the results are displayed using the face of
     the extent, and mouse clicks over this section are processed using
     the keymap of the extent. (In addition, if the extent has a
     help-echo property, that string will be echoed when the mouse
     moves over this section.) If extents are nested, all keymaps are
     properly consulted when processing mouse clicks, but multiple
     faces are not correctly merged (only the first face is used), and
     lists of faces are not correctly handled.

   If you do alter `modeline-format' itself, the new value should use
the same variables that appear in the default value (*note Modeline
Variables::), rather than duplicating their contents or displaying the
information in another fashion.  This way, customizations made by the
user or by Lisp programs (such as `display-time' and major modes) via
changes to those variables remain effective.

   Here is an example of a `modeline-format' that might be useful for
`shell-mode', since it contains the hostname and default directory.

     (setq modeline-format
       (list ""
        'modeline-modified
        "%b--"
        (getenv "HOST")      ; One element is not constant.
        ":"
        'default-directory
        "   "
        'global-mode-string
        "   %[("
        'mode-name
        'modeline-process
        'minor-mode-alist
        "%n"
        ")%]----"
        '(line-number-mode "L%l--")
        '(-3 . "%p")
        "-%-"))

\1f
File: lispref.info,  Node: Modeline Variables,  Next: %-Constructs,  Prev: Modeline Data,  Up: Modeline Format

33.3.2 Variables Used in the Modeline
-------------------------------------

This section describes variables incorporated by the standard value of
`modeline-format' into the text of the mode line.  There is nothing
inherently special about these variables; any other variables could
have the same effects on the modeline if `modeline-format' were changed
to use them.

 -- Variable: modeline-modified
     This variable holds the value of the modeline construct that
     displays whether the current buffer is modified.

     The default value of `modeline-modified' is `("--%1*%1+-")'.  This
     means that the modeline displays `--**-' if the buffer is
     modified, `-----' if the buffer is not modified, `--%%-' if the
     buffer is read only, and `--%*--' if the buffer is read only and
     modified.

     Changing this variable does not force an update of the modeline.

 -- Variable: modeline-buffer-identification
     This variable identifies the buffer being displayed in the window.
     Its default value is `("%F: %17b")', which means that it usually
     displays `Emacs:' followed by seventeen characters of the buffer
     name.  (In a terminal frame, it displays the frame name instead of
     `Emacs'; this has the effect of showing the frame number.)  You may
     want to change this in modes such as Rmail that do not behave like
     a "normal" XEmacs.

 -- Variable: global-mode-string
     This variable holds a modeline spec that appears in the mode line
     by default, just after the buffer name.  The command `display-time'
     sets `global-mode-string' to refer to the variable
     `display-time-string', which holds a string containing the time and
     load information.

     The `%M' construct substitutes the value of `global-mode-string',
     but this is obsolete, since the variable is included directly in
     the modeline.

 -- Variable: mode-name
     This buffer-local variable holds the "pretty" name of the current
     buffer's major mode.  Each major mode should set this variable so
     that the mode name will appear in the modeline.

 -- Variable: minor-mode-alist
     This variable holds an association list whose elements specify how
     the modeline should indicate that a minor mode is active.  Each
     element of the `minor-mode-alist' should be a two-element list:

          (MINOR-MODE-VARIABLE MODELINE-STRING)

     More generally, MODELINE-STRING can be any mode line spec.  It
     appears in the mode line when the value of MINOR-MODE-VARIABLE is
     non-`nil', and not otherwise.  These strings should begin with
     spaces so that they don't run together.  Conventionally, the
     MINOR-MODE-VARIABLE for a specific mode is set to a non-`nil'
     value when that minor mode is activated.

     The default value of `minor-mode-alist' is:

          minor-mode-alist
          => ((vc-mode vc-mode)
              (abbrev-mode " Abbrev")
              (overwrite-mode overwrite-mode)
              (auto-fill-function " Fill")
              (defining-kbd-macro " Def")
              (isearch-mode isearch-mode))

     `minor-mode-alist' is not buffer-local.  The variables mentioned
     in the alist should be buffer-local if the minor mode can be
     enabled separately in each buffer.

 -- Variable: modeline-process
     This buffer-local variable contains the modeline information on
     process status in modes used for communicating with subprocesses.
     It is displayed immediately following the major mode name, with no
     intervening space.  For example, its value in the `*shell*' buffer
     is `(": %s")', which allows the shell to display its status along
     with the major mode as: `(Shell: run)'.  Normally this variable is
     `nil'.

 -- Variable: default-modeline-format
     This variable holds the default `modeline-format' for buffers that
     do not override it.  This is the same as `(default-value
     'modeline-format)'.

     The default value of `default-modeline-format' is:

          (""
           modeline-modified
           modeline-buffer-identification
           "   "
           global-mode-string
           "   %[("
           mode-name
           modeline-process
           minor-mode-alist
           "%n"
           ")%]----"
           (line-number-mode "L%l--")
           (-3 . "%p")
           "-%-")

 -- Variable: vc-mode
     The variable `vc-mode', local in each buffer, records whether the
     buffer's visited file is maintained with version control, and, if
     so, which kind.  Its value is `nil' for no version control, or a
     string that appears in the mode line.

\1f
File: lispref.info,  Node: %-Constructs,  Prev: Modeline Variables,  Up: Modeline Format

33.3.3 `%'-Constructs in the ModeLine
-------------------------------------

The following table lists the recognized `%'-constructs and what they
mean.  In any construct except `%%', you can add a decimal integer
after the `%' to specify how many characters to display.

`%b'
     The current buffer name, obtained with the `buffer-name' function.
     *Note Buffer Names::.

`%f'
     The visited file name, obtained with the `buffer-file-name'
     function.  *Note Buffer File Name::.

`%F'
     The name of the selected frame.

`%c'
     The current column number of point.

`%l'
     The current line number of point.

`%*'
     `%' if the buffer is read only (see `buffer-read-only');
     `*' if the buffer is modified (see `buffer-modified-p');
     `-' otherwise.  *Note Buffer Modification::.

`%+'
     `*' if the buffer is modified (see `buffer-modified-p');
     `%' if the buffer is read only (see `buffer-read-only');
     `-' otherwise.  This differs from `%*' only for a modified
     read-only buffer.  *Note Buffer Modification::.

`%&'
     `*' if the buffer is modified, and `-' otherwise.

`%s'
     The status of the subprocess belonging to the current buffer,
     obtained with `process-status'.  *Note Process Information::.

`%l'
     The current line number.

`%S'
     The name of the selected frame; this is only meaningful under the
     X Window System.  *Note Frame Name::.

`%t'
     Whether the visited file is a text file or a binary file.  (This
     is a meaningful distinction only on certain operating systems.)

`%p'
     The percentage of the buffer text above the *top* of window, or
     `Top', `Bottom' or `All'.

`%P'
     The percentage of the buffer text that is above the *bottom* of
     the window (which includes the text visible in the window, as well
     as the text above the top), plus `Top' if the top of the buffer is
     visible on screen; or `Bottom' or `All'.

`%n'
     `Narrow' when narrowing is in effect; nothing otherwise (see
     `narrow-to-region' in *Note Narrowing::).

`%C'
     Under XEmacs/mule, the mnemonic for `buffer-file-coding-system'.

`%['
     An indication of the depth of recursive editing levels (not
     counting minibuffer levels): one `[' for each editing level.
     *Note Recursive Editing::.

`%]'
     One `]' for each recursive editing level (not counting minibuffer
     levels).

`%%'
     The character `%'--this is how to include a literal `%' in a
     string in which `%'-constructs are allowed.

`%-'
     Dashes sufficient to fill the remainder of the modeline.

   The following two `%'-constructs are still supported, but they are
obsolete, since you can get the same results with the variables
`mode-name' and `global-mode-string'.

`%m'
     The value of `mode-name'.

`%M'
     The value of `global-mode-string'.  Currently, only `display-time'
     modifies the value of `global-mode-string'.

\1f
File: lispref.info,  Node: Hooks,  Prev: Modeline Format,  Up: Modes

33.4 Hooks
==========

A "hook" is a variable where you can store a function or functions to
be called on a particular occasion by an existing program.  XEmacs
provides hooks for the sake of customization.  Most often, hooks are set
up in the `.emacs' file, but Lisp programs can set them also.  *Note
Standard Hooks::, for a list of standard hook variables.

   Most of the hooks in XEmacs are "normal hooks".  These variables
contain lists of functions to be called with no arguments.  The reason
most hooks are normal hooks is so that you can use them in a uniform
way.  You can usually tell when a hook is a normal hook, because its
name ends in `-hook'.

   The recommended way to add a hook function to a normal hook is by
calling `add-hook' (see below).  The hook functions may be any of the
valid kinds of functions that `funcall' accepts (*note What Is a
Function::).  Most normal hook variables are initially void; `add-hook'
knows how to deal with this.

   As for abnormal hooks, those whose names end in `-function' have a
value that is a single function.  Those whose names end in `-hooks'
have a value that is a list of functions.  Any hook that is abnormal is
abnormal because a normal hook won't do the job; either the functions
are called with arguments, or their values are meaningful.  The name
shows you that the hook is abnormal and that you should look at its
documentation string to see how to use it properly.

   Major mode functions are supposed to run a hook called the "mode
hook" as the last step of initialization.  This makes it easy for a user
to customize the behavior of the mode, by overriding the local variable
assignments already made by the mode.  But hooks are used in other
contexts too.  For example, the hook `suspend-hook' runs just before
XEmacs suspends itself (*note Suspending XEmacs::).

   Here's an expression that uses a mode hook to turn on Auto Fill mode
when in Lisp Interaction mode:

     (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)

   The next example shows how to use a hook to customize the way XEmacs
formats C code.  (People often have strong personal preferences for one
format or another.)  Here the hook function is an anonymous lambda
expression.

     (add-hook 'c-mode-hook
       (function (lambda ()
                   (setq c-indent-level 4
                         c-argdecl-indent 0
                         c-label-offset -4
                         c-continued-statement-indent 0
                         c-brace-offset 0
                         comment-column 40))))

     (setq c++-mode-hook c-mode-hook)

   The final example shows how the appearance of the modeline can be
modified for a particular class of buffers only.

     (add-hook 'text-mode-hook
       (function (lambda ()
                   (setq modeline-format
                         '(modeline-modified
                           "Emacs: %14b"
                           "  "
                           default-directory
                           " "
                           global-mode-string
                           "%[("
                           mode-name
                           minor-mode-alist
                           "%n"
                           modeline-process
                           ") %]---"
                           (-3 . "%p")
                           "-%-")))))

   At the appropriate time, XEmacs uses the `run-hooks' function to run
particular hooks.  This function calls the hook functions you have
added with `add-hooks'.

 -- Function: run-hooks &rest hookvar
     This function takes one or more hook variable names as arguments,
     and runs each hook in turn.  Each HOOKVAR argument should be a
     symbol that is a hook variable.  These arguments are processed in
     the order specified.

     If a hook variable has a non-`nil' value, that value may be a
     function or a list of functions.  If the value is a function
     (either a lambda expression or a symbol with a function
     definition), it is called.  If it is a list, the elements are
     called, in order.  The hook functions are called with no arguments.

     For example, here's how `emacs-lisp-mode' runs its mode hook:

          (run-hooks 'emacs-lisp-mode-hook)

 -- Function: run-mode-hooks &rest hookvars
     Like `run-hooks', but is affected by the `delay-mode-hooks' macro.

 -- Macro: delay-mode-hooks body...
     This macro executes the BODY forms but defers all calls to
     `run-mode-hooks' within them until the end of BODY.  This macro
     enables a derived mode to arrange not to run its parent modes'
     mode hooks until the end.

 -- Function: run-hook-with-args hook &rest args
     This function is the way to run an abnormal hook and always call
     all of the hook functions.  It calls each of the hook functions
     one by one, passing each of them the arguments ARGS.

 -- Function: run-hook-with-args-until-failure hook &rest args
     This function is the way to run an abnormal hook until one of the
     hook functions fails.  It calls each of the hook functions,
     passing each of them the arguments ARGS, until some hook function
     returns `nil'.  It then stops and returns `nil'.  If none of the
     hook functions return `nil', it returns a non-`nil' value.

 -- Function: run-hook-with-args-until-success hook &rest args
     This function is the way to run an abnormal hook until a hook
     function succeeds.  It calls each of the hook functions, passing
     each of them the arguments ARGS, until some hook function returns
     non-`nil'.  Then it stops, and returns whatever was returned by
     the last hook function that was called.  If all hook functions
     return `nil', it returns `nil' as well.

 -- Function: add-hook hook function &optional append local
     This function is the handy way to add function FUNCTION to hook
     variable HOOK.  The argument FUNCTION may be any valid Lisp
     function with the proper number of arguments.  For example,

          (add-hook 'text-mode-hook 'my-text-hook-function)

     adds `my-text-hook-function' to the hook called `text-mode-hook'.

     You can use `add-hook' for abnormal hooks as well as for normal
     hooks.

     It is best to design your hook functions so that the order in
     which they are executed does not matter.  Any dependence on the
     order is "asking for trouble."  However, the order is predictable:
     normally, FUNCTION goes at the front of the hook list, so it will
     be executed first (barring another `add-hook' call).

     If the optional argument APPEND is non-`nil', the new hook
     function goes at the end of the hook list and will be executed
     last.

     If LOCAL is non-`nil', that says to make the new hook function
     local to the current buffer.  Before you can do this, you must
     make the hook itself buffer-local by calling `make-local-hook'
     (*not* `make-local-variable').  If the hook itself is not
     buffer-local, then the value of LOCAL makes no difference--the
     hook function is always global.

 -- Function: remove-hook hook function &optional local
     This function removes FUNCTION from the hook variable HOOK.

     If LOCAL is non-`nil', that says to remove FUNCTION from the local
     hook list instead of from the global hook list.  If the hook
     itself is not buffer-local, then the value of LOCAL makes no
     difference.

 -- Function: make-local-hook hook
     This function makes the hook variable HOOK local to the current
     buffer.  When a hook variable is local, it can have local and
     global hook functions, and `run-hooks' runs all of them.

     This function works by making `t' an element of the buffer-local
     value.  That serves as a flag to use the hook functions in the
     default value of the hook variable as well as those in the local
     value.  Since `run-hooks' understands this flag, `make-local-hook'
     works with all normal hooks.  It works for only some non-normal
     hooks--those whose callers have been updated to understand this
     meaning of `t'.

     Do not use `make-local-variable' directly for hook variables; it is
     not sufficient.

\1f
File: lispref.info,  Node: Documentation,  Next: Files,  Prev: Modes,  Up: Top

34 Documentation
****************

XEmacs Lisp has convenient on-line help facilities, most of which
derive their information from the documentation strings associated with
functions and variables.  This chapter describes how to write good
documentation strings for your Lisp programs, as well as how to write
programs to access documentation.

   Note that the documentation strings for XEmacs are not the same thing
as the XEmacs manual.  Manuals have their own source files, written in
the Texinfo language; documentation strings are specified in the
definitions of the functions and variables they apply to.  A collection
of documentation strings is not sufficient as a manual because a good
manual is not organized in that fashion; it is organized in terms of
topics of discussion.

* Menu:

* Documentation Basics::      Good style for doc strings.
                                Where to put them.  How XEmacs stores them.
* Accessing Documentation::   How Lisp programs can access doc strings.
* Keys in Documentation::     Substituting current key bindings.
* Describing Characters::     Making printable descriptions of
                                non-printing characters and key sequences.
* Help Functions::            Subroutines used by XEmacs help facilities.
* Obsoleteness::              Upgrading Lisp functionality over time.

\1f
File: lispref.info,  Node: Documentation Basics,  Next: Accessing Documentation,  Up: Documentation

34.1 Documentation Basics
=========================

A documentation string is written using the Lisp syntax for strings,
with double-quote characters surrounding the text of the string.  This
is because it really is a Lisp string object.  The string serves as
documentation when it is written in the proper place in the definition
of a function or variable.  In a function definition, the documentation
string follows the argument list.  In a variable definition, the
documentation string follows the initial value of the variable.

   When you write a documentation string, make the first line a complete
sentence (or two complete sentences) since some commands, such as
`apropos', show only the first line of a multi-line documentation
string.  Also, you should not indent the second line of a documentation
string, if you have one, because that looks odd when you use `C-h f'
(`describe-function') or `C-h v' (`describe-variable').  *Note
Documentation Tips::.

   Documentation strings may contain several special substrings, which
stand for key bindings to be looked up in the current keymaps when the
documentation is displayed.  This allows documentation strings to refer
to the keys for related commands and be accurate even when a user
rearranges the key bindings.  (*Note Accessing Documentation::.)

   Within the Lisp world, a documentation string is accessible through
the function or variable that it describes:

   * The documentation for a function is stored in the function
     definition itself (*note Lambda Expressions::).  The function
     `documentation' knows how to extract it.

   * The documentation for a variable is stored in the variable's
     property list under the property name `variable-documentation'.
     The function `documentation-property' knows how to extract it.

   To save space, the documentation for preloaded functions and
variables (including primitive functions and autoloaded functions) is
stored in the "internal doc file" `DOC'.  The documentation for
functions and variables loaded during the XEmacs session from
byte-compiled files is stored in those very same byte-compiled files
(*note Docs and Compilation::).

   XEmacs does not keep documentation strings in memory unless
necessary.  Instead, XEmacs maintains, for preloaded symbols, an
integer offset into the internal doc file, and for symbols loaded from
byte-compiled files, a list containing the filename of the
byte-compiled file and an integer offset, in place of the documentation
string.  The functions `documentation' and `documentation-property' use
that information to read the documentation from the appropriate file;
this is transparent to the user.

   For information on the uses of documentation strings, see *Note
Help: (xemacs)Help.

   The `emacs/lib-src' directory contains two utilities that you can
use to print nice-looking hardcopy for the file
`emacs/etc/DOC-VERSION'.  These are `sorted-doc.c' and `digest-doc.c'.

\1f
File: lispref.info,  Node: Accessing Documentation,  Next: Keys in Documentation,  Prev: Documentation Basics,  Up: Documentation

34.2 Access to Documentation Strings
====================================

 -- Function: documentation-property symbol property &optional verbatim
     This function returns the documentation string that is recorded in
     SYMBOL's property list under property PROPERTY.  It retrieves the
     text from a file if necessary, and runs `substitute-command-keys'
     to substitute actual key bindings.  (This substitution is not done
     if VERBATIM is non-`nil'; the VERBATIM argument exists only as of
     Emacs 19.)

          (documentation-property 'command-line-processed
             'variable-documentation)
               => "t once command line has been processed"
          (symbol-plist 'command-line-processed)
               => (variable-documentation 188902)

 -- Function: documentation function &optional verbatim
     This function returns the documentation string of FUNCTION.  It
     reads the text from a file if necessary.  Then (unless VERBATIM is
     non-`nil') it calls `substitute-command-keys', to return a value
     containing the actual (current) key bindings.

     The function `documentation' signals a `void-function' error if
     FUNCTION has no function definition.  However, it is ok if the
     function definition has no documentation string.  In that case,
     `documentation' returns `nil'.

   Here is an example of using the two functions, `documentation' and
`documentation-property', to display the documentation strings for
several symbols in a `*Help*' buffer.

     (defun describe-symbols (pattern)
       "Describe the XEmacs Lisp symbols matching PATTERN.
     All symbols that have PATTERN in their name are described
     in the `*Help*' buffer."
       (interactive "sDescribe symbols matching: ")
       (let ((describe-func
              (function
               (lambda (s)
                 ;; Print description of symbol.
                 (if (fboundp s)             ; It is a function.
                     (princ
                      (format "%s\t%s\n%s\n\n" s
                        (if (commandp s)
                            (let ((keys (where-is-internal s)))
                              (if keys
                                  (concat
                                   "Keys: "
                                   (mapconcat 'key-description
                                              keys " "))
                                "Keys: none"))
                          "Function")
                        (or (documentation s)
                            "not documented"))))

                 (if (boundp s)              ; It is a variable.
                     (princ
                      (format "%s\t%s\n%s\n\n" s
                        (if (user-variable-p s)
                            "Option " "Variable")
                        (or (documentation-property
                              s 'variable-documentation)
                            "not documented")))))))
             sym-list)

         ;; Build a list of symbols that match pattern.
         (mapatoms (function
                    (lambda (sym)
                      (if (string-match pattern (symbol-name sym))
                          (setq sym-list (cons sym sym-list))))))

         ;; Display the data.
         (with-output-to-temp-buffer "*Help*"
           (mapcar describe-func (sort sym-list 'string<))
           (print-help-return-message))))

   The `describe-symbols' function works like `apropos', but provides
more information.

     (describe-symbols "goal")

     ---------- Buffer: *Help* ----------
     goal-column     Option
     *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.

     set-goal-column Command: C-x C-n
     Set the current horizontal position as a goal for C-n and C-p.
     Those commands will move to this position in the line moved to
     rather than trying to keep the same horizontal position.
     With a non-`nil' argument, clears out the goal column
     so that C-n and C-p resume vertical motion.
     The goal column is stored in the variable `goal-column'.

     temporary-goal-column   Variable
     Current goal column for vertical motion.
     It is the column where point was
     at the start of current run of vertical motion commands.
     When the `track-eol' feature is doing its job, the value is 9999.
     ---------- Buffer: *Help* ----------

 -- Function: Snarf-documentation filename
     This function is used only during XEmacs initialization, just
     before the runnable XEmacs is dumped.  It finds the file offsets
     of the documentation strings stored in the file FILENAME, and
     records them in the in-core function definitions and variable
     property lists in place of the actual strings.  *Note Building
     XEmacs::.

     XEmacs finds the file FILENAME in the `lib-src' directory.  When
     the dumped XEmacs is later executed, the same file is found in the
     directory `doc-directory'.  The usual value for FILENAME is `DOC',
     but this can be changed by modifying the variable
     `internal-doc-file-name'.

 -- Variable: internal-doc-file-name
     This variable holds the name of the file containing documentation
     strings of built-in symbols, usually `DOC'.  The full pathname of
     the internal doc file is `(concat doc-directory
     internal-doc-file-name)'.

 -- Variable: doc-directory
     This variable holds the name of the directory which contains the
     "internal doc file" that contains documentation strings for
     built-in and preloaded functions and variables.

     In most cases, this is the same as `exec-directory'.  They may be
     different when you run XEmacs from the directory where you built
     it, without actually installing it.  See `exec-directory' in *Note
     Help Functions::.

     In older Emacs versions, `exec-directory' was used for this.

 -- Variable: data-directory
     This variable holds the name of the directory in which XEmacs finds
     certain system independent documentation and text files that come
     with XEmacs.  In older Emacs versions, `exec-directory' was used
     for this.

\1f
File: lispref.info,  Node: Keys in Documentation,  Next: Describing Characters,  Prev: Accessing Documentation,  Up: Documentation

34.3 Substituting Key Bindings in Documentation
===============================================

When documentation strings refer to key sequences, they should use the
current, actual key bindings.  They can do so using certain special text
sequences described below.  Accessing documentation strings in the usual
way substitutes current key binding information for these special
sequences.  This works by calling `substitute-command-keys'.  You can
also call that function yourself.

   Here is a list of the special sequences and what they mean:

`\[COMMAND]'
     stands for a key sequence that will invoke COMMAND, or `M-x
     COMMAND' if COMMAND has no key bindings.

`\{MAPVAR}'
     stands for a summary of the value of MAPVAR, which should be a
     keymap.  The summary is made by `describe-bindings'.

`\<MAPVAR>'
     stands for no text itself.  It is used for a side effect: it
     specifies MAPVAR as the keymap for any following `\[COMMAND]'
     sequences in this documentation string.

`\='
     quotes the following character and is discarded; this `\=\=' puts
     `\=' into the output, and `\=\[' puts `\[' into the output.

   *Please note:* Each `\' must be doubled when written in a string in
XEmacs Lisp.

 -- Function: substitute-command-keys string
     This function scans STRING for the above special sequences and
     replaces them by what they stand for, returning the result as a
     string.  This permits display of documentation that refers
     accurately to the user's own customized key bindings.

   Here are examples of the special sequences:

     (substitute-command-keys
        "To abort recursive edit, type: \\[abort-recursive-edit]")
     => "To abort recursive edit, type: C-]"

     (substitute-command-keys
        "The keys that are defined for the minibuffer here are:
       \\{minibuffer-local-must-match-map}")
     => "The keys that are defined for the minibuffer here are:

     ?               minibuffer-completion-help
     SPC             minibuffer-complete-word
     TAB             minibuffer-complete
     LFD             minibuffer-complete-and-exit
     RET             minibuffer-complete-and-exit
     C-g             abort-recursive-edit
     "

     (substitute-command-keys
        "To abort a recursive edit from the minibuffer, type\
     \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
     => "To abort a recursive edit from the minibuffer, type C-g."

     (substitute-command-keys
       "Substrings of the form \\=\\{MAPVAR} are replaced by summaries
     \(made by `describe-bindings') of the value of MAPVAR, taken as a keymap.
     Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR
     as the keymap for future \\=\\[COMMAND] substrings.
     \\=\\= quotes the following character and is discarded;
     thus, \\=\\=\\=\\= puts \\=\\= into the output,
     and \\=\\=\\=\\[ puts \\=\\[ into the output.")
     => "Substrings of the form \{MAPVAR} are replaced by summaries
     (made by `describe-bindings') of the value of MAPVAR, taken as a keymap.
     Substrings of the form \<MAPVAR> specify to use the value of MAPVAR
     as the keymap for future \[COMMAND] substrings.
     \= quotes the following character and is discarded;
     thus, \=\= puts \= into the output,
     and \=\[ puts \[ into the output."

\1f
File: lispref.info,  Node: Describing Characters,  Next: Help Functions,  Prev: Keys in Documentation,  Up: Documentation

34.4 Describing Characters for Help Messages
============================================

These functions convert events, key sequences or characters to textual
descriptions.  These descriptions are useful for including arbitrary
text characters or key sequences in messages, because they convert
non-printing and whitespace characters to sequences of printing
characters.  The description of a non-whitespace printing character is
the character itself.

 -- Function: key-description sequence
     This function returns a string containing the XEmacs standard
     notation for the input events in SEQUENCE.  The argument SEQUENCE
     may be a string, vector or list.  *Note Events::, for more
     information about valid events.  See also the examples for
     `single-key-description', below.

 -- Function: single-key-description key
     This function returns a string describing KEY in the standard
     XEmacs notation for keyboard input.  A normal printing character
     appears as itself, but a control character turns into a string
     starting with `C-', a meta character turns into a string starting
     with `M-', and space, linefeed, etc. appear as `SPC', `LFD', etc.
     A symbol appears as the name of the symbol.  An event that is a
     list appears as the name of the symbol in the CAR of the list.

          (single-key-description ?\C-x)
               => "C-x"
          (key-description "\C-x \M-y \n \t \r \f123")
               => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
          (single-key-description 'kp-next)
               => "kp-next"
          (single-key-description '(shift button1))
               => "Sh-button1"

 -- Function: text-char-description character
     This function returns a string describing CHARACTER in the
     standard XEmacs notation for characters that appear in text--like
     `single-key-description', except that control characters are
     represented with a leading caret (which is how control characters
     in XEmacs buffers are usually displayed).

          (text-char-description ?\C-c)
               => "^C"
          (text-char-description ?\M-m)
               => "M-m"
          (text-char-description ?\C-\M-m)
               => "M-^M"

\1f
File: lispref.info,  Node: Help Functions,  Next: Obsoleteness,  Prev: Describing Characters,  Up: Documentation

34.5 Help Functions
===================

XEmacs provides a variety of on-line help functions, all accessible to
the user as subcommands of the prefix `C-h', or on some keyboards,
`help'.  For more information about them, see *Note Help: (emacs)Help.
Here we describe some program-level interfaces to the same information.

 -- Command: apropos regexp &optional do-all predicate
     This function finds all symbols whose names contain a match for the
     regular expression REGEXP, and returns a list of them (*note
     Regular Expressions::).  It also displays the symbols in a buffer
     named `*Help*', each with a one-line description.

     If DO-ALL is non-`nil', then `apropos' also shows key bindings for
     the functions that are found.

     If PREDICATE is non-`nil', it should be a function to be called on
     each symbol that has matched REGEXP.  Only symbols for which
     PREDICATE returns a non-`nil' value are listed or displayed.

     In the first of the following examples, `apropos' finds all the
     symbols with names containing `exec'.  In the second example, it
     finds and returns only those symbols that are also commands.  (We
     don't show the output that results in the `*Help*' buffer.)

          (apropos "exec")
               => (Buffer-menu-execute command-execute exec-directory
              exec-path execute-extended-command execute-kbd-macro
              executing-kbd-macro executing-macro)

          (apropos "exec" nil 'commandp)
               => (Buffer-menu-execute execute-extended-command)

     `apropos' is used by various user-level commands, such as `C-h a'
     (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A'
     (`command-apropos'), which does an apropos over only those
     functions which are user commands.  `command-apropos' calls
     `apropos', specifying a PREDICATE to restrict the output to
     symbols that are commands.  The call to `apropos' looks like this:

          (apropos string t 'commandp)

 -- Variable: help-map
     The value of this variable is a local keymap for characters
     following the Help key, `C-h'.

 -- Prefix Command: help-command
     This symbol is not a function; its function definition is actually
     the keymap known as `help-map'.  It is defined in `help.el' as
     follows:

          (define-key global-map "\C-h" 'help-command)
          (fset 'help-command help-map)

 -- Function: print-help-return-message &optional function
     This function builds a string that explains how to restore the
     previous state of the windows after a help command.  After
     building the message, it applies FUNCTION to it if FUNCTION is
     non-`nil'.  Otherwise it calls `message' to display it in the echo
     area.

     This function expects to be called inside a
     `with-output-to-temp-buffer' special form, and expects
     `standard-output' to have the value bound by that special form.
     For an example of its use, see the long example in *Note Accessing
     Documentation::.

 -- Variable: help-char
     The value of this variable is the help character--the character
     that XEmacs recognizes as meaning Help.  By default, it is the
     character `?\^H' (ASCII 8), which is `C-h'.  When XEmacs reads this
     character, if `help-form' is non-`nil' Lisp expression, it
     evaluates that expression, and displays the result in a window if
     it is a string.

     `help-char' can be a character or a key description such as `help'
     or `(meta h)'.

     Usually the value of `help-form''s value is `nil'.  Then the help
     character has no special meaning at the level of command input, and
     it becomes part of a key sequence in the normal way.  The standard
     key binding of `C-h' is a prefix key for several general-purpose
     help features.

     The help character is special after prefix keys, too.  If it has no
     binding as a subcommand of the prefix key, it runs
     `describe-prefix-bindings', which displays a list of all the
     subcommands of the prefix key.

 -- Variable: help-form
     If this variable is non-`nil', its value is a form to evaluate
     whenever the character `help-char' is read.  If evaluating the form
     produces a string, that string is displayed.

     A command that calls `next-command-event' or `next-event' probably
     should bind `help-form' to a non-`nil' expression while it does
     input.  (The exception is when `C-h' is meaningful input.)
     Evaluating this expression should result in a string that explains
     what the input is for and how to enter it properly.

     Entry to the minibuffer binds this variable to the value of
     `minibuffer-help-form' (*note Minibuffer Misc::).

 -- Variable: prefix-help-command
     This variable holds a function to print help for a prefix
     character.  The function is called when the user types a prefix
     key followed by the help character, and the help character has no
     binding after that prefix.  The variable's default value is
     `describe-prefix-bindings'.

 -- Command: describe-prefix-bindings
     This function calls `describe-bindings' to display a list of all
     the subcommands of the prefix key of the most recent key sequence.
     The prefix described consists of all but the last event of that
     key sequence.  (The last event is, presumably, the help character.)

   The following two functions are found in the library `helper'.  They
are for modes that want to provide help without relinquishing control,
such as the "electric" modes.  You must load that library with
`(require 'helper)' in order to use them.  Their names begin with
`Helper' to distinguish them from the ordinary help functions.

 -- Command: Helper-describe-bindings
     This command pops up a window displaying a help buffer containing a
     listing of all of the key bindings from both the local and global
     keymaps.  It works by calling `describe-bindings'.

 -- Command: Helper-help
     This command provides help for the current mode.  It prompts the
     user in the minibuffer with the message `Help (Type ? for further
     options)', and then provides assistance in finding out what the key
     bindings are, and what the mode is intended for.  It returns `nil'.

     This can be customized by changing the map `Helper-help-map'.

\1f
File: lispref.info,  Node: Obsoleteness,  Prev: Help Functions,  Up: Documentation

34.6 Obsoleteness
=================

As you add functionality to a package, you may at times want to replace
an older function with a new one.  To preserve compatibility with
existing code, the older function needs to still exist; but users of
that function should be told to use the newer one instead.  XEmacs Lisp
lets you mark a function or variable as "obsolete", and indicate what
should be used instead.

 -- Command: make-obsolete function new &optional when
     This function indicates that FUNCTION is an obsolete function, and
     the function NEW should be used instead.  The byte compiler will
     issue a warning to this effect when it encounters a usage of the
     older function, and the help system will also note this in the
     function's documentation.  NEW can also be a string (if there is
     not a single function with the same functionality any more), and
     should be a descriptive statement, such as "use FOO or BAR
     instead" or "this function is unnecessary".  If provided, WHEN
     should be a string indicating when the function was first made
     obsolete, for example a date or a release number.

 -- Command: make-obsolete-variable variable new
     This is like `make-obsolete' but is for variables instead of
     functions.

 -- Function: define-obsolete-function-alias oldfun newfun
     This function combines `make-obsolete' and `define-function',
     declaring OLDFUN to be an obsolete variant of NEWFUN and defining
     OLDFUN as an alias for NEWFUN.

 -- Function: define-obsolete-variable-alias oldvar newvar
     This is like `define-obsolete-function-alias' but for variables.

   Note that you should not normally put obsoleteness information
explicitly in a function or variable's doc string.  The obsoleteness
information that you specify using the above functions will be displayed
whenever the doc string is displayed, and by adding it explicitly the
result is redundancy.

   Also, if an obsolete function is substantially the same as a newer
one but is not actually an alias, you should consider omitting the doc
string entirely (use a null string `""' as the doc string).  That way,
the user is told about the obsoleteness and is forced to look at the
documentation of the new function, making it more likely that he will
use the new function.

 -- Function: function-obsoleteness-doc function
     If FUNCTION is obsolete, this function returns a string describing
     this.  This is the message that is printed out during byte
     compilation or in the function's documentation.  If FUNCTION is
     not obsolete, `nil' is returned.

 -- Function: variable-obsoleteness-doc variable
     This is like `function-obsoleteness-doc' but for variables.

   The obsoleteness information is stored internally by putting a
property `byte-obsolete-info' (for functions) or
`byte-obsolete-variable' (for variables) on the symbol that specifies
the obsolete function or variable.  For more information, see the
implementation of `make-obsolete' and `make-obsolete-variable' in
`lisp/bytecomp/bytecomp-runtime.el'.

\1f
File: lispref.info,  Node: Files,  Next: Backups and Auto-Saving,  Prev: Documentation,  Up: Top

35 Files
********

In XEmacs, you can find, create, view, save, and otherwise work with
files and file directories.  This chapter describes most of the
file-related functions of XEmacs Lisp, but a few others are described in
*Note Buffers::, and those related to backups and auto-saving are
described in *Note Backups and Auto-Saving::.

   Many of the file functions take one or more arguments that are file
names.  A file name is actually a string.  Most of these functions
expand file name arguments using `expand-file-name', so that `~' is
handled correctly, as are relative file names (including `../').  These
functions don't recognize environment variable substitutions such as
`$HOME'.  *Note File Name Expansion::.

* Menu:

* Visiting Files::           Reading files into Emacs buffers for editing.
* Saving Buffers::           Writing changed buffers back into files.
* Reading from Files::       Reading files into buffers without visiting.
* Writing to Files::         Writing new files from parts of buffers.
* File Locks::               Locking and unlocking files, to prevent
                               simultaneous editing by two people.
* Information about Files::  Testing existence, accessibility, size of files.
* Changing File Attributes:: Renaming files, changing protection, etc.
* File Names::               Decomposing and expanding file names.
* Contents of Directories::  Getting a list of the files in a directory.
* Create/Delete Dirs::       Creating and Deleting Directories.
* Magic File Names::         Defining "magic" special handling
                               for certain file names.
* Partial Files::            Treating a section of a buffer as a file.
* Format Conversion::        Conversion to and from various file formats.
* Files and MS-DOS::         Distinguishing text and binary files on MS-DOS.

\1f
File: lispref.info,  Node: Visiting Files,  Next: Saving Buffers,  Up: Files

35.1 Visiting Files
===================

Visiting a file means reading a file into a buffer.  Once this is done,
we say that the buffer is "visiting" that file, and call the file "the
visited file" of the buffer.

   A file and a buffer are two different things.  A file is information
recorded permanently in the computer (unless you delete it).  A buffer,
on the other hand, is information inside of XEmacs that will vanish at
the end of the editing session (or when you kill the buffer).  Usually,
a buffer contains information that you have copied from a file; then we
say the buffer is visiting that file.  The copy in the buffer is what
you modify with editing commands.  Such changes to the buffer do not
change the file; therefore, to make the changes permanent, you must
"save" the buffer, which means copying the altered buffer contents back
into the file.

   In spite of the distinction between files and buffers, people often
refer to a file when they mean a buffer and vice-versa.  Indeed, we say,
"I am editing a file," rather than, "I am editing a buffer that I will
soon save as a file of the same name."  Humans do not usually need to
make the distinction explicit.  When dealing with a computer program,
however, it is good to keep the distinction in mind.

* Menu:

* Visiting Functions::         The usual interface functions for visiting.
* Subroutines of Visiting::    Lower-level subroutines that they use.

\1f
File: lispref.info,  Node: Visiting Functions,  Next: Subroutines of Visiting,  Up: Visiting Files

35.1.1 Functions for Visiting Files
-----------------------------------

This section describes the functions normally used to visit files.  For
historical reasons, these functions have names starting with `find-'
rather than `visit-'.  *Note Buffer File Name::, for functions and
variables that access the visited file name of a buffer or that find an
existing buffer by its visited file name.

   In a Lisp program, if you want to look at the contents of a file but
not alter it, the fastest way is to use `insert-file-contents' in a
temporary buffer.  Visiting the file is not necessary and takes longer.
*Note Reading from Files::.

 -- Command: find-file filename
     This command selects a buffer visiting the file FILENAME, using an
     existing buffer if there is one, and otherwise creating a new
     buffer and reading the file into it.  It also returns that buffer.

     The body of the `find-file' function is very simple and looks like
     this:

          (switch-to-buffer (find-file-noselect filename))

     (See `switch-to-buffer' in *Note Displaying Buffers::.)

     When `find-file' is called interactively, it prompts for FILENAME
     in the minibuffer.

 -- Function: find-file-noselect filename &optional nowarn
     This function is the guts of all the file-visiting functions.  It
     finds or creates a buffer visiting the file FILENAME, and returns
     it.  It uses an existing buffer if there is one, and otherwise
     creates a new buffer and reads the file into it.  You may make the
     buffer current or display it in a window if you wish, but this
     function does not do so.

     When `find-file-noselect' uses an existing buffer, it first
     verifies that the file has not changed since it was last visited or
     saved in that buffer.  If the file has changed, then this function
     asks the user whether to reread the changed file.  If the user says
     `yes', any changes previously made in the buffer are lost.

     If `find-file-noselect' needs to create a buffer, and there is no
     file named FILENAME, it displays the message `New file' in the
     echo area, and leaves the buffer empty.

     If NOWARN is non-`nil', various warnings that XEmacs normally
     gives (e.g. if another buffer is already visiting FILENAME but
     FILENAME has been removed from disk since that buffer was created)
     are suppressed.

     The `find-file-noselect' function calls `after-find-file' after
     reading the file (*note Subroutines of Visiting::).  That function
     sets the buffer major mode, parses local variables, warns the user
     if there exists an auto-save file more recent than the file just
     visited, and finishes by running the functions in
     `find-file-hooks'.

     The `find-file-noselect' function returns the buffer that is
     visiting the file FILENAME.

          (find-file-noselect "/etc/fstab")
               => #<buffer fstab>

 -- Command: find-file-other-window filename
     This command selects a buffer visiting the file FILENAME, but does
     so in a window other than the selected window.  It may use another
     existing window or split a window; see *Note Displaying Buffers::.

     When this command is called interactively, it prompts for FILENAME.

 -- Command: find-file-read-only filename
     This command selects a buffer visiting the file FILENAME, like
     `find-file', but it marks the buffer as read-only.  *Note Read
     Only Buffers::, for related functions and variables.

     When this command is called interactively, it prompts for FILENAME.

 -- Command: view-file filename &optional other-window-p
     This command visits FILENAME in View mode, and displays it in a
     recursive edit, returning to the previous buffer when done.  View
     mode is a mode that allows you to skim rapidly through the file
     but does not let you modify it.  Entering View mode runs the
     normal hook `view-mode-hook'.  *Note Hooks::.

     When `view-file' is called interactively, it prompts for FILENAME.

     With non-`nil' prefix arg OTHER-WINDOW-P, visit FILENAME in
     another window.

 -- Variable: find-file-hooks
     The value of this variable is a list of functions to be called
     after a file is visited.  The file's local-variables specification
     (if any) will have been processed before the hooks are run.  The
     buffer visiting the file is current when the hook functions are
     run.

     This variable works just like a normal hook, but we think that
     renaming it would not be advisable.

 -- Variable: find-file-not-found-hooks
     The value of this variable is a list of functions to be called when
     `find-file' or `find-file-noselect' is passed a nonexistent file
     name.  `find-file-noselect' calls these functions as soon as it
     detects a nonexistent file.  It calls them in the order of the
     list, until one of them returns non-`nil'.  `buffer-file-name' is
     already set up.

     This is not a normal hook because the values of the functions are
     used and they may not all be called.

\1f
File: lispref.info,  Node: Subroutines of Visiting,  Prev: Visiting Functions,  Up: Visiting Files

35.1.2 Subroutines of Visiting
------------------------------

The `find-file-noselect' function uses the `create-file-buffer' and
`after-find-file' functions as subroutines.  Sometimes it is useful to
call them directly.

 -- Function: create-file-buffer filename
     This function creates a suitably named buffer for visiting
     FILENAME, and returns it.  It uses FILENAME (sans directory) as
     the name if that name is free; otherwise, it appends a string such
     as `<2>' to get an unused name.  See also *Note Creating Buffers::.

     *Please note:* `create-file-buffer' does _not_ associate the new
     buffer with a file and does not select the buffer.  It also does
     not use the default major mode.

          (create-file-buffer "foo")
               => #<buffer foo>
          (create-file-buffer "foo")
               => #<buffer foo<2>>
          (create-file-buffer "foo")
               => #<buffer foo<3>>

     This function is used by `find-file-noselect'.  It uses
     `generate-new-buffer' (*note Creating Buffers::).

 -- Function: after-find-file &optional error warn noauto
     This function sets the buffer major mode, and parses local
     variables (*note Auto Major Mode::).  It is called by
     `find-file-noselect' and by the default revert function (*note
     Reverting::).

     If reading the file got an error because the file does not exist,
     but its directory does exist, the caller should pass a non-`nil'
     value for ERROR.  In that case, `after-find-file' issues a warning:
     `(New File)'.  For more serious errors, the caller should usually
     not call `after-find-file'.

     If WARN is non-`nil', then this function issues a warning if an
     auto-save file exists and is more recent than the visited file.

     If NOAUTO is non-`nil', then this function does not turn on
     auto-save mode; otherwise, it does.

     The last thing `after-find-file' does is call all the functions in
     `find-file-hooks'.

\1f
File: lispref.info,  Node: Saving Buffers,  Next: Reading from Files,  Prev: Visiting Files,  Up: Files

35.2 Saving Buffers
===================

When you edit a file in XEmacs, you are actually working on a buffer
that is visiting that file--that is, the contents of the file are
copied into the buffer and the copy is what you edit.  Changes to the
buffer do not change the file until you "save" the buffer, which means
copying the contents of the buffer into the file.

 -- Command: save-buffer &optional backup-option
     This function saves the contents of the current buffer in its
     visited file if the buffer has been modified since it was last
     visited or saved.  Otherwise it does nothing.

     `save-buffer' is responsible for making backup files.  Normally,
     BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only
     if this is the first save since visiting the file.  Other values
     for BACKUP-OPTION request the making of backup files in other
     circumstances:

        * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the
          `save-buffer' function marks this version of the file to be
          backed up when the buffer is next saved.

        * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the
          `save-buffer' function unconditionally backs up the previous
          version of the file before saving it.

 -- Command: save-some-buffers &optional save-silently-p exiting
     This command saves some modified file-visiting buffers.  Normally
     it asks the user about each buffer.  But if SAVE-SILENTLY-P is
     non-`nil', it saves all the file-visiting buffers without querying
     the user.

     The optional EXITING argument, if non-`nil', requests this
     function to offer also to save certain other buffers that are not
     visiting files.  These are buffers that have a non-`nil' local
     value of `buffer-offer-save'.  (A user who says yes to saving one
     of these is asked to specify a file name to use.)  The
     `save-buffers-kill-emacs' function passes a non-`nil' value for
     this argument.

 -- Variable: buffer-offer-save
     When this variable is non-`nil' in a buffer, XEmacs offers to save
     the buffer on exit even if the buffer is not visiting a file.  The
     variable is automatically local in all buffers.  Normally, Mail
     mode (used for editing outgoing mail) sets this to `t'.

 -- Command: write-file filename
     This function writes the current buffer into file FILENAME, makes
     the buffer visit that file, and marks it not modified.  Then it
     renames the buffer based on FILENAME, appending a string like `<2>'
     if necessary to make a unique buffer name.  It does most of this
     work by calling `set-visited-file-name' and `save-buffer'.

 -- Variable: write-file-hooks
     The value of this variable is a list of functions to be called
     before writing out a buffer to its visited file.  If one of them
     returns non-`nil', the file is considered already written and the
     rest of the functions are not called, nor is the usual code for
     writing the file executed.

     If a function in `write-file-hooks' returns non-`nil', it is
     responsible for making a backup file (if that is appropriate).  To
     do so, execute the following code:

          (or buffer-backed-up (backup-buffer))

     You might wish to save the file modes value returned by
     `backup-buffer' and use that to set the mode bits of the file that
     you write.  This is what `save-buffer' normally does.

     Even though this is not a normal hook, you can use `add-hook' and
     `remove-hook' to manipulate the list.  *Note Hooks::.

 -- Variable: local-write-file-hooks
     This works just like `write-file-hooks', but it is intended to be
     made local to particular buffers.  It's not a good idea to make
     `write-file-hooks' local to a buffer--use this variable instead.

     The variable is marked as a permanent local, so that changing the
     major mode does not alter a buffer-local value.  This is
     convenient for packages that read "file" contents in special ways,
     and set up hooks to save the data in a corresponding way.

 -- Variable: write-contents-hooks
     This works just like `write-file-hooks', but it is intended for
     hooks that pertain to the contents of the file, as opposed to
     hooks that pertain to where the file came from.  Such hooks are
     usually set up by major modes, as buffer-local bindings for this
     variable.  Switching to a new major mode always resets this
     variable.

 -- Variable: after-save-hook
     This normal hook runs after a buffer has been saved in its visited
     file.

 -- Variable: file-precious-flag
     If this variable is non-`nil', then `save-buffer' protects against
     I/O errors while saving by writing the new file to a temporary
     name instead of the name it is supposed to have, and then renaming
     it to the intended name after it is clear there are no errors.
     This procedure prevents problems such as a lack of disk space from
     resulting in an invalid file.

     As a side effect, backups are necessarily made by copying.  *Note
     Rename or Copy::.  Yet, at the same time, saving a precious file
     always breaks all hard links between the file you save and other
     file names.

     Some modes set this variable non-`nil' locally in particular
     buffers.

 -- User Option: require-final-newline
     This variable determines whether files may be written out that do
     _not_ end with a newline.  If the value of the variable is `t',
     then `save-buffer' silently adds a newline at the end of the file
     whenever the buffer being saved does not already end in one.  If
     the value of the variable is non-`nil', but not `t', then
     `save-buffer' asks the user whether to add a newline each time the
     case arises.

     If the value of the variable is `nil', then `save-buffer' doesn't
     add newlines at all.  `nil' is the default value, but a few major
     modes set it to `t' in particular buffers.

\1f
File: lispref.info,  Node: Reading from Files,  Next: Writing to Files,  Prev: Saving Buffers,  Up: Files

35.3 Reading from Files
=======================

You can copy a file from the disk and insert it into a buffer using the
`insert-file-contents' function.  Don't use the user-level command
`insert-file' in a Lisp program, as that sets the mark.

 -- Function: insert-file-contents filename &optional visit start end
          replace
     This function inserts the contents of file FILENAME into the
     current buffer after point.  It returns a list of the absolute
     file name and the length of the data inserted.  An error is
     signaled if FILENAME is not the name of a file that can be read.

     The function `insert-file-contents' checks the file contents
     against the defined file formats, and converts the file contents if
     appropriate.  *Note Format Conversion::.  It also calls the
     functions in the list `after-insert-file-functions'; see *Note
     Saving Properties::.

     If VISIT is non-`nil', this function additionally marks the buffer
     as unmodified and sets up various fields in the buffer so that it
     is visiting the file FILENAME: these include the buffer's visited
     file name and its last save file modtime.  This feature is used by
     `find-file-noselect' and you probably should not use it yourself.

     If START and END are non-`nil', they should be integers specifying
     the portion of the file to insert.  In this case, VISIT must be
     `nil'.  For example,

          (insert-file-contents filename nil 0 500)

     inserts the first 500 characters of a file.

     If the argument REPLACE is non-`nil', it means to replace the
     contents of the buffer (actually, just the accessible portion)
     with the contents of the file.  This is better than simply
     deleting the buffer contents and inserting the whole file, because
     (1) it preserves some marker positions and (2) it puts less data
     in the undo list.

   If you want to pass a file name to another process so that another
program can read the file, use the function `file-local-copy'; see
*Note Magic File Names::.

\1f
File: lispref.info,  Node: Writing to Files,  Next: File Locks,  Prev: Reading from Files,  Up: Files

35.4 Writing to Files
=====================

You can write the contents of a buffer, or part of a buffer, directly
to a file on disk using the `append-to-file' and `write-region'
functions.  Don't use these functions to write to files that are being
visited; that could cause confusion in the mechanisms for visiting.

 -- Command: append-to-file start end filename
     This function appends the contents of the region delimited by
     START and END in the current buffer to the end of file FILENAME.
     If that file does not exist, it is created.  If that file exists
     it is overwritten.  This function returns `nil'.

     An error is signaled if FILENAME specifies a nonwritable file, or
     a nonexistent file in a directory where files cannot be created.

 -- Command: write-region start end filename &optional append visit
     This function writes the region delimited by START and END in the
     current buffer into the file specified by FILENAME.

     If START is a string, then `write-region' writes or appends that
     string, rather than text from the buffer.

     If APPEND is non-`nil', then the specified text is appended to the
     existing file contents (if any).

     If VISIT is `t', then XEmacs establishes an association between
     the buffer and the file: the buffer is then visiting that file.
     It also sets the last file modification time for the current
     buffer to FILENAME's modtime, and marks the buffer as not
     modified.  This feature is used by `save-buffer', but you probably
     should not use it yourself.

     If VISIT is a string, it specifies the file name to visit.  This
     way, you can write the data to one file (FILENAME) while recording
     the buffer as visiting another file (VISIT).  The argument VISIT
     is used in the echo area message and also for file locking; VISIT
     is stored in `buffer-file-name'.  This feature is used to
     implement `file-precious-flag'; don't use it yourself unless you
     really know what you're doing.

     The function `write-region' converts the data which it writes to
     the appropriate file formats specified by `buffer-file-format'.
     *Note Format Conversion::.  It also calls the functions in the list
     `write-region-annotate-functions'; see *Note Saving Properties::.

     Normally, `write-region' displays a message `Wrote file FILENAME'
     in the echo area.  If VISIT is neither `t' nor `nil' nor a string,
     then this message is inhibited.  This feature is useful for
     programs that use files for internal purposes, files that the user
     does not need to know about.

\1f
File: lispref.info,  Node: File Locks,  Next: Information about Files,  Prev: Writing to Files,  Up: Files

35.5 File Locks
===============

When two users edit the same file at the same time, they are likely to
interfere with each other.  XEmacs tries to prevent this situation from
arising by recording a "file lock" when a file is being modified.
XEmacs can then detect the first attempt to modify a buffer visiting a
file that is locked by another XEmacs process, and ask the user what to
do.

   File locks do not work properly when multiple machines can share
file systems, such as with NFS.  Perhaps a better file locking system
will be implemented in the future.  When file locks do not work, it is
possible for two users to make changes simultaneously, but XEmacs can
still warn the user who saves second.  Also, the detection of
modification of a buffer visiting a file changed on disk catches some
cases of simultaneous editing; see *Note Modification Time::.

 -- Function: file-locked-p &optional filename
     This function returns `nil' if the file FILENAME is not locked by
     this XEmacs process.  It returns `t' if it is locked by this
     XEmacs, and it returns the name of the user who has locked it if it
     is locked by someone else.

          (file-locked-p "foo")
               => nil

 -- Function: lock-buffer &optional filename
     This function locks the file FILENAME, if the current buffer is
     modified.  The argument FILENAME defaults to the current buffer's
     visited file.  Nothing is done if the current buffer is not
     visiting a file, or is not modified.

 -- Function: unlock-buffer
     This function unlocks the file being visited in the current buffer,
     if the buffer is modified.  If the buffer is not modified, then
     the file should not be locked, so this function does nothing.  It
     also does nothing if the current buffer is not visiting a file.

 -- Function: ask-user-about-lock filename other-user
     This function is called when the user tries to modify FILENAME,
     but it is locked by another user named OTHER-USER.  The value it
     returns determines what happens next:

        * A value of `t' says to grab the lock on the file.  Then this
          user may edit the file and OTHER-USER loses the lock.

        * A value of `nil' says to ignore the lock and let this user
          edit the file anyway.

        * This function may instead signal a `file-locked' error, in
          which case the change that the user was about to make does
          not take place.

          The error message for this error looks like this:

               error--> File is locked: FILENAME OTHER-USER

          where FILENAME is the name of the file and OTHER-USER is the
          name of the user who has locked the file.

     The default definition of this function asks the user to choose
     what to do.  If you wish, you can replace the `ask-user-about-lock'
     function with your own version that decides in another way.  The
     code for its usual definition is in `userlock.el'.

\1f
File: lispref.info,  Node: Information about Files,  Next: Changing File Attributes,  Prev: File Locks,  Up: Files

35.6 Information about Files
============================

The functions described in this section all operate on strings that
designate file names.  All the functions have names that begin with the
word `file'.  These functions all return information about actual files
or directories, so their arguments must all exist as actual files or
directories unless otherwise noted.

* Menu:

* Testing Accessibility::   Is a given file readable?  Writable?
* Kinds of Files::          Is it a directory?  A symbolic link?
* Truenames::               Eliminating symbolic links from a file name.
* File Attributes::         How large is it?  Any other names?  Etc.

\1f
File: lispref.info,  Node: Testing Accessibility,  Next: Kinds of Files,  Up: Information about Files

35.6.1 Testing Accessibility
----------------------------

These functions test for permission to access a file in specific ways.

 -- Function: file-exists-p filename
     This function returns `t' if a file named FILENAME appears to
     exist.  This does not mean you can necessarily read the file, only
     that you can find out its attributes.  (On Unix, this is true if
     the file exists and you have execute permission on the containing
     directories, regardless of the protection of the file itself.)

     If the file does not exist, or if fascist access control policies
     prevent you from finding the attributes of the file, this function
     returns `nil'.

 -- Function: file-readable-p filename
     This function returns `t' if a file named FILENAME exists and you
     can read it.  It returns `nil' otherwise.

          (file-readable-p "files.texi")
               => t
          (file-exists-p "/usr/spool/mqueue")
               => t
          (file-readable-p "/usr/spool/mqueue")
               => nil

 -- Function: file-executable-p filename
     This function returns `t' if a file named FILENAME exists and you
     can execute it.  It returns `nil' otherwise.  If the file is a
     directory, execute permission means you can check the existence and
     attributes of files inside the directory, and open those files if
     their modes permit.

 -- Function: file-writable-p filename
     This function returns `t' if the file FILENAME can be written or
     created by you, and `nil' otherwise.  A file is writable if the
     file exists and you can write it.  It is creatable if it does not
     exist, but the specified directory does exist and you can write in
     that directory.

     In the third example below, `foo' is not writable because the
     parent directory does not exist, even though the user could create
     such a directory.

          (file-writable-p "~/foo")
               => t
          (file-writable-p "/foo")
               => nil
          (file-writable-p "~/no-such-dir/foo")
               => nil

 -- Function: file-accessible-directory-p dirname
     This function returns `t' if you have permission to open existing
     files in the directory whose name as a file is DIRNAME; otherwise
     (or if there is no such directory), it returns `nil'.  The value
     of DIRNAME may be either a directory name or the file name of a
     directory.

     Example: after the following,

          (file-accessible-directory-p "/foo")
               => nil

     we can deduce that any attempt to read a file in `/foo/' will give
     an error.

 -- Function: file-ownership-preserved-p filename
     This function returns `t' if deleting the file FILENAME and then
     creating it anew would keep the file's owner unchanged.

 -- Function: file-newer-than-file-p filename1 filename2
     This function returns `t' if the file FILENAME1 is newer than file
     FILENAME2.  If FILENAME1 does not exist, it returns `nil'.  If
     FILENAME2 does not exist, it returns `t'.

     In the following example, assume that the file `aug-19' was written
     on the 19th, `aug-20' was written on the 20th, and the file
     `no-file' doesn't exist at all.

          (file-newer-than-file-p "aug-19" "aug-20")
               => nil
          (file-newer-than-file-p "aug-20" "aug-19")
               => t
          (file-newer-than-file-p "aug-19" "no-file")
               => t
          (file-newer-than-file-p "no-file" "aug-19")
               => nil

     You can use `file-attributes' to get a file's last modification
     time as a list of two numbers.  *Note File Attributes::.

\1f
File: lispref.info,  Node: Kinds of Files,  Next: Truenames,  Prev: Testing Accessibility,  Up: Information about Files

35.6.2 Distinguishing Kinds of Files
------------------------------------

This section describes how to distinguish various kinds of files, such
as directories, symbolic links, and ordinary files.

 -- Function: file-symlink-p filename
     If the file FILENAME is a symbolic link, the `file-symlink-p'
     function returns the file name to which it is linked.  This may be
     the name of a text file, a directory, or even another symbolic
     link, or it may be a nonexistent file name.

     If the file FILENAME is not a symbolic link (or there is no such
     file), `file-symlink-p' returns `nil'.

          (file-symlink-p "foo")
               => nil
          (file-symlink-p "sym-link")
               => "foo"
          (file-symlink-p "sym-link2")
               => "sym-link"
          (file-symlink-p "/bin")
               => "/pub/bin"


 -- Function: file-directory-p filename
     This function returns `t' if FILENAME is the name of an existing
     directory, `nil' otherwise.

          (file-directory-p "~rms")
               => t
          (file-directory-p "~rms/lewis/files.texi")
               => nil
          (file-directory-p "~rms/lewis/no-such-file")
               => nil
          (file-directory-p "$HOME")
               => nil
          (file-directory-p
           (substitute-in-file-name "$HOME"))
               => t

 -- Function: file-regular-p filename
     This function returns `t' if the file FILENAME exists and is a
     regular file (not a directory, symbolic link, named pipe,
     terminal, or other I/O device).

\1f
File: lispref.info,  Node: Truenames,  Next: File Attributes,  Prev: Kinds of Files,  Up: Information about Files

35.6.3 Truenames
----------------

The "truename" of a file is the name that you get by following symbolic
links until none remain, then expanding to get rid of `.' and `..' as
components.  Strictly speaking, a file need not have a unique truename;
the number of distinct truenames a file has is equal to the number of
hard links to the file.  However, truenames are useful because they
eliminate symbolic links as a cause of name variation.

 -- Function: file-truename filename &optional default
     The function `file-truename' returns the true name of the file
     FILENAME.  This is the name that you get by following symbolic
     links until none remain.

     If the filename is relative, DEFAULT is the directory to start
     with.  If DEFAULT is `nil' or missing, the current buffer's value
     of `default-directory' is used.

   *Note Buffer File Name::, for related information.

\1f
File: lispref.info,  Node: File Attributes,  Prev: Truenames,  Up: Information about Files

35.6.4 Other Information about Files
------------------------------------

This section describes the functions for getting detailed information
about a file, other than its contents.  This information includes the
mode bits that control access permission, the owner and group numbers,
the number of names, the inode number, the size, and the times of access
and modification.

 -- Function: file-modes filename
     This function returns the mode bits of FILENAME, as an integer.
     The mode bits are also called the file permissions, and they
     specify access control in the usual Unix fashion.  If the
     low-order bit is 1, then the file is executable by all users, if
     the second-lowest-order bit is 1, then the file is writable by all
     users, etc.

     The highest value returnable is 4095 (7777 octal), meaning that
     everyone has read, write, and execute permission, that the SUID bit
     is set for both others and group, and that the sticky bit is set.

          (file-modes "~/junk/diffs")
               => 492               ; Decimal integer.
          (format "%o" 492)
               => "754"             ; Convert to octal.

          (set-file-modes "~/junk/diffs" 438)
               => nil

          (format "%o" 438)
               => "666"             ; Convert to octal.

          % ls -l diffs
            -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs

 -- Function: file-nlinks filename
     This functions returns the number of names (i.e., hard links) that
     file FILENAME has.  If the file does not exist, then this function
     returns `nil'.  Note that symbolic links have no effect on this
     function, because they are not considered to be names of the files
     they link to.

          % ls -l foo*
          -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo
          -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo1

          (file-nlinks "foo")
               => 2
          (file-nlinks "doesnt-exist")
               => nil

 -- Function: file-attributes filename
     This function returns a list of attributes of file FILENAME.  If
     the specified file cannot be opened, it returns `nil'.

     The elements of the list, in order, are:

       0. `t' for a directory, a string for a symbolic link (the name
          linked to), or `nil' for a text file.

       1. The number of names the file has.  Alternate names, also
          known as hard links, can be created by using the
          `add-name-to-file' function (*note Changing File
          Attributes::).

       2. The file's UID.

       3. The file's GID.

       4. The time of last access, as a list of two integers.  The
          first integer has the high-order 16 bits of time, the second
          has the low 16 bits.  (This is similar to the value of
          `current-time'; see *Note Time of Day::.)

       5. The time of last modification as a list of two integers (as
          above).

       6. The time of last status change as a list of two integers (as
          above).

       7. The size of the file in bytes.

       8. The file's modes, as a string of ten letters or dashes, as in
          `ls -l'.

       9. `t' if the file's GID would change if file were deleted and
          recreated; `nil' otherwise.

      10. The file's inode number.

      11. The file system number of the file system that the file is
          in.  This element and the file's inode number together give
          enough information to distinguish any two files on the
          system--no two files can have the same values for both of
          these numbers.

     For example, here are the file attributes for `files.texi':

          (file-attributes "files.texi")
               =>  (nil
                    1
                    2235
                    75
                    (8489 20284)
                    (8489 20284)
                    (8489 20285)
                    14906
                    "-rw-rw-rw-"
                    nil
                    129500
                    -32252)

     and here is how the result is interpreted:

    `nil'
          is neither a directory nor a symbolic link.

    `1'
          has only one name (the name `files.texi' in the current
          default directory).

    `2235'
          is owned by the user with UID 2235.

    `75'
          is in the group with GID 75.

    `(8489 20284)'
          was last accessed on Aug 19 00:09. Use `format-time-string' to
          ! convert this number into a time string.  *Note Time
          Conversion::.

    `(8489 20284)'
          was last modified on Aug 19 00:09.

    `(8489 20285)'
          last had its inode changed on Aug 19 00:09.

    `14906'
          is 14906 characters long.

    `"-rw-rw-rw-"'
          has a mode of read and write access for the owner, group, and
          world.

    `nil'
          would retain the same GID if it were recreated.

    `129500'
          has an inode number of 129500.

    `-32252'
          is on file system number -32252.

\1f
File: lispref.info,  Node: Changing File Attributes,  Next: File Names,  Prev: Information about Files,  Up: Files

35.7 Changing File Names and Attributes
=======================================

The functions in this section rename, copy, delete, link, and set the
modes of files.

   In the functions that have arguments NEWNAME and
OK-IF-ALREADY-EXISTS, if a file by the name of NEWNAME already exists,
the actions taken depend on the value of OK-IF-ALREADY-EXISTS:

   * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is
     `nil'.

   * Request confirmation if OK-IF-ALREADY-EXISTS is a number.  This is
     what happens when the function is invoked interactively.

   * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
     is any other value.

 -- Command: add-name-to-file filename newname &optional
          ok-if-already-exists
     This function gives the file named FILENAME the additional name
     NEWNAME.  This means that NEWNAME becomes a new "hard link" to
     FILENAME.  Both these arguments must be strings.

     In the first part of the following example, we list two files,
     `foo' and `foo3'.

          % ls -l fo*
          -rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
          -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3

     Then we evaluate the form `(add-name-to-file "~/lewis/foo"
     "~/lewis/foo2")'.  Again we list the files.  This shows two names,
     `foo' and `foo2'.

          (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
               => nil

          % ls -l fo*
          -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
          -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
          -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3

     Finally, we evaluate the following:

          (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)

     and list the files again.  Now there are three names for one file:
     `foo', `foo2', and `foo3'.  The old contents of `foo3' are lost.

          (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
               => nil

          % ls -l fo*
          -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
          -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
          -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3

     This function is meaningless on non-Unix systems, where multiple
     names for one file are not allowed.

     See also `file-nlinks' in *Note File Attributes::.

 -- Command: rename-file filename newname &optional ok-if-already-exists
     This command renames the file FILENAME as NEWNAME.

     If FILENAME has additional names aside from FILENAME, it continues
     to have those names.  In fact, adding the name NEWNAME with
     `add-name-to-file' and then deleting FILENAME has the same effect
     as renaming, aside from momentary intermediate states.

     In an interactive call, this function prompts for FILENAME and
     NEWNAME in the minibuffer; also, it requests confirmation if
     NEWNAME already exists.

 -- Command: copy-file filename newname &optional ok-if-already-exists
          time
     This command copies the file FILENAME to NEWNAME.  An error is
     signaled if FILENAME does not exist.

     If TIME is non-`nil', then this functions gives the new file the
     same last-modified time that the old one has.  (This works on only
     some operating systems.)

     In an interactive call, this function prompts for FILENAME and
     NEWNAME in the minibuffer; also, it requests confirmation if
     NEWNAME already exists.

 -- Command: delete-file filename
     This command deletes the file FILENAME, like the shell command `rm
     FILENAME'.  If the file has multiple names, it continues to exist
     under the other names.

     A suitable kind of `file-error' error is signaled if the file does
     not exist, or is not deletable.  (On Unix, a file is deletable if
     its directory is writable.)

     See also `delete-directory' in *Note Create/Delete Dirs::.

 -- Command: make-symbolic-link filename newname &optional
          ok-if-already-exists
     This command makes a symbolic link to FILENAME, named NEWNAME.
     This is like the shell command `ln -s FILENAME NEWNAME'.

     In an interactive call, this function prompts for FILENAME and
     NEWNAME in the minibuffer; also, it requests confirmation if
     NEWNAME already exists.

 -- Function: set-file-modes filename mode
     This function sets mode bits of FILENAME to MODE (which must be an
     integer).  Only the low 12 bits of MODE are used.

 -- Function: set-default-file-modes mode
     This function sets the default file protection for new files
     created by XEmacs and its subprocesses.  Every file created with
     XEmacs initially has this protection.  On Unix, the default
     protection is the bitwise complement of the "umask" value.

     The argument MODE must be an integer.  Only the low 9 bits of MODE
     are used.

     Saving a modified version of an existing file does not count as
     creating the file; it does not change the file's mode, and does
     not use the default file protection.

 -- Function: default-file-modes
     This function returns the current default protection value.

   On MS-DOS, there is no such thing as an "executable" file mode bit.
So Emacs considers a file executable if its name ends in `.com', `.bat'
or `.exe'.  This is reflected in the values returned by `file-modes'
and `file-attributes'.

\1f
File: lispref.info,  Node: File Names,  Next: Contents of Directories,  Prev: Changing File Attributes,  Up: Files

35.8 File Names
===============

Files are generally referred to by their names, in XEmacs as elsewhere.
File names in XEmacs are represented as strings.  The functions that
operate on a file all expect a file name argument.

   In addition to operating on files themselves, XEmacs Lisp programs
often need to operate on the names; i.e., to take them apart and to use
part of a name to construct related file names.  This section describes
how to manipulate file names.

   The functions in this section do not actually access files, so they
can operate on file names that do not refer to an existing file or
directory.

   On MS-DOS, these functions understand MS-DOS file-name syntax as
well as Unix syntax. This is so that all the standard Lisp libraries
can specify file names in Unix syntax and work properly on all systems
without change.  Similarly for other operating systems.

* Menu:

* File Name Components::  The directory part of a file name, and the rest.
* Directory Names::       A directory's name as a directory
                            is different from its name as a file.
* Relative File Names::   Some file names are relative to a current directory.
* File Name Expansion::   Converting relative file names to absolute ones.
* Unique File Names::     Generating names for temporary files.
* File Name Completion::  Finding the completions for a given file name.
* User Name Completion::  Finding the completions for a given user name.

\1f
File: lispref.info,  Node: File Name Components,  Next: Directory Names,  Up: File Names

35.8.1 File Name Components
---------------------------

The operating system groups files into directories.  To specify a file,
you must specify the directory and the file's name within that
directory.  Therefore, XEmacs considers a file name as having two main
parts: the "directory name" part, and the "nondirectory" part (or "file
name within the directory").  Either part may be empty.  Concatenating
these two parts reproduces the original file name.

   On Unix, the directory part is everything up to and including the
last slash; the nondirectory part is the rest.

   For some purposes, the nondirectory part is further subdivided into
the name proper and the "version number".  On Unix, only backup files
have version numbers in their names.

 -- Function: file-name-directory filename
     This function returns the directory part of FILENAME (or `nil' if
     FILENAME does not include a directory part).  On Unix, the
     function returns a string ending in a slash.

          (file-name-directory "lewis/foo")  ; Unix example
               => "lewis/"
          (file-name-directory "foo")        ; Unix example
               => nil

 -- Function: file-name-nondirectory filename
     This function returns the nondirectory part of FILENAME.

          (file-name-nondirectory "lewis/foo")
               => "foo"
          (file-name-nondirectory "foo")
               => "foo"

 -- Function: file-name-sans-versions filename &optional
          keep-backup-version
     This function returns FILENAME without any file version numbers,
     backup version numbers, or trailing tildes.

     If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup
     version numbers, only true file version numbers.

          (file-name-sans-versions "~rms/foo.~1~")
               => "~rms/foo"
          (file-name-sans-versions "~rms/foo~")
               => "~rms/foo"
          (file-name-sans-versions "~rms/foo")
               => "~rms/foo"

 -- Function: file-name-sans-extension filename
     This function returns FILENAME minus its "extension," if any.  The
     extension, in a file name, is the part that starts with the last
     `.' in the last name component.  For example,

          (file-name-sans-extension "foo.lose.c")
               => "foo.lose"
          (file-name-sans-extension "big.hack/foo")
               => "big.hack/foo"

\1f
File: lispref.info,  Node: Directory Names,  Next: Relative File Names,  Prev: File Name Components,  Up: File Names

35.8.2 Directory Names
----------------------

A "directory name" is the name of a directory.  A directory is a kind
of file, and it has a file name, which is related to the directory name
but not identical to it.  (This is not quite the same as the usual Unix
terminology.)  These two different names for the same entity are
related by a syntactic transformation.  On Unix, this is simple: a
directory name ends in a slash, whereas the directory's name as a file
lacks that slash.

   The difference between a directory name and its name as a file is
subtle but crucial.  When an XEmacs variable or function argument is
described as being a directory name, a file name of a directory is not
acceptable.

   The following two functions convert between directory names and file
names.  They do nothing special with environment variable substitutions
such as `$HOME', and the constructs `~', and `..'.

 -- Function: file-name-as-directory filename
     This function returns a string representing FILENAME in a form
     that the operating system will interpret as the name of a
     directory.  In Unix, this means appending a slash to the string.

          (file-name-as-directory "~rms/lewis")
               => "~rms/lewis/"

 -- Function: directory-file-name dirname
     This function returns a string representing DIRNAME in a form that
     the operating system will interpret as the name of a file.  On
     Unix, this means removing a final slash from the string.

          (directory-file-name "~lewis/")
               => "~lewis"

   Directory name abbreviations are useful for directories that are
normally accessed through symbolic links.  Sometimes the users recognize
primarily the link's name as "the name" of the directory, and find it
annoying to see the directory's "real" name.  If you define the link
name as an abbreviation for the "real" name, XEmacs shows users the
abbreviation instead.

   If you wish to convert a directory name to its abbreviation, use this
function:

 -- Function: abbreviate-file-name filename &optional hack-homedir
     This function applies abbreviations from `directory-abbrev-alist'
     to its argument, and substitutes `~' for the user's home directory.

     If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for
     the user's home directory.


 -- Variable: directory-abbrev-alist
     The variable `directory-abbrev-alist' contains an alist of
     abbreviations to use for file directories.  Each element has the
     form `(FROM . TO)', and says to replace FROM with TO when it
     appears in a directory name.  The FROM string is actually a
     regular expression; it should always start with `^'.  The function
     `abbreviate-file-name' performs these substitutions.

     You can set this variable in `site-init.el' to describe the
     abbreviations appropriate for your site.

     Here's an example, from a system on which file system `/home/fsf'
     and so on are normally accessed through symbolic links named `/fsf'
     and so on.

          (("^/home/fsf" . "/fsf")
           ("^/home/gp" . "/gp")
           ("^/home/gd" . "/gd"))

\1f
File: lispref.info,  Node: Relative File Names,  Next: File Name Expansion,  Prev: Directory Names,  Up: File Names

35.8.3 Absolute and Relative File Names
---------------------------------------

All the directories in the file system form a tree starting at the root
directory.  A file name can specify all the directory names starting
from the root of the tree; then it is called an "absolute" file name.
Or it can specify the position of the file in the tree relative to a
default directory; then it is called a "relative" file name.  On Unix,
an absolute file name starts with a slash or a tilde (`~'), and a
relative one does not.

 -- Function: file-name-absolute-p filename
     This function returns `t' if file FILENAME is an absolute file
     name, `nil' otherwise.

          (file-name-absolute-p "~rms/foo")
               => t
          (file-name-absolute-p "rms/foo")
               => nil
          (file-name-absolute-p "/user/rms/foo")
               => t

\1f
File: lispref.info,  Node: File Name Expansion,  Next: Unique File Names,  Prev: Relative File Names,  Up: File Names

35.8.4 Functions that Expand Filenames
--------------------------------------

"Expansion" of a file name means converting a relative file name to an
absolute one.  Since this is done relative to a default directory, you
must specify the default directory name as well as the file name to be
expanded.  Expansion also simplifies file names by eliminating
redundancies such as `./' and `NAME/../'.

 -- Function: expand-file-name filename &optional directory
     This function converts FILENAME to an absolute file name.  If
     DIRECTORY is supplied, it is the directory to start with if
     FILENAME is relative.  (The value of DIRECTORY should itself be an
     absolute directory name; it may start with `~'.)  Otherwise, the
     current buffer's value of `default-directory' is used.  For
     example:

          (expand-file-name "foo")
               => "/xcssun/users/rms/lewis/foo"
          (expand-file-name "../foo")
               => "/xcssun/users/rms/foo"
          (expand-file-name "foo" "/usr/spool/")
               => "/usr/spool/foo"
          (expand-file-name "$HOME/foo")
               => "/xcssun/users/rms/lewis/$HOME/foo"

     Filenames containing `.' or `..' are simplified to their canonical
     form:

          (expand-file-name "bar/../foo")
               => "/xcssun/users/rms/lewis/foo"

     `~/' at the beginning is expanded into the user's home directory.
     A `/' or `~' following a `/'.

     Note that `expand-file-name' does _not_ expand environment
     variables; only `substitute-in-file-name' does that.

 -- Function: file-relative-name filename &optional directory
     This function does the inverse of expansion--it tries to return a
     relative name that is equivalent to FILENAME when interpreted
     relative to DIRECTORY.

     If DIRECTORY is `nil' or omitted, the value of `default-directory'
     is used.

          (file-relative-name "/foo/bar" "/foo/")
               => "bar")
          (file-relative-name "/foo/bar" "/hack/")
               => "../foo/bar")

 -- Variable: default-directory
     The value of this buffer-local variable is the default directory
     for the current buffer.  It should be an absolute directory name;
     it may start with `~'.  This variable is local in every buffer.

     `expand-file-name' uses the default directory when its second
     argument is `nil'.

     On Unix systems, the value is always a string ending with a slash.

          default-directory
               => "/user/lewis/manual/"

 -- Function: substitute-in-file-name filename
     This function replaces environment variable references in FILENAME
     with the environment variable values.  Following standard Unix
     shell syntax, `$' is the prefix to substitute an environment
     variable value.

     The environment variable name is the series of alphanumeric
     characters (including underscores) that follow the `$'.  If the
     character following the `$' is a `{', then the variable name is
     everything up to the matching `}'.

     Here we assume that the environment variable `HOME', which holds
     the user's home directory name, has value `/xcssun/users/rms'.

          (substitute-in-file-name "$HOME/foo")
               => "/xcssun/users/rms/foo"

     After substitution, a `/' or `~' following a `/' is taken to be
     the start of an absolute file name that overrides what precedes
     it, so everything before that `/' or `~' is deleted.  For example:

          (substitute-in-file-name "bar/~/foo")
               => "~/foo"
          (substitute-in-file-name "/usr/local/$HOME/foo")
               => "/xcssun/users/rms/foo"

\1f
File: lispref.info,  Node: Unique File Names,  Next: File Name Completion,  Prev: File Name Expansion,  Up: File Names

35.8.5 Generating Unique File Names
-----------------------------------

Some programs need to write temporary files.  Here is the usual way to
construct a name for such a file:

     (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory)))

Here we use `(temp-directory)' to specify a directory for temporary
files--under Unix, it will normally evaluate to `"/tmp/"'.  The job of
`make-temp-name' is to prevent two different users or two different
processes from trying to use the same name.

 -- Function: temp-directory
     This function returns the name of the directory to use for
     temporary files.  Under Unix, this will be the value of `TMPDIR',
     defaulting to `/tmp'.  On Windows, this will be obtained from the
     `TEMP' or `TMP' environment variables, defaulting to `/'.

     Note that the `temp-directory' function does not exist under FSF
     Emacs.

 -- Function: make-temp-name prefix
     This function generates a temporary file name starting with
     PREFIX.  The Emacs process number forms part of the result, so
     there is no danger of generating a name being used by another
     process.

          (make-temp-name "/tmp/foo")
               => "/tmp/fooGaAQjC"

     In addition, this function makes an attempt to choose a name that
     does not specify an existing file.  To make this work, PREFIX
     should be an absolute file name.

     To avoid confusion, each Lisp application should preferably use a
     unique PREFIX to `make-temp-name'.

\1f
File: lispref.info,  Node: File Name Completion,  Next: User Name Completion,  Prev: Unique File Names,  Up: File Names

35.8.6 File Name Completion
---------------------------

This section describes low-level subroutines for completing a file
name.  For other completion functions, see *Note Completion::.

 -- Function: file-name-all-completions partial-filename directory
     This function returns a list of all possible completions for files
     whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
     The order of the completions is the order of the files in the
     directory, which is unpredictable and conveys no useful
     information.

     The argument PARTIAL-FILENAME must be a file name containing no
     directory part and no slash.  The current buffer's default
     directory is prepended to DIRECTORY, if DIRECTORY is not absolute.

     File names which end with any member of
     `completion-ignored-extensions' are not considered as possible
     completions for PARTIAL-FILENAME unless there is no other possible
     completion. `completion-ignored-extensions' is not applied to the
     names of directories.

     In the following example, suppose that the current default
     directory, `~rms/lewis', has five files whose names begin with `f':
     `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.

          (file-name-all-completions "f" "")
               => ("foo" "file~" "file.c.~2~"
                          "file.c.~1~" "file.c")

          (file-name-all-completions "fo" "")
               => ("foo")

 -- Function: file-name-completion partial-filename directory
     This function completes the file name PARTIAL-FILENAME in directory
     DIRECTORY.  It returns the longest prefix common to all file names
     in directory DIRECTORY that start with PARTIAL-FILENAME.

     If only one match exists and PARTIAL-FILENAME matches it exactly,
     the function returns `t'.  The function returns `nil' if directory
     DIRECTORY contains no name starting with PARTIAL-FILENAME.

     File names which end with any member of
     `completion-ignored-extensions' are not considered as possible
     completions for PARTIAL-FILENAME unless there is no other possible
     completion. `completion-ignored-extensions' is not applied to the
     names of directories.

     In the following example, suppose that the current default
     directory has five files whose names begin with `f': `foo',
     `file~', `file.c', `file.c.~1~', and `file.c.~2~'.

          (file-name-completion "fi" "")
               => "file"

          (file-name-completion "file.c.~1" "")
               => "file.c.~1~"

          (file-name-completion "file.c.~1~" "")
               => t

          (file-name-completion "file.c.~3" "")
               => nil

 -- User Option: completion-ignored-extensions
     `file-name-completion' usually ignores file names that end in any
     string in this list.  It does not ignore them when all the possible
     completions end in one of these suffixes or when a buffer showing
     all possible completions is displayed.

     A typical value might look like this:

          completion-ignored-extensions
               => (".o" ".elc" "~" ".dvi")