X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Fxemacs.info-18;h=5cadc3a038533bcfaea46598a382a091fd901691;hb=98769b42a33fd8236341ac4175165b2dab7ceae4;hp=1983b657c28b2eaf8519a74ea51d0da49f6c75e7;hpb=1d9bc86590766427e2431876a50d78206a99edd5;p=chise%2Fxemacs-chise.git diff --git a/info/xemacs.info-18 b/info/xemacs.info-18 index 1983b65..5cadc3a 100644 --- a/info/xemacs.info-18 +++ b/info/xemacs.info-18 @@ -1,4 +1,4 @@ -This is ../info/xemacs.info, produced by makeinfo version 4.0 from +This is ../info/xemacs.info, produced by makeinfo version 4.0b from xemacs/xemacs.texi. INFO-DIR-SECTION XEmacs Editor @@ -30,6 +30,862 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Keymaps, Next: Rebinding, Up: Key Bindings + +Keymaps +------- + + The bindings between characters and command functions are recorded in +data structures called "keymaps". Emacs has many of these. One, the +"global" keymap, defines the meanings of the single-character keys that +are defined regardless of major mode. It is the value of the variable +`global-map'. + + Each major mode has another keymap, its "local keymap", which +contains overriding definitions for the single-character keys that are +redefined in that mode. Each buffer records which local keymap is +installed for it at any time, and the current buffer's local keymap is +the only one that directly affects command execution. The local keymaps +for Lisp mode, C mode, and many other major modes always exist even when +not in use. They are the values of the variables `lisp-mode-map', +`c-mode-map', and so on. For less frequently used major modes, the +local keymap is sometimes constructed only when the mode is used for the +first time in a session, to save space. + + There are local keymaps for the minibuffer, too; they contain various +completion and exit commands. + + * `minibuffer-local-map' is used for ordinary input (no completion). + + * `minibuffer-local-ns-map' is similar, except that exits just + like . This is used mainly for Mocklisp compatibility. + + * `minibuffer-local-completion-map' is for permissive completion. + + * `minibuffer-local-must-match-map' is for strict completion and for + cautious completion. + + * `repeat-complex-command-map' is for use in `C-x '. + + * `isearch-mode-map' contains the bindings of the special keys which + are bound in the pseudo-mode entered with `C-s' and `C-r'. + + Finally, each prefix key has a keymap which defines the key sequences +that start with it. For example, `ctl-x-map' is the keymap used for +characters following a `C-x'. + + * `ctl-x-map' is the variable name for the map used for characters + that follow `C-x'. + + * `help-map' is used for characters that follow `C-h'. + + * `esc-map' is for characters that follow . All Meta characters + are actually defined by this map. + + * `ctl-x-4-map' is for characters that follow `C-x 4'. + + * `mode-specific-map' is for characters that follow `C-c'. + + The definition of a prefix key is the keymap to use for looking up +the following character. Sometimes the definition is actually a Lisp +symbol whose function definition is the following character keymap. The +effect is the same, but it provides a command name for the prefix key +that you can use as a description of what the prefix key is for. Thus +the binding of `C-x' is the symbol `Ctl-X-Prefix', whose function +definition is the keymap for `C-x' commands, the value of `ctl-x-map'. + + Prefix key definitions can appear in either the global map or a +local map. The definitions of `C-c', `C-x', `C-h', and as prefix +keys appear in the global map, so these prefix keys are always +available. Major modes can locally redefine a key as a prefix by +putting a prefix key definition for it in the local map. + + A mode can also put a prefix definition of a global prefix character +such as `C-x' into its local map. This is how major modes override the +definitions of certain keys that start with `C-x'. This case is +special, because the local definition does not entirely replace the +global one. When both the global and local definitions of a key are +other keymaps, the next character is looked up in both keymaps, with +the local definition overriding the global one. The character after the +`C-x' is looked up in both the major mode's own keymap for redefined +`C-x' commands and in `ctl-x-map'. If the major mode's own keymap for +`C-x' commands contains `nil', the definition from the global keymap +for `C-x' commands is used. + + +File: xemacs.info, Node: Rebinding, Next: Disabling, Prev: Keymaps, Up: Key Bindings + +Changing Key Bindings +--------------------- + + You can redefine an Emacs key by changing its entry in a keymap. +You can change the global keymap, in which case the change is effective +in all major modes except those that have their own overriding local +definitions for the same key. Or you can change the current buffer's +local map, which affects all buffers using the same major mode. + +* Menu: + +* Interactive Rebinding:: Changing Key Bindings Interactively +* Programmatic Rebinding:: Changing Key Bindings Programmatically +* Key Bindings Using Strings:: Using Strings for Changing Key Bindings + + +File: xemacs.info, Node: Interactive Rebinding, Next: Programmatic Rebinding, Up: Rebinding + +Changing Key Bindings Interactively +................................... + +`M-x global-set-key KEY CMD ' + Defines KEY globally to run CMD. + +`M-x local-set-key KEYS CMD ' + Defines KEY locally (in the major mode now in effect) to run CMD. + +`M-x local-unset-key KEYS ' + Removes the local binding of KEY. + + CMD is a symbol naming an interactively-callable function. + + When called interactively, KEY is the next complete key sequence +that you type. When called as a function, KEY is a string, a vector of +events, or a vector of key-description lists as described in the +`define-key' function description. The binding goes in the current +buffer's local map, which is shared with other buffers in the same +major mode. + + The following example: + + M-x global-set-key C-f next-line + +redefines `C-f' to move down a line. The fact that CMD is read second +makes it serve as a kind of confirmation for KEY. + + These functions offer no way to specify a particular prefix keymap as +the one to redefine in, but that is not necessary, as you can include +prefixes in KEY. KEY is read by reading characters one by one until +they amount to a complete key (that is, not a prefix key). Thus, if +you type `C-f' for KEY, Emacs enters the minibuffer immediately to read +CMD. But if you type `C-x', another character is read; if that +character is `4', another character is read, and so on. For example, + + M-x global-set-key C-x 4 $ spell-other-window + +redefines `C-x 4 $' to run the (fictitious) command +`spell-other-window'. + + The most general way to modify a keymap is the function +`define-key', used in Lisp code (such as your init file). `define-key' +takes three arguments: the keymap, the key to modify in it, and the new +definition. *Note Init File::, for an example. +`substitute-key-definition' is used similarly; it takes three +arguments, an old definition, a new definition, and a keymap, and +redefines in that keymap all keys that were previously defined with the +old definition to have the new definition instead. + + +File: xemacs.info, Node: Programmatic Rebinding, Next: Key Bindings Using Strings, Prev: Interactive Rebinding, Up: Rebinding + +Changing Key Bindings Programmatically +...................................... + + You can use the functions `global-set-key' and `define-key' to +rebind keys under program control. + +``(global-set-key KEYS CMD)'' + Defines KEYS globally to run CMD. + +``(define-key KEYMAP KEYS DEF)'' + Defines KEYS to run DEF in the keymap KEYMAP. + + KEYMAP is a keymap object. + + KEYS is the sequence of keystrokes to bind. + + DEF is anything that can be a key's definition: + + * `nil', meaning key is undefined in this keymap + + * A command, that is, a Lisp function suitable for interactive + calling + + * A string or key sequence vector, which is treated as a keyboard + macro + + * A keymap to define a prefix key + + * A symbol so that when the key is looked up, the symbol stands for + its function definition, which should at that time be one of the + above, or another symbol whose function definition is used, and so + on + + * A cons, `(string . defn)', meaning that DEFN is the definition + (DEFN should be a valid definition in its own right) + + * A cons, `(keymap . char)', meaning use the definition of CHAR in + map KEYMAP + + For backward compatibility, XEmacs allows you to specify key +sequences as strings. However, the preferred method is to use the +representations of key sequences as vectors of keystrokes. *Note +Keystrokes::, for more information about the rules for constructing key +sequences. + + Emacs allows you to abbreviate representations for key sequences in +most places where there is no ambiguity. Here are some rules for +abbreviation: + + * The keysym by itself is equivalent to a list of just that keysym, + i.e., `f1' is equivalent to `(f1)'. + + * A keystroke by itself is equivalent to a vector containing just + that keystroke, i.e., `(control a)' is equivalent to `[(control + a)]'. + + * You can use ASCII codes for keysyms that have them. i.e., `65' is + equivalent to `A'. (This is not so much an abbreviation as an + alternate representation.) + + Here are some examples of programmatically binding keys: + + + ;;; Bind `my-command' to + (global-set-key 'f1 'my-command) + + ;;; Bind `my-command' to Shift-f1 + (global-set-key '(shift f1) 'my-command) + + ;;; Bind `my-command' to C-c Shift-f1 + (global-set-key '[(control c) (shift f1)] 'my-command) + + ;;; Bind `my-command' to the middle mouse button. + (global-set-key 'button2 'my-command) + + ;;; Bind `my-command' to + ;;; in the keymap that is in force when you are running `dired'. + (define-key dired-mode-map '(meta control button3) 'my-command) + + +File: xemacs.info, Node: Key Bindings Using Strings, Prev: Programmatic Rebinding, Up: Rebinding + +Using Strings for Changing Key Bindings +....................................... + + For backward compatibility, you can still use strings to represent +key sequences. Thus you can use commands like the following: + + ;;; Bind `end-of-line' to C-f + (global-set-key "\C-f" 'end-of-line) + + Note, however, that in some cases you may be binding more than one +key sequence by using a single command. This situation can arise +because in ASCII, `C-i' and have the same representation. +Therefore, when Emacs sees: + + (global-set-key "\C-i" 'end-of-line) + + it is unclear whether the user intended to bind `C-i' or . The +solution XEmacs adopts is to bind both of these key sequences. + + After binding a command to two key sequences with a form like: + + (define-key global-map "\^X\^I" 'command-1) + + it is possible to redefine only one of those sequences like so: + + (define-key global-map [(control x) (control i)] 'command-2) + (define-key global-map [(control x) tab] 'command-3) + + This applies only when running under a window system. If you are +talking to Emacs through an ASCII-only channel, you do not get any of +these features. + + Here is a table of pairs of key sequences that behave in a similar +fashion: + + control h backspace + control l clear + control i tab + control m return + control j linefeed + control [ escape + control @ control space + + +File: xemacs.info, Node: Disabling, Prev: Rebinding, Up: Key Bindings + +Disabling Commands +------------------ + + Disabling a command marks it as requiring confirmation before it can +be executed. The purpose of disabling a command is to prevent +beginning users from executing it by accident and being confused. + + The direct mechanism for disabling a command is to have a non-`nil' +`disabled' property on the Lisp symbol for the command. These +properties are normally set by the user's init file with Lisp +expressions such as: + + (put 'delete-region 'disabled t) + + *Note Init File::. + + If the value of the `disabled' property is a string, that string is +included in the message printed when the command is used: + + (put 'delete-region 'disabled + "Text deleted this way cannot be yanked back!\n") + + You can disable a command either by editing the init file directly +or with the command `M-x disable-command', which edits the init file +for you. *Note Init File::. + + When you attempt to invoke a disabled command interactively in Emacs, +a window is displayed containing the command's name, its documentation, +and some instructions on what to do next; then Emacs asks for input +saying whether to execute the command as requested, enable it and +execute, or cancel it. If you decide to enable the command, you are +asked whether to do this permanently or just for the current session. +Enabling permanently works by automatically editing your init file. +You can use `M-x enable-command' at any time to enable any command +permanently. + + Whether a command is disabled is independent of what key is used to +invoke it; it also applies if the command is invoked using `M-x'. +Disabling a command has no effect on calling it as a function from Lisp +programs. + + +File: xemacs.info, Node: Syntax, Next: Init File, Prev: Key Bindings, Up: Customization + +The Syntax Table +================ + + All the Emacs commands which parse words or balance parentheses are +controlled by the "syntax table". The syntax table specifies which +characters are opening delimiters, which are parts of words, which are +string quotes, and so on. Actually, each major mode has its own syntax +table (though sometimes related major modes use the same one) which it +installs in each buffer that uses that major mode. The syntax table +installed in the current buffer is the one that all commands use, so we +call it "the" syntax table. A syntax table is a Lisp object, a vector +of length 256 whose elements are numbers. + +* Menu: + +* Entry: Syntax Entry. What the syntax table records for each character. +* Change: Syntax Change. How to change the information. + + +File: xemacs.info, Node: Syntax Entry, Next: Syntax Change, Up: Syntax + +Information About Each Character +-------------------------------- + + The syntax table entry for a character is a number that encodes six +pieces of information: + + * The syntactic class of the character, represented as a small + integer + + * The matching delimiter, for delimiter characters only (the + matching delimiter of `(' is `)', and vice versa) + + * A flag saying whether the character is the first character of a + two-character comment starting sequence + + * A flag saying whether the character is the second character of a + two-character comment starting sequence + + * A flag saying whether the character is the first character of a + two-character comment ending sequence + + * A flag saying whether the character is the second character of a + two-character comment ending sequence + + The syntactic classes are stored internally as small integers, but +are usually described to or by the user with characters. For example, +`(' is used to specify the syntactic class of opening delimiters. Here +is a table of syntactic classes, with the characters that specify them. + +` ' + The class of whitespace characters. + +`w' + The class of word-constituent characters. + +`_' + The class of characters that are part of symbol names but not + words. This class is represented by `_' because the character `_' + has this class in both C and Lisp. + +`.' + The class of punctuation characters that do not fit into any other + special class. + +`(' + The class of opening delimiters. + +`)' + The class of closing delimiters. + +`'' + The class of expression-adhering characters. These characters are + part of a symbol if found within or adjacent to one, and are part + of a following expression if immediately preceding one, but are + like whitespace if surrounded by whitespace. + +`"' + The class of string-quote characters. They match each other in + pairs, and the characters within the pair all lose their syntactic + significance except for the `\' and `/' classes of escape + characters, which can be used to include a string-quote inside the + string. + +`$' + The class of self-matching delimiters. This is intended for TeX's + `$', which is used both to enter and leave math mode. Thus, a + pair of matching `$' characters surround each piece of math mode + TeX input. A pair of adjacent `$' characters act like a single + one for purposes of matching. + +`/' + The class of escape characters that always just deny the following + character its special syntactic significance. The character after + one of these escapes is always treated as alphabetic. + +`\' + The class of C-style escape characters. In practice, these are + treated just like `/'-class characters, because the extra + possibilities for C escapes (such as being followed by digits) + have no effect on where the containing expression ends. + +`<' + The class of comment-starting characters. Only single-character + comment starters (such as `;' in Lisp mode) are represented this + way. + +`>' + The class of comment-ending characters. Newline has this syntax in + Lisp mode. + + The characters flagged as part of two-character comment delimiters +can have other syntactic functions most of the time. For example, `/' +and `*' in C code, when found separately, have nothing to do with +comments. The comment-delimiter significance overrides when the pair of +characters occur together in the proper order. Only the list and sexp +commands use the syntax table to find comments; the commands +specifically for comments have other variables that tell them where to +find comments. Moreover, the list and sexp commands notice comments +only if `parse-sexp-ignore-comments' is non-`nil'. This variable is set +to `nil' in modes where comment-terminator sequences are liable to +appear where there is no comment, for example, in Lisp mode where the +comment terminator is a newline but not every newline ends a comment. + + +File: xemacs.info, Node: Syntax Change, Prev: Syntax Entry, Up: Syntax + +Altering Syntax Information +--------------------------- + + It is possible to alter a character's syntax table entry by storing +a new number in the appropriate element of the syntax table, but it +would be hard to determine what number to use. Emacs therefore +provides a command that allows you to specify the syntactic properties +of a character in a convenient way. + + `M-x modify-syntax-entry' is the command to change a character's +syntax. It can be used interactively and is also used by major modes +to initialize their own syntax tables. Its first argument is the +character to change. The second argument is a string that specifies the +new syntax. When called from Lisp code, there is a third, optional +argument, which specifies the syntax table in which to make the change. +If not supplied, or if this command is called interactively, the third +argument defaults to the current buffer's syntax table. + + 1. The first character in the string specifies the syntactic class. + It is one of the characters in the previous table (*note Syntax + Entry::). + + 2. The second character is the matching delimiter. For a character + that is not an opening or closing delimiter, this should be a + space, and may be omitted if no following characters are needed. + + 3. The remaining characters are flags. The flag characters allowed + are: + + `1' + Flag this character as the first of a two-character comment + starting sequence. + + `2' + Flag this character as the second of a two-character comment + starting sequence. + + `3' + Flag this character as the first of a two-character comment + ending sequence. + + `4' + Flag this character as the second of a two-character comment + ending sequence. + + Use `C-h s' (`describe-syntax') to display a description of the +contents of the current syntax table. The description of each +character includes both the string you have to pass to +`modify-syntax-entry' to set up that character's current syntax, and +some English to explain that string if necessary. + + +File: xemacs.info, Node: Init File, Next: Audible Bell, Prev: Syntax, Up: Customization + +The Init File +============= + + When you start Emacs, it normally loads either `.xemacs/init.el' or +the file `.emacs' (whichever comes first) in your home directory. This +file, if it exists, should contain Lisp code. It is called your +initialization file or "init file". Use the command line switch `-q' +to tell Emacs whether to load an init file (*note Entering Emacs::). +Use the command line switch `-user-init-file' (*note Command +Switches::) to tell Emacs to load a different file instead of +`~/.xemacs/init.el'/`~/.emacs'. + + When the init file is read, the variable `user-init-file' says which +init file was loaded. + + At some sites there is a "default init file", which is the library +named `default.el', found via the standard search path for libraries. +The Emacs distribution contains no such library; your site may create +one for local customizations. If this library exists, it is loaded +whenever you start Emacs. But your init file, if any, is loaded first; +if it sets `inhibit-default-init' non-`nil', then `default' is not +loaded. + + If you have a large amount of code in your init file, you should +byte-compile it to `~/.xemacs/init.elc' or `~/.emacs.elc'. + +* Menu: + +* Init Syntax:: Syntax of constants in Emacs Lisp. +* Init Examples:: How to do some things with an init file. +* Terminal Init:: Each terminal type can have an init file. + + +File: xemacs.info, Node: Init Syntax, Next: Init Examples, Up: Init File + +Init File Syntax +---------------- + + The init file contains one or more Lisp function call expressions. +Each consists of a function name followed by arguments, all surrounded +by parentheses. For example, `(setq fill-column 60)' represents a call +to the function `setq' which is used to set the variable `fill-column' +(*note Filling::) to 60. + + The second argument to `setq' is an expression for the new value of +the variable. This can be a constant, a variable, or a function call +expression. In the init file, constants are used most of the time. +They can be: + +Numbers + Integers are written in decimal, with an optional initial minus + sign. + + If a sequence of digits is followed by a period and another + sequence of digits, it is interpreted as a floating point number. + + The number prefixes `#b', `#o', and `#x' are supported to + represent numbers in binary, octal, and hexadecimal notation (or + radix). + +Strings + Lisp string syntax is the same as C string syntax with a few extra + features. Use a double-quote character to begin and end a string + constant. + + Newlines and special characters may be present literally in + strings. They can also be represented as backslash sequences: + `\n' for newline, `\b' for backspace, `\r' for return, `\t' for + tab, `\f' for formfeed (control-l), `\e' for escape, `\\' for a + backslash, `\"' for a double-quote, or `\OOO' for the character + whose octal code is OOO. Backslash and double-quote are the only + characters for which backslash sequences are mandatory. + + You can use `\C-' as a prefix for a control character, as in + `\C-s' for ASCII Control-S, and `\M-' as a prefix for a Meta + character, as in `\M-a' for Meta-A or `\M-\C-a' for Control-Meta-A. + +Characters + Lisp character constant syntax consists of a `?' followed by + either a character or an escape sequence starting with `\'. + Examples: `?x', `?\n', `?\"', `?\)'. Note that strings and + characters are not interchangeable in Lisp; some contexts require + one and some contexts require the other. + +True + `t' stands for `true'. + +False + `nil' stands for `false'. + +Other Lisp objects + Write a single-quote (') followed by the Lisp object you want. + + +File: xemacs.info, Node: Init Examples, Next: Terminal Init, Prev: Init Syntax, Up: Init File + +Init File Examples +------------------ + + Here are some examples of doing certain commonly desired things with +Lisp expressions: + + * Make in C mode just insert a tab if point is in the middle + of a line. + + (setq c-tab-always-indent nil) + + Here we have a variable whose value is normally `t' for `true' and + the alternative is `nil' for `false'. + + * Make searches case sensitive by default (in all buffers that do not + override this). + + (setq-default case-fold-search nil) + + This sets the default value, which is effective in all buffers + that do not have local values for the variable. Setting + `case-fold-search' with `setq' affects only the current buffer's + local value, which is probably not what you want to do in an init + file. + + * Make Text mode the default mode for new buffers. + + (setq default-major-mode 'text-mode) + + Note that `text-mode' is used because it is the command for + entering the mode we want. A single-quote is written before it to + make a symbol constant; otherwise, `text-mode' would be treated as + a variable name. + + * Turn on Auto Fill mode automatically in Text mode and related + modes. + + (setq text-mode-hook + '(lambda () (auto-fill-mode 1))) + + Here we have a variable whose value should be a Lisp function. The + function we supply is a list starting with `lambda', and a single + quote is written in front of it to make it (for the purpose of this + `setq') a list constant rather than an expression. Lisp functions + are not explained here; for mode hooks it is enough to know that + `(auto-fill-mode 1)' is an expression that will be executed when + Text mode is entered. You could replace it with any other + expression that you like, or with several expressions in a row. + + (setq text-mode-hook 'turn-on-auto-fill) + + This is another way to accomplish the same result. + `turn-on-auto-fill' is a symbol whose function definition is + `(lambda () (auto-fill-mode 1))'. + + * Load the installed Lisp library named `foo' (actually a file + `foo.elc' or `foo.el' in a standard Emacs directory). + + (load "foo") + + When the argument to `load' is a relative pathname, not starting + with `/' or `~', `load' searches the directories in `load-path' + (*note Loading::). + + * Load the compiled Lisp file `foo.elc' from your home directory. + + (load "~/foo.elc") + + Here an absolute file name is used, so no searching is done. + + * Rebind the key `C-x l' to run the function `make-symbolic-link'. + + (global-set-key "\C-xl" 'make-symbolic-link) + + or + + (define-key global-map "\C-xl" 'make-symbolic-link) + + Note once again the single-quote used to refer to the symbol + `make-symbolic-link' instead of its value as a variable. + + * Do the same thing for C mode only. + + (define-key c-mode-map "\C-xl" 'make-symbolic-link) + + * Bind the function key to a command in C mode. Note that the + names of function keys must be lower case. + + (define-key c-mode-map 'f1 'make-symbolic-link) + + * Bind the shifted version of to a command. + + (define-key c-mode-map '(shift f1) 'make-symbolic-link) + + * Redefine all keys which now run `next-line' in Fundamental mode to + run `forward-line' instead. + + (substitute-key-definition 'next-line 'forward-line + global-map) + + * Make `C-x C-v' undefined. + + (global-unset-key "\C-x\C-v") + + One reason to undefine a key is so that you can make it a prefix. + Simply defining `C-x C-v ANYTHING' would make `C-x C-v' a prefix, + but `C-x C-v' must be freed of any non-prefix definition first. + + * Make `$' have the syntax of punctuation in Text mode. Note the + use of a character constant for `$'. + + (modify-syntax-entry ?\$ "." text-mode-syntax-table) + + * Enable the use of the command `eval-expression' without + confirmation. + + (put 'eval-expression 'disabled nil) + + +File: xemacs.info, Node: Terminal Init, Prev: Init Examples, Up: Init File + +Terminal-Specific Initialization +-------------------------------- + + Each terminal type can have a Lisp library to be loaded into Emacs +when it is run on that type of terminal. For a terminal type named +TERMTYPE, the library is called `term/TERMTYPE' and it is found by +searching the directories `load-path' as usual and trying the suffixes +`.elc' and `.el'. Normally it appears in the subdirectory `term' of +the directory where most Emacs libraries are kept. + + The usual purpose of the terminal-specific library is to define the +escape sequences used by the terminal's function keys using the library +`keypad.el'. See the file `term/vt100.el' for an example of how this +is done. + + When the terminal type contains a hyphen, only the part of the name +before the first hyphen is significant in choosing the library name. +Thus, terminal types `aaa-48' and `aaa-30-rv' both use the library +`term/aaa'. The code in the library can use `(getenv "TERM")' to find +the full terminal type name. + + The library's name is constructed by concatenating the value of the +variable `term-file-prefix' and the terminal type. Your init file can +prevent the loading of the terminal-specific library by setting +`term-file-prefix' to `nil'. *Note Init File::. + + The value of the variable `term-setup-hook', if not `nil', is called +as a function of no arguments at the end of Emacs initialization, after +both your init file and any terminal-specific library have been read. +*Note Init File::. You can set the value in the init file to override +part of any of the terminal-specific libraries and to define +initializations for terminals that do not have a library. + + +File: xemacs.info, Node: Audible Bell, Next: Faces, Prev: Init File, Up: Customization + +Changing the Bell Sound +======================= + + You can now change how the audible bell sounds using the variable +`sound-alist'. + + `sound-alist''s value is an list associating symbols with, among +other things, strings of audio-data. When `ding' is called with one of +the symbols, the associated sound data is played instead of the +standard beep. This only works if you are logged in on the console of a +machine with audio hardware. To listen to a sound of the provided type, +call the function `play-sound' with the argument SOUND. You can also +set the volume of the sound with the optional argument VOLUME. + + Each element of `sound-alist' is a list describing a sound. The +first element of the list is the name of the sound being defined. +Subsequent elements of the list are alternating keyword/value pairs: + +`sound' + A string of raw sound data, or the name of another sound to play. + The symbol `t' here means use the default X beep. + +`volume' + An integer from 0-100, defaulting to `bell-volume'. + +`pitch' + If using the default X beep, the pitch (Hz) to generate. + +`duration' + If using the default X beep, the duration (milliseconds). + + For compatibility, elements of `sound-alist' may also be of the form: + + ( SOUND-NAME . ) + ( SOUND-NAME ) + + You should probably add things to this list by calling the function +`load-sound-file'. + + Note that you can only play audio data if running on the console +screen of a machine with audio hardware which emacs understands, which +at this time means a Sun SparcStation, SGI, or HP9000s700. + + Also note that the pitch, duration, and volume options are available +everywhere, but most X servers ignore the `pitch' option. + + The variable `bell-volume' should be an integer from 0 to 100, with +100 being loudest, which controls how loud the sounds emacs makes +should be. Elements of the `sound-alist' may override this value. +This variable applies to the standard X bell sound as well as sound +files. + + If the symbol `t' is in place of a sound-string, Emacs uses the +default X beep. This allows you to define beep-types of different +volumes even when not running on the console. + + You can add things to this list by calling the function +`load-sound-file', which reads in an audio-file and adds its data to +the sound-alist. You can specify the sound with the SOUND-NAME argument +and the file into which the sounds are loaded with the FILENAME +argument. The optional VOLUME argument sets the volume. + + `load-sound-file (FILENAME SOUND-NAME &optional VOLUME)' + + To load and install some sound files as beep-types, use the function +`load-default-sounds' (note that this only works if you are on display +0 of a machine with audio hardware). + + The following beep-types are used by Emacs itself. Other Lisp +packages may use other beep types, but these are the ones that the C +kernel of Emacs uses. + +`auto-save-error' + An auto-save does not succeed + +`command-error' + The Emacs command loop catches an error + +`undefined-key' + You type a key that is undefined + +`undefined-click' + You use an undefined mouse-click combination + +`no-completion' + Completion was not possible + +`y-or-n-p' + You type something other than the required `y' or `n' + +`yes-or-no-p' + You type something other than `yes' or `no' + + File: xemacs.info, Node: Faces, Next: Frame Components, Prev: Audible Bell, Up: Customization Faces @@ -425,578 +1281,3 @@ Resource List resources are used to initialize the variables `x-pointer-foreground-color' and `x-pointer-background-color'. - -File: xemacs.info, Node: Face Resources, Next: Widgets, Prev: Resource List, Up: X Resources - -Face Resources --------------- - - The attributes of faces are also per-frame. They can be specified as: - - Emacs.FACE_NAME.parameter: value - -or - - Emacs*FRAME_NAME.FACE_NAME.parameter: value - -Faces accept the following resources: - -`attributeFont' (class `AttributeFont'): font-name - The font of this face. - -`attributeForeground' (class `AttributeForeground'): color-name -`attributeBackground' (class `AttributeBackground'): color-name - The foreground and background colors of this face. - -`attributeBackgroundPixmap' (class `AttributeBackgroundPixmap'): file-name - The name of an XBM file (or XPM file, if your version of Emacs - supports XPM), to use as a background stipple. - -`attributeUnderline' (class `AttributeUnderline'): boolean - Whether text in this face should be underlined. - - All text is displayed in some face, defaulting to the face named -`default'. To set the font of normal text, use -`Emacs*default.attributeFont'. To set it in the frame named `fred', use -`Emacs*fred.default.attributeFont'. - - These are the names of the predefined faces: - -`default' - Everything inherits from this. - -`bold' - If this is not specified in the resource database, Emacs tries to - find a bold version of the font of the default face. - -`italic' - If this is not specified in the resource database, Emacs tries to - find an italic version of the font of the default face. - -`bold-italic' - If this is not specified in the resource database, Emacs tries to - find a bold-italic version of the font of the default face. - -`modeline' - This is the face that the modeline is displayed in. If not - specified in the resource database, it is determined from the - default face by reversing the foreground and background colors. - -`highlight' - This is the face that highlighted extents (for example, Info - cross-references and possible completions, when the mouse passes - over them) are displayed in. - -`left-margin' -`right-margin' - These are the faces that the left and right annotation margins are - displayed in. - -`zmacs-region' - This is the face that mouse selections are displayed in. - -`isearch' - This is the face that the matched text being searched for is - displayed in. - -`info-node' - This is the face of info menu items. If unspecified, it is copied - from `bold-italic'. - -`info-xref' - This is the face of info cross-references. If unspecified, it is - copied from `bold'. (Note that, when the mouse passes over a - cross-reference, the cross-reference's face is determined from a - combination of the `info-xref' and `highlight' faces.) - - Other packages might define their own faces; to see a list of all -faces, use any of the interactive face-manipulation commands such as -`set-face-font' and type `?' when you are prompted for the name of a -face. - - If the `bold', `italic', and `bold-italic' faces are not specified -in the resource database, then XEmacs attempts to derive them from the -font of the default face. It can only succeed at this if you have -specified the default font using the XLFD (X Logical Font Description) -format, which looks like - - *-courier-medium-r-*-*-*-120-*-*-*-*-*-* - -If you use any of the other, less strict font name formats, some of -which look like - - lucidasanstypewriter-12 - fixed - 9x13 - - then XEmacs won't be able to guess the names of the bold and italic -versions. All X fonts can be referred to via XLFD-style names, so you -should use those forms. See the man pages for `X(1)', `xlsfonts(1)', -and `xfontsel(1)'. - - -File: xemacs.info, Node: Widgets, Next: Menubar Resources, Prev: Face Resources, Up: X Resources - -Widgets -------- - - There are several structural widgets between the terminal EmacsFrame -widget and the top level ApplicationShell; the exact names and types of -these widgets change from release to release (for example, they changed -between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are -subject to further change in the future, so you should avoid mentioning -them in your resource database. The above-mentioned syntaxes should be -forward- compatible. As of 19.13, the exact widget hierarchy is as -follows: - - INVOCATION-NAME "shell" "container" FRAME-NAME - x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame" - - where INVOCATION-NAME is the terminal component of the name of the -XEmacs executable (usually `xemacs'), and `x-emacs-application-class' -is generally `Emacs'. - - -File: xemacs.info, Node: Menubar Resources, Prev: Widgets, Up: X Resources - -Menubar Resources ------------------ - - As the menubar is implemented as a widget which is not a part of -XEmacs proper, it does not use the face mechanism for specifying fonts -and colors: It uses whatever resources are appropriate to the type of -widget which is used to implement it. - - If Emacs was compiled to use only the Lucid Motif-lookalike menu -widgets, then one way to specify the font of the menubar would be - - Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-* - - If both the Lucid Motif-lookalike menu widgets and X Font Sets are -configured to allow multilingual menubars, then one uses - - *menubar*FontSet: -*-helvetica-bold-r-*-*-*-120-*-*-*-*-iso8859-*, \ - -*-*-*-*-*-*-*-120-*-jisx0208.1983-0 - - That would specify fonts for a Japanese menubar. Specifying only one -XLFD is acceptable; specifying more than one for a given registry -(language) is also allowed. When X Font Sets are configured, some .font -resources (eg, menubars) are ignored in favor of the corresponding -.fontSet resources. - - If the Motif library is being used, then one would have to use - - Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-* - - because the Motif library uses the `fontList' resource name instead -of `font', which has subtly different semantics. - - The same is true of the scrollbars: They accept whichever resources -are appropriate for the toolkit in use. - - -File: xemacs.info, Node: Quitting, Next: Lossage, Prev: Customization, Up: Top - -Quitting and Aborting -===================== - -`C-g' - Quit. Cancel running or partially typed command. - -`C-]' - Abort innermost recursive editing level and cancel the command - which invoked it (`abort-recursive-edit'). - -`M-x top-level' - Abort all recursive editing levels that are currently executing. - -`C-x u' - Cancel an already-executed command, usually (`undo'). - - There are two ways of cancelling commands which are not finished -executing: "quitting" with `C-g', and "aborting" with `C-]' or `M-x -top-level'. Quitting is cancelling a partially typed command or one -which is already running. Aborting is getting out of a recursive -editing level and cancelling the command that invoked the recursive -edit. - - Quitting with `C-g' is used for getting rid of a partially typed -command or a numeric argument that you don't want. It also stops a -running command in the middle in a relatively safe way, so you can use -it if you accidentally start executing a command that takes a long -time. In particular, it is safe to quit out of killing; either your -text will ALL still be there, or it will ALL be in the kill ring (or -maybe both). Quitting an incremental search does special things -documented under searching; in general, it may take two successive -`C-g' characters to get out of a search. `C-g' works by setting the -variable `quit-flag' to `t' the instant `C-g' is typed; Emacs Lisp -checks this variable frequently and quits if it is non-`nil'. `C-g' is -only actually executed as a command if it is typed while Emacs is -waiting for input. - - If you quit twice in a row before the first `C-g' is recognized, you -activate the "emergency escape" feature and return to the shell. *Note -Emergency Escape::. - - You can use `C-]' (`abort-recursive-edit') to get out of a recursive -editing level and cancel the command which invoked it. Quitting with -`C-g' does not do this, and could not do this because it is used to -cancel a partially typed command within the recursive editing level. -Both operations are useful. For example, if you are in the Emacs -debugger (*note Lisp Debug::) and have typed `C-u 8' to enter a numeric -argument, you can cancel that argument with `C-g' and remain in the -debugger. - - The command `M-x top-level' is equivalent to "enough" `C-]' commands -to get you out of all the levels of recursive edits that you are in. -`C-]' only gets you out one level at a time, but `M-x top-level' goes -out all levels at once. Both `C-]' and `M-x top-level' are like all -other commands and unlike `C-g' in that they are effective only when -Emacs is ready for a command. `C-]' is an ordinary key and has its -meaning only because of its binding in the keymap. *Note Recursive -Edit::. - - `C-x u' (`undo') is not strictly speaking a way of cancelling a -command, but you can think of it as cancelling a command already -finished executing. *Note Undo::. - - -File: xemacs.info, Node: Lossage, Next: Bugs, Prev: Quitting, Up: Top - -Dealing With Emacs Trouble -========================== - - This section describes various conditions in which Emacs fails to -work, and how to recognize them and correct them. - -* Menu: - -* Stuck Recursive:: `[...]' in mode line around the parentheses. -* Screen Garbled:: Garbage on the screen. -* Text Garbled:: Garbage in the text. -* Unasked-for Search:: Spontaneous entry to incremental search. -* Emergency Escape:: Emergency escape--- - What to do if Emacs stops responding. -* Total Frustration:: When you are at your wits' end. - - -File: xemacs.info, Node: Stuck Recursive, Next: Screen Garbled, Prev: Lossage, Up: Lossage - -Recursive Editing Levels ------------------------- - - Recursive editing levels are important and useful features of Emacs, -but they can seem like malfunctions to the user who does not understand -them. - - If the mode line has square brackets `[...]' around the parentheses -that contain the names of the major and minor modes, you have entered a -recursive editing level. If you did not do this on purpose, or if you -don't understand what that means, you should just get out of the -recursive editing level. To do so, type `M-x top-level'. This is -called getting back to top level. *Note Recursive Edit::. - - -File: xemacs.info, Node: Screen Garbled, Next: Text Garbled, Prev: Stuck Recursive, Up: Lossage - -Garbage on the Screen ---------------------- - - If the data on the screen looks wrong, the first thing to do is see -whether the text is actually wrong. Type `C-l', to redisplay the -entire screen. If the text appears correct after this, the problem was -entirely in the previous screen update. - - Display updating problems often result from an incorrect termcap -entry for the terminal you are using. The file `etc/TERMS' in the Emacs -distribution gives the fixes for known problems of this sort. -`INSTALL' contains general advice for these problems in one of its -sections. Very likely there is simply insufficient padding for certain -display operations. To investigate the possibility that you have this -sort of problem, try Emacs on another terminal made by a different -manufacturer. If problems happen frequently on one kind of terminal but -not another kind, the real problem is likely to be a bad termcap entry, -though it could also be due to a bug in Emacs that appears for terminals -that have or lack specific features. - - -File: xemacs.info, Node: Text Garbled, Next: Unasked-for Search, Prev: Screen Garbled, Up: Lossage - -Garbage in the Text -------------------- - - If `C-l' shows that the text is wrong, try undoing the changes to it -using `C-x u' until it gets back to a state you consider correct. Also -try `C-h l' to find out what command you typed to produce the observed -results. - - If a large portion of text appears to be missing at the beginning or -end of the buffer, check for the word `Narrow' in the mode line. If it -appears, the text is still present, but marked off-limits. To make it -visible again, type `C-x n w'. *Note Narrowing::. - - -File: xemacs.info, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage - -Spontaneous Entry to Incremental Search ---------------------------------------- - - If Emacs spontaneously displays `I-search:' at the bottom of the -screen, it means that the terminal is sending `C-s' and `C-q' according -to the poorly designed xon/xoff "flow control" protocol. You should -try to prevent this by putting the terminal in a mode where it will not -use flow control, or by giving it enough padding that it will never -send a `C-s'. If that cannot be done, you must tell Emacs to expect -flow control to be used, until you can get a properly designed terminal. - - Information on how to do these things can be found in the file -`INSTALL' in the Emacs distribution. - - -File: xemacs.info, Node: Emergency Escape, Next: Total Frustration, Prev: Unasked-for Search, Up: Lossage - -Emergency Escape ----------------- - - Because at times there have been bugs causing Emacs to loop without -checking `quit-flag', a special feature causes Emacs to be suspended -immediately if you type a second `C-g' while the flag is already set, -so you can always get out of XEmacs. Normally Emacs recognizes and -clears `quit-flag' (and quits!) quickly enough to prevent this from -happening. - - When you resume Emacs after a suspension caused by multiple `C-g', it -asks two questions before going back to what it had been doing: - - Auto-save? (y or n) - Abort (and dump core)? (y or n) - -Answer each one with `y' or `n' followed by . - - Saying `y' to `Auto-save?' causes immediate auto-saving of all -modified buffers in which auto-saving is enabled. - - Saying `y' to `Abort (and dump core)?' causes an illegal instruction -to be executed, dumping core. This is to enable a wizard to figure out -why Emacs was failing to quit in the first place. Execution does not -continue after a core dump. If you answer `n', execution does -continue. With luck, Emacs will ultimately check `quit-flag' and quit -normally. If not, and you type another `C-g', it is suspended again. - - If Emacs is not really hung, but is just being slow, you may invoke -the double `C-g' feature without really meaning to. In that case, -simply resume and answer `n' to both questions, and you will arrive at -your former state. Presumably the quit you requested will happen soon. - - The double-`C-g' feature may be turned off when Emacs is running -under a window system, since the window system always enables you to -kill Emacs or to create another window and run another program. - - -File: xemacs.info, Node: Total Frustration, Prev: Emergency Escape, Up: Lossage - -Help for Total Frustration --------------------------- - - If using Emacs (or something else) becomes terribly frustrating and -none of the techniques described above solve the problem, Emacs can -still help you. - - First, if the Emacs you are using is not responding to commands, type -`C-g C-g' to get out of it and then start a new one. - - Second, type `M-x doctor '. - - The doctor will make you feel better. Each time you say something to -the doctor, you must end it by typing . This lets the -doctor know you are finished. - - -File: xemacs.info, Node: Bugs, Prev: Lossage, Up: Top - -Reporting Bugs -============== - - Sometimes you will encounter a bug in Emacs. Although we cannot -promise we can or will fix the bug, and we might not even agree that it -is a bug, we want to hear about bugs you encounter in case we do want -to fix them. - - To make it possible for us to fix a bug, you must report it. In -order to do so effectively, you must know when and how to do it. - -When Is There a Bug -------------------- - - If Emacs executes an illegal instruction, or dies with an operating -system error message that indicates a problem in the program (as -opposed to something like "disk full"), then it is certainly a bug. - - If Emacs updates the display in a way that does not correspond to -what is in the buffer, then it is certainly a bug. If a command seems -to do the wrong thing but the problem corrects itself if you type -`C-l', it is a case of incorrect display updating. - - Taking forever to complete a command can be a bug, but you must make -certain that it was really Emacs's fault. Some commands simply take a -long time. Type `C-g' and then `C-h l' to see whether the input Emacs -received was what you intended to type; if the input was such that you -KNOW it should have been processed quickly, report a bug. If you don't -know whether the command should take a long time, find out by looking -in the manual or by asking for assistance. - - If a command you are familiar with causes an Emacs error message in a -case where its usual definition ought to be reasonable, it is probably a -bug. - - If a command does the wrong thing, that is a bug. But be sure you -know for certain what it ought to have done. If you aren't familiar -with the command, or don't know for certain how the command is supposed -to work, then it might actually be working right. Rather than jumping -to conclusions, show the problem to someone who knows for certain. - - Finally, a command's intended definition may not be best for editing -with. This is a very important sort of problem, but it is also a -matter of judgment. Also, it is easy to come to such a conclusion out -of ignorance of some of the existing features. It is probably best not -to complain about such a problem until you have checked the -documentation in the usual ways, feel confident that you understand it, -and know for certain that what you want is not available. If you are -not sure what the command is supposed to do after a careful reading of -the manual, check the index and glossary for any terms that may be -unclear. If you still do not understand, this indicates a bug in the -manual. The manual's job is to make everything clear. It is just as -important to report documentation bugs as program bugs. - - If the online documentation string of a function or variable -disagrees with the manual, one of them must be wrong, so report the bug. - -How to Report a Bug -------------------- - - When you decide that there is a bug, it is important to report it -and to report it in a way which is useful. What is most useful is an -exact description of what commands you type, starting with the shell -command to run Emacs, until the problem happens. Always include the -version number of Emacs that you are using; type `M-x emacs-version' to -print this. - - The most important principle in reporting a bug is to report FACTS, -not hypotheses or categorizations. It is always easier to report the -facts, but people seem to prefer to strain to posit explanations and -report them instead. If the explanations are based on guesses about -how Emacs is implemented, they will be useless; we will have to try to -figure out what the facts must have been to lead to such speculations. -Sometimes this is impossible. But in any case, it is unnecessary work -for us. - - For example, suppose that you type `C-x C-f /glorp/baz.ugh ', -visiting a file which (you know) happens to be rather large, and Emacs -prints out `I feel pretty today'. The best way to report the bug is -with a sentence like the preceding one, because it gives all the facts -and nothing but the facts. - - Do not assume that the problem is due to the size of the file and -say, "When I visit a large file, Emacs prints out `I feel pretty -today'." This is what we mean by "guessing explanations". The problem -is just as likely to be due to the fact that there is a `z' in the file -name. If this is so, then when we got your report, we would try out -the problem with some "large file", probably with no `z' in its name, -and not find anything wrong. There is no way in the world that we -could guess that we should try visiting a file with a `z' in its name. - - Alternatively, the problem might be due to the fact that the file -starts with exactly 25 spaces. For this reason, you should make sure -that you inform us of the exact contents of any file that is needed to -reproduce the bug. What if the problem only occurs when you have typed -the `C-x a l' command previously? This is why we ask you to give the -exact sequence of characters you typed since starting to use Emacs. - - You should not even say "visit a file" instead of `C-x C-f' unless -you know that it makes no difference which visiting command is used. -Similarly, rather than saying "if I have three characters on the line," -say "after I type ` A B C C-p'," if that is the way you -entered the text. - - If you are not in Fundamental mode when the problem occurs, you -should say what mode you are in. - - If the manifestation of the bug is an Emacs error message, it is -important to report not just the text of the error message but a -backtrace showing how the Lisp program in Emacs arrived at the error. -To make the backtrace, you must execute the Lisp expression `(setq -debug-on-error t)' before the error happens (that is to say, you must -execute that expression and then make the bug happen). This causes the -Lisp debugger to run (*note Lisp Debug::). The debugger's backtrace -can be copied as text into the bug report. This use of the debugger is -possible only if you know how to make the bug happen again. Do note -the error message the first time the bug happens, so if you can't make -it happen again, you can report at least that. - - Check whether any programs you have loaded into the Lisp world, -including your init file, set any variables that may affect the -functioning of Emacs. *Note Init File::. Also, see whether the -problem happens in a freshly started Emacs without loading your init -file (start Emacs with the `-q' switch to prevent loading the init -file). If the problem does NOT occur then, it is essential that we -know the contents of any programs that you must load into the Lisp -world in order to cause the problem to occur. - - If the problem does depend on an init file or other Lisp programs -that are not part of the standard Emacs system, then you should make -sure it is not a bug in those programs by complaining to their -maintainers first. After they verify that they are using Emacs in a -way that is supposed to work, they should report the bug. - - If you can tell us a way to cause the problem without visiting any -files, please do so. This makes it much easier to debug. If you do -need files, make sure you arrange for us to see their exact contents. -For example, it can often matter whether there are spaces at the ends -of lines, or a newline after the last line in the buffer (nothing ought -to care whether the last line is terminated, but tell that to the bugs). - - The easy way to record the input to Emacs precisely is to write a -dribble file; execute the Lisp expression: - - (open-dribble-file "~/dribble") - -using `Meta-' or from the `*scratch*' buffer just after starting -Emacs. From then on, all Emacs input will be written in the specified -dribble file until the Emacs process is killed. - - For possible display bugs, it is important to report the terminal -type (the value of environment variable `TERM'), the complete termcap -entry for the terminal from `/etc/termcap' (since that file is not -identical on all machines), and the output that Emacs actually sent to -the terminal. The way to collect this output is to execute the Lisp -expression: - - (open-termscript "~/termscript") - -using `Meta-' or from the `*scratch*' buffer just after starting -Emacs. From then on, all output from Emacs to the terminal will be -written in the specified termscript file as well, until the Emacs -process is killed. If the problem happens when Emacs starts up, put -this expression into your init file so that the termscript file will be -open when Emacs displays the screen for the first time. *Note Init -File::. Be warned: it is often difficult, and sometimes impossible, to -fix a terminal-dependent bug without access to a terminal of the type -that stimulates the bug. - - The newsgroup `comp.emacs.xemacs' may be used for bug reports, other -discussions and requests for assistance. - - If you don't have access to this newgroup, you can subscribe to the -mailing list version: the newsgroup is bidirectionally gatewayed into -the mailing list `xemacs@xemacs.org'. - - To be added or removed from this mailing list, send mail to -`xemacs-request@xemacs.org'. Do not send requests for addition to the -mailing list itself. - - The mailing lists and newsgroups are archived on our anonymous FTP -server, `ftp.xemacs.org', and at various other archive sites around the -net. You should also check the `FAQ' in `/pub/xemacs' on our anonymous -FTP server. It provides some introductory information and help for -initial configuration problems. -