[PATCH] doc: Add table of MI versions

[Simon Marchi]

>> -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 minimize the problems by describing how the protocol
>> -might change.
>> +The MI interface is versioned, allowing it to evolve while avoiding 
>> breaking
>> +existing front ends.
> 
> Some of the rationale you removed sounds like something good to have.
> Explaining the rationale for a section is in general a Good Thing,
> IMO.

The "is still incomplete" sentence sounds useless to me, and can even 
make people wonder if they should really use it, since it's incomplete.  
It will always evolve, it will never be "complete".  I could add back 
the last sentence with a bit more stuff, like so:

The MI interface is versioned, allowing it to evolve while avoiding 
breaking existing front ends.  This section describes how the protocol 
might change within a version and the breaking changes across versions.

>>  If the changes are likely to break front ends, the MI version level
>> -will be increased by one.  This will allow the front end to parse the
>> -output according to the MI version.  Apart from mi0, new versions of
>> -@value{GDBN} will not support old versions of MI and it will be the
>> -responsibility of the front end to work with the new one.
>> +will be increased by one.  Previous versions of MI remain available, 
>> allowing
>> +front ends to keep using them until they are modified to use the 
>> latest MI
>> +version.
> 
> Likewise here: the old text explained that miN version will generally
> be incompatible with miN-1 version.  Your change removes that
> important statement.  I'd prefer not to lose that part.

Which part of the original text says that?  The first sentence, which I 
have not removed, is pretty clear about that.

And the statement "Apart from mi0, new versions of GDB will not support 
old versions of MI" sounds completely wrong.  New versions of GDB don't 
support mi0 (presumably the first version of MI to have existed), but do 
support mi1.  What I want to say is that even if a new version of MI is 
released, the previous versions of MI stay available for some time, 
allowing front ends to do the transition.

>> -@c Starting with mi3, add a new command -mi-version that prints the 
>> MI
>> -@c version?
> 
> Why did you remove the comment?  It seems like a valid idea, perhaps
> worth implementing.

I don't think this is the right place for such things (it's quite 
hidden).  If we really want to keep track of this, let's open an issue 
on Bugzilla for it.

About the idea itself, I don't think we need to implement this.  If 
front ends request a specific version of MI (which is good practice, in 
my experience), they won't need to query it.

>> +Since @code{--interpreter=mi} always points to the latest MI version, 
>> it is
>> +recommended that front ends request a specific version of MI when 
>> launching
>> +@value{GDBN} (e.g. @code{--interpreter=mi2}) to make sure to get an 
>> interpreter
> 
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> "to make sure they get and interpreter ..."

Fixed.

>> +The @code{-environment-pwd}, @code{-environment-directory} and
>> +@code{-environment-path} commands now returns values using the MI 
>> output
>> +syntax, rather than CLI output.
>                        ^^^^^^^^^^
> "CLI output syntax", I presume.

Not sure there is really a syntax for CLI output like there is a syntax 
for MI output, but I made the change anyway.

>> +@item
>> +@code{-var-list-children}'s @code{children} result field is a now 
>> list, rather
>                                                             ^^^^^^^^
> A typo.

Fixed.

Thanks,

Simon