[Emacs-diffs] /srv/bzr/emacs/trunk r106648: More updates to Building chapter of Emacs manual.

[Chong Yidong]

------------------------------------------------------------
revno: 106648
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2011-12-10 15:39:43 +0800
message:
  More updates to Building chapter of Emacs manual.
  
  * doc/emacs/building.texi (Compilation): Say what the -k flag to make does.
  Move subprocess discussion to Compilation Shell.
  (Compilation Mode): Add xref for grep, occur, and mouse
  references.  Define "locus".
  (Grep Searching): Use @command.
  (Debuggers, Commands of GUD, GDB Graphical Interface): Clarify
  intro.
  (Starting GUD): Clarify how arguments are specified.
  (Debugger Operation): Index entry for "GUD interaction buffer",
  and move basic description here from Commands of GUD node.
  (GDB User Interface Layout): Copyedits.
  (Source Buffers): Remove gdb-find-source-frame, which is not in
  gdb-mi.el.
  (Other GDB Buffers): Remove gdb-use-separate-io-buffer and
  toggle-gdb-all-registers, which are not in gdb-mi.el.  Don't
  re-document GUD interaction buffers.
modified:
  doc/emacs/ChangeLog
  doc/emacs/building.texi
  doc/emacs/emacs.texi

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-12-08 13:21:58 +0000
+++ b/doc/emacs/ChangeLog       2011-12-10 07:39:43 +0000
@@ -1,10 +1,21 @@
-2011-12-08  Chong Yidong  <address@hidden>
+2011-12-10  Chong Yidong  <address@hidden>
 
        * building.texi (Compilation): Say what the -k flag to make does.
        Move subprocess discussion to Compilation Shell.
        (Compilation Mode): Add xref for grep, occur, and mouse
        references.  Define "locus".
        (Grep Searching): Use @command.
+       (Debuggers, Commands of GUD, GDB Graphical Interface): Clarify
+       intro.
+       (Starting GUD): Clarify how arguments are specified.
+       (Debugger Operation): Index entry for "GUD interaction buffer",
+       and move basic description here from Commands of GUD node.
+       (GDB User Interface Layout): Copyedits.
+       (Source Buffers): Remove gdb-find-source-frame, which is not in
+       gdb-mi.el.
+       (Other GDB Buffers): Remove gdb-use-separate-io-buffer and
+       toggle-gdb-all-registers, which are not in gdb-mi.el.  Don't
+       re-document GUD interaction buffers.
 
        * programs.texi (Symbol Completion): M-TAB can now use Semantic.
        (Semantic): Add cindex entries for Semantic.

=== modified file 'doc/emacs/building.texi'
--- a/doc/emacs/building.texi   2011-12-08 13:21:58 +0000
+++ b/doc/emacs/building.texi   2011-12-10 07:39:43 +0000
@@ -453,16 +453,18 @@
 @cindex JDB
 @cindex PDB
 
address@hidden Do you believe in GUD?
 The GUD (Grand Unified Debugger) library provides an Emacs interface
-to a wide variety of symbolic debuggers.  Unlike the GDB graphical
-interface, which only runs GDB (@pxref{GDB Graphical Interface}), GUD
-can also run DBX, SDB, XDB, Perl's debugging mode, the Python debugger
-PDB, or the Java Debugger JDB.
-
-  In addition, Emacs contains a built-in system for debugging Emacs
-Lisp programs.  @xref{Debugging,, The Lisp Debugger, elisp, the Emacs
-Lisp Reference Manual}, for information on the Emacs Lisp debugger.
+to a wide variety of symbolic debuggers.  It can run the GNU Debugger
+(GDB), as well as DBX, SDB, XDB, Perl's debugging mode, the Python
+debugger PDB, and the Java Debugger JDB.
+
+  Emacs provides a special interface to GDB, which uses extra Emacs
+windows to display the state of the debugged program.  @xref{GDB
+Graphical Interface}.
+
+  Emacs also has a built-in debugger for Emacs Lisp programs.
address@hidden,, The Lisp Debugger, elisp, the Emacs Lisp Reference
+Manual}.
 
 @menu
 * Starting GUD::        How to start a debugger subprocess.
@@ -477,146 +479,136 @@
 @node Starting GUD
 @subsection Starting GUD
 
-  There are several commands for starting a debugger under GUD, each
+  There are several commands for starting a debugger subprocess, each
 corresponding to a particular debugger program.
 
 @table @kbd
address@hidden M-x gdb @key{RET} @var{file} @key{RET}
address@hidden M-x gdb
 @findex gdb
-Run GDB as a subprocess of Emacs.  This uses an IDE-like graphical
-interface; see @ref{GDB Graphical Interface}.  Only GDB works with the
-graphical interface.
+Run GDB as a subprocess, and interact with it via an IDE-like Emacs
+interface.  @xref{GDB Graphical Interface}, for more information about
+this command.
 
address@hidden M-x gud-gdb @key{RET} @var{file} @key{RET}
address@hidden M-x gud-gdb
 @findex gud-gdb
-Run GDB as a subprocess of Emacs.  This command creates a buffer for
-input and output to GDB, and switches to it.  If a GDB buffer already
-exists, it just switches to that buffer.
-
address@hidden M-x dbx @key{RET} @var{file} @key{RET}
+Run GDB, using a GUD interaction buffer for input and output to the
+GDB subprocess (@pxref{Debugger Operation}).  If such a buffer already
+exists, switch to it; otherwise, create the buffer and switch to it.
+
+The other commands in this list do the same, for other debugger
+programs.
+
address@hidden M-x perldb
address@hidden perldb
+Run the Perl interpreter in debug mode.
+
address@hidden M-x jdb
address@hidden jdb
+Run the Java debugger.
+
address@hidden M-x pdb
address@hidden pdb
+Run the Python debugger.
+
address@hidden M-x dbx
 @findex dbx
-Run DBX as a subprocess of Emacs.  Since Emacs does not implement a
-graphical interface for DBX, communication with DBX works by typing
-commands in the GUD interaction buffer.  The same is true for all
-the other supported debuggers.
+Run the DBX debugger.
 
address@hidden M-x xdb @key{RET} @var{file} @key{RET}
address@hidden M-x xdb
 @findex xdb
 @vindex gud-xdb-directories
-Run XDB as a subprocess of Emacs.  Use the variable
address@hidden to specify directories to search for source
-files.
+Run the XDB debugger.
 
address@hidden M-x sdb @key{RET} @var{file} @key{RET}
address@hidden M-x sdb
 @findex sdb
-Run SDB as a subprocess of Emacs.
-
-Some versions of SDB do not mention source file names in their
-messages.  When you use them, you need to have a valid tags table
-(@pxref{Tags}) in order for GUD to find functions in the source code.
-If you have not visited a tags table or the tags table doesn't list
-one of the functions, you get a message saying @samp{The sdb support
-requires a valid tags table to work}.  If this happens, generate a
-valid tags table in the working directory and try again.
-
address@hidden M-x perldb @key{RET} @var{file} @key{RET}
address@hidden perldb
-Run the Perl interpreter in debug mode to debug @var{file}, a Perl program.
-
address@hidden M-x jdb @key{RET} @var{file} @key{RET}
address@hidden jdb
-Run the Java debugger to debug @var{file}.
-
address@hidden M-x pdb @key{RET} @var{file} @key{RET}
address@hidden pdb
-Run the Python debugger to debug @var{file}.
+Run the SDB debugger.
 @end table
 
-  Each of these commands takes one argument: a command line to invoke
-the debugger.  In the simplest case, specify just the name of the
-executable file you want to debug.  You may also use options that the
-debugger supports.  However, shell wildcards and variables are not
-allowed.  GUD assumes that the first argument not starting with a
address@hidden is the executable file name.
+  Each of these commands reads a command line to invoke the debugger,
+using the minibuffer.  The minibuffer's initial contents contain the
+standard executable name and options for the debugger, and sometimes
+also a guess for the name of the executable file you want to debug.
+Shell wildcards and variables are not allowed in this command line.
+Emacs assumes that the first command argument which does not start
+with a @samp{-} is the executable file name.
 
 @cindex remote host, debugging on
-Tramp provides a facility to debug programs on remote hosts
-(@pxref{Running a debugger on a remote host, Running a debugger on a
-remote host,, tramp, The Tramp Manual}), whereby both the debugger and
-the program being debugged are on the same remote host.  This should
-not be confused with debugging programs remotely, where the program
-and the debugger run on different machines, as can be done using the
-GDB remote debugging feature, for example (@pxref{Remote Debugging,,
-Debugging Remote Programs, gdb, The GNU debugger}).
+  Tramp provides a facility for remote debugging, whereby both the
+debugger and the program being debugged are on the same remote host.
address@hidden a debugger on a remote host,,, tramp, The Tramp Manual},
+for details.  This is separate from GDB's remote debugging feature,
+where the program and the debugger run on different machines
+(@pxref{Remote Debugging,, Debugging Remote Programs, gdb, The GNU
+debugger}).
 
 @node Debugger Operation
 @subsection Debugger Operation
-
address@hidden fringes, and current execution line in GUD
-  Generally when you run a debugger with GUD, the debugger uses an Emacs
-buffer for its ordinary input and output.  This is called the GUD
-buffer.  Input and output from the program you are debugging also use
-this buffer.  We call this @dfn{text command mode}.  The GDB Graphical
-Interface can use further buffers (@pxref{GDB Graphical Interface}).
-
-  The debugger displays the source files of the program by visiting
-them in Emacs buffers.  An arrow in the left fringe indicates the
-current execution address@hidden a text-only terminal, the arrow
-appears as @samp{=>} and overlays the first two text columns.}  Moving
-point in this buffer does not move the arrow.  The arrow is not part
-of the file's text; it appears only on the screen.
-
-  You can start editing these source files at any time in the buffers
-that display them.  If you do modify a source file, keep in mind that
-inserting or deleting lines will throw off the arrow's positioning;
-GUD has no way of figuring out which line corresponded before your
-changes to the line number in a debugger message.  Also, you'll
-typically have to recompile and restart the program for your changes
-to be reflected in the debugger's tables.
-
address@hidden tooltips with GUD
address@hidden tooltip-gud-modes
address@hidden gud-tooltip-mode
address@hidden GUD interaction buffer
+
+  The @dfn{GUD interaction buffer} is an Emacs buffer which is used to
+send text commands to a debugger subprocess, and record its output.
+This is the basic interface for interacting with a debugger, used by
address@hidden gud-gdb} and other commands listed in
address@hidden
+the preceding section.
address@hidden iftext
address@hidden
address@hidden GUD}.
address@hidden ifnottex
+The @kbd{M-x gdb} command extends this interface with additional
+specialized buffers for controlling breakpoints, stack frames, and
+other aspects of the debugger state (@pxref{GDB Graphical Interface}).
+
+  The GUD interaction buffer uses a variant of Shell mode, so the
+Emacs commands defined by Shell mode are available (@pxref{Shell
+Mode}).  Completion is available for most debugger commands
+(@pxref{Completion}), and you can use the usual Shell mode history
+commands to repeat them.
address@hidden
+See the next section
address@hidden iftext
address@hidden
address@hidden of GUD},
address@hidden ifnottex
+for special commands that can be used in the GUD interaction buffer.
+
+  As you debug a program, Emacs displays the relevant source files by
+visiting them in Emacs buffers, with an arrow in the left fringe
+indicating the current execution line.  (On a text-only terminal, the
+arrow appears as @samp{=>}, overlaid on the first two text columns.)
+Moving point in such a buffer does not move the arrow.  You are free
+to edit these source files, but note that inserting or deleting lines
+will throw off the arrow's positioning, as Emacs has no way to figure
+out which edited source line corresponds to the line reported by the
+debugger subprocess.  To update this information, you typically have
+to recompile and restart the program.
+
address@hidden GUD Tooltip mode
address@hidden mode, GUD Tooltip
address@hidden gud-tooltip-mode
 @vindex gud-tooltip-echo-area
-  The Tooltip facility (@pxref{Tooltips}) provides support for address@hidden
-You activate this feature by turning on the minor mode
address@hidden  Then you can display a variable's value in a
-tooltip simply by pointing at it with the mouse.  This operates in the
-GUD buffer and in source buffers with major modes in the list
address@hidden  If the variable @code{gud-tooltip-echo-area}
-is address@hidden then the variable's value is displayed in the echo
-area.  When debugging a C program using the GDB Graphical Interface, you
-can also display macro definitions associated with an identifier when
-the program is not executing.
+  GUD Tooltip mode is a global minor mode that adds tooltip support to
+GUD.  To toggle this mode, type @kbd{M-x gud-tooltip-mode}.  It is
+disabled by default.  If enabled, you can move the mouse cursor over a
+variable to show its value in a tooltip (@pxref{Tooltips}); this takes
+effect in the GUD interaction buffer, and in all source buffers with
+major modes listed in the variable @code{gud-tooltip-modes}.  If the
+variable @code{gud-tooltip-echo-area} is address@hidden, values are
+shown in the echo area instead of a tooltip.
 
-  GUD tooltips are disabled when you use GDB in text command mode
-(@pxref{GDB Graphical Interface}), because displaying an expression's
-value in GDB can sometimes expand a macro and result in a side effect
-that interferes with the program's operation.  The GDB graphical
-interface supports GUD tooltips and assures they will not cause side
-effects.
+  When using GUD Tooltip mode with @kbd{M-x gud-gdb}, you should note
+that displaying an expression's value in GDB can sometimes expand a
+macro, potentially causing side effects in the debugged program.  If
+you use the @kbd{M-x gdb} interface, this problem does not occur, as
+there is special code to avoid side-effects; furthermore, you can
+display macro definitions associated with an identifier when the
+program is not executing.
 
 @node Commands of GUD
 @subsection Commands of GUD
 
-  The GUD interaction buffer uses a variant of Shell mode, so the
-Emacs commands of Shell mode are available (@pxref{Shell Mode}).  All
-the usual commands for your debugger are available, and you can use
-the Shell mode history commands to repeat them.  If you wish, you can
-control your debugger process entirely through this buffer.
-
-  GUD mode also provides commands for setting and clearing
-breakpoints, for selecting stack frames, and for stepping through the
-program.  These commands are available both in the GUD buffer and
-globally, but with different key bindings.  It also has its own tool
-bar from which you can invoke the more common commands by clicking on
-the appropriate icon.  This is particularly useful for repetitive
-commands like @code{gud-next} and @code{gud-step}, and allows you to
-keep the GUD buffer hidden.
-
-  The breakpoint commands are normally used in source file buffers,
-because that is the easiest way to specify where to set or clear the
-breakpoint.  Here's the global command to set a breakpoint:
+  GUD provides commands for setting and clearing breakpoints,
+selecting stack frames, and stepping through the program.
 
 @table @kbd
 @item C-x @key{SPC}
@@ -624,35 +616,42 @@
 Set a breakpoint on the source line that point is on.
 @end table
 
+  @kbd{C-x @key{SPC}} (@code{gud-break}), when called in a source
+buffer, sets a debugger breakpoint on the current source line.  This
+command is available only after starting GUD.  If you call it in a
+buffer that is not associated with any debugger subprocess, it signals
+a error.
+
 @kindex C-x C-a @r{(GUD)}
-  Here are the other special commands provided by address@hidden  The keys
+  The following commands are available both in the GUD interaction
+buffer and globally, but with different key bindings.  The keys
 starting with @kbd{C-c} are available only in the GUD interaction
-buffer.  The key bindings that start with @kbd{C-x C-a} are available
-in the GUD interaction buffer and also in source files.  Some of these
-commands are not available to all the supported debuggers.
+buffer, while those starting with @kbd{C-x C-a} are available
+globally.  Some of these commands are also available via the tool bar;
+some are not supported by certain debuggers.
 
 @table @kbd
 @item C-c C-l
 @kindex C-c C-l @r{(GUD)}
 @itemx C-x C-a C-l
 @findex gud-refresh
-Display in another window the last line referred to in the GUD
-buffer (that is, the line indicated in the last location message).
-This runs the command @code{gud-refresh}.
+Display, in another window, the last source line referred to in the
+GUD interaction buffer (@code{gud-refresh}).
 
 @item C-c C-s
 @kindex C-c C-s @r{(GUD)}
 @itemx C-x C-a C-s
 @findex gud-step
-Execute a single line of code (@code{gud-step}).  If the line contains
-a function call, execution stops after entering the called function.
+Execute the next single line of code (@code{gud-step}).  If the line
+contains a function call, execution stops after entering the called
+function.
 
 @item C-c C-n
 @kindex C-c C-n @r{(GUD)}
 @itemx C-x C-a C-n
 @findex gud-next
-Execute a single line of code, stepping across entire function calls
-at full speed (@code{gud-next}).
+Execute the next single line of code, stepping across function calls
+without stopping inside the functions (@code{gud-next}).
 
 @item C-c C-i
 @kindex C-c C-i @r{(GUD)}
@@ -763,17 +762,17 @@
 @vindex perldb-mode-hook
 @vindex pdb-mode-hook
 @vindex jdb-mode-hook
-  On startup, GUD runs one of the following hooks: @code{gdb-mode-hook},
-if you are using GDB; @code{dbx-mode-hook}, if you are using DBX;
address@hidden, if you are using SDB; @code{xdb-mode-hook}, if you
-are using XDB; @code{perldb-mode-hook}, for Perl debugging mode;
address@hidden, for PDB; @code{jdb-mode-hook}, for JDB.  You can
-use these hooks to define custom key bindings for the debugger
-interaction buffer.  @xref{Hooks}.
+  On startup, GUD runs one of the following hooks:
address@hidden, if you are using GDB; @code{dbx-mode-hook}, if
+you are using DBX; @code{sdb-mode-hook}, if you are using SDB;
address@hidden, if you are using XDB; @code{perldb-mode-hook},
+for Perl debugging mode; @code{pdb-mode-hook}, for PDB;
address@hidden, for JDB.  @xref{Hooks}.
 
-  Here is a convenient way to define a command that sends a particular
-command string to the debugger, and set up a key binding for it in the
-debugger interaction buffer:
+  The @code{gud-def} Lisp macro (@pxref{Defining Macros,,, elisp, the
+Emacs Lisp Reference Manual}) provides a convenient way to define an
+Emacs command that sends a particular command string to the debugger,
+and set up a key binding for in the GUD interaction buffer:
 
 @findex gud-def
 @example
@@ -829,21 +828,22 @@
 @node GDB Graphical Interface
 @subsection GDB Graphical Interface
 
-  The command @code{gdb} starts GDB in a graphical interface, using
-Emacs windows for display program state information.  With it, you do
-not need to use textual GDB commands; you can control the debugging
-session with the mouse.  For example, you can click in the fringe of a
-source buffer to set a breakpoint there, or on a stack frame in the
-stack buffer to select that frame.
-
-  This mode requires telling GDB that its ``screen size'' is
-unlimited, so it sets the height and width accordingly.  For correct
-operation you must not change these values during the GDB session.
+  The command @kbd{M-x gdb} starts GDB in an IDE-like interface, with
+specialized buffers for controlling breakpoints, stack frames, and
+other aspects of the debugger state.  It also provides additional ways
+to control the debugging session with the mouse, such as clicking in
+the fringe of a source buffer to set a breakpoint there.
 
 @vindex gud-gdb-command-name
-  To run GDB in text command mode, like the other debuggers in Emacs,
-use @kbd{M-x gud-gdb}.  You need to use text command mode to debug
-multiple programs within one Emacs session.
+  To run GDB using just the GUD interaction buffer interface, without
+these additional features, use @kbd{M-x gud-gdb} (@pxref{Starting
+GUD}).  You must use this if you want to debug multiple programs
+within one Emacs session, as that is currently unsupported by @kbd{M-x
+gdb}.
+
+  Internally, @kbd{M-x gdb} informs GDB that its ``screen size'' is
+unlimited; for correct operation, you must not change GDB's screen
+height and width values during the debugging session.
 
 @menu
 * GDB User Interface Layout::   Control the number of displayed buffers.
@@ -852,8 +852,7 @@
 * Breakpoints Buffer::          A breakpoint control panel.
 * Threads Buffer::              Displays your threads.
 * Stack Buffer::                Select a frame from the call stack.
-* Other GDB Buffers::           Input/output, locals, registers,
-                                assembler, threads and memory buffers.
+* Other GDB Buffers::           Other buffers for controlling the GDB state.
 * Watch Expressions::           Monitor variable values in the speedbar.
 * Multithreaded Debugging::     Debugging programs with several threads.
 @end menu
@@ -863,12 +862,12 @@
 @cindex GDB User Interface layout
 
 @vindex gdb-many-windows
-  If the variable @code{gdb-many-windows} is @code{nil} (the default
-value) then @kbd{M-x gdb} normally displays only the GUD buffer.
+  If the variable @code{gdb-many-windows} is @code{nil} (the default),
address@hidden gdb} normally displays only the GUD interaction buffer.
 However, if the variable @code{gdb-show-main} is also address@hidden,
-it starts with two windows: one displaying the GUD buffer, and the
-other showing the source for the @code{main} function of the program
-you are debugging.
+it starts with two windows: one displaying the GUD interaction buffer,
+and the other showing the source for the @code{main} function of the
+program you are debugging.
 
   If @code{gdb-many-windows} is address@hidden, then @kbd{M-x gdb}
 displays the following frame layout:
@@ -876,7 +875,7 @@
 @smallexample
 @group
 +--------------------------------+--------------------------------+
-|   GUD buffer (I/O of GDB)      |   Locals/Registers buffer      |
+|   GUD interaction buffer       |   Locals/Registers buffer      |
 |--------------------------------+--------------------------------+
 |   Primary Source buffer        |   I/O buffer for debugged pgm  |
 |--------------------------------+--------------------------------+
@@ -890,264 +889,233 @@
 width of the frame.
 
 @findex gdb-restore-windows
-  If you change the window layout, for example, while editing and
-re-compiling your program, then you can restore this standard window
-layout with the command @code{gdb-restore-windows}.
-
 @findex gdb-many-windows
-  To switch between this standard layout and a simple layout
-containing just the GUD buffer and a source file, type @kbd{M-x
-gdb-many-windows}.
+  If you ever change the window layout, you can restore the ``many
+windows'' layout by typing @kbd{M-x gdb-restore-windows}.  To toggle
+between the many windows layout and a simple layout with just the GUD
+interaction buffer and a source file, type @kbd{M-x gdb-many-windows}.
 
   You may also specify additional GDB-related buffers to display,
 either in the same frame or a different one.  Select the buffers you
-want with the @samp{GUD->GDB-Windows} and @samp{GUD->GDB-Frames}
-sub-menus.  If the menu-bar is unavailable, type @code{M-x
address@hidden or @code{M-x
address@hidden respectively, where
address@hidden is the relevant buffer type, such as
address@hidden  Most of these buffers are read-only, and typing
address@hidden in them kills them.
+want by typing @code{M-x address@hidden or
address@hidden address@hidden, where @var{buffertype}
+is the relevant buffer type, such as @samp{breakpoints}.  You can do
+the same with the menu bar, with the @samp{GDB-Windows} and
address@hidden sub-menus of the @samp{GUD} menu.
 
-  When you finish debugging, kill the GUD buffer with @kbd{C-x k},
-which will also kill all the buffers associated with the session.
-However you need not do this if, after editing and re-compiling your
-source code within Emacs, you wish continue debugging.  When you
-restart execution, GDB will automatically find your new executable.
-Keeping the GUD buffer has the advantage of keeping the shell history
-as well as GDB's breakpoints.  You do need to check that the
-breakpoints in recently edited source files are still in the right
-places.
+  When you finish debugging, kill the GUD interaction buffer with
address@hidden k}, which will also kill all the buffers associated with the
+session.  However you need not do this if, after editing and
+re-compiling your source code within Emacs, you wish to continue
+debugging.  When you restart execution, GDB automatically finds the
+new executable.  Keeping the GUD interaction buffer has the advantage
+of keeping the shell history as well as GDB's breakpoints.  You do
+need to check that the breakpoints in recently edited source files are
+still in the right places.
 
 @node Source Buffers
 @subsubsection Source Buffers
address@hidden GDB commands in Fringe
-
address@hidden @findex gdb-mouse-set-clear-breakpoint
address@hidden @findex gdb-mouse-toggle-breakpoint
-Many GDB commands can be entered using key bindings or the tool bar but
-sometimes it is quicker to use the fringe.  These commands either
-manipulate breakpoints or control program execution.  When there is no
-fringe, you can use the margin but this is only present when the
-source file already has a breakpoint.
-
-You can click @kbd{Mouse-1} in the fringe or display margin of a
-source buffer to set a breakpoint there and, on a graphical display, a
-red bullet will appear on that line.  If a breakpoint already exists
-on that line, the same click will remove it.  You can also enable or
-disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet.
-
-A solid arrow in the left fringe of a source buffer indicates the line
-of the innermost frame where the debugged program has stopped. A
-hollow arrow indicates the current execution line of higher level
-frames.
-
-If you drag the arrow in the fringe with @kbd{Mouse-1}
-(@code{gdb-mouse-until}), execution will continue to the line where
-you release the button, provided it is still in the same frame.
-Alternatively, you can click @kbd{Mouse-3} at some point in the fringe
-of this buffer and execution will advance to there.  A similar command
-(@code{gdb-mouse-jump}) allows you to jump to a source line without
-executing the intermediate lines by clicking @kbd{C-Mouse-3}.  This
-command allows you to go backwards which can be useful for running
-through code that has already executed, in order to examine its
-execution in more detail.
-
address@hidden @kbd
address@hidden Mouse-1
-Set or clear a breakpoint.
-
address@hidden C-Mouse-1
-Enable or disable a breakpoint.
-
address@hidden Mouse-3
-Continue execution to here.
-
address@hidden C-Mouse-3
-Jump to here.
address@hidden fringes, for debugging
+
address@hidden @asis
address@hidden @kbd{Mouse-1} (in fringe)
+Set or clear a breakpoint on that line.
+
address@hidden @kbd{C-Mouse-1} (in fringe)
+Enable or disable a breakpoint on that line.
+
address@hidden @kbd{Mouse-3} (in fringe)
+Continue execution to that line.
+
address@hidden @kbd{C-Mouse-3} (in fringe)
+Jump to that line.
 @end table
 
-If the variable @code{gdb-find-source-frame} is address@hidden and
-execution stops in a frame for which there is no source code e.g after
-an interrupt, then Emacs finds and displays the first frame further up
-stack for which there is source.  If it is @code{nil} then the source
-buffer continues to display the last frame which maybe more useful,
-for example, when re-setting a breakpoint.
+  On a graphical display, you can click @kbd{Mouse-1} in the fringe of
+a source buffer, to set a breakpoint on that line (@pxref{Fringes}).
+A red dot appears in the fringe, where you clicked.  If a breakpoint
+already exists there, the click removes it.  A @kbd{C-Mouse-1} click
+enables or disables an existing breakpoint; a breakpoint that is
+disabled, but not unset, is indicated by a gray dot.
+
+  On a text-only terminal, or when fringes are disabled, enabled
+breakpoints are indicated with a @samp{B} character in the left margin
+of the window.  Disabled breakpoints are indicated with @samp{b}.
+(The margin is only displayed if a breakpoint is present.)
+
+  A solid arrow in the left fringe of a source buffer indicates the
+line of the innermost frame where the debugged program has stopped. A
+hollow arrow indicates the current execution line of a higher-level
+frame.  If you drag the arrow in the fringe with @kbd{Mouse-1}, that
+causes execution to advance to the line where you release the button.
+Alternatively, you can click @kbd{Mouse-3} in the fringe to advance to
+that line.  You can click @kbd{C-Mouse-3} in the fringe to jump to
+that line without executing the intermediate lines.  This command
+allows you to go backwards, which can be useful for running through
+code that has already executed, in order to examine its execution in
+more detail.
 
 @node Breakpoints Buffer
 @subsubsection Breakpoints Buffer
 
-  The breakpoints buffer shows the existing breakpoints, watchpoints and
-catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}).  It has
-these special commands, which mostly apply to the @dfn{current
-breakpoint}, the breakpoint which point is on.
+  The GDB Breakpoints buffer shows the breakpoints, watchpoints and
+catchpoints in the debugger session.  @xref{Breakpoints,,, gdb, The
+GNU debugger}.  It provides the following commands, which mostly apply
+to the @dfn{current breakpoint} (the breakpoint which point is on):
 
 @table @kbd
 @item @key{SPC}
address@hidden SPC @r{(GDB breakpoints buffer)}
address@hidden SPC @r{(GDB Breakpoints buffer)}
 @findex gdb-toggle-breakpoint
-Enable/disable current breakpoint (@code{gdb-toggle-breakpoint}).
-On a graphical display, this changes the color of a bullet in the
-margin of a source buffer at the relevant line.  This is red when
-the breakpoint is enabled and gray when it is disabled.  Text-only
-terminals correspondingly display a @samp{B} or @samp{b}.
+Enable/disable current breakpoint (@code{gdb-toggle-breakpoint}).  On
+a graphical display, this changes the color of the dot in the fringe
+of the source buffer at that line.  The dot is red when the breakpoint
+is enabled, and gray when it is disabled.
 
 @item D
address@hidden D @r{(GDB breakpoints buffer)}
address@hidden D @r{(GDB Breakpoints buffer)}
 @findex gdb-delete-breakpoint
 Delete the current breakpoint (@code{gdb-delete-breakpoint}).
 
 @item @key{RET}
address@hidden RET @r{(GDB breakpoints buffer)}
address@hidden RET @r{(GDB Breakpoints buffer)}
 @findex gdb-goto-breakpoint
 Visit the source line for the current breakpoint
 (@code{gdb-goto-breakpoint}).
 
 @item Mouse-2
address@hidden Mouse-2 @r{(GDB breakpoints buffer)}
address@hidden Mouse-2 @r{(GDB Breakpoints buffer)}
 Visit the source line for the breakpoint you click on.
 @end table
 
 @vindex gdb-show-threads-by-default
-When @code{gdb-many-windows} is address@hidden, the breakpoints buffer
-shares its window with the threads buffer.  To switch from one to the
-other click with @kbd{Mouse-1} on the relevant button in the header
-line.  If @code{gdb-show-threads-by-default} is address@hidden, the
-threads buffer, rather than the breakpoints buffer, is shown at start
-up.
+  When @code{gdb-many-windows} is address@hidden, the GDB Breakpoints
+buffer shares its window with the GDB Threads buffer.  To switch from
+one to the other click with @kbd{Mouse-1} on the relevant button in
+the header line.  If @code{gdb-show-threads-by-default} is
address@hidden, the GDB Threads buffer is the one shown by default.
 
 @node Threads Buffer
 @subsubsection Threads Buffer
 
 @findex gdb-select-thread
-The threads buffer displays a summary of all threads currently in your
-program (@pxref{Threads, Threads, Debugging programs with multiple
-threads, gdb, The GNU debugger}).  Move point to any thread in the list
-and press @key{RET} to select it (@code{gdb-select-thread}) and
-display the associated source in the primary source buffer.
-Alternatively, click @kbd{Mouse-2} on a thread to select it.  Contents
-of all GDB buffers are updated whenever you select a thread.
+  The GDB Threads buffer displays a summary of the threads in the
+debugged program.  @xref{Threads, Threads, Debugging programs with
+multiple threads, gdb, The GNU debugger}.  To select a thread, move
+point there and type @key{RET} (@code{gdb-select-thread}), or click on
+it with @kbd{Mouse-2}.  This also displays the associated source
+buffer, and updates the contents of the other GDB buffers.
 
   You can customize variables under @code{gdb-buffers} group to select
-fields included in threads buffer.
+fields included in GDB Threads buffer.
 
 @table @code
 @item gdb-thread-buffer-verbose-names
 @vindex gdb-thread-buffer-verbose-names
-Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)} in
-threads buffer.
+Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)}.
 
 @item gdb-thread-buffer-arguments
 @vindex gdb-thread-buffer-arguments
-Show arguments of thread top frames in threads buffer.
+Show arguments of thread top frames.
 
 @item gdb-thread-buffer-locations
 @vindex gdb-thread-buffer-locations
-Show file information or library names in threads buffer.
+Show file information or library names.
 
 @item gdb-thread-buffer-addresses
 @vindex gdb-thread-buffer-addresses
 Show addresses for thread frames in threads buffer.
 @end table
 
-  It's possible to observe information for several threads
-simultaneously (in addition to buffers which show information for
-currently selected thread) using the following keys from the threads
-buffer.
+  To view information for several threads simultaneously, use the
+following commands from the GDB Threads buffer.
 
 @table @kbd
 @item d
 @kindex d @r{(GDB threads buffer)}
 @findex gdb-display-disassembly-for-thread
-Display disassembly buffer for the thread at current line.
-(@code{gdb-display-disassembly-for-thread})
+Display disassembly buffer for the thread at current line
+(@code{gdb-display-disassembly-for-thread}).
 
 @item f
 @kindex f @r{(GDB threads buffer)}
 @findex gdb-display-stack-for-thread
-Display stack buffer for the thread at current line.
+Display the GDB Stack buffer for the thread at current line
 (@code{gdb-display-stack-for-thread}).
 
 @item l
 @kindex l @r{(GDB threads buffer)}
 @findex gdb-display-locals-for-thread
-Display locals buffer for the thread at current line.
+Display the GDB Locals buffer for the thread at current line
 (@code{gdb-display-locals-for-thread}).
 
 @item r
 @kindex r @r{(GDB threads buffer)}
 @findex gdb-display-registers-for-thread
-Display registers buffer for the thread at current line.
+Display the GDB Registers buffer for the thread at current line
 (@code{gdb-display-registers-for-thread}).
 @end table
 
-Pressing their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and
address@hidden displays the corresponding buffer in a new frame.
address@hidden
+Their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and @kbd{R},
+display the corresponding buffer in a new frame.
 
   When you create a buffer showing information about some specific
 thread, it becomes bound to that thread and keeps showing actual
-information while you debug your program.  Every GDB buffer contains a
-number of thread it shows information for in its mode name.  Thread
-number is also included in the buffer name of bound buffers to prevent
-buffer names clashing.
+information while you debug your program.  The mode indicator for each
+GDB buffer shows the number of thread it is showing information about.
+The thread number is also included in the buffer name of bound
+buffers.
 
-Further commands are available in the threads buffer which depend on the
-mode of GDB that is used for controlling execution of your program.
-(@pxref{Multithreaded Debugging, Stopping and Starting Multi-threaded 
Programs}).
+  Further commands are available in the GDB Threads buffer which
+depend on the mode of GDB that is used for controlling execution of
+your program.  @xref{Multithreaded Debugging}.
 
 @node Stack Buffer
 @subsubsection Stack Buffer
 
-  The stack buffer displays a @dfn{call stack}, with one line for each
-of the nested subroutine calls (@dfn{stack frames}) now active in the
-program.  @xref{Backtrace,, Backtraces, gdb, The GNU debugger}.
+  The GDB Stack buffer displays a @dfn{call stack}, with one line for
+each of the nested subroutine calls (@dfn{stack frames}) in the
+debugger session.  @xref{Backtrace,, Backtraces, gdb, The GNU
+debugger}.
 
 @findex gdb-frames-select
-An arrow in the fringe points to the selected frame or, if the fringe is
-not present, the number of the selected frame is displayed in reverse
-contrast.  To select a frame in GDB, move point in the stack buffer to
-that stack frame and type @key{RET} (@code{gdb-frames-select}), or click
address@hidden on a stack frame.  If the locals buffer is visible,
-selecting a stack frame updates it to display the local variables of the
-new frame.
+  On graphical displays, the selected stack frame is indicated by an
+arrow in the fringe.  On text-only terminals, or when fringes are
+disabled, the selected stack frame is displayed in reverse contrast.
+To select a stack frame, move point in its line and type @key{RET}
+(@code{gdb-frames-select}), or click @kbd{Mouse-2} on it.  Doing so
+also updates the Locals buffer
address@hidden
+(@pxref{Other GDB Buffers}).
address@hidden ifnottex
address@hidden
+(described in the next section).
address@hidden iftex
 
 @node Other GDB Buffers
address@hidden Other Buffers
address@hidden Other GDB Buffers
 
 @table @asis
address@hidden Input/Output Buffer
address@hidden gdb-use-separate-io-buffer
-If the variable @code{gdb-use-separate-io-buffer} is address@hidden,
-the program being debugged takes its input and displays its output
-here.  Otherwise it uses the GUD buffer for that.  To toggle whether
-GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}.
-This takes effect when you next restart the program you are debugging.
-
-The history and replay commands from Shell mode are available here,
-as are the commands to send signals to the debugged program.
address@hidden Mode}.
-
 @item Locals Buffer
-The locals buffer displays the values of local variables of the
-current frame for simple data types (@pxref{Frame Info, Frame Info,
+This buffer displays the values of local variables of the current
+frame for simple data types (@pxref{Frame Info, Frame Info,
 Information on a frame, gdb, The GNU debugger}).  Press @key{RET} or
 click @kbd{Mouse-2} on the value if you want to edit it.
 
 Arrays and structures display their type only.  With GDB 6.4 or later,
-move point to their name and press @key{RET}, or alternatively click
address@hidden there, to examine their values.  With earlier versions
-of GDB, use @kbd{Mouse-2} or @key{RET} on the type description
+you can examine the value of the local variable at point by typing
address@hidden, or with a @kbd{Mouse-2} click.  With earlier versions of
+GDB, use @key{RET} or @kbd{Mouse-2} on the type description
 (@samp{[struct/union]} or @samp{[array]}).  @xref{Watch Expressions}.
 
 @item Registers Buffer
 @findex toggle-gdb-all-registers
-The registers buffer displays the values held by the registers
+This buffer displays the values held by the registers
 (@pxref{Registers,,, gdb, The GNU debugger}).  Press @key{RET} or
-click @kbd{Mouse-2} on a register if you want to edit its value.
-With GDB 6.4 or later, recently changed register values display with
address@hidden  With earlier versions of GDB, you can
-press @key{SPC} to toggle the display of floating point registers
-(@code{toggle-gdb-all-registers}).
+click @kbd{Mouse-2} on a register if you want to edit its value.  With
+GDB 6.4 or later, recently changed register values display with
address@hidden
 
 @item Assembler Buffer
 The assembler buffer displays the current frame as machine code.  An
@@ -1166,8 +1134,8 @@
 @end table
 
 When @code{gdb-many-windows} is address@hidden, the locals buffer
-shares its window with the registers buffer, just like breakpoints
-and threads buffers. To switch from one to the other click with
+shares its window with the registers buffer, just like breakpoints and
+threads buffers. To switch from one to the other, click with
 @kbd{Mouse-1} on the relevant button in the header line.
 
 @node Watch Expressions
@@ -1182,14 +1150,15 @@
 specify a prefix argument, you can enter the variable name in the
 minibuffer.
 
-  Each watch expression is displayed in the speedbar.  Complex data
-types, such as arrays, structures and unions are represented in a tree
-format.  Leaves and simple data types show the name of the expression
-and its value and, when the speedbar frame is selected, display the
-type as a tooltip.  Higher levels show the name, type and address
-value for pointers and just the name and type otherwise.  Root expressions
-also display the frame address as a tooltip to help identify the frame
-in which they were defined.
+  Each watch expression is displayed in the speedbar
+(@pxref{Speedbar}).  Complex data types, such as arrays, structures
+and unions are represented in a tree format.  Leaves and simple data
+types show the name of the expression and its value and, when the
+speedbar frame is selected, display the type as a tooltip.  Higher
+levels show the name, type and address value for pointers and just the
+name and type otherwise.  Root expressions also display the frame
+address as a tooltip to help identify the frame in which they were
+defined.
 
   To expand or contract a complex data type, click @kbd{Mouse-2} or
 press @key{SPC} on the tag to the left of the expression.  Emacs asks
@@ -1237,51 +1206,43 @@
 screen Emacs frame.
 
 @node Multithreaded Debugging
address@hidden Stopping and Starting Multi-threaded Programs
address@hidden Multithreaded Debugging
 @cindex Multithreaded debugging in GDB
-
address@hidden All-stop Debugging
-
-In all-stop mode, whenever your program stops, @emph{all} threads of
-execution stop.  Likewise, whenever you restart the program, all
-threads start executing.  @xref{All-Stop Mode, , All-Stop Mode, gdb,
-The GNU debugger}.  You can enable this behavior in Emacs by setting
address@hidden to @code{nil} before starting a debugging
-session.
-
address@hidden Non-stop Debugging
 @cindex Non-stop debugging in GDB
 
-For some multi-threaded targets, GDB supports a further mode of
-operation in which you can examine stopped program threads in the
-debugger while other threads continue to execute freely.
address@hidden Mode, , Non-Stop Mode, gdb, The GNU debugger}.
-This is referred to as @dfn{non-stop} mode.
-
-Versions of GDB prior to 7.0 do not support non-stop mode and it does
-not work on all targets.  In such cases, Emacs uses all-stop mode
-regardless of the value of @code{gdb-non-stop-setting}.
+  In GDB's @dfn{all-stop mode}, whenever your program stops, all
+execution threads stop.  Likewise, whenever you restart the program,
+all threads start executing.  @xref{All-Stop Mode, , All-Stop Mode,
+gdb, The GNU debugger}.  For some multi-threaded targets, GDB supports
+a further mode of operation, called @dfn{non-stop mode}, in which you
+can examine stopped program threads in the debugger while other
+threads continue to execute freely.  @xref{Non-Stop Mode, , Non-Stop
+Mode, gdb, The GNU debugger}.  Versions of GDB prior to 7.0 do not
+support non-stop mode, and it does not work on all targets.
 
 @vindex gdb-non-stop-setting
-If the variable @code{gdb-non-stop-setting} is address@hidden (the
-default value), Emacs tries to start GDB in non-stop mode.  Note that
-GDB debugging session needs to be restarted for change of this setting
-to take effect.
+  The variable @code{gdb-non-stop-setting} determines whether Emacs
+runs GDB in all-stop mode or non-stop mode.  The default is @code{t},
+which means it tries to use non-stop mode if that is available.  If
+you change the value to @code{nil}, or if non-stop mode is
+unavailable, Emacs runs GDB in all-stop mode.  The variable takes
+effect when Emacs begins a debugging session; if you change its value,
+you should restart any active debugging session.
 
 @vindex gdb-switch-when-another-stopped
-When a thread stops in non-stop mode, Emacs automatically switches to
-that thread.  It may be undesirable to allow switching of current
-thread when some other stopped thread is already selected.  Set
address@hidden to @code{nil} to prevent this.
+  When a thread stops in non-stop mode, Emacs usually switches to that
+thread.  If you don't want Emacs to do this switch if another stopped
+thread is already selected, change the variable
address@hidden to @code{nil}.
 
 @vindex gdb-switch-reasons
-Emacs can decide whether or not to switch to the stopped thread
-depending on the reason which caused the stop.  Customize
address@hidden to select stop reasons which make Emacs
-switch thread.
+  Emacs can decide whether or not to switch to the stopped thread
+depending on the reason which caused the stop.  Customize the variable
address@hidden to select the stop reasons which will cause
+a thread switch.
 
 @vindex gdb-stopped-hooks
-The variable @code{gdb-stopped-hooks} allows you to execute your
+  The variable @code{gdb-stopped-hooks} allows you to execute your
 functions whenever some thread stops.
 
   In non-stop mode, you can switch between different modes for GUD
@@ -1291,7 +1252,7 @@
 @table @dfn
 @item Non-stop/A
 
-When @code{gdb-gud-control-all-threads} is @code{t} (the default
+  When @code{gdb-gud-control-all-threads} is @code{t} (the default
 value), interruption and continuation commands apply to all threads,
 so you can halt or continue all your threads with one command using
 @code{gud-stop-subjob} and @code{gud-cont}, respectively.  The
@@ -1312,18 +1273,13 @@
 
   Stepping commands always apply to the current thread.
 
address@hidden Fine Thread Control
-
   In non-stop mode, you can interrupt/continue your threads without
 selecting them.  Hitting @kbd{i} in threads buffer interrupts thread
 under point, @kbd{c} continues it, @kbd{s} steps through.  More such
 commands may be added in the future.
 
-Combined with creating bound buffers for any thread, this allows you
-to change and track state of many threads in the same time.
-
-  Note that when you interrupt a thread, it stops with @samp{signal
-received} reason.  If that reason is included in your
+  Note that when you interrupt a thread, it stops with the
address@hidden received} reason.  If that reason is included in your
 @code{gdb-switch-reasons} (it is by default), Emacs will switch to
 that thread.
 

=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi      2011-12-08 13:21:58 +0000
+++ b/doc/emacs/emacs.texi      2011-12-10 07:39:43 +0000
@@ -722,8 +722,7 @@
 * Breakpoints Buffer::          A breakpoint control panel.
 * Threads Buffer::              Displays your threads.
 * Stack Buffer::                Select a frame from the call stack.
-* Other GDB Buffers::           Input/output, locals, registers,
-                                assembler, threads and memory buffers.
+* Other GDB Buffers::           Other buffers for controlling the GDB state.
 * Watch Expressions::           Monitor variable values in the speedbar.
 * Multithreaded Debugging::     Debugging programs with several threads.