From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 20936 invoked by alias); 25 Jun 2007 19:10:43 -0000 Received: (qmail 20924 invoked by uid 22791); 25 Jun 2007 19:10:41 -0000 X-Spam-Check-By: sourceware.org Received: from mail.codesourcery.com (HELO mail.codesourcery.com) (65.74.133.4) by sourceware.org (qpsmtpd/0.31) with ESMTP; Mon, 25 Jun 2007 19:10:39 +0000 Received: (qmail 30466 invoked from network); 25 Jun 2007 19:10:37 -0000 Received: from unknown (HELO localhost) (jimb@127.0.0.2) by mail.codesourcery.com with ESMTPA; 25 Jun 2007 19:10:37 -0000 To: Michael Eager Cc: Stan Shebs , gdb@sources.redhat.com Subject: Re: What's an annex? stratum? References: <467D5FEF.7010900@eagercon.com> <467D6D1F.7090507@earthlink.net> <467D6FB8.4080909@eagercon.com> <468009EA.4040504@eagercon.com> From: Jim Blandy Date: Mon, 25 Jun 2007 19:10:00 -0000 In-Reply-To: <468009EA.4040504@eagercon.com> (Michael Eager's message of "Mon, 25 Jun 2007 11:31:06 -0700") Message-ID: User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-IsSubscribed: yes Mailing-List: contact gdb-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sourceware.org X-SW-Source: 2007-06/txt/msg00254.txt.bz2 Michael Eager writes: >> For what it's worth --- we don't invest enough time in >> doc/gdbint.texinfo to keep it a clear, accurate reference to the >> code. (For me, at least, this is a deliberate decision.) It's more a >> collection of the clearer explanations that have appeared on the >> mailing list over time. > > Unfortunately, much of it is obsolete. Some sections, like 9.6, > make this explicit. Other sections say that the area is in flux, > like section 9.7. Other sections don't tell you that they are > out of date (like the section about libgdb?). > > Some important parts are simply missing, like the sections titled > Console Printing, TUI, Frame Interpretation, Inferior Call Setup, and > others. > > I don't mean to harp on the documentation, but often the "clearer > explanations" amount to commentary about how the old technique didn't > work well and the new technique is better. That may be true, but it > doesn't reveal much about how to use the technique. > > If I get to the point where I think I really understand an area, > I'll be happy to contribute to documentation improvements. I'm > not there at the moment. Well, let me try again to say what I meant: if you're new to GDB, you should not start by reading gdbint.texinfo. Instead, start by reading and grepping, and then experiment by debugging GDB with itself. If you ask a question, people may occasionally refer you to gdbint.texinfo. But it's not useful as a getting started guide for GDB hackers, and I think the effort required to make it so is far more than any of us have available. I'm even a little skeptical about the value of internals documentation at all. It seems to me that explanations like that belong in the code, where people are more likely to see them, keep them up to date, and delete them when appropriate.