-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
translation approved by the author instead of in the original English.
\1f
+File: xemacs.info, Node: Disabling, Prev: Rebinding, Up: Key Bindings
+
+Disabling Commands
+------------------
+
+ Disabling a command marks it as requiring confirmation before it can
+be executed. The purpose of disabling a command is to prevent
+beginning users from executing it by accident and being confused.
+
+ The direct mechanism for disabling a command is to have a non-`nil'
+`disabled' property on the Lisp symbol for the command. These
+properties are normally set by the user's init file with Lisp
+expressions such as:
+
+ (put 'delete-region 'disabled t)
+
+ *Note Init File::.
+
+ If the value of the `disabled' property is a string, that string is
+included in the message printed when the command is used:
+
+ (put 'delete-region 'disabled
+ "Text deleted this way cannot be yanked back!\n")
+
+ You can disable a command either by editing the init file directly
+or with the command `M-x disable-command', which edits the init file
+for you. *Note Init File::.
+
+ When you attempt to invoke a disabled command interactively in Emacs,
+a window is displayed containing the command's name, its documentation,
+and some instructions on what to do next; then Emacs asks for input
+saying whether to execute the command as requested, enable it and
+execute, or cancel it. If you decide to enable the command, you are
+asked whether to do this permanently or just for the current session.
+Enabling permanently works by automatically editing your init file.
+You can use `M-x enable-command' at any time to enable any command
+permanently.
+
+ Whether a command is disabled is independent of what key is used to
+invoke it; it also applies if the command is invoked using `M-x'.
+Disabling a command has no effect on calling it as a function from Lisp
+programs.
+
+\1f
+File: xemacs.info, Node: Syntax, Next: Init File, Prev: Key Bindings, Up: Customization
+
+The Syntax Table
+================
+
+ All the Emacs commands which parse words or balance parentheses are
+controlled by the "syntax table". The syntax table specifies which
+characters are opening delimiters, which are parts of words, which are
+string quotes, and so on. Actually, each major mode has its own syntax
+table (though sometimes related major modes use the same one) which it
+installs in each buffer that uses that major mode. The syntax table
+installed in the current buffer is the one that all commands use, so we
+call it "the" syntax table. A syntax table is a Lisp object, a vector
+of length 256 whose elements are numbers.
+
+* Menu:
+
+* Entry: Syntax Entry. What the syntax table records for each character.
+* Change: Syntax Change. How to change the information.
+
+\1f
+File: xemacs.info, Node: Syntax Entry, Next: Syntax Change, Up: Syntax
+
+Information About Each Character
+--------------------------------
+
+ The syntax table entry for a character is a number that encodes six
+pieces of information:
+
+ * The syntactic class of the character, represented as a small
+ integer
+
+ * The matching delimiter, for delimiter characters only (the
+ matching delimiter of `(' is `)', and vice versa)
+
+ * A flag saying whether the character is the first character of a
+ two-character comment starting sequence
+
+ * A flag saying whether the character is the second character of a
+ two-character comment starting sequence
+
+ * A flag saying whether the character is the first character of a
+ two-character comment ending sequence
+
+ * A flag saying whether the character is the second character of a
+ two-character comment ending sequence
+
+ The syntactic classes are stored internally as small integers, but
+are usually described to or by the user with characters. For example,
+`(' is used to specify the syntactic class of opening delimiters. Here
+is a table of syntactic classes, with the characters that specify them.
+
+` '
+ The class of whitespace characters.
+
+`w'
+ The class of word-constituent characters.
+
+`_'
+ The class of characters that are part of symbol names but not
+ words. This class is represented by `_' because the character `_'
+ has this class in both C and Lisp.
+
+`.'
+ The class of punctuation characters that do not fit into any other
+ special class.
+
+`('
+ The class of opening delimiters.
+
+`)'
+ The class of closing delimiters.
+
+`''
+ The class of expression-adhering characters. These characters are
+ part of a symbol if found within or adjacent to one, and are part
+ of a following expression if immediately preceding one, but are
+ like whitespace if surrounded by whitespace.
+
+`"'
+ The class of string-quote characters. They match each other in
+ pairs, and the characters within the pair all lose their syntactic
+ significance except for the `\' and `/' classes of escape
+ characters, which can be used to include a string-quote inside the
+ string.
+
+`$'
+ The class of self-matching delimiters. This is intended for TeX's
+ `$', which is used both to enter and leave math mode. Thus, a
+ pair of matching `$' characters surround each piece of math mode
+ TeX input. A pair of adjacent `$' characters act like a single
+ one for purposes of matching.
+
+`/'
+ The class of escape characters that always just deny the following
+ character its special syntactic significance. The character after
+ one of these escapes is always treated as alphabetic.
+
+`\'
+ The class of C-style escape characters. In practice, these are
+ treated just like `/'-class characters, because the extra
+ possibilities for C escapes (such as being followed by digits)
+ have no effect on where the containing expression ends.
+
+`<'
+ The class of comment-starting characters. Only single-character
+ comment starters (such as `;' in Lisp mode) are represented this
+ way.
+
+`>'
+ The class of comment-ending characters. Newline has this syntax in
+ Lisp mode.
+
+ The characters flagged as part of two-character comment delimiters
+can have other syntactic functions most of the time. For example, `/'
+and `*' in C code, when found separately, have nothing to do with
+comments. The comment-delimiter significance overrides when the pair of
+characters occur together in the proper order. Only the list and sexp
+commands use the syntax table to find comments; the commands
+specifically for comments have other variables that tell them where to
+find comments. Moreover, the list and sexp commands notice comments
+only if `parse-sexp-ignore-comments' is non-`nil'. This variable is set
+to `nil' in modes where comment-terminator sequences are liable to
+appear where there is no comment, for example, in Lisp mode where the
+comment terminator is a newline but not every newline ends a comment.
+
+\1f
+File: xemacs.info, Node: Syntax Change, Prev: Syntax Entry, Up: Syntax
+
+Altering Syntax Information
+---------------------------
+
+ It is possible to alter a character's syntax table entry by storing
+a new number in the appropriate element of the syntax table, but it
+would be hard to determine what number to use. Emacs therefore
+provides a command that allows you to specify the syntactic properties
+of a character in a convenient way.
+
+ `M-x modify-syntax-entry' is the command to change a character's
+syntax. It can be used interactively and is also used by major modes
+to initialize their own syntax tables. Its first argument is the
+character to change. The second argument is a string that specifies the
+new syntax. When called from Lisp code, there is a third, optional
+argument, which specifies the syntax table in which to make the change.
+If not supplied, or if this command is called interactively, the third
+argument defaults to the current buffer's syntax table.
+
+ 1. The first character in the string specifies the syntactic class.
+ It is one of the characters in the previous table (*note Syntax
+ Entry::).
+
+ 2. The second character is the matching delimiter. For a character
+ that is not an opening or closing delimiter, this should be a
+ space, and may be omitted if no following characters are needed.
+
+ 3. The remaining characters are flags. The flag characters allowed
+ are:
+
+ `1'
+ Flag this character as the first of a two-character comment
+ starting sequence.
+
+ `2'
+ Flag this character as the second of a two-character comment
+ starting sequence.
+
+ `3'
+ Flag this character as the first of a two-character comment
+ ending sequence.
+
+ `4'
+ Flag this character as the second of a two-character comment
+ ending sequence.
+
+ Use `C-h s' (`describe-syntax') to display a description of the
+contents of the current syntax table. The description of each
+character includes both the string you have to pass to
+`modify-syntax-entry' to set up that character's current syntax, and
+some English to explain that string if necessary.
+
+\1f
+File: xemacs.info, Node: Init File, Next: Audible Bell, Prev: Syntax, Up: Customization
+
+The Init File
+=============
+
+ When you start Emacs, it normally loads either `.xemacs/init.el' or
+the file `.emacs' (whichever comes first) in your home directory. This
+file, if it exists, should contain Lisp code. It is called your
+initialization file or "init file". Use the command line switch `-q'
+to tell Emacs whether to load an init file (*note Entering Emacs::).
+Use the command line switch `-user-init-file' (*note Command
+Switches::) to tell Emacs to load a different file instead of
+`~/.xemacs/init.el'/`~/.emacs'.
+
+ When the init file is read, the variable `user-init-file' says which
+init file was loaded.
+
+ At some sites there is a "default init file", which is the library
+named `default.el', found via the standard search path for libraries.
+The Emacs distribution contains no such library; your site may create
+one for local customizations. If this library exists, it is loaded
+whenever you start Emacs. But your init file, if any, is loaded first;
+if it sets `inhibit-default-init' non-`nil', then `default' is not
+loaded.
+
+ If you have a large amount of code in your init file, you should
+byte-compile it to `~/.xemacs/init.elc' or `~/.emacs.elc'.
+
+* Menu:
+
+* Init Syntax:: Syntax of constants in Emacs Lisp.
+* Init Examples:: How to do some things with an init file.
+* Terminal Init:: Each terminal type can have an init file.
+
+\1f
+File: xemacs.info, Node: Init Syntax, Next: Init Examples, Up: Init File
+
+Init File Syntax
+----------------
+
+ The init file contains one or more Lisp function call expressions.
+Each consists of a function name followed by arguments, all surrounded
+by parentheses. For example, `(setq fill-column 60)' represents a call
+to the function `setq' which is used to set the variable `fill-column'
+(*note Filling::) to 60.
+
+ The second argument to `setq' is an expression for the new value of
+the variable. This can be a constant, a variable, or a function call
+expression. In the init file, constants are used most of the time.
+They can be:
+
+Numbers
+ Integers are written in decimal, with an optional initial minus
+ sign.
+
+ If a sequence of digits is followed by a period and another
+ sequence of digits, it is interpreted as a floating point number.
+
+ The number prefixes `#b', `#o', and `#x' are supported to
+ represent numbers in binary, octal, and hexadecimal notation (or
+ radix).
+
+Strings
+ Lisp string syntax is the same as C string syntax with a few extra
+ features. Use a double-quote character to begin and end a string
+ constant.
+
+ Newlines and special characters may be present literally in
+ strings. They can also be represented as backslash sequences:
+ `\n' for newline, `\b' for backspace, `\r' for return, `\t' for
+ tab, `\f' for formfeed (control-l), `\e' for escape, `\\' for a
+ backslash, `\"' for a double-quote, or `\OOO' for the character
+ whose octal code is OOO. Backslash and double-quote are the only
+ characters for which backslash sequences are mandatory.
+
+ You can use `\C-' as a prefix for a control character, as in
+ `\C-s' for ASCII Control-S, and `\M-' as a prefix for a Meta
+ character, as in `\M-a' for Meta-A or `\M-\C-a' for Control-Meta-A.
+
+Characters
+ Lisp character constant syntax consists of a `?' followed by
+ either a character or an escape sequence starting with `\'.
+ Examples: `?x', `?\n', `?\"', `?\)'. Note that strings and
+ characters are not interchangeable in Lisp; some contexts require
+ one and some contexts require the other.
+
+True
+ `t' stands for `true'.
+
+False
+ `nil' stands for `false'.
+
+Other Lisp objects
+ Write a single-quote (') followed by the Lisp object you want.
+
+\1f
+File: xemacs.info, Node: Init Examples, Next: Terminal Init, Prev: Init Syntax, Up: Init File
+
+Init File Examples
+------------------
+
+ Here are some examples of doing certain commonly desired things with
+Lisp expressions:
+
+ * Make <TAB> in C mode just insert a tab if point is in the middle
+ of a line.
+
+ (setq c-tab-always-indent nil)
+
+ Here we have a variable whose value is normally `t' for `true' and
+ the alternative is `nil' for `false'.
+
+ * Make searches case sensitive by default (in all buffers that do not
+ override this).
+
+ (setq-default case-fold-search nil)
+
+ This sets the default value, which is effective in all buffers
+ that do not have local values for the variable. Setting
+ `case-fold-search' with `setq' affects only the current buffer's
+ local value, which is probably not what you want to do in an init
+ file.
+
+ * Make Text mode the default mode for new buffers.
+
+ (setq default-major-mode 'text-mode)
+
+ Note that `text-mode' is used because it is the command for
+ entering the mode we want. A single-quote is written before it to
+ make a symbol constant; otherwise, `text-mode' would be treated as
+ a variable name.
+
+ * Turn on Auto Fill mode automatically in Text mode and related
+ modes.
+
+ (setq text-mode-hook
+ '(lambda () (auto-fill-mode 1)))
+
+ Here we have a variable whose value should be a Lisp function. The
+ function we supply is a list starting with `lambda', and a single
+ quote is written in front of it to make it (for the purpose of this
+ `setq') a list constant rather than an expression. Lisp functions
+ are not explained here; for mode hooks it is enough to know that
+ `(auto-fill-mode 1)' is an expression that will be executed when
+ Text mode is entered. You could replace it with any other
+ expression that you like, or with several expressions in a row.
+
+ (setq text-mode-hook 'turn-on-auto-fill)
+
+ This is another way to accomplish the same result.
+ `turn-on-auto-fill' is a symbol whose function definition is
+ `(lambda () (auto-fill-mode 1))'.
+
+ * Load the installed Lisp library named `foo' (actually a file
+ `foo.elc' or `foo.el' in a standard Emacs directory).
+
+ (load "foo")
+
+ When the argument to `load' is a relative pathname, not starting
+ with `/' or `~', `load' searches the directories in `load-path'
+ (*note Loading::).
+
+ * Load the compiled Lisp file `foo.elc' from your home directory.
+
+ (load "~/foo.elc")
+
+ Here an absolute file name is used, so no searching is done.
+
+ * Rebind the key `C-x l' to run the function `make-symbolic-link'.
+
+ (global-set-key "\C-xl" 'make-symbolic-link)
+
+ or
+
+ (define-key global-map "\C-xl" 'make-symbolic-link)
+
+ Note once again the single-quote used to refer to the symbol
+ `make-symbolic-link' instead of its value as a variable.
+
+ * Do the same thing for C mode only.
+
+ (define-key c-mode-map "\C-xl" 'make-symbolic-link)
+
+ * Bind the function key <F1> to a command in C mode. Note that the
+ names of function keys must be lower case.
+
+ (define-key c-mode-map 'f1 'make-symbolic-link)
+
+ * Bind the shifted version of <F1> to a command.
+
+ (define-key c-mode-map '(shift f1) 'make-symbolic-link)
+
+ * Redefine all keys which now run `next-line' in Fundamental mode to
+ run `forward-line' instead.
+
+ (substitute-key-definition 'next-line 'forward-line
+ global-map)
+
+ * Make `C-x C-v' undefined.
+
+ (global-unset-key "\C-x\C-v")
+
+ One reason to undefine a key is so that you can make it a prefix.
+ Simply defining `C-x C-v ANYTHING' would make `C-x C-v' a prefix,
+ but `C-x C-v' must be freed of any non-prefix definition first.
+
+ * Make `$' have the syntax of punctuation in Text mode. Note the
+ use of a character constant for `$'.
+
+ (modify-syntax-entry ?\$ "." text-mode-syntax-table)
+
+ * Enable the use of the command `eval-expression' without
+ confirmation.
+
+ (put 'eval-expression 'disabled nil)
+
+\1f
+File: xemacs.info, Node: Terminal Init, Prev: Init Examples, Up: Init File
+
+Terminal-Specific Initialization
+--------------------------------
+
+ Each terminal type can have a Lisp library to be loaded into Emacs
+when it is run on that type of terminal. For a terminal type named
+TERMTYPE, the library is called `term/TERMTYPE' and it is found by
+searching the directories `load-path' as usual and trying the suffixes
+`.elc' and `.el'. Normally it appears in the subdirectory `term' of
+the directory where most Emacs libraries are kept.
+
+ The usual purpose of the terminal-specific library is to define the
+escape sequences used by the terminal's function keys using the library
+`keypad.el'. See the file `term/vt100.el' for an example of how this
+is done.
+
+ When the terminal type contains a hyphen, only the part of the name
+before the first hyphen is significant in choosing the library name.
+Thus, terminal types `aaa-48' and `aaa-30-rv' both use the library
+`term/aaa'. The code in the library can use `(getenv "TERM")' to find
+the full terminal type name.
+
+ The library's name is constructed by concatenating the value of the
+variable `term-file-prefix' and the terminal type. Your init file can
+prevent the loading of the terminal-specific library by setting
+`term-file-prefix' to `nil'. *Note Init File::.
+
+ The value of the variable `term-setup-hook', if not `nil', is called
+as a function of no arguments at the end of Emacs initialization, after
+both your init file and any terminal-specific library have been read.
+*Note Init File::. You can set the value in the init file to override
+part of any of the terminal-specific libraries and to define
+initializations for terminals that do not have a library.
+
+\1f
+File: xemacs.info, Node: Audible Bell, Next: Faces, Prev: Init File, Up: Customization
+
+Changing the Bell Sound
+=======================
+
+ You can now change how the audible bell sounds using the variable
+`sound-alist'.
+
+ `sound-alist''s value is an list associating symbols with, among
+other things, strings of audio-data. When `ding' is called with one of
+the symbols, the associated sound data is played instead of the
+standard beep. This only works if you are logged in on the console of a
+machine with audio hardware. To listen to a sound of the provided type,
+call the function `play-sound' with the argument SOUND. You can also
+set the volume of the sound with the optional argument VOLUME.
+
+ Each element of `sound-alist' is a list describing a sound. The
+first element of the list is the name of the sound being defined.
+Subsequent elements of the list are alternating keyword/value pairs:
+
+`sound'
+ A string of raw sound data, or the name of another sound to play.
+ The symbol `t' here means use the default X beep.
+
+`volume'
+ An integer from 0-100, defaulting to `bell-volume'.
+
+`pitch'
+ If using the default X beep, the pitch (Hz) to generate.
+
+`duration'
+ If using the default X beep, the duration (milliseconds).
+
+ For compatibility, elements of `sound-alist' may also be of the form:
+
+ ( SOUND-NAME . <SOUND> )
+ ( SOUND-NAME <VOLUME> <SOUND> )
+
+ You should probably add things to this list by calling the function
+`load-sound-file'.
+
+ Note that you can only play audio data if running on the console
+screen of a machine with audio hardware which emacs understands, which
+at this time means a Sun SparcStation, SGI, or HP9000s700.
+
+ Also note that the pitch, duration, and volume options are available
+everywhere, but most X servers ignore the `pitch' option.
+
+ The variable `bell-volume' should be an integer from 0 to 100, with
+100 being loudest, which controls how loud the sounds emacs makes
+should be. Elements of the `sound-alist' may override this value.
+This variable applies to the standard X bell sound as well as sound
+files.
+
+ If the symbol `t' is in place of a sound-string, Emacs uses the
+default X beep. This allows you to define beep-types of different
+volumes even when not running on the console.
+
+ You can add things to this list by calling the function
+`load-sound-file', which reads in an audio-file and adds its data to
+the sound-alist. You can specify the sound with the SOUND-NAME argument
+and the file into which the sounds are loaded with the FILENAME
+argument. The optional VOLUME argument sets the volume.
+
+ `load-sound-file (FILENAME SOUND-NAME &optional VOLUME)'
+
+ To load and install some sound files as beep-types, use the function
+`load-default-sounds' (note that this only works if you are on display
+0 of a machine with audio hardware).
+
+ The following beep-types are used by Emacs itself. Other Lisp
+packages may use other beep types, but these are the ones that the C
+kernel of Emacs uses.
+
+`auto-save-error'
+ An auto-save does not succeed
+
+`command-error'
+ The Emacs command loop catches an error
+
+`undefined-key'
+ You type a key that is undefined
+
+`undefined-click'
+ You use an undefined mouse-click combination
+
+`no-completion'
+ Completion was not possible
+
+`y-or-n-p'
+ You type something other than the required `y' or `n'
+
+`yes-or-no-p'
+ You type something other than `yes' or `no'
+
+\1f
File: xemacs.info, Node: Faces, Next: Frame Components, Prev: Audible Bell, Up: Customization
Faces
recursive editing level. To do so, type `M-x top-level'. This is
called getting back to top level. *Note Recursive Edit::.
-\1f
-File: xemacs.info, Node: Screen Garbled, Next: Text Garbled, Prev: Stuck Recursive, Up: Lossage
-
-Garbage on the Screen
----------------------
-
- If the data on the screen looks wrong, the first thing to do is see
-whether the text is actually wrong. Type `C-l', to redisplay the
-entire screen. If the text appears correct after this, the problem was
-entirely in the previous screen update.
-
- Display updating problems often result from an incorrect termcap
-entry for the terminal you are using. The file `etc/TERMS' in the Emacs
-distribution gives the fixes for known problems of this sort.
-`INSTALL' contains general advice for these problems in one of its
-sections. Very likely there is simply insufficient padding for certain
-display operations. To investigate the possibility that you have this
-sort of problem, try Emacs on another terminal made by a different
-manufacturer. If problems happen frequently on one kind of terminal but
-not another kind, the real problem is likely to be a bad termcap entry,
-though it could also be due to a bug in Emacs that appears for terminals
-that have or lack specific features.
-
-\1f
-File: xemacs.info, Node: Text Garbled, Next: Unasked-for Search, Prev: Screen Garbled, Up: Lossage
-
-Garbage in the Text
--------------------
-
- If `C-l' shows that the text is wrong, try undoing the changes to it
-using `C-x u' until it gets back to a state you consider correct. Also
-try `C-h l' to find out what command you typed to produce the observed
-results.
-
- If a large portion of text appears to be missing at the beginning or
-end of the buffer, check for the word `Narrow' in the mode line. If it
-appears, the text is still present, but marked off-limits. To make it
-visible again, type `C-x n w'. *Note Narrowing::.
-
-\1f
-File: xemacs.info, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage
-
-Spontaneous Entry to Incremental Search
----------------------------------------
-
- If Emacs spontaneously displays `I-search:' at the bottom of the
-screen, it means that the terminal is sending `C-s' and `C-q' according
-to the poorly designed xon/xoff "flow control" protocol. You should
-try to prevent this by putting the terminal in a mode where it will not
-use flow control, or by giving it enough padding that it will never
-send a `C-s'. If that cannot be done, you must tell Emacs to expect
-flow control to be used, until you can get a properly designed terminal.
-
- Information on how to do these things can be found in the file
-`INSTALL' in the Emacs distribution.
-
-\1f
-File: xemacs.info, Node: Emergency Escape, Next: Total Frustration, Prev: Unasked-for Search, Up: Lossage
-
-Emergency Escape
-----------------
-
- Because at times there have been bugs causing Emacs to loop without
-checking `quit-flag', a special feature causes Emacs to be suspended
-immediately if you type a second `C-g' while the flag is already set,
-so you can always get out of XEmacs. Normally Emacs recognizes and
-clears `quit-flag' (and quits!) quickly enough to prevent this from
-happening.
-
- When you resume Emacs after a suspension caused by multiple `C-g', it
-asks two questions before going back to what it had been doing:
-
- Auto-save? (y or n)
- Abort (and dump core)? (y or n)
-
-Answer each one with `y' or `n' followed by <RET>.
-
- Saying `y' to `Auto-save?' causes immediate auto-saving of all
-modified buffers in which auto-saving is enabled.
-
- Saying `y' to `Abort (and dump core)?' causes an illegal instruction
-to be executed, dumping core. This is to enable a wizard to figure out
-why Emacs was failing to quit in the first place. Execution does not
-continue after a core dump. If you answer `n', execution does
-continue. With luck, Emacs will ultimately check `quit-flag' and quit
-normally. If not, and you type another `C-g', it is suspended again.
-
- If Emacs is not really hung, but is just being slow, you may invoke
-the double `C-g' feature without really meaning to. In that case,
-simply resume and answer `n' to both questions, and you will arrive at
-your former state. Presumably the quit you requested will happen soon.
-
- The double-`C-g' feature may be turned off when Emacs is running
-under a window system, since the window system always enables you to
-kill Emacs or to create another window and run another program.
-
-\1f
-File: xemacs.info, Node: Total Frustration, Prev: Emergency Escape, Up: Lossage
-
-Help for Total Frustration
---------------------------
-
- If using Emacs (or something else) becomes terribly frustrating and
-none of the techniques described above solve the problem, Emacs can
-still help you.
-
- First, if the Emacs you are using is not responding to commands, type
-`C-g C-g' to get out of it and then start a new one.
-
- Second, type `M-x doctor <RET>'.
-
- The doctor will make you feel better. Each time you say something to
-the doctor, you must end it by typing <RET> <RET>. This lets the
-doctor know you are finished.
-
-\1f
-File: xemacs.info, Node: Bugs, Prev: Lossage, Up: Top
-
-Reporting Bugs
-==============
-
- Sometimes you will encounter a bug in Emacs. Although we cannot
-promise we can or will fix the bug, and we might not even agree that it
-is a bug, we want to hear about bugs you encounter in case we do want
-to fix them.
-
- To make it possible for us to fix a bug, you must report it. In
-order to do so effectively, you must know when and how to do it.
-
-When Is There a Bug
--------------------
-
- If Emacs executes an illegal instruction, or dies with an operating
-system error message that indicates a problem in the program (as
-opposed to something like "disk full"), then it is certainly a bug.
-
- If Emacs updates the display in a way that does not correspond to
-what is in the buffer, then it is certainly a bug. If a command seems
-to do the wrong thing but the problem corrects itself if you type
-`C-l', it is a case of incorrect display updating.
-
- Taking forever to complete a command can be a bug, but you must make
-certain that it was really Emacs's fault. Some commands simply take a
-long time. Type `C-g' and then `C-h l' to see whether the input Emacs
-received was what you intended to type; if the input was such that you
-KNOW it should have been processed quickly, report a bug. If you don't
-know whether the command should take a long time, find out by looking
-in the manual or by asking for assistance.
-
- If a command you are familiar with causes an Emacs error message in a
-case where its usual definition ought to be reasonable, it is probably a
-bug.
-
- If a command does the wrong thing, that is a bug. But be sure you
-know for certain what it ought to have done. If you aren't familiar
-with the command, or don't know for certain how the command is supposed
-to work, then it might actually be working right. Rather than jumping
-to conclusions, show the problem to someone who knows for certain.
-
- Finally, a command's intended definition may not be best for editing
-with. This is a very important sort of problem, but it is also a
-matter of judgment. Also, it is easy to come to such a conclusion out
-of ignorance of some of the existing features. It is probably best not
-to complain about such a problem until you have checked the
-documentation in the usual ways, feel confident that you understand it,
-and know for certain that what you want is not available. If you are
-not sure what the command is supposed to do after a careful reading of
-the manual, check the index and glossary for any terms that may be
-unclear. If you still do not understand, this indicates a bug in the
-manual. The manual's job is to make everything clear. It is just as
-important to report documentation bugs as program bugs.
-
- If the online documentation string of a function or variable
-disagrees with the manual, one of them must be wrong, so report the bug.
-
-How to Report a Bug
--------------------
-
- When you decide that there is a bug, it is important to report it
-and to report it in a way which is useful. What is most useful is an
-exact description of what commands you type, starting with the shell
-command to run Emacs, until the problem happens. Always include the
-version number of Emacs that you are using; type `M-x emacs-version' to
-print this.
-
- The most important principle in reporting a bug is to report FACTS,
-not hypotheses or categorizations. It is always easier to report the
-facts, but people seem to prefer to strain to posit explanations and
-report them instead. If the explanations are based on guesses about
-how Emacs is implemented, they will be useless; we will have to try to
-figure out what the facts must have been to lead to such speculations.
-Sometimes this is impossible. But in any case, it is unnecessary work
-for us.
-
- For example, suppose that you type `C-x C-f /glorp/baz.ugh <RET>',
-visiting a file which (you know) happens to be rather large, and Emacs
-prints out `I feel pretty today'. The best way to report the bug is
-with a sentence like the preceding one, because it gives all the facts
-and nothing but the facts.
-
- Do not assume that the problem is due to the size of the file and
-say, "When I visit a large file, Emacs prints out `I feel pretty
-today'." This is what we mean by "guessing explanations". The problem
-is just as likely to be due to the fact that there is a `z' in the file
-name. If this is so, then when we got your report, we would try out
-the problem with some "large file", probably with no `z' in its name,
-and not find anything wrong. There is no way in the world that we
-could guess that we should try visiting a file with a `z' in its name.
-
- Alternatively, the problem might be due to the fact that the file
-starts with exactly 25 spaces. For this reason, you should make sure
-that you inform us of the exact contents of any file that is needed to
-reproduce the bug. What if the problem only occurs when you have typed
-the `C-x a l' command previously? This is why we ask you to give the
-exact sequence of characters you typed since starting to use Emacs.
-
- You should not even say "visit a file" instead of `C-x C-f' unless
-you know that it makes no difference which visiting command is used.
-Similarly, rather than saying "if I have three characters on the line,"
-say "after I type `<RET> A B C <RET> C-p'," if that is the way you
-entered the text.
-
- If you are not in Fundamental mode when the problem occurs, you
-should say what mode you are in.
-
- If the manifestation of the bug is an Emacs error message, it is
-important to report not just the text of the error message but a
-backtrace showing how the Lisp program in Emacs arrived at the error.
-To make the backtrace, you must execute the Lisp expression `(setq
-debug-on-error t)' before the error happens (that is to say, you must
-execute that expression and then make the bug happen). This causes the
-Lisp debugger to run (*note Lisp Debug::). The debugger's backtrace
-can be copied as text into the bug report. This use of the debugger is
-possible only if you know how to make the bug happen again. Do note
-the error message the first time the bug happens, so if you can't make
-it happen again, you can report at least that.
-
- Check whether any programs you have loaded into the Lisp world,
-including your init file, set any variables that may affect the
-functioning of Emacs. *Note Init File::. Also, see whether the
-problem happens in a freshly started Emacs without loading your init
-file (start Emacs with the `-q' switch to prevent loading the init
-file). If the problem does NOT occur then, it is essential that we
-know the contents of any programs that you must load into the Lisp
-world in order to cause the problem to occur.
-
- If the problem does depend on an init file or other Lisp programs
-that are not part of the standard Emacs system, then you should make
-sure it is not a bug in those programs by complaining to their
-maintainers first. After they verify that they are using Emacs in a
-way that is supposed to work, they should report the bug.
-
- If you can tell us a way to cause the problem without visiting any
-files, please do so. This makes it much easier to debug. If you do
-need files, make sure you arrange for us to see their exact contents.
-For example, it can often matter whether there are spaces at the ends
-of lines, or a newline after the last line in the buffer (nothing ought
-to care whether the last line is terminated, but tell that to the bugs).
-
- The easy way to record the input to Emacs precisely is to write a
-dribble file; execute the Lisp expression:
-
- (open-dribble-file "~/dribble")
-
-using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
-Emacs. From then on, all Emacs input will be written in the specified
-dribble file until the Emacs process is killed.
-
- For possible display bugs, it is important to report the terminal
-type (the value of environment variable `TERM'), the complete termcap
-entry for the terminal from `/etc/termcap' (since that file is not
-identical on all machines), and the output that Emacs actually sent to
-the terminal. The way to collect this output is to execute the Lisp
-expression:
-
- (open-termscript "~/termscript")
-
-using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
-Emacs. From then on, all output from Emacs to the terminal will be
-written in the specified termscript file as well, until the Emacs
-process is killed. If the problem happens when Emacs starts up, put
-this expression into your init file so that the termscript file will be
-open when Emacs displays the screen for the first time. *Note Init
-File::. Be warned: it is often difficult, and sometimes impossible, to
-fix a terminal-dependent bug without access to a terminal of the type
-that stimulates the bug.
-
- The newsgroup `comp.emacs.xemacs' may be used for bug reports, other
-discussions and requests for assistance.
-
- If you don't have access to this newgroup, you can subscribe to the
-mailing list version: the newsgroup is bidirectionally gatewayed into
-the mailing list `xemacs@xemacs.org'.
-
- To be added or removed from this mailing list, send mail to
-`xemacs-request@xemacs.org'. Do not send requests for addition to the
-mailing list itself.
-
- The mailing lists and newsgroups are archived on our anonymous FTP
-server, `ftp.xemacs.org', and at various other archive sites around the
-net. You should also check the `FAQ' in `/pub/xemacs' on our anonymous
-FTP server. It provides some introductory information and help for
-initial configuration problems.
-
projects / chise / xemacs-chise.git / blobdiff