- `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.
+ '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. For example, 'pgrowx' dumps all
+glyphs in its argument, which must be of type 'struct glyph_row'.
+
+Since redisplay is performed by Emacs very frequently, you need to place your
+breakpoints cleverly to avoid hitting them all the time, when the issue you are
+debugging did not (yet) happen. Here are some useful techniques for that:
+
+ . Put a breakpoint at 'Fredraw_display' before running Emacs. Then do
+ whatever is required to reproduce the bad display, and invoke "M-x
+ redraw-display". The debugger will kick in, and you can set or enable
+ breakpoints in strategic places, knowing that the bad display will be
+ redrawn from scratch.
+
+ . For debugging incorrect cursor position, a good place to put a breakpoint is
+ in 'set_cursor_from_row'. The first time this function is called as part of
+ 'redraw-display', Emacs is redrawing the minibuffer window, which is usually
+ not what you want; type "continue" to get to the call you want. In general,
+ always make sure 'set_cursor_from_row' is called for the right window and
+ buffer by examining the value of w->contents: it should be the buffer whose
+ display you are debugging.
+
+ . 'set_cursor_from_row' is also a good place to look at the contents of a
+ screen line (a.k.a. "glyph row"), by means of the 'pgrow' GDB command. Of
+ course, you need first to make sure the cursor is on the screen line which
+ you want to investigate. If you have set a breakpoint in 'Fredraw_display',
+ as advised above, move cursor to that line before invoking 'redraw-display'.
+
+ . If the problem happens only at some specific buffer position or for some
+ specific rarely-used character, you can make your breakpoints conditional on
+ those values. The display engine maintains the buffer and string position
+ it is processing in the it->current member; for example, the buffer
+ character position is in it->current.pos.charpos. Most redisplay functions
+ accept a pointer to a 'struct it' object as their argument, so you can make
+ conditional breakpoints in those functions, like this:
+
+ (gdb) break x_produce_glyphs if it->current.pos.charpos == 1234
+
+ For conditioning on the character being displayed, use it->c or
+ it->char_to_display.
+
+ . You can also make the breakpoints conditional on what object is being used
+ for producing glyphs for display. The it->method member has the value
+ GET_FROM_BUFFER for displaying buffer contents, GET_FROM_STRING for
+ displaying a Lisp string (e.g., a 'display' property or an overlay string),
+ GET_FROM_IMAGE for displaying an image, etc. See 'enum it_method' in
+ dispextern.h for the full list of values.