-File: xemacs.info, Node: Bugs, Prev: Lossage, Up: Top
-
-Reporting Bugs
-==============
-
- Sometimes you will encounter a bug in Emacs. Although we cannot
-promise we can or will fix the bug, and we might not even agree that it
-is a bug, we want to hear about bugs you encounter in case we do want
-to fix them.
-
- To make it possible for us to fix a bug, you must report it. In
-order to do so effectively, you must know when and how to do it.
-
-When Is There a Bug
--------------------
-
- If Emacs executes an illegal instruction, or dies with an operating
-system error message that indicates a problem in the program (as
-opposed to something like "disk full"), then it is certainly a bug.
-
- If Emacs updates the display in a way that does not correspond to
-what is in the buffer, then it is certainly a bug. If a command seems
-to do the wrong thing but the problem corrects itself if you type
-`C-l', it is a case of incorrect display updating.
-
- Taking forever to complete a command can be a bug, but you must make
-certain that it was really Emacs's fault. Some commands simply take a
-long time. Type `C-g' and then `C-h l' to see whether the input Emacs
-received was what you intended to type; if the input was such that you
-KNOW it should have been processed quickly, report a bug. If you don't
-know whether the command should take a long time, find out by looking
-in the manual or by asking for assistance.
-
- If a command you are familiar with causes an Emacs error message in a
-case where its usual definition ought to be reasonable, it is probably a
-bug.
-
- If a command does the wrong thing, that is a bug. But be sure you
-know for certain what it ought to have done. If you aren't familiar
-with the command, or don't know for certain how the command is supposed
-to work, then it might actually be working right. Rather than jumping
-to conclusions, show the problem to someone who knows for certain.
-
- Finally, a command's intended definition may not be best for editing
-with. This is a very important sort of problem, but it is also a
-matter of judgment. Also, it is easy to come to such a conclusion out
-of ignorance of some of the existing features. It is probably best not
-to complain about such a problem until you have checked the
-documentation in the usual ways, feel confident that you understand it,
-and know for certain that what you want is not available. If you are
-not sure what the command is supposed to do after a careful reading of
-the manual, check the index and glossary for any terms that may be
-unclear. If you still do not understand, this indicates a bug in the
-manual. The manual's job is to make everything clear. It is just as
-important to report documentation bugs as program bugs.
-
- If the online documentation string of a function or variable
-disagrees with the manual, one of them must be wrong, so report the bug.
-
-How to Report a Bug
--------------------
-
- When you decide that there is a bug, it is important to report it
-and to report it in a way which is useful. What is most useful is an
-exact description of what commands you type, starting with the shell
-command to run Emacs, until the problem happens. Always include the
-version number of Emacs that you are using; type `M-x emacs-version' to
-print this.
-
- The most important principle in reporting a bug is to report FACTS,
-not hypotheses or categorizations. It is always easier to report the
-facts, but people seem to prefer to strain to posit explanations and
-report them instead. If the explanations are based on guesses about
-how Emacs is implemented, they will be useless; we will have to try to
-figure out what the facts must have been to lead to such speculations.
-Sometimes this is impossible. But in any case, it is unnecessary work
-for us.
-
- For example, suppose that you type `C-x C-f /glorp/baz.ugh <RET>',
-visiting a file which (you know) happens to be rather large, and Emacs
-prints out `I feel pretty today'. The best way to report the bug is
-with a sentence like the preceding one, because it gives all the facts
-and nothing but the facts.
-
- Do not assume that the problem is due to the size of the file and
-say, "When I visit a large file, Emacs prints out `I feel pretty
-today'." This is what we mean by "guessing explanations". The problem
-is just as likely to be due to the fact that there is a `z' in the file
-name. If this is so, then when we got your report, we would try out
-the problem with some "large file", probably with no `z' in its name,
-and not find anything wrong. There is no way in the world that we
-could guess that we should try visiting a file with a `z' in its name.
-
- Alternatively, the problem might be due to the fact that the file
-starts with exactly 25 spaces. For this reason, you should make sure
-that you inform us of the exact contents of any file that is needed to
-reproduce the bug. What if the problem only occurs when you have typed
-the `C-x a l' command previously? This is why we ask you to give the
-exact sequence of characters you typed since starting to use Emacs.
-
- You should not even say "visit a file" instead of `C-x C-f' unless
-you know that it makes no difference which visiting command is used.
-Similarly, rather than saying "if I have three characters on the line,"
-say "after I type `<RET> A B C <RET> C-p'," if that is the way you
-entered the text.
-
- If you are not in Fundamental mode when the problem occurs, you
-should say what mode you are in.
-
- If the manifestation of the bug is an Emacs error message, it is
-important to report not just the text of the error message but a
-backtrace showing how the Lisp program in Emacs arrived at the error.
-To make the backtrace, you must execute the Lisp expression `(setq
-debug-on-error t)' before the error happens (that is to say, you must
-execute that expression and then make the bug happen). This causes the
-Lisp debugger to run (*note Lisp Debug::). The debugger's backtrace
-can be copied as text into the bug report. This use of the debugger is
-possible only if you know how to make the bug happen again. Do note
-the error message the first time the bug happens, so if you can't make
-it happen again, you can report at least that.
-
- Check whether any programs you have loaded into the Lisp world,
-including your `.emacs' file, set any variables that may affect the
-functioning of Emacs. Also, see whether the problem happens in a
-freshly started Emacs without loading your `.emacs' file (start Emacs
-with the `-q' switch to prevent loading the init file). If the problem
-does NOT occur then, it is essential that we know the contents of any
-programs that you must load into the Lisp world in order to cause the
-problem to occur.
-
- If the problem does depend on an init file or other Lisp programs
-that are not part of the standard Emacs system, then you should make
-sure it is not a bug in those programs by complaining to their
-maintainers first. After they verify that they are using Emacs in a
-way that is supposed to work, they should report the bug.
-
- If you can tell us a way to cause the problem without visiting any
-files, please do so. This makes it much easier to debug. If you do
-need files, make sure you arrange for us to see their exact contents.
-For example, it can often matter whether there are spaces at the ends
-of lines, or a newline after the last line in the buffer (nothing ought
-to care whether the last line is terminated, but tell that to the bugs).
-
- The easy way to record the input to Emacs precisely is to write a
-dribble file; execute the Lisp expression:
-
- (open-dribble-file "~/dribble")
-
-using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
-Emacs. From then on, all Emacs input will be written in the specified
-dribble file until the Emacs process is killed.
-
- For possible display bugs, it is important to report the terminal
-type (the value of environment variable `TERM'), the complete termcap
-entry for the terminal from `/etc/termcap' (since that file is not
-identical on all machines), and the output that Emacs actually sent to
-the terminal. The way to collect this output is to execute the Lisp
-expression:
-
- (open-termscript "~/termscript")
-
-using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
-Emacs. From then on, all output from Emacs to the terminal will be
-written in the specified termscript file as well, until the Emacs
-process is killed. If the problem happens when Emacs starts up, put
-this expression into your `.emacs' file so that the termscript file will
-be open when Emacs displays the screen for the first time. Be warned:
-it is often difficult, and sometimes impossible, to fix a
-terminal-dependent bug without access to a terminal of the type that
-stimulates the bug.
-
- The newsgroup `comp.emacs.xemacs' may be used for bug reports, other
-discussions and requests for assistance.
-
- If you don't have access to this newgroup, you can subscribe to the
-mailing list version: the newsgroup is bidirectionally gatewayed into
-the mailing list `xemacs@xemacs.org'.
-
- To be added or removed from this mailing list, send mail to
-`xemacs-request@xemacs.org'. Do not send requests for addition to the
-mailing list itself.
-
- The mailing lists and newsgroups are archived on our anonymous FTP
-server, `ftp.xemacs.org', and at various other archive sites around the
-net. You should also check the `FAQ' in `/pub/xemacs' on our anonymous
-FTP server. It provides some introductory information and help for
-initial configuration problems.
+File: xemacs.info, Node: Resource List, Next: Face Resources, Prev: Iconic Resources, Up: X Resources
+
+Resource List
+-------------
+
+ Emacs frames accept the following resources:
+
+`geometry' (class `Geometry'): string
+ Initial geometry for the frame. *Note Geometry Resources::, for a
+ complete discussion of how this works.
+
+`iconic' (class `Iconic'): boolean
+ Whether this frame should appear in the iconified state.
+
+`internalBorderWidth' (class `InternalBorderWidth'): int
+ How many blank pixels to leave between the text and the edge of the
+ window.
+
+`interline' (class `Interline'): int
+ How many pixels to leave between each line (may not be
+ implemented).
+
+`menubar' (class `Menubar'): boolean
+ Whether newly-created frames should initially have a menubar. Set
+ to true by default.
+
+`initiallyUnmapped' (class `InitiallyUnmapped'): boolean
+ Whether XEmacs should leave the initial frame unmapped when it
+ starts up. This is useful if you are starting XEmacs as a server
+ (e.g. in conjunction with gnuserv or the external client widget).
+ You can also control this with the `-unmapped' command-line option.
+
+`barCursor' (class `BarColor'): boolean
+ Whether the cursor should be displayed as a bar, or the
+ traditional box.
+
+`cursorColor' (class `CursorColor'): color-name
+ The color of the text cursor.
+
+`scrollBarWidth' (class `ScrollBarWidth'): integer
+ How wide the vertical scrollbars should be, in pixels; 0 means no
+ vertical scrollbars. You can also use a resource specification of
+ the form `*scrollbar.width', or the usual toolkit scrollbar
+ resources: `*XmScrollBar.width' (Motif), `*XlwScrollBar.width'
+ (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend
+ that you use the toolkit resources, though, because they're
+ dependent on how exactly your particular build of XEmacs was
+ configured.
+
+`scrollBarHeight' (class `ScrollBarHeight'): integer
+ How high the horizontal scrollbars should be, in pixels; 0 means no
+ horizontal scrollbars. You can also use a resource specification
+ of the form `*scrollbar.height', or the usual toolkit scrollbar
+ resources: `*XmScrollBar.height' (Motif), `*XlwScrollBar.height'
+ (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend
+ that you use the toolkit resources, though, because they're
+ dependent on how exactly your particular build of XEmacs was
+ configured.
+
+`scrollBarPlacement' (class `ScrollBarPlacement'): string
+ Where the horizontal and vertical scrollbars should be positioned.
+ This should be one of the four strings `BOTTOM_LEFT',
+ `BOTTOM_RIGHT', `TOP_LEFT', and `TOP_RIGHT'. Default is
+ `BOTTOM_RIGHT' for the Motif and Lucid scrollbars and
+ `BOTTOM_LEFT' for the Athena scrollbars.
+
+`topToolBarHeight' (class `TopToolBarHeight'): integer
+`bottomToolBarHeight' (class `BottomToolBarHeight'): integer
+`leftToolBarWidth' (class `LeftToolBarWidth'): integer
+`rightToolBarWidth' (class `RightToolBarWidth'): integer
+ Height and width of the four possible toolbars.
+
+`topToolBarShadowColor' (class `TopToolBarShadowColor'): color-name
+`bottomToolBarShadowColor' (class `BottomToolBarShadowColor'): color-name
+ Color of the top and bottom shadows for the toolbars. NOTE: These
+ resources do _not_ have anything to do with the top and bottom
+ toolbars (i.e. the toolbars at the top and bottom of the frame)!
+ Rather, they affect the top and bottom shadows around the edges of
+ all four kinds of toolbars.
+
+`topToolBarShadowPixmap' (class `TopToolBarShadowPixmap'): pixmap-name
+`bottomToolBarShadowPixmap' (class `BottomToolBarShadowPixmap'): pixmap-name
+ Pixmap of the top and bottom shadows for the toolbars. If set,
+ these resources override the corresponding color resources. NOTE:
+ These resources do _not_ have anything to do with the top and
+ bottom toolbars (i.e. the toolbars at the top and bottom of the
+ frame)! Rather, they affect the top and bottom shadows around the
+ edges of all four kinds of toolbars.
+
+`toolBarShadowThickness' (class `ToolBarShadowThickness'): integer
+ Thickness of the shadows around the toolbars, in pixels.
+
+`visualBell' (class `VisualBell'): boolean
+ Whether XEmacs should flash the screen rather than making an
+ audible beep.
+
+`bellVolume' (class `BellVolume'): integer
+ Volume of the audible beep.
+
+`useBackingStore' (class `UseBackingStore'): boolean
+ Whether XEmacs should set the backing-store attribute of the X
+ windows it creates. This increases the memory usage of the X
+ server but decreases the amount of X traffic necessary to update
+ the screen, and is useful when the connection to the X server goes
+ over a low-bandwidth line such as a modem connection.
+
+ Emacs devices accept the following resources:
+
+`textPointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over text. This resource is
+ used to initialize the variable `x-pointer-shape'.
+
+`selectionPointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over a selectable text region
+ (an extent with the `highlight' property; for example, an Info
+ cross-reference). This resource is used to initialize the variable
+ `x-selection-pointer-shape'.
+
+`spacePointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over a blank space in a buffer
+ (that is, after the end of a line or after the end-of-file). This
+ resource is used to initialize the variable
+ `x-nontext-pointer-shape'.
+
+`modeLinePointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over a modeline. This
+ resource is used to initialize the variable `x-mode-pointer-shape'.
+
+`gcPointer' (class `Cursor'): cursor-name
+ The cursor to display when a garbage-collection is in progress.
+ This resource is used to initialize the variable
+ `x-gc-pointer-shape'.
+
+`scrollbarPointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over the scrollbar. This
+ resource is used to initialize the variable
+ `x-scrollbar-pointer-shape'.
+
+`pointerColor' (class `Foreground'): color-name
+`pointerBackground' (class `Background'): color-name
+ The foreground and background colors of the mouse cursor. These
+ resources are used to initialize the variables
+ `x-pointer-foreground-color' and `x-pointer-background-color'.