1 This is ../info/xemacs.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * XEmacs: (xemacs). XEmacs Editor.
9 This file documents the XEmacs editor.
11 Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
12 1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
13 Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided also
21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
22 General Public License" are included exactly as in the original, and
23 provided that the entire resulting derived work is distributed under the
24 terms of a permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above conditions for modified
28 versions, except that the sections entitled "The GNU Manifesto",
29 "Distribution" and "GNU General Public License" may be included in a
30 translation approved by the author instead of in the original English.
33 File: xemacs.info, Node: Resource List, Next: Face Resources, Prev: Iconic Resources, Up: X Resources
38 Emacs frames accept the following resources:
40 `geometry' (class `Geometry'): string
41 Initial geometry for the frame. *Note Geometry Resources::, for a
42 complete discussion of how this works.
44 `iconic' (class `Iconic'): boolean
45 Whether this frame should appear in the iconified state.
47 `internalBorderWidth' (class `InternalBorderWidth'): int
48 How many blank pixels to leave between the text and the edge of the
51 `interline' (class `Interline'): int
52 How many pixels to leave between each line (may not be
55 `menubar' (class `Menubar'): boolean
56 Whether newly-created frames should initially have a menubar. Set
59 `initiallyUnmapped' (class `InitiallyUnmapped'): boolean
60 Whether XEmacs should leave the initial frame unmapped when it
61 starts up. This is useful if you are starting XEmacs as a server
62 (e.g. in conjunction with gnuserv or the external client widget).
63 You can also control this with the `-unmapped' command-line option.
65 `barCursor' (class `BarColor'): boolean
66 Whether the cursor should be displayed as a bar, or the
69 `cursorColor' (class `CursorColor'): color-name
70 The color of the text cursor.
72 `scrollBarWidth' (class `ScrollBarWidth'): integer
73 How wide the vertical scrollbars should be, in pixels; 0 means no
74 vertical scrollbars. You can also use a resource specification of
75 the form `*scrollbar.width', or the usual toolkit scrollbar
76 resources: `*XmScrollBar.width' (Motif), `*XlwScrollBar.width'
77 (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend
78 that you use the toolkit resources, though, because they're
79 dependent on how exactly your particular build of XEmacs was
82 `scrollBarHeight' (class `ScrollBarHeight'): integer
83 How high the horizontal scrollbars should be, in pixels; 0 means no
84 horizontal scrollbars. You can also use a resource specification
85 of the form `*scrollbar.height', or the usual toolkit scrollbar
86 resources: `*XmScrollBar.height' (Motif), `*XlwScrollBar.height'
87 (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend
88 that you use the toolkit resources, though, because they're
89 dependent on how exactly your particular build of XEmacs was
92 `scrollBarPlacement' (class `ScrollBarPlacement'): string
93 Where the horizontal and vertical scrollbars should be positioned.
94 This should be one of the four strings `BOTTOM_LEFT',
95 `BOTTOM_RIGHT', `TOP_LEFT', and `TOP_RIGHT'. Default is
96 `BOTTOM_RIGHT' for the Motif and Lucid scrollbars and
97 `BOTTOM_LEFT' for the Athena scrollbars.
99 `topToolBarHeight' (class `TopToolBarHeight'): integer
100 `bottomToolBarHeight' (class `BottomToolBarHeight'): integer
101 `leftToolBarWidth' (class `LeftToolBarWidth'): integer
102 `rightToolBarWidth' (class `RightToolBarWidth'): integer
103 Height and width of the four possible toolbars.
105 `topToolBarShadowColor' (class `TopToolBarShadowColor'): color-name
106 `bottomToolBarShadowColor' (class `BottomToolBarShadowColor'): color-name
107 Color of the top and bottom shadows for the toolbars. NOTE: These
108 resources do _not_ have anything to do with the top and bottom
109 toolbars (i.e. the toolbars at the top and bottom of the frame)!
110 Rather, they affect the top and bottom shadows around the edges of
111 all four kinds of toolbars.
113 `topToolBarShadowPixmap' (class `TopToolBarShadowPixmap'): pixmap-name
114 `bottomToolBarShadowPixmap' (class `BottomToolBarShadowPixmap'): pixmap-name
115 Pixmap of the top and bottom shadows for the toolbars. If set,
116 these resources override the corresponding color resources. NOTE:
117 These resources do _not_ have anything to do with the top and
118 bottom toolbars (i.e. the toolbars at the top and bottom of the
119 frame)! Rather, they affect the top and bottom shadows around the
120 edges of all four kinds of toolbars.
122 `toolBarShadowThickness' (class `ToolBarShadowThickness'): integer
123 Thickness of the shadows around the toolbars, in pixels.
125 `visualBell' (class `VisualBell'): boolean
126 Whether XEmacs should flash the screen rather than making an
129 `bellVolume' (class `BellVolume'): integer
130 Volume of the audible beep.
132 `useBackingStore' (class `UseBackingStore'): boolean
133 Whether XEmacs should set the backing-store attribute of the X
134 windows it creates. This increases the memory usage of the X
135 server but decreases the amount of X traffic necessary to update
136 the screen, and is useful when the connection to the X server goes
137 over a low-bandwidth line such as a modem connection.
139 Emacs devices accept the following resources:
141 `textPointer' (class `Cursor'): cursor-name
142 The cursor to use when the mouse is over text. This resource is
143 used to initialize the variable `x-pointer-shape'.
145 `selectionPointer' (class `Cursor'): cursor-name
146 The cursor to use when the mouse is over a selectable text region
147 (an extent with the `highlight' property; for example, an Info
148 cross-reference). This resource is used to initialize the variable
149 `x-selection-pointer-shape'.
151 `spacePointer' (class `Cursor'): cursor-name
152 The cursor to use when the mouse is over a blank space in a buffer
153 (that is, after the end of a line or after the end-of-file). This
154 resource is used to initialize the variable
155 `x-nontext-pointer-shape'.
157 `modeLinePointer' (class `Cursor'): cursor-name
158 The cursor to use when the mouse is over a modeline. This
159 resource is used to initialize the variable `x-mode-pointer-shape'.
161 `gcPointer' (class `Cursor'): cursor-name
162 The cursor to display when a garbage-collection is in progress.
163 This resource is used to initialize the variable
164 `x-gc-pointer-shape'.
166 `scrollbarPointer' (class `Cursor'): cursor-name
167 The cursor to use when the mouse is over the scrollbar. This
168 resource is used to initialize the variable
169 `x-scrollbar-pointer-shape'.
171 `pointerColor' (class `Foreground'): color-name
172 `pointerBackground' (class `Background'): color-name
173 The foreground and background colors of the mouse cursor. These
174 resources are used to initialize the variables
175 `x-pointer-foreground-color' and `x-pointer-background-color'.
178 File: xemacs.info, Node: Face Resources, Next: Widgets, Prev: Resource List, Up: X Resources
183 The attributes of faces are also per-frame. They can be specified as:
185 Emacs.FACE_NAME.parameter: value
189 Emacs*FRAME_NAME.FACE_NAME.parameter: value
191 Faces accept the following resources:
193 `attributeFont' (class `AttributeFont'): font-name
194 The font of this face.
196 `attributeForeground' (class `AttributeForeground'): color-name
197 `attributeBackground' (class `AttributeBackground'): color-name
198 The foreground and background colors of this face.
200 `attributeBackgroundPixmap' (class `AttributeBackgroundPixmap'): file-name
201 The name of an XBM file (or XPM file, if your version of Emacs
202 supports XPM), to use as a background stipple.
204 `attributeUnderline' (class `AttributeUnderline'): boolean
205 Whether text in this face should be underlined.
207 All text is displayed in some face, defaulting to the face named
208 `default'. To set the font of normal text, use
209 `Emacs*default.attributeFont'. To set it in the frame named `fred', use
210 `Emacs*fred.default.attributeFont'.
212 These are the names of the predefined faces:
215 Everything inherits from this.
218 If this is not specified in the resource database, Emacs tries to
219 find a bold version of the font of the default face.
222 If this is not specified in the resource database, Emacs tries to
223 find an italic version of the font of the default face.
226 If this is not specified in the resource database, Emacs tries to
227 find a bold-italic version of the font of the default face.
230 This is the face that the modeline is displayed in. If not
231 specified in the resource database, it is determined from the
232 default face by reversing the foreground and background colors.
235 This is the face that highlighted extents (for example, Info
236 cross-references and possible completions, when the mouse passes
237 over them) are displayed in.
241 These are the faces that the left and right annotation margins are
245 This is the face that mouse selections are displayed in.
248 This is the face that the matched text being searched for is
252 This is the face of info menu items. If unspecified, it is copied
256 This is the face of info cross-references. If unspecified, it is
257 copied from `bold'. (Note that, when the mouse passes over a
258 cross-reference, the cross-reference's face is determined from a
259 combination of the `info-xref' and `highlight' faces.)
261 Other packages might define their own faces; to see a list of all
262 faces, use any of the interactive face-manipulation commands such as
263 `set-face-font' and type `?' when you are prompted for the name of a
266 If the `bold', `italic', and `bold-italic' faces are not specified
267 in the resource database, then XEmacs attempts to derive them from the
268 font of the default face. It can only succeed at this if you have
269 specified the default font using the XLFD (X Logical Font Description)
270 format, which looks like
272 *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
274 If you use any of the other, less strict font name formats, some of
277 lucidasanstypewriter-12
281 then XEmacs won't be able to guess the names of the bold and italic
282 versions. All X fonts can be referred to via XLFD-style names, so you
283 should use those forms. See the man pages for `X(1)', `xlsfonts(1)',
287 File: xemacs.info, Node: Widgets, Next: Menubar Resources, Prev: Face Resources, Up: X Resources
292 There are several structural widgets between the terminal EmacsFrame
293 widget and the top level ApplicationShell; the exact names and types of
294 these widgets change from release to release (for example, they changed
295 between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are
296 subject to further change in the future, so you should avoid mentioning
297 them in your resource database. The above-mentioned syntaxes should be
298 forward- compatible. As of 19.13, the exact widget hierarchy is as
301 INVOCATION-NAME "shell" "container" FRAME-NAME
302 x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame"
304 where INVOCATION-NAME is the terminal component of the name of the
305 XEmacs executable (usually `xemacs'), and `x-emacs-application-class'
306 is generally `Emacs'.
309 File: xemacs.info, Node: Menubar Resources, Prev: Widgets, Up: X Resources
314 As the menubar is implemented as a widget which is not a part of
315 XEmacs proper, it does not use the face mechanism for specifying fonts
316 and colors: It uses whatever resources are appropriate to the type of
317 widget which is used to implement it.
319 If Emacs was compiled to use only the Lucid Motif-lookalike menu
320 widgets, then one way to specify the font of the menubar would be
322 Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
324 If both the Lucid Motif-lookalike menu widgets and X Font Sets are
325 configured to allow multilingual menubars, then one uses
327 *menubar*FontSet: -*-helvetica-bold-r-*-*-*-120-*-*-*-*-iso8859-*, \
328 -*-*-*-*-*-*-*-120-*-jisx0208.1983-0
330 That would specify fonts for a Japanese menubar. Specifying only one
331 XLFD is acceptable; specifying more than one for a given registry
332 (language) is also allowed. When X Font Sets are configured, some .font
333 resources (eg, menubars) are ignored in favor of the corresponding
336 If the Motif library is being used, then one would have to use
338 Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
340 because the Motif library uses the `fontList' resource name instead
341 of `font', which has subtly different semantics.
343 The same is true of the scrollbars: They accept whichever resources
344 are appropriate for the toolkit in use.
347 File: xemacs.info, Node: Quitting, Next: Lossage, Prev: Customization, Up: Top
349 Quitting and Aborting
350 =====================
353 Quit. Cancel running or partially typed command.
356 Abort innermost recursive editing level and cancel the command
357 which invoked it (`abort-recursive-edit').
360 Abort all recursive editing levels that are currently executing.
363 Cancel an already-executed command, usually (`undo').
365 There are two ways of cancelling commands which are not finished
366 executing: "quitting" with `C-g', and "aborting" with `C-]' or `M-x
367 top-level'. Quitting is cancelling a partially typed command or one
368 which is already running. Aborting is getting out of a recursive
369 editing level and cancelling the command that invoked the recursive
372 Quitting with `C-g' is used for getting rid of a partially typed
373 command or a numeric argument that you don't want. It also stops a
374 running command in the middle in a relatively safe way, so you can use
375 it if you accidentally start executing a command that takes a long
376 time. In particular, it is safe to quit out of killing; either your
377 text will ALL still be there, or it will ALL be in the kill ring (or
378 maybe both). Quitting an incremental search does special things
379 documented under searching; in general, it may take two successive
380 `C-g' characters to get out of a search. `C-g' works by setting the
381 variable `quit-flag' to `t' the instant `C-g' is typed; Emacs Lisp
382 checks this variable frequently and quits if it is non-`nil'. `C-g' is
383 only actually executed as a command if it is typed while Emacs is
386 If you quit twice in a row before the first `C-g' is recognized, you
387 activate the "emergency escape" feature and return to the shell. *Note
390 You can use `C-]' (`abort-recursive-edit') to get out of a recursive
391 editing level and cancel the command which invoked it. Quitting with
392 `C-g' does not do this, and could not do this because it is used to
393 cancel a partially typed command within the recursive editing level.
394 Both operations are useful. For example, if you are in the Emacs
395 debugger (*note Lisp Debug::) and have typed `C-u 8' to enter a numeric
396 argument, you can cancel that argument with `C-g' and remain in the
399 The command `M-x top-level' is equivalent to "enough" `C-]' commands
400 to get you out of all the levels of recursive edits that you are in.
401 `C-]' only gets you out one level at a time, but `M-x top-level' goes
402 out all levels at once. Both `C-]' and `M-x top-level' are like all
403 other commands and unlike `C-g' in that they are effective only when
404 Emacs is ready for a command. `C-]' is an ordinary key and has its
405 meaning only because of its binding in the keymap. *Note Recursive
408 `C-x u' (`undo') is not strictly speaking a way of cancelling a
409 command, but you can think of it as cancelling a command already
410 finished executing. *Note Undo::.
413 File: xemacs.info, Node: Lossage, Next: Bugs, Prev: Quitting, Up: Top
415 Dealing With Emacs Trouble
416 ==========================
418 This section describes various conditions in which Emacs fails to
419 work, and how to recognize them and correct them.
423 * Stuck Recursive:: `[...]' in mode line around the parentheses.
424 * Screen Garbled:: Garbage on the screen.
425 * Text Garbled:: Garbage in the text.
426 * Unasked-for Search:: Spontaneous entry to incremental search.
427 * Emergency Escape:: Emergency escape---
428 What to do if Emacs stops responding.
429 * Total Frustration:: When you are at your wits' end.
432 File: xemacs.info, Node: Stuck Recursive, Next: Screen Garbled, Prev: Lossage, Up: Lossage
434 Recursive Editing Levels
435 ------------------------
437 Recursive editing levels are important and useful features of Emacs,
438 but they can seem like malfunctions to the user who does not understand
441 If the mode line has square brackets `[...]' around the parentheses
442 that contain the names of the major and minor modes, you have entered a
443 recursive editing level. If you did not do this on purpose, or if you
444 don't understand what that means, you should just get out of the
445 recursive editing level. To do so, type `M-x top-level'. This is
446 called getting back to top level. *Note Recursive Edit::.
449 File: xemacs.info, Node: Screen Garbled, Next: Text Garbled, Prev: Stuck Recursive, Up: Lossage
451 Garbage on the Screen
452 ---------------------
454 If the data on the screen looks wrong, the first thing to do is see
455 whether the text is actually wrong. Type `C-l', to redisplay the
456 entire screen. If the text appears correct after this, the problem was
457 entirely in the previous screen update.
459 Display updating problems often result from an incorrect termcap
460 entry for the terminal you are using. The file `etc/TERMS' in the Emacs
461 distribution gives the fixes for known problems of this sort.
462 `INSTALL' contains general advice for these problems in one of its
463 sections. Very likely there is simply insufficient padding for certain
464 display operations. To investigate the possibility that you have this
465 sort of problem, try Emacs on another terminal made by a different
466 manufacturer. If problems happen frequently on one kind of terminal but
467 not another kind, the real problem is likely to be a bad termcap entry,
468 though it could also be due to a bug in Emacs that appears for terminals
469 that have or lack specific features.
472 File: xemacs.info, Node: Text Garbled, Next: Unasked-for Search, Prev: Screen Garbled, Up: Lossage
477 If `C-l' shows that the text is wrong, try undoing the changes to it
478 using `C-x u' until it gets back to a state you consider correct. Also
479 try `C-h l' to find out what command you typed to produce the observed
482 If a large portion of text appears to be missing at the beginning or
483 end of the buffer, check for the word `Narrow' in the mode line. If it
484 appears, the text is still present, but marked off-limits. To make it
485 visible again, type `C-x n w'. *Note Narrowing::.
488 File: xemacs.info, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage
490 Spontaneous Entry to Incremental Search
491 ---------------------------------------
493 If Emacs spontaneously displays `I-search:' at the bottom of the
494 screen, it means that the terminal is sending `C-s' and `C-q' according
495 to the poorly designed xon/xoff "flow control" protocol. You should
496 try to prevent this by putting the terminal in a mode where it will not
497 use flow control, or by giving it enough padding that it will never
498 send a `C-s'. If that cannot be done, you must tell Emacs to expect
499 flow control to be used, until you can get a properly designed terminal.
501 Information on how to do these things can be found in the file
502 `INSTALL' in the Emacs distribution.
505 File: xemacs.info, Node: Emergency Escape, Next: Total Frustration, Prev: Unasked-for Search, Up: Lossage
510 Because at times there have been bugs causing Emacs to loop without
511 checking `quit-flag', a special feature causes Emacs to be suspended
512 immediately if you type a second `C-g' while the flag is already set,
513 so you can always get out of XEmacs. Normally Emacs recognizes and
514 clears `quit-flag' (and quits!) quickly enough to prevent this from
517 When you resume Emacs after a suspension caused by multiple `C-g', it
518 asks two questions before going back to what it had been doing:
521 Abort (and dump core)? (y or n)
523 Answer each one with `y' or `n' followed by <RET>.
525 Saying `y' to `Auto-save?' causes immediate auto-saving of all
526 modified buffers in which auto-saving is enabled.
528 Saying `y' to `Abort (and dump core)?' causes an illegal instruction
529 to be executed, dumping core. This is to enable a wizard to figure out
530 why Emacs was failing to quit in the first place. Execution does not
531 continue after a core dump. If you answer `n', execution does
532 continue. With luck, Emacs will ultimately check `quit-flag' and quit
533 normally. If not, and you type another `C-g', it is suspended again.
535 If Emacs is not really hung, but is just being slow, you may invoke
536 the double `C-g' feature without really meaning to. In that case,
537 simply resume and answer `n' to both questions, and you will arrive at
538 your former state. Presumably the quit you requested will happen soon.
540 The double-`C-g' feature may be turned off when Emacs is running
541 under a window system, since the window system always enables you to
542 kill Emacs or to create another window and run another program.
545 File: xemacs.info, Node: Total Frustration, Prev: Emergency Escape, Up: Lossage
547 Help for Total Frustration
548 --------------------------
550 If using Emacs (or something else) becomes terribly frustrating and
551 none of the techniques described above solve the problem, Emacs can
554 First, if the Emacs you are using is not responding to commands, type
555 `C-g C-g' to get out of it and then start a new one.
557 Second, type `M-x doctor <RET>'.
559 The doctor will make you feel better. Each time you say something to
560 the doctor, you must end it by typing <RET> <RET>. This lets the
561 doctor know you are finished.
564 File: xemacs.info, Node: Bugs, Prev: Lossage, Up: Top
569 Sometimes you will encounter a bug in Emacs. Although we cannot
570 promise we can or will fix the bug, and we might not even agree that it
571 is a bug, we want to hear about bugs you encounter in case we do want
574 To make it possible for us to fix a bug, you must report it. In
575 order to do so effectively, you must know when and how to do it.
580 If Emacs executes an illegal instruction, or dies with an operating
581 system error message that indicates a problem in the program (as
582 opposed to something like "disk full"), then it is certainly a bug.
584 If Emacs updates the display in a way that does not correspond to
585 what is in the buffer, then it is certainly a bug. If a command seems
586 to do the wrong thing but the problem corrects itself if you type
587 `C-l', it is a case of incorrect display updating.
589 Taking forever to complete a command can be a bug, but you must make
590 certain that it was really Emacs's fault. Some commands simply take a
591 long time. Type `C-g' and then `C-h l' to see whether the input Emacs
592 received was what you intended to type; if the input was such that you
593 KNOW it should have been processed quickly, report a bug. If you don't
594 know whether the command should take a long time, find out by looking
595 in the manual or by asking for assistance.
597 If a command you are familiar with causes an Emacs error message in a
598 case where its usual definition ought to be reasonable, it is probably a
601 If a command does the wrong thing, that is a bug. But be sure you
602 know for certain what it ought to have done. If you aren't familiar
603 with the command, or don't know for certain how the command is supposed
604 to work, then it might actually be working right. Rather than jumping
605 to conclusions, show the problem to someone who knows for certain.
607 Finally, a command's intended definition may not be best for editing
608 with. This is a very important sort of problem, but it is also a
609 matter of judgment. Also, it is easy to come to such a conclusion out
610 of ignorance of some of the existing features. It is probably best not
611 to complain about such a problem until you have checked the
612 documentation in the usual ways, feel confident that you understand it,
613 and know for certain that what you want is not available. If you are
614 not sure what the command is supposed to do after a careful reading of
615 the manual, check the index and glossary for any terms that may be
616 unclear. If you still do not understand, this indicates a bug in the
617 manual. The manual's job is to make everything clear. It is just as
618 important to report documentation bugs as program bugs.
620 If the online documentation string of a function or variable
621 disagrees with the manual, one of them must be wrong, so report the bug.
626 When you decide that there is a bug, it is important to report it
627 and to report it in a way which is useful. What is most useful is an
628 exact description of what commands you type, starting with the shell
629 command to run Emacs, until the problem happens. Always include the
630 version number of Emacs that you are using; type `M-x emacs-version' to
633 The most important principle in reporting a bug is to report FACTS,
634 not hypotheses or categorizations. It is always easier to report the
635 facts, but people seem to prefer to strain to posit explanations and
636 report them instead. If the explanations are based on guesses about
637 how Emacs is implemented, they will be useless; we will have to try to
638 figure out what the facts must have been to lead to such speculations.
639 Sometimes this is impossible. But in any case, it is unnecessary work
642 For example, suppose that you type `C-x C-f /glorp/baz.ugh <RET>',
643 visiting a file which (you know) happens to be rather large, and Emacs
644 prints out `I feel pretty today'. The best way to report the bug is
645 with a sentence like the preceding one, because it gives all the facts
646 and nothing but the facts.
648 Do not assume that the problem is due to the size of the file and
649 say, "When I visit a large file, Emacs prints out `I feel pretty
650 today'." This is what we mean by "guessing explanations". The problem
651 is just as likely to be due to the fact that there is a `z' in the file
652 name. If this is so, then when we got your report, we would try out
653 the problem with some "large file", probably with no `z' in its name,
654 and not find anything wrong. There is no way in the world that we
655 could guess that we should try visiting a file with a `z' in its name.
657 Alternatively, the problem might be due to the fact that the file
658 starts with exactly 25 spaces. For this reason, you should make sure
659 that you inform us of the exact contents of any file that is needed to
660 reproduce the bug. What if the problem only occurs when you have typed
661 the `C-x a l' command previously? This is why we ask you to give the
662 exact sequence of characters you typed since starting to use Emacs.
664 You should not even say "visit a file" instead of `C-x C-f' unless
665 you know that it makes no difference which visiting command is used.
666 Similarly, rather than saying "if I have three characters on the line,"
667 say "after I type `<RET> A B C <RET> C-p'," if that is the way you
670 If you are not in Fundamental mode when the problem occurs, you
671 should say what mode you are in.
673 If the manifestation of the bug is an Emacs error message, it is
674 important to report not just the text of the error message but a
675 backtrace showing how the Lisp program in Emacs arrived at the error.
676 To make the backtrace, you must execute the Lisp expression `(setq
677 debug-on-error t)' before the error happens (that is to say, you must
678 execute that expression and then make the bug happen). This causes the
679 Lisp debugger to run (*note Lisp Debug::). The debugger's backtrace
680 can be copied as text into the bug report. This use of the debugger is
681 possible only if you know how to make the bug happen again. Do note
682 the error message the first time the bug happens, so if you can't make
683 it happen again, you can report at least that.
685 Check whether any programs you have loaded into the Lisp world,
686 including your init file, set any variables that may affect the
687 functioning of Emacs. *Note Init File::. Also, see whether the
688 problem happens in a freshly started Emacs without loading your init
689 file (start Emacs with the `-q' switch to prevent loading the init
690 file). If the problem does NOT occur then, it is essential that we
691 know the contents of any programs that you must load into the Lisp
692 world in order to cause the problem to occur.
694 If the problem does depend on an init file or other Lisp programs
695 that are not part of the standard Emacs system, then you should make
696 sure it is not a bug in those programs by complaining to their
697 maintainers first. After they verify that they are using Emacs in a
698 way that is supposed to work, they should report the bug.
700 If you can tell us a way to cause the problem without visiting any
701 files, please do so. This makes it much easier to debug. If you do
702 need files, make sure you arrange for us to see their exact contents.
703 For example, it can often matter whether there are spaces at the ends
704 of lines, or a newline after the last line in the buffer (nothing ought
705 to care whether the last line is terminated, but tell that to the bugs).
707 The easy way to record the input to Emacs precisely is to write a
708 dribble file; execute the Lisp expression:
710 (open-dribble-file "~/dribble")
712 using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
713 Emacs. From then on, all Emacs input will be written in the specified
714 dribble file until the Emacs process is killed.
716 For possible display bugs, it is important to report the terminal
717 type (the value of environment variable `TERM'), the complete termcap
718 entry for the terminal from `/etc/termcap' (since that file is not
719 identical on all machines), and the output that Emacs actually sent to
720 the terminal. The way to collect this output is to execute the Lisp
723 (open-termscript "~/termscript")
725 using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
726 Emacs. From then on, all output from Emacs to the terminal will be
727 written in the specified termscript file as well, until the Emacs
728 process is killed. If the problem happens when Emacs starts up, put
729 this expression into your init file so that the termscript file will be
730 open when Emacs displays the screen for the first time. *Note Init
731 File::. Be warned: it is often difficult, and sometimes impossible, to
732 fix a terminal-dependent bug without access to a terminal of the type
733 that stimulates the bug.
735 The newsgroup `comp.emacs.xemacs' may be used for bug reports, other
736 discussions and requests for assistance.
738 If you don't have access to this newgroup, you can subscribe to the
739 mailing list version: the newsgroup is bidirectionally gatewayed into
740 the mailing list `xemacs@xemacs.org'.
742 To be added or removed from this mailing list, send mail to
743 `xemacs-request@xemacs.org'. Do not send requests for addition to the
746 The mailing lists and newsgroups are archived on our anonymous FTP
747 server, `ftp.xemacs.org', and at various other archive sites around the
748 net. You should also check the `FAQ' in `/pub/xemacs' on our anonymous
749 FTP server. It provides some introductory information and help for
750 initial configuration problems.