Re: {PATCH] MI Doco [was Re: CLI and GDB/MI...]

[Bob Rossi <bob_rossi@cox.net>]

On Tue, May 30, 2006 at 07:16:43PM +1200, Nick Roberts wrote:
>  > >                          ...We did start to talk about what changes could
>  > > be made within one level: new commands, extra fields etc which I think we
>  > > need to document so that developers know what to expect.  I think at some
>  > > stage we should also document our thoughts changing MI level.
>  > 
>  > I invite you :-)
> 
> OK, here's something along these lines.  Its a bit incomplete but it might
> be good to put something in now, and develop it as our ideas crystallise.
> 
> I must say I don't like the term "front end" (or "back end").  It makes
> me think of all those Carry On films I watched as a child!

What terminology would you prefer? I don't mind this terminology much.

> *** gdb.texinfo	30 May 2006 18:30:35 +1200	1.332
> --- gdb.texinfo	30 May 2006 19:13:48 +1200	
> ***************
> *** 17215,17221 ****
>   in the form of a reference manual.
>   
>   Note that @sc{gdb/mi} is still under construction, so some of the
> ! features described below are incomplete and subject to change.
>   
>   @unnumberedsec Notation and Terminology
>   
> --- 17215,17222 ----
>   in the form of a reference manual.
>   
>   Note that @sc{gdb/mi} is still under construction, so some of the
> ! features described below are incomplete and subject to change
> ! (@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}).  
>   
>   @unnumberedsec Notation and Terminology
>   
> ***************
> *** 17246,17259 ****
>   @heading Dependencies
>   @end ignore
>   
> - @heading Acknowledgments
> - 
> - In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
> - Elena Zannoni.
> - 
>   @menu
>   * GDB/MI Command Syntax::
>   * GDB/MI Compatibility with CLI::
>   * GDB/MI Output Records::
>   * GDB/MI Command Description Format::
>   * GDB/MI Breakpoint Table Commands::
> --- 17247,17256 ----
>   @heading Dependencies
>   @end ignore
>   
>   @menu
>   * GDB/MI Command Syntax::
>   * GDB/MI Compatibility with CLI::
> + * GDB/MI Development and Front Ends::
>   * GDB/MI Output Records::
>   * GDB/MI Command Description Format::
>   * GDB/MI Breakpoint Table Commands::
> ***************
> *** 17571,17576 ****
> --- 17568,17624 ----
>   an un-supported hybrid of @sc{gdb/mi} and CLI output.
>   
>   @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
> + @node GDB/MI Development and Front Ends
> + @section @sc{gdb/mi} Development and Front Ends
> + 
> + The application which takes the MI output and presents the state of the
> + program being debugged to the user is called a @dfn{front end}.
> + 
> + Although @sc{gdb/mi} is still incomplete, it is currently being used
> + by a variety of front ends to @value{GDBN}.  This makes it difficult
> + to introduce new functionality without breaking existing usage.  This
> + section tries to minimise the problems by describing how the protocol
> + might change.

I think it would be nice to describe the difference between changing the
MI syntax verses changing the MI commands. For instance, a change to the
syntax will either force the FE to create a new generated parser, or to
create a parser (mi3) that is a superset of the old parser (mi2).
Obviously you described nicely the changes to the MI commands below.

> + Some changes in MI need not break a carefully designed front end, and
> + for these the MI version will remain unchanged.  The following is a
> + list of changes that may occur within one level, so front ends should
> + parse MI output in a way that can handle them:

I think 'may occur within one level' would be better as 'may occur
between two different version of the MI protocol' would be clearer, but
that's just me.

Other than that, looks pretty good to me!

Bob Rossi