diff etc/DEBUG @ 90519:138ce2701550

Merge from emacs--devo--0 Patches applied: * emacs--devo--0 (patch 320-342) - Update from CVS - Merge from gnus--rel--5.10 - lisp/play/cookie1.el (cookie): Work properly when there's only one entry - Add note about "link" button-class to etc/TODO * gnus--rel--5.10 (patch 108-112) - Merge from emacs--devo--0 - Clean up merge mistakes - Update from CVS - Update from CVS: texi/gnus.texi (Summary Buffer Lines): Fix typo. Revision: [e-mail]/emacs--unicode--0--patch-86

--- a/etc/DEBUG	Wed Jul 05 17:38:31 2006 +0000
+++ b/etc/DEBUG	Thu Jul 06 08:59:39 2006 +0000
@@ -20,6 +20,8 @@
 ** When you debug Emacs with GDB, you should start it in the directory
 where the executable was made.  That directory has a .gdbinit file
 that defines various "user-defined" commands for debugging Emacs.
+(These commands are described below under "Examining Lisp object
+values" and "Debugging Emacs Redisplay problems".)
 
 ** When you are trying to analyze failed assertions, it will be
 essential to compile Emacs either completely without optimizations or
@@ -84,7 +86,9 @@
 
 You can also use `pp value' to print the emacs value directly.
 
-Note: It is not a good idea to try `pr' or `pp' if you know that Emacs
+To see the current value of a Lisp Variable, use `pv variable'.
+
+Note: It is not a good idea to try `pr', `pp', or `pv' if you know that Emacs
 is in deep trouble: its stack smashed (e.g., if it encountered SIGSEGV
 due to stack overflow), or crucial data structures, such as `obarray',
 corrupted, etc.  In such cases, the Emacs subroutine called by `pr'
@@ -97,10 +101,17 @@
 use `pr'.  Instead, use `s' to step out of the system call.  Then
 Emacs will be between instructions and capable of handling `pr'.
 
-If you can't use `pr' command, for whatever reason, you can fall back
-on lower-level commands.  Use the `xtype' command to print out the
-data type of the last data value.  Once you know the data type, use
-the command that corresponds to that type.  Here are these commands:
+If you can't use `pr' command, for whatever reason, you can use the
+`xpr' command to print out the data type and value of the last data
+value, For example:
+
+    p it->object
+    xpr
+
+You may also analyze data values using lower-level commands.  Use the
+`xtype' command to print out the data type of the last data value.
+Once you know the data type, use the command that corresponds to that
+type.  Here are these commands:
 
     xint xptr xwindow xmarker xoverlay xmiscfree xintfwd xboolfwd xobjfwd
     xbufobjfwd xkbobjfwd xbuflocal xbuffer xsymbol xstring xvector xframe
@@ -132,11 +143,11 @@
 
     (gdb) p frame
     $1 = 139854428
-    (gdb) xtype
+    (gdb) xpr
     Lisp_Vectorlike
     PVEC_FRAME
-    (gdb) xframe
     $2 = (struct frame *) 0x8560258
+    "emacs@localhost"
     (gdb) p *$
     $3 = {
       size = 1073742931,
@@ -144,13 +155,12 @@
       name = 140615219,
       [...]
     }
-    (gdb) p $3->name
-    $4 = 140615219
+
+Now we can use `pr' to print the frame parameters:
 
-Now we can use `pr' to print the name of the frame:
+    (gdb) pp $->param_alist
+    ((background-mode . light) (display-type . color) [...])
 
-    (gdb) pr
-    "[e-mail]"
 
 The Emacs C code heavily uses macros defined in lisp.h.  So suppose
 we want the address of the l-value expression near the bottom of
@@ -245,15 +255,32 @@
 
    xsymbol
 
+** Debugging Emacs Redisplay problems
+
+The src/.gdbinit file defines many useful commands for dumping redisplay
+related data structures in a terse and user-friendly format:
+
+ `ppt' prints value of PT, narrowing, and gap in current buffer.
+ `pit' dumps the current display iterator `it'.
+ `pwin' dumps the current window 'win'.
+ `prow' dumps the current glyph_row `row'.
+ `pg' dumps the current glyph `glyph'.
+ `pgi' dumps the next glyph.
+ `pgrow' dumps all glyphs in current glyph_row `row'.
+ `pcursor' dumps current output_cursor.
+
+The above commands also exist in a version with an `x' suffix which
+takes an object of the relevant type as argument.
+
 ** Using GDB in Emacs
 
 Debugging with GDB in Emacs offers some advantages over the command line (See
 the GDB Graphical Interface node of the Emacs manual).  There are also some
 features available just for debugging Emacs:
 
-1) The command gud-pp isavailable on the tool bar (the `pp' icon) and allows
-   the user to print the s-expression of the variable at point, in the GUD
-   buffer.
+1) The command gud-pp is available on the tool bar (the `pp' icon) and
+   allows the user to print the s-expression of the variable at point,
+   in the GUD buffer.
 
 2) Pressing `p' on a component of a watch expression that is a lisp object
    in the speedbar prints its s-expression in the GUD buffer.