Re: CLI and GDB/MI documentation patch

Re: CLI and GDB/MI documentation patch

[Nick Roberts]

> I'd agree with Eli that the proposed text sounds a bit like history, but it
> documents some important points:

I'm not sure I like it because:

> - That you can type CLI commands into MI, and this is not longer considered
>   to work just by accident

It was never just by accident, just more of a hack.

> - That typing CLI command has the same effect as -interpreter-exec console

Its not quite the same, the latter goes through mi_cmd_execute but the
former doesn't.

> - That CLI command don't produce async notifications

They don't *currently* produce async notifications but I'm trying to change
that with my branch.

> Those points are important to have documented, IMO.

Putting these things in the manual just makes it harder to change GDB.
I would rather say: "Its there.  Use it at your own risk".  Or at least:


  For the developers convenience CLI commands can be entered directly.
  However this feature may be removed at some stage in the future and
  it is recommended that front ends use the @code{-interpreter exec} command.
  @xref{GDB/MI Miscellaneous Commands}.




-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Sun, 14 May 2006 00:43:41 +1200
> Cc: gdb-patches@sources.redhat.com
> 
> > - That typing CLI command has the same effect as -interpreter-exec console
> 
> Its not quite the same, the latter goes through mi_cmd_execute but the
> former doesn't.

Bob described the minor differences:

            There may be a small difference in the @sc{gdb/mi} output between 
  directly typing the CLI command into the @sc{gdb/mi} interpreter or by using 
  the @code{-interpreter-exec} command, however, both ways should provide 
  valid @sc{gdb/mi} output.

(``small differences in output'' is too vague; I'd like a more precise
and clear description of the differences.)

And later:

  One current major difference between entering a CLI command directly into
  the @sc{gdb/mi} interpreter and entering the corresponding @sc{gdb/mi} 
  command into the interpreter is that the CLI command will not have the 
  asynchronous output that the @sc{gdb/mi} command will have. For instance,
  typing @code{run} as a CLI command, you will not get the @code{*stopped}
  response that @sc{gdb/mi} will provide if you enter the @code{-exec-run}
  command.

Are there any other differences?  If so, let's describe them.

> > Those points are important to have documented, IMO.
> 
> Putting these things in the manual just makes it harder to change GDB.
> I would rather say: "Its there.  Use it at your own risk".  Or at least:
> 
> 
>   For the developers convenience CLI commands can be entered directly.
>   However this feature may be removed at some stage in the future and
>   it is recommended that front ends use the @code{-interpreter exec} command.
>   @xref{GDB/MI Miscellaneous Commands}.

Do we indeed intend to remove this feature any time soon?  If so, I
agree that we should add a warning about that.  But, other than that,
why do you say that describing the CLI support in mi in more detail
will make it harder to change GDB?

Re: CLI and GDB/MI documentation patch

[Bob Rossi]

On Fri, May 12, 2006 at 05:05:51PM +0300, Eli Zaretskii wrote:
> > From: Nick Roberts <nickrob@snap.net.nz>
> > Date: Sun, 14 May 2006 00:43:41 +1200
> > Cc: gdb-patches@sources.redhat.com
> > 
> > > - That typing CLI command has the same effect as -interpreter-exec console
> > 
> > Its not quite the same, the latter goes through mi_cmd_execute but the
> > former doesn't.
> 
> Bob described the minor differences:
> 
>             There may be a small difference in the @sc{gdb/mi} output between 
>   directly typing the CLI command into the @sc{gdb/mi} interpreter or by using 
>   the @code{-interpreter-exec} command, however, both ways should provide 
>   valid @sc{gdb/mi} output.
> 
> (``small differences in output'' is too vague; I'd like a more precise
> and clear description of the differences.)
> 
> And later:
> 
>   One current major difference between entering a CLI command directly into
>   the @sc{gdb/mi} interpreter and entering the corresponding @sc{gdb/mi} 
>   command into the interpreter is that the CLI command will not have the 
>   asynchronous output that the @sc{gdb/mi} command will have. For instance,
>   typing @code{run} as a CLI command, you will not get the @code{*stopped}
>   response that @sc{gdb/mi} will provide if you enter the @code{-exec-run}
>   command.
> 
> Are there any other differences?  If so, let's describe them.
> 
> > > Those points are important to have documented, IMO.
> > 
> > Putting these things in the manual just makes it harder to change GDB.
> > I would rather say: "Its there.  Use it at your own risk".  Or at least:
> > 
> > 
> >   For the developers convenience CLI commands can be entered directly.
> >   However this feature may be removed at some stage in the future and
> >   it is recommended that front ends use the @code{-interpreter exec} command.
> >   @xref{GDB/MI Miscellaneous Commands}.
> 
> Do we indeed intend to remove this feature any time soon?  If so, I
> agree that we should add a warning about that.  But, other than that,
> why do you say that describing the CLI support in mi in more detail
> will make it harder to change GDB?

IMO, we don't intend to remove it soon. I attempted to remove it with 
this statement:
  I'm thinking it would be a good idea to remove the ability to enter
  CLI commands into the MI interpreter. Does anyone disagree?

and this was the response from Nick:
  No one is forcing you to use it.  Why would you want to force others
  not to use it?
from Daniel
  No way.  The fact is, the MI command set is not complete, and
  -interpreter-exec is still recent.  I would expect most front ends
  to still require this support, for the indefinite future.

So, with that in mind, I'm assuming it won't be dropped for a very long
time.

Bob Rossi

Re: CLI and GDB/MI documentation patch

[Nick Roberts]

 > > Putting these things in the manual just makes it harder to change GDB.
 > > I would rather say: "Its there.  Use it at your own risk".  Or at least:
 > > 
 > > 
 > >   For the developers convenience CLI commands can be entered directly.
 > >   However this feature may be removed at some stage in the future and
 > >   it is recommended that front ends use the @code{-interpreter exec} command.
 > >   @xref{GDB/MI Miscellaneous Commands}.
 > 
 > Do we indeed intend to remove this feature any time soon?  If so, I
 > agree that we should add a warning about that.  

I don't know about any time soon buts it's clearly irregular and I guess
could interfere with the design of MI.  Also it doesn't have to stay as
-interpreter exec provides an alternative.
 >                                                But, other than that,
 > why do you say that describing the CLI support in mi in more detail
 > will make it harder to change GDB?

Because if people write a front end that relies on a feature then understanably
they are upset when it is changed or removed, just as I was when it appeared
that annotations would be removed.   The one advantage of Emacs long
release cycle is that it gives you more time to get everything right before
its released.  GDB goes out about every six months along with an expectation
that its behaviour will some level of maintenance.



-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: CLI and GDB/MI documentation patch

[Bob Rossi]

On Sat, May 13, 2006 at 09:52:47AM +1200, Nick Roberts wrote:
>  > > Putting these things in the manual just makes it harder to change GDB.
>  > > I would rather say: "Its there.  Use it at your own risk".  Or at least:
>  > > 
>  > > 
>  > >   For the developers convenience CLI commands can be entered directly.
>  > >   However this feature may be removed at some stage in the future and
>  > >   it is recommended that front ends use the @code{-interpreter exec} command.
>  > >   @xref{GDB/MI Miscellaneous Commands}.
>  > 
>  > Do we indeed intend to remove this feature any time soon?  If so, I
>  > agree that we should add a warning about that.  
> 
> I don't know about any time soon buts it's clearly irregular and I guess
> could interfere with the design of MI.  Also it doesn't have to stay as
> -interpreter exec provides an alternative.
>  >                                                But, other than that,
>  > why do you say that describing the CLI support in mi in more detail
>  > will make it harder to change GDB?
> 
> Because if people write a front end that relies on a feature then understanably
> they are upset when it is changed or removed, just as I was when it appeared
> that annotations would be removed.   The one advantage of Emacs long
> release cycle is that it gives you more time to get everything right before
> its released.  GDB goes out about every six months along with an expectation
> that its behaviour will some level of maintenance.

I agree with you completly. What if we released mi3 with the
next release of GDB. We could remove the direct CLI commands then. I
think there would be some advantages to releasing mi3 anyways.

The good news for FE developers, is that a very quick fix on there side
should allow them to be working again.

Bob Rossi

Re: CLI and GDB/MI documentation patch

[Nick Roberts]

 > > Because if people write a front end that relies on a feature then
 > > understanably they are upset when it is changed or removed, just as I was
 > > when it appeared that annotations would be removed.  The one advantage of
 > > Emacs long release cycle is that it gives you more time to get everything
 > > right before its released.  GDB goes out about every six months along
 > > with an expectation that its behaviour will some level of maintenance.
 > 
 > I agree with you completly. What if we released mi3 with the
 > next release of GDB. We could remove the direct CLI commands then. I
 > think there would be some advantages to releasing mi3 anyways.

AFAICS the only changes to MI since 6.4 have been to add the fullname field
to breakpoint related commands and to generate an error record for directly
entered CLI commands.  I think we only need to bump the number when an
incompatible change change is made that will break existing front ends.

I also think it will prove too difficult to maintain functionality for old
levels in general (mi0 or mi1 might be an exception) but clearly new front
ends will be able to work with more than one level if they want (old ones will
break with the new level).  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.


-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: CLI and GDB/MI documentation patch

[Daniel Jacobowitz]

On Sun, May 14, 2006 at 09:06:56PM +1200, Nick Roberts wrote:
> AFAICS the only changes to MI since 6.4 have been to add the fullname field
> to breakpoint related commands and to generate an error record for directly
> entered CLI commands.  I think we only need to bump the number when an
> incompatible change change is made that will break existing front ends.

Right.  I have at least one such change in mind - I posted about the
mess of quoting and backslash processing on gdb@ some time ago though I
have no idea when I'll have time to get back to it.  The asynchronous
changes you've been working with may also require an MI level bump.

> break with the new level).  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 :-)

-- 
Daniel Jacobowitz
CodeSourcery

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

[Nick Roberts]

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

-- 
Nick                                           http://www.inet.net.nz/~nickrob


*** 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.
+ 
+ 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:
+ 
+ @itemize @bullet
+ @item
+ New MI commands may be added.
+ 
+ @item
+ New fields may be added to the output of any MI command.
+ 
+ @c The format of field's content e.g type prefix, may change so parse it
+ @c   at your own risk.  Yes, in general?
+ 
+ @c The order of fields may change?  Shouldn't really matter but it might
+ @c resolve inconsistencies.
+ @end itemize
+ 
+ If the changes are such that is considered likely that they would
+ necessarily break a front end, 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 GDB will not
+ support old versions of MI and it will be the responsibility of the
+ front end to work with the new one.  
+ 
+ @c Starting with mi3, add a new command -mi-version that prints the MI
+ @c version?
+ 
+ The best way to ensure that unexpected changes which break your front
+ end are not made is to make your project known to GDB developers and
+ follow development on @email{gdb@@sources.redhat.com} and
+ @email{gdb-patches@@sources.redhat.com}.  There is also the mailing list
+ @email{dmi-discuss@@lists.freestandards.org}, hosted by the Free Standards
+ Group, which has the aim of creating a a more general MI protocol
+ called Debugger Machine Interface (DMI) that will become a standard
+ for all debuggers, not just GDB.
+ 
+ @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  @node GDB/MI Output Records
  @section @sc{gdb/mi} Output Records
  

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

[Eli Zaretskii]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Tue, 30 May 2006 19:16:43 +1200
> Cc: gdb-patches@sources.redhat.com
> 
> 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.

Thanks.  I have a few comments and suggestions:

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

Please add a @cindex entry here.  The text can be the name of the
section, or some permutation thereof.

> + section tries to minimise the problems by describing how the protocol

"minimize", please.  We use the US spelling.

> + If the changes are such that is considered likely that they would
> + necessarily break a front end

I think the following is simpler and more clear:

  If changes are accumulated that are likely to break front ends, ...

> + to the MI version.  Apart from mi0, new versions of GDB will not

Please use "@value{GDBN}" instead of a literal "GDB".

> + The best way to ensure that unexpected changes which break your front
> + end are not made is

  The best way to avoid changes in MI that might unexpectedly break
  your front end is ...

>                 is to make your project known to GDB developers and
> + follow development on @email{gdb@@sources.redhat.com} and
> + @email{gdb-patches@@sources.redhat.com}.  There is also the mailing list
> + @email{dmi-discuss@@lists.freestandards.org}, hosted by the Free Standards
> + Group, which has the aim of creating a a more general MI protocol
> + called Debugger Machine Interface (DMI) that will become a standard
> + for all debuggers, not just GDB.

I suggest an index entry here, something like

  @cindex @sc{gdb/mi} development, mailing lists

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

[Nick Roberts]

 > Thanks.  I have a few comments and suggestions:
 > 
 > > + @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}.
 > 
 > Please add a @cindex entry here.  The text can be the name of the
 > section, or some permutation thereof.

OK

 > > + section tries to minimise the problems by describing how the protocol
 > 
 > "minimize", please.  We use the US spelling.

OK

 > > + If the changes are such that is considered likely that they would
 > > + necessarily break a front end

OK

 > I think the following is simpler and more clear:
 > 
 >   If changes are accumulated that are likely to break front ends, ...
 > 
 > > + to the MI version.  Apart from mi0, new versions of GDB will not

OK

 > Please use "@value{GDBN}" instead of a literal "GDB".

OK

 > > + The best way to ensure that unexpected changes which break your front
 > > + end are not made is
 > 
 >   The best way to avoid changes in MI that might unexpectedly break
 >   your front end is ...

I made a similar change.

 > >                 is to make your project known to GDB developers and
 > > + follow development on @email{gdb@@sources.redhat.com} and
 > > + @email{gdb-patches@@sources.redhat.com}.  There is also the mailing list
 > > + @email{dmi-discuss@@lists.freestandards.org}, hosted by the Free Standards
 > > + Group, which has the aim of creating a a more general MI protocol
 > > + called Debugger Machine Interface (DMI) that will become a standard
 > > + for all debuggers, not just GDB.
 > 
 > I suggest an index entry here, something like
 > 
 >   @cindex @sc{gdb/mi} development, mailing lists

I added "@cindex @sc{gdb/mi} development" at the start of the node, so I just
added "@cindex mailing lists" here.

Thanks for the prompt review.

-- 
Nick                                           http://www.inet.net.nz/~nickrob


2006-05-31  Nick Roberts  <nickrob@snap.net.nz>

	* gdb.texinfo (GDB/MI Development and Front Ends): New Node.


*** gdb.texinfo	31 May 2006 13:03:22 +1200	1.332
--- gdb.texinfo	31 May 2006 13:14:09 +1200	
*************** This chapter is a specification of the @
*** 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
  
*************** Elena Zannoni.
*** 17254,17259 ****
--- 17255,17261 ----
  @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::
*************** behaviour, the exact output of such comm
*** 17571,17576 ****
--- 17573,17630 ----
  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
+ @cindex @sc{gdb/mi} development
+ 
+ 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 minimize the problems by describing how the protocol
+ might change.
+ 
+ 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:
+ 
+ @itemize @bullet
+ @item
+ New MI commands may be added.
+ 
+ @item
+ New fields may be added to the output of any MI command.
+ 
+ @c The format of field's content e.g type prefix, may change so parse it
+ @c   at your own risk.  Yes, in general?
+ 
+ @c The order of fields may change?  Shouldn't really matter but it might
+ @c resolve inconsistencies.
+ @end itemize
+ 
+ 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.
+ 
+ @c Starting with mi3, add a new command -mi-version that prints the MI
+ @c version?
+ 
+ The best way to avoid unexpected changes in MI that might break your front
+ end is to make your project known to GDB developers and
+ follow development on @email{gdb@@sources.redhat.com} and
+ @email{gdb-patches@@sources.redhat.com}.  There is also the mailing list
+ @email{dmi-discuss@@lists.freestandards.org}, hosted by the Free Standards
+ Group, which has the aim of creating a a more general MI protocol
+ called Debugger Machine Interface (DMI) that will become a standard
+ for all debuggers, not just GDB.
+ @cindex mailing lists
+ 
+ @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  @node GDB/MI Output Records
  @section @sc{gdb/mi} Output Records
  

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

[Eli Zaretskii]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Wed, 31 May 2006 13:19:43 +1200
> Cc: gdb-patches@sources.redhat.com
> 
>  > Please use "@value{GDBN}" instead of a literal "GDB".
> 
> OK

I didn't mean just there, I meant everywhere.  There are a couple more
literal "GDB"s.

Other than that, this patch is fine with me.

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

[Nick Roberts]

 > >  > Please use "@value{GDBN}" instead of a literal "GDB".
 > > 
 > > OK
 > 
 > I didn't mean just there, I meant everywhere.  There are a couple more
 > literal "GDB"s.
 > 
 > Other than that, this patch is fine with me.

Duh!  OK, I've committed this just to mainline.  I think maybe things should
be worked out a bit more before it's included in a release.

-- 
Nick                                           http://www.inet.net.nz/~nickrob

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

[Daniel Jacobowitz]

On Wed, May 31, 2006 at 01:19:43PM +1200, Nick Roberts wrote:
> + follow development on @email{gdb@@sources.redhat.com} and
> + @email{gdb-patches@@sources.redhat.com}.  There is also the mailing list

Please use the sourceware.org name, instead.

This patch looks fine to me too, but for avoidance of doubt: Eli, did
you intend to approve the patch's content, or just its markup? I often
can't tell in your responses.

-- 
Daniel Jacobowitz
CodeSourcery

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

[Eli Zaretskii]

> Date: Wed, 31 May 2006 18:11:46 -0400
> From: Daniel Jacobowitz <drow@false.org>
> Cc: Eli Zaretskii <eliz@gnu.org>, gdb-patches@sources.redhat.com
> 
> Eli, did you intend to approve the patch's content, or just its
> markup? I often can't tell in your responses.

I'm not sure I understand the question; feel free to elaborate if
what's below doesn't answer it.

The short answer is that if I approve a patch, that means I approve it
in its entirety.  That's what everyone else does, right?

The long answer is that I definitely look into aspects such as markup
and the documentation quality (indexing, clear language, etc.) when
reviewing a patch, and the approval includes them.  As for contents,
if I feel I don't understand the underlying issues well enough, I
usually say that in some way.  In this case, the issue was pretty much
clear to me and the text described it correctly, AFAICS.  (The email
address change that you requested is definitely not a codified
practice I knew about, although I don't mind the address either way.)

In any case, even if I happen to approve a doco change whose text is
nice and clear, but wrong as far as the facts go, I expect those in
the know to holler about the wrong parts, and then the author of the
patch or myself will fix them.  I cannot pretend I know everything, or
even that I know everything about what I don't know ;-)

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

[Daniel Jacobowitz]

On Thu, Jun 01, 2006 at 10:24:02AM +0300, Eli Zaretskii wrote:
> I'm not sure I understand the question; feel free to elaborate if
> what's below doesn't answer it.

Nope, you answered me perfectly.  Thanks a lot, as usual!

-- 
Daniel Jacobowitz
CodeSourcery

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

[Bob Rossi]

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

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

[Nick Roberts]

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

I don't know, something without innuendo.  Referring to "your front end"
(or "my back end") just tempts ridicule.

-- 
Nick                                           http://www.inet.net.nz/~nickrob