Starting multiple GUD session; doc problem

Starting multiple GUD session; doc problem

[Stephen Leake]

[-- Attachment #1: Type: text/plain, Size: 976 bytes --]

I just tried to start two gdb sessions in one CVS Emacs session for
the first time (I've done this many times in Emacs 21). I got the
error message:

 "gdb: Multiple debugging is only supported with "gdb --fullname"

So I dutifully added "--fullname" to the gdb command line:

    gdb --annotate=3 --fullname gds-main_models_test.exe 

and got the same error message. I read the GUD and GDB entries in the
Emacs manual, and the help message for `gdb'; no success. Finally I
read the Emacs lisp source code for gud, and found this comment in
gud.el (gud-gdb-marker-filter):

    ;; Check for annotations and change gud-minor-mode to 'gdba if
    ;; they are found.

It seems the real issue is the presence or absence of "--annotate=3",
not the presence of "--fullname". In fact, "--fullname" is not
necessary if compilation-search-path is set to include the source
directories.

So I suggest the attached patch to the Emacs manual (building.texi)
and a couple gud doc strings.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: gud.diff --]
[-- Type: text/x-patch, Size: 3601 bytes --]

Index: lisp/progmodes/gdb-ui.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/progmodes/gdb-ui.el,v
retrieving revision 1.191
diff -c -r1.191 gdb-ui.el
*** lisp/progmodes/gdb-ui.el	10 Nov 2006 09:38:11 -0000	1.191
--- lisp/progmodes/gdb-ui.el	23 Nov 2006 16:29:12 -0000
***************
*** 214,220 ****
  
  ;;;###autoload
  (defun gdba (command-line)
!   "Run gdb on program FILE in buffer *gud-FILE*.
  The directory containing FILE becomes the initial working directory
  and source-file directory for your debugger.
  
--- 214,220 ----
  
  ;;;###autoload
  (defun gdba (command-line)
!   "Run gdb in GUI mode on program FILE in buffer *gud-FILE*.
  The directory containing FILE becomes the initial working directory
  and source-file directory for your debugger.
  
Index: lisp/progmodes/gud.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/progmodes/gud.el,v
retrieving revision 1.116
diff -c -r1.116 gud.el
*** lisp/progmodes/gud.el	5 Sep 2006 03:40:54 -0000	1.116
--- lisp/progmodes/gud.el	23 Nov 2006 16:29:15 -0000
***************
*** 680,687 ****
  default this command starts GDB using a graphical interface.  See
  `gdba' for more information.
  
! To run GDB in text command mode, set `gud-gdb-command-name' to
! \"gdb --fullname\" and include the pathname, if necessary."
    (interactive (list (gud-query-cmdline 'gdb)))
  
    (if (and gud-comint-buffer
--- 680,686 ----
  default this command starts GDB using a graphical interface.  See
  `gdba' for more information.
  
! To run GDB in text command mode, delete \"--annotate=3\" from `gud-gdb-command-name'."
    (interactive (list (gud-query-cmdline 'gdb)))
  
    (if (and gud-comint-buffer
Index: man/building.texi
===================================================================
RCS file: /sources/emacs/emacs/man/building.texi,v
retrieving revision 1.109
diff -c -r1.109 building.texi
*** man/building.texi	7 Oct 2006 23:38:51 -0000	1.109
--- man/building.texi	23 Nov 2006 16:29:17 -0000
***************
*** 827,838 ****
  
  @vindex gud-gdb-command-name
  @findex gdba
!   You can also run GDB in text command mode, like other debuggers.  To
! do this, set @code{gud-gdb-command-name} to @code{"gdb --fullname"} or
! edit the startup command in the minibuffer to say that.  You need to
! do use text command mode to run multiple debugging sessions within one
! Emacs session.  If you have customized @code{gud-gdb-command-name} in
! that way, you can use @kbd{M-x gdba} to invoke GDB in graphical mode.
  
  @menu
  * GDB-UI Layout::               Control the number of displayed buffers.
--- 827,845 ----
  
  @vindex gud-gdb-command-name
  @findex gdba
!   You can also run GDB in text command mode, like other debuggers.
! Emacs automatically switches to GUI mode if it sees annotations in the
! gdb output.  GDB generates annotations when started with the command
! line option @code{"--annotate=3"}, which is set by default in
! @code{gud-gdb-command-name}.  To run in text mode, you must customize
! @code{gud-gdb-command-name} to delete this option, or delete it from
! the startup command in the minibuffer.
! 
! You need to use text command mode for the first and subsequent
! debugging sessions if you plan to run multiple debugging sessions
! within one Emacs session. If you have customized
! @code{gud-gdb-command-name} in that way, you can specify
! @code{"--annotate=3"} to invoke GDB in graphical mode.
  
  @menu
  * GDB-UI Layout::               Control the number of displayed buffers.

[-- Attachment #3: Type: text/plain, Size: 15 bytes --]


-- 
-- Stephe

[-- Attachment #4: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: Starting multiple GUD session; doc problem

[Nick Roberts]

Stephen Leake writes:
 > I just tried to start two gdb sessions in one CVS Emacs session for
 > the first time (I've done this many times in Emacs 21). I got the
 > error message:
 > 
 >  "gdb: Multiple debugging is only supported with "gdb --fullname"
 > 
 > So I dutifully added "--fullname" to the gdb command line:
 >
 >     gdb --annotate=3 --fullname gds-main_models_test.exe 

Well, I'm not sure that's dutiful, it means start with "gdb --fullname"
_instead of_ "gdb --annotate=3" but if other's find it ambiguous too
I'll change it.

 > and got the same error message. I read the GUD and GDB entries in the
 > Emacs manual, and the help message for `gdb'; no success.

Was this not clear:

    You can also run GDB in text command mode, like other debuggers.  To
 do this, set `gud-gdb-command-name' to `"gdb --fullname"' or edit the
 startup command in the minibuffer to say that.  You need to do use text
 command mode to run multiple debugging sessions within one Emacs
 session.

 >                                                            Finally I
 > read the Emacs lisp source code for gud, and found this comment in
 > gud.el (gud-gdb-marker-filter):
 > 
 >     ;; Check for annotations and change gud-minor-mode to 'gdba if
 >     ;; they are found.

This comment is not for users.

 > It seems the real issue is the presence or absence of "--annotate=3",
 > not the presence of "--fullname". In fact, "--fullname" is not
 > necessary if compilation-search-path is set to include the source
 > directories.

That's not true.  If "--annotate=3" is not used the option "--fullname" is
necessary for the Emacs to display the current line in the source buffer.

 > So I suggest the attached patch to the Emacs manual (building.texi)
 > and a couple gud doc strings.
 >...

 >   ;;;###autoload
 >   (defun gdba (command-line)
 > !   "Run gdb on program FILE in buffer *gud-FILE*.
 >   The directory containing FILE becomes the initial working directory
 >   and source-file directory for your debugger.
 >   
 > --- 214,220 ----
 >   
 >   ;;;###autoload
 >   (defun gdba (command-line)
 > !   "Run gdb in GUI mode on program FILE in buffer *gud-FILE*.
 >   The directory containing FILE becomes the initial working directory
 >   and source-file directory for your debugger.

The current doc string goes on to explain what how this function lays out the
buffers.  To the first time user what would GUI mode mean?

The other changes are wrong because "--fullname" is needed.  Perhaps some
confusion arises over the term "text command mode".  It refers to the way that
it works in Emacs 21: GUD buffer + source buffer.  Perhaps you think it means
just GUD buffer i.e like the command line in a terminal.  Perhaps it would help
to refer to "text command mode" in the section "Debugger Operation" (it
currently says "using the textual interface").


-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: Starting multiple GUD session; doc problem

[Stephen Leake]

[-- Attachment #1: Type: text/plain, Size: 4162 bytes --]

Nick Roberts <nickrob@snap.net.nz> writes:

> Stephen Leake writes:
>  > I just tried to start two gdb sessions in one CVS Emacs session for
>  > the first time (I've done this many times in Emacs 21). I got the
>  > error message:
>  > 
>  >  "gdb: Multiple debugging is only supported with "gdb --fullname"
>  > 
>  > So I dutifully added "--fullname" to the gdb command line:
>  >
>  >     gdb --annotate=3 --fullname gds-main_models_test.exe 
>
> Well, I'm not sure that's dutiful, it means start with "gdb --fullname"
> _instead of_ "gdb --annotate=3" but if other's find it ambiguous too
> I'll change it.

Since the info manual never mentions "--annotate=3", I thought it was
always necessary. So yes, I found it ambiguous.

>  > It seems the real issue is the presence or absence of "--annotate=3",
>  > not the presence of "--fullname". In fact, "--fullname" is not
>  > necessary if compilation-search-path is set to include the source
>  > directories.
>
> That's not true.  If "--annotate=3" is not used the option "--fullname" is
> necessary for the Emacs to display the current line in the source
> buffer.

"--fullname" provides path information for source files. Apparently
"--annotate=3" also provides that, but in a different way. 

But I run "gdb" without "--fullname" all the time in Emacs 21. I
thought that meant gud was searching the directory path in
compilation-search-path. 

However, testing on Emacs 22, I see the --fullname is required now.

> The current doc string goes on to explain what how this function
> lays out the buffers. To the first time user what would GUI mode
> mean?

Good point. On the other hand, the first sentence in 32.6.5 mentions a
"graphical interface"; so that would be a good place to define "GUI
mode".

> The other changes are wrong because "--fullname" is needed. Perhaps
> some confusion arises over the term "text command mode". It refers
> to the way that it works in Emacs 21: GUD buffer + source buffer.

Right, I did understand that. "gdb --fullname" works the same in Emacs
22 as "gdb" in Emacs 21, and that is the behavior I was expecting. In
particular, I don't have to do anything special to get two debugging
sessions.

At the same time, if you don't customize 'gdb-many-windows', "gdb
--annotate=3" in Emacs 22 also works the same as "gdb" in Emacs 21,
except that it doesn't allow multiple debugging sessions. So that's
why I was surprised by this.

GUI mode (with 'gdb-many-windows' t) adds a fancy display (which I
find annoying; I prefer my screen real estate to show actual code :).
It also adds tooltips for viewing variables, which is very nice.

(aside; I don't understand why the tooltips are not available in "text
command mode". Is "--annotate" required to get tooltip variable values?)

> Perhaps it would help to refer to "text command mode" in the section
> "Debugger Operation" (it currently says "using the textual
> interface").

Yes, that would help.

Hmm. The first paragraph there says the program input and output is
via the GUD buffer, in text command mode. However, it doesn't say
where they are in GUI mode; are there separate buffers for that? Hmm.
I just tried it, and the answer seems to be "no"; stdin and stdout are
still mixed in the GUD buffer in GUI mode. Perhaps there is another
variable to customize? I'm running GNU gdb 5.3 for GNAT Pro 5.04a
(20060125), compiling Ada code.

So the discussion of debugger input/output and program input/output is
correct whether in GUI mode or text command mode.

If it was totally up to me, I'd make "M-x gdb" in Emacs 22 do "gdb
--fullname" by default, since that is closest to the Emacs 21 behavior
(it allows multiple debugging sessions). To get the GUI mode, you
would do "M-x gdba". (And that's how I've customized things in my
.emacs).

That means people would have to read the manual to know about the GUI
mode. But that is the case now anyway; you have to set
'gdb-many-windows' to get the GUI mode multiple windows display when
starting with "M-x gdb", and you have to read the manual to know that.
You also have to read the manual to know about the additional mouse
bindings. 

I've attached an updated patch.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: gud.diff --]
[-- Type: text/x-patch, Size: 6443 bytes --]

Index: lisp/progmodes/gdb-ui.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/progmodes/gdb-ui.el,v
retrieving revision 1.191
diff -c -r1.191 gdb-ui.el
*** lisp/progmodes/gdb-ui.el	10 Nov 2006 09:38:11 -0000	1.191
--- lisp/progmodes/gdb-ui.el	25 Nov 2006 13:19:16 -0000
***************
*** 214,220 ****
  
  ;;;###autoload
  (defun gdba (command-line)
!   "Run gdb on program FILE in buffer *gud-FILE*.
  The directory containing FILE becomes the initial working directory
  and source-file directory for your debugger.
  
--- 214,220 ----
  
  ;;;###autoload
  (defun gdba (command-line)
!   "Run gdb in GUI mode on program FILE in buffer *gud-FILE*.
  The directory containing FILE becomes the initial working directory
  and source-file directory for your debugger.
  
Index: lisp/progmodes/gud.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/progmodes/gud.el,v
retrieving revision 1.116
diff -c -r1.116 gud.el
*** lisp/progmodes/gud.el	5 Sep 2006 03:40:54 -0000	1.116
--- lisp/progmodes/gud.el	25 Nov 2006 13:19:19 -0000
***************
*** 680,687 ****
  default this command starts GDB using a graphical interface.  See
  `gdba' for more information.
  
! To run GDB in text command mode, set `gud-gdb-command-name' to
! \"gdb --fullname\" and include the pathname, if necessary."
    (interactive (list (gud-query-cmdline 'gdb)))
  
    (if (and gud-comint-buffer
--- 680,687 ----
  default this command starts GDB using a graphical interface.  See
  `gdba' for more information.
  
! To run GDB in text command mode, delete \"--annotate=3\" from
! `gud-gdb-command-name', and add \"--fullname\"."
    (interactive (list (gud-query-cmdline 'gdb)))
  
    (if (and gud-comint-buffer
Index: man/building.texi
===================================================================
RCS file: /sources/emacs/emacs/man/building.texi,v
retrieving revision 1.109
diff -c -r1.109 building.texi
*** man/building.texi	7 Oct 2006 23:38:51 -0000	1.109
--- man/building.texi	25 Nov 2006 13:19:21 -0000
***************
*** 536,545 ****
  @subsection Debugger Operation
  
  @cindex fringes, and current execution line in GUD
!   When you run a debugger with GUD using the textual interface, 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.
  
    The debugger displays the source files of the program by visiting
  them in Emacs buffers.  An arrow in the left fringe indicates the
--- 536,545 ----
  @subsection Debugger Operation
  
  @cindex fringes, and current execution line in GUD
!   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.
  
    The debugger displays the source files of the program by visiting
  them in Emacs buffers.  An arrow in the left fringe indicates the
***************
*** 815,838 ****
  
    By default, the command @code{gdb} starts GDB using a graphical
  interface, using Emacs windows for display program state information.
! In effect, this makes Emacs into an IDE (interactive development
! environment).  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.
  
  @vindex gud-gdb-command-name
  @findex gdba
!   You can also run GDB in text command mode, like other debuggers.  To
! do this, set @code{gud-gdb-command-name} to @code{"gdb --fullname"} or
! edit the startup command in the minibuffer to say that.  You need to
! do use text command mode to run multiple debugging sessions within one
! Emacs session.  If you have customized @code{gud-gdb-command-name} in
! that way, you can use @kbd{M-x gdba} to invoke GDB in graphical mode.
  
  @menu
  * GDB-UI Layout::               Control the number of displayed buffers.
--- 815,856 ----
  
    By default, the command @code{gdb} starts GDB using a graphical
  interface, using Emacs windows for display program state information.
! This is called ``GUI mode''. In effect, this makes Emacs into an IDE
! (interactive development environment). 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.
! 
!   To display the program state information windows, you must set the
! variable @code{gdb-many-windows} to non-@code{nil}. Or you can use the
! command @code{gdba} to start the debugger.
! 
!   You can also run GDB without the program state information windows;
! this also disables many of the mouse bindings that interact with the
! debugger. This is called ``text command mode''. 
! 
!   You need to use text mode for the first and subsequent debugging
! sessions if you plan to run multiple debugging sessions within one
! Emacs session.
  
  @vindex gud-gdb-command-name
  @findex gdba
!   Emacs automatically switches to GUI mode if it sees annotations in
! the gdb output. GDB generates annotations when started with the
! command line option @code{"--annotate=3"}, which is set by default in
! @code{gud-gdb-command-name}. To run in text mode, you must customize
! @code{gud-gdb-command-name} to delete this option, and specify
! @code{"--fullname"} instead. Or you can make this change in the
! startup command in the minibuffer.
! 
! If you have customized @code{gud-gdb-command-name} in that way, you
! can use @code{gdba} to invoke GDB in graphical mode; it uses the
! default command @code{gud-gdba-command-name}.
! 
!   GUI 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.
  
  @menu
  * GDB-UI Layout::               Control the number of displayed buffers.

[-- Attachment #3: Type: text/plain, Size: 15 bytes --]


-- 
-- Stephe

[-- Attachment #4: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: Starting multiple GUD session; doc problem

[Andreas Schwab]

Stephen Leake <stephen_leake@member.fsf.org> writes:

> "--fullname" provides path information for source files. Apparently
> "--annotate=3" also provides that, but in a different way. 

"--fullname" is the same as "--annotate=1 --nw".

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Starting multiple GUD session; doc problem

[Richard Stallman]

Nick, would you please install that change if it is correct?
It does make things clearer.  But there are a few little
points that ought to be changed.

    ! You need

Please indent the start of the paragraph; that's our style for
Texinfo source text outside of major constructs.

	       to use text command mode for the first and subsequent
    ! debugging sessions

Would it be just as correct to say "for all debugging sessions"?

			 if you plan to run multiple debugging sessions
    ! within one Emacs session. If you have customized

Please put two spaces after the end of a sentence.

Re: Starting multiple GUD session; doc problem

[Nick Roberts]

 > >  > I just tried to start two gdb sessions in one CVS Emacs session for
 > >  > the first time (I've done this many times in Emacs 21). I got the
 > >  > error message:
 > >  > 
 > >  >  "gdb: Multiple debugging is only supported with "gdb --fullname"
 > >  > 
 > >  > So I dutifully added "--fullname" to the gdb command line:
 > >  >
 > >  >     gdb --annotate=3 --fullname gds-main_models_test.exe 
 > >
 > > Well, I'm not sure that's dutiful, it means start with "gdb --fullname"
 > > _instead of_ "gdb --annotate=3" but if other's find it ambiguous too
 > > I'll change it.
 > 
 > Since the info manual never mentions "--annotate=3", I thought it was
 > always necessary. So yes, I found it ambiguous.

I guess it presupposes a knowledge of "--fullname" and "--annotate=3".  Ideally
it would mention neither but give the user the option of switching between
the two in terms of their functionality.

 > But I run "gdb" without "--fullname" all the time in Emacs 21. I
 > thought that meant gud was searching the directory path in
 > compilation-search-path. 

It gets added by Emacs, it's just not displayed in the minibuffer.  See
gud-gdb-massage-args.

 > However, testing on Emacs 22, I see the --fullname is required now.
 > 
 > > The current doc string goes on to explain what how this function
 > > lays out the buffers. To the first time user what would GUI mode
 > > mean?
 > 
 > Good point. On the other hand, the first sentence in 32.6.5 mentions a
 > "graphical interface"; so that would be a good place to define "GUI
 > mode".
 > 
 > > The other changes are wrong because "--fullname" is needed. Perhaps
 > > some confusion arises over the term "text command mode". It refers
 > > to the way that it works in Emacs 21: GUD buffer + source buffer.
 > 
 > Right, I did understand that. "gdb --fullname" works the same in Emacs
 > 22 as "gdb" in Emacs 21, 

They work the same because they _are_ the same i.e. both use --fullname.

 >                         and that is the behavior I was expecting. In
 > particular, I don't have to do anything special to get two debugging
 > sessions.
 >
 > At the same time, if you don't customize 'gdb-many-windows', "gdb
 > --annotate=3" in Emacs 22 also works the same as "gdb" in Emacs 21,
 > except that it doesn't allow multiple debugging sessions. So that's
 > why I was surprised by this.

I've arranged so that it starts up the same way.  However it has much more
functionality.  If you create a breakpoint a red bullet is placed in the
fringe/margin so you don't have to remember where your breakpoints are.  You
can view the stack, examine watch expressions, manipulate breakpoints...


 > GUI mode (with 'gdb-many-windows' t) adds a fancy display (which I
 > find annoying; I prefer my screen real estate to show actual code :).

Many people like to set gdb-many-windows to t but the default value is nil
If you don't want to use it, don't change it's value.

 > It also adds tooltips for viewing variables, which is very nice.

GUD Tooltips are available for Emacs 21 but they are rather awkwad to turn on
and off.

 > (aside; I don't understand why the tooltips are not available in "text
 > command mode". Is "--annotate" required to get tooltip variable values?)

The section Debugger Operation says

      GUD tooltips are disabled when you use GDB in text command mode
   (*note 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.

 > > Perhaps it would help to refer to "text command mode" in the section
 > > "Debugger Operation" (it currently says "using the textual
 > > interface").
 > 
 > Yes, that would help.

I think "text command mode" and textual interface (and graphical interface)
are RMS' terms.  Let's see what he thinks.

 > Hmm. The first paragraph there says the program input and output is
 > via the GUD buffer, in text command mode. However, it doesn't say
 > where they are in GUI mode;

That's because the graphical interface is described in a later section

 >                              are there separate buffers for that? Hmm.
 > I just tried it, and the answer seems to be "no";

The answer is yes.  See GDB User Interface Layout

 >                                                   stdin and stdout are
 > still mixed in the GUD buffer in GUI mode. Perhaps there is another
 > variable to customize?

gdb-use-separate-io-buffer.  See Other GDB-UI Buffers.  I think it's only fair
that you read what is in the manual first.

 >                         I'm running GNU gdb 5.3 for GNAT Pro 5.04a
 > (20060125), compiling Ada code.

5.3 sounds old to me.  Even if you use FSF GDB (6.6 shortly) you should be
able to debug Ada code.  I've even tested expanding/contracting arrays
as watch expressions in the speedbar.

 >...
 > If it was totally up to me, I'd make "M-x gdb" in Emacs 22 do "gdb
 > --fullname" by default, since that is closest to the Emacs 21 behavior
 > (it allows multiple debugging sessions).

Fortunately it's not up to you.  The aim of Emacs 22 is to improve upon
Emacs 21 not emulate it.  Could you please experiment with the new
features and report your findings so that we can improve it further.

 >                                            To get the GUI mode, you
 > would do "M-x gdba". (And that's how I've customized things in my
 > .emacs).
 > 
 > That means people would have to read the manual to know about the GUI
 > mode.

The default behaviour is generally the one which is most useful.

 >        But that is the case now anyway; you have to set
 > 'gdb-many-windows' to get the GUI mode multiple windows display when
 > starting with "M-x gdb",

Other buffers can be displayed manually from the menu bar without setting it.

 >                         and you have to read the manual to know that.
 > You also have to read the manual to know about the additional mouse
 > bindings. 

It is true that you need to read the manual to understand the new features,
and that's not a bad thing, but I think many are fairly intuitive if you
have experience of graphical debuggers.

 > I've attached an updated patch.

Please don't.  There's currently no consensus that your changes are the
right ones.

-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: Starting multiple GUD session; doc problem

[Nick Roberts]

 > Nick, would you please install that change if it is correct?
 > It does make things clearer.  But there are a few little
 > points that ought to be changed.
 >...

I've made other changes to the gdb documentation string/error message and Emacs
manual to try to address some of the points Stephen made.

Stephen, do they make things clearer?

-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: Starting multiple GUD session; doc problem

[Stephen Leake]

Nick Roberts <nickrob@snap.net.nz> writes:

>  > Nick, would you please install that change if it is correct?
>  > It does make things clearer.  But there are a few little
>  > points that ought to be changed.
>  >...
>
> I've made other changes to the gdb documentation string/error
> message and Emacs manual to try to address some of the points
> Stephen made.
>
> Stephen, do they make things clearer?

Yes, thank you. 

This is good enough for the release, but I may come back later for
more :).

-- 
-- Stephe

Re: Starting multiple GUD session; doc problem

[Stephen Leake]

Nick Roberts <nickrob@snap.net.nz> writes:

>  > Since the info manual never mentions "--annotate=3", I thought it was
>  > always necessary. So yes, I found it ambiguous.
>
> I guess it presupposes a knowledge of "--fullname" and
> "--annotate=3". 

Yes.

> Ideally it would mention neither but give the user the option of
> switching between the two in terms of their functionality.

Yes. Maybe after the release.

>  >                         and that is the behavior I was expecting. In
>  > particular, I don't have to do anything special to get two debugging
>  > sessions.
>  >
>  > At the same time, if you don't customize 'gdb-many-windows', "gdb
>  > --annotate=3" in Emacs 22 also works the same as "gdb" in Emacs 21,
>  > except that it doesn't allow multiple debugging sessions. So that's
>  > why I was surprised by this.
>
> I've arranged so that it starts up the same way. However it has much
> more functionality. If you create a breakpoint a red bullet is
> placed in the fringe/margin so you don't have to remember where your
> breakpoints are. 

That is nice.

> You can view the stack, examine watch expressions, manipulate
> breakpoints...

You can do all that with text command mode as well. But with GUI mode,
you can do it with only the mouse, and all of the results are always
visible. It's a trade of screen usage between showing program state
and program source, and of mouse vs keyboard. It is nice to have the
choice.

>  > (aside; I don't understand why the tooltips are not available in "text
>  > command mode". Is "--annotate" required to get tooltip variable values?)
>
> The section Debugger Operation says
>
>       GUD tooltips are disabled when you use GDB in text command mode
>    (*note 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.

Ok. I'm mostly using Ada, which doesn't have macros. So perhaps after
the release we could explore relaxing that restriction for Ada (and
other languages where it would be safe).

I _often_ run two debugging sessions, to find the difference between
two programs (one that works and one that doesn't). Running them in
separate Emacs sessions is dangerous, because they usually share lots
of code, and I don't want to risk editing the same file in two
different Emacs sessions. (This is one area where Emacs is better than
other IDEs.) So I'd like to have as many debugger features as possible
while running two debugging sessions.

I'll go read the manual more thoroughly now :).

-- 
-- Stephe