-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Specifier Type, Next: Font Instance Type, Prev: Glyph Type, Up: Window-System Types
+File: lispref.info, Node: Peeking and Discarding, Prev: Quoted Character Input, Up: Reading Input
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+Dialog Boxes
+************
+
+* Menu:
+
+* Dialog Box Format::
+* Dialog Box Functions::
+
+\1f
+File: lispref.info, Node: Dialog Box Format, Next: Dialog Box Functions, Up: Dialog Boxes
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+Buffer Tabs
+-----------
+
+Not documented yet.
+
+\1f
+File: lispref.info, Node: Progress Bars, Prev: Buffer Tabs, Up: Common Gutter Widgets
+
+Progress Bars
+-------------
+
+Not documented yet.
+
+\1f
+File: lispref.info, Node: Scrollbars, Next: Drag and Drop, Prev: Gutter, Up: Top
+
+Scrollbars
+**********
+
+Not yet documented.
+
+\1f
+File: lispref.info, Node: Drag and Drop, Next: Modes, Prev: Scrollbars, Up: Top
+
+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.
-Specifier Type
---------------
+ 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).
- (not yet documented)
+* 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: Font Instance Type, Next: Color Instance Type, Prev: Specifier Type, Up: Window-System Types
+File: lispref.info, Node: Supported Protocols, Next: Drop Interface, Up: Drag and Drop
+
+Supported Protocols
+===================
-Font Instance Type
-------------------
+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.
- (not yet documented)
+* 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: Color Instance Type, Next: Image Instance Type, Prev: Font Instance Type, Up: Window-System Types
+File: lispref.info, Node: OffiX DND, Next: CDE dt, Up: Supported Protocols
-Color Instance Type
--------------------
+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.
- (not yet documented)
+ 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: Image Instance Type, Next: Toolbar Button Type, Prev: Color Instance Type, Up: Window-System Types
+File: lispref.info, Node: CDE dt, Next: MSWindows OLE, Prev: OffiX DND, Up: Supported Protocols
-Image Instance Type
--------------------
+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).
- (not yet documented)
+ 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: Toolbar Button Type, Next: Subwindow Type, Prev: Image Instance Type, Up: Window-System Types
+File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols
-Toolbar Button Type
--------------------
+MSWindows OLE
+-------------
- (not yet documented)
+Only allows file drags and drops.
\1f
-File: lispref.info, Node: Subwindow Type, Next: X Resource Type, Prev: Toolbar Button Type, Up: Window-System Types
+File: lispref.info, Node: Loose ends, Prev: MSWindows OLE, Up: Supported Protocols
-Subwindow Type
---------------
+Loose ends
+----------
- (not yet documented)
+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: X Resource Type, Prev: Subwindow Type, Up: Window-System Types
+File: lispref.info, Node: Drop Interface, Next: Drag Interface, Prev: Supported Protocols, Up: Drag and Drop
-X Resource Type
----------------
+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.
- (not yet documented)
+ 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: Type Predicates, Next: Equality Predicates, Prev: Window-System Types, Up: Lisp Data Types
+File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop
-Type Predicates
-===============
+Drag Interface
+==============
- The XEmacs Lisp interpreter itself does not perform type checking on
-the actual arguments passed to functions when they are called. It could
-not do so, since function arguments in Lisp do not have declared data
-types, as they do in other programming languages. It is therefore up to
-the individual function to test whether each actual argument belongs to
-a type that the function can use.
+This describes the drag API (not implemented yet).
- All built-in functions do check the types of their actual arguments
-when appropriate, and signal a `wrong-type-argument' error if an
-argument is of the wrong type. For example, here is what happens if you
-pass an argument to `+' that it cannot handle:
+\1f
+File: lispref.info, Node: Modes, Next: Documentation, Prev: Drag and Drop, Up: Top
- (+ 2 'a)
- error--> Wrong type argument: integer-or-marker-p, a
+Major and Minor Modes
+*********************
- If you want your program to handle different types differently, you
-must do explicit type checking. The most common way to check the type
-of an object is to call a "type predicate" function. Emacs has a type
-predicate for each type, as well as some predicates for combinations of
-types.
+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.
- A type predicate function takes one argument; it returns `t' if the
-argument belongs to the appropriate type, and `nil' otherwise.
-Following a general Lisp convention for predicate functions, most type
-predicates' names end with `p'.
+ 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::.
- Here is an example which uses the predicates `listp' to check for a
-list and `symbolp' to check for a symbol.
+* Menu:
- (defun add-on (x)
- (cond ((symbolp x)
- ;; If X is a symbol, put it on LIST.
- (setq list (cons x list)))
- ((listp x)
- ;; If X is a list, add its elements to LIST.
- (setq list (append x list)))
- (t
- ;; We only handle symbols and lists.
- (error "Invalid argument %s in add-on" x))))
+* 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.
- Here is a table of predefined type predicates, in alphabetical order,
-with references to further information.
+\1f
+File: lispref.info, Node: Major Modes, Next: Minor Modes, Up: Modes
+
+Major Modes
+===========
+
+Major modes specialize XEmacs for editing particular kinds of text.
+Each buffer has only one major mode at a time.
+
+ 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.
+
+ 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.
-`annotationp'
- *Note annotationp: Annotation Primitives.
+* Menu:
-`arrayp'
- *Note arrayp: Array Functions.
+* 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.
-`atom'
- *Note atom: List-related Predicates.
+\1f
+File: lispref.info, Node: Major Mode Conventions, Next: Example Major Modes, Up: Major Modes
+
+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.
+
+ * 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::.
-`bit-vector-p'
- *Note bit-vector-p: Bit Vector Functions.
+\1f
+File: lispref.info, Node: Example Major Modes, Next: Auto Major Mode, Prev: Major Mode Conventions, Up: Major Modes
-`bitp'
- *Note bitp: Bit Vector Functions.
+Major Mode Examples
+-------------------
-`boolean-specifier-p'
- *Note boolean-specifier-p: Specifier Types.
+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.
-`buffer-glyph-p'
- *Note buffer-glyph-p: Glyph Types.
+\1f
+File: lispref.info, Node: Auto Major Mode, Next: Mode Help, Prev: Example Major Modes, Up: Major Modes
+
+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'.
-`buffer-live-p'
- *Note buffer-live-p: Killing Buffers.
+\1f
+File: lispref.info, Node: Mode Help, Next: Derived Modes, Prev: Auto Major Mode, Up: Major Modes
-`bufferp'
- *Note bufferp: Buffer Basics.
+Getting Help about a Major Mode
+-------------------------------
-`button-event-p'
- *Note button-event-p: Event Predicates.
+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.
-`button-press-event-p'
- *Note button-press-event-p: Event Predicates.
+ - Command: describe-mode
+ This function displays the documentation of the current major mode.
-`button-release-event-p'
- *Note button-release-event-p: Event Predicates.
+ 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::.)
-`case-table-p'
- *Note case-table-p: Case Tables.
+ - 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.
-`char-int-p'
- *Note char-int-p: Character Codes.
+\1f
+File: lispref.info, Node: Derived Modes, Prev: Mode Help, Up: Major Modes
-`char-or-char-int-p'
- *Note char-or-char-int-p: Character Codes.
+Defining Derived Modes
+----------------------
-`char-or-string-p'
- *Note char-or-string-p: Predicates for Strings.
+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'.
-`char-table-p'
- *Note char-table-p: Char Tables.
+ - 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.
-`characterp'
- *Note characterp: Predicates for Characters.
+ The new command VARIANT is defined to call the function PARENT,
+ then override certain aspects of that parent mode:
-`color-instance-p'
- *Note color-instance-p: Colors.
+ * 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.
-`color-pixmap-image-instance-p'
- *Note color-pixmap-image-instance-p: Image Instance Types.
+ * 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.
-`color-specifier-p'
- *Note color-specifier-p: Specifier Types.
+ * 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.
-`commandp'
- *Note commandp: Interactive Call.
+ * 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.)
-`compiled-function-p'
- *Note compiled-function-p: Compiled-Function Type.
+ 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'.
-`console-live-p'
- *Note console-live-p: Connecting to a Console or Device.
+ The argument DOCSTRING specifies the documentation string for the
+ new mode. If you omit DOCSTRING, `define-derived-mode' generates
+ a documentation string.
-`consolep'
- *Note consolep: Consoles and Devices.
+ Here is a hypothetical example:
-`consp'
- *Note consp: List-related Predicates.
+ (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)
-`database-live-p'
- *Note database-live-p: Connecting to a Database.
+\1f
+File: lispref.info, Node: Minor Modes, Next: Modeline Format, Prev: Major Modes, Up: Modes
-`databasep'
- *Note databasep: Databases.
+Minor Modes
+===========
-`device-live-p'
- *Note device-live-p: Connecting to a Console or Device.
+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.
-`device-or-frame-p'
- *Note device-or-frame-p: Basic Device Functions.
+ 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.
-`devicep'
- *Note devicep: Consoles and Devices.
+ 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.
-`eval-event-p'
- *Note eval-event-p: Event Predicates.
+ 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.
-`event-live-p'
- *Note event-live-p: Event Predicates.
+* Menu:
-`eventp'
- *Note eventp: Events.
+* Minor Mode Conventions:: Tips for writing a minor mode.
+* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
-`extent-live-p'
- *Note extent-live-p: Creating and Modifying Extents.
+\1f
+File: lispref.info, Node: Minor Mode Conventions, Next: Keymaps and Minor Modes, Up: Minor Modes
-`extentp'
- *Note extentp: Extents.
+Conventions for Writing Minor Modes
+-----------------------------------
-`face-boolean-specifier-p'
- *Note face-boolean-specifier-p: Specifier Types.
+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.
-`facep'
- *Note facep: Basic Face Functions.
+ In addition, there are several conventions that are specific to
+minor modes.
-`floatp'
- *Note floatp: Predicates on Numbers.
+ * 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".
-`font-instance-p'
- *Note font-instance-p: Fonts.
+ 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.
-`font-specifier-p'
- *Note font-specifier-p: Specifier Types.
+ If you want the minor mode to be enabled separately in each buffer,
+ make the variable buffer-local.
-`frame-live-p'
- *Note frame-live-p: Deleting Frames.
+ * 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.
-`framep'
- *Note framep: Frames.
+ 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.
-`functionp'
- (not yet documented)
+ 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.
-`generic-specifier-p'
- *Note generic-specifier-p: Specifier Types.
+ (setq transient-mark-mode
+ (if (null arg) (not transient-mark-mode)
+ (> (prefix-numeric-value arg) 0)))
-`glyphp'
- *Note glyphp: Glyphs.
+ * Add an element to `minor-mode-alist' for each minor mode (*note
+ Modeline Variables::). This element should be a list of the
+ following form:
-`hash-table-p'
- *Note hash-table-p: Hash Tables.
+ (MODE-VARIABLE STRING)
-`icon-glyph-p'
- *Note icon-glyph-p: Glyph Types.
+ 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.
-`image-instance-p'
- *Note image-instance-p: Images.
+ When you add an element to `minor-mode-alist', use `assq' to check
+ for an existing element, to avoid duplication. For example:
-`image-specifier-p'
- *Note image-specifier-p: Specifier Types.
+ (or (assq 'leif-mode minor-mode-alist)
+ (setq minor-mode-alist
+ (cons '(leif-mode " Leif") minor-mode-alist)))
-`integer-char-or-marker-p'
- *Note integer-char-or-marker-p: Predicates on Markers.
+\1f
+File: lispref.info, Node: Keymaps and Minor Modes, Prev: Minor Mode Conventions, Up: Minor Modes
-`integer-or-char-p'
- *Note integer-or-char-p: Predicates for Characters.
+Keymaps and Minor Modes
+-----------------------
-`integer-or-marker-p'
- *Note integer-or-marker-p: Predicates on Markers.
+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::.
-`integer-specifier-p'
- *Note integer-specifier-p: Specifier Types.
+ 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.)
-`integerp'
- *Note integerp: Predicates on Numbers.
+\1f
+File: lispref.info, Node: Modeline Format, Next: Hooks, Prev: Minor Modes, Up: Modes
-`itimerp'
- (not yet documented)
+Modeline Format
+===============
-`key-press-event-p'
- *Note key-press-event-p: Event Predicates.
+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.
-`keymapp'
- *Note keymapp: Creating Keymaps.
+ 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.
-`keywordp'
- (not yet documented)
+ `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).
-`listp'
- *Note listp: List-related Predicates.
+ 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.
-`markerp'
- *Note markerp: Predicates on Markers.
+ - Function: redraw-modeline &optional all
+ Force redisplay of the current buffer's modeline. If ALL is
+ non-`nil', then force redisplay of all modelines.
-`misc-user-event-p'
- *Note misc-user-event-p: Event Predicates.
+ The modeline is usually displayed in inverse video. This is
+controlled using the `modeline' face. *Note Faces::.
-`mono-pixmap-image-instance-p'
- *Note mono-pixmap-image-instance-p: Image Instance Types.
+* Menu:
-`motion-event-p'
- *Note motion-event-p: Event Predicates.
+* Modeline Data:: The data structure that controls the modeline.
+* Modeline Variables:: Variables used in that data structure.
+* %-Constructs:: Putting information into a modeline.
-`mouse-event-p'
- *Note mouse-event-p: Event Predicates.
+\1f
+File: lispref.info, Node: Modeline Data, Next: Modeline Variables, Up: Modeline Format
+
+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")
+ "-%-"))
-`natnum-specifier-p'
- *Note natnum-specifier-p: Specifier Types.
+\1f
+File: lispref.info, Node: Modeline Variables, Next: %-Constructs, Prev: Modeline Data, Up: Modeline Format
+
+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.
-`natnump'
- *Note natnump: Predicates on Numbers.
+\1f
+File: lispref.info, Node: %-Constructs, Prev: Modeline Variables, Up: Modeline Format
-`nlistp'
- *Note nlistp: List-related Predicates.
+`%'-Constructs in the ModeLine
+------------------------------
-`nothing-image-instance-p'
- *Note nothing-image-instance-p: Image Instance Types.
+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.
-`number-char-or-marker-p'
- *Note number-char-or-marker-p: Predicates on Markers.
+`%b'
+ The current buffer name, obtained with the `buffer-name' function.
+ *Note Buffer Names::.
-`number-or-marker-p'
- *Note number-or-marker-p: Predicates on Markers.
+`%f'
+ The visited file name, obtained with the `buffer-file-name'
+ function. *Note Buffer File Name::.
-`numberp'
- *Note numberp: Predicates on Numbers.
+`%F'
+ The name of the selected frame.
-`pointer-glyph-p'
- *Note pointer-glyph-p: Glyph Types.
+`%c'
+ The current column number of point.
-`pointer-image-instance-p'
- *Note pointer-image-instance-p: Image Instance Types.
+`%l'
+ The current line number of point.
-`process-event-p'
- *Note process-event-p: Event Predicates.
+`%*'
+ `%' if the buffer is read only (see `buffer-read-only');
+ `*' if the buffer is modified (see `buffer-modified-p');
+ `-' otherwise. *Note Buffer Modification::.
-`processp'
- *Note processp: Processes.
+`%+'
+ `*' 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::.
-`range-table-p'
- *Note range-table-p: Range Tables.
+`%&'
+ `*' if the buffer is modified, and `-' otherwise.
-`ringp'
- (not yet documented)
+`%s'
+ The status of the subprocess belonging to the current buffer,
+ obtained with `process-status'. *Note Process Information::.
-`sequencep'
- *Note sequencep: Sequence Functions.
+`%l'
+ The current line number.
-`specifierp'
- *Note specifierp: Specifiers.
+`%S'
+ The name of the selected frame; this is only meaningful under the
+ X Window System. *Note Frame Name::.
-`stringp'
- *Note stringp: Predicates for Strings.
+`%t'
+ Whether the visited file is a text file or a binary file. (This
+ is a meaningful distinction only on certain operating systems.)
-`subrp'
- *Note subrp: Function Cells.
+`%p'
+ The percentage of the buffer text above the *top* of window, or
+ `Top', `Bottom' or `All'.
-`subwindow-image-instance-p'
- *Note subwindow-image-instance-p: Image Instance Types.
+`%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'.
-`subwindowp'
- *Note subwindowp: Subwindows.
+`%n'
+ `Narrow' when narrowing is in effect; nothing otherwise (see
+ `narrow-to-region' in *Note Narrowing::).
-`symbolp'
- *Note symbolp: Symbols.
+`%C'
+ Under XEmacs/mule, the mnemonic for `buffer-file-coding-system'.
-`syntax-table-p'
- *Note syntax-table-p: Syntax Tables.
+`%['
+ An indication of the depth of recursive editing levels (not
+ counting minibuffer levels): one `[' for each editing level.
+ *Note Recursive Editing::.
-`text-image-instance-p'
- *Note text-image-instance-p: Image Instance Types.
+`%]'
+ One `]' for each recursive editing level (not counting minibuffer
+ levels).
-`timeout-event-p'
- *Note timeout-event-p: Event Predicates.
+`%%'
+ The character `%'--this is how to include a literal `%' in a
+ string in which `%'-constructs are allowed.
-`toolbar-button-p'
- *Note toolbar-button-p: Toolbar.
+`%-'
+ Dashes sufficient to fill the remainder of the modeline.
-`toolbar-specifier-p'
- *Note toolbar-specifier-p: Toolbar.
+ 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'.
-`user-variable-p'
- *Note user-variable-p: Defining Variables.
+`%m'
+ The value of `mode-name'.
-`vectorp'
- *Note vectorp: Vectors.
+`%M'
+ The value of `global-mode-string'. Currently, only `display-time'
+ modifies the value of `global-mode-string'.
-`weak-list-p'
- *Note weak-list-p: Weak Lists.
+\1f
+File: lispref.info, Node: Hooks, Prev: Modeline Format, Up: Modes
+
+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: 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.
-`window-configuration-p'
- *Note window-configuration-p: Window Configurations.
+\1f
+File: lispref.info, Node: Documentation, Next: Files, Prev: Modes, Up: Top
-`window-live-p'
- *Note window-live-p: Deleting Windows.
+Documentation
+*************
-`windowp'
- *Note windowp: Basic Windows.
+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.
- The most general way to check the type of an object is to call the
-function `type-of'. Recall that each object belongs to one and only
-one primitive type; `type-of' tells you which one (*note Lisp Data
-Types::). But `type-of' knows nothing about non-primitive types. In
-most cases, it is more convenient to use type predicates than `type-of'.
+ 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.
- - Function: type-of object
- This function returns a symbol naming the primitive type of
- OBJECT. The value is one of `bit-vector', `buffer', `char-table',
- `character', `charset', `coding-system', `cons', `color-instance',
- `compiled-function', `console', `database', `device', `event',
- `extent', `face', `float', `font-instance', `frame', `glyph',
- `hash-table', `image-instance', `integer', `keymap', `marker',
- `process', `range-table', `specifier', `string', `subr',
- `subwindow', `symbol', `toolbar-button', `tooltalk-message',
- `tooltalk-pattern', `vector', `weak-list', `window',
- `window-configuration', or `x-resource'.
+* Menu:
- (type-of 1)
- => integer
- (type-of 'nil)
- => symbol
- (type-of '()) ; `()' is `nil'.
- => symbol
- (type-of '(x))
- => cons
+* 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: Equality Predicates, Prev: Type Predicates, Up: Lisp Data Types
+File: lispref.info, Node: Documentation Basics, Next: Accessing Documentation, Up: Documentation
+
+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'.
-Equality Predicates
-===================
+\1f
+File: lispref.info, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation
- Here we describe two functions that test for equality between any two
-objects. Other functions test equality between objects of specific
-types, e.g., strings. For these predicates, see the appropriate chapter
-describing the data type.
-
- - Function: eq object1 object2
- This function returns `t' if OBJECT1 and OBJECT2 are the same
- object, `nil' otherwise. The "same object" means that a change in
- one will be reflected by the same change in the other.
-
- `eq' returns `t' if OBJECT1 and OBJECT2 are integers with the same
- value. Also, since symbol names are normally unique, if the
- arguments are symbols with the same name, they are `eq'. For
- other types (e.g., lists, vectors, strings), two arguments with
- the same contents or elements are not necessarily `eq' to each
- other: they are `eq' only if they are the same object.
-
- (The `make-symbol' function returns an uninterned symbol that is
- not interned in the standard `obarray'. When uninterned symbols
- are in use, symbol names are no longer unique. Distinct symbols
- with the same name are not `eq'. *Note Creating Symbols::.)
-
- NOTE: Under XEmacs 19, characters are really just integers, and
- thus characters and integers are `eq'. Under XEmacs 20, it was
- necessary to preserve remnants of this in function such as `old-eq'
- in order to maintain byte-code compatibility. Byte code compiled
- under any Emacs 19 will automatically have calls to `eq' mapped to
- `old-eq' when executed under XEmacs 20.
-
- (eq 'foo 'foo)
- => t
-
- (eq 456 456)
- => t
-
- (eq "asdf" "asdf")
- => nil
-
- (eq '(1 (2 (3))) '(1 (2 (3))))
- => nil
-
- (setq foo '(1 (2 (3))))
- => (1 (2 (3)))
- (eq foo foo)
- => t
- (eq foo '(1 (2 (3))))
- => nil
-
- (eq [(1 2) 3] [(1 2) 3])
- => nil
-
- (eq (point-marker) (point-marker))
- => nil
+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.
- - Function: old-eq obj1 obj2
- This function exists under XEmacs 20 and is exactly like `eq'
- except that it suffers from the char-int confoundance disease. In
- other words, it returns `t' if given a character and the
- equivalent integer, even though the objects are of different types!
- You should _not_ ever call this function explicitly in your code.
- However, be aware that all calls to `eq' in byte code compiled
- under version 19 map to `old-eq' in XEmacs 20. (Likewise for
- `old-equal', `old-memq', `old-member', `old-assq' and
- `old-assoc'.)
-
- ;; Remember, this does not apply under XEmacs 19.
- ?A
- => ?A
- (char-int ?A)
- => 65
- (old-eq ?A 65)
- => t ; Eek, we've been infected.
- (eq ?A 65)
- => nil ; We are still healthy.
-
- - Function: equal object1 object2
- This function returns `t' if OBJECT1 and OBJECT2 have equal
- components, `nil' otherwise. Whereas `eq' tests if its arguments
- are the same object, `equal' looks inside nonidentical arguments
- to see if their elements are the same. So, if two objects are
- `eq', they are `equal', but the converse is not always true.
-
- (equal 'foo 'foo)
- => t
-
- (equal 456 456)
- => t
-
- (equal "asdf" "asdf")
- => t
- (eq "asdf" "asdf")
- => nil
-
- (equal '(1 (2 (3))) '(1 (2 (3))))
- => t
- (eq '(1 (2 (3))) '(1 (2 (3))))
- => nil
-
- (equal [(1 2) 3] [(1 2) 3])
- => t
- (eq [(1 2) 3] [(1 2) 3])
- => nil
-
- (equal (point-marker) (point-marker))
- => t
-
- (eq (point-marker) (point-marker))
- => nil
+\1f
+File: lispref.info, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation
+
+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."
- Comparison of strings is case-sensitive.
+\1f
+File: lispref.info, Node: Describing Characters, Next: Help Functions, Prev: Keys in Documentation, Up: Documentation
+
+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"
- Note that in FSF GNU Emacs, comparison of strings takes into
- account their text properties, and you have to use `string-equal'
- if you want only the strings themselves compared. This difference
- does not exist in XEmacs; `equal' and `string-equal' always return
- the same value on the same strings.
+\1f
+File: lispref.info, Node: Help Functions, Next: Obsoleteness, Prev: Describing Characters, Up: Documentation
- (equal "asdf" "ASDF")
- => nil
+Help Functions
+==============
- Two distinct buffers are never `equal', even if their contents are
- the same.
+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'.
- The test for equality is implemented recursively, and circular lists
-may therefore cause infinite recursion (leading to an error).
+\1f
+File: lispref.info, Node: Obsoleteness, Prev: Help Functions, Up: Documentation
+
+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
+ 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".
+
+ - 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: Numbers, Next: Strings and Characters, Prev: Lisp Data Types, Up: Top
+File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top
-Numbers
-*******
+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::.
- XEmacs supports two numeric data types: "integers" and "floating
-point numbers". Integers are whole numbers such as -3, 0, #b0111,
-#xFEED, #o744. Their values are exact. The number prefixes `#b',
-`#o', and `#x' are supported to represent numbers in binary, octal, and
-hexadecimal notation (or radix). Floating point numbers are numbers
-with fractional parts, such as -4.5, 0.0, or 2.71828. They can also be
-expressed in exponential notation: 1.5e2 equals 150; in this example,
-`e2' stands for ten to the second power, and is multiplied by 1.5.
-Floating point values are not exact; they have a fixed, limited amount
-of precision.
+ 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:
-* Integer Basics:: Representation and range of integers.
-* Float Basics:: Representation and range of floating point.
-* Predicates on Numbers:: Testing for numbers.
-* Comparison of Numbers:: Equality and inequality predicates.
-* Numeric Conversions:: Converting float to integer and vice versa.
-* Arithmetic Operations:: How to add, subtract, multiply and divide.
-* Rounding Operations:: Explicitly rounding floating point numbers.
-* Bitwise Operations:: Logical and, or, not, shifting.
-* Math Functions:: Trig, exponential and logarithmic functions.
-* Random Numbers:: Obtaining random integers, predictable or not.
+* 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: Integer Basics, Next: Float Basics, Up: Numbers
+File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files
-Integer Basics
+Visiting Files
==============
- The range of values for an integer depends on the machine. The
-minimum range is -134217728 to 134217727 (28 bits; i.e., -2**27 to
-2**27 - 1), but some machines may provide a wider range. Many examples
-in this chapter assume an integer has 28 bits.
+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
+
+Functions for Visiting Files
+----------------------------
- The Lisp reader reads an integer as a sequence of digits with
-optional initial sign and optional final period.
+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.
- 1 ; The integer 1.
- 1. ; The integer 1.
- +1 ; Also the integer 1.
- -1 ; The integer -1.
- 268435457 ; Also the integer 1, due to overflow.
- 0 ; The integer 0.
- -0 ; The integer 0.
+ 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::.
- To understand how various functions work on integers, especially the
-bitwise operators (*note Bitwise Operations::), it is often helpful to
-view the numbers in their binary form.
+ - 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.
- In 28-bit binary, the decimal integer 5 looks like this:
+ 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.
- 0000 0000 0000 0000 0000 0000 0101
+ 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'.
-(We have inserted spaces between groups of 4 bits, and two spaces
-between groups of 8 bits, to make the binary integer easier to read.)
+ The `find-file-noselect' function returns the buffer that is
+ visiting the file FILENAME.
- The integer -1 looks like this:
+ (find-file-noselect "/etc/fstab")
+ => #<buffer fstab>
- 1111 1111 1111 1111 1111 1111 1111
+ - 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::.
--1 is represented as 28 ones. (This is called "two's complement"
-notation.)
+ When this command is called interactively, it prompts for FILENAME.
- The negative integer, -5, is creating by subtracting 4 from -1. In
-binary, the decimal integer 4 is 100. Consequently, -5 looks like this:
+ - 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.
- 1111 1111 1111 1111 1111 1111 1011
+ When this command is called interactively, it prompts for FILENAME.
- In this implementation, the largest 28-bit binary integer is the
-decimal integer 134,217,727. In binary, it looks like this:
+ - 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::.
- 0111 1111 1111 1111 1111 1111 1111
+ When `view-file' is called interactively, it prompts for FILENAME.
- Since the arithmetic functions do not check whether integers go
-outside their range, when you add 1 to 134,217,727, the value is the
-negative integer -134,217,728:
+ With non-`nil' prefix arg OTHER-WINDOW-P, visit FILENAME in
+ another window.
- (+ 1 134217727)
- => -134217728
- => 1000 0000 0000 0000 0000 0000 0000
+ - 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.
- Many of the following functions accept markers for arguments as well
-as integers. (*Note Markers::.) More precisely, the actual arguments
-to such functions may be either integers or markers, which is why we
-often give these arguments the name INT-OR-MARKER. When the argument
-value is a marker, its position value is used and its buffer is ignored.
+ 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: Float Basics, Next: Predicates on Numbers, Prev: Integer Basics, Up: Numbers
+File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files
-Floating Point Basics
-=====================
+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::).
- XEmacs supports floating point numbers. The precise range of
-floating point numbers is machine-specific; it is the same as the range
-of the C data type `double' on the machine in question.
+ - 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::).
- The printed representation for floating point numbers requires either
-a decimal point (with at least one digit following), an exponent, or
-both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4'
-are five ways of writing a floating point number whose value is 1500.
-They are all equivalent. You can also use a minus sign to write
-negative floating point numbers, as in `-1.0'.
+ 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'.
- Most modern computers support the IEEE floating point standard, which
-provides for positive infinity and negative infinity as floating point
-values. It also provides for a class of values called NaN or
-"not-a-number"; numerical functions return such values in cases where
-there is no correct answer. For example, `(sqrt -1.0)' returns a NaN.
-For practical purposes, there's no significant difference between
-different NaN values in XEmacs Lisp, and there's no rule for precisely
-which NaN value should be used in a particular case, so this manual
-doesn't try to distinguish them. XEmacs Lisp has no read syntax for
-NaNs or infinities; perhaps we should create a syntax in the future.
+ 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.
- You can use `logb' to extract the binary exponent of a floating
-point number (or estimate the logarithm of an integer):
+ If NOAUTO is non-`nil', then this function does not turn on
+ auto-save mode; otherwise, it does.
- - Function: logb number
- This function returns the binary exponent of NUMBER. More
- precisely, the value is the logarithm of NUMBER base 2, rounded
- down to an integer.
+ The last thing `after-find-file' does is call all the functions in
+ `find-file-hooks'.
\1f
-File: lispref.info, Node: Predicates on Numbers, Next: Comparison of Numbers, Prev: Float Basics, Up: Numbers
+File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files
-Type Predicates for Numbers
-===========================
+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
- The functions in this section test whether the argument is a number
-or whether it is a certain sort of number. The functions `integerp'
-and `floatp' can take any type of Lisp object as argument (the
-predicates would not be of much use otherwise); but the `zerop'
-predicate requires a number as its argument. See also
-`integer-or-marker-p', `integer-char-or-marker-p', `number-or-marker-p'
-and `number-char-or-marker-p', in *Note Predicates on Markers::.
+Reading from Files
+==================
- - Function: floatp object
- This predicate tests whether its argument is a floating point
- number and returns `t' if so, `nil' otherwise.
+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.
- `floatp' does not exist in Emacs versions 18 and earlier.
+ - 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.
- - Function: integerp object
- This predicate tests whether its argument is an integer, and
- returns `t' if so, `nil' otherwise.
+ 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::.
- - Function: numberp object
- This predicate tests whether its argument is a number (either
- integer or floating point), and returns `t' if so, `nil' otherwise.
+ 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.
- - Function: natnump object
- The `natnump' predicate (whose name comes from the phrase
- "natural-number-p") tests to see whether its argument is a
- nonnegative integer, and returns `t' if so, `nil' otherwise. 0 is
- considered non-negative.
+ 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,
- - Function: zerop number
- This predicate tests whether its argument is zero, and returns `t'
- if so, `nil' otherwise. The argument must be a number.
+ (insert-file-contents filename nil 0 500)
- These two forms are equivalent: `(zerop x)' == `(= x 0)'.
+ 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: Comparison of Numbers, Next: Numeric Conversions, Prev: Predicates on Numbers, Up: Numbers
+File: lispref.info, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files
+
+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.
-Comparison of Numbers
-=====================
+\1f
+File: lispref.info, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files
+
+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:
- To test numbers for numerical equality, you should normally use `=',
-not `eq'. There can be many distinct floating point number objects
-with the same numeric value. If you use `eq' to compare them, then you
-test whether two values are the same _object_. By contrast, `='
-compares only the numeric values of the objects.
-
- At present, each integer value has a unique Lisp object in XEmacs
-Lisp. Therefore, `eq' is equivalent to `=' where integers are
-concerned. It is sometimes convenient to use `eq' for comparing an
-unknown value with an integer, because `eq' does not report an error if
-the unknown value is not a number--it accepts arguments of any type.
-By contrast, `=' signals an error if the arguments are not numbers or
-markers. However, it is a good idea to use `=' if you can, even for
-comparing integers, just in case we change the representation of
-integers in a future XEmacs version.
-
- There is another wrinkle: because floating point arithmetic is not
-exact, it is often a bad idea to check for equality of two floating
-point values. Usually it is better to test for approximate equality.
-Here's a function to do this:
-
- (defconst fuzz-factor 1.0e-6)
- (defun approx-equal (x y)
- (or (and (= x 0) (= y 0))
- (< (/ (abs (- x y))
- (max (abs x) (abs y)))
- fuzz-factor)))
-
- Common Lisp note: Comparing numbers in Common Lisp always requires
- `=' because Common Lisp implements multi-word integers, and two
- distinct integer objects can have the same numeric value. XEmacs
- Lisp can have just one integer object for any given value because
- it has a limited range of integer values.
-
- In addition to numbers, all of the following functions also accept
-characters and markers as arguments, and treat them as their number
-equivalents.
-
- - Function: = number &rest more-numbers
- This function returns `t' if all of its arguments are numerically
- equal, `nil' otherwise.
-
- (= 5)
+ 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
+
+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
+
+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
- (= 5 6)
- => nil
- (= 5 5.0)
+ (file-exists-p "/usr/spool/mqueue")
=> t
- (= 5 5 6)
+ (file-readable-p "/usr/spool/mqueue")
=> nil
- - Function: /= number &rest more-numbers
- This function returns `t' if no two arguments are numerically
- equal, `nil' otherwise.
-
- (/= 5 6)
+ - 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
- (/= 5 5 6)
+ (file-writable-p "/foo")
+ => nil
+ (file-writable-p "~/no-such-dir/foo")
=> nil
- (/= 5 6 1)
- => t
- - Function: < number &rest more-numbers
- This function returns `t' if the sequence of its arguments is
- monotonically increasing, `nil' otherwise.
+ - 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.
- (< 5 6)
- => t
- (< 5 6 6)
+ Example: after the following,
+
+ (file-accessible-directory-p "/foo")
=> nil
- (< 5 6 7)
- => t
- - Function: <= number &rest more-numbers
- This function returns `t' if the sequence of its arguments is
- monotonically nondecreasing, `nil' otherwise.
+ we can deduce that any attempt to read a file in `/foo/' will give
+ an error.
- (<= 5 6)
+ - 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
- (<= 5 6 6)
+ (file-newer-than-file-p "aug-19" "no-file")
=> t
- (<= 5 6 5)
+ (file-newer-than-file-p "no-file" "aug-19")
=> nil
- - Function: > number &rest more-numbers
- This function returns `t' if the sequence of its arguments is
- monotonically decreasing, `nil' otherwise.
+ You can use `file-attributes' to get a file's last modification
+ time as a list of two numbers. *Note File Attributes::.
- - Function: >= number &rest more-numbers
- This function returns `t' if the sequence of its arguments is
- monotonically nonincreasing, `nil' otherwise.
+\1f
+File: lispref.info, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files
- - Function: max number &rest more-numbers
- This function returns the largest of its arguments.
+Distinguishing Kinds of Files
+-----------------------------
- (max 20)
- => 20
- (max 1 2.5)
- => 2.5
- (max 1 3 2.5)
- => 3
+This section describes how to distinguish various kinds of files, such
+as directories, symbolic links, and ordinary files.
- - Function: min number &rest more-numbers
- This function returns the smallest of its arguments.
+ - 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.
- (min -4 1)
- => -4
+ If the file FILENAME is not a symbolic link (or there is no such
+ file), `file-symlink-p' returns `nil'.
-\1f
-File: lispref.info, Node: Numeric Conversions, Next: Arithmetic Operations, Prev: Comparison of Numbers, Up: Numbers
+ (file-symlink-p "foo")
+ => nil
+ (file-symlink-p "sym-link")
+ => "foo"
+ (file-symlink-p "sym-link2")
+ => "sym-link"
+ (file-symlink-p "/bin")
+ => "/pub/bin"
-Numeric Conversions
-===================
- To convert an integer to floating point, use the function `float'.
+ - Function: file-directory-p filename
+ This function returns `t' if FILENAME is the name of an existing
+ directory, `nil' otherwise.
- - Function: float number
- This returns NUMBER converted to floating point. If NUMBER is
- already a floating point number, `float' returns it unchanged.
+ (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).
- There are four functions to convert floating point numbers to
-integers; they differ in how they round. These functions accept
-integer arguments also, and return such arguments unchanged.
+\1f
+File: lispref.info, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files
- - Function: truncate number
- This returns NUMBER, converted to an integer by rounding towards
- zero.
+Truenames
+---------
- - Function: floor number &optional divisor
- This returns NUMBER, converted to an integer by rounding downward
- (towards negative infinity).
+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.
- If DIVISOR is specified, NUMBER is divided by DIVISOR before the
- floor is taken; this is the division operation that corresponds to
- `mod'. An `arith-error' results if DIVISOR is 0.
+ - 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.
- - Function: ceiling number
- This returns NUMBER, converted to an integer by rounding upward
- (towards positive infinity).
+ 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.
- - Function: round number
- This returns NUMBER, converted to an integer by rounding towards
- the nearest integer. Rounding a value equidistant between two
- integers may choose the integer closer to zero, or it may prefer
- an even integer, depending on your machine.
+ *Note Buffer File Name::, for related information.
\1f
-File: lispref.info, Node: Arithmetic Operations, Next: Rounding Operations, Prev: Numeric Conversions, Up: Numbers
+File: lispref.info, Node: File Attributes, Prev: Truenames, Up: Information about Files
+
+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
-Arithmetic Operations
-=====================
+ - Function: file-attributes filename
+ This function returns a list of attributes of file FILENAME. If
+ the specified file cannot be opened, it returns `nil'.
- XEmacs Lisp provides the traditional four arithmetic operations:
-addition, subtraction, multiplication, and division. Remainder and
-modulus functions supplement the division functions. The functions to
-add or subtract 1 are provided because they are traditional in Lisp and
-commonly used.
+ The elements of the list, in order, are:
- All of these functions except `%' return a floating point value if
-any argument is floating.
+ 0. `t' for a directory, a string for a symbolic link (the name
+ linked to), or `nil' for a text file.
- It is important to note that in XEmacs Lisp, arithmetic functions do
-not check for overflow. Thus `(1+ 134217727)' may evaluate to
--134217728, depending on your hardware.
+ 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::).
- - Function: 1+ number-or-marker
- This function returns NUMBER-OR-MARKER plus 1. For example,
+ 2. The file's UID.
- (setq foo 4)
- => 4
- (1+ foo)
- => 5
+ 3. The file's GID.
- This function is not analogous to the C operator `++'--it does not
- increment a variable. It just computes a sum. Thus, if we
- continue,
+ 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::.)
- foo
- => 4
+ 5. The time of last modification as a list of two integers (as
+ above).
- If you want to increment the variable, you must use `setq', like
- this:
+ 6. The time of last status change as a list of two integers (as
+ above).
- (setq foo (1+ foo))
- => 5
-
- Now that the `cl' package is always available from lisp code, a
- more convenient and natural way to increment a variable is
- `(incf foo)'.
-
- - Function: 1- number-or-marker
- This function returns NUMBER-OR-MARKER minus 1.
-
- - Function: abs number
- This returns the absolute value of NUMBER.
-
- - Function: + &rest numbers-or-markers
- This function adds its arguments together. When given no
- arguments, `+' returns 0.
-
- (+)
- => 0
- (+ 1)
- => 1
- (+ 1 2 3 4)
- => 10
-
- - Function: - &optional number-or-marker &rest other-numbers-or-markers
- The `-' function serves two purposes: negation and subtraction.
- When `-' has a single argument, the value is the negative of the
- argument. When there are multiple arguments, `-' subtracts each of
- the OTHER-NUMBERS-OR-MARKERS from NUMBER-OR-MARKER, cumulatively.
- If there are no arguments, the result is 0.
-
- (- 10 1 2 3 4)
- => 0
- (- 10)
- => -10
- (-)
- => 0
-
- - Function: * &rest numbers-or-markers
- This function multiplies its arguments together, and returns the
- product. When given no arguments, `*' returns 1.
-
- (*)
- => 1
- (* 1)
- => 1
- (* 1 2 3 4)
- => 24
+ 7. The size of the file in bytes.
- - Function: / dividend divisor &rest divisors
- This function divides DIVIDEND by DIVISOR and returns the
- quotient. If there are additional arguments DIVISORS, then it
- divides DIVIDEND by each divisor in turn. Each argument may be a
- number or a marker.
-
- If all the arguments are integers, then the result is an integer
- too. This means the result has to be rounded. On most machines,
- the result is rounded towards zero after each division, but some
- machines may round differently with negative arguments. This is
- because the Lisp function `/' is implemented using the C division
- operator, which also permits machine-dependent rounding. As a
- practical matter, all known machines round in the standard fashion.
-
- If you divide by 0, an `arith-error' error is signaled. (*Note
- Errors::.)
-
- (/ 6 2)
- => 3
- (/ 5 2)
- => 2
- (/ 25 3 2)
- => 4
- (/ -17 6)
- => -2
+ 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.
- The result of `(/ -17 6)' could in principle be -3 on some
- machines.
+ 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.
- - Function: % dividend divisor
- This function returns the integer remainder after division of
- DIVIDEND by DIVISOR. The arguments must be integers or markers.
+ For example, here are the file attributes for `files.texi':
- For negative arguments, the remainder is in principle
- machine-dependent since the quotient is; but in practice, all
- known machines behave alike.
+ (file-attributes "files.texi")
+ => (nil
+ 1
+ 2235
+ 75
+ (8489 20284)
+ (8489 20284)
+ (8489 20285)
+ 14906
+ "-rw-rw-rw-"
+ nil
+ 129500
+ -32252)
- An `arith-error' results if DIVISOR is 0.
+ and here is how the result is interpreted:
- (% 9 4)
- => 1
- (% -9 4)
- => -1
- (% 9 -4)
- => 1
- (% -9 -4)
- => -1
+ `nil'
+ is neither a directory nor a symbolic link.
- For any two integers DIVIDEND and DIVISOR,
+ `1'
+ has only one name (the name `files.texi' in the current
+ default directory).
- (+ (% DIVIDEND DIVISOR)
- (* (/ DIVIDEND DIVISOR) DIVISOR))
+ `2235'
+ is owned by the user with UID 2235.
- always equals DIVIDEND.
+ `75'
+ is in the group with GID 75.
- - Function: mod dividend divisor
- This function returns the value of DIVIDEND modulo DIVISOR; in
- other words, the remainder after division of DIVIDEND by DIVISOR,
- but with the same sign as DIVISOR. The arguments must be numbers
- or markers.
+ `(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::.
- Unlike `%', `mod' returns a well-defined result for negative
- arguments. It also permits floating point arguments; it rounds the
- quotient downward (towards minus infinity) to an integer, and uses
- that quotient to compute the remainder.
+ `(8489 20284)'
+ was last modified on Aug 19 00:09.
- An `arith-error' results if DIVISOR is 0.
+ `(8489 20285)'
+ last had its inode changed on Aug 19 00:09.
- (mod 9 4)
- => 1
- (mod -9 4)
- => 3
- (mod 9 -4)
- => -3
- (mod -9 -4)
- => -1
- (mod 5.5 2.5)
- => .5
+ `14906'
+ is 14906 characters long.
- For any two numbers DIVIDEND and DIVISOR,
+ `"-rw-rw-rw-"'
+ has a mode of read and write access for the owner, group, and
+ world.
- (+ (mod DIVIDEND DIVISOR)
- (* (floor DIVIDEND DIVISOR) DIVISOR))
+ `nil'
+ would retain the same GID if it were recreated.
- always equals DIVIDEND, subject to rounding error if either
- argument is floating point. For `floor', see *Note Numeric
- Conversions::.
+ `129500'
+ has an inode number of 129500.
+
+ `-32252'
+ is on file system number -32252.
\1f
-File: lispref.info, Node: Rounding Operations, Next: Bitwise Operations, Prev: Arithmetic Operations, Up: Numbers
+File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files
-Rounding Operations
-===================
+Changing File Names and Attributes
+==================================
- The functions `ffloor', `fceiling', `fround' and `ftruncate' take a
-floating point argument and return a floating point result whose value
-is a nearby integer. `ffloor' returns the nearest integer below;
-`fceiling', the nearest integer above; `ftruncate', the nearest integer
-in the direction towards zero; `fround', the nearest integer.
+The functions in this section rename, copy, delete, link, and set the
+modes of files.
- - Function: ffloor float
- This function rounds FLOAT to the next lower integral value, and
- returns that value as a floating point number.
+ 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:
- - Function: fceiling float
- This function rounds FLOAT to the next higher integral value, and
- returns that value as a floating point number.
+ * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is
+ `nil'.
- - Function: ftruncate float
- This function rounds FLOAT towards zero to an integral value, and
- returns that value as a floating point number.
+ * Request confirmation if OK-IF-ALREADY-EXISTS is a number. This is
+ what happens when the function is invoked interactively.
- - Function: fround float
- This function rounds FLOAT to the nearest integral value, and
- returns that value as a floating point number.
+ * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
+ is any other value.
-\1f
-File: lispref.info, Node: Bitwise Operations, Next: Math Functions, Prev: Rounding Operations, Up: Numbers
+ - 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'.
-Bitwise Operations on Integers
-==============================
+ % 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
- In a computer, an integer is represented as a binary number, a
-sequence of "bits" (digits which are either zero or one). A bitwise
-operation acts on the individual bits of such a sequence. For example,
-"shifting" moves the whole sequence left or right one or more places,
-reproducing the same pattern "moved over".
+ 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'.
- The bitwise operations in XEmacs Lisp apply only to integers.
+ (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
- - Function: lsh integer1 count
- `lsh', which is an abbreviation for "logical shift", shifts the
- bits in INTEGER1 to the left COUNT places, or to the right if
- COUNT is negative, bringing zeros into the vacated bits. If COUNT
- is negative, `lsh' shifts zeros into the leftmost
- (most-significant) bit, producing a positive result even if
- INTEGER1 is negative. Contrast this with `ash', below.
+ Finally, we evaluate the following:
- Here are two examples of `lsh', shifting a pattern of bits one
- place to the left. We show only the low-order eight bits of the
- binary pattern; the rest are all zero.
+ (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
- (lsh 5 1)
- => 10
- ;; Decimal 5 becomes decimal 10.
- 00000101 => 00001010
+ 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
- (lsh 7 1)
- => 14
- ;; Decimal 7 becomes decimal 14.
- 00000111 => 00001110
+ % 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
- As the examples illustrate, shifting the pattern of bits one place
- to the left produces a number that is twice the value of the
- previous number.
+ This function is meaningless on non-Unix systems, where multiple
+ names for one file are not allowed.
- Shifting a pattern of bits two places to the left produces results
- like this (with 8-bit binary numbers):
+ See also `file-nlinks' in *Note File Attributes::.
- (lsh 3 2)
- => 12
- ;; Decimal 3 becomes decimal 12.
- 00000011 => 00001100
+ - Command: rename-file filename newname &optional ok-if-already-exists
+ This command renames the file FILENAME as NEWNAME.
- On the other hand, shifting one place to the right looks like this:
+ 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.
- (lsh 6 -1)
- => 3
- ;; Decimal 6 becomes decimal 3.
- 00000110 => 00000011
-
- (lsh 5 -1)
- => 2
- ;; Decimal 5 becomes decimal 2.
- 00000101 => 00000010
+ In an interactive call, this function prompts for FILENAME and
+ NEWNAME in the minibuffer; also, it requests confirmation if
+ NEWNAME already exists.
- As the example illustrates, shifting one place to the right
- divides the value of a positive integer by two, rounding downward.
+ - 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.
- The function `lsh', like all XEmacs Lisp arithmetic functions, does
- not check for overflow, so shifting left can discard significant
- bits and change the sign of the number. For example, left shifting
- 134,217,727 produces -2 on a 28-bit machine:
+ 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.)
- (lsh 134217727 1) ; left shift
- => -2
+ In an interactive call, this function prompts for FILENAME and
+ NEWNAME in the minibuffer; also, it requests confirmation if
+ NEWNAME already exists.
- In binary, in the 28-bit implementation, the argument looks like
- this:
+ - 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.
- ;; Decimal 134,217,727
- 0111 1111 1111 1111 1111 1111 1111
+ 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.)
- which becomes the following when left shifted:
+ See also `delete-directory' in *Note Create/Delete Dirs::.
- ;; Decimal -2
- 1111 1111 1111 1111 1111 1111 1110
+ - 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'.
- - Function: ash integer1 count
- `ash' ("arithmetic shift") shifts the bits in INTEGER1 to the left
- COUNT places, or to the right if COUNT is negative.
+ In an interactive call, this function prompts for FILENAME and
+ NEWNAME in the minibuffer; also, it requests confirmation if
+ NEWNAME already exists.
- `ash' gives the same results as `lsh' except when INTEGER1 and
- COUNT are both negative. In that case, `ash' puts ones in the
- empty bit positions on the left, while `lsh' puts zeros in those
- bit positions.
+ - 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.
- Thus, with `ash', shifting the pattern of bits one place to the
- right looks like this:
+ - 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.
- (ash -6 -1) => -3
- ;; Decimal -6 becomes decimal -3.
- 1111 1111 1111 1111 1111 1111 1010
- =>
- 1111 1111 1111 1111 1111 1111 1101
+ The argument MODE must be an integer. Only the low 9 bits of MODE
+ are used.
- In contrast, shifting the pattern of bits one place to the right
- with `lsh' looks like this:
+ 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.
- (lsh -6 -1) => 134217725
- ;; Decimal -6 becomes decimal 134,217,725.
- 1111 1111 1111 1111 1111 1111 1010
- =>
- 0111 1111 1111 1111 1111 1111 1101
+ - Function: default-file-modes
+ This function returns the current default protection value.
- Here are other examples:
+ 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'.
- ; 28-bit binary values
-
- (lsh 5 2) ; 5 = 0000 0000 0000 0000 0000 0000 0101
- => 20 ; = 0000 0000 0000 0000 0000 0001 0100
- (ash 5 2)
- => 20
- (lsh -5 2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
- => -20 ; = 1111 1111 1111 1111 1111 1110 1100
- (ash -5 2)
- => -20
- (lsh 5 -2) ; 5 = 0000 0000 0000 0000 0000 0000 0101
- => 1 ; = 0000 0000 0000 0000 0000 0000 0001
- (ash 5 -2)
- => 1
- (lsh -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
- => 4194302 ; = 0011 1111 1111 1111 1111 1111 1110
- (ash -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
- => -2 ; = 1111 1111 1111 1111 1111 1111 1110
-
- - Function: logand &rest ints-or-markers
- This function returns the "logical and" of the arguments: the Nth
- bit is set in the result if, and only if, the Nth bit is set in
- all the arguments. ("Set" means that the value of the bit is 1
- rather than 0.)
-
- For example, using 4-bit binary numbers, the "logical and" of 13
- and 12 is 12: 1101 combined with 1100 produces 1100. In both the
- binary numbers, the leftmost two bits are set (i.e., they are
- 1's), so the leftmost two bits of the returned value are set.
- However, for the rightmost two bits, each is zero in at least one
- of the arguments, so the rightmost two bits of the returned value
- are 0's.
-
- Therefore,
-
- (logand 13 12)
- => 12
-
- If `logand' is not passed any argument, it returns a value of -1.
- This number is an identity element for `logand' because its binary
- representation consists entirely of ones. If `logand' is passed
- just one argument, it returns that argument.
-
- ; 28-bit binary values
-
- (logand 14 13) ; 14 = 0000 0000 0000 0000 0000 0000 1110
- ; 13 = 0000 0000 0000 0000 0000 0000 1101
- => 12 ; 12 = 0000 0000 0000 0000 0000 0000 1100
-
- (logand 14 13 4) ; 14 = 0000 0000 0000 0000 0000 0000 1110
- ; 13 = 0000 0000 0000 0000 0000 0000 1101
- ; 4 = 0000 0000 0000 0000 0000 0000 0100
- => 4 ; 4 = 0000 0000 0000 0000 0000 0000 0100
-
- (logand)
- => -1 ; -1 = 1111 1111 1111 1111 1111 1111 1111
+\1f
+File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files
- - Function: logior &rest ints-or-markers
- This function returns the "inclusive or" of its arguments: the Nth
- bit is set in the result if, and only if, the Nth bit is set in at
- least one of the arguments. If there are no arguments, the result
- is zero, which is an identity element for this operation. If
- `logior' is passed just one argument, it returns that argument.
+File Names
+==========
- ; 28-bit binary values
-
- (logior 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100
- ; 5 = 0000 0000 0000 0000 0000 0000 0101
- => 13 ; 13 = 0000 0000 0000 0000 0000 0000 1101
-
- (logior 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100
- ; 5 = 0000 0000 0000 0000 0000 0000 0101
- ; 7 = 0000 0000 0000 0000 0000 0000 0111
- => 15 ; 15 = 0000 0000 0000 0000 0000 0000 1111
-
- - Function: logxor &rest ints-or-markers
- This function returns the "exclusive or" of its arguments: the Nth
- bit is set in the result if, and only if, the Nth bit is set in an
- odd number of the arguments. If there are no arguments, the
- result is 0, which is an identity element for this operation. If
- `logxor' is passed just one argument, it returns that argument.
-
- ; 28-bit binary values
-
- (logxor 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100
- ; 5 = 0000 0000 0000 0000 0000 0000 0101
- => 9 ; 9 = 0000 0000 0000 0000 0000 0000 1001
-
- (logxor 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100
- ; 5 = 0000 0000 0000 0000 0000 0000 0101
- ; 7 = 0000 0000 0000 0000 0000 0000 0111
- => 14 ; 14 = 0000 0000 0000 0000 0000 0000 1110
+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.
- - Function: lognot integer
- This function returns the logical complement of its argument: the
- Nth bit is one in the result if, and only if, the Nth bit is zero
- in INTEGER, and vice-versa.
+ 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.
- (lognot 5)
- => -6
- ;; 5 = 0000 0000 0000 0000 0000 0000 0101
- ;; becomes
- ;; -6 = 1111 1111 1111 1111 1111 1111 1010
+ 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: Math Functions, Next: Random Numbers, Prev: Bitwise Operations, Up: Numbers
+File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names
-Standard Mathematical Functions
-===============================
+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
+
+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.
- These mathematical functions are available if floating point is
-supported (which is the normal state of affairs). They allow integers
-as well as floating point numbers as arguments.
+ 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: sin arg
- - Function: cos arg
- - Function: tan arg
- These are the ordinary trigonometric functions, with argument
- measured in radians.
+ - 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.
- - Function: asin arg
- The value of `(asin ARG)' is a number between -pi/2 and pi/2
- (inclusive) whose sine is ARG; if, however, ARG is out of range
- (outside [-1, 1]), then the result is a NaN.
+ (file-name-as-directory "~rms/lewis")
+ => "~rms/lewis/"
- - Function: acos arg
- The value of `(acos ARG)' is a number between 0 and pi (inclusive)
- whose cosine is ARG; if, however, ARG is out of range (outside
- [-1, 1]), then the result is a NaN.
+ - 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.
- - Function: atan arg
- The value of `(atan ARG)' is a number between -pi/2 and pi/2
- (exclusive) whose tangent is ARG.
+ (directory-file-name "~lewis/")
+ => "~lewis"
- - Function: sinh arg
- - Function: cosh arg
- - Function: tanh arg
- These are the ordinary hyperbolic trigonometric functions.
+ 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.
- - Function: asinh arg
- - Function: acosh arg
- - Function: atanh arg
- These are the inverse hyperbolic trigonometric functions.
+ If you wish to convert a directory name to its abbreviation, use this
+function:
- - Function: exp arg
- This is the exponential function; it returns e to the power ARG.
- e is a fundamental mathematical constant also called the base of
- natural logarithms.
+ - 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.
- - Function: log arg &optional base
- This function returns the logarithm of ARG, with base BASE. If
- you don't specify BASE, the base E is used. If ARG is negative,
- the result is a NaN.
+ If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for
+ the user's home directory.
- - Function: log10 arg
- This function returns the logarithm of ARG, with base 10. If ARG
- is negative, the result is a NaN. `(log10 X)' == `(log X 10)', at
- least approximately.
- - Function: expt x y
- This function returns X raised to power Y. If both arguments are
- integers and Y is positive, the result is an integer; in this
- case, it is truncated to fit the range of possible integer values.
+ - 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.
- - Function: sqrt arg
- This returns the square root of ARG. If ARG is negative, the
- value is a NaN.
+ You can set this variable in `site-init.el' to describe the
+ abbreviations appropriate for your site.
- - Function: cube-root arg
- This returns the cube root of ARG.
+ 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: Random Numbers, Prev: Math Functions, Up: Numbers
+File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names
-Random Numbers
-==============
+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
+
+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
+
+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.
- A deterministic computer program cannot generate true random numbers.
-For most purposes, "pseudo-random numbers" suffice. A series of
-pseudo-random numbers is generated in a deterministic fashion. The
-numbers are not truly random, but they have certain properties that
-mimic a random series. For example, all possible values occur equally
-often in a pseudo-random series.
+ - 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 `/'.
- In XEmacs, pseudo-random numbers are generated from a "seed" number.
-Starting from any given seed, the `random' function always generates
-the same sequence of numbers. XEmacs always starts with the same seed
-value, so the sequence of values of `random' is actually the same in
-each XEmacs run! For example, in one operating system, the first call
-to `(random)' after you start XEmacs always returns -1457731, and the
-second one always returns -7692030. This repeatability is helpful for
-debugging.
+ Note that the `temp-directory' function does not exist under FSF
+ Emacs.
- If you want truly unpredictable random numbers, execute `(random
-t)'. This chooses a new seed based on the current time of day and on
-XEmacs's process ID number.
+ - 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.
- - Function: random &optional limit
- This function returns a pseudo-random integer. Repeated calls
- return a series of pseudo-random integers.
+ (make-temp-name "/tmp/foo")
+ => "/tmp/fooGaAQjC"
- If LIMIT is a positive integer, the value is chosen to be
- nonnegative and less than LIMIT.
+ 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.
- If LIMIT is `t', it means to choose a new seed based on the
- current time of day and on XEmacs's process ID number.
+ To avoid confusion, each Lisp application should preferably use a
+ unique PREFIX to `make-temp-name'.
- On some machines, any integer representable in Lisp may be the
- result of `random'. On other machines, the result can never be
- larger than a certain maximum or less than a certain (negative)
- minimum.
+\1f
+File: lispref.info, Node: File Name Completion, Next: User Name Completion, Prev: Unique File Names, Up: File Names
+
+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")
\1f
-File: lispref.info, Node: Strings and Characters, Next: Lists, Prev: Numbers, Up: Top
+File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names
-Strings and Characters
-**********************
+User Name Completion
+--------------------
- A string in XEmacs Lisp is an array that contains an ordered sequence
-of characters. Strings are used as names of symbols, buffers, and
-files, to send messages to users, to hold text being copied between
-buffers, and for many other purposes. Because strings are so important,
-XEmacs Lisp has many functions expressly for manipulating them. XEmacs
-Lisp programs use strings more often than individual characters.
+This section describes low-level subroutines for completing a user
+name. For other completion functions, see *Note Completion::.
-* Menu:
+ - Function: user-name-all-completions partial-username
+ This function returns a list of all possible completions for a
+ user name starting with PARTIAL-USERNAME. The order of the
+ completions is unpredictable and conveys no useful information.
+
+ The argument PARTIAL-USERNAME must be a partial user name
+ containing no tilde character and no slash.
-* String Basics:: Basic properties of strings and characters.
-* Predicates for Strings:: Testing whether an object is a string or char.
-* Creating Strings:: Functions to allocate new strings.
-* Predicates for Characters:: Testing whether an object is a character.
-* Character Codes:: Each character has an equivalent integer.
-* Text Comparison:: Comparing characters or strings.
-* String Conversion:: Converting characters or strings and vice versa.
-* Modifying Strings:: Changing characters in a string.
-* String Properties:: Additional information attached to strings.
-* Formatting Strings:: `format': XEmacs's analog of `printf'.
-* Character Case:: Case conversion functions.
-* Case Tables:: Customizing case conversion.
-* Char Tables:: Mapping from characters to Lisp objects.
+ - Function: user-name-completion partial-username
+ This function completes a user name from PARTIAL-USERNAME. It
+ returns the longest prefix common to all user names that start with
+ PARTIAL-USERNAME.
+
+ If only one match exists and PARTIAL-USERNAME matches it exactly,
+ the function returns `t'. The function returns `nil' if no user
+ name starting with PARTIAL-USERNAME exists.
+
+ - Function: user-name-completion-1 partial-username
+ This function completes the partial user name PARTIAL-USERNAME,
+ like `user-name-completion', differing only in the return value.
+ This function returns the cons of the completion returned by
+ `user-name-completion', and a boolean indicating whether that
+ completion was unique.
+
+\1f
+File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files
+
+Contents of Directories
+=======================
+
+A directory is a kind of file that contains other files entered under
+various names. Directories are a feature of the file system.
+
+ XEmacs can list the names of the files in a directory as a Lisp list,
+or display the names in a buffer using the `ls' shell command. In the
+latter case, it can optionally display information about each file,
+depending on the value of switches passed to the `ls' command.
+
+ - Function: directory-files directory &optional full-name match-regexp
+ nosort files-only
+ This function returns a list of the names of the files in the
+ directory DIRECTORY. By default, the list is in alphabetical
+ order.
+
+ If FULL-NAME is non-`nil', the function returns the files'
+ absolute file names. Otherwise, it returns just the names
+ relative to the specified directory.
+
+ If MATCH-REGEXP is non-`nil', this function returns only those
+ file names that contain that regular expression--the other file
+ names are discarded from the list.
+
+ If NOSORT is non-`nil', `directory-files' does not sort the list,
+ so you get the file names in no particular order. Use this if you
+ want the utmost possible speed and don't care what order the files
+ are processed in. If the order of processing is visible to the
+ user, then the user will probably be happier if you do sort the
+ names.
+
+ If FILES-ONLY is the symbol `t', then only the "files" in the
+ directory will be returned; subdirectories will be excluded. If
+ FILES-ONLY is not `nil' and not `t', then only the subdirectories
+ will be returned. Otherwise, if FILES-ONLY is `nil' (the default)
+ then both files and subdirectories will be returned.
+
+ (directory-files "~lewis")
+ => ("#foo#" "#foo.el#" "." ".."
+ "dired-mods.el" "files.texi"
+ "files.texi.~1~")
+
+ An error is signaled if DIRECTORY is not the name of a directory
+ that can be read.
+
+ - Function: insert-directory file switches &optional wildcard
+ full-directory-p
+ This function inserts (in the current buffer) a directory listing
+ for directory FILE, formatted with `ls' according to SWITCHES. It
+ leaves point after the inserted text.
+
+ The argument FILE may be either a directory name or a file
+ specification including wildcard characters. If WILDCARD is
+ non-`nil', that means treat FILE as a file specification with
+ wildcards.
+
+ If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
+ and switches do not contain `-d', so that the listing should show
+ the full contents of the directory. (The `-d' option to `ls' says
+ to describe a directory itself rather than its contents.)
+
+ This function works by running a directory listing program whose
+ name is in the variable `insert-directory-program'. If WILDCARD is
+ non-`nil', it also runs the shell specified by `shell-file-name',
+ to expand the wildcards.
+
+ - Variable: insert-directory-program
+ This variable's value is the program to run to generate a
+ directory listing for the function `insert-directory'.
projects / chise / xemacs-chise.git.1 / blobdiff