From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 9058 invoked by alias); 12 Feb 2014 17:17:40 -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 9047 invoked by uid 89); 12 Feb 2014 17:17:40 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.5 required=5.0 tests=AWL,BAYES_00 autolearn=ham version=3.3.2 X-HELO: rock.gnat.com Received: from rock.gnat.com (HELO rock.gnat.com) (205.232.38.15) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-SHA encrypted) ESMTPS; Wed, 12 Feb 2014 17:17:39 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id 937BD1165D7; Wed, 12 Feb 2014 12:17:37 -0500 (EST) Received: from rock.gnat.com ([127.0.0.1]) by localhost (rock.gnat.com [127.0.0.1]) (amavisd-new, port 10024) with LMTP id 9xwVs6eZs86C; Wed, 12 Feb 2014 12:17:37 -0500 (EST) Received: from joel.gnat.com (localhost.localdomain [127.0.0.1]) by rock.gnat.com (Postfix) with ESMTP id 2D5A711659F; Wed, 12 Feb 2014 12:17:37 -0500 (EST) Received: by joel.gnat.com (Postfix, from userid 1000) id 594C9E0784; Wed, 12 Feb 2014 21:17:38 +0400 (RET) Date: Wed, 12 Feb 2014 17:17:00 -0000 From: Joel Brobecker To: Pedro Alves Cc: Eli Zaretskii , gdb-patches@sourceware.org Subject: Re: [Windows/RFA/commit] Deprecate windows-specific dll-symbols command and aliases Message-ID: <20140212171738.GR5485@adacore.com> 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> <52FB88CB.6000706@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <52FB88CB.6000706@redhat.com> User-Agent: Mutt/1.5.21 (2010-09-15) X-SW-Source: 2014-02/txt/msg00424.txt.bz2 Hi Pedro, > 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. I understand your reasoning, and can agree with you in the sense that someone already using the deprecated command might want to look some detail up in the GDB manual and not find it. But I do not have a strong opininon on this, and whatever we end up deciding is fine by me. Let's just decide now :). I will go with #3, or else #2. -- Joel