Re: MI handshaking

[Bob Rossi <bob@brasko.net>]

On Fri, Nov 05, 2004 at 07:44:18PM +0200, Eli Zaretskii wrote:
> > Date: Fri, 5 Nov 2004 11:39:33 -0500
> > From: Bob Rossi <bob@brasko.net>
> > Cc: gdb-patches@sources.redhat.com
> > 
> > +@node GDB/MI Handshaking Syntax
> > +@subsection @sc{gdb/mi} Handshaking Syntax
> > +
> > +@cindex handshaking syntax for @sc{gdb/mi}
> > +@cindex @sc{gdb/mi}, handshaking syntax
> > +@table @code
> > +@item @var{handshake_output} @expansion{}
> > +@code{"handshake=@{stable_protocols=@{" @var{mi-protocol-list} 
> > +"@}" @var{nl}}
> 
> I think there's a need here for a cross-reference to the section that
> explains the reason and principles of the handshaking (the other
> section you wrote), otherwise this table looks awkwardly unexplained.

I think i did this correctly.
> > +It is possible to start the @sc{gdb/mi} interpreter using -i=mi1, -i=mi2, or 
> > +simply with -i=mi.
> 
> The command-line options should be in @samp{} or in @option{}, like
> this:
> 
>   It is possible to start the @sc{gdb/mi} interpreter using @samp{-i=mi1}

done
> 
> Actually, instead of using literal mi1 and mi2, which could confuse
> the reader into thinking that only MI1 and MI2 are supported (think
> about someone reading this 10 years from now), I'd say
> 
>   It is possible to start the @sc{gdb/mi} interpreter using
>   @samp{-i=mi@var{n}}, where @var{n} is the MI protocol version
>   (@pxref{Interpreters}).  When invoked with a specific version of the
>   MI interpreter, @value{GDBN} will bypass the handshaking mode and go
>   directly into...

done
> 
> > +then this tells @value{GDBN} to go into it's handshaking mode with the 
>                                            ^^^^
> This should be "its", without the apostrophe.
> 

done
> > +it supports.  The term "stable MI protocol" simply means that the protocol
> 
> Please use ``this style'' to quote phrases in Texinfo (the result is
> prettier in the printed version).  Actually, in this case, since you
> are introducing a new term, I'd suggest to say
> 
>   The term @dfn{stable MI protocol} simply means...
> 
> Also, a @cindex entry here about stable MI protocol would be useful.
> 

I think I did the cindex part right, but I don't really understand how
there used, or why.
> > +untested protocols, they could simply try to invoke @value{GDBN} with -i=miN,
> > +where N is version they wish to communicate with.
> 
> Please use @var{n} instead of a literal "N" here.
> 
> > +If a specific version of @value{GDBN} speaks only one stable MI protocol than
> 
> The last woprd should be "then", not "than".
> 

done
> > +versions of the MI protocol, than it will output a list of these protocols 
>                                 ^^^^
> Again, "then".
> 

done
> Other than these few minor problems, the documentation patch is
> approved.  Thanks.

I hope this resolves all of the issues you brought up. I really am not
good at editing info files but am trying to do my best to help out.

Bob Rossi

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.222
diff -w -u -r1.222 gdb.texinfo
--- gdb.texinfo	23 Oct 2004 15:05:29 -0000	1.222
+++ gdb.texinfo	5 Nov 2004 22:09:54 -0000
@@ -14997,6 +14997,7 @@
 @menu
 * GDB/MI Command Syntax::
 * GDB/MI Compatibility with CLI::
+* GDB/MI Handshaking Interface::
 * GDB/MI Output Records::
 * GDB/MI Command Description Format::
 * GDB/MI Breakpoint Table Commands::
@@ -15021,11 +15022,53 @@
 @section @sc{gdb/mi} Command Syntax
 
 @menu
+* GDB/MI Handshaking Syntax::
 * GDB/MI Input Syntax::
 * GDB/MI Output Syntax::
 * GDB/MI Simple Examples::
 @end menu
 
+@node GDB/MI Handshaking Syntax
+@subsection @sc{gdb/mi} Handshaking Syntax
+
+@cindex handshaking syntax for @sc{gdb/mi}
+@cindex @sc{gdb/mi}, handshaking syntax
+@table @code
+@item @var{handshake_output} @expansion{}
+@code{"handshake=@{stable_protocols=@{" @var{mi-protocol-list} 
+"@}" @var{nl}}
+
+@item @var{mi-protocol-list} @expansion{}
+@code{ epsilon | @var{mi-protocol} | @var{mi-protocol-list} "," @var{mi-protocol} }
+
+@item @var{mi-protocol} @expansion{}
+@code{ "mi" @var{token} }
+
+@item @var{token} @expansion{}
+"any sequence of digits"
+
+@item @var{nl} @expansion{}
+@code{CR | CR-LF}
+@end table
+
+@noindent
+Notes:
+
+@itemize @bullet
+@item
+If only one stable @sc{mi} protocol is supported by a particular release of 
+@value{GDBN}, then that release is used and the caller does not have to
+do anything.
+
+@item
+If there is more than one stable @sc{mi} protocol supported by a particular 
+release of @value{GDBN}, then the caller has to specify which version of the
+@sc{mi} protocol it wants @value{GDBN} to communicate with.
+
+@item
+For more information on handshaking see @ref{GDB/MI Handshaking Interface}
+@end itemize
+
 @node GDB/MI Input Syntax
 @subsection @sc{gdb/mi} Input Syntax
 
@@ -15111,6 +15154,9 @@
 @var{token}.
 
 @table @code
+@item @var{output-list} @expansion{}
+@code{@var{output} | @var{output-list} @var{output}}
+
 @item @var{output} @expansion{}
 @code{( @var{out-of-band-record} )* [ @var{result-record} ] "(@value{GDBP})" @var{nl}}
 
@@ -15314,6 +15360,51 @@
 an un-supported hybrid of @sc{gdb/mi} and CLI output.
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Handshaking Interface
+@section @sc{gdb/mi} Handshaking Interface
+
+@cindex @sc{gdb/mi}, handshaking interface
+@value{GDBN} is capable of speaking several MI protocols at a time.  This
+interface is intended to help developers understand what version of the MI
+protocol that a particular @value{GDBN} is going to communicate with.
+
+It is possible to start the @sc{gdb/mi} interpreter using @samp{-i=mi@var{n}}, 
+where @var{n} is the MI protocol version (@pxref{Interpreters}).  When invoked 
+with a specific version of the MI interpreter, @value{GDBN} will bypass the 
+handshaking mode and go directly into the version of the MI that it requested.  
+However, if @value{GDBN} is started with the -i=mi flag, then this tells 
+@value{GDBN} to go into its handshaking mode with the client to determine the 
+correct MI protocol to communicate with.
+
+@value{GDBN} will output all of the stable versions of the MI protocol that
+it supports.  The term @dfn{stable MI protocol} simply means that the protocol
+was tested when this particular release was made.  Protocols that are no longer
+tested in the @value{GDBN} testsuite will not be considered a stable release.  
+If the caller still wishes to communicate with @value{GDBN} using one of these
+untested protocols, they could simply try to invoke @value{GDBN} with 
+-i=mi@var{N}, where @var{N} is version they wish to communicate with.
+
+@value{GDBN} will output all of the stable MI versions that it supports.  
+If a specific version of @value{GDBN} speaks only one stable MI protocol then
+it will begin communicating with that version of the protocol.  The front end
+has no way to change this version.  However, if @value{GDBN} speaks several 
+versions of the MI protocol, then it will output a list of these protocols 
+and the front end then has to choose the version that it wants @value{GDBN}
+to communicate with.
+
+@cindex @dfn{stable MI protocol}
+You could have a @value{GDBN} version that is capable of communicating with
+several versions of the @sc{mi} protocol.  In general, an official release or
+a CVS snapshot will have depricated @sc{mi} protocols, stable @sc{mi} 
+protocols and development @sc{mi} protocols.  The depricated @sc{mi} protocols
+are kept around in @value{GDBN} for some period of time and then will 
+eventually get removed.  The @dfn{stable MI protocols} are considered stable
+because they were tested when the particular @value{GDBN} program you have was
+created.  The development @sc{mi} protocols are not ready to be used since
+there is a good change there will be incompatible changes made to it before it
+can become a stable protocol.
+
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Output Records
 @section @sc{gdb/mi} Output Records