Re: [PATCH] doc: Add table of MI versions

[Eli Zaretskii <eliz at gnu dot org>]

> From: Simon Marchi <simon.marchi@ericsson.com>
> CC: Simon Marchi <simon.marchi@ericsson.com>
> Date: Mon, 14 Jan 2019 20:39:16 +0000
> 
> This patch adds a table summarizing the history or MI versions:
> 
> - The version number
> - Which GDB version introduced it
> - Breaking changes compared to the previous version

Thanks.

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

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

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

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

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

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