CLI and GDB/MI documentation patch

[Bob Rossi <bob_rossi@cox.net>]

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

Hi all,

I hope this looks correct. Please let me know otherwise. I think it's 
an improvement over what is there now, and could save others valuable
research time.

Bob Rossi

[-- Attachment #2: gdb.texinfo.diff --]
[-- Type: text/plain, Size: 3882 bytes --]

Index: ChangeLog
===================================================================
RCS file: /cvs/src/src/gdb/doc/ChangeLog,v
retrieving revision 1.575
diff -u -r1.575 ChangeLog
--- ChangeLog	5 May 2006 22:48:14 -0000	1.575
+++ ChangeLog	12 May 2006 01:15:02 -0000
@@ -1,3 +1,8 @@
+2006-05-11  Bob Rossi  <bob_rossi@cox.net>
+
+	* gdb.texinfo (GDB/MI Compatibility with CLI): Document how CLI
+	commands and GDB/MI interface.
+
 2006-05-05  Jim Blandy  <jimb@codesourcery.com>
 
 	* gdb.texinfo (General Query Packets): Document conventions for
Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.328
diff -u -r1.328 gdb.texinfo
--- gdb.texinfo	5 May 2006 22:48:14 -0000	1.328
+++ gdb.texinfo	12 May 2006 01:15:05 -0000
@@ -17377,16 +17377,43 @@
 
 @cindex compatibility, @sc{gdb/mi} and CLI
 @cindex @sc{gdb/mi}, compatibility with CLI
-To help users familiar with @value{GDBN}'s existing CLI interface, @sc{gdb/mi}
-accepts existing CLI commands.  As specified by the syntax, such
-commands can be directly entered into the @sc{gdb/mi} interface and @value{GDBN} will
-respond.
-
-This mechanism is provided as an aid to developers of @sc{gdb/mi}
-clients and not as a reliable interface into the CLI.  Since the command
-is being interpreteted in an environment that assumes @sc{gdb/mi}
-behaviour, the exact output of such commands is likely to end up being
-an un-supported hybrid of @sc{gdb/mi} and CLI output.
+Initially, the @sc{gdb/mi} interface accepted CLI commands to help users
+familiar with @value{GDBN}'s existing CLI interface.  As specified by the 
+syntax, such commands can be directly entered into the @sc{gdb/mi} interface 
+and @value{GDBN} will respond.
+
+This mechanism was originally provided as an aid to developers of @sc{gdb/mi}
+clients and not as a reliable interface into the CLI. The output of these
+commands were likely to end up being an un-supported hybrid of @sc{gdb/mi} 
+and CLI output.  This was the case until some time in the @sc{gdb/mi} version
+2 protocol.
+
+Somewhere in the @sc{gdb/mi} version 2 protocol, the command 
+@code{-interpreter-exec} was added to @value{GDBN}.  This provided the 
+capability to allow @sc{gdb/mi} clients to execute CLI commands in a way 
+that would provide supported @sc{gdb/mi} output.  Since this feature was 
+so useful, and @sc{gdb/mi} clients historically passed CLI commands directly 
+into the @sc{gdb/mi} interface, @value{GDBN} was modified to accept CLI 
+commands directly into the @sc{gdb/mi} interpreter.  @value{GDBN} takes
+the CLI command, and internally uses the @code{-interpreter-exec} @sc{gdb/mi}
+command to ensure that the CLI command the user passed in has supported 
+@sc{gdb/mi} output.
+
+So, entering CLI commands directly into the @sc{gdb/mi} interpreter is now
+essentially the same as using the @sc{gdb/mi} @code{-interpreter-exec} 
+command.  There may be a small difference in the @sc{gdb/mi} output between 
+directly typing the CLI command into the @sc{gdb/mi} interpreter or by using 
+the @code{-interpreter-exec} command, however, both ways should provide 
+valid @sc{gdb/mi} output.
+
+One current major difference between entering a CLI command directly into
+the @sc{gdb/mi} interpreter and entering the corresponding @sc{gdb/mi} 
+command into the interpreter is that the CLI command will not have the 
+asynchronous output that the @sc{gdb/mi} command will have. For instance,
+typing @code{run} as a CLI command, you will not get the @code{*stopped}
+response that @sc{gdb/mi} will provide if you enter the @code{-exec-run}
+command.  This is currently considered a limitation of @sc{gdb/mi} that 
+will be fixed in future versions of @value{GDBN}.
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Output Records