Mercurial > emacs
annotate man/trouble.texi @ 37347:bd817d6f9ba3
Minor clarifications regarding DEL key.
Mention toggle-debug-on-error.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Sat, 14 Apr 2001 14:48:01 +0000 |
parents | 6a2d75e45a87 |
children | ad563f9185fb |
rev | line source |
---|---|
25829 | 1 @c This is part of the Emacs manual. |
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. | |
3 @c See file emacs.texi for copying conditions. | |
4 @iftex | |
5 @chapter Dealing with Common Problems | |
6 | |
7 If you type an Emacs command you did not intend, the results are often | |
8 mysterious. This chapter tells what you can do to cancel your mistake or | |
9 recover from a mysterious situation. Emacs bugs and system crashes are | |
10 also considered. | |
11 @end iftex | |
12 | |
13 @node Quitting, Lossage, Customization, Top | |
14 @section Quitting and Aborting | |
15 @cindex quitting | |
16 | |
17 @table @kbd | |
18 @item C-g | |
36180
252e21b04fb1
Suggest copying problematical manual text into the bug report.
Richard M. Stallman <rms@gnu.org>
parents:
35874
diff
changeset
|
19 @itemx C-@key{BREAK} @r{(MS-DOS only)} |
252e21b04fb1
Suggest copying problematical manual text into the bug report.
Richard M. Stallman <rms@gnu.org>
parents:
35874
diff
changeset
|
20 Quit: cancel running or partially typed command. |
25829 | 21 @item C-] |
22 Abort innermost recursive editing level and cancel the command which | |
23 invoked it (@code{abort-recursive-edit}). | |
24 @item @key{ESC} @key{ESC} @key{ESC} | |
25 Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}). | |
26 @item M-x top-level | |
27 Abort all recursive editing levels that are currently executing. | |
28 @item C-x u | |
29 Cancel a previously made change in the buffer contents (@code{undo}). | |
30 @end table | |
31 | |
32 There are two ways of canceling commands which are not finished | |
33 executing: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with | |
34 @kbd{C-]} or @kbd{M-x top-level}. Quitting cancels a partially typed | |
35 command or one which is already running. Aborting exits a recursive | |
36 editing level and cancels the command that invoked the recursive edit. | |
37 (@xref{Recursive Edit}.) | |
38 | |
39 @cindex quitting | |
40 @kindex C-g | |
41 Quitting with @kbd{C-g} is used for getting rid of a partially typed | |
42 command, or a numeric argument that you don't want. It also stops a | |
43 running command in the middle in a relatively safe way, so you can use | |
44 it if you accidentally give a command which takes a long time. In | |
45 particular, it is safe to quit out of killing; either your text will | |
46 @emph{all} still be in the buffer, or it will @emph{all} be in the kill | |
47 ring (or maybe both). Quitting an incremental search does special | |
48 things documented under searching; in general, it may take two | |
49 successive @kbd{C-g} characters to get out of a search | |
50 (@pxref{Incremental Search}). | |
51 | |
52 On MS-DOS, the character @kbd{C-@key{BREAK}} serves as a quit character | |
53 like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to | |
54 recognize @kbd{C-g} while a command is running, between interactions | |
55 with the user. By contrast, it @emph{is} feasible to recognize | |
56 @kbd{C-@key{BREAK}} at all times. @xref{MS-DOS Input}. | |
57 | |
36180
252e21b04fb1
Suggest copying problematical manual text into the bug report.
Richard M. Stallman <rms@gnu.org>
parents:
35874
diff
changeset
|
58 @findex keyboard-quit |
25829 | 59 @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t} |
60 the instant @kbd{C-g} is typed; Emacs Lisp checks this variable | |
61 frequently and quits if it is non-@code{nil}. @kbd{C-g} is only | |
62 actually executed as a command if you type it while Emacs is waiting for | |
36180
252e21b04fb1
Suggest copying problematical manual text into the bug report.
Richard M. Stallman <rms@gnu.org>
parents:
35874
diff
changeset
|
63 input. In that case, the command it runs is @code{keyboard-quit}. |
25829 | 64 |
65 If you quit with @kbd{C-g} a second time before the first @kbd{C-g} is | |
66 recognized, you activate the ``emergency escape'' feature and return to | |
67 the shell. @xref{Emergency Escape}. | |
68 | |
69 @cindex NFS and quitting | |
70 There may be times when you cannot quit. When Emacs is waiting for | |
71 the operating system to do something, quitting is impossible unless | |
72 special pains are taken for the particular system call within Emacs | |
73 where the waiting occurs. We have done this for the system calls that | |
74 users are likely to want to quit from, but it's possible you will find | |
75 another. In one very common case---waiting for file input or output | |
76 using NFS---Emacs itself knows how to quit, but most NFS implementations | |
77 simply do not allow user programs to stop waiting for NFS when the NFS | |
78 server is hung. | |
79 | |
80 @cindex aborting recursive edit | |
81 @findex abort-recursive-edit | |
82 @kindex C-] | |
83 Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get | |
84 out of a recursive editing level and cancel the command which invoked | |
85 it. Quitting with @kbd{C-g} does not do this, and could not do this, | |
86 because it is used to cancel a partially typed command @emph{within} the | |
87 recursive editing level. Both operations are useful. For example, if | |
88 you are in a recursive edit and type @kbd{C-u 8} to enter a numeric | |
89 argument, you can cancel that argument with @kbd{C-g} and remain in the | |
90 recursive edit. | |
91 | |
92 @findex keyboard-escape-quit | |
93 @kindex ESC ESC ESC | |
94 The command @kbd{@key{ESC} @key{ESC} @key{ESC}} | |
95 (@code{keyboard-escape-quit}) can either quit or abort. This key was | |
96 defined because @key{ESC} is used to ``get out'' in many PC programs. | |
97 It can cancel a prefix argument, clear a selected region, or get out of | |
98 a Query Replace, like @kbd{C-g}. It can get out of the minibuffer or a | |
99 recursive edit, like @kbd{C-]}. It can also get out of splitting the | |
100 frame into multiple windows, like @kbd{C-x 1}. One thing it cannot do, | |
101 however, is stop a command that is running. That's because it executes | |
102 as an ordinary command, and Emacs doesn't notice it until it is ready | |
103 for a command. | |
104 | |
105 @findex top-level | |
106 The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]} | |
107 commands to get you out of all the levels of recursive edits that you | |
108 are in. @kbd{C-]} gets you out one level at a time, but @kbd{M-x | |
109 top-level} goes out all levels at once. Both @kbd{C-]} and @kbd{M-x | |
110 top-level} are like all other commands, and unlike @kbd{C-g}, in that | |
111 they take effect only when Emacs is ready for a command. @kbd{C-]} is | |
112 an ordinary key and has its meaning only because of its binding in the | |
113 keymap. @xref{Recursive Edit}. | |
114 | |
115 @kbd{C-x u} (@code{undo}) is not strictly speaking a way of canceling | |
116 a command, but you can think of it as canceling a command that already | |
117 finished executing. @xref{Undo}. | |
118 | |
119 @node Lossage, Bugs, Quitting, Top | |
120 @section Dealing with Emacs Trouble | |
121 | |
122 This section describes various conditions in which Emacs fails to work | |
123 normally, and how to recognize them and correct them. | |
124 | |
125 @menu | |
126 * DEL Gets Help:: What to do if @key{DEL} doesn't delete. | |
127 * Stuck Recursive:: `[...]' in mode line around the parentheses. | |
128 * Screen Garbled:: Garbage on the screen. | |
129 * Text Garbled:: Garbage in the text. | |
130 * Unasked-for Search:: Spontaneous entry to incremental search. | |
131 * Memory Full:: How to cope when you run out of memory. | |
132 * After a Crash:: Recovering editing in an Emacs session that crashed. | |
133 * Emergency Escape:: Emergency escape--- | |
134 What to do if Emacs stops responding. | |
135 * Total Frustration:: When you are at your wits' end. | |
136 @end menu | |
137 | |
138 @node DEL Gets Help | |
139 @subsection If @key{DEL} Fails to Delete | |
36791
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
140 @cindex @key{DEL} vs @key{BACKSPACE} |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
141 @cindex @key{BACKSPACE} vs @key{DEL} |
37126
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
142 @cindex usual erasure key |
25829 | 143 |
37126
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
144 Every keyboard has a large key, a little ways above the @key{RET} or |
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
145 @key{ENTER} key, which you normally use outside Emacs to erase the |
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
146 last character that you typed. We call this key @dfn{the usual |
37347
bd817d6f9ba3
Minor clarifications regarding DEL key.
Richard M. Stallman <rms@gnu.org>
parents:
37126
diff
changeset
|
147 erasure key}. In Emacs, it is supposed to be equivalent to @key{DEL}, |
bd817d6f9ba3
Minor clarifications regarding DEL key.
Richard M. Stallman <rms@gnu.org>
parents:
37126
diff
changeset
|
148 and when Emacs is properly configured for your terminal, it translates |
bd817d6f9ba3
Minor clarifications regarding DEL key.
Richard M. Stallman <rms@gnu.org>
parents:
37126
diff
changeset
|
149 that key into the character @key{DEL}. |
36791
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
150 |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
151 When Emacs starts up using a window system, it determines |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
152 automatically which key should be @key{DEL}. In some unusual cases |
37126
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
153 Emacs gets the wrong information from the system. If the usual |
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
154 erasure key deletes forwards instead of backwards, that is probably |
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
155 what happened---Emacs ought to be treating the @key{DELETE} key as |
36791
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
156 @key{DEL}, but it isn't. |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
157 |
37126
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
158 With a window system, if the usual erasure key is labeled |
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
159 @key{BACKSPACE} and there is a @key{DELETE} key elsewhere, but the |
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
160 @key{DELETE} key deletes backward instead of forward, that too |
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
161 suggests Emacs got the wrong information---but in the opposite sense. |
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
162 It ought to be treating the @key{BACKSPACE} key as @key{DEL}, but it |
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
163 isn't. |
36791
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
164 |
37126
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
165 On a text-only terminal, if you find the usual erasure key prompts |
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
166 for a Help command, like @kbd{Control-h}, instead of deleting a |
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
167 character, it means that key is actually sending the @key{BS} |
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
168 character. Emacs ought to be treating @key{BS} as @key{DEL}, but it |
6a2d75e45a87
Add concept of "usual erasure key" to explain about DEL.
Richard M. Stallman <rms@gnu.org>
parents:
37119
diff
changeset
|
169 isn't. |
36791
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
170 |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
171 In all of those cases, the immediate remedy is the same: use the |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
172 command @kbd{M-x normal-erase-is-backspace-mode}. That should make |
37347
bd817d6f9ba3
Minor clarifications regarding DEL key.
Richard M. Stallman <rms@gnu.org>
parents:
37126
diff
changeset
|
173 the proper key work as @key{DEL}. On a text-only terminal, if you do |
36791
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
174 want to ask for help, use @key{F1} or @kbd{C-?}. |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
175 |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
176 @findex normal-erase-is-backspace-mode |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
177 To fix the problem automatically for every Emacs session, you can |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
178 put one of the following lines into your @file{.emacs} file |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
179 (@pxref{Init File}). For the first case above, where @key{DEL} |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
180 deletes forwards instead of backwards, use this line: |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
181 |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
182 @lisp |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
183 (normal-erase-is-backspace-mode 0) |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
184 @end lisp |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
185 |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
186 @noindent |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
187 For the other two cases, use this line: |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
188 |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
189 @lisp |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
190 (normal-erase-is-backspace-mode 1) |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
191 @end lisp |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
192 |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
193 @vindex normal-erase-is-backspace |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
194 Another way to fix the problem for every Emacs session is to |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
195 customize the variable @code{normal-erase-is-backspace}: the value |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
196 @code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
197 @key{DEL}, and @code{nil} specifies the other mode. @xref{Easy |
308577404dc3
DEL Gets Help: Complete rewrite to deal with automatic
Richard M. Stallman <rms@gnu.org>
parents:
36620
diff
changeset
|
198 Customization}. |
25829 | 199 |
200 @node Stuck Recursive | |
201 @subsection Recursive Editing Levels | |
202 | |
203 Recursive editing levels are important and useful features of Emacs, but | |
204 they can seem like malfunctions to the user who does not understand them. | |
205 | |
206 If the mode line has square brackets @samp{[@dots{}]} around the parentheses | |
207 that contain the names of the major and minor modes, you have entered a | |
208 recursive editing level. If you did not do this on purpose, or if you | |
209 don't understand what that means, you should just get out of the recursive | |
210 editing level. To do so, type @kbd{M-x top-level}. This is called getting | |
211 back to top level. @xref{Recursive Edit}. | |
212 | |
213 @node Screen Garbled | |
214 @subsection Garbage on the Screen | |
215 | |
216 If the data on the screen looks wrong, the first thing to do is see | |
36294
4f794fec4857
(Screen Garbled): Remove a comma.
Gerd Moellmann <gerd@gnu.org>
parents:
36180
diff
changeset
|
217 whether the text is really wrong. Type @kbd{C-l} to redisplay the |
25829 | 218 entire screen. If the screen appears correct after this, the problem |
219 was entirely in the previous screen update. (Otherwise, see @ref{Text | |
220 Garbled}.) | |
221 | |
222 Display updating problems often result from an incorrect termcap entry | |
223 for the terminal you are using. The file @file{etc/TERMS} in the Emacs | |
224 distribution gives the fixes for known problems of this sort. | |
225 @file{INSTALL} contains general advice for these problems in one of its | |
226 sections. Very likely there is simply insufficient padding for certain | |
227 display operations. To investigate the possibility that you have this sort | |
228 of problem, try Emacs on another terminal made by a different manufacturer. | |
229 If problems happen frequently on one kind of terminal but not another kind, | |
230 it is likely to be a bad termcap entry, though it could also be due to a | |
231 bug in Emacs that appears for terminals that have or that lack specific | |
232 features. | |
233 | |
234 @node Text Garbled | |
235 @subsection Garbage in the Text | |
236 | |
237 If @kbd{C-l} shows that the text is wrong, try undoing the changes to it | |
238 using @kbd{C-x u} until it gets back to a state you consider correct. Also | |
239 try @kbd{C-h l} to find out what command you typed to produce the observed | |
240 results. | |
241 | |
242 If a large portion of text appears to be missing at the beginning or | |
243 end of the buffer, check for the word @samp{Narrow} in the mode line. | |
244 If it appears, the text you don't see is probably still present, but | |
245 temporarily off-limits. To make it accessible again, type @kbd{C-x n | |
246 w}. @xref{Narrowing}. | |
247 | |
248 @node Unasked-for Search | |
249 @subsection Spontaneous Entry to Incremental Search | |
250 | |
251 If Emacs spontaneously displays @samp{I-search:} at the bottom of the | |
252 screen, it means that the terminal is sending @kbd{C-s} and @kbd{C-q} | |
253 according to the poorly designed xon/xoff ``flow control'' protocol. | |
254 | |
255 If this happens to you, your best recourse is to put the terminal in a | |
256 mode where it will not use flow control, or give it so much padding that | |
257 it will never send a @kbd{C-s}. (One way to increase the amount of | |
258 padding is to set the variable @code{baud-rate} to a larger value. Its | |
259 value is the terminal output speed, measured in the conventional units | |
260 of baud.) | |
261 | |
262 @cindex flow control | |
263 @cindex xon-xoff | |
264 @findex enable-flow-control | |
265 If you don't succeed in turning off flow control, the next best thing | |
266 is to tell Emacs to cope with it. To do this, call the function | |
267 @code{enable-flow-control}. | |
268 | |
269 @findex enable-flow-control-on | |
270 Typically there are particular terminal types with which you must use | |
271 flow control. You can conveniently ask for flow control on those | |
272 terminal types only, using @code{enable-flow-control-on}. For example, | |
273 if you find you must use flow control on VT-100 and H19 terminals, put | |
274 the following in your @file{.emacs} file: | |
275 | |
276 @example | |
277 (enable-flow-control-on "vt100" "h19") | |
278 @end example | |
279 | |
280 When flow control is enabled, you must type @kbd{C-\} to get the | |
281 effect of a @kbd{C-s}, and type @kbd{C-^} to get the effect of a | |
282 @kbd{C-q}. (These aliases work by means of keyboard translations; see | |
283 @ref{Keyboard Translations}.) | |
284 | |
285 @node Memory Full | |
286 @subsection Running out of Memory | |
287 @cindex memory full | |
288 @cindex out of memory | |
289 | |
290 If you get the error message @samp{Virtual memory exceeded}, save your | |
291 modified buffers with @kbd{C-x s}. This method of saving them has the | |
292 smallest need for additional memory. Emacs keeps a reserve of memory | |
293 which it makes available when this error happens; that should be enough | |
294 to enable @kbd{C-x s} to complete its work. | |
295 | |
296 Once you have saved your modified buffers, you can exit this Emacs job | |
297 and start another, or you can use @kbd{M-x kill-some-buffers} to free | |
298 space in the current Emacs job. If you kill buffers containing a | |
299 substantial amount of text, you can safely go on editing. Emacs refills | |
300 its memory reserve automatically when it sees sufficient free space | |
301 available, in case you run out of memory another time. | |
302 | |
303 Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run | |
304 out of memory, because the buffer menu needs a fair amount memory | |
305 itself, and the reserve supply may not be enough. | |
306 | |
307 @node After a Crash | |
308 @subsection Recovery After a Crash | |
309 | |
310 If Emacs or the computer crashes, you can recover the files you were | |
311 editing at the time of the crash from their auto-save files. To do | |
312 this, start Emacs again and type the command @kbd{M-x recover-session}. | |
313 | |
314 This command initially displays a buffer which lists interrupted | |
315 session files, each with its date. You must choose which session to | |
316 recover from. Typically the one you want is the most recent one. Move | |
317 point to the one you choose, and type @kbd{C-c C-c}. | |
318 | |
319 Then @code{recover-session} asks about each of the files that you were | |
320 editing during that session; it asks whether to recover that file. If | |
321 you answer @kbd{y} for a file, it shows the dates of that file and its | |
322 auto-save file, then asks once again whether to recover that file. For | |
323 the second question, you must confirm with @kbd{yes}. If you do, Emacs | |
324 visits the file but gets the text from the auto-save file. | |
325 | |
326 When @code{recover-session} is done, the files you've chosen to | |
327 recover are present in Emacs buffers. You should then save them. Only | |
328 this---saving them---updates the files themselves. | |
329 | |
330 @node Emergency Escape | |
331 @subsection Emergency Escape | |
332 | |
333 Because at times there have been bugs causing Emacs to loop without | |
334 checking @code{quit-flag}, a special feature causes Emacs to be suspended | |
335 immediately if you type a second @kbd{C-g} while the flag is already set, | |
336 so you can always get out of GNU Emacs. Normally Emacs recognizes and | |
337 clears @code{quit-flag} (and quits!) quickly enough to prevent this from | |
338 happening. (On MS-DOS and compatible systems, type @kbd{C-@key{BREAK}} | |
339 twice.) | |
340 | |
341 When you resume Emacs after a suspension caused by multiple @kbd{C-g}, it | |
342 asks two questions before going back to what it had been doing: | |
343 | |
344 @example | |
345 Auto-save? (y or n) | |
346 Abort (and dump core)? (y or n) | |
347 @end example | |
348 | |
349 @noindent | |
350 Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}. | |
351 | |
352 Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of all | |
353 modified buffers in which auto-saving is enabled. | |
354 | |
355 Saying @kbd{y} to @samp{Abort (and dump core)?} causes an illegal instruction to be | |
356 executed, dumping core. This is to enable a wizard to figure out why Emacs | |
357 was failing to quit in the first place. Execution does not continue | |
358 after a core dump. If you answer @kbd{n}, execution does continue. With | |
359 luck, GNU Emacs will ultimately check @code{quit-flag} and quit normally. | |
360 If not, and you type another @kbd{C-g}, it is suspended again. | |
361 | |
362 If Emacs is not really hung, just slow, you may invoke the double | |
363 @kbd{C-g} feature without really meaning to. Then just resume and answer | |
364 @kbd{n} to both questions, and you will arrive at your former state. | |
365 Presumably the quit you requested will happen soon. | |
366 | |
367 The double-@kbd{C-g} feature is turned off when Emacs is running under | |
368 the X Window System, since you can use the window manager to kill Emacs | |
369 or to create another window and run another program. | |
370 | |
371 On MS-DOS and compatible systems, the emergency escape feature is | |
372 sometimes unavailable, even if you press @kbd{C-@key{BREAK}} twice, when | |
373 some system call (MS-DOS or BIOS) hangs, or when Emacs is stuck in a | |
374 very tight endless loop (in C code, @strong{not} in Lisp code). | |
375 | |
376 @node Total Frustration | |
377 @subsection Help for Total Frustration | |
378 @cindex Eliza | |
379 @cindex doctor | |
380 | |
381 If using Emacs (or something else) becomes terribly frustrating and none | |
382 of the techniques described above solve the problem, Emacs can still help | |
383 you. | |
384 | |
385 First, if the Emacs you are using is not responding to commands, type | |
386 @kbd{C-g C-g} to get out of it and then start a new one. | |
387 | |
388 @findex doctor | |
389 Second, type @kbd{M-x doctor @key{RET}}. | |
390 | |
391 The doctor will help you feel better. Each time you say something to | |
392 the doctor, you must end it by typing @key{RET} @key{RET}. This lets | |
393 the doctor know you are finished. | |
394 | |
395 @node Bugs, Contributing, Lossage, Top | |
396 @section Reporting Bugs | |
397 | |
398 @cindex bugs | |
399 Sometimes you will encounter a bug in Emacs. Although we cannot | |
400 promise we can or will fix the bug, and we might not even agree that it | |
401 is a bug, we want to hear about problems you encounter. Often we agree | |
402 they are bugs and want to fix them. | |
403 | |
404 To make it possible for us to fix a bug, you must report it. In order | |
405 to do so effectively, you must know when and how to do it. | |
406 | |
407 @menu | |
408 * Criteria: Bug Criteria. Have you really found a bug? | |
409 * Understanding Bug Reporting:: How to report a bug effectively. | |
410 * Checklist:: Steps to follow for a good bug report. | |
411 * Sending Patches:: How to send a patch for GNU Emacs. | |
412 @end menu | |
413 | |
414 @node Bug Criteria | |
415 @subsection When Is There a Bug | |
416 | |
417 If Emacs executes an illegal instruction, or dies with an operating | |
418 system error message that indicates a problem in the program (as opposed to | |
419 something like ``disk full''), then it is certainly a bug. | |
420 | |
421 If Emacs updates the display in a way that does not correspond to what is | |
422 in the buffer, then it is certainly a bug. If a command seems to do the | |
423 wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a | |
424 case of incorrect display updating. | |
425 | |
426 Taking forever to complete a command can be a bug, but you must make | |
427 certain that it was really Emacs's fault. Some commands simply take a | |
428 long time. Type @kbd{C-g} (@kbd{C-@key{BREAK}} on MS-DOS) and then @kbd{C-h l} | |
429 to see whether the input Emacs received was what you intended to type; | |
430 if the input was such that you @emph{know} it should have been processed | |
431 quickly, report a bug. If you don't know whether the command should | |
432 take a long time, find out by looking in the manual or by asking for | |
433 assistance. | |
434 | |
435 If a command you are familiar with causes an Emacs error message in a | |
436 case where its usual definition ought to be reasonable, it is probably a | |
437 bug. | |
438 | |
439 If a command does the wrong thing, that is a bug. But be sure you know | |
440 for certain what it ought to have done. If you aren't familiar with the | |
441 command, or don't know for certain how the command is supposed to work, | |
442 then it might actually be working right. Rather than jumping to | |
443 conclusions, show the problem to someone who knows for certain. | |
444 | |
36388
5835d43dcf93
(Bug Criteria): Reword a sentence.
Gerd Moellmann <gerd@gnu.org>
parents:
36294
diff
changeset
|
445 Finally, a command's intended definition may not be the best |
5835d43dcf93
(Bug Criteria): Reword a sentence.
Gerd Moellmann <gerd@gnu.org>
parents:
36294
diff
changeset
|
446 possible definition for editing with. This is a very important sort |
5835d43dcf93
(Bug Criteria): Reword a sentence.
Gerd Moellmann <gerd@gnu.org>
parents:
36294
diff
changeset
|
447 of problem, but it is also a matter of judgment. Also, it is easy to |
5835d43dcf93
(Bug Criteria): Reword a sentence.
Gerd Moellmann <gerd@gnu.org>
parents:
36294
diff
changeset
|
448 come to such a conclusion out of ignorance of some of the existing |
5835d43dcf93
(Bug Criteria): Reword a sentence.
Gerd Moellmann <gerd@gnu.org>
parents:
36294
diff
changeset
|
449 features. It is probably best not to complain about such a problem |
5835d43dcf93
(Bug Criteria): Reword a sentence.
Gerd Moellmann <gerd@gnu.org>
parents:
36294
diff
changeset
|
450 until you have checked the documentation in the usual ways, feel |
5835d43dcf93
(Bug Criteria): Reword a sentence.
Gerd Moellmann <gerd@gnu.org>
parents:
36294
diff
changeset
|
451 confident that you understand it, and know for certain that what you |
5835d43dcf93
(Bug Criteria): Reword a sentence.
Gerd Moellmann <gerd@gnu.org>
parents:
36294
diff
changeset
|
452 want is not available. If you are not sure what the command is |
5835d43dcf93
(Bug Criteria): Reword a sentence.
Gerd Moellmann <gerd@gnu.org>
parents:
36294
diff
changeset
|
453 supposed to do after a careful reading of the manual, check the index |
5835d43dcf93
(Bug Criteria): Reword a sentence.
Gerd Moellmann <gerd@gnu.org>
parents:
36294
diff
changeset
|
454 and glossary for any terms that may be unclear. |
25829 | 455 |
456 If after careful rereading of the manual you still do not understand | |
457 what the command should do, that indicates a bug in the manual, which | |
458 you should report. The manual's job is to make everything clear to | |
459 people who are not Emacs experts---including you. It is just as | |
460 important to report documentation bugs as program bugs. | |
461 | |
462 If the on-line documentation string of a function or variable disagrees | |
463 with the manual, one of them must be wrong; that is a bug. | |
464 | |
465 @node Understanding Bug Reporting | |
466 @subsection Understanding Bug Reporting | |
467 | |
468 @findex emacs-version | |
469 When you decide that there is a bug, it is important to report it and to | |
470 report it in a way which is useful. What is most useful is an exact | |
471 description of what commands you type, starting with the shell command to | |
472 run Emacs, until the problem happens. | |
473 | |
474 The most important principle in reporting a bug is to report | |
475 @emph{facts}. Hypotheses and verbal descriptions are no substitute for | |
476 the detailed raw data. Reporting the facts is straightforward, but many | |
477 people strain to posit explanations and report them instead of the | |
478 facts. If the explanations are based on guesses about how Emacs is | |
479 implemented, they will be useless; meanwhile, lacking the facts, we will | |
480 have no real information about the bug. | |
481 | |
482 For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh | |
483 @key{RET}}, visiting a file which (you know) happens to be rather large, | |
484 and Emacs displayed @samp{I feel pretty today}. The best way to report | |
485 the bug is with a sentence like the preceding one, because it gives all | |
486 the facts. | |
487 | |
488 A bad way would be to assume that the problem is due to the size of | |
489 the file and say, ``I visited a large file, and Emacs displayed @samp{I | |
490 feel pretty today}.'' This is what we mean by ``guessing | |
491 explanations.'' The problem is just as likely to be due to the fact | |
492 that there is a @samp{z} in the file name. If this is so, then when we | |
493 got your report, we would try out the problem with some ``large file,'' | |
494 probably with no @samp{z} in its name, and not see any problem. There | |
495 is no way in the world that we could guess that we should try visiting a | |
496 file with a @samp{z} in its name. | |
497 | |
498 Alternatively, the problem might be due to the fact that the file starts | |
499 with exactly 25 spaces. For this reason, you should make sure that you | |
500 inform us of the exact contents of any file that is needed to reproduce the | |
501 bug. What if the problem only occurs when you have typed the @kbd{C-x C-a} | |
502 command previously? This is why we ask you to give the exact sequence of | |
503 characters you typed since starting the Emacs session. | |
504 | |
505 You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless | |
506 you @emph{know} that it makes no difference which visiting command is used. | |
507 Similarly, rather than saying ``if I have three characters on the line,'' | |
508 say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is | |
509 the way you entered the text.@refill | |
510 | |
511 So please don't guess any explanations when you report a bug. If you | |
512 want to actually @emph{debug} the problem, and report explanations that | |
513 are more than guesses, that is useful---but please include the facts as | |
514 well. | |
515 | |
516 @node Checklist | |
517 @subsection Checklist for Bug Reports | |
518 | |
519 @cindex reporting bugs | |
520 The best way to send a bug report is to mail it electronically to the | |
36180
252e21b04fb1
Suggest copying problematical manual text into the bug report.
Richard M. Stallman <rms@gnu.org>
parents:
35874
diff
changeset
|
521 Emacs maintainers at @email{bug-gnu-emacs@@gnu.org}, or to |
252e21b04fb1
Suggest copying problematical manual text into the bug report.
Richard M. Stallman <rms@gnu.org>
parents:
35874
diff
changeset
|
522 @email{emacs-pretest-bug@@gnu.org} if you are pretesting an Emacs beta |
26021
4f5e4ec69f6a
Add emacs-prestest-bug@gnu.org analogous to bug-gnu-emacs@gnu.org.
Gerd Moellmann <gerd@gnu.org>
parents:
25829
diff
changeset
|
523 release. (If you want to suggest a change as an improvement, use the |
4f5e4ec69f6a
Add emacs-prestest-bug@gnu.org analogous to bug-gnu-emacs@gnu.org.
Gerd Moellmann <gerd@gnu.org>
parents:
25829
diff
changeset
|
524 same address.) |
25829 | 525 |
526 If you'd like to read the bug reports, you can find them on the | |
527 newsgroup @samp{gnu.emacs.bug}; keep in mind, however, that as a | |
528 spectator you should not criticize anything about what you see there. | |
529 The purpose of bug reports is to give information to the Emacs | |
530 maintainers. Spectators are welcome only as long as they do not | |
531 interfere with this. In particular, some bug reports contain large | |
532 amounts of data; spectators should not complain about this. | |
533 | |
534 Please do not post bug reports using netnews; mail is more reliable | |
535 than netnews about reporting your correct address, which we may need in | |
536 order to ask you for more information. | |
537 | |
538 If you can't send electronic mail, then mail the bug report on paper | |
539 or machine-readable media to this address: | |
540 | |
541 @format | |
542 GNU Emacs Bugs | |
543 Free Software Foundation | |
544 59 Temple Place, Suite 330 | |
545 Boston, MA 02111-1307 USA | |
546 @end format | |
547 | |
548 We do not promise to fix the bug; but if the bug is serious, | |
549 or ugly, or easy to fix, chances are we will want to. | |
550 | |
551 @findex report-emacs-bug | |
552 A convenient way to send a bug report for Emacs is to use the command | |
553 @kbd{M-x report-emacs-bug}. This sets up a mail buffer (@pxref{Sending | |
554 Mail}) and automatically inserts @emph{some} of the essential | |
555 information. However, it cannot supply all the necessary information; | |
556 you should still read and follow the guidelines below, so you can enter | |
557 the other crucial information by hand before you send the message. | |
558 | |
559 To enable maintainers to investigate a bug, your report | |
560 should include all these things: | |
561 | |
562 @itemize @bullet | |
563 @item | |
564 The version number of Emacs. Without this, we won't know whether there | |
565 is any point in looking for the bug in the current version of GNU | |
566 Emacs. | |
567 | |
568 You can get the version number by typing @kbd{M-x emacs-version | |
569 @key{RET}}. If that command does not work, you probably have something | |
570 other than GNU Emacs, so you will have to report the bug somewhere | |
571 else. | |
572 | |
573 @item | |
574 The type of machine you are using, and the operating system name and | |
575 version number. @kbd{M-x emacs-version @key{RET}} provides this | |
576 information too. Copy its output from the @samp{*Messages*} buffer, so | |
577 that you get it all and get it accurately. | |
578 | |
579 @item | |
580 The operands given to the @code{configure} command when Emacs was | |
581 installed. | |
582 | |
583 @item | |
584 A complete list of any modifications you have made to the Emacs source. | |
585 (We may not have time to investigate the bug unless it happens in an | |
586 unmodified Emacs. But if you've made modifications and you don't tell | |
587 us, you are sending us on a wild goose chase.) | |
588 | |
589 Be precise about these changes. A description in English is not | |
590 enough---send a context diff for them. | |
591 | |
592 Adding files of your own, or porting to another machine, is a | |
593 modification of the source. | |
594 | |
595 @item | |
596 Details of any other deviations from the standard procedure for installing | |
597 GNU Emacs. | |
598 | |
599 @item | |
600 The complete text of any files needed to reproduce the bug. | |
601 | |
602 If you can tell us a way to cause the problem without visiting any files, | |
603 please do so. This makes it much easier to debug. If you do need files, | |
604 make sure you arrange for us to see their exact contents. For example, it | |
605 can often matter whether there are spaces at the ends of lines, or a | |
606 newline after the last line in the buffer (nothing ought to care whether | |
607 the last line is terminated, but try telling the bugs that). | |
608 | |
609 @item | |
610 The precise commands we need to type to reproduce the bug. | |
611 | |
612 @findex open-dribble-file | |
613 @cindex dribble file | |
35705
6c05ec832ecc
(Checklist): Add index entry for logging keystrokes.
Eli Zaretskii <eliz@gnu.org>
parents:
35239
diff
changeset
|
614 @cindex logging keystrokes |
25829 | 615 The easy way to record the input to Emacs precisely is to write a |
616 dribble file. To start the file, execute the Lisp expression | |
617 | |
618 @example | |
619 (open-dribble-file "~/dribble") | |
620 @end example | |
621 | |
622 @noindent | |
623 using @kbd{M-:} or from the @samp{*scratch*} buffer just after | |
624 starting Emacs. From then on, Emacs copies all your input to the | |
625 specified dribble file until the Emacs process is killed. | |
626 | |
627 @item | |
628 @findex open-termscript | |
629 @cindex termscript file | |
29107 | 630 @cindex @env{TERM} environment variable |
25829 | 631 For possible display bugs, the terminal type (the value of environment |
29107 | 632 variable @env{TERM}), the complete termcap entry for the terminal from |
25829 | 633 @file{/etc/termcap} (since that file is not identical on all machines), |
634 and the output that Emacs actually sent to the terminal. | |
635 | |
636 The way to collect the terminal output is to execute the Lisp expression | |
637 | |
638 @example | |
639 (open-termscript "~/termscript") | |
640 @end example | |
641 | |
642 @noindent | |
643 using @kbd{M-:} or from the @samp{*scratch*} buffer just after | |
644 starting Emacs. From then on, Emacs copies all terminal output to the | |
645 specified termscript file as well, until the Emacs process is killed. | |
646 If the problem happens when Emacs starts up, put this expression into | |
647 your @file{.emacs} file so that the termscript file will be open when | |
648 Emacs displays the screen for the first time. | |
649 | |
650 Be warned: it is often difficult, and sometimes impossible, to fix a | |
651 terminal-dependent bug without access to a terminal of the type that | |
652 stimulates the bug.@refill | |
653 | |
654 @item | |
35239
a4e73c75cbca
Ask for locale info in bug reports.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
655 If non-ASCII text or internationalization is relevant, the locale that |
36497
1ba3f8033b3a
(Checklist): Say that the example with LC_ALL and such is for a Unix shell.
Eli Zaretskii <eliz@gnu.org>
parents:
36388
diff
changeset
|
656 was current when you started Emacs. On GNU/Linux and Unix systems, or |
1ba3f8033b3a
(Checklist): Say that the example with LC_ALL and such is for a Unix shell.
Eli Zaretskii <eliz@gnu.org>
parents:
36388
diff
changeset
|
657 if you use a Unix-style shell such as Bash, you can use this shell |
1ba3f8033b3a
(Checklist): Say that the example with LC_ALL and such is for a Unix shell.
Eli Zaretskii <eliz@gnu.org>
parents:
36388
diff
changeset
|
658 command to view the relevant values: |
35239
a4e73c75cbca
Ask for locale info in bug reports.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
659 |
a4e73c75cbca
Ask for locale info in bug reports.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
660 @example |
37119
a4f474cb3812
(Checklist): Include more LC_* variables in the list, as suggested
Eli Zaretskii <eliz@gnu.org>
parents:
37087
diff
changeset
|
661 echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_TYPE=$LC_TYPE \ |
a4f474cb3812
(Checklist): Include more LC_* variables in the list, as suggested
Eli Zaretskii <eliz@gnu.org>
parents:
37087
diff
changeset
|
662 LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG |
35239
a4e73c75cbca
Ask for locale info in bug reports.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
663 @end example |
a4e73c75cbca
Ask for locale info in bug reports.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
664 |
37087
f4039f11318f
(Checklist): Mention the `locale' command as an alternative method of
Eli Zaretskii <eliz@gnu.org>
parents:
36791
diff
changeset
|
665 Alternatively, use the @command{locale} command, if your system has it, |
f4039f11318f
(Checklist): Mention the `locale' command as an alternative method of
Eli Zaretskii <eliz@gnu.org>
parents:
36791
diff
changeset
|
666 to display your locale settings. |
f4039f11318f
(Checklist): Mention the `locale' command as an alternative method of
Eli Zaretskii <eliz@gnu.org>
parents:
36791
diff
changeset
|
667 |
f4039f11318f
(Checklist): Mention the `locale' command as an alternative method of
Eli Zaretskii <eliz@gnu.org>
parents:
36791
diff
changeset
|
668 You can use the @kbd{M-!} command to execute these commands from |
35239
a4e73c75cbca
Ask for locale info in bug reports.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
669 Emacs, and then copy the output from the @samp{*Messages*} buffer into |
36620
639ad3d05eb6
(Checklist): Mention that `getenv' can be used to get at the value
Eli Zaretskii <eliz@gnu.org>
parents:
36497
diff
changeset
|
670 the bug report. Alternatively, @kbd{M-x getenv @key{RET} LC_ALL |
639ad3d05eb6
(Checklist): Mention that `getenv' can be used to get at the value
Eli Zaretskii <eliz@gnu.org>
parents:
36497
diff
changeset
|
671 @key{RET}} will print the value of @code{LC_ALL} in the echo area, and |
639ad3d05eb6
(Checklist): Mention that `getenv' can be used to get at the value
Eli Zaretskii <eliz@gnu.org>
parents:
36497
diff
changeset
|
672 you can copy its output from the @samp{*Messages*} buffer. |
35239
a4e73c75cbca
Ask for locale info in bug reports.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
673 |
a4e73c75cbca
Ask for locale info in bug reports.
Richard M. Stallman <rms@gnu.org>
parents:
35188
diff
changeset
|
674 @item |
25829 | 675 A description of what behavior you observe that you believe is |
676 incorrect. For example, ``The Emacs process gets a fatal signal,'' or, | |
677 ``The resulting text is as follows, which I think is wrong.'' | |
678 | |
679 Of course, if the bug is that Emacs gets a fatal signal, then one can't | |
680 miss it. But if the bug is incorrect text, the maintainer might fail to | |
681 notice what is wrong. Why leave it to chance? | |
682 | |
683 Even if the problem you experience is a fatal signal, you should still | |
684 say so explicitly. Suppose something strange is going on, such as, your | |
685 copy of the source is out of sync, or you have encountered a bug in the | |
686 C library on your system. (This has happened!) Your copy might crash | |
687 and the copy here might not. If you @emph{said} to expect a crash, then | |
688 when Emacs here fails to crash, we would know that the bug was not | |
689 happening. If you don't say to expect a crash, then we would not know | |
690 whether the bug was happening---we would not be able to draw any | |
691 conclusion from our observations. | |
692 | |
693 @item | |
36180
252e21b04fb1
Suggest copying problematical manual text into the bug report.
Richard M. Stallman <rms@gnu.org>
parents:
35874
diff
changeset
|
694 If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual |
252e21b04fb1
Suggest copying problematical manual text into the bug report.
Richard M. Stallman <rms@gnu.org>
parents:
35874
diff
changeset
|
695 fails to describe the actual behavior of Emacs, or that the text is |
252e21b04fb1
Suggest copying problematical manual text into the bug report.
Richard M. Stallman <rms@gnu.org>
parents:
35874
diff
changeset
|
696 confusing, copy in the text from the online manual which you think is |
252e21b04fb1
Suggest copying problematical manual text into the bug report.
Richard M. Stallman <rms@gnu.org>
parents:
35874
diff
changeset
|
697 at fault. If the section is small, just the section name is enough. |
252e21b04fb1
Suggest copying problematical manual text into the bug report.
Richard M. Stallman <rms@gnu.org>
parents:
35874
diff
changeset
|
698 |
252e21b04fb1
Suggest copying problematical manual text into the bug report.
Richard M. Stallman <rms@gnu.org>
parents:
35874
diff
changeset
|
699 @item |
25829 | 700 If the manifestation of the bug is an Emacs error message, it is |
701 important to report the precise text of the error message, and a | |
702 backtrace showing how the Lisp program in Emacs arrived at the error. | |
703 | |
704 To get the error message text accurately, copy it from the | |
705 @samp{*Messages*} buffer into the bug report. Copy all of it, not just | |
706 part. | |
707 | |
37347
bd817d6f9ba3
Minor clarifications regarding DEL key.
Richard M. Stallman <rms@gnu.org>
parents:
37126
diff
changeset
|
708 @findex toggle-debug-on-error |
bd817d6f9ba3
Minor clarifications regarding DEL key.
Richard M. Stallman <rms@gnu.org>
parents:
37126
diff
changeset
|
709 To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error} |
bd817d6f9ba3
Minor clarifications regarding DEL key.
Richard M. Stallman <rms@gnu.org>
parents:
37126
diff
changeset
|
710 before the error happens (that is to say, you must give that command |
bd817d6f9ba3
Minor clarifications regarding DEL key.
Richard M. Stallman <rms@gnu.org>
parents:
37126
diff
changeset
|
711 and then make the bug happen). This causes the error to run the Lisp |
bd817d6f9ba3
Minor clarifications regarding DEL key.
Richard M. Stallman <rms@gnu.org>
parents:
37126
diff
changeset
|
712 debugger, which shows you a backtrace. Copy the text of the |
bd817d6f9ba3
Minor clarifications regarding DEL key.
Richard M. Stallman <rms@gnu.org>
parents:
37126
diff
changeset
|
713 debugger's backtrace into the bug report. @xref{Debugger,, The Lisp |
bd817d6f9ba3
Minor clarifications regarding DEL key.
Richard M. Stallman <rms@gnu.org>
parents:
37126
diff
changeset
|
714 Debugger, elisp, the Emacs Lisp Reference Manual}, for information on |
bd817d6f9ba3
Minor clarifications regarding DEL key.
Richard M. Stallman <rms@gnu.org>
parents:
37126
diff
changeset
|
715 debugging Emacs Lisp programs. |
25829 | 716 |
717 This use of the debugger is possible only if you know how to make the | |
718 bug happen again. If you can't make it happen again, at least copy | |
719 the whole error message. | |
720 | |
721 @item | |
722 Check whether any programs you have loaded into the Lisp world, | |
723 including your @file{.emacs} file, set any variables that may affect the | |
724 functioning of Emacs. Also, see whether the problem happens in a | |
725 freshly started Emacs without loading your @file{.emacs} file (start | |
726 Emacs with the @code{-q} switch to prevent loading the init file). If | |
727 the problem does @emph{not} occur then, you must report the precise | |
728 contents of any programs that you must load into the Lisp world in order | |
729 to cause the problem to occur. | |
730 | |
731 @item | |
732 If the problem does depend on an init file or other Lisp programs that | |
733 are not part of the standard Emacs system, then you should make sure it | |
734 is not a bug in those programs by complaining to their maintainers | |
735 first. After they verify that they are using Emacs in a way that is | |
736 supposed to work, they should report the bug. | |
737 | |
738 @item | |
739 If you wish to mention something in the GNU Emacs source, show the line | |
740 of code with a few lines of context. Don't just give a line number. | |
741 | |
742 The line numbers in the development sources don't match those in your | |
743 sources. It would take extra work for the maintainers to determine what | |
744 code is in your version at a given line number, and we could not be | |
745 certain. | |
746 | |
747 @item | |
748 Additional information from a C debugger such as GDB might enable | |
749 someone to find a problem on a machine which he does not have available. | |
750 If you don't know how to use GDB, please read the GDB manual---it is not | |
751 very long, and using GDB is easy. You can find the GDB distribution, | |
752 including the GDB manual in online form, in most of the same places you | |
753 can find the Emacs distribution. To run Emacs under GDB, you should | |
754 switch to the @file{src} subdirectory in which Emacs was compiled, then | |
755 do @samp{gdb emacs}. It is important for the directory @file{src} to be | |
756 current so that GDB will read the @file{.gdbinit} file in this | |
757 directory. | |
758 | |
759 However, you need to think when you collect the additional information | |
760 if you want it to show what causes the bug. | |
761 | |
762 @cindex backtrace for bug reports | |
763 For example, many people send just a backtrace, but that is not very | |
764 useful by itself. A simple backtrace with arguments often conveys | |
765 little about what is happening inside GNU Emacs, because most of the | |
766 arguments listed in the backtrace are pointers to Lisp objects. The | |
767 numeric values of these pointers have no significance whatever; all that | |
768 matters is the contents of the objects they point to (and most of the | |
769 contents are themselves pointers). | |
770 | |
771 @findex debug_print | |
772 To provide useful information, you need to show the values of Lisp | |
773 objects in Lisp notation. Do this for each variable which is a Lisp | |
774 object, in several stack frames near the bottom of the stack. Look at | |
775 the source to see which variables are Lisp objects, because the debugger | |
776 thinks of them as integers. | |
777 | |
778 To show a variable's value in Lisp syntax, first print its value, then | |
779 use the user-defined GDB command @code{pr} to print the Lisp object in | |
780 Lisp syntax. (If you must use another debugger, call the function | |
781 @code{debug_print} with the object as an argument.) The @code{pr} | |
782 command is defined by the file @file{.gdbinit}, and it works only if you | |
783 are debugging a running process (not with a core dump). | |
784 | |
785 To make Lisp errors stop Emacs and return to GDB, put a breakpoint at | |
786 @code{Fsignal}. | |
787 | |
27729 | 788 For a short listing of Lisp functions running, type the GDB |
789 command @code{xbacktrace}. | |
790 | |
25829 | 791 The file @file{.gdbinit} defines several other commands that are useful |
792 for examining the data types and contents of Lisp objects. Their names | |
793 begin with @samp{x}. These commands work at a lower level than | |
794 @code{pr}, and are less convenient, but they may work even when | |
795 @code{pr} does not, such as when debugging a core dump or when Emacs has | |
796 had a fatal signal. | |
797 | |
35874
99572fa1c8c3
Remove the more arcane part of Emacs debug instructions. Replace
Eli Zaretskii <eliz@gnu.org>
parents:
35705
diff
changeset
|
798 @cindex debugging Emacs, tricks and techniques |
99572fa1c8c3
Remove the more arcane part of Emacs debug instructions. Replace
Eli Zaretskii <eliz@gnu.org>
parents:
35705
diff
changeset
|
799 More detailed advice and other useful techniques for debugging Emacs |
99572fa1c8c3
Remove the more arcane part of Emacs debug instructions. Replace
Eli Zaretskii <eliz@gnu.org>
parents:
35705
diff
changeset
|
800 are available in the file @file{etc/DEBUG} in the Emacs distribution. |
99572fa1c8c3
Remove the more arcane part of Emacs debug instructions. Replace
Eli Zaretskii <eliz@gnu.org>
parents:
35705
diff
changeset
|
801 That file also includes instructions for investigating problems |
99572fa1c8c3
Remove the more arcane part of Emacs debug instructions. Replace
Eli Zaretskii <eliz@gnu.org>
parents:
35705
diff
changeset
|
802 whereby Emacs stops responding (many people assume that Emacs is |
36180
252e21b04fb1
Suggest copying problematical manual text into the bug report.
Richard M. Stallman <rms@gnu.org>
parents:
35874
diff
changeset
|
803 ``hung,'' whereas in fact it might be in an infinite loop). |
25829 | 804 |
35874
99572fa1c8c3
Remove the more arcane part of Emacs debug instructions. Replace
Eli Zaretskii <eliz@gnu.org>
parents:
35705
diff
changeset
|
805 In an installed Emacs, the file @file{etc/DEBUG} is in the same |
99572fa1c8c3
Remove the more arcane part of Emacs debug instructions. Replace
Eli Zaretskii <eliz@gnu.org>
parents:
35705
diff
changeset
|
806 directory where the Emacs on-line documentation file @file{DOC}, |
99572fa1c8c3
Remove the more arcane part of Emacs debug instructions. Replace
Eli Zaretskii <eliz@gnu.org>
parents:
35705
diff
changeset
|
807 typically in the @file{/usr/local/share/emacs/@var{version}/etc/} |
99572fa1c8c3
Remove the more arcane part of Emacs debug instructions. Replace
Eli Zaretskii <eliz@gnu.org>
parents:
35705
diff
changeset
|
808 directory. The directory for your installation is stored in the |
99572fa1c8c3
Remove the more arcane part of Emacs debug instructions. Replace
Eli Zaretskii <eliz@gnu.org>
parents:
35705
diff
changeset
|
809 variable @code{data-directory}. |
25829 | 810 @end itemize |
811 | |
812 Here are some things that are not necessary in a bug report: | |
813 | |
814 @itemize @bullet | |
815 @item | |
816 A description of the envelope of the bug---this is not necessary for a | |
817 reproducible bug. | |
818 | |
819 Often people who encounter a bug spend a lot of time investigating | |
820 which changes to the input file will make the bug go away and which | |
821 changes will not affect it. | |
822 | |
823 This is often time-consuming and not very useful, because the way we | |
824 will find the bug is by running a single example under the debugger with | |
825 breakpoints, not by pure deduction from a series of examples. You might | |
826 as well save time by not searching for additional examples. | |
827 | |
828 Of course, if you can find a simpler example to report @emph{instead} of | |
829 the original one, that is a convenience. Errors in the output will be | |
830 easier to spot, running under the debugger will take less time, etc. | |
831 | |
832 However, simplification is not vital; if you can't do this or don't have | |
833 time to try, please report the bug with your original test case. | |
834 | |
835 @item | |
836 A system-call trace of Emacs execution. | |
837 | |
838 System-call traces are very useful for certain special kinds of | |
839 debugging, but in most cases they give little useful information. It is | |
840 therefore strange that many people seem to think that @emph{the} way to | |
841 report information about a crash is to send a system-call trace. Perhaps | |
842 this is a habit formed from experience debugging programs that don't | |
843 have source code or debugging symbols. | |
844 | |
845 In most programs, a backtrace is normally far, far more informative than | |
846 a system-call trace. Even in Emacs, a simple backtrace is generally | |
847 more informative, though to give full information you should supplement | |
848 the backtrace by displaying variable values and printing them as Lisp | |
849 objects with @code{pr} (see above). | |
850 | |
851 @item | |
852 A patch for the bug. | |
853 | |
854 A patch for the bug is useful if it is a good one. But don't omit the | |
855 other information that a bug report needs, such as the test case, on the | |
856 assumption that a patch is sufficient. We might see problems with your | |
857 patch and decide to fix the problem another way, or we might not | |
858 understand it at all. And if we can't understand what bug you are | |
859 trying to fix, or why your patch should be an improvement, we mustn't | |
860 install it. | |
861 | |
862 @ifinfo | |
863 @xref{Sending Patches}, for guidelines on how to make it easy for us to | |
864 understand and install your patches. | |
865 @end ifinfo | |
866 | |
867 @item | |
868 A guess about what the bug is or what it depends on. | |
869 | |
870 Such guesses are usually wrong. Even experts can't guess right about | |
871 such things without first using the debugger to find the facts. | |
872 @end itemize | |
873 | |
874 @node Sending Patches | |
875 @subsection Sending Patches for GNU Emacs | |
876 | |
877 @cindex sending patches for GNU Emacs | |
878 @cindex patches, sending | |
879 If you would like to write bug fixes or improvements for GNU Emacs, | |
880 that is very helpful. When you send your changes, please follow these | |
881 guidelines to make it easy for the maintainers to use them. If you | |
882 don't follow these guidelines, your information might still be useful, | |
883 but using it will take extra work. Maintaining GNU Emacs is a lot of | |
884 work in the best of circumstances, and we can't keep up unless you do | |
885 your best to help. | |
886 | |
887 @itemize @bullet | |
888 @item | |
889 Send an explanation with your changes of what problem they fix or what | |
890 improvement they bring about. For a bug fix, just include a copy of the | |
891 bug report, and explain why the change fixes the bug. | |
892 | |
893 (Referring to a bug report is not as good as including it, because then | |
894 we will have to look it up, and we have probably already deleted it if | |
895 we've already fixed the bug.) | |
896 | |
897 @item | |
898 Always include a proper bug report for the problem you think you have | |
899 fixed. We need to convince ourselves that the change is right before | |
900 installing it. Even if it is correct, we might have trouble | |
901 understanding it if we don't have a way to reproduce the problem. | |
902 | |
903 @item | |
904 Include all the comments that are appropriate to help people reading the | |
905 source in the future understand why this change was needed. | |
906 | |
907 @item | |
908 Don't mix together changes made for different reasons. | |
909 Send them @emph{individually}. | |
910 | |
911 If you make two changes for separate reasons, then we might not want to | |
912 install them both. We might want to install just one. If you send them | |
913 all jumbled together in a single set of diffs, we have to do extra work | |
914 to disentangle them---to figure out which parts of the change serve | |
915 which purpose. If we don't have time for this, we might have to ignore | |
916 your changes entirely. | |
917 | |
918 If you send each change as soon as you have written it, with its own | |
919 explanation, then two changes never get tangled up, and we can consider | |
920 each one properly without any extra work to disentangle them. | |
921 | |
922 @item | |
923 Send each change as soon as that change is finished. Sometimes people | |
924 think they are helping us by accumulating many changes to send them all | |
925 together. As explained above, this is absolutely the worst thing you | |
926 could do. | |
927 | |
928 Since you should send each change separately, you might as well send it | |
929 right away. That gives us the option of installing it immediately if it | |
930 is important. | |
931 | |
932 @item | |
933 Use @samp{diff -c} to make your diffs. Diffs without context are hard | |
934 to install reliably. More than that, they are hard to study; we must | |
935 always study a patch to decide whether we want to install it. Unidiff | |
936 format is better than contextless diffs, but not as easy to read as | |
937 @samp{-c} format. | |
938 | |
939 If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when | |
940 making diffs of C code. This shows the name of the function that each | |
941 change occurs in. | |
942 | |
943 @item | |
944 Avoid any ambiguity as to which is the old version and which is the new. | |
945 Please make the old version the first argument to diff, and the new | |
946 version the second argument. And please give one version or the other a | |
947 name that indicates whether it is the old version or your new changed | |
948 one. | |
949 | |
950 @item | |
951 Write the change log entries for your changes. This is both to save us | |
952 the extra work of writing them, and to help explain your changes so we | |
953 can understand them. | |
954 | |
955 The purpose of the change log is to show people where to find what was | |
956 changed. So you need to be specific about what functions you changed; | |
957 in large functions, it's often helpful to indicate where within the | |
958 function the change was. | |
959 | |
960 On the other hand, once you have shown people where to find the change, | |
961 you need not explain its purpose in the change log. Thus, if you add a | |
962 new function, all you need to say about it is that it is new. If you | |
963 feel that the purpose needs explaining, it probably does---but put the | |
964 explanation in comments in the code. It will be more useful there. | |
965 | |
966 Please read the @file{ChangeLog} files in the @file{src} and @file{lisp} | |
967 directories to see what sorts of information to put in, and to learn the | |
968 style that we use. If you would like your name to appear in the header | |
969 line, showing who made the change, send us the header line. | |
970 @xref{Change Log}. | |
971 | |
972 @item | |
973 When you write the fix, keep in mind that we can't install a change that | |
974 would break other systems. Please think about what effect your change | |
975 will have if compiled on another type of system. | |
976 | |
977 Sometimes people send fixes that @emph{might} be an improvement in | |
978 general---but it is hard to be sure of this. It's hard to install | |
979 such changes because we have to study them very carefully. Of course, | |
980 a good explanation of the reasoning by which you concluded the change | |
981 was correct can help convince us. | |
982 | |
983 The safest changes are changes to the configuration files for a | |
984 particular machine. These are safe because they can't create new bugs | |
985 on other machines. | |
986 | |
987 Please help us keep up with the workload by designing the patch in a | |
988 form that is clearly safe to install. | |
989 @end itemize | |
990 | |
991 @node Contributing, Service, Bugs, Top | |
992 @section Contributing to Emacs Development | |
993 | |
994 If you would like to help pretest Emacs releases to assure they work | |
995 well, or if you would like to work on improving Emacs, please contact | |
29107 | 996 the maintainers at @email{bug-gnu-emacs@@gnu.org}. A pretester |
25829 | 997 should be prepared to investigate bugs as well as report them. If you'd |
998 like to work on improving Emacs, please ask for suggested projects or | |
999 suggest your own ideas. | |
1000 | |
1001 If you have already written an improvement, please tell us about it. If | |
1002 you have not yet started work, it is useful to contact | |
29107 | 1003 @email{bug-gnu-emacs@@gnu.org} before you start; it might be |
25829 | 1004 possible to suggest ways to make your extension fit in better with the |
1005 rest of Emacs. | |
1006 | |
1007 @node Service, Command Arguments, Contributing, Top | |
1008 @section How To Get Help with GNU Emacs | |
1009 | |
1010 If you need help installing, using or changing GNU Emacs, there are two | |
1011 ways to find it: | |
1012 | |
1013 @itemize @bullet | |
1014 @item | |
1015 Send a message to the mailing list | |
29107 | 1016 @email{help-gnu-emacs@@gnu.org}, or post your request on |
25829 | 1017 newsgroup @code{gnu.emacs.help}. (This mailing list and newsgroup |
1018 interconnect, so it does not matter which one you use.) | |
1019 | |
1020 @item | |
1021 Look in the service directory for someone who might help you for a fee. | |
1022 The service directory is found in the file named @file{etc/SERVICE} in the | |
1023 Emacs distribution. | |
1024 @end itemize |