From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 16365 invoked by alias); 7 Oct 2004 02:40:50 -0000 Mailing-List: contact gdb-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sources.redhat.com Received: (qmail 16356 invoked from network); 7 Oct 2004 02:40:48 -0000 Received: from unknown (HELO takamaka.act-europe.fr) (142.179.108.108) by sourceware.org with SMTP; 7 Oct 2004 02:40:48 -0000 Received: by takamaka.act-europe.fr (Postfix, from userid 507) id 099C447D98; Wed, 6 Oct 2004 19:40:48 -0700 (PDT) Date: Thu, 07 Oct 2004 04:48:00 -0000 From: Joel Brobecker To: Eli Zaretskii Cc: Andrew Cagney , gdb@sources.redhat.com Subject: Re: Discussion: Formalizing the deprecation process in GDB Message-ID: <20041007024047.GB1282@gnat.com> References: <20040927175539.GS974@gnat.com> <41637DBD.8030209@gnu.org> <01c4aba7$Blat.v2.2.2$141c3ea0@zahav.net.il> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <01c4aba7$Blat.v2.2.2$141c3ea0@zahav.net.il> User-Agent: Mutt/1.4i X-SW-Source: 2004-10/txt/msg00192.txt.bz2 > Unfortunately, it doesn't help in making a progress in this > discussion, since all it does is reiterate your opinions that were > clear (at least to me) during the XM_FILE debate, or else explaining > principles and generalities that don't need to be explained. The reason why I sent my message was that I felt that both parties had exposed their views and that both had their merits. So I felt that it was necessary to bring more people in the discussion and decide one way or the other. I suggested that the discussion group be the global maintainers for instance. > I'm not sure what is it that you are saying here. Should we abandon > gdbint.texinfo and instead rely on the code to explain itself, because > ``we are programmers and thus code is the only thing we read''? Maybe > I should stop trying so hard to review each documentation patch in a > matter of days, because the code already says all there is to tell? Just my two cents on this specific topic: I do agree with Andrew that the place were developers search for documentation is the code. I would love to see a lot of the documentation contained in gdbint.texinfo be moved as comments into the code. Having the documentation embedded inside the code is very convenient, and also where I have been trained to look first. This does not mean that I am suggesting that we get rid of gdbint entirely. I see chapters and sections that can only be placed in a separate documentation, such as how to add support for a new host for instance. But the documentation about partial symbol tables, for instance, would be much more useful directly in symtab.h or symtab.c. I don't know about others, but I have read the gdbint manual once from cover to cover almost 4 years ago, and never refered to it anymore. -- Joel