Re: [PATCH] Fix MI output for multi-location breakpoints

Simon Marchi
2019-01-13T16:17:40Z

> Doing this for every single feature is indeed overkill. But changes
> in the version of MI are rare and backward-incompatible, so they are a
> different story, IMO.

Just adding a new MI version is not a backward-incompatible change.
Adding MI3 does not change anything for you if you use MI2. What is
backward-incompatible may be which version of MI is selected if you use
"--interpreter=mi" (without an explicit version). Is it what we are
trying to document here, which version of the interpreter you end up
with if you use "--interpreter=mi"? Or we are trying to document the
possible arguments to pass to "--interpreter"?

For the former, wouldn't it be clear to say that you end up with the
latest stable release of the MI interpreter (and cross-reference to the
table)?

For the latter, a cross-reference to the table gives would point you to
the relevant info, without overloading this section as the number of MI
releases grow.

>> > I'm okay with adding a detailed table elsewhere, but I don't think
>> > it's a good idea to remove the above information from the description
>> > of the -mi command-line switch.
>>
>> Would a cross-reference to the table be good enough?
>
> Not in this particular case, no.

Can you expand on why? I really don't expect that many users to come to
the manual often to know about MI versions. Only a handful of people
care about that (people who implement frontends), and they will surely
dig much more in the manual (especially the GDB/MI section) to achieve
what they want to do.

>> If we add a detailed table
>> of MI versions (which I think is required), we will have the
>> information about which
>> GDB version introduced each MI versions at three separate places in
>> the manual...
>
> Which is the third place? I thought we have it only in two places.
> The detailed table could come instead of that second place we have
> now, not in addition to it. But let's wait with that decision until
> we actually see the proposed change for that table.

1. In "@node Mode Options"
2. In "@node Interpreters"
3. In the hypothetical table of MI versions.

>> - mi1 can be used by any GDB version between 5.1 and the present. Why
>> do we list
>> specifically 5.1, 5.2 and 5.3?
>
> So that readers who have those versions installed knew they can only
> use mi1.
>> - The term "included in", or "used by", regardless of whether it is
>> coupled with "5.1"
>> or 5.1, 5.2 and 5.3". Since mi1 can be used with any version
>> between 5.1 and the
>> latest release, I think we should be looking for a phrasing that
>> conveys that it's
>> an half-open interval. Saying that "mi1 is used by GDB 5.1" just
>> tells you about
>> 5.1. Saying that "mi1 is available starting with GDB 5.1" tells you
>> about all
>> versions between 5.1 and the current one.
>
> The purpose of that text is to say that those versions can only use
> mi1.

Well, IMO it's clear from the fact that mi2, documented just above, is
said to have been introduced by version 6.0 (and that 5.3 < 6.0).

But anyhow, I can live with the "used by" formulation if you and Tom
think it's clear enough. For MI2, however, we won't list all versions,
since there are too many. Could we switch them both to ranges for
consistency?

- mi3: The gdb/mi interface used by GDB versions 9.1 and later. This is
the latest gdb/mi version.
- mi2: The gdb/mi interface used by GDB versions 6.0 to 8.3
(inclusively).
- mi1: The gdb/mi interface used by GDB versions 5.1 to 5.3
(inclusively).

Thanks,

Simon