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: Faces, Next: Frame Components, Prev: Audible Bell, Up: Customization
38 XEmacs has objects called extents and faces. An "extent" is a
39 region of text and a "face" is a collection of textual attributes, such
40 as fonts and colors. Every extent is displayed in some face;
41 therefore, changing the properties of a face immediately updates the
42 display of all associated extents. Faces can be frame-local: you can
43 have a region of text that displays with completely different
44 attributes when its buffer is viewed from a different X window.
46 The display attributes of faces may be specified either in Lisp or
47 through the X resource manager.
52 You can change the face of an extent with the functions in this
53 section. All the functions prompt for a FACE as an argument; use
54 completion for a list of possible values.
57 Swap the foreground and background colors of the given FACE.
60 Make the font of the given FACE bold. When called from a program,
61 returns `nil' if this is not possible.
63 `M-x make-face-bold-italic'
64 Make the font of the given FACE bold italic. When called from a
65 program, returns `nil' if not possible.
67 `M-x make-face-italic'
68 Make the font of the given FACE italic. When called from a
69 program, returns `nil' if not possible.
71 `M-x make-face-unbold'
72 Make the font of the given FACE non-bold. When called from a
73 program, returns `nil' if not possible.
75 `M-x make-face-unitalic'
76 Make the font of the given FACE non-italic. When called from a
77 program, returns `nil' if not possible.
79 `M-x make-face-larger'
80 Make the font of the given FACE a little larger. When called from
81 a program, returns `nil' if not possible.
83 `M-x make-face-smaller'
84 Make the font of the given FACE a little smaller. When called
85 from a program, returns `nil' if not possible.
87 `M-x set-face-background'
88 Change the background color of the given FACE.
90 `M-x set-face-background-pixmap'
91 Change the background pixmap of the given FACE.
94 Change the font of the given FACE.
96 `M-x set-face-foreground'
97 Change the foreground color of the given FACE.
99 `M-x set-face-underline-p'
100 Change whether the given FACE is underlined.
102 You can exchange the foreground and background color of the selected
103 FACE with the function `invert-face'. If the face does not specify both
104 foreground and background, then its foreground and background are set
105 to the background and foreground of the default face. When calling
106 this from a program, you can supply the optional argument FRAME to
107 specify which frame is affected; otherwise, all frames are affected.
109 You can set the background color of the specified FACE with the
110 function `set-face-background'. The argument `color' should be a
111 string, the name of a color. When called from a program, if the
112 optional FRAME argument is provided, the face is changed only in that
113 frame; otherwise, it is changed in all frames.
115 You can set the background pixmap of the specified FACE with the
116 function `set-face-background-pixmap'. The pixmap argument NAME should
117 be a string, the name of a file of pixmap data. The directories listed
118 in the `x-bitmap-file-path' variable are searched. The bitmap may also
119 be a list of the form `(WIDTH HEIGHT DATA)', where WIDTH and HEIGHT are
120 the size in pixels, and DATA is a string containing the raw bits of the
121 bitmap. If the optional FRAME argument is provided, the face is
122 changed only in that frame; otherwise, it is changed in all frames.
124 The variable `x-bitmap-file-path' takes as a value a list of the
125 directories in which X bitmap files may be found. If the value is
126 `nil', the list is initialized from the `*bitmapFilePath' resource.
128 If the environment variable XBMLANGPATH is set, then it is consulted
129 before the `x-bitmap-file-path' variable.
131 You can set the font of the specified FACE with the function
132 `set-face-font'. The FONT argument should be a string, the name of a
133 font. When called from a program, if the optional FRAME argument is
134 provided, the face is changed only in that frame; otherwise, it is
135 changed in all frames.
137 You can set the foreground color of the specified FACE with the
138 function `set-face-foreground'. The argument COLOR should be a string,
139 the name of a color. If the optional FRAME argument is provided, the
140 face is changed only in that frame; otherwise, it is changed in all
143 You can set underline the specified FACE with the function
144 `set-face-underline-p'. The argument UNDERLINE-P can be used to make
145 underlining an attribute of the face or not. If the optional FRAME
146 argument is provided, the face is changed only in that frame;
147 otherwise, it is changed in all frames.
150 File: xemacs.info, Node: Frame Components, Next: X Resources, Prev: Faces, Up: Customization
155 You can control the presence and position of most frame components,
156 such as the menubar, toolbars, and gutters.
158 This section is not written yet. Try the Lisp Reference Manual:
159 *Note Menubar: (lispref)Menubar, *Note Toolbar Intro: (lispref)Toolbar
160 Intro, and *Note Gutter Intro: (lispref)Gutter Intro.
163 File: xemacs.info, Node: X Resources, Prev: Frame Components, Up: Customization
168 Historically, XEmacs has used the X resource application class
169 `Emacs' for its resources. Unfortunately, GNU Emacs uses the same
170 application class, and resources are not compatible between the two
171 Emacsen. This sharing of the application class often leads to trouble
172 if you want to run both variants.
174 Starting with XEmacs 21, XEmacs uses the class `XEmacs' if it finds
175 any XEmacs resources in the resource database when the X connection is
176 initialized. Otherwise, it will use the class `Emacs' for backwards
177 compatibility. The variable X-EMACS-APPLICATION-CLASS may be consulted
178 to determine the application class being used.
180 The examples in this section assume the application class is `Emacs'.
182 The Emacs resources are generally set per-frame. Each Emacs frame
183 can have its own name or the same name as another, depending on the
184 name passed to the `make-frame' function.
186 You can specify resources for all frames with the syntax:
188 Emacs*parameter: value
192 Emacs*EmacsFrame.parameter:value
194 You can specify resources for a particular frame with the syntax:
196 Emacs*FRAME-NAME.parameter: value
200 * Geometry Resources:: Controlling the size and position of frames.
201 * Iconic Resources:: Controlling whether frames come up iconic.
202 * Resource List:: List of resources settable on a frame or device.
203 * Face Resources:: Controlling faces using resources.
204 * Widgets:: The widget hierarchy for XEmacs.
205 * Menubar Resources:: Specifying resources for the menubar.
208 File: xemacs.info, Node: Geometry Resources, Next: Iconic Resources, Up: X Resources
213 To make the default size of all Emacs frames be 80 columns by 55
216 Emacs*EmacsFrame.geometry: 80x55
218 To set the geometry of a particular frame named `fred', do this:
220 Emacs*fred.geometry: 80x55
222 Important! Do not use the following syntax:
224 Emacs*geometry: 80x55
226 You should never use `*geometry' with any X application. It does not
227 say "make the geometry of Emacs be 80 columns by 55 lines." It really
228 says, "make Emacs and all subwindows thereof be 80x55 in whatever units
229 they care to measure in." In particular, that is both telling the
230 Emacs text pane to be 80x55 in characters, and telling the menubar pane
231 to be 80x55 pixels, which is surely not what you want.
233 As a special case, this geometry specification also works (and sets
234 the default size of all Emacs frames to 80 columns by 55 lines):
236 Emacs.geometry: 80x55
238 since that is the syntax used with most other applications (since most
239 other applications have only one top-level window, unlike Emacs). In
240 general, however, the top-level shell (the unmapped ApplicationShell
241 widget named `Emacs' that is the parent of the shell widgets that
242 actually manage the individual frames) does not have any interesting
243 resources on it, and you should set the resources on the frames instead.
245 The `-geometry' command-line argument sets only the geometry of the
246 initial frame created by Emacs.
248 A more complete explanation of geometry-handling is
250 * The `-geometry' command-line option sets the `Emacs.geometry'
251 resource, that is, the geometry of the ApplicationShell.
253 * For the first frame created, the size of the frame is taken from
254 the ApplicationShell if it is specified, otherwise from the
255 geometry of the frame.
257 * For subsequent frames, the order is reversed: First the frame, and
258 then the ApplicationShell.
260 * For the first frame created, the position of the frame is taken
261 from the ApplicationShell (`Emacs.geometry') if it is specified,
262 otherwise from the geometry of the frame.
264 * For subsequent frames, the position is taken only from the frame,
265 and never from the ApplicationShell.
267 This is rather complicated, but it does seem to provide the most
268 intuitive behavior with respect to the default sizes and positions of
269 frames created in various ways.
272 File: xemacs.info, Node: Iconic Resources, Next: Resource List, Prev: Geometry Resources, Up: X Resources
277 Analogous to `-geometry', the `-iconic' command-line option sets the
278 iconic flag of the ApplicationShell (`Emacs.iconic') and always applies
279 to the first frame created regardless of its name. However, it is
280 possible to set the iconic flag on particular frames (by name) by using
281 the `Emacs*FRAME-NAME.iconic' resource.
284 File: xemacs.info, Node: Resource List, Next: Face Resources, Prev: Iconic Resources, Up: X Resources
289 Emacs frames accept the following resources:
291 `geometry' (class `Geometry'): string
292 Initial geometry for the frame. *Note Geometry Resources::, for a
293 complete discussion of how this works.
295 `iconic' (class `Iconic'): boolean
296 Whether this frame should appear in the iconified state.
298 `internalBorderWidth' (class `InternalBorderWidth'): int
299 How many blank pixels to leave between the text and the edge of the
302 `interline' (class `Interline'): int
303 How many pixels to leave between each line (may not be
306 `menubar' (class `Menubar'): boolean
307 Whether newly-created frames should initially have a menubar. Set
310 `initiallyUnmapped' (class `InitiallyUnmapped'): boolean
311 Whether XEmacs should leave the initial frame unmapped when it
312 starts up. This is useful if you are starting XEmacs as a server
313 (e.g. in conjunction with gnuserv or the external client widget).
314 You can also control this with the `-unmapped' command-line option.
316 `barCursor' (class `BarColor'): boolean
317 Whether the cursor should be displayed as a bar, or the
320 `cursorColor' (class `CursorColor'): color-name
321 The color of the text cursor.
323 `scrollBarWidth' (class `ScrollBarWidth'): integer
324 How wide the vertical scrollbars should be, in pixels; 0 means no
325 vertical scrollbars. You can also use a resource specification of
326 the form `*scrollbar.width', or the usual toolkit scrollbar
327 resources: `*XmScrollBar.width' (Motif), `*XlwScrollBar.width'
328 (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend
329 that you use the toolkit resources, though, because they're
330 dependent on how exactly your particular build of XEmacs was
333 `scrollBarHeight' (class `ScrollBarHeight'): integer
334 How high the horizontal scrollbars should be, in pixels; 0 means no
335 horizontal scrollbars. You can also use a resource specification
336 of the form `*scrollbar.height', or the usual toolkit scrollbar
337 resources: `*XmScrollBar.height' (Motif), `*XlwScrollBar.height'
338 (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend
339 that you use the toolkit resources, though, because they're
340 dependent on how exactly your particular build of XEmacs was
343 `scrollBarPlacement' (class `ScrollBarPlacement'): string
344 Where the horizontal and vertical scrollbars should be positioned.
345 This should be one of the four strings `BOTTOM_LEFT',
346 `BOTTOM_RIGHT', `TOP_LEFT', and `TOP_RIGHT'. Default is
347 `BOTTOM_RIGHT' for the Motif and Lucid scrollbars and
348 `BOTTOM_LEFT' for the Athena scrollbars.
350 `topToolBarHeight' (class `TopToolBarHeight'): integer
351 `bottomToolBarHeight' (class `BottomToolBarHeight'): integer
352 `leftToolBarWidth' (class `LeftToolBarWidth'): integer
353 `rightToolBarWidth' (class `RightToolBarWidth'): integer
354 Height and width of the four possible toolbars.
356 `topToolBarShadowColor' (class `TopToolBarShadowColor'): color-name
357 `bottomToolBarShadowColor' (class `BottomToolBarShadowColor'): color-name
358 Color of the top and bottom shadows for the toolbars. NOTE: These
359 resources do _not_ have anything to do with the top and bottom
360 toolbars (i.e. the toolbars at the top and bottom of the frame)!
361 Rather, they affect the top and bottom shadows around the edges of
362 all four kinds of toolbars.
364 `topToolBarShadowPixmap' (class `TopToolBarShadowPixmap'): pixmap-name
365 `bottomToolBarShadowPixmap' (class `BottomToolBarShadowPixmap'): pixmap-name
366 Pixmap of the top and bottom shadows for the toolbars. If set,
367 these resources override the corresponding color resources. NOTE:
368 These resources do _not_ have anything to do with the top and
369 bottom toolbars (i.e. the toolbars at the top and bottom of the
370 frame)! Rather, they affect the top and bottom shadows around the
371 edges of all four kinds of toolbars.
373 `toolBarShadowThickness' (class `ToolBarShadowThickness'): integer
374 Thickness of the shadows around the toolbars, in pixels.
376 `visualBell' (class `VisualBell'): boolean
377 Whether XEmacs should flash the screen rather than making an
380 `bellVolume' (class `BellVolume'): integer
381 Volume of the audible beep.
383 `useBackingStore' (class `UseBackingStore'): boolean
384 Whether XEmacs should set the backing-store attribute of the X
385 windows it creates. This increases the memory usage of the X
386 server but decreases the amount of X traffic necessary to update
387 the screen, and is useful when the connection to the X server goes
388 over a low-bandwidth line such as a modem connection.
390 Emacs devices accept the following resources:
392 `textPointer' (class `Cursor'): cursor-name
393 The cursor to use when the mouse is over text. This resource is
394 used to initialize the variable `x-pointer-shape'.
396 `selectionPointer' (class `Cursor'): cursor-name
397 The cursor to use when the mouse is over a selectable text region
398 (an extent with the `highlight' property; for example, an Info
399 cross-reference). This resource is used to initialize the variable
400 `x-selection-pointer-shape'.
402 `spacePointer' (class `Cursor'): cursor-name
403 The cursor to use when the mouse is over a blank space in a buffer
404 (that is, after the end of a line or after the end-of-file). This
405 resource is used to initialize the variable
406 `x-nontext-pointer-shape'.
408 `modeLinePointer' (class `Cursor'): cursor-name
409 The cursor to use when the mouse is over a modeline. This
410 resource is used to initialize the variable `x-mode-pointer-shape'.
412 `gcPointer' (class `Cursor'): cursor-name
413 The cursor to display when a garbage-collection is in progress.
414 This resource is used to initialize the variable
415 `x-gc-pointer-shape'.
417 `scrollbarPointer' (class `Cursor'): cursor-name
418 The cursor to use when the mouse is over the scrollbar. This
419 resource is used to initialize the variable
420 `x-scrollbar-pointer-shape'.
422 `pointerColor' (class `Foreground'): color-name
423 `pointerBackground' (class `Background'): color-name
424 The foreground and background colors of the mouse cursor. These
425 resources are used to initialize the variables
426 `x-pointer-foreground-color' and `x-pointer-background-color'.
429 File: xemacs.info, Node: Face Resources, Next: Widgets, Prev: Resource List, Up: X Resources
434 The attributes of faces are also per-frame. They can be specified as:
436 Emacs.FACE_NAME.parameter: value
440 Emacs*FRAME_NAME.FACE_NAME.parameter: value
442 Faces accept the following resources:
444 `attributeFont' (class `AttributeFont'): font-name
445 The font of this face.
447 `attributeForeground' (class `AttributeForeground'): color-name
448 `attributeBackground' (class `AttributeBackground'): color-name
449 The foreground and background colors of this face.
451 `attributeBackgroundPixmap' (class `AttributeBackgroundPixmap'): file-name
452 The name of an XBM file (or XPM file, if your version of Emacs
453 supports XPM), to use as a background stipple.
455 `attributeUnderline' (class `AttributeUnderline'): boolean
456 Whether text in this face should be underlined.
458 All text is displayed in some face, defaulting to the face named
459 `default'. To set the font of normal text, use
460 `Emacs*default.attributeFont'. To set it in the frame named `fred', use
461 `Emacs*fred.default.attributeFont'.
463 These are the names of the predefined faces:
466 Everything inherits from this.
469 If this is not specified in the resource database, Emacs tries to
470 find a bold version of the font of the default face.
473 If this is not specified in the resource database, Emacs tries to
474 find an italic version of the font of the default face.
477 If this is not specified in the resource database, Emacs tries to
478 find a bold-italic version of the font of the default face.
481 This is the face that the modeline is displayed in. If not
482 specified in the resource database, it is determined from the
483 default face by reversing the foreground and background colors.
486 This is the face that highlighted extents (for example, Info
487 cross-references and possible completions, when the mouse passes
488 over them) are displayed in.
492 These are the faces that the left and right annotation margins are
496 This is the face that mouse selections are displayed in.
499 This is the face that the matched text being searched for is
503 This is the face of info menu items. If unspecified, it is copied
507 This is the face of info cross-references. If unspecified, it is
508 copied from `bold'. (Note that, when the mouse passes over a
509 cross-reference, the cross-reference's face is determined from a
510 combination of the `info-xref' and `highlight' faces.)
512 Other packages might define their own faces; to see a list of all
513 faces, use any of the interactive face-manipulation commands such as
514 `set-face-font' and type `?' when you are prompted for the name of a
517 If the `bold', `italic', and `bold-italic' faces are not specified
518 in the resource database, then XEmacs attempts to derive them from the
519 font of the default face. It can only succeed at this if you have
520 specified the default font using the XLFD (X Logical Font Description)
521 format, which looks like
523 *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
525 If you use any of the other, less strict font name formats, some of
528 lucidasanstypewriter-12
532 then XEmacs won't be able to guess the names of the bold and italic
533 versions. All X fonts can be referred to via XLFD-style names, so you
534 should use those forms. See the man pages for `X(1)', `xlsfonts(1)',
538 File: xemacs.info, Node: Widgets, Next: Menubar Resources, Prev: Face Resources, Up: X Resources
543 There are several structural widgets between the terminal EmacsFrame
544 widget and the top level ApplicationShell; the exact names and types of
545 these widgets change from release to release (for example, they changed
546 between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are
547 subject to further change in the future, so you should avoid mentioning
548 them in your resource database. The above-mentioned syntaxes should be
549 forward- compatible. As of 19.13, the exact widget hierarchy is as
552 INVOCATION-NAME "shell" "container" FRAME-NAME
553 x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame"
555 where INVOCATION-NAME is the terminal component of the name of the
556 XEmacs executable (usually `xemacs'), and `x-emacs-application-class'
557 is generally `Emacs'.
560 File: xemacs.info, Node: Menubar Resources, Prev: Widgets, Up: X Resources
565 As the menubar is implemented as a widget which is not a part of
566 XEmacs proper, it does not use the face mechanism for specifying fonts
567 and colors: It uses whatever resources are appropriate to the type of
568 widget which is used to implement it.
570 If Emacs was compiled to use only the Lucid Motif-lookalike menu
571 widgets, then one way to specify the font of the menubar would be
573 Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
575 If both the Lucid Motif-lookalike menu widgets and X Font Sets are
576 configured to allow multilingual menubars, then one uses
578 *menubar*FontSet: -*-helvetica-bold-r-*-*-*-120-*-*-*-*-iso8859-*, \
579 -*-*-*-*-*-*-*-120-*-jisx0208.1983-0
581 That would specify fonts for a Japanese menubar. Specifying only one
582 XLFD is acceptable; specifying more than one for a given registry
583 (language) is also allowed. When X Font Sets are configured, some .font
584 resources (eg, menubars) are ignored in favor of the corresponding
587 If the Motif library is being used, then one would have to use
589 Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
591 because the Motif library uses the `fontList' resource name instead
592 of `font', which has subtly different semantics.
594 The same is true of the scrollbars: They accept whichever resources
595 are appropriate for the toolkit in use.
598 File: xemacs.info, Node: Quitting, Next: Lossage, Prev: Customization, Up: Top
600 Quitting and Aborting
601 =====================
604 Quit. Cancel running or partially typed command.
607 Abort innermost recursive editing level and cancel the command
608 which invoked it (`abort-recursive-edit').
611 Abort all recursive editing levels that are currently executing.
614 Cancel an already-executed command, usually (`undo').
616 There are two ways of cancelling commands which are not finished
617 executing: "quitting" with `C-g', and "aborting" with `C-]' or `M-x
618 top-level'. Quitting is cancelling a partially typed command or one
619 which is already running. Aborting is getting out of a recursive
620 editing level and cancelling the command that invoked the recursive
623 Quitting with `C-g' is used for getting rid of a partially typed
624 command or a numeric argument that you don't want. It also stops a
625 running command in the middle in a relatively safe way, so you can use
626 it if you accidentally start executing a command that takes a long
627 time. In particular, it is safe to quit out of killing; either your
628 text will ALL still be there, or it will ALL be in the kill ring (or
629 maybe both). Quitting an incremental search does special things
630 documented under searching; in general, it may take two successive
631 `C-g' characters to get out of a search. `C-g' works by setting the
632 variable `quit-flag' to `t' the instant `C-g' is typed; Emacs Lisp
633 checks this variable frequently and quits if it is non-`nil'. `C-g' is
634 only actually executed as a command if it is typed while Emacs is
637 If you quit twice in a row before the first `C-g' is recognized, you
638 activate the "emergency escape" feature and return to the shell. *Note
641 You can use `C-]' (`abort-recursive-edit') to get out of a recursive
642 editing level and cancel the command which invoked it. Quitting with
643 `C-g' does not do this, and could not do this because it is used to
644 cancel a partially typed command within the recursive editing level.
645 Both operations are useful. For example, if you are in the Emacs
646 debugger (*note Lisp Debug::) and have typed `C-u 8' to enter a numeric
647 argument, you can cancel that argument with `C-g' and remain in the
650 The command `M-x top-level' is equivalent to "enough" `C-]' commands
651 to get you out of all the levels of recursive edits that you are in.
652 `C-]' only gets you out one level at a time, but `M-x top-level' goes
653 out all levels at once. Both `C-]' and `M-x top-level' are like all
654 other commands and unlike `C-g' in that they are effective only when
655 Emacs is ready for a command. `C-]' is an ordinary key and has its
656 meaning only because of its binding in the keymap. *Note Recursive
659 `C-x u' (`undo') is not strictly speaking a way of cancelling a
660 command, but you can think of it as cancelling a command already
661 finished executing. *Note Undo::.
664 File: xemacs.info, Node: Lossage, Next: Bugs, Prev: Quitting, Up: Top
666 Dealing With Emacs Trouble
667 ==========================
669 This section describes various conditions in which Emacs fails to
670 work, and how to recognize them and correct them.
674 * Stuck Recursive:: `[...]' in mode line around the parentheses.
675 * Screen Garbled:: Garbage on the screen.
676 * Text Garbled:: Garbage in the text.
677 * Unasked-for Search:: Spontaneous entry to incremental search.
678 * Emergency Escape:: Emergency escape---
679 What to do if Emacs stops responding.
680 * Total Frustration:: When you are at your wits' end.
683 File: xemacs.info, Node: Stuck Recursive, Next: Screen Garbled, Prev: Lossage, Up: Lossage
685 Recursive Editing Levels
686 ------------------------
688 Recursive editing levels are important and useful features of Emacs,
689 but they can seem like malfunctions to the user who does not understand
692 If the mode line has square brackets `[...]' around the parentheses
693 that contain the names of the major and minor modes, you have entered a
694 recursive editing level. If you did not do this on purpose, or if you
695 don't understand what that means, you should just get out of the
696 recursive editing level. To do so, type `M-x top-level'. This is
697 called getting back to top level. *Note Recursive Edit::.
700 File: xemacs.info, Node: Screen Garbled, Next: Text Garbled, Prev: Stuck Recursive, Up: Lossage
702 Garbage on the Screen
703 ---------------------
705 If the data on the screen looks wrong, the first thing to do is see
706 whether the text is actually wrong. Type `C-l', to redisplay the
707 entire screen. If the text appears correct after this, the problem was
708 entirely in the previous screen update.
710 Display updating problems often result from an incorrect termcap
711 entry for the terminal you are using. The file `etc/TERMS' in the Emacs
712 distribution gives the fixes for known problems of this sort.
713 `INSTALL' contains general advice for these problems in one of its
714 sections. Very likely there is simply insufficient padding for certain
715 display operations. To investigate the possibility that you have this
716 sort of problem, try Emacs on another terminal made by a different
717 manufacturer. If problems happen frequently on one kind of terminal but
718 not another kind, the real problem is likely to be a bad termcap entry,
719 though it could also be due to a bug in Emacs that appears for terminals
720 that have or lack specific features.
723 File: xemacs.info, Node: Text Garbled, Next: Unasked-for Search, Prev: Screen Garbled, Up: Lossage
728 If `C-l' shows that the text is wrong, try undoing the changes to it
729 using `C-x u' until it gets back to a state you consider correct. Also
730 try `C-h l' to find out what command you typed to produce the observed
733 If a large portion of text appears to be missing at the beginning or
734 end of the buffer, check for the word `Narrow' in the mode line. If it
735 appears, the text is still present, but marked off-limits. To make it
736 visible again, type `C-x n w'. *Note Narrowing::.
739 File: xemacs.info, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage
741 Spontaneous Entry to Incremental Search
742 ---------------------------------------
744 If Emacs spontaneously displays `I-search:' at the bottom of the
745 screen, it means that the terminal is sending `C-s' and `C-q' according
746 to the poorly designed xon/xoff "flow control" protocol. You should
747 try to prevent this by putting the terminal in a mode where it will not
748 use flow control, or by giving it enough padding that it will never
749 send a `C-s'. If that cannot be done, you must tell Emacs to expect
750 flow control to be used, until you can get a properly designed terminal.
752 Information on how to do these things can be found in the file
753 `INSTALL' in the Emacs distribution.
756 File: xemacs.info, Node: Emergency Escape, Next: Total Frustration, Prev: Unasked-for Search, Up: Lossage
761 Because at times there have been bugs causing Emacs to loop without
762 checking `quit-flag', a special feature causes Emacs to be suspended
763 immediately if you type a second `C-g' while the flag is already set,
764 so you can always get out of XEmacs. Normally Emacs recognizes and
765 clears `quit-flag' (and quits!) quickly enough to prevent this from
768 When you resume Emacs after a suspension caused by multiple `C-g', it
769 asks two questions before going back to what it had been doing:
772 Abort (and dump core)? (y or n)
774 Answer each one with `y' or `n' followed by <RET>.
776 Saying `y' to `Auto-save?' causes immediate auto-saving of all
777 modified buffers in which auto-saving is enabled.
779 Saying `y' to `Abort (and dump core)?' causes an illegal instruction
780 to be executed, dumping core. This is to enable a wizard to figure out
781 why Emacs was failing to quit in the first place. Execution does not
782 continue after a core dump. If you answer `n', execution does
783 continue. With luck, Emacs will ultimately check `quit-flag' and quit
784 normally. If not, and you type another `C-g', it is suspended again.
786 If Emacs is not really hung, but is just being slow, you may invoke
787 the double `C-g' feature without really meaning to. In that case,
788 simply resume and answer `n' to both questions, and you will arrive at
789 your former state. Presumably the quit you requested will happen soon.
791 The double-`C-g' feature may be turned off when Emacs is running
792 under a window system, since the window system always enables you to
793 kill Emacs or to create another window and run another program.
796 File: xemacs.info, Node: Total Frustration, Prev: Emergency Escape, Up: Lossage
798 Help for Total Frustration
799 --------------------------
801 If using Emacs (or something else) becomes terribly frustrating and
802 none of the techniques described above solve the problem, Emacs can
805 First, if the Emacs you are using is not responding to commands, type
806 `C-g C-g' to get out of it and then start a new one.
808 Second, type `M-x doctor <RET>'.
810 The doctor will make you feel better. Each time you say something to
811 the doctor, you must end it by typing <RET> <RET>. This lets the
812 doctor know you are finished.
815 File: xemacs.info, Node: Bugs, Prev: Lossage, Up: Top
820 Sometimes you will encounter a bug in Emacs. Although we cannot
821 promise we can or will fix the bug, and we might not even agree that it
822 is a bug, we want to hear about bugs you encounter in case we do want
825 To make it possible for us to fix a bug, you must report it. In
826 order to do so effectively, you must know when and how to do it.
831 If Emacs executes an illegal instruction, or dies with an operating
832 system error message that indicates a problem in the program (as
833 opposed to something like "disk full"), then it is certainly a bug.
835 If Emacs updates the display in a way that does not correspond to
836 what is in the buffer, then it is certainly a bug. If a command seems
837 to do the wrong thing but the problem corrects itself if you type
838 `C-l', it is a case of incorrect display updating.
840 Taking forever to complete a command can be a bug, but you must make
841 certain that it was really Emacs's fault. Some commands simply take a
842 long time. Type `C-g' and then `C-h l' to see whether the input Emacs
843 received was what you intended to type; if the input was such that you
844 KNOW it should have been processed quickly, report a bug. If you don't
845 know whether the command should take a long time, find out by looking
846 in the manual or by asking for assistance.
848 If a command you are familiar with causes an Emacs error message in a
849 case where its usual definition ought to be reasonable, it is probably a
852 If a command does the wrong thing, that is a bug. But be sure you
853 know for certain what it ought to have done. If you aren't familiar
854 with the command, or don't know for certain how the command is supposed
855 to work, then it might actually be working right. Rather than jumping
856 to conclusions, show the problem to someone who knows for certain.
858 Finally, a command's intended definition may not be best for editing
859 with. This is a very important sort of problem, but it is also a
860 matter of judgment. Also, it is easy to come to such a conclusion out
861 of ignorance of some of the existing features. It is probably best not
862 to complain about such a problem until you have checked the
863 documentation in the usual ways, feel confident that you understand it,
864 and know for certain that what you want is not available. If you are
865 not sure what the command is supposed to do after a careful reading of
866 the manual, check the index and glossary for any terms that may be
867 unclear. If you still do not understand, this indicates a bug in the
868 manual. The manual's job is to make everything clear. It is just as
869 important to report documentation bugs as program bugs.
871 If the online documentation string of a function or variable
872 disagrees with the manual, one of them must be wrong, so report the bug.
877 When you decide that there is a bug, it is important to report it
878 and to report it in a way which is useful. What is most useful is an
879 exact description of what commands you type, starting with the shell
880 command to run Emacs, until the problem happens. Always include the
881 version number of Emacs that you are using; type `M-x emacs-version' to
884 The most important principle in reporting a bug is to report FACTS,
885 not hypotheses or categorizations. It is always easier to report the
886 facts, but people seem to prefer to strain to posit explanations and
887 report them instead. If the explanations are based on guesses about
888 how Emacs is implemented, they will be useless; we will have to try to
889 figure out what the facts must have been to lead to such speculations.
890 Sometimes this is impossible. But in any case, it is unnecessary work
893 For example, suppose that you type `C-x C-f /glorp/baz.ugh <RET>',
894 visiting a file which (you know) happens to be rather large, and Emacs
895 prints out `I feel pretty today'. The best way to report the bug is
896 with a sentence like the preceding one, because it gives all the facts
897 and nothing but the facts.
899 Do not assume that the problem is due to the size of the file and
900 say, "When I visit a large file, Emacs prints out `I feel pretty
901 today'." This is what we mean by "guessing explanations". The problem
902 is just as likely to be due to the fact that there is a `z' in the file
903 name. If this is so, then when we got your report, we would try out
904 the problem with some "large file", probably with no `z' in its name,
905 and not find anything wrong. There is no way in the world that we
906 could guess that we should try visiting a file with a `z' in its name.
908 Alternatively, the problem might be due to the fact that the file
909 starts with exactly 25 spaces. For this reason, you should make sure
910 that you inform us of the exact contents of any file that is needed to
911 reproduce the bug. What if the problem only occurs when you have typed
912 the `C-x a l' command previously? This is why we ask you to give the
913 exact sequence of characters you typed since starting to use Emacs.
915 You should not even say "visit a file" instead of `C-x C-f' unless
916 you know that it makes no difference which visiting command is used.
917 Similarly, rather than saying "if I have three characters on the line,"
918 say "after I type `<RET> A B C <RET> C-p'," if that is the way you
921 If you are not in Fundamental mode when the problem occurs, you
922 should say what mode you are in.
924 If the manifestation of the bug is an Emacs error message, it is
925 important to report not just the text of the error message but a
926 backtrace showing how the Lisp program in Emacs arrived at the error.
927 To make the backtrace, you must execute the Lisp expression `(setq
928 debug-on-error t)' before the error happens (that is to say, you must
929 execute that expression and then make the bug happen). This causes the
930 Lisp debugger to run (*note Lisp Debug::). The debugger's backtrace
931 can be copied as text into the bug report. This use of the debugger is
932 possible only if you know how to make the bug happen again. Do note
933 the error message the first time the bug happens, so if you can't make
934 it happen again, you can report at least that.
936 Check whether any programs you have loaded into the Lisp world,
937 including your init file, set any variables that may affect the
938 functioning of Emacs. *Note Init File::. Also, see whether the
939 problem happens in a freshly started Emacs without loading your init
940 file (start Emacs with the `-q' switch to prevent loading the init
941 file). If the problem does NOT occur then, it is essential that we
942 know the contents of any programs that you must load into the Lisp
943 world in order to cause the problem to occur.
945 If the problem does depend on an init file or other Lisp programs
946 that are not part of the standard Emacs system, then you should make
947 sure it is not a bug in those programs by complaining to their
948 maintainers first. After they verify that they are using Emacs in a
949 way that is supposed to work, they should report the bug.
951 If you can tell us a way to cause the problem without visiting any
952 files, please do so. This makes it much easier to debug. If you do
953 need files, make sure you arrange for us to see their exact contents.
954 For example, it can often matter whether there are spaces at the ends
955 of lines, or a newline after the last line in the buffer (nothing ought
956 to care whether the last line is terminated, but tell that to the bugs).
958 The easy way to record the input to Emacs precisely is to write a
959 dribble file; execute the Lisp expression:
961 (open-dribble-file "~/dribble")
963 using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
964 Emacs. From then on, all Emacs input will be written in the specified
965 dribble file until the Emacs process is killed.
967 For possible display bugs, it is important to report the terminal
968 type (the value of environment variable `TERM'), the complete termcap
969 entry for the terminal from `/etc/termcap' (since that file is not
970 identical on all machines), and the output that Emacs actually sent to
971 the terminal. The way to collect this output is to execute the Lisp
974 (open-termscript "~/termscript")
976 using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
977 Emacs. From then on, all output from Emacs to the terminal will be
978 written in the specified termscript file as well, until the Emacs
979 process is killed. If the problem happens when Emacs starts up, put
980 this expression into your init file so that the termscript file will be
981 open when Emacs displays the screen for the first time. *Note Init
982 File::. Be warned: it is often difficult, and sometimes impossible, to
983 fix a terminal-dependent bug without access to a terminal of the type
984 that stimulates the bug.
986 The newsgroup `comp.emacs.xemacs' may be used for bug reports, other
987 discussions and requests for assistance.
989 If you don't have access to this newgroup, you can subscribe to the
990 mailing list version: the newsgroup is bidirectionally gatewayed into
991 the mailing list `xemacs@xemacs.org'.
993 To be added or removed from this mailing list, send mail to
994 `xemacs-request@xemacs.org'. Do not send requests for addition to the
997 The mailing lists and newsgroups are archived on our anonymous FTP
998 server, `ftp.xemacs.org', and at various other archive sites around the
999 net. You should also check the `FAQ' in `/pub/xemacs' on our anonymous
1000 FTP server. It provides some introductory information and help for
1001 initial configuration problems.