From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 8053 invoked by alias); 13 May 2006 09:21:40 -0000 Received: (qmail 8043 invoked by uid 22791); 13 May 2006 09:21:39 -0000 X-Spam-Check-By: sourceware.org Received: from romy.inter.net.il (HELO romy.inter.net.il) (192.114.186.66) by sourceware.org (qpsmtpd/0.31) with ESMTP; Sat, 13 May 2006 09:21:36 +0000 Received: from HOME-C4E4A596F7 (IGLD-83-130-243-9.inter.net.il [83.130.243.9]) by romy.inter.net.il (MOS 3.7.3-GA) with ESMTP id EED98586 (AUTH halo1); Sat, 13 May 2006 12:21:32 +0300 (IDT) Date: Sat, 13 May 2006 09:28:00 -0000 Message-Id: From: Eli Zaretskii To: gdb-patches@sourceware.org In-reply-to: <20060512190152.GA15416@nevyn.them.org> (message from Daniel Jacobowitz on Fri, 12 May 2006 15:01:52 -0400) Subject: Re: CLI and GDB/MI documentation patch Reply-to: Eli Zaretskii References: <20060512011730.GA26655@brasko.net> <20060512124940.GB3860@nevyn.them.org> <20060512135802.GA6472@nevyn.them.org> <20060512183723.GA14434@nevyn.them.org> <20060512190152.GA15416@nevyn.them.org> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2006-05/txt/msg00282.txt.bz2 > Date: Fri, 12 May 2006 15:01:52 -0400 > From: Daniel Jacobowitz > > 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?