info/xemacs.info-18

   1 This is ../info/xemacs.info, produced by makeinfo version 4.0 from
   2 xemacs/xemacs.texi.
   3
   4 INFO-DIR-SECTION XEmacs Editor
   5 START-INFO-DIR-ENTRY
   6 * XEmacs: (xemacs).             XEmacs Editor.
   7 END-INFO-DIR-ENTRY
   8
   9    This file documents the XEmacs editor.
  10
  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.
  14
  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.
  18
  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.
  25
  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.
  31
  32 \1f
  33 File: xemacs.info,  Node: Resource List,  Next: Face Resources,  Prev: Iconic Resources,  Up: X Resources
  34
  35 Resource List
  36 -------------
  37
  38    Emacs frames accept the following resources:
  39
  40 `geometry' (class `Geometry'): string
  41      Initial geometry for the frame.  *Note Geometry Resources::, for a
  42      complete discussion of how this works.
  43
  44 `iconic' (class `Iconic'): boolean
  45      Whether this frame should appear in the iconified state.
  46
  47 `internalBorderWidth' (class `InternalBorderWidth'): int
  48      How many blank pixels to leave between the text and the edge of the
  49      window.
  50
  51 `interline' (class `Interline'): int
  52      How many pixels to leave between each line (may not be
  53      implemented).
  54
  55 `menubar' (class `Menubar'): boolean
  56      Whether newly-created frames should initially have a menubar.  Set
  57      to true by default.
  58
  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.
  64
  65 `barCursor' (class `BarColor'): boolean
  66      Whether the cursor should be displayed as a bar, or the
  67      traditional box.
  68
  69 `cursorColor' (class `CursorColor'): color-name
  70      The color of the text cursor.
  71
  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
  80      configured.
  81
  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
  90      configured.
  91
  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.
  98
  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.
 104
 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.
 112
 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.
 121
 122 `toolBarShadowThickness' (class `ToolBarShadowThickness'): integer
 123      Thickness of the shadows around the toolbars, in pixels.
 124
 125 `visualBell' (class `VisualBell'): boolean
 126      Whether XEmacs should flash the screen rather than making an
 127      audible beep.
 128
 129 `bellVolume' (class `BellVolume'): integer
 130      Volume of the audible beep.
 131
 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.
 138
 139    Emacs devices accept the following resources:
 140
 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'.
 144
 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'.
 150
 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'.
 156
 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'.
 160
 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'.
 165
 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'.
 170
 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'.
 176
 177 \1f
 178 File: xemacs.info,  Node: Face Resources,  Next: Widgets,  Prev: Resource List,  Up: X Resources
 179
 180 Face Resources
 181 --------------
 182
 183    The attributes of faces are also per-frame. They can be specified as:
 184
 185      Emacs.FACE_NAME.parameter: value
 186
 187 or
 188
 189      Emacs*FRAME_NAME.FACE_NAME.parameter: value
 190
 191 Faces accept the following resources:
 192
 193 `attributeFont' (class `AttributeFont'): font-name
 194      The font of this face.
 195
 196 `attributeForeground' (class `AttributeForeground'): color-name
 197 `attributeBackground' (class `AttributeBackground'): color-name
 198      The foreground and background colors of this face.
 199
 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.
 203
 204 `attributeUnderline' (class `AttributeUnderline'): boolean
 205      Whether text in this face should be underlined.
 206
 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'.
 211
 212    These are the names of the predefined faces:
 213
 214 `default'
 215      Everything inherits from this.
 216
 217 `bold'
 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.
 220
 221 `italic'
 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.
 224
 225 `bold-italic'
 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.
 228
 229 `modeline'
 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.
 233
 234 `highlight'
 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.
 238
 239 `left-margin'
 240 `right-margin'
 241      These are the faces that the left and right annotation margins are
 242      displayed in.
 243
 244 `zmacs-region'
 245      This is the face that mouse selections are displayed in.
 246
 247 `isearch'
 248      This is the face that the matched text being searched for is
 249      displayed in.
 250
 251 `info-node'
 252      This is the face of info menu items.  If unspecified, it is copied
 253      from `bold-italic'.
 254
 255 `info-xref'
 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.)
 260
 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
 264 face.
 265
 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
 271
 272      *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
 273
 274 If you use any of the other, less strict font name formats, some of
 275 which look like
 276
 277      lucidasanstypewriter-12
 278      fixed
 279      9x13
 280
 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)',
 284 and `xfontsel(1)'.
 285
 286 \1f
 287 File: xemacs.info,  Node: Widgets,  Next: Menubar Resources,  Prev: Face Resources,  Up: X Resources
 288
 289 Widgets
 290 -------
 291
 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
 299 follows:
 300
 301      INVOCATION-NAME            "shell"       "container"     FRAME-NAME
 302      x-emacs-application-class  "EmacsShell"  "EmacsManager"  "EmacsFrame"
 303
 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'.
 307
 308 \1f
 309 File: xemacs.info,  Node: Menubar Resources,  Prev: Widgets,  Up: X Resources
 310
 311 Menubar Resources
 312 -----------------
 313
 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.
 318
 319    If Emacs was compiled to use only the Motif-lookalike menu widgets,
 320 then one way to specify the font of the menubar would be
 321
 322      Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
 323
 324    If the Motif library is being used, then one would have to use
 325
 326      Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
 327
 328    because the Motif library uses the `fontList' resource name instead
 329 of `font', which has subtly different semantics.
 330
 331    The same is true of the scrollbars: They accept whichever resources
 332 are appropriate for the toolkit in use.
 333
 334 \1f
 335 File: xemacs.info,  Node: Quitting,  Next: Lossage,  Prev: Customization,  Up: Top
 336
 337 Quitting and Aborting
 338 =====================
 339
 340 `C-g'
 341      Quit.  Cancel running or partially typed command.
 342
 343 `C-]'
 344      Abort innermost recursive editing level and cancel the command
 345      which invoked it (`abort-recursive-edit').
 346
 347 `M-x top-level'
 348      Abort all recursive editing levels that are currently executing.
 349
 350 `C-x u'
 351      Cancel an already-executed command, usually (`undo').
 352
 353    There are two ways of cancelling commands which are not finished
 354 executing: "quitting" with `C-g', and "aborting" with `C-]' or `M-x
 355 top-level'.  Quitting is cancelling a partially typed command or one
 356 which is already running.  Aborting is getting out of a recursive
 357 editing level and cancelling the command that invoked the recursive
 358 edit.
 359
 360    Quitting with `C-g' is used for getting rid of a partially typed
 361 command or a numeric argument that you don't want.  It also stops a
 362 running command in the middle in a relatively safe way, so you can use
 363 it if you accidentally start executing a command that takes a long
 364 time.  In particular, it is safe to quit out of killing; either your
 365 text will ALL still be there, or it will ALL be in the kill ring (or
 366 maybe both).  Quitting an incremental search does special things
 367 documented under searching; in general, it may take two successive
 368 `C-g' characters to get out of a search.  `C-g' works by setting the
 369 variable `quit-flag' to `t' the instant `C-g' is typed; Emacs Lisp
 370 checks this variable frequently and quits if it is non-`nil'.  `C-g' is
 371 only actually executed as a command if it is typed while Emacs is
 372 waiting for input.
 373
 374    If you quit twice in a row before the first `C-g' is recognized, you
 375 activate the "emergency escape" feature and return to the shell.  *Note
 376 Emergency Escape::.
 377
 378    You can use `C-]' (`abort-recursive-edit') to get out of a recursive
 379 editing level and cancel the command which invoked it.  Quitting with
 380 `C-g' does not do this, and could not do this because it is used to
 381 cancel a partially typed command within the recursive editing level.
 382 Both operations are useful.  For example, if you are in the Emacs
 383 debugger (*note Lisp Debug::) and have typed `C-u 8' to enter a numeric
 384 argument, you can cancel that argument with `C-g' and remain in the
 385 debugger.
 386
 387    The command `M-x top-level' is equivalent to "enough" `C-]' commands
 388 to get you out of all the levels of recursive edits that you are in.
 389 `C-]' only gets you out one level at a time, but `M-x top-level' goes
 390 out all levels at once.  Both `C-]' and `M-x top-level' are like all
 391 other commands and unlike `C-g' in that they are effective only when
 392 Emacs is ready for a command.  `C-]' is an ordinary key and has its
 393 meaning only because of its binding in the keymap.  *Note Recursive
 394 Edit::.
 395
 396    `C-x u' (`undo') is not strictly speaking a way of cancelling a
 397 command, but you can think of it as cancelling a command already
 398 finished executing.  *Note Undo::.
 399
 400 \1f
 401 File: xemacs.info,  Node: Lossage,  Next: Bugs,  Prev: Quitting,  Up: Top
 402
 403 Dealing With Emacs Trouble
 404 ==========================
 405
 406    This section describes various conditions in which Emacs fails to
 407 work, and how to recognize them and correct them.
 408
 409 * Menu:
 410
 411 * Stuck Recursive::    `[...]' in mode line around the parentheses.
 412 * Screen Garbled::     Garbage on the screen.
 413 * Text Garbled::       Garbage in the text.
 414 * Unasked-for Search:: Spontaneous entry to incremental search.
 415 * Emergency Escape::   Emergency escape---
 416                         What to do if Emacs stops responding.
 417 * Total Frustration::  When you are at your wits' end.
 418
 419 \1f
 420 File: xemacs.info,  Node: Stuck Recursive,  Next: Screen Garbled,  Prev: Lossage,  Up: Lossage
 421
 422 Recursive Editing Levels
 423 ------------------------
 424
 425    Recursive editing levels are important and useful features of Emacs,
 426 but they can seem like malfunctions to the user who does not understand
 427 them.
 428
 429    If the mode line has square brackets `[...]' around the parentheses
 430 that contain the names of the major and minor modes, you have entered a
 431 recursive editing level.  If you did not do this on purpose, or if you
 432 don't understand what that means, you should just get out of the
 433 recursive editing level.  To do so, type `M-x top-level'.  This is
 434 called getting back to top level.  *Note Recursive Edit::.
 435
 436 \1f
 437 File: xemacs.info,  Node: Screen Garbled,  Next: Text Garbled,  Prev: Stuck Recursive,  Up: Lossage
 438
 439 Garbage on the Screen
 440 ---------------------
 441
 442    If the data on the screen looks wrong, the first thing to do is see
 443 whether the text is actually wrong.  Type `C-l', to redisplay the
 444 entire screen.  If the text appears correct after this, the problem was
 445 entirely in the previous screen update.
 446
 447    Display updating problems often result from an incorrect termcap
 448 entry for the terminal you are using.  The file `etc/TERMS' in the Emacs
 449 distribution gives the fixes for known problems of this sort.
 450 `INSTALL' contains general advice for these problems in one of its
 451 sections.  Very likely there is simply insufficient padding for certain
 452 display operations.  To investigate the possibility that you have this
 453 sort of problem, try Emacs on another terminal made by a different
 454 manufacturer.  If problems happen frequently on one kind of terminal but
 455 not another kind, the real problem is likely to be a bad termcap entry,
 456 though it could also be due to a bug in Emacs that appears for terminals
 457 that have or lack specific features.
 458
 459 \1f
 460 File: xemacs.info,  Node: Text Garbled,  Next: Unasked-for Search,  Prev: Screen Garbled,  Up: Lossage
 461
 462 Garbage in the Text
 463 -------------------
 464
 465    If `C-l' shows that the text is wrong, try undoing the changes to it
 466 using `C-x u' until it gets back to a state you consider correct.  Also
 467 try `C-h l' to find out what command you typed to produce the observed
 468 results.
 469
 470    If a large portion of text appears to be missing at the beginning or
 471 end of the buffer, check for the word `Narrow' in the mode line.  If it
 472 appears, the text is still present, but marked off-limits.  To make it
 473 visible again, type `C-x n w'.  *Note Narrowing::.
 474
 475 \1f
 476 File: xemacs.info,  Node: Unasked-for Search,  Next: Emergency Escape,  Prev: Text Garbled,  Up: Lossage
 477
 478 Spontaneous Entry to Incremental Search
 479 ---------------------------------------
 480
 481    If Emacs spontaneously displays `I-search:' at the bottom of the
 482 screen, it means that the terminal is sending `C-s' and `C-q' according
 483 to the poorly designed xon/xoff "flow control" protocol.  You should
 484 try to prevent this by putting the terminal in a mode where it will not
 485 use flow control, or by giving it enough padding that it will never
 486 send a `C-s'.  If that cannot be done, you must tell Emacs to expect
 487 flow control to be used, until you can get a properly designed terminal.
 488
 489    Information on how to do these things can be found in the file
 490 `INSTALL' in the Emacs distribution.
 491
 492 \1f
 493 File: xemacs.info,  Node: Emergency Escape,  Next: Total Frustration,  Prev: Unasked-for Search,  Up: Lossage
 494
 495 Emergency Escape
 496 ----------------
 497
 498    Because at times there have been bugs causing Emacs to loop without
 499 checking `quit-flag', a special feature causes Emacs to be suspended
 500 immediately if you type a second `C-g' while the flag is already set,
 501 so you can always get out of XEmacs.  Normally Emacs recognizes and
 502 clears `quit-flag' (and quits!) quickly enough to prevent this from
 503 happening.
 504
 505    When you resume Emacs after a suspension caused by multiple `C-g', it
 506 asks two questions before going back to what it had been doing:
 507
 508      Auto-save? (y or n)
 509      Abort (and dump core)? (y or n)
 510
 511 Answer each one with `y' or `n' followed by <RET>.
 512
 513    Saying `y' to `Auto-save?' causes immediate auto-saving of all
 514 modified buffers in which auto-saving is enabled.
 515
 516    Saying `y' to `Abort (and dump core)?' causes an illegal instruction
 517 to be executed, dumping core.  This is to enable a wizard to figure out
 518 why Emacs was failing to quit in the first place.  Execution does not
 519 continue after a core dump.  If you answer `n', execution does
 520 continue.  With luck, Emacs will ultimately check `quit-flag' and quit
 521 normally.  If not, and you type another `C-g', it is suspended again.
 522
 523    If Emacs is not really hung, but is just being slow, you may invoke
 524 the double `C-g' feature without really meaning to.  In that case,
 525 simply resume and answer `n' to both questions, and you will arrive at
 526 your former state.  Presumably the quit you requested will happen soon.
 527
 528    The double-`C-g' feature may be turned off when Emacs is running
 529 under a window system, since the window system always enables you to
 530 kill Emacs or to create another window and run another program.
 531
 532 \1f
 533 File: xemacs.info,  Node: Total Frustration,  Prev: Emergency Escape,  Up: Lossage
 534
 535 Help for Total Frustration
 536 --------------------------
 537
 538    If using Emacs (or something else) becomes terribly frustrating and
 539 none of the techniques described above solve the problem, Emacs can
 540 still help you.
 541
 542    First, if the Emacs you are using is not responding to commands, type
 543 `C-g C-g' to get out of it and then start a new one.
 544
 545    Second, type `M-x doctor <RET>'.
 546
 547    The doctor will make you feel better.  Each time you say something to
 548 the doctor, you must end it by typing <RET> <RET>.  This lets the
 549 doctor know you are finished.
 550
 551 \1f
 552 File: xemacs.info,  Node: Bugs,  Prev: Lossage,  Up: Top
 553
 554 Reporting Bugs
 555 ==============
 556
 557    Sometimes you will encounter a bug in Emacs.  Although we cannot
 558 promise we can or will fix the bug, and we might not even agree that it
 559 is a bug, we want to hear about bugs you encounter in case we do want
 560 to fix them.
 561
 562    To make it possible for us to fix a bug, you must report it.  In
 563 order to do so effectively, you must know when and how to do it.
 564
 565 When Is There a Bug
 566 -------------------
 567
 568    If Emacs executes an illegal instruction, or dies with an operating
 569 system error message that indicates a problem in the program (as
 570 opposed to something like "disk full"), then it is certainly a bug.
 571
 572    If Emacs updates the display in a way that does not correspond to
 573 what is in the buffer, then it is certainly a bug.  If a command seems
 574 to do the wrong thing but the problem corrects itself if you type
 575 `C-l', it is a case of incorrect display updating.
 576
 577    Taking forever to complete a command can be a bug, but you must make
 578 certain that it was really Emacs's fault.  Some commands simply take a
 579 long time.  Type `C-g' and then `C-h l' to see whether the input Emacs
 580 received was what you intended to type; if the input was such that you
 581 KNOW it should have been processed quickly, report a bug.  If you don't
 582 know whether the command should take a long time, find out by looking
 583 in the manual or by asking for assistance.
 584
 585    If a command you are familiar with causes an Emacs error message in a
 586 case where its usual definition ought to be reasonable, it is probably a
 587 bug.
 588
 589    If a command does the wrong thing, that is a bug.  But be sure you
 590 know for certain what it ought to have done.  If you aren't familiar
 591 with the command, or don't know for certain how the command is supposed
 592 to work, then it might actually be working right.  Rather than jumping
 593 to conclusions, show the problem to someone who knows for certain.
 594
 595    Finally, a command's intended definition may not be best for editing
 596 with.  This is a very important sort of problem, but it is also a
 597 matter of judgment.  Also, it is easy to come to such a conclusion out
 598 of ignorance of some of the existing features.  It is probably best not
 599 to complain about such a problem until you have checked the
 600 documentation in the usual ways, feel confident that you understand it,
 601 and know for certain that what you want is not available.  If you are
 602 not sure what the command is supposed to do after a careful reading of
 603 the manual, check the index and glossary for any terms that may be
 604 unclear.  If you still do not understand, this indicates a bug in the
 605 manual.  The manual's job is to make everything clear.  It is just as
 606 important to report documentation bugs as program bugs.
 607
 608    If the online documentation string of a function or variable
 609 disagrees with the manual, one of them must be wrong, so report the bug.
 610
 611 How to Report a Bug
 612 -------------------
 613
 614    When you decide that there is a bug, it is important to report it
 615 and to report it in a way which is useful.  What is most useful is an
 616 exact description of what commands you type, starting with the shell
 617 command to run Emacs, until the problem happens.  Always include the
 618 version number of Emacs that you are using; type `M-x emacs-version' to
 619 print this.
 620
 621    The most important principle in reporting a bug is to report FACTS,
 622 not hypotheses or categorizations.  It is always easier to report the
 623 facts, but people seem to prefer to strain to posit explanations and
 624 report them instead.  If the explanations are based on guesses about
 625 how Emacs is implemented, they will be useless; we will have to try to
 626 figure out what the facts must have been to lead to such speculations.
 627 Sometimes this is impossible.  But in any case, it is unnecessary work
 628 for us.
 629
 630    For example, suppose that you type `C-x C-f /glorp/baz.ugh <RET>',
 631 visiting a file which (you know) happens to be rather large, and Emacs
 632 prints out `I feel pretty today'.  The best way to report the bug is
 633 with a sentence like the preceding one, because it gives all the facts
 634 and nothing but the facts.
 635
 636    Do not assume that the problem is due to the size of the file and
 637 say, "When I visit a large file, Emacs prints out `I feel pretty
 638 today'."  This is what we mean by "guessing explanations".  The problem
 639 is just as likely to be due to the fact that there is a `z' in the file
 640 name.  If this is so, then when we got your report, we would try out
 641 the problem with some "large file", probably with no `z' in its name,
 642 and not find anything wrong.  There is no way in the world that we
 643 could guess that we should try visiting a file with a `z' in its name.
 644
 645    Alternatively, the problem might be due to the fact that the file
 646 starts with exactly 25 spaces.  For this reason, you should make sure
 647 that you inform us of the exact contents of any file that is needed to
 648 reproduce the bug.  What if the problem only occurs when you have typed
 649 the `C-x a l' command previously?  This is why we ask you to give the
 650 exact sequence of characters you typed since starting to use Emacs.
 651
 652    You should not even say "visit a file" instead of `C-x C-f' unless
 653 you know that it makes no difference which visiting command is used.
 654 Similarly, rather than saying "if I have three characters on the line,"
 655 say "after I type `<RET> A B C <RET> C-p'," if that is the way you
 656 entered the text.
 657
 658    If you are not in Fundamental mode when the problem occurs, you
 659 should say what mode you are in.
 660
 661    If the manifestation of the bug is an Emacs error message, it is
 662 important to report not just the text of the error message but a
 663 backtrace showing how the Lisp program in Emacs arrived at the error.
 664 To make the backtrace, you must execute the Lisp expression `(setq
 665 debug-on-error t)' before the error happens (that is to say, you must
 666 execute that expression and then make the bug happen).  This causes the
 667 Lisp debugger to run (*note Lisp Debug::).  The debugger's backtrace
 668 can be copied as text into the bug report.  This use of the debugger is
 669 possible only if you know how to make the bug happen again.  Do note
 670 the error message the first time the bug happens, so if you can't make
 671 it happen again, you can report at least that.
 672
 673    Check whether any programs you have loaded into the Lisp world,
 674 including your `.emacs' file, set any variables that may affect the
 675 functioning of Emacs.  Also, see whether the problem happens in a
 676 freshly started Emacs without loading your `.emacs' file (start Emacs
 677 with the `-q' switch to prevent loading the init file).  If the problem
 678 does NOT occur then, it is essential that we know the contents of any
 679 programs that you must load into the Lisp world in order to cause the
 680 problem to occur.
 681
 682    If the problem does depend on an init file or other Lisp programs
 683 that are not part of the standard Emacs system, then you should make
 684 sure it is not a bug in those programs by complaining to their
 685 maintainers first.  After they verify that they are using Emacs in a
 686 way that is supposed to work, they should report the bug.
 687
 688    If you can tell us a way to cause the problem without visiting any
 689 files, please do so.  This makes it much easier to debug.  If you do
 690 need files, make sure you arrange for us to see their exact contents.
 691 For example, it can often matter whether there are spaces at the ends
 692 of lines, or a newline after the last line in the buffer (nothing ought
 693 to care whether the last line is terminated, but tell that to the bugs).
 694
 695    The easy way to record the input to Emacs precisely is to write a
 696 dribble file; execute the Lisp expression:
 697
 698      (open-dribble-file "~/dribble")
 699
 700 using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
 701 Emacs.  From then on, all Emacs input will be written in the specified
 702 dribble file until the Emacs process is killed.
 703
 704    For possible display bugs, it is important to report the terminal
 705 type (the value of environment variable `TERM'), the complete termcap
 706 entry for the terminal from `/etc/termcap' (since that file is not
 707 identical on all machines), and the output that Emacs actually sent to
 708 the terminal.  The way to collect this output is to execute the Lisp
 709 expression:
 710
 711      (open-termscript "~/termscript")
 712
 713 using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
 714 Emacs.  From then on, all output from Emacs to the terminal will be
 715 written in the specified termscript file as well, until the Emacs
 716 process is killed.  If the problem happens when Emacs starts up, put
 717 this expression into your `.emacs' file so that the termscript file will
 718 be open when Emacs displays the screen for the first time.  Be warned:
 719 it is often difficult, and sometimes impossible, to fix a
 720 terminal-dependent bug without access to a terminal of the type that
 721 stimulates the bug.
 722
 723    The newsgroup `comp.emacs.xemacs' may be used for bug reports, other
 724 discussions and requests for assistance.
 725
 726    If you don't have access to this newgroup, you can subscribe to the
 727 mailing list version: the newsgroup is bidirectionally gatewayed into
 728 the mailing list `xemacs@xemacs.org'.
 729
 730    To be added or removed from this mailing list, send mail to
 731 `xemacs-request@xemacs.org'.  Do not send requests for addition to the
 732 mailing list itself.
 733
 734    The mailing lists and newsgroups are archived on our anonymous FTP
 735 server, `ftp.xemacs.org', and at various other archive sites around the
 736 net. You should also check the `FAQ' in `/pub/xemacs' on our anonymous
 737 FTP server. It provides some introductory information and help for
 738 initial configuration problems.
 739