(make-autoload): Simplify docstring.
Make use of symbol-property doc-string-elt.
Use memq rather than a sequence of eq.
(doc-string-elt): Fix the wrong or missing previously unused values.
(autoload-print-form): New function extracted from
generate-file-autoloads to allow recursion when handling progn
so that defvar's and defun's docstrings are properly printed.
(generate-file-autoloads): Use it.
Debugging GNU EmacsCopyright (c) 1985 Richard M. Stallman. Permission is granted to anyone to make or distribute verbatim copies of this document as received, in any medium, provided that the copyright notice and permission notice are preserved, and that the distributor grants the recipient permission for further redistribution as permitted by this notice. Permission is granted to distribute modified versions of this document, or of portions of it, under the above conditions, provided also that they carry prominent notices stating who last changed them.On 4.2 you will probably find that dbx does not work fordebugging GNU Emacs. For one thing, dbx does not keep theinferior process's terminal modes separate from its own.For another, dbx does not put the inferior in a separateprocess group, which makes trouble when an inferior usesinterrupt input, which GNU Emacs must do on 4.2.dbx has also been observed to have other problems,such as getting incorrect values for register variablesin stack frames other than the innermost one.The Emacs distribution now contains GDB, the new source-leveldebugger for the GNU system. GDB works for debugging Emacs.GDB currently runs on vaxes under 4.2 and on Sun 2 and Sun 3systems.** Some useful techniques`Fsignal' is a very useful place to stop in.All Lisp errors go through there.It is useful, when debugging, to have a guaranteed wayto return to the debugger at any time. If you are usinginterrupt-driven input, which is the default, then Emacs is usingRAW mode and the only way you can do it is to storethe code for some character into the variable stop_character: set stop_character = 29makes Control-] (decimal code 29) the stop character.Typing Control-] will cause immediate stop. You cannotuse the set command until the inferior process has been started.Put a breakpoint early in `main', or suspend the Emacs,to get an opportunity to do the set command.If you are using cbreak input (see the Lisp function set-input-mode),then typing Control-g will cause a SIGINT, which will return controlto the debugger immediately unless you have done ignore 3 (in dbx)or handle 3 nostop noprint (in gdb)You will note that most of GNU Emacs is written to avoiddeclaring a local variable in an inner block, even incases where using one would be the cleanest thing to do.This is because dbx cannot access any of the variablesin a function which has even one variable defined in aninner block. A few functions in GNU Emacs do have variablesin inner blocks, only because I wrote them before realizingthat dbx had this problem and never rewrote them to avoid it.I believe that GDB does not have such a problem.** Examining Lisp object values.When you have a live process to debug, and it has not encountered afatal error, you can use the GDB command `pr'. First print the valuein the ordinary way, with the `p' command. Then type `pr' with noarguments. This calls a subroutine which uses the Lisp printer.If you can't use this command, either because the process can't runa subroutine or because the data is invalid, you can fall back onlower-level commands.Use the `xtype' command to print out the data type of the last datavalue. Once you know the data type, use the command that correspondsto that type. Here are these commands: xint xptr xwindow xmarker xoverlay xmiscfree xintfwd xboolfwd xobjfwd xbufobjfwd xkbobjfwd xbuflocal xbuffer xsymbol xstring xvector xframe xwinconfig xcompiled xcons xcar xcdr xsubr xprocess xfloat xscrollbarEach one of them applies to a certain type or class of types.(Some of these types are not visible in Lisp, because they exist onlyinternally.)Each x... command prints some information about the value, andproduces a GDB value (subsequently available in $) through which youcan get at the rest of the contents.In general, most of the rest of the contents will be addition Lispobjects which you can examine in turn with the x... commands.** If GDB does not run and your debuggers can't load Emacs.On some systems, no debugger can load Emacs with a symbol table,perhaps because they all have fixed limits on the number of symbolsand Emacs exceeds the limits. Here is a method that can be usedin such an extremity. Do nm -n temacs > nmout strip temacs adb temacs 0xd:i 0xe:i 14:i 17:i :r -l loadup (or whatever)It is necessary to refer to the file `nmout' to convertnumeric addresses into symbols and vice versa.It is useful to be running under a window system.Then, if Emacs becomes hopelessly wedged, you can createanother window to do kill -9 in. kill -ILL is oftenuseful too, since that may make Emacs dump core or returnto adb.** Debugging incorrect screen updating.To debug Emacs problems that update the screen wrong, it is usefulto have a record of what input you typed and what Emacs sent to thescreen. To make these records, do(open-dribble-file "~/.dribble")(open-termscript "~/.termscript")The dribble file contains all characters read by Emacs from theterminal, and the termscript file contains all characters it sent tothe terminal. The use of the directory `~/' prevents interferencewith any other user.If you have irreproducible display problems, put those two expressionsin your ~/.emacs file. When the problem happens, exit the Emacs thatyou were running, kill it, and rename the two files. Then you can startanother Emacs without clobbering those files, and use it to examine them.