X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Fxemacs.info-18;h=497f813be9972291d28f7223738b7945fca4b0c7;hb=bdbf322fda10f6dcfae7d04c81ff0862e41ecc56;hp=406752e8cff9212b050f2e238eb3930851b166ca;hpb=7d6edaefa00e7b7e102354283824a4f6a721b71a;p=chise%2Fxemacs-chise.git- diff --git a/info/xemacs.info-18 b/info/xemacs.info-18 index 406752e..497f813 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,1049 +30,1243 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  -File: xemacs.info, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage +File: xemacs.info, Node: Disabling, Prev: Rebinding, Up: Key Bindings -Spontaneous Entry to Incremental Search ---------------------------------------- +Disabling Commands +------------------ - 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. + 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. - Information on how to do these things can be found in the file -`INSTALL' in the Emacs distribution. + 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: Emergency Escape, Next: Total Frustration, Prev: Unasked-for Search, Up: Lossage +File: xemacs.info, Node: Init Syntax, Next: Init Examples, Up: Init File -Emergency Escape +Init File Syntax ---------------- - 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. + 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). - 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: + (load "foo") - Auto-save? (y or n) - Abort (and dump core)? (y or n) + When the argument to `load' is a relative pathname, not starting + with `/' or `~', `load' searches the directories in `load-path' + (*note Loading::). -Answer each one with `y' or `n' followed by . + * Load the compiled Lisp file `foo.elc' from your home directory. - Saying `y' to `Auto-save?' causes immediate auto-saving of all -modified buffers in which auto-saving is enabled. + (load "~/foo.elc") - 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. + Here an absolute file name is used, so no searching is done. - 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. + * Rebind the key `C-x l' to run the function `make-symbolic-link'. - 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. + (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: Total Frustration, Prev: Emergency Escape, Up: Lossage +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. -Help for Total Frustration --------------------------- +`volume' + An integer from 0-100, defaulting to `bell-volume'. - If using Emacs (or something else) becomes terribly frustrating and -none of the techniques described above solve the problem, Emacs can -still help you. +`pitch' + If using the default X beep, the pitch (Hz) to generate. - 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. +`duration' + If using the default X beep, the duration (milliseconds). - Second, type `M-x doctor '. + For compatibility, elements of `sound-alist' may also be of the form: - 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. + ( 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: 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 `.emacs' file, set any variables that may affect the -functioning of Emacs. Also, see whether the problem happens in a -freshly started Emacs without loading your `.emacs' 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 `.emacs' file so that the termscript file will -be open when Emacs displays the screen for the first time. 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. +File: xemacs.info, Node: Faces, Next: Frame Components, Prev: Audible Bell, Up: Customization + +Faces +===== + + XEmacs has objects called extents and faces. An "extent" is a +region of text and a "face" is a collection of textual attributes, such +as fonts and colors. Every extent is displayed in some face; +therefore, changing the properties of a face immediately updates the +display of all associated extents. Faces can be frame-local: you can +have a region of text that displays with completely different +attributes when its buffer is viewed from a different X window. + + The display attributes of faces may be specified either in Lisp or +through the X resource manager. + +Customizing Faces +----------------- + + You can change the face of an extent with the functions in this +section. All the functions prompt for a FACE as an argument; use +completion for a list of possible values. + +`M-x invert-face' + Swap the foreground and background colors of the given FACE. + +`M-x make-face-bold' + Make the font of the given FACE bold. When called from a program, + returns `nil' if this is not possible. + +`M-x make-face-bold-italic' + Make the font of the given FACE bold italic. When called from a + program, returns `nil' if not possible. + +`M-x make-face-italic' + Make the font of the given FACE italic. When called from a + program, returns `nil' if not possible. + +`M-x make-face-unbold' + Make the font of the given FACE non-bold. When called from a + program, returns `nil' if not possible. + +`M-x make-face-unitalic' + Make the font of the given FACE non-italic. When called from a + program, returns `nil' if not possible. + +`M-x make-face-larger' + Make the font of the given FACE a little larger. When called from + a program, returns `nil' if not possible. + +`M-x make-face-smaller' + Make the font of the given FACE a little smaller. When called + from a program, returns `nil' if not possible. + +`M-x set-face-background' + Change the background color of the given FACE. + +`M-x set-face-background-pixmap' + Change the background pixmap of the given FACE. + +`M-x set-face-font' + Change the font of the given FACE. + +`M-x set-face-foreground' + Change the foreground color of the given FACE. + +`M-x set-face-underline-p' + Change whether the given FACE is underlined. + + You can exchange the foreground and background color of the selected +FACE with the function `invert-face'. If the face does not specify both +foreground and background, then its foreground and background are set +to the background and foreground of the default face. When calling +this from a program, you can supply the optional argument FRAME to +specify which frame is affected; otherwise, all frames are affected. + + You can set the background color of the specified FACE with the +function `set-face-background'. The argument `color' should be a +string, the name of a color. When called from a program, if the +optional FRAME argument is provided, the face is changed only in that +frame; otherwise, it is changed in all frames. + + You can set the background pixmap of the specified FACE with the +function `set-face-background-pixmap'. The pixmap argument NAME should +be a string, the name of a file of pixmap data. The directories listed +in the `x-bitmap-file-path' variable are searched. The bitmap may also +be a list of the form `(WIDTH HEIGHT DATA)', where WIDTH and HEIGHT are +the size in pixels, and DATA is a string containing the raw bits of the +bitmap. If the optional FRAME argument is provided, the face is +changed only in that frame; otherwise, it is changed in all frames. + + The variable `x-bitmap-file-path' takes as a value a list of the +directories in which X bitmap files may be found. If the value is +`nil', the list is initialized from the `*bitmapFilePath' resource. + + If the environment variable XBMLANGPATH is set, then it is consulted +before the `x-bitmap-file-path' variable. + + You can set the font of the specified FACE with the function +`set-face-font'. The FONT argument should be a string, the name of a +font. When called from a program, if the optional FRAME argument is +provided, the face is changed only in that frame; otherwise, it is +changed in all frames. + + You can set the foreground color of the specified FACE with the +function `set-face-foreground'. The argument COLOR should be a string, +the name of a color. If the optional FRAME argument is provided, the +face is changed only in that frame; otherwise, it is changed in all +frames. + + You can set underline the specified FACE with the function +`set-face-underline-p'. The argument UNDERLINE-P can be used to make +underlining an attribute of the face or not. If the optional FRAME +argument is provided, the face is changed only in that frame; +otherwise, it is changed in all frames.  -File: xemacs.info, Node: Glossary, Next: Manifesto, Prev: Intro, Up: Top - -Glossary -******** - -Abbrev - An abbrev is a text string which expands into a different text - string when present in the buffer. For example, you might define - a short word as an abbrev for a long phrase that you want to insert - frequently. *Note Abbrevs::. - -Aborting - Aborting means getting out of a recursive edit (q.v.). You can use - the commands `C-]' and `M-x top-level' for this. *Note Quitting::. - -Auto Fill mode - Auto Fill mode is a minor mode in which text you insert is - automatically broken into lines of fixed width. *Note Filling::. - -Auto Saving - Auto saving means that Emacs automatically stores the contents of - an Emacs buffer in a specially-named file so the information will - not be lost if the buffer is lost due to a system error or user - error. *Note Auto Save::. - -Backup File - A backup file records the contents that a file had before the - current editing session. Emacs creates backup files automatically - to help you track down or cancel changes you later regret. *Note - Backup::. - -Balance Parentheses - Emacs can balance parentheses manually or automatically. Manual - balancing is done by the commands to move over balanced expressions - (*note Lists::). Automatic balancing is done by blinking the - parenthesis that matches one just inserted (*note Matching Parens: - Matching.). - -Bind - To bind a key is to change its binding (q.v.). *Note Rebinding::. - -Binding - A key gets its meaning in Emacs by having a binding which is a - command (q.v.), a Lisp function that is run when the key is typed. - *Note Binding: Commands. Customization often involves rebinding a - character to a different command function. The bindings of all - keys are recorded in the keymaps (q.v.). *Note Keymaps::. - -Blank Lines - Blank lines are lines that contain only whitespace. Emacs has - several commands for operating on the blank lines in a buffer. - -Buffer - The buffer is the basic editing unit; one buffer corresponds to one - piece of text being edited. You can have several buffers, but at - any time you are editing only one, the `selected' buffer, though - several buffers can be visible when you are using multiple - windows. *Note Buffers::. - -Buffer Selection History - Emacs keeps a buffer selection history which records how recently - each Emacs buffer was selected. Emacs uses this list when - choosing a buffer to select. *Note Buffers::. - -C- - `C' in the name of a character is an abbreviation for Control. - *Note C-: Keystrokes. - -C-M- - `C-M-' in the name of a character is an abbreviation for - Control-Meta. *Note C-M-: Keystrokes. - -Case Conversion - Case conversion means changing text from upper case to lower case - or vice versa. *Note Case::, for the commands for case conversion. +File: xemacs.info, Node: Frame Components, Next: X Resources, Prev: Faces, Up: Customization -Characters - Characters form the contents of an Emacs buffer; also, Emacs - commands are invoked by keys (q.v.), which are sequences of one or - more characters. *Note Keystrokes::. - -Command - A command is a Lisp function specially defined to be able to serve - as a key binding in Emacs. When you type a key (q.v.), Emacs - looks up its binding (q.v.) in the relevant keymaps (q.v.) to find - the command to run. *Note Commands::. - -Command Name - A command name is the name of a Lisp symbol which is a command - (*note Commands::). You can invoke any command by its name using - `M-x' (*note M-x::). - -Comments - A comment is text in a program which is intended only for the - people reading the program, and is marked specially so that it - will be ignored when the program is loaded or compiled. Emacs - offers special commands for creating, aligning, and killing - comments. *Note Comments::. - -Compilation - Compilation is the process of creating an executable program from - source code. Emacs has commands for compiling files of Emacs Lisp - code (*note Lisp Libraries::) and programs in C and other languages - (*note Compilation::). - -Complete Key - A complete key is a character or sequence of characters which, - when typed by the user, fully specifies one action to be performed - by Emacs. For example, `X' and `Control-f' and `Control-x m' are - keys. Keys derive their meanings from being bound (q.v.) to - commands (q.v.). Thus, `X' is conventionally bound to a command - to insert `X' in the buffer; `C-x m' is conventionally bound to a - command to begin composing a mail message. *Note Keystrokes::. - -Completion - When Emacs automatically fills an abbreviation for a name into the - entire name, that process is called completion. Completion is - done for minibuffer (q.v.) arguments when the set of possible - valid inputs is known; for example, on command names, buffer - names, and file names. Completion occurs when you type , - , or . *Note Completion::. - -Continuation Line - When a line of text is longer than the width of the frame, it - takes up more than one screen line when displayed. We say that the - text line is continued, and all screen lines used for it after the - first are called continuation lines. *Note Continuation: Basic. - -Control-Character - ASCII characters with octal codes 0 through 037, and also code - 0177, do not have graphic images assigned to them. These are the - control characters. Any control character can be typed by holding - down the key and typing some other character; some have - special keys on the keyboard. , , , , and - are all control characters. *Note Keystrokes::. - -Copyleft - A copyleft is a notice giving the public legal permission to - redistribute a program or other work of art. Copylefts are used - by leftists to enrich the public just as copyrights are used by - rightists to gain power over the public. - -Current Buffer - The current buffer in Emacs is the Emacs buffer on which most - editing commands operate. You can select any Emacs buffer as the - current one. *Note Buffers::. - -Current Line - The line point is on (*note Point::). - -Current Paragraph - The paragraph that point is in. If point is between paragraphs, - the current paragraph is the one that follows point. *Note - Paragraphs::. - -Current Defun - The defun (q.v.) that point is in. If point is between defuns, the - current defun is the one that follows point. *Note Defuns::. - -Cursor - The cursor is the rectangle on the screen which indicates the - position called point (q.v.) at which insertion and deletion takes - place. The cursor is on or under the character that follows - point. Often people speak of `the cursor' when, strictly - speaking, they mean `point'. *Note Cursor: Basic. - -Customization - Customization is making minor changes in the way Emacs works. It - is often done by setting variables (*note Variables::) or by - rebinding keys (*note Keymaps::). - -Default Argument - The default for an argument is the value that is used if you do not - specify one. When Emacs prompts you in the minibuffer for an - argument, the default argument is used if you just type . - *Note Minibuffer::. - -Default Directory - When you specify a file name that does not start with `/' or `~', - it is interpreted relative to the current buffer's default - directory. *Note Default Directory: Minibuffer File. - -Defun - A defun is a list at the top level of parenthesis or bracket - structure in a program. It is so named because most such lists in - Lisp programs are calls to the Lisp function `defun'. *Note - Defuns::. - - - The character runs the command that deletes one character of - text. *Note DEL: Basic. - -Deletion - Deleting text means erasing it without saving it. Emacs deletes - text only when it is expected not to be worth saving (all - whitespace, or only one character). The alternative is killing - (q.v.). *Note Deletion: Killing. - -Deletion of Files - Deleting a file means removing it from the file system. *Note - Misc File Ops::. - -Deletion of Messages - Deleting a message means flagging it to be eliminated from your - mail file. Until the mail file is expunged, you can undo this by - undeleting the message. - -Deletion of Frames - When working under the multi-frame X-based version of XEmacs, you - can delete individual frames using the Close menu item from the - File menu. - -Deletion of Windows - When you delete a subwindow of an Emacs frame, you eliminate it - from the frame. Other windows expand to use up the space. The - deleted window can never come back, but no actual text is lost. - *Note Windows::. - -Directory - Files in the Unix file system are grouped into file directories. - *Note Directories: ListDir. - -Dired - Dired is the Emacs facility that displays the contents of a file - directory and allows you to "edit the directory", performing - operations on the files in the directory. *Note Dired::. - -Disabled Command - A disabled command is one that you may not run without special - confirmation. Commands are usually disabled because they are - confusing for beginning users. *Note Disabling::. - -Dribble File - A file into which Emacs writes all the characters that the user - types on the keyboard. Dribble files are used to make a record for - debugging Emacs bugs. Emacs does not make a dribble file unless - you tell it to. *Note Bugs::. - -Echo Area - The area at the bottom of the Emacs frame which is used for - echoing the arguments to commands, for asking questions, and for - printing brief messages (including error messages). *Note Echo - Area::. - -Echoing - Echoing refers to acknowledging the receipt of commands by - displaying them (in the echo area). Emacs never echoes - single-character keys; longer keys echo only if you pause while - typing them. - -Error - An error occurs when an Emacs command cannot execute in the current - circumstances. When an error occurs, execution of the command - stops (unless the command has been programmed to do otherwise) and - Emacs reports the error by printing an error message (q.v.). - Type-ahead is discarded. Then Emacs is ready to read another - editing command. - -Error Messages - Error messages are single lines of output printed by Emacs when the - user asks for something impossible to do (such as killing text - forward when point is at the end of the buffer). They appear in - the echo area, accompanied by a beep. - - - is a character used as a prefix for typing Meta characters on - keyboards lacking a key. Unlike the key (which, - like the key, is held down while another character is - typed), the key is pressed and released, and applies to the - next character typed. - -Fill Prefix - The fill prefix is a string that Emacs enters at the beginning of - each line when it performs filling. It is not regarded as part of - the text to be filled. *Note Filling::. - -Filling - Filling text means moving text from line to line so that all the - lines are approximately the same length. *Note Filling::. - -Frame - When running Emacs on a TTY terminal, "frame" means the terminal's - screen. When running Emacs under X, you can have multiple frames, - each corresponding to a top-level X window and each looking like - the screen on a TTY. Each frame contains one or more - non-overlapping Emacs windows (possibly with associated - scrollbars, under X), an echo area, and (under X) possibly a - menubar. - -Global - Global means `independent of the current environment; in effect - throughout Emacs'. It is the opposite of local (q.v.). Examples - of the use of `global' appear below. - -Global Abbrev - A global definition of an abbrev (q.v.) is effective in all major - modes that do not have local (q.v.) definitions for the same - abbrev. *Note Abbrevs::. - -Global Keymap - The global keymap (q.v.) contains key bindings that are in effect - unless local key bindings in a major mode's local keymap (q.v.) - override them.*Note Keymaps::. - -Global Substitution - Global substitution means replacing each occurrence of one string - by another string through a large amount of text. *Note Replace::. - -Global Variable - The global value of a variable (q.v.) takes effect in all buffers - that do not have their own local (q.v.) values for the variable. - *Note Variables::. - -Graphic Character - Graphic characters are those assigned pictorial images rather than - just names. All the non-Meta (q.v.) characters except for the - Control (q.v.) character are graphic characters. These include - letters, digits, punctuation, and spaces; they do not include - or . In Emacs, typing a graphic character inserts that - character (in ordinary editing modes). *Note Basic Editing: Basic. - -Grinding - Grinding means adjusting the indentation in a program to fit the - nesting structure. *Note Grinding: Indentation. - -Hardcopy - Hardcopy means printed output. Emacs has commands for making - printed listings of text in Emacs buffers. *Note Hardcopy::. - - - You can type at any time to ask what options you have, or - to ask what any command does. is really `Control-h'. - *Note Help::. - -Inbox - An inbox is a file in which mail is delivered by the operating - system. Some mail handlers transfers mail from inboxes to mail - files (q.v.) in which the mail is then stored permanently or until - explicitly deleted. - -Indentation - Indentation means blank space at the beginning of a line. Most - programming languages have conventions for using indentation to - illuminate the structure of the program, and Emacs has special - features to help you set up the correct indentation. *Note - Indentation::. - -Insertion - Insertion means copying text into the buffer, either from the - keyboard or from some other place in Emacs. - -Justification - Justification means adding extra spaces to lines of text to make - them come exactly to a specified width. *Note Justification: - Filling. - -Keyboard Macros - Keyboard macros are a way of defining new Emacs commands from - sequences of existing ones, with no need to write a Lisp program. - *Note Keyboard Macros::. - -Key - A key is a sequence of characters that, when input to Emacs, - specify or begin to specify a single action for Emacs to perform. - That is, the sequence is considered a single unit. If the key is - enough to specify one action, it is a complete key (q.v.); if it - is less than enough, it is a prefix key (q.v.). *Note - Keystrokes::. - -Keymap - The keymap is the data structure that records the bindings (q.v.) - of keys to the commands that they run. For example, the keymap - binds the character `C-n' to the command function `next-line'. - *Note Keymaps::. - -Kill Ring - The kill ring is the place where all text you have killed recently - is saved. You can re-insert any of the killed text still in the - ring; this is called yanking (q.v.). *Note Yanking::. - -Killing - Killing means erasing text and saving it on the kill ring so it - can be yanked (q.v.) later. Some other systems call this - "cutting." Most Emacs commands to erase text do killing, as - opposed to deletion (q.v.). *Note Killing::. - -Killing Jobs - Killing a job (such as, an invocation of Emacs) means making it - cease to exist. Any data within it, if not saved in a file, is - lost. *Note Exiting::. - -List - A list is, approximately, a text string beginning with an open - parenthesis and ending with the matching close parenthesis. In C - mode and other non-Lisp modes, groupings surrounded by other kinds - of matched delimiters appropriate to the language, such as braces, - are also considered lists. Emacs has special commands for many - operations on lists. *Note Lists::. - -Local - Local means `in effect only in a particular context'; the relevant - kind of context is a particular function execution, a particular - buffer, or a particular major mode. Local is the opposite of - `global' (q.v.). Specific uses of `local' in Emacs terminology - appear below. - -Local Abbrev - A local abbrev definition is effective only if a particular major - mode is selected. In that major mode, it overrides any global - definition for the same abbrev. *Note Abbrevs::. - -Local Keymap - A local keymap is used in a particular major mode; the key bindings - (q.v.) in the current local keymap override global bindings of the - same keys. *Note Keymaps::. - -Local Variable - A local value of a variable (q.v.) applies to only one buffer. - *Note Locals::. - -M- - `M-' in the name of a character is an abbreviation for , one - of the modifier keys that can accompany any character. *Note - Keystrokes::. - -M-C- - `M-C-' in the name of a character is an abbreviation for - Control-Meta; it means the same thing as `C-M-'. If your terminal - lacks a real key, you type a Control-Meta character by - typing and then typing the corresponding Control character. - *Note C-M-: Keystrokes. - -M-x - `M-x' is the key which is used to call an Emacs command by name. - You use it to call commands that are not bound to keys. *Note - M-x::. - -Mail - Mail means messages sent from one user to another through the - computer system, to be read at the recipient's convenience. Emacs - has commands for composing and sending mail, and for reading and - editing the mail you have received. *Note Sending Mail::. - -Major Mode - The major modes are a mutually exclusive set of options each of - which configures Emacs for editing a certain sort of text. - Ideally, each programming language has its own major mode. *Note - Major Modes::. - -Mark - The mark points to a position in the text. It specifies one end - of the region (q.v.), point being the other end. Many commands - operate on the whole region, that is, all the text from point to - the mark. *Note Mark::. - -Mark Ring - The mark ring is used to hold several recent previous locations of - the mark, just in case you want to move back to them. *Note Mark - Ring::. - -Message - See `mail'. - -Meta - Meta is the name of a modifier bit which a command character may - have. It is present in a character if the character is typed with - the key held down. Such characters are given names that - start with `Meta-'. For example, `Meta-<' is typed by holding down - and at the same time typing `<' (which itself is done, on - most terminals, by holding down and typing `,'). *Note - Meta: Keystrokes. - -Meta Character - A Meta character is one whose character code includes the Meta bit. - -Minibuffer - The minibuffer is the window that Emacs displays inside the echo - area (q.v.) when it prompts you for arguments to commands. *Note - Minibuffer::. - -Minor Mode - A minor mode is an optional feature of Emacs which can be switched - on or off independent of the major mode. Each minor mode has a - command to turn it on or off. *Note Minor Modes::. - -Mode Line - The mode line is the line at the bottom of each text window (q.v.), - which gives status information on the buffer displayed in that - window. *Note Mode Line::. - -Modified Buffer - A buffer (q.v.) is modified if its text has been changed since the - last time the buffer was saved (or since it was created, if it has - never been saved). *Note Saving::. - -Moving Text - Moving text means erasing it from one place and inserting it in - another. This is done by killing (q.v.) and then yanking (q.v.). - *Note Killing::. - -Named Mark - A named mark is a register (q.v.) in its role of recording a - location in text so that you can move point to that location. - *Note Registers::. - -Narrowing - Narrowing means creating a restriction (q.v.) that limits editing - in the current buffer to only a part of the text in the buffer. - Text outside that part is inaccessible to the user until the - boundaries are widened again, but it is still there, and saving - the file saves the invisible text. *Note Narrowing::. - -Newline - characters in the buffer terminate lines of text and are - called newlines. *Note Newline: Keystrokes. - -Numeric Argument - A numeric argument is a number, specified before a command, to - change the effect of the command. Often the numeric argument - serves as a repeat count. *Note Arguments::. - -Option - An option is a variable (q.v.) that allows you to customize Emacs - by giving it a new value. *Note Variables::. - -Overwrite Mode - Overwrite mode is a minor mode. When it is enabled, ordinary text - characters replace the existing text after point rather than - pushing it to the right. *Note Minor Modes::. - -Page - A page is a unit of text, delimited by formfeed characters (ASCII - Control-L, code 014) coming at the beginning of a line. Some Emacs - commands are provided for moving over and operating on pages. - *Note Pages::. - -Paragraphs - Paragraphs are the medium-size unit of English text. There are - special Emacs commands for moving over and operating on paragraphs. - *Note Paragraphs::. - -Parsing - We say that Emacs parses words or expressions in the text being - edited. Really, all it knows how to do is find the other end of a - word or expression. *Note Syntax::. - -Point - Point is the place in the buffer at which insertion and deletion - occur. Point is considered to be between two characters, not at - one character. The terminal's cursor (q.v.) indicates the - location of point. *Note Point: Basic. - -Prefix Key - A prefix key is a key (q.v.) whose sole function is to introduce a - set of multi-character keys. `Control-x' is an example of a prefix - key; any two-character sequence starting with `C-x' is also a - legitimate key. *Note Keystrokes::. - -Prompt - A prompt is text printed to ask the user for input. Printing a - prompt is called prompting. Emacs prompts always appear in the - echo area (q.v.). One kind of prompting happens when the - minibuffer is used to read an argument (*note Minibuffer::); the - echoing which happens when you pause in the middle of typing a - multi-character key is also a kind of prompting (*note Echo - Area::). - -Quitting - Quitting means cancelling a partially typed command or a running - command, using `C-g'. *Note Quitting::. - -Quoting - Quoting means depriving a character of its usual special - significance. In Emacs this is usually done with `Control-q'. - What constitutes special significance depends on the context and - on convention. For example, an "ordinary" character as an Emacs - command inserts itself; so in this context, a special character is - any character that does not normally insert itself (such as , - for example), and quoting it makes it insert itself as if it were - not special. Not all contexts allow quoting. *Note Quoting: - Basic. - -Read-only Buffer - A read-only buffer is one whose text you are not allowed to change. - Normally Emacs makes buffers read-only when they contain text which - has a special significance to Emacs, such asDired buffers. - Visiting a file that is write-protected also makes a read-only - buffer. *Note Buffers::. - -Recursive Editing Level - A recursive editing level is a state in which part of the - execution of a command involves asking the user to edit some text. - This text may or may not be the same as the text to which the - command was applied. The mode line indicates recursive editing - levels with square brackets (`[' and `]'). *Note Recursive Edit::. - -Redisplay - Redisplay is the process of correcting the image on the screen to - correspond to changes that have been made in the text being edited. - *Note Redisplay: Frame. - -Regexp - See `regular expression'. - -Region - The region is the text between point (q.v.) and the mark (q.v.). - Many commands operate on the text of the region. *Note Region: - Mark. - -Registers - Registers are named slots in which text or buffer positions or - rectangles can be saved for later use. *Note Registers::. - -Regular Expression - A regular expression is a pattern that can match various text - strings; for example, `l[0-9]+' matches `l' followed by one or more - digits. *Note Regexps::. - -Replacement - See `global substitution'. - -Restriction - A buffer's restriction is the amount of text, at the beginning or - the end of the buffer, that is temporarily invisible and - inaccessible. Giving a buffer a nonzero amount of restriction is - called narrowing (q.v.). *Note Narrowing::. - - - is the character than runs the command to insert a newline - into the text. It is also used to terminate most arguments read - in the minibuffer (q.v.). *Note Return: Keystrokes. - -Saving - Saving a buffer means copying its text into the file that was - visited (q.v.) in that buffer. To actually change a file you have - edited in Emacs, you have to save it. *Note Saving::. - -Scrolling - Scrolling means shifting the text in the Emacs window to make a - different part ot the buffer visible. *Note Scrolling: Display. - -Searching - Searching means moving point to the next occurrence of a specified - string. *Note Search::. - -Selecting - Selecting a buffer means making it the current (q.v.) buffer. - *Note Selecting: Buffers. - -Self-documentation - Self-documentation is the feature of Emacs which can tell you what - any command does, or can give you a list of all commands related - to a topic you specify. You ask for self-documentation with the - help character, `C-h'. *Note Help::. - -Sentences - Emacs has commands for moving by or killing by sentences. *Note - Sentences::. - -Sexp - An sexp (short for `s-expression,' itself short for `symbolic - expression') is the basic syntactic unit of Lisp in its textual - form: either a list, or Lisp atom. Many Emacs commands operate on - sexps. The term `sexp' is generalized to languages other than - Lisp to mean a syntactically recognizable expression. *Note - Sexps: Lists. - -Simultaneous Editing - Simultaneous editing means two users modifying the same file at - once. If simultaneous editing is not detected, you may lose your - work. Emacs detects all cases of simultaneous editing and warns - the user to investigate them. *Note Simultaneous Editing: - Interlocking. - -String - A string is a kind of Lisp data object which contains a sequence of - characters. Many Emacs variables are intended to have strings as - values. The Lisp syntax for a string consists of the characters in - the string with a `"' before and another `"' after. Write a `"' - that is part of the string as `\"' and a `\' that is part of the - string as `\\'. You can include all other characters, including - newline, just by writing them inside the string. You can also - include escape sequences as in C, such as `\n' for newline or - `\241' using an octal character code. - -String Substitution - See `global substitution'. - -Syntax Table - The syntax table tells Emacs which characters are part of a word, - which characters balance each other like parentheses, etc. *Note - Syntax::. - -Tag Table - A tag table is a file that serves as an index to the function - definitions in one or more other files. *Note Tags::. - -Termscript File - A termscript file contains a record of all characters Emacs sent to - the terminal. It is used for tracking down bugs in Emacs - redisplay. Emacs does not make a termscript file unless - explicitly instructed to do so. *Note Bugs::. - -Text - Text has two meanings (*note Text::): - - * Data consisting of a sequence of characters, as opposed to - binary numbers, images, graphics commands, executable - programs, and the like. The contents of an Emacs buffer are - always text in this sense. - - * Data consisting of written human language, as opposed to - programs, or something that follows the stylistic conventions - of human language. - -Top Level - Top level is the normal state of Emacs, in which you are editing - the text of the file you have visited. You are at top level - whenever you are not in a recursive editing level (q.v.) or the - minibuffer (q.v.), and not in the middle of a command. You can - get back to top level by aborting (q.v.) and quitting (q.v.). - *Note Quitting::. - -Transposition - Transposing two units of text means putting each one into the place - formerly occupied by the other. There are Emacs commands to - transpose two adjacent characters, words, sexps (q.v.), or lines - (*note Transpose::). - -Truncation - Truncating text lines in the display means leaving out any text on - a line that does not fit within the right margin of the window - displaying it. See also `continuation line'. *Note Truncation: - Basic. - -Undoing - Undoing means making your previous editing go in reverse, bringing - back the text that existed earlier in the editing session. *Note - Undo::. - -Variable - A variable is Lisp object that can store an arbitrary value. - Emacs uses some variables for internal purposes, and has others - (known as `options' (q.v.)) you can set to control the behavior of - Emacs. The variables used in Emacs that you are likely to be - interested in are listed in the Variables Index of this manual. - *Note Variables::, for information on variables. - -Visiting - Visiting a file means loading its contents into a buffer (q.v.) - where they can be edited. *Note Visiting::. - -Whitespace - Whitespace is any run of consecutive formatting characters (spaces, - tabs, newlines, and backspaces). - -Widening - Widening is removing any restriction (q.v.) on the current buffer; - it is the opposite of narrowing (q.v.). *Note Narrowing::. - -Window - Emacs divides the frame into one or more windows, each of which can - display the contents of one buffer (q.v.) at any time. *Note - Frame::, for basic information on how Emacs uses the frame. *Note - Windows::, for commands to control the use of windows. Note that if - you are running Emacs under X, terminology can be confusing: Each - Emacs frame occupies a separate X window and can, in turn, be - divided into different subwindows. - -Word Abbrev - Synonymous with `abbrev'. - -Word Search - Word search is searching for a sequence of words, considering the - punctuation between them as insignificant. *Note Word Search::. - -Yanking - Yanking means reinserting text previously killed. It can be used - to undo a mistaken kill, or for copying or moving text. Some other - systems call this "pasting". *Note Yanking::. +Frame Components +================ + + You can control the presence and position of most frame components, +such as the menubar, toolbars, and gutters. + + This section is not written yet. Try the Lisp Reference Manual: +*Note Menubar: (lispref)Menubar, *Note Toolbar Intro: (lispref)Toolbar +Intro, and *Note Gutter Intro: (lispref)Gutter Intro. + + +File: xemacs.info, Node: X Resources, Prev: Frame Components, Up: Customization + +X Resources +=========== + + Historically, XEmacs has used the X resource application class +`Emacs' for its resources. Unfortunately, GNU Emacs uses the same +application class, and resources are not compatible between the two +Emacsen. This sharing of the application class often leads to trouble +if you want to run both variants. + + Starting with XEmacs 21, XEmacs uses the class `XEmacs' if it finds +any XEmacs resources in the resource database when the X connection is +initialized. Otherwise, it will use the class `Emacs' for backwards +compatibility. The variable X-EMACS-APPLICATION-CLASS may be consulted +to determine the application class being used. + + The examples in this section assume the application class is `Emacs'. + + The Emacs resources are generally set per-frame. Each Emacs frame +can have its own name or the same name as another, depending on the +name passed to the `make-frame' function. + + You can specify resources for all frames with the syntax: + + Emacs*parameter: value + +or + + Emacs*EmacsFrame.parameter:value + +You can specify resources for a particular frame with the syntax: + + Emacs*FRAME-NAME.parameter: value + +* Menu: + +* Geometry Resources:: Controlling the size and position of frames. +* Iconic Resources:: Controlling whether frames come up iconic. +* Resource List:: List of resources settable on a frame or device. +* Face Resources:: Controlling faces using resources. +* Widgets:: The widget hierarchy for XEmacs. +* Menubar Resources:: Specifying resources for the menubar. + + +File: xemacs.info, Node: Geometry Resources, Next: Iconic Resources, Up: X Resources + +Geometry Resources +------------------ + + To make the default size of all Emacs frames be 80 columns by 55 +lines, do this: + + Emacs*EmacsFrame.geometry: 80x55 + +To set the geometry of a particular frame named `fred', do this: + + Emacs*fred.geometry: 80x55 + +Important! Do not use the following syntax: + + Emacs*geometry: 80x55 + +You should never use `*geometry' with any X application. It does not +say "make the geometry of Emacs be 80 columns by 55 lines." It really +says, "make Emacs and all subwindows thereof be 80x55 in whatever units +they care to measure in." In particular, that is both telling the +Emacs text pane to be 80x55 in characters, and telling the menubar pane +to be 80x55 pixels, which is surely not what you want. + + As a special case, this geometry specification also works (and sets +the default size of all Emacs frames to 80 columns by 55 lines): + + Emacs.geometry: 80x55 + +since that is the syntax used with most other applications (since most +other applications have only one top-level window, unlike Emacs). In +general, however, the top-level shell (the unmapped ApplicationShell +widget named `Emacs' that is the parent of the shell widgets that +actually manage the individual frames) does not have any interesting +resources on it, and you should set the resources on the frames instead. + + The `-geometry' command-line argument sets only the geometry of the +initial frame created by Emacs. + + A more complete explanation of geometry-handling is + + * The `-geometry' command-line option sets the `Emacs.geometry' + resource, that is, the geometry of the ApplicationShell. + + * For the first frame created, the size of the frame is taken from + the ApplicationShell if it is specified, otherwise from the + geometry of the frame. + + * For subsequent frames, the order is reversed: First the frame, and + then the ApplicationShell. + + * For the first frame created, the position of the frame is taken + from the ApplicationShell (`Emacs.geometry') if it is specified, + otherwise from the geometry of the frame. + + * For subsequent frames, the position is taken only from the frame, + and never from the ApplicationShell. + + This is rather complicated, but it does seem to provide the most +intuitive behavior with respect to the default sizes and positions of +frames created in various ways. + + +File: xemacs.info, Node: Iconic Resources, Next: Resource List, Prev: Geometry Resources, Up: X Resources + +Iconic Resources +---------------- + + Analogous to `-geometry', the `-iconic' command-line option sets the +iconic flag of the ApplicationShell (`Emacs.iconic') and always applies +to the first frame created regardless of its name. However, it is +possible to set the iconic flag on particular frames (by name) by using +the `Emacs*FRAME-NAME.iconic' resource. + + +File: xemacs.info, Node: Resource List, Next: Face Resources, Prev: Iconic Resources, Up: X Resources + +Resource List +------------- + + Emacs frames accept the following resources: + +`geometry' (class `Geometry'): string + Initial geometry for the frame. *Note Geometry Resources::, for a + complete discussion of how this works. + +`iconic' (class `Iconic'): boolean + Whether this frame should appear in the iconified state. + +`internalBorderWidth' (class `InternalBorderWidth'): int + How many blank pixels to leave between the text and the edge of the + window. + +`interline' (class `Interline'): int + How many pixels to leave between each line (may not be + implemented). + +`menubar' (class `Menubar'): boolean + Whether newly-created frames should initially have a menubar. Set + to true by default. + +`initiallyUnmapped' (class `InitiallyUnmapped'): boolean + Whether XEmacs should leave the initial frame unmapped when it + starts up. This is useful if you are starting XEmacs as a server + (e.g. in conjunction with gnuserv or the external client widget). + You can also control this with the `-unmapped' command-line option. + +`barCursor' (class `BarColor'): boolean + Whether the cursor should be displayed as a bar, or the + traditional box. + +`cursorColor' (class `CursorColor'): color-name + The color of the text cursor. + +`scrollBarWidth' (class `ScrollBarWidth'): integer + How wide the vertical scrollbars should be, in pixels; 0 means no + vertical scrollbars. You can also use a resource specification of + the form `*scrollbar.width', or the usual toolkit scrollbar + resources: `*XmScrollBar.width' (Motif), `*XlwScrollBar.width' + (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend + that you use the toolkit resources, though, because they're + dependent on how exactly your particular build of XEmacs was + configured. + +`scrollBarHeight' (class `ScrollBarHeight'): integer + How high the horizontal scrollbars should be, in pixels; 0 means no + horizontal scrollbars. You can also use a resource specification + of the form `*scrollbar.height', or the usual toolkit scrollbar + resources: `*XmScrollBar.height' (Motif), `*XlwScrollBar.height' + (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend + that you use the toolkit resources, though, because they're + dependent on how exactly your particular build of XEmacs was + configured. + +`scrollBarPlacement' (class `ScrollBarPlacement'): string + Where the horizontal and vertical scrollbars should be positioned. + This should be one of the four strings `BOTTOM_LEFT', + `BOTTOM_RIGHT', `TOP_LEFT', and `TOP_RIGHT'. Default is + `BOTTOM_RIGHT' for the Motif and Lucid scrollbars and + `BOTTOM_LEFT' for the Athena scrollbars. + +`topToolBarHeight' (class `TopToolBarHeight'): integer +`bottomToolBarHeight' (class `BottomToolBarHeight'): integer +`leftToolBarWidth' (class `LeftToolBarWidth'): integer +`rightToolBarWidth' (class `RightToolBarWidth'): integer + Height and width of the four possible toolbars. + +`topToolBarShadowColor' (class `TopToolBarShadowColor'): color-name +`bottomToolBarShadowColor' (class `BottomToolBarShadowColor'): color-name + Color of the top and bottom shadows for the toolbars. NOTE: These + resources do _not_ have anything to do with the top and bottom + toolbars (i.e. the toolbars at the top and bottom of the frame)! + Rather, they affect the top and bottom shadows around the edges of + all four kinds of toolbars. + +`topToolBarShadowPixmap' (class `TopToolBarShadowPixmap'): pixmap-name +`bottomToolBarShadowPixmap' (class `BottomToolBarShadowPixmap'): pixmap-name + Pixmap of the top and bottom shadows for the toolbars. If set, + these resources override the corresponding color resources. NOTE: + These resources do _not_ have anything to do with the top and + bottom toolbars (i.e. the toolbars at the top and bottom of the + frame)! Rather, they affect the top and bottom shadows around the + edges of all four kinds of toolbars. + +`toolBarShadowThickness' (class `ToolBarShadowThickness'): integer + Thickness of the shadows around the toolbars, in pixels. + +`visualBell' (class `VisualBell'): boolean + Whether XEmacs should flash the screen rather than making an + audible beep. + +`bellVolume' (class `BellVolume'): integer + Volume of the audible beep. + +`useBackingStore' (class `UseBackingStore'): boolean + Whether XEmacs should set the backing-store attribute of the X + windows it creates. This increases the memory usage of the X + server but decreases the amount of X traffic necessary to update + the screen, and is useful when the connection to the X server goes + over a low-bandwidth line such as a modem connection. + + Emacs devices accept the following resources: + +`textPointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over text. This resource is + used to initialize the variable `x-pointer-shape'. + +`selectionPointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over a selectable text region + (an extent with the `highlight' property; for example, an Info + cross-reference). This resource is used to initialize the variable + `x-selection-pointer-shape'. + +`spacePointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over a blank space in a buffer + (that is, after the end of a line or after the end-of-file). This + resource is used to initialize the variable + `x-nontext-pointer-shape'. + +`modeLinePointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over a modeline. This + resource is used to initialize the variable `x-mode-pointer-shape'. + +`gcPointer' (class `Cursor'): cursor-name + The cursor to display when a garbage-collection is in progress. + This resource is used to initialize the variable + `x-gc-pointer-shape'. + +`scrollbarPointer' (class `Cursor'): cursor-name + The cursor to use when the mouse is over the scrollbar. This + resource is used to initialize the variable + `x-scrollbar-pointer-shape'. + +`pointerColor' (class `Foreground'): color-name +`pointerBackground' (class `Background'): color-name + The foreground and background colors of the mouse cursor. These + resources are used to initialize the variables + `x-pointer-foreground-color' and `x-pointer-background-color'. + + +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::.