Re: CLI and GDB/MI documentation patch

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Fri, 12 May 2006 15:01:52 -0400
> From: Daniel Jacobowitz <drow@false.org>
> 
> New tools, written today, are probably written against a fairly
> current manual.  Then someone approaches you and says "I'd like to
> use your nice IDE on our stable enterprise platform from three years
> ago which has an older GDB".

I don't see any practical solution for such a situation.  To cater to
it, we'd need to convert the MI and Remote Protocol parts of the
manual into a kind of a very detailed ChangeLog, where every change
gets documented (together with its precise date, since ``there are so
many snapshots in use out there'', as Bob says), but the description
of the previous behavior is never removed, for those unfortunate souls
that will need to interface to it as you describe.  Just saying
``previous versions of GDB behaved like this'' will not solve the
problem, since there's no information about when the change(s) became
effective.

> The range of supported GDBs does not only grow forwards.

In my experience, the only way to extend it backwards is to read the
sources and experiment.  That's because, as users come up with
suggestions and requests to expand and extend the manual, we only do
that for the current version; the old behavior stays undocumented.
It's impractical to ask us to document the past behavior, for every
new piece of documentation we add to the manual.

If you see any practical solution for this kind of situations, please
tell what can we reasonably do in the manual.

> > If you feel we should tell how to create a front end and/or a stub
> > that supports several versions of GDB/MI or remote protocol, that's
> > fine by me, but let's have sections whose focus is to provide tips to
> > such programmers, not to tell the history of MI or the protocol's
> > evolution.  That's quite a different attitude than what Bob wrote.
> 
> I do think that such a section would be useful.  I'm not entirely sure
> about the distinction you are drawing, though.  Is it a "what" versus
> "why" difference?

No.  When you write a Tips section, you in essence write a cookbook,
and the logic of the text (i.e. what you tell, how, and in which
order) is in accordance with that.  That is, you pick up an issue and
give tips relevant to that issue, and while at that, you also say
things like ``Note that versions of GDB older than X.YZ didn't support
the -mi-frobnicate command, so you will have to use -mi-hack as a
workaround with those versions, which has this-and-that
disadvantage.''  Then you pick up another issue, etc.

By contrast, the logic of text posted by Bob was chronological: ``In
the beginning, we did this; later we started to do that; so now you
could solve this with such-and-such methods.''  Do you see the
difference?