* gdb.texinfo: Add chapter on interpreters. Refer the

        command-line option "-i"/"--interpreter" to this chapter.

2 files changed, 62 insertions, 6 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index b9d82f09765..a74863fffbb 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,8 @@
+2002-08-28  Keith Seitz  <keiths@redhat.com>
+
+	* gdb.texinfo: Add chapter on interpreters. Refer the
+	command-line option "-i"/"--interpreter" to this chapter.
+
 2002-08-08  Grace Sainsbury  <graces@redhat.com>
 
 	From Mark Salter:            
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index dd5e7aa3c6e..99bf767d195 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1122,12 +1122,8 @@ Do not use this option if you run @value{GDBN} from Emacs
 @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.
-
-@samp{--interpreter=mi} (or @samp{--interpreter=mi1}) causes
-@value{GDBN} to use the @dfn{gdb/mi interface} (@pxref{GDB/MI, , The
-@sc{gdb/mi} Interface}). The older @sc{gdb/mi} interface, included in
-@value{GDBN} version 5.0 can be selected with @samp{--interpreter=mi0}.
+communicate with @value{GDBN} using it as a back end. @xref{Interpreters, ,
+Command Interpreters}.
 
 @item -write
 @cindex @code{--write}
@@ -13079,6 +13075,61 @@ string are the simple ones that consist of backslash followed by a
 letter.
 @end table
 
+@node Interpreters
+@chapter 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 "-i" or "--interpreter" startup options.  Defined interpreters include:
+
+@table @code
+@item console
+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
+The newest @sc{gdb/mi} interface, 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
+The latest version of the @sc{gdb/mi} interface.
+
+@item mi1
+The @sc{gdb/mi} version included in @value{GDBN} version 5.1.
+
+@item mi0
+The @sc{gdb/mi} version included in @value{GDBN} version 5.0.
+@end table
+
+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!
+
+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
 @cindex TUI