[rfa/doc] Document interpreters

[Andrew Cagney <ac131313@redhat.com>]

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

Hello,

This documents the various interpreters that GDB supports.

(eli, you've seen approved an earlier version.  I did tweak it a tiny 
bit though - removed reference to mi0 and updated descriptions of mi1/mi2.)

ok?
Andrew

[-- Attachment #2: diffs --]
[-- Type: text/plain, Size: 4059 bytes --]

2003-02-04  Andrew Cagney  <ac131313@redhat.com>

	From 2003-02-04 Keith Seitz <keiths@redhat.com>:
	* gdb.texinfo (Interpreters): New chapter.  Refer the command-line
	option "-i"/"--interpreter" to this chapter.  Include index
	entries.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.145
diff -u -r1.145 gdb.texinfo
--- gdb.texinfo	1 Feb 2003 20:51:06 -0000	1.145
+++ gdb.texinfo	4 Feb 2003 17:28:43 -0000
@@ -146,6 +146,7 @@
 * Controlling GDB::             Controlling @value{GDBN}
 * Sequences::                   Canned sequences of commands
 * TUI::                         @value{GDBN} Text User Interface
+* Interpreters::		Command Interpreters
 * Emacs::                       Using @value{GDBN} under @sc{gnu} Emacs
 * Annotations::                 @value{GDBN}'s annotation interface.
 * GDB/MI::                      @value{GDBN}'s Machine Interface.
@@ -1123,7 +1124,8 @@
 @cindex @code{--interpreter}
 Use the interpreter @var{interp} for interface with the controlling
 program or device.  This option is meant to be set by programs which
-communicate with @value{GDBN} using it as a back end.
+communicate with @value{GDBN} using it as a back end. @xref{Interpreters, ,
+Command Interpreters}.
 
 @samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes
 @value{GDBN} to use the current @dfn{@sc{gdb/mi} interface}
@@ -13219,6 +13221,68 @@
 string are the simple ones that consist of backslash followed by a
 letter.
 @end table
+
+@node Interpreters
+@chapter Command Interpreters
+@cindex command interpreters
+
+@value{GDBN} supports multiple command interpreters, and some command
+infrastructure to allow users or user interface writers to switch
+between interpreters or run commands in other interpreters.
+
+@value{GDBN} currently supports two command interpreters, the console
+interpreter (sometimes called the command-line interpreter or @sc{cli})
+and the machine interface interpreter (or @sc{gdb/mi}).  This manual
+describes both of these interfaces in great detail.
+
+By default, @value{GDBN} will start with the console interpreter.
+However, the user may choose to start @value{GDBN} with another
+interpreter by specifying the @option{-i} or @option{--interpreter}
+startup options.  Defined interpreters include:
+
+@table @code
+@item console
+@cindex console interpreter
+The traditional console or command-line interpreter.  This is the most often
+used interpreter with @value{GDBN}. With no interpreter specified at runtime,
+@value{GDBN} will use this interpreter.
+
+@item mi
+@cindex mi interpreter
+The newest @sc{gdb/mi} interface (currently @code{mi2}).  Used primarily
+by programs wishing to use @value{GDBN} as a backend for a debugger GUI
+or an IDE.  For more information, see @ref{GDB/MI, ,The @sc{gdb/mi}
+Interface}.
+
+@item mi2
+@cindex mi2 interpreter
+The current @sc{gdb/mi} interface.
+
+@item mi1
+@cindex mi1 interpreter
+The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3.
+
+@end table
+
+@cindex invoke another interpreter
+The interpreter being used by @value{GDBN} may not be dynamically switched at
+runtime.  Although possible, this could lead to a very precarious situation.
+Consider an IDE using @sc{gdb/mi}. If a user enters the command
+"interpreter-set console" in a console view, @value{GDBN} would switch
+to using the console interpreter, rendering the IDE inoperable!
+
+@kindex interpreter-exec
+Although you may only choose a single interpreter at startup, you may execute
+commands in any interpreter from the current interpreter using the appropriate
+command.  If you are running the console interpreter, simply use the
+@code{interpreter-exec} command:
+
+@smallexample
+interpreter-exec mi "-data-list-register-names"
+@end smallexample
+
+@sc{gdb/mi} has a similar command, although it is only available in versions of
+@value{GDBN} which support @sc{gdb/mi} version 2 (or greater).
 
 @node TUI
 @chapter @value{GDBN} Text User Interface