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: Faces,  Next: Frame Components,  Prev: Audible Bell,  Up: Customization
  34
  35 Faces
  36 =====
  37
  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.
  45
  46    The display attributes of faces may be specified either in Lisp or
  47 through the X resource manager.
  48
  49 Customizing Faces
  50 -----------------
  51
  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.
  55
  56 `M-x invert-face'
  57      Swap the foreground and background colors of the given FACE.
  58
  59 `M-x make-face-bold'
  60      Make the font of the given FACE bold.  When called from a program,
  61      returns `nil' if this is not possible.
  62
  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.
  66
  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.
  70
  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.
  74
  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.
  78
  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.
  82
  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.
  86
  87 `M-x set-face-background'
  88      Change the background color of the given FACE.
  89
  90 `M-x set-face-background-pixmap'
  91      Change the background pixmap of the given FACE.
  92
  93 `M-x set-face-font'
  94      Change the font of the given FACE.
  95
  96 `M-x set-face-foreground'
  97      Change the foreground color of the given FACE.
  98
  99 `M-x set-face-underline-p'
 100      Change whether the given FACE is underlined.
 101
 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.
 108
 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.
 114
 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.
 123
 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.
 127
 128    If the environment variable XBMLANGPATH is set, then it is consulted
 129 before the `x-bitmap-file-path' variable.
 130
 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.
 136
 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
 141 frames.
 142
 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.
 148
 149 \1f
 150 File: xemacs.info,  Node: Frame Components,  Next: X Resources,  Prev: Faces,  Up: Customization
 151
 152 Frame Components
 153 ================
 154
 155    You can control the presence and position of most frame components,
 156 such as the menubar, toolbars, and gutters.
 157
 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.
 161
 162 \1f
 163 File: xemacs.info,  Node: X Resources,  Prev: Frame Components,  Up: Customization
 164
 165 X Resources
 166 ===========
 167
 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.
 173
 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.
 179
 180    The examples in this section assume the application class is `Emacs'.
 181
 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.
 185
 186    You can specify resources for all frames with the syntax:
 187
 188      Emacs*parameter: value
 189
 190 or
 191
 192      Emacs*EmacsFrame.parameter:value
 193
 194 You can specify resources for a particular frame with the syntax:
 195
 196      Emacs*FRAME-NAME.parameter: value
 197
 198 * Menu:
 199
 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.
 206
 207 \1f
 208 File: xemacs.info,  Node: Geometry Resources,  Next: Iconic Resources,  Up: X Resources
 209
 210 Geometry Resources
 211 ------------------
 212
 213    To make the default size of all Emacs frames be 80 columns by 55
 214 lines, do this:
 215
 216      Emacs*EmacsFrame.geometry: 80x55
 217
 218 To set the geometry of a particular frame named `fred', do this:
 219
 220      Emacs*fred.geometry: 80x55
 221
 222 Important! Do not use the following syntax:
 223
 224      Emacs*geometry: 80x55
 225
 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.
 232
 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):
 235
 236      Emacs.geometry: 80x55
 237
 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.
 244
 245    The `-geometry' command-line argument sets only the geometry of the
 246 initial frame created by Emacs.
 247
 248    A more complete explanation of geometry-handling is
 249
 250    * The `-geometry' command-line option sets the `Emacs.geometry'
 251      resource, that is, the geometry of the ApplicationShell.
 252
 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.
 256
 257    * For subsequent frames, the order is reversed: First the frame, and
 258      then the ApplicationShell.
 259
 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.
 263
 264    * For subsequent frames, the position is taken only from the frame,
 265      and never from the ApplicationShell.
 266
 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.
 270
 271 \1f
 272 File: xemacs.info,  Node: Iconic Resources,  Next: Resource List,  Prev: Geometry Resources,  Up: X Resources
 273
 274 Iconic Resources
 275 ----------------
 276
 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.
 282
 283 \1f
 284 File: xemacs.info,  Node: Resource List,  Next: Face Resources,  Prev: Iconic Resources,  Up: X Resources
 285
 286 Resource List
 287 -------------
 288
 289    Emacs frames accept the following resources:
 290
 291 `geometry' (class `Geometry'): string
 292      Initial geometry for the frame.  *Note Geometry Resources::, for a
 293      complete discussion of how this works.
 294
 295 `iconic' (class `Iconic'): boolean
 296      Whether this frame should appear in the iconified state.
 297
 298 `internalBorderWidth' (class `InternalBorderWidth'): int
 299      How many blank pixels to leave between the text and the edge of the
 300      window.
 301
 302 `interline' (class `Interline'): int
 303      How many pixels to leave between each line (may not be
 304      implemented).
 305
 306 `menubar' (class `Menubar'): boolean
 307      Whether newly-created frames should initially have a menubar.  Set
 308      to true by default.
 309
 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.
 315
 316 `barCursor' (class `BarColor'): boolean
 317      Whether the cursor should be displayed as a bar, or the
 318      traditional box.
 319
 320 `cursorColor' (class `CursorColor'): color-name
 321      The color of the text cursor.
 322
 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
 331      configured.
 332
 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
 341      configured.
 342
 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.
 349
 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.
 355
 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.
 363
 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.
 372
 373 `toolBarShadowThickness' (class `ToolBarShadowThickness'): integer
 374      Thickness of the shadows around the toolbars, in pixels.
 375
 376 `visualBell' (class `VisualBell'): boolean
 377      Whether XEmacs should flash the screen rather than making an
 378      audible beep.
 379
 380 `bellVolume' (class `BellVolume'): integer
 381      Volume of the audible beep.
 382
 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.
 389
 390    Emacs devices accept the following resources:
 391
 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'.
 395
 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'.
 401
 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'.
 407
 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'.
 411
 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'.
 416
 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'.
 421
 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'.
 427
 428 \1f
 429 File: xemacs.info,  Node: Face Resources,  Next: Widgets,  Prev: Resource List,  Up: X Resources
 430
 431 Face Resources
 432 --------------
 433
 434    The attributes of faces are also per-frame. They can be specified as:
 435
 436      Emacs.FACE_NAME.parameter: value
 437
 438 or
 439
 440      Emacs*FRAME_NAME.FACE_NAME.parameter: value
 441
 442 Faces accept the following resources:
 443
 444 `attributeFont' (class `AttributeFont'): font-name
 445      The font of this face.
 446
 447 `attributeForeground' (class `AttributeForeground'): color-name
 448 `attributeBackground' (class `AttributeBackground'): color-name
 449      The foreground and background colors of this face.
 450
 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.
 454
 455 `attributeUnderline' (class `AttributeUnderline'): boolean
 456      Whether text in this face should be underlined.
 457
 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'.
 462
 463    These are the names of the predefined faces:
 464
 465 `default'
 466      Everything inherits from this.
 467
 468 `bold'
 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.
 471
 472 `italic'
 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.
 475
 476 `bold-italic'
 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.
 479
 480 `modeline'
 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.
 484
 485 `highlight'
 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.
 489
 490 `left-margin'
 491 `right-margin'
 492      These are the faces that the left and right annotation margins are
 493      displayed in.
 494
 495 `zmacs-region'
 496      This is the face that mouse selections are displayed in.
 497
 498 `isearch'
 499      This is the face that the matched text being searched for is
 500      displayed in.
 501
 502 `info-node'
 503      This is the face of info menu items.  If unspecified, it is copied
 504      from `bold-italic'.
 505
 506 `info-xref'
 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.)
 511
 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
 515 face.
 516
 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
 522
 523      *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
 524
 525 If you use any of the other, less strict font name formats, some of
 526 which look like
 527
 528      lucidasanstypewriter-12
 529      fixed
 530      9x13
 531
 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)',
 535 and `xfontsel(1)'.
 536
 537 \1f
 538 File: xemacs.info,  Node: Widgets,  Next: Menubar Resources,  Prev: Face Resources,  Up: X Resources
 539
 540 Widgets
 541 -------
 542
 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
 550 follows:
 551
 552      INVOCATION-NAME            "shell"       "container"     FRAME-NAME
 553      x-emacs-application-class  "EmacsShell"  "EmacsManager"  "EmacsFrame"
 554
 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'.
 558
 559 \1f
 560 File: xemacs.info,  Node: Menubar Resources,  Prev: Widgets,  Up: X Resources
 561
 562 Menubar Resources
 563 -----------------
 564
 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.
 569
 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
 572
 573      Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
 574
 575    If both the Lucid Motif-lookalike menu widgets and X Font Sets are
 576 configured to allow multilingual menubars, then one uses
 577
 578      *menubar*FontSet:       -*-helvetica-bold-r-*-*-*-120-*-*-*-*-iso8859-*, \
 579                              -*-*-*-*-*-*-*-120-*-jisx0208.1983-0
 580
 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
 585 .fontSet resources.
 586
 587    If the Motif library is being used, then one would have to use
 588
 589      Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
 590
 591    because the Motif library uses the `fontList' resource name instead
 592 of `font', which has subtly different semantics.
 593
 594    The same is true of the scrollbars: They accept whichever resources
 595 are appropriate for the toolkit in use.
 596
 597 \1f
 598 File: xemacs.info,  Node: Quitting,  Next: Lossage,  Prev: Customization,  Up: Top
 599
 600 Quitting and Aborting
 601 =====================
 602
 603 `C-g'
 604      Quit.  Cancel running or partially typed command.
 605
 606 `C-]'
 607      Abort innermost recursive editing level and cancel the command
 608      which invoked it (`abort-recursive-edit').
 609
 610 `M-x top-level'
 611      Abort all recursive editing levels that are currently executing.
 612
 613 `C-x u'
 614      Cancel an already-executed command, usually (`undo').
 615
 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
 621 edit.
 622
 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
 635 waiting for input.
 636
 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
 639 Emergency Escape::.
 640
 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
 648 debugger.
 649
 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
 657 Edit::.
 658
 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::.
 662
 663 \1f
 664 File: xemacs.info,  Node: Lossage,  Next: Bugs,  Prev: Quitting,  Up: Top
 665
 666 Dealing With Emacs Trouble
 667 ==========================
 668
 669    This section describes various conditions in which Emacs fails to
 670 work, and how to recognize them and correct them.
 671
 672 * Menu:
 673
 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.
 681
 682 \1f
 683 File: xemacs.info,  Node: Stuck Recursive,  Next: Screen Garbled,  Prev: Lossage,  Up: Lossage
 684
 685 Recursive Editing Levels
 686 ------------------------
 687
 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
 690 them.
 691
 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::.
 698
 699 \1f
 700 File: xemacs.info,  Node: Screen Garbled,  Next: Text Garbled,  Prev: Stuck Recursive,  Up: Lossage
 701
 702 Garbage on the Screen
 703 ---------------------
 704
 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.
 709
 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.
 721
 722 \1f
 723 File: xemacs.info,  Node: Text Garbled,  Next: Unasked-for Search,  Prev: Screen Garbled,  Up: Lossage
 724
 725 Garbage in the Text
 726 -------------------
 727
 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
 731 results.
 732
 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::.
 737
 738 \1f
 739 File: xemacs.info,  Node: Unasked-for Search,  Next: Emergency Escape,  Prev: Text Garbled,  Up: Lossage
 740
 741 Spontaneous Entry to Incremental Search
 742 ---------------------------------------
 743
 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.
 751
 752    Information on how to do these things can be found in the file
 753 `INSTALL' in the Emacs distribution.
 754
 755 \1f
 756 File: xemacs.info,  Node: Emergency Escape,  Next: Total Frustration,  Prev: Unasked-for Search,  Up: Lossage
 757
 758 Emergency Escape
 759 ----------------
 760
 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
 766 happening.
 767
 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:
 770
 771      Auto-save? (y or n)
 772      Abort (and dump core)? (y or n)
 773
 774 Answer each one with `y' or `n' followed by <RET>.
 775
 776    Saying `y' to `Auto-save?' causes immediate auto-saving of all
 777 modified buffers in which auto-saving is enabled.
 778
 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.
 785
 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.
 790
 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.
 794
 795 \1f
 796 File: xemacs.info,  Node: Total Frustration,  Prev: Emergency Escape,  Up: Lossage
 797
 798 Help for Total Frustration
 799 --------------------------
 800
 801    If using Emacs (or something else) becomes terribly frustrating and
 802 none of the techniques described above solve the problem, Emacs can
 803 still help you.
 804
 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.
 807
 808    Second, type `M-x doctor <RET>'.
 809
 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.
 813
 814 \1f
 815 File: xemacs.info,  Node: Bugs,  Prev: Lossage,  Up: Top
 816
 817 Reporting Bugs
 818 ==============
 819
 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
 823 to fix them.
 824
 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.
 827
 828 When Is There a Bug
 829 -------------------
 830
 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.
 834
 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.
 839
 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.
 847
 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
 850 bug.
 851
 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.
 857
 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.
 870
 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.
 873
 874 How to Report a Bug
 875 -------------------
 876
 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
 882 print this.
 883
 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
 891 for us.
 892
 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.
 898
 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.
 907
 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.
 914
 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
 919 entered the text.
 920
 921    If you are not in Fundamental mode when the problem occurs, you
 922 should say what mode you are in.
 923
 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.
 935
 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.
 944
 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.
 950
 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).
 957
 958    The easy way to record the input to Emacs precisely is to write a
 959 dribble file; execute the Lisp expression:
 960
 961      (open-dribble-file "~/dribble")
 962
 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.
 966
 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
 972 expression:
 973
 974      (open-termscript "~/termscript")
 975
 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.
 985
 986    The newsgroup `comp.emacs.xemacs' may be used for bug reports, other
 987 discussions and requests for assistance.
 988
 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'.
 992
 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
 995 mailing list itself.
 996
 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.
1002