[RFC/doc] Interpreters documentation

[RFC/doc] Interpreters documentation

[Keith Seitz]

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

Re: [RFC/doc] Interpreters documentation

[Eli Zaretskii]

On Wed, 28 Aug 2002, Keith Seitz wrote:

> This is the small documentation that I have regarding interpreters in gdb. 

Thanks.

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

Your Texinfo is very good, so nothing to be ashamed of.  I have a few 
minor comments, mostly about indexing.  Otherwise, this patch is 
approved.

> + @node Interpreters
> + @chapter Command Interpreters

It is usually a good idea to have an index entry for each chapter or 
section whose name is the same as the chapter or section name:

  @cindex command interpreters

This is especially true when the chapter/section name is a meaningful 
term, like in this case.  With that index entry, users can easily get to 
the chapter by typing "i command interpreter" int the Info reader 
(instead of looking up the subject in the table of contents), which is 
important for someone who uses the manual as a reference.

> + 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.

Command-line options should have the @option markup:

   by specifying the @option{-i} or @option{--interpreter} startup 
   options.

> + @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.

It is a good idea to put a "@cindex console interpreter" right after the 
@item.

> + @item mi
> + The newest @sc{gdb/mi} interface, used primarily by programs wishing to use

Same here for the MI interpreter (and for the other ones as well).

> + 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:

This might benefit from an index entry as well.  For example:

  @cindex invoke another interpreter

Is interpreter-exec documented elsewhere in the manual (I cannot find it 
in my sandbox, but maybe I'm not up-to-date)?  If not, you should add a 
@kindex entry here (we have a @kindex for every GDB command).

Re: [RFC/doc] Interpreters documentation

[Keith Seitz]

On Thu, 29 Aug 2002, Eli Zaretskii wrote:

[snip suggestions]

See below patch, which is changed to previous patch

> Is interpreter-exec documented elsewhere in the manual (I cannot find it 
> in my sandbox, but maybe I'm not up-to-date)?  If not, you should add a 
> @kindex entry here (we have a @kindex for every GDB command).

interpreter-exec is a new command. It is mentioned in the gdbmi.texinfo 
file on the interpreter branch (which I have not yet submitted).

I appreciate your timely review of this -- thanks!
Keith

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.100.2.4
diff -p -r1.100.2.4 gdb.texinfo
*** gdb.texinfo	28 Aug 2002 19:01:18 -0000	1.100.2.4
--- gdb.texinfo	29 Aug 2002 18:35:39 -0000
*************** letter.
*** 13077,13082 ****
--- 13077,13083 ----
  
  @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
*************** both of these interfaces in great detail
*** 13089,13123 ****
  
  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
--- 13090,13132 ----
  
  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, 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 latest version of the @sc{gdb/mi} interface.
  
  @item mi1
+ @cindex mi1 interpreter
  The @sc{gdb/mi} version included in @value{GDBN} version 5.1.
  
  @item mi0
+ @cindex mi0 interpreter
  The @sc{gdb/mi} version included in @value{GDBN} version 5.0.
  @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

Re: [RFC/doc] Interpreters documentation

[Eli Zaretskii]

> Date: Thu, 29 Aug 2002 11:40:20 -0700 (PDT)
> From: Keith Seitz <keiths@redhat.com>
> 
> See below patch, which is changed to previous patch

Thanks, that's exactly what I had in mind.

> > Is interpreter-exec documented elsewhere in the manual (I cannot find it 
> > in my sandbox, but maybe I'm not up-to-date)?  If not, you should add a 
> > @kindex entry here (we have a @kindex for every GDB command).
> 
> interpreter-exec is a new command. It is mentioned in the gdbmi.texinfo 
> file on the interpreter branch (which I have not yet submitted).

Then please add a @pxref to the section in gdbmi.texinfo where this
command is documented in full.

Re: [RFC/doc] Interpreters documentation

[Keith Seitz]

On Fri, 30 Aug 2002, Eli Zaretskii wrote:

Sorry for the long delay, I misread this message...

> > > Is interpreter-exec documented elsewhere in the manual (I cannot find it 
> > > in my sandbox, but maybe I'm not up-to-date)?  If not, you should add a 
> > > @kindex entry here (we have a @kindex for every GDB command).
> > 
> > interpreter-exec is a new command. It is mentioned in the gdbmi.texinfo 
> > file on the interpreter branch (which I have not yet submitted).
> 
> Then please add a @pxref to the section in gdbmi.texinfo where this
> command is documented in full.

interpreter-exec is both an mi command and a console command. The 
interpreter chapter in the gdb manual (gdb.texinfo proper, that is), 
defines this command. I've added a @kindex for it where it is described. I 
can add a cross-reference to the equivalent MI command when I commit the 
MI changes (yes, this command is documented in gdbmi.texinfo, but only on 
the branch).

Here's what I've done, which admittedly is the path of least resistance 
(aka typing ;-).  Please make recommendation if you'd like to see 
something different.

Keith

[snip]
+ @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:
[snip]

Re: [RFC/doc] Interpreters documentation

[Eli Zaretskii]

On Fri, 6 Sep 2002, Keith Seitz wrote:

> I can add a cross-reference to the equivalent MI command when I commit the 
> MI changes (yes, this command is documented in gdbmi.texinfo, but only on 
> the branch).

Yes, please do.

> Here's what I've done, which admittedly is the path of least resistance 
> (aka typing ;-).  Please make recommendation if you'd like to see 
> something different.

It's okay to commit this, thanks.