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