[RFC/doc] Interpreters documentation

[Keith Seitz <keiths at redhat dot com>]

Hi,

This is the small documentation that I have regarding interpreters in gdb. 
(Okay, it's going to mention MI2 stuff, which hasn't been committed yet.)

Comments? Corrections? (I'm still a texinfo newbie.)

Keith

ChangeLog
2002-08-28  Keith Seitz  <keiths@redhat.com>

        * gdb.texinfo: Add chapter on interpreters. Refer the
        command-line option "-i"/"--interpreter" to this chapter.

Patch
Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.115
diff -p -r1.115 gdb.texinfo
*** doc/gdb.texinfo	25 Aug 2002 19:10:15 -0000	1.115
--- doc/gdb.texinfo	28 Aug 2002 20:48:32 -0000
*************** Do not use this option if you run @value
*** 1122,1133 ****
  @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}.
  
  @item -write
  @cindex @code{--write}
--- 1122,1129 ----
  @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. @xref{Interpreters, ,
! Command Interpreters}.
  
  @item -write
  @cindex @code{--write}
*************** The only backslash-escape sequences that
*** 13093,13098 ****
--- 13089,13149 ----
  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