From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 15063 invoked by alias); 12 Feb 2014 14:44:36 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 15051 invoked by uid 89); 12 Feb 2014 14:44:35 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.1 required=5.0 tests=AWL,BAYES_00,RP_MATCHES_RCVD,SPF_HELO_PASS,SPF_PASS autolearn=ham version=3.3.2 X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Wed, 12 Feb 2014 14:44:34 +0000 Received: from int-mx10.intmail.prod.int.phx2.redhat.com (int-mx10.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id s1CEiT2B003670 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 12 Feb 2014 09:44:30 -0500 Received: from [127.0.0.1] (ovpn01.gateway.prod.ext.ams2.redhat.com [10.39.146.11]) by int-mx10.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id s1CEiRkt005127; Wed, 12 Feb 2014 09:44:28 -0500 Message-ID: <52FB88CB.6000706@redhat.com> Date: Wed, 12 Feb 2014 14:44:00 -0000 From: Pedro Alves User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130625 Thunderbird/17.0.7 MIME-Version: 1.0 To: Joel Brobecker CC: Eli Zaretskii , gdb-patches@sourceware.org Subject: Re: [Windows/RFA/commit] Deprecate windows-specific dll-symbols command and aliases References: <1391161706-340-1-git-send-email-brobecker@adacore.com> <834n4k75iu.fsf@gnu.org> <20140131113924.GB4101@adacore.com> <83zjmc5q2i.fsf@gnu.org> <52F14B9D.3000802@redhat.com> <20140210143456.GC5485@adacore.com> In-Reply-To: <20140210143456.GC5485@adacore.com> Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-SW-Source: 2014-02/txt/msg00413.txt.bz2 On 02/10/2014 02:34 PM, Joel Brobecker wrote: > My 2 cents: I think it's fine to either remove the documentation, or > else leave it as is. Adding more info as you suggest is indeed making > the documentation better, but only for a short period of time. "short period of time" here doesn't seem all that correct to me. Sure, it's short if you track mainline. But a user using a release will be looking at the documentation of the gdb version she is using. In that perspective, the fact that mainline has already changed is not what dictates how long the user sees the documentation. The next upgrade cycle does. > During > that period of time, if people happen to read about the deprecated > command in the manual, and then actually use that function, they'll > immediately get a warning, the warning will tell them which command to > use in its place. On the other hand, if we excise the commands' > documentation and they are searching the users manual, the only > command they can find are the non-deprecated ones. > > In that respect, I now tend to agree with Eli. But it's not a strong > opinion. Alright, so AIUI, the argument for deleting seems to be that we should not advertise deprecated commands. IOW, we should avoid that people reading the manual end up using deprecated commands when a better alternative exists, and the deprecated command might well be removed soon. I completely agree that we should avoid that. What I don't agree is that deleting the documentation is the only way to do that. I believe that adding a note to the command's documentation in the manual saying the command is deprecated and pointing at the better alternative would do just as well. I'm of the opinion that as long as the command exists, it should be documented. Sure, by being deprecated, the user should no longer rely on its existence, but it might take a while for said user to actually upgrade to a gdb that actually removes the command (if we ever do), and there's no need IMO to make it more painful for the user to look up documentation for the command she is actually currently using right now to solve some hard to catch bug in her application. If we remove the documentation, then she has to do look for a manual of an older gdb. Note that old -> new command mapping might not be trivial, it might need adjustment of command parameters, and might well be that the new form is actually a sequence of commands, not a single command. (Note that I'm talking about policy here, not about any specific command.) So it seems like we have 3 possible policies: #1 - Leave the manual unchanged when we deprecate commands. Delete the documentation at the same time the command is actually deleted. #2 - Always excise documentation for deprecated commands at the same time we do the deprecation. #3 - Mark the commands deprecated in the manual at the same time we mark them deprecated in the code. Delete the documentation at the same time the command is actually deleted. In my view, #1 is just a bad policy. Having documentation for deprecated commands behind _without_ a "deprecated, use foo instead" note in them might lead users to find the old command and start using them while newer better alternatives exist. I think everyone will agree to that. And in my view, #3 is a superior policy than #2. But I'll accept #2, if that's what the group ends up preferring. Whatever we end up deciding, I think we should document the outcome as guideline somewhere in the internals manual, and if we go with #2, then we it'd be good to make a pass over the manual and remove all the existing documentation for currently deprecated commands. Thanks, -- Pedro Alves