From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 15871 invoked by alias); 13 Feb 2014 12:01:04 -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 15860 invoked by uid 89); 13 Feb 2014 12:01:04 -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; Thu, 13 Feb 2014 12:01:03 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id 0051511653C; Thu, 13 Feb 2014 07:01:01 -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 x8tZfLoAHQcd; Thu, 13 Feb 2014 07:01:01 -0500 (EST) Received: from joel.gnat.com (localhost.localdomain [127.0.0.1]) by rock.gnat.com (Postfix) with ESMTP id 8A99A116537; Thu, 13 Feb 2014 07:01:01 -0500 (EST) Received: by joel.gnat.com (Postfix, from userid 1000) id 6BA64E0DAA; Thu, 13 Feb 2014 16:01:03 +0400 (RET) Date: Thu, 13 Feb 2014 12:01: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: <20140213120103.GZ5485@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> <20140212171738.GR5485@adacore.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20140212171738.GR5485@adacore.com> User-Agent: Mutt/1.5.21 (2010-09-15) X-SW-Source: 2014-02/txt/msg00461.txt.bz2 Hi Eli, Since you are the official Maintainer of the GDB documentation, would you mind telling us what you think? I'd like us to make a decision, so that I can redo the documentation that goes with the patch. Thank you! > > 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 -- Joel