Re: [RFC/doc] Interpreters documentation

[Eli Zaretskii <eliz@is.elta.co.il>]

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