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